Implement checkbox confirmation contract

Co-Authored-By: Paperclip <noreply@paperclip.ing>

server/src/__tests__/issue-thread-interaction-routes.test.ts

@@ -542,6 +542,74 @@ describe.sequential("issue thread interaction routes", () => {
     );
   });
 
+  it("accepts request checkbox confirmations with selected option ids and wakes the assignee", async () => {
+    mockInteractionService.acceptInteraction.mockResolvedValueOnce({
+      interaction: {
+        id: "interaction-checkbox",
+        companyId: "company-1",
+        issueId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+        kind: "request_checkbox_confirmation",
+        status: "accepted",
+        continuationPolicy: "wake_assignee",
+        idempotencyKey: null,
+        sourceCommentId: null,
+        sourceRunId: "run-checkbox",
+        payload: {
+          version: 1,
+          prompt: "Delete selected files?",
+          options: [
+            { id: "file-a", label: "a.txt" },
+            { id: "file-b", label: "b.txt" },
+          ],
+        },
+        result: {
+          version: 1,
+          outcome: "accepted",
+          selectedOptionIds: ["file-b"],
+        },
+        createdAt: "2026-04-20T12:00:00.000Z",
+        updatedAt: "2026-04-20T12:05:00.000Z",
+        resolvedAt: "2026-04-20T12:05:00.000Z",
+      },
+      createdIssues: [],
+    });
+    const app = await createApp();
+
+    const res = await request(app)
+      .post("/api/issues/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa/interactions/interaction-checkbox/accept")
+      .send({ selectedOptionIds: ["file-b"] });
+
+    expect(res.status).toBe(200);
+    expect(mockInteractionService.acceptInteraction).toHaveBeenCalledWith(
+      expect.objectContaining({ id: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" }),
+      "interaction-checkbox",
+      { selectedOptionIds: ["file-b"] },
+      expect.objectContaining({ userId: "local-board" }),
+    );
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledTimes(1);
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledWith(
+      ASSIGNEE_AGENT_ID,
+      expect.objectContaining({
+        reason: "issue_commented",
+        payload: expect.objectContaining({
+          interactionId: "interaction-checkbox",
+          interactionKind: "request_checkbox_confirmation",
+          interactionStatus: "accepted",
+        }),
+      }),
+    );
+    expect(mockLogActivity).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        action: "issue.thread_interaction_accepted",
+        details: expect.objectContaining({
+          interactionKind: "request_checkbox_confirmation",
+          interactionStatus: "accepted",
+        }),
+      }),
+    );
+  });
+
   it("forces a fresh workspace-aware session when accepting a planning confirmation", async () => {
     mockIssueService.getById.mockResolvedValueOnce(createIssue({ workMode: "planning" }));
     mockInteractionService.acceptInteraction.mockResolvedValueOnce({

server/src/__tests__/issue-thread-interactions-service.test.ts

@@ -746,6 +746,163 @@ describeEmbeddedPostgres("issueThreadInteractionService", () => {
     })).rejects.toThrow("A decline reason is required for this confirmation");
   });
 
+  it("accepts request_checkbox_confirmation interactions with selected option ids", async () => {
+    const { companyId, goalId, issueId } = await seedConfirmationIssue("Checkbox confirmation accept");
+
+    const created = await interactionsSvc.create({
+      id: issueId,
+      companyId,
+    }, {
+      kind: "request_checkbox_confirmation",
+      payload: {
+        version: 1,
+        prompt: "Which files should be deleted?",
+        options: [
+          { id: "file-a", label: "a.txt" },
+          { id: "file-b", label: "b.txt" },
+          { id: "file-c", label: "c.txt" },
+        ],
+        defaultSelectedOptionIds: ["file-a"],
+        minSelected: 0,
+        maxSelected: 2,
+      },
+    }, {
+      userId: "local-board",
+    });
+
+    expect(created).toMatchObject({
+      kind: "request_checkbox_confirmation",
+      status: "pending",
+      continuationPolicy: "wake_assignee",
+      payload: {
+        supersedeOnUserComment: true,
+        allowDeclineReason: true,
+      },
+    });
+
+    const accepted = await interactionsSvc.acceptInteraction({
+      id: issueId,
+      companyId,
+      goalId,
+      projectId: null,
+    }, created.id, {
+      selectedOptionIds: ["file-c", "file-a"],
+    }, {
+      userId: "local-board",
+    });
+
+    expect(accepted.createdIssues).toEqual([]);
+    expect(accepted.interaction).toMatchObject({
+      kind: "request_checkbox_confirmation",
+      status: "accepted",
+      result: {
+        version: 1,
+        outcome: "accepted",
+        selectedOptionIds: ["file-a", "file-c"],
+      },
+      resolvedByUserId: "local-board",
+    });
+  });
+
+  it("enforces request_checkbox_confirmation selected option references and bounds", async () => {
+    const { companyId, goalId, issueId } = await seedConfirmationIssue("Checkbox confirmation bounds");
+
+    const created = await interactionsSvc.create({
+      id: issueId,
+      companyId,
+    }, {
+      kind: "request_checkbox_confirmation",
+      payload: {
+        version: 1,
+        prompt: "Pick one or two options.",
+        options: [
+          { id: "one", label: "One" },
+          { id: "two", label: "Two" },
+          { id: "three", label: "Three" },
+        ],
+        minSelected: 1,
+        maxSelected: 2,
+      },
+    }, {
+      userId: "local-board",
+    });
+
+    await expect(interactionsSvc.acceptInteraction({
+      id: issueId,
+      companyId,
+      goalId,
+      projectId: null,
+    }, created.id, {
+      selectedOptionIds: [],
+    }, {
+      userId: "local-board",
+    })).rejects.toThrow("Select at least 1 checkbox confirmation option(s)");
+
+    await expect(interactionsSvc.acceptInteraction({
+      id: issueId,
+      companyId,
+      goalId,
+      projectId: null,
+    }, created.id, {
+      selectedOptionIds: ["missing"],
+    }, {
+      userId: "local-board",
+    })).rejects.toThrow("Unknown checkbox confirmation optionId: missing");
+
+    await expect(interactionsSvc.acceptInteraction({
+      id: issueId,
+      companyId,
+      goalId,
+      projectId: null,
+    }, created.id, {
+      selectedOptionIds: ["one", "two", "three"],
+    }, {
+      userId: "local-board",
+    })).rejects.toThrow("Select no more than 2 checkbox confirmation option(s)");
+  });
+
+  it("expires request_checkbox_confirmation interactions when a user comments after creation", async () => {
+    const { companyId, issueId } = await seedConfirmationIssue("Checkbox confirmation supersede");
+    const commentId = randomUUID();
+
+    const created = await interactionsSvc.create({
+      id: issueId,
+      companyId,
+    }, {
+      kind: "request_checkbox_confirmation",
+      payload: {
+        version: 1,
+        prompt: "Which files should be deleted?",
+        options: [{ id: "file-a", label: "a.txt" }],
+      },
+    }, {
+      userId: "local-board",
+    });
+
+    const expired = await interactionsSvc.expireRequestConfirmationsSupersededByComment({
+      id: issueId,
+      companyId,
+    }, {
+      id: commentId,
+      createdAt: new Date(new Date(created.createdAt).getTime() + 1_000),
+      authorUserId: "local-board",
+    }, {
+      userId: "local-board",
+    });
+
+    expect(expired).toHaveLength(1);
+    expect(expired[0]).toMatchObject({
+      id: created.id,
+      kind: "request_checkbox_confirmation",
+      status: "expired",
+      result: {
+        version: 1,
+        outcome: "superseded_by_comment",
+        commentId,
+      },
+    });
+  });
+
   it("returns agent-authored request confirmations to the creating agent when a board user accepts", async () => {
     const companyId = randomUUID();
     const goalId = randomUUID();

server/src/routes/issues.ts

@@ -6033,7 +6033,9 @@ export function issueRoutes(
         });
       }
 
-      const acceptedPlanTarget = readAcceptedPlanConfirmationTarget(interaction.payload);
+      const acceptedPlanTarget = interaction.kind === "request_confirmation"
+        ? readAcceptedPlanConfirmationTarget(interaction.payload)
+        : null;
       const acceptedPlanConfirmation =
         interaction.kind === "request_confirmation" &&
         interaction.status === "accepted" &&
@@ -6091,7 +6093,7 @@ export function issueRoutes(
           rejectionReason:
             interaction.kind === "suggest_tasks"
               ? (interaction.result?.rejectionReason ?? null)
-              : interaction.kind === "request_confirmation"
+              : interaction.kind === "request_confirmation" || interaction.kind === "request_checkbox_confirmation"
                 ? (interaction.result?.reason ?? null)
               : null,
         },

server/src/services/issue-thread-interactions.ts

@@ -16,6 +16,7 @@ import type {
   CancelIssueThreadInteraction,
   CreateIssueThreadInteraction,
   IssueThreadInteraction,
+  RequestCheckboxConfirmationInteraction,
   RequestConfirmationInteraction,
   RequestConfirmationTarget,
   RejectIssueThreadInteraction,
@@ -30,6 +31,8 @@ import {
   cancelIssueThreadInteractionSchema,
   createIssueThreadInteractionSchema,
   rejectIssueThreadInteractionSchema,
+  requestCheckboxConfirmationPayloadSchema,
+  requestCheckboxConfirmationResultSchema,
   requestConfirmationPayloadSchema,
   requestConfirmationResultSchema,
   suggestTasksPayloadSchema,
@@ -70,6 +73,19 @@ type IssueResolutionContext = {
   assigneeUserId: string | null;
 };
 
+const REQUEST_CONFIRMATION_INTERACTION_KINDS = [
+  "request_confirmation",
+  "request_checkbox_confirmation",
+] as const;
+type RequestConfirmationLikeKind = (typeof REQUEST_CONFIRMATION_INTERACTION_KINDS)[number];
+type RequestConfirmationLikeInteraction =
+  | RequestConfirmationInteraction
+  | RequestCheckboxConfirmationInteraction;
+
+function isRequestConfirmationLikeKind(kind: string): kind is RequestConfirmationLikeKind {
+  return (REQUEST_CONFIRMATION_INTERACTION_KINDS as readonly string[]).includes(kind);
+}
+
 function isIssueThreadInteractionIdempotencyConflict(error: unknown): boolean {
   if (typeof error !== "object" || error === null) return false;
   const err = error as { code?: string; constraint?: string; constraint_name?: string };
@@ -128,6 +144,13 @@ function hydrateInteraction(
         payload: requestConfirmationPayloadSchema.parse(row.payload),
         result: row.result ? requestConfirmationResultSchema.parse(row.result) : null,
       } satisfies RequestConfirmationInteraction;
+    case "request_checkbox_confirmation":
+      return {
+        ...base,
+        kind: "request_checkbox_confirmation",
+        payload: requestCheckboxConfirmationPayloadSchema.parse(row.payload),
+        result: row.result ? requestCheckboxConfirmationResultSchema.parse(row.result) : null,
+      } satisfies RequestCheckboxConfirmationInteraction;
     default:
       throw unprocessable(`Unknown interaction kind: ${row.kind}`);
   }
@@ -149,7 +172,7 @@ function shouldReturnAcceptedConfirmationToCreatorAgent(args: {
   current: IssueThreadInteractionRow;
   actor: InteractionActor;
 }) {
-  if (args.current.kind !== "request_confirmation") return false;
+  if (!isRequestConfirmationLikeKind(args.current.kind)) return false;
   if (!args.current.createdByAgentId) return false;
   if (!args.actor.userId) return false;
   if (!args.issue.assigneeUserId) return false;
@@ -158,19 +181,31 @@ function shouldReturnAcceptedConfirmationToCreatorAgent(args: {
   return true;
 }
 
-function shouldSupersedeRequestConfirmationOnUserComment(interaction: RequestConfirmationInteraction) {
+function shouldSupersedeRequestConfirmationOnUserComment(interaction: RequestConfirmationLikeInteraction) {
   return interaction.payload.supersedeOnUserComment === true;
 }
 
 function normalizeCreateInteractionInput(input: CreateIssueThreadInteraction): CreateIssueThreadInteraction {
-  if (input.kind !== "request_confirmation") return input;
-  return {
-    ...input,
-    payload: {
-      ...input.payload,
-      supersedeOnUserComment: input.payload.supersedeOnUserComment ?? true,
-    },
-  };
+  switch (input.kind) {
+    case "request_confirmation":
+      return {
+        ...input,
+        payload: {
+          ...input.payload,
+          supersedeOnUserComment: input.payload.supersedeOnUserComment ?? true,
+        },
+      };
+    case "request_checkbox_confirmation":
+      return {
+        ...input,
+        payload: {
+          ...input.payload,
+          supersedeOnUserComment: input.payload.supersedeOnUserComment ?? true,
+        },
+      };
+    default:
+      return input;
+  }
 }
 
 function isCommentAtOrAfterInteraction(args: {
@@ -255,6 +290,36 @@ function resolveSelectedSuggestedTasks(args: {
   };
 }
 
+function resolveSelectedCheckboxConfirmationOptions(args: {
+  interaction: RequestCheckboxConfirmationInteraction;
+  selectedOptionIds?: AcceptIssueThreadInteraction["selectedOptionIds"];
+}) {
+  const optionIds = new Set(args.interaction.payload.options.map((option) => option.id));
+  const selectedOptionIds = args.selectedOptionIds ?? args.interaction.payload.defaultSelectedOptionIds ?? [];
+  const selectedOptionIdSet = new Set<string>();
+
+  for (const optionId of selectedOptionIds) {
+    if (!optionIds.has(optionId)) {
+      throw unprocessable(`Unknown checkbox confirmation optionId: ${optionId}`);
+    }
+    selectedOptionIdSet.add(optionId);
+  }
+
+  const selectedCount = selectedOptionIdSet.size;
+  const minSelected = args.interaction.payload.minSelected ?? 0;
+  const maxSelected = args.interaction.payload.maxSelected ?? null;
+  if (selectedCount < minSelected) {
+    throw unprocessable(`Select at least ${minSelected} checkbox confirmation option(s)`);
+  }
+  if (maxSelected != null && selectedCount > maxSelected) {
+    throw unprocessable(`Select no more than ${maxSelected} checkbox confirmation option(s)`);
+  }
+
+  return args.interaction.payload.options
+    .filter((option) => selectedOptionIdSet.has(option.id))
+    .map((option) => option.id);
+}
+
 function normalizeQuestionAnswers(args: {
   questions: AskUserQuestionsInteraction["payload"]["questions"];
   answers: RespondIssueThreadInteraction["answers"];
@@ -401,8 +466,8 @@ async function expireStaleRequestConfirmationTarget(db: Db | any, args: {
   row: IssueThreadInteractionRow;
   actor: InteractionActor;
 }): Promise<IssueThreadInteraction | null> {
-  if (args.row.kind !== "request_confirmation" || args.row.status !== "pending") return null;
-  const interaction = hydrateInteraction(args.row) as RequestConfirmationInteraction;
+  if (!isRequestConfirmationLikeKind(args.row.kind) || args.row.status !== "pending") return null;
+  const interaction = hydrateInteraction(args.row) as RequestConfirmationLikeInteraction;
   const target = interaction.payload.target ?? null;
   if (!target) return null;
   if (target.type !== "issue_document") return null;
@@ -522,6 +587,7 @@ export function issueThreadInteractionService(db: Db) {
   async function acceptRequestConfirmation(args: {
     issue: { id: string; companyId: string };
     current: IssueThreadInteractionRow;
+    input: AcceptIssueThreadInteraction;
     actor: InteractionActor;
   }): Promise<{
     interaction: IssueThreadInteraction;
@@ -535,6 +601,15 @@ export function issueThreadInteractionService(db: Db) {
       return { interaction: expired, continuationIssue: null };
     }
 
+    const interaction = hydrateInteraction(args.current);
+    const selectedOptionIds =
+      interaction.kind === "request_checkbox_confirmation"
+        ? resolveSelectedCheckboxConfirmationOptions({
+            interaction,
+            selectedOptionIds: args.input.selectedOptionIds,
+          })
+        : undefined;
+
     const now = new Date();
     return db.transaction(async (tx) => {
       const [updated] = await tx
@@ -544,6 +619,7 @@ export function issueThreadInteractionService(db: Db) {
           result: {
             version: 1,
             outcome: "accepted",
+            ...(selectedOptionIds ? { selectedOptionIds } : {}),
           },
           resolvedByAgentId: args.actor.agentId ?? null,
           resolvedByUserId: args.actor.userId ?? null,
@@ -624,7 +700,7 @@ export function issueThreadInteractionService(db: Db) {
       return expired;
     }
 
-    const interaction = hydrateInteraction(args.current) as RequestConfirmationInteraction;
+    const interaction = hydrateInteraction(args.current) as RequestConfirmationLikeInteraction;
     const reason = args.input.reason?.trim() ?? "";
     if (interaction.payload.rejectRequiresReason === true && reason.length === 0) {
       throw unprocessable("A decline reason is required for this confirmation");
@@ -729,7 +805,7 @@ export function issueThreadInteractionService(db: Db) {
         }
       }
 
-      if (data.kind === "request_confirmation") {
+      if (data.kind === "request_confirmation" || data.kind === "request_checkbox_confirmation") {
         await assertRequestConfirmationTargetIsCurrent(db, {
           companyId: issue.companyId,
           issueId: issue.id,
@@ -798,6 +874,21 @@ export function issueThreadInteractionService(db: Db) {
           const accepted = await acceptRequestConfirmation({
             issue,
             current,
+            input: data,
+            actor,
+          });
+          return {
+            interaction: accepted.interaction,
+            continuationIssue: accepted.continuationIssue,
+            createdIssues: [],
+          };
+        }
+        case "request_checkbox_confirmation": {
+          await assertIssueWorkspaceFinalizedForAccept({ db, issue });
+          const accepted = await acceptRequestConfirmation({
+            issue,
+            current,
+            input: data,
             actor,
           });
           return {
@@ -970,6 +1061,7 @@ export function issueThreadInteractionService(db: Db) {
         case "suggest_tasks":
           return issueThreadInteractionService(db).rejectSuggestedTasks(issue, interactionId, data, actor, current);
         case "request_confirmation":
+        case "request_checkbox_confirmation":
           return rejectRequestConfirmation({
             issue,
             current,
@@ -1038,12 +1130,12 @@ export function issueThreadInteractionService(db: Db) {
         .where(and(
           eq(issueThreadInteractions.companyId, issue.companyId),
           eq(issueThreadInteractions.issueId, issue.id),
-          eq(issueThreadInteractions.kind, "request_confirmation"),
+          inArray(issueThreadInteractions.kind, [...REQUEST_CONFIRMATION_INTERACTION_KINDS]),
           eq(issueThreadInteractions.status, "pending"),
         ));
 
       const superseded = rows.filter((row) => {
-        const interaction = hydrateInteraction(row) as RequestConfirmationInteraction;
+        const interaction = hydrateInteraction(row) as RequestConfirmationLikeInteraction;
         return (
           shouldSupersedeRequestConfirmationOnUserComment(interaction)
           && isCommentAtOrAfterInteraction({
@@ -1096,7 +1188,7 @@ export function issueThreadInteractionService(db: Db) {
           .where(and(
             eq(issueThreadInteractions.companyId, issue.companyId),
             eq(issueThreadInteractions.issueId, issue.id),
-            eq(issueThreadInteractions.kind, "request_confirmation"),
+            inArray(issueThreadInteractions.kind, [...REQUEST_CONFIRMATION_INTERACTION_KINDS]),
             eq(issueThreadInteractions.status, "pending"),
           )),
         db
@@ -1122,7 +1214,7 @@ export function issueThreadInteractionService(db: Db) {
         }
       >();
       for (const row of rows) {
-        const interaction = hydrateInteraction(row) as RequestConfirmationInteraction;
+        const interaction = hydrateInteraction(row) as RequestConfirmationLikeInteraction;
         if (!shouldSupersedeRequestConfirmationOnUserComment(interaction)) continue;
 
         const supersedingComment = comments.find((comment) => isCommentAtOrAfterInteraction({
@@ -1182,12 +1274,12 @@ export function issueThreadInteractionService(db: Db) {
         .where(and(
           eq(issueThreadInteractions.companyId, issue.companyId),
           eq(issueThreadInteractions.issueId, issue.id),
-          eq(issueThreadInteractions.kind, "request_confirmation"),
+          inArray(issueThreadInteractions.kind, [...REQUEST_CONFIRMATION_INTERACTION_KINDS]),
           eq(issueThreadInteractions.status, "pending"),
         ));
 
       const staleRows = rows.filter((row) => {
-        const interaction = hydrateInteraction(row) as RequestConfirmationInteraction;
+        const interaction = hydrateInteraction(row) as RequestConfirmationLikeInteraction;
         const target = interaction.payload.target;
         if (!target || target.type !== "issue_document") return false;
         const targetIssueId = target.issueId ?? issue.id;
@@ -1206,7 +1298,7 @@ export function issueThreadInteractionService(db: Db) {
       const now = new Date();
       const expired: IssueThreadInteraction[] = [];
       for (const row of staleRows) {
-        const interaction = hydrateInteraction(row) as RequestConfirmationInteraction;
+        const interaction = hydrateInteraction(row) as RequestConfirmationLikeInteraction;
         const target = interaction.payload.target ?? null;
         const currentTarget = buildIssueDocumentTargetFromDocument({
           issueId: issue.id,