Add Code Queue resume contract

2026-05-23 10:28:57 +00:00
parent 184667b4cb
commit fd8e21e611
11 changed files with 830 additions and 4 deletions
@@ -370,6 +370,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
    items.push(commandItem("code-queue:prompt-lint-contract", ["bun", "scripts/code-queue-prompt-lint-contract-test.ts"], 30_000));
    items.push(commandItem("code-queue:cli-steer-contract", ["bun", "scripts/code-queue-cli-steer-test.ts"], 30_000));
    items.push(commandItem("code-queue:steer-confirmation-contract", ["bun", "scripts/code-queue-steer-confirmation-contract-test.ts"], 30_000));
+    items.push(commandItem("code-queue:resume-contract", ["bun", "scripts/code-queue-resume-contract-test.ts"], 30_000));
    items.push(commandItem("code-queue:read-terminal-contract", ["bun", "scripts/code-queue-cli-read-terminal-contract-test.ts"], 30_000));
    items.push(commandItem("code-queue:submit-prompt-contract", ["bun", "scripts/code-queue-cli-submit-prompt-contract-test.ts"], 30_000));
    items.push(commandItem("code-queue:submit-execution-mode-contract", ["bun", "scripts/code-queue-submit-execution-mode-contract-test.ts"], 30_000));
@@ -407,6 +408,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
    items.push(skippedItem("code-queue:prompt-lint-contract", "Code Queue prompt live-authorization lint contract is opt-in with script checks", "--scripts-typecheck or --full"));
    items.push(skippedItem("code-queue:cli-steer-contract", "Code Queue steer CLI contract is opt-in with script checks", "--scripts-typecheck or --full"));
    items.push(skippedItem("code-queue:steer-confirmation-contract", "Code Queue steer delivery confirmation contract is opt-in with script checks", "--scripts-typecheck or --full"));
+    items.push(skippedItem("code-queue:resume-contract", "Code Queue resume CLI and delivery contract is opt-in with script checks", "--scripts-typecheck or --full"));
    items.push(skippedItem("code-queue:read-terminal-contract", "Code Queue terminal read contract is opt-in with script checks", "--scripts-typecheck or --full"));
    items.push(skippedItem("code-queue:submit-prompt-contract", "Code Queue submit prompt contract is opt-in with script checks", "--scripts-typecheck or --full"));
    items.push(skippedItem("code-queue:submit-execution-mode-contract", "Code Queue submit execution-mode contract is opt-in with script checks", "--scripts-typecheck or --full"));
@@ -3,6 +3,7 @@ import { runCommand } from "./command";
 import { type UniDeskConfig, repoRoot, rootPath } from "./config";
 import { coreInternalFetch } from "./microservices";
 import { previewJson } from "./preview";
+import { createResumeId, type ResumeDeliveryState } from "../../src/components/microservices/code-queue/src/resume-confirmation";
 import { createSteerId, type SteerDeliveryState } from "../../src/components/microservices/code-queue/src/steer-confirmation";
 import {
  codeAgentPortForModel,
@@ -234,6 +235,14 @@ interface CodexSteerConfirmOptions {
  raw: boolean;
 }

+interface CodexResumeOptions {
+  prompt: string;
+  resumeId: string | undefined;
+  dryRun: boolean;
+  full: boolean;
+  raw: boolean;
+}
+
 type CodexSteerFailureReason =
  | "backend-core-unreachable"
  | "code-queue-microservice-unregistered"
@@ -245,6 +254,8 @@ type CodexSteerFailureReason =
  | "invalid-proxy-response";

 type CodexSteerAcceptanceStatus = "accepted" | "not_accepted" | "accepted_response_timeout" | "unknown";
+type CodexResumeAcceptanceStatus = "queued" | "duplicate_suppressed" | "not_accepted" | "accepted_response_timeout" | "unknown";
+type CodexResumeDeliveryState = ResumeDeliveryState;

 interface ClassifiedCodexSteerError {
  reason: CodexSteerFailureReason;
@@ -468,6 +479,10 @@ function rawSteerConfirmationCommand(taskId: string, steerId: string): string {
  return `bun scripts/cli.ts microservice proxy code-queue ${steerConfirmationPath(taskId, steerId)} --raw`;
 }

+function resumeCommand(taskId: string, resumeId: string): string {
+  return `bun scripts/cli.ts codex resume ${taskId} --prompt-file <path> --resume-id ${resumeId}`;
+}
+
 function nonNegativeIntegerEnv(name: string, fallback: number): number {
  const raw = process.env[name];
  if (raw === undefined || raw.trim().length === 0) return fallback;
@@ -2595,6 +2610,10 @@ export function codexSteerTaskForTest(taskId: string, optionArgs: string[], fetc
  return codexSteerTask(taskId, optionArgs, fetcher);
 }

+export function codexResumeTaskForTest(taskId: string, optionArgs: string[], fetcher: CodexResponseFetcher): unknown {
+  return codexResumeTask(taskId, optionArgs, fetcher);
+}
+
 export function codexSteerTraceConfirmForTest(taskId: string, optionArgs: string[], fetcher: CodexResponseFetcher): unknown {
  return codexSteerTraceConfirm(taskId, optionArgs, fetcher);
 }
@@ -4071,6 +4090,13 @@ const steerPromptValueOptions = new Set([
  "--steerId",
 ]);

+const resumePromptValueOptions = new Set([
+  "--prompt-file",
+  "--file",
+  "--resume-id",
+  "--resumeId",
+]);
+
 function referenceTaskIdsFromOptions(args: string[]): string[] {
  const values = optionValues(args, ["--reference-task-id", "--reference", "--ref"]);
  const ids: string[] = [];
@@ -4207,6 +4233,22 @@ function parseSteerConfirmOptions(args: string[]): CodexSteerConfirmOptions {
  return { steerId, raw: hasFlag(args, "--raw") };
 }

+function parseResumeOptions(args: string[]): CodexResumeOptions {
+  assertKnownOptions(args, {
+    flags: ["--prompt-stdin", "--stdin", "--dry-run", "--full", "--raw"],
+    valueOptions: ["--prompt-file", "--file", "--resume-id", "--resumeId"],
+  }, "codex resume");
+  const resumeId = optionValue(args, ["--resume-id", "--resumeId"]);
+  if (resumeId !== undefined && !/^[A-Za-z0-9._:-]{8,128}$/u.test(resumeId)) throw new Error("--resume-id must be 8-128 chars using letters, numbers, dot, underscore, colon, or dash");
+  return {
+    prompt: promptFromArgs(args, "codex resume", resumePromptValueOptions),
+    resumeId,
+    dryRun: hasFlag(args, "--dry-run"),
+    full: hasFlag(args, "--full") || hasFlag(args, "--raw"),
+    raw: hasFlag(args, "--raw"),
+  };
+}
+
 function parsePromptLintOptions(args: string[]): CodexPromptLintOptions {
  assertKnownOptions(args, {
    flags: ["--prompt-stdin", "--stdin"],
@@ -4308,6 +4350,58 @@ function compactSteerTaskConfirmation(task: unknown, steerId: string): Record<st
  };
 }

+function compactResumeTraceConfirmation(value: unknown, taskId: string, resumeId: string): Record<string, unknown> {
+  const record = asRecord(value) ?? {};
+  const confirmation = asRecord(record.confirmation) ?? record;
+  const trace = asRecord(confirmation.trace);
+  const compactTrace = trace === null ? null : {
+    seq: trace.seq ?? null,
+    at: trace.at ?? null,
+    method: trace.method ?? null,
+    resumeId: trace.resumeId ?? resumeId,
+    promptChars: trace.promptChars ?? null,
+    promptHash: trace.promptHash ?? null,
+    promptOmitted: true,
+    source: trace.source ?? null,
+  };
+  return {
+    taskId: asString(confirmation.taskId) || taskId,
+    resumeId: asString(confirmation.resumeId) || resumeId,
+    found: confirmation.found === true,
+    accepted: confirmation.accepted === true,
+    deliveryState: asString(confirmation.deliveryState) || (confirmation.found === true ? "queued_for_existing_thread" : "unknown"),
+    matchCount: asNumber(confirmation.matchCount, 0),
+    trace: compactTrace,
+    duplicateSuppressionKey: confirmation.duplicateSuppressionKey ?? resumeId,
+    promptOmitted: true,
+  };
+}
+
+function terminalStatusFromResumeTask(task: Record<string, unknown> | null): string {
+  return terminalStatusFromTask(task);
+}
+
+function compactResumeTaskConfirmation(task: unknown, resumeId: string, source: Record<string, unknown>): Record<string, unknown> {
+  const compact = compactSubmitTaskConfirmation(task);
+  const commands = asRecord(compact.commands) ?? {};
+  const record = asRecord(task) ?? {};
+  return {
+    ...compact,
+    currentAttempt: record.currentAttempt ?? null,
+    currentMode: record.currentMode ?? null,
+    terminalStatus: terminalStatusFromResumeTask(record) || null,
+    reusedCodexThreadId: source.originalCodexThreadId ?? source.codexThreadId ?? record.codexThreadId ?? null,
+    commands: {
+      ...commands,
+      show: `bun scripts/cli.ts codex task ${asString(compact.id) || "<taskId>"}`,
+      detail: `bun scripts/cli.ts codex task ${asString(compact.id) || "<taskId>"} --detail`,
+      trace: `bun scripts/cli.ts codex task ${asString(compact.id) || "<taskId>"} --trace --tail --limit ${defaultTraceLimit}`,
+      output: `bun scripts/cli.ts codex output ${asString(compact.id) || "<taskId>"} --tail --limit ${defaultOutputLimit}`,
+      resumeAgain: resumeCommand(asString(compact.id) || "<taskId>", resumeId),
+    },
+  };
+}
+
 function orderedUniqueStringList(values: string[]): string[] {
  const seen = new Set<string>();
  const items: string[] = [];
@@ -6461,6 +6555,147 @@ function codexSteerTraceConfirm(taskId: string, args: string[], fetcher: CodexRe
  };
 }

+function compactResumeRejection(taskId: string, resumeId: string, response: unknown, options: CodexResumeOptions): Record<string, unknown> {
+  const record = asRecord(response);
+  const body = responseBody(record);
+  const task = asRecord(body?.task);
+  const status = asString(task?.status);
+  const upstreamStatus = responseStatus(record);
+  const bodyError = asString(body?.error);
+  const disposition = asString(body?.disposition)
+    || (upstreamStatus === 404 || bodyError?.toLowerCase().includes("not found") ? "task-not-found" : isActiveTaskStatus(status) ? "use-steer-for-active-task" : isTerminalTaskStatus(status) ? "resume-rejected" : "not-terminal");
+  const result: Record<string, unknown> = {
+    ok: false,
+    resume: {
+      accepted: false,
+      status: "not_accepted" satisfies CodexResumeAcceptanceStatus,
+      deliveryState: "not_accepted" satisfies CodexResumeDeliveryState,
+      resumeId,
+      reason: disposition,
+      taskId,
+      taskStatus: status || null,
+      terminalStatus: terminalStatusFromResumeTask(task) || null,
+      retryable: false,
+      promptOmitted: true,
+    },
+    message: asString(body?.error) || `task ${taskId} is not resumable`,
+    commands: {
+      show: `bun scripts/cli.ts codex task ${taskId}`,
+      detail: `bun scripts/cli.ts codex task ${taskId} --detail`,
+      ...(disposition === "use-steer-for-active-task" ? { steer: `bun scripts/cli.ts codex steer ${taskId} --prompt-file <path>` } : {}),
+      supervisor: `bun scripts/cli.ts codex tasks --view supervisor --limit ${defaultTasksLimit}`,
+    },
+    upstream: {
+      status: upstreamStatus,
+      error: bodyError || null,
+    },
+    disclosure: {
+      defaultPolicy: "compact resume rejection; request prompt, upstream task body, and raw response require explicit --full or --raw",
+      full: options.full,
+      raw: options.raw,
+      defaultOmitted: ["request.body.prompt.text", "task.prompt", "task.finalResponse", "rawFailure"],
+    },
+  };
+  if (options.full) {
+    result.task = compactResumeTaskConfirmation(task, resumeId, body ?? {});
+    result.upstreamBodyPreview = previewJson(body ?? record, { maxDepth: 4, maxArrayItems: 8, maxObjectKeys: 24, maxStringLength: 600 });
+  }
+  if (options.raw) result.rawFailure = response;
+  return result;
+}
+
+function codexResumeTask(taskId: string, args: string[], fetcher: CodexResponseFetcher = coreInternalFetch): unknown {
+  const options = parseResumeOptions(args);
+  const resumeId = options.resumeId ?? createResumeId(taskId, options.prompt);
+  const targetPath = `/api/tasks/${encodeURIComponent(taskId)}/resume`;
+  const stableProxyPath = codeQueueProxyPath(targetPath);
+  const rawProxyEquivalent = codeQueueProxyEquivalentCommand(targetPath, `{"prompt":"...","resumeId":"${resumeId}"}`);
+  const prompt = textView(options.prompt, false, steerPromptPreviewChars);
+  const request = {
+    path: targetPath,
+    stableProxyPath,
+    method: "POST",
+    resumeId,
+    bodySummary: {
+      resumeId,
+      promptChars: options.prompt.length,
+      promptPreviewChars: steerPromptPreviewChars,
+      promptTruncated: prompt.truncated,
+    },
+    body: { resumeId, prompt },
+    contract: {
+      target: "terminal-or-awaiting-closeout task follow-up turn",
+      idempotency: "same resumeId and same prompt is duplicate-suppressed; same resumeId and different prompt is rejected as conflict",
+      activeTaskDisposition: "active running/judging tasks must use codex steer, not resume",
+      promptEchoPolicy: "default dry-run shows only bounded prompt preview; non-dry-run never echoes prompt text",
+    },
+  };
+  if (options.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      request,
+      commands: {
+        run: resumeCommand(taskId, resumeId),
+        show: `bun scripts/cli.ts codex task ${taskId}`,
+        supervisor: `bun scripts/cli.ts codex tasks --view supervisor --limit ${defaultTasksLimit}`,
+        rawProxy: rawProxyEquivalent,
+      },
+    };
+  }
+  const rawResponse = fetcher(stableProxyPath, { method: "POST", body: { prompt: options.prompt, resumeId } });
+  const record = asRecord(rawResponse);
+  const body = responseBody(record);
+  if (record?.ok !== true || body?.ok !== true) {
+    return compactResumeRejection(taskId, resumeId, rawResponse, options);
+  }
+  const responseResumeId = asString(body.resumeId) || resumeId;
+  const duplicateSuppressed = body.duplicateSuppressed === true;
+  const traceConfirmation = compactResumeTraceConfirmation(body.traceConfirmation, taskId, responseResumeId);
+  const deliveryState = asString(body.deliveryState) || asString(traceConfirmation.deliveryState) || (duplicateSuppressed ? "duplicate_suppressed" : "queued_for_existing_thread");
+  const acceptanceStatus: CodexResumeAcceptanceStatus = duplicateSuppressed ? "duplicate_suppressed" : deliveryState === "accepted_response_timeout" ? "accepted_response_timeout" : "queued";
+  const traceRecord = asRecord(traceConfirmation.trace);
+  return {
+    ok: true,
+    upstream: { ok: record.ok, status: record.status },
+    resume: {
+      accepted: true,
+      status: acceptanceStatus,
+      deliveryState,
+      resumeId: responseResumeId,
+      turnId: body.turnId ?? traceRecord?.seq ?? null,
+      taskId,
+      promptChars: options.prompt.length,
+      promptOmitted: true,
+      duplicateSuppressed,
+      duplicateSuppressionKey: responseResumeId,
+      reusedCodexThread: body.reuseOriginalThread === true,
+      originalCodexThreadId: body.originalCodexThreadId ?? null,
+      codexThreadId: body.codexThreadId ?? null,
+      deliveryUnconfirmed: deliveryState === "accepted_response_timeout",
+      outputPolicy: {
+        default: "write-confirmation",
+        promptEchoed: false,
+        taskDetailEchoed: false,
+        reason: "codex resume is a write operation; default output confirms queued delivery and provides drill-down commands without echoing prompt text or full task state.",
+      },
+    },
+    traceConfirmation,
+    task: compactResumeTaskConfirmation(body.task, responseResumeId, body),
+    queue: compactSubmitQueueConfirmation(body.queue),
+    commands: {
+      show: `bun scripts/cli.ts codex task ${taskId}`,
+      detail: `bun scripts/cli.ts codex task ${taskId} --detail`,
+      trace: `bun scripts/cli.ts codex task ${taskId} --trace --tail --limit ${defaultTraceLimit}`,
+      output: `bun scripts/cli.ts codex output ${taskId} --tail --limit ${defaultOutputLimit}`,
+      retrySameResumeId: resumeCommand(taskId, responseResumeId),
+      supervisor: `bun scripts/cli.ts codex tasks --view supervisor --limit ${defaultTasksLimit}`,
+      confirmDelivery: `bun scripts/cli.ts codex task ${taskId} --trace --tail --limit ${defaultTraceLimit}`,
+      ...(deliveryState === "accepted_response_timeout" ? { deliveryUnconfirmed: `bun scripts/cli.ts codex task ${taskId} --trace --tail --limit ${defaultTraceLimit}` } : {}),
+    },
+  };
+}
+
 export async function runCodeQueueCommand(config: UniDeskConfig, args: string[]): Promise<unknown> {
  const [action = "task", taskIdArg] = args;
  if (action === "prompt-lint" || action === "lint-prompt") {
@@ -6519,9 +6754,13 @@ export async function runCodeQueueCommand(config: UniDeskConfig, args: string[])
    const taskId = requireTaskId(taskIdArg, "codex steer");
    return codexSteerTask(taskId, args.slice(2));
  }
+  if (action === "resume") {
+    const taskId = requireTaskId(taskIdArg, "codex resume");
+    return codexResumeTask(taskId, args.slice(2));
+  }
  if (action === "steer-confirm" || action === "steer-confirmation") {
    const taskId = requireTaskId(taskIdArg, `codex ${action}`);
    return codexSteerTraceConfirm(taskId, args.slice(2));
  }
-  throw new Error("codex command must be one of: prompt-lint, submit, enqueue, task, summary, show, tasks, overview, unread, terminal-unread, output, judge, read, mark-read, dev-ready, health, skills-sync, pr-preflight, runtime-preflight, queues, queue list, queue create, queue merge, move, steer, steer-confirm, interrupt, cancel");
+  throw new Error("codex command must be one of: prompt-lint, submit, enqueue, task, summary, show, tasks, overview, unread, terminal-unread, output, judge, read, mark-read, dev-ready, health, skills-sync, pr-preflight, runtime-preflight, queues, queue list, queue create, queue merge, move, steer, resume, steer-confirm, interrupt, cancel");
 }
@@ -64,6 +64,7 @@ export function rootHelp(): unknown {
      { command: "codex dev-ready", description: "Fetch execution-container readiness, including sanitized skill injection status from /api/dev-ready." },
      { command: "codex judge <taskId> --attempt N [--dry-run] [--include-prompt]", description: "Replay one stored Code Queue attempt through the same judge context builder and MiniMax judge call path used by the live queue worker." },
      { command: "codex steer <taskId> [prompt|--prompt-file path|--prompt-stdin] [--steer-id id] [--dry-run] [--no-retry|--retry-attempts N] [--full|--raw]", description: "Push a corrective prompt into a running Code Queue task with a steerId/idempotency key; retryable tunnel aborts get bounded trace confirmation before any retry guidance." },
+      { command: "codex resume <taskId> [prompt|--prompt-file path|--prompt-stdin] [--resume-id id] [--dry-run] [--full|--raw]", description: "Queue a follow-up turn on a terminal Code Queue task, preserving the original task/thread/PR context and suppressing duplicate resumeId delivery without echoing the prompt." },
      { command: "codex steer-confirm <taskId> --steer-id <id> [--raw]", description: "Read-only lookup for a steerId in task trace so deliveryUnconfirmed can be resolved without resending the corrective prompt." },
      { command: "codex interrupt|cancel <taskId>", description: "Request interrupt for a running Code Queue task, or cancel a queued/retry_wait task, through the same private proxy." },
      { command: "codex (queues [--full|--all] | queue create <queueId> | queue merge <sourceQueueId> --into <targetQueueId> | move <taskId> --queue <queueId>)", description: "List low-noise queue summaries by default, including effective activity counts that distinguish scheduler-local queues, DB running tasks, and heartbeat-fresh runners; full queue rows require --full/--all." },
@@ -249,7 +250,7 @@ function scheduleHelp(): unknown {

 function codexHelp(): unknown {
  return {
-    command: "codex deploy|prompt-lint|submit|task|tasks|unread|output|read|dev-ready|skills-sync|pr-preflight|judge|steer|interrupt|cancel|queues|queue|move",
+    command: "codex deploy|prompt-lint|submit|task|tasks|unread|output|read|dev-ready|skills-sync|pr-preflight|judge|steer|resume|interrupt|cancel|queues|queue|move",
    output: "json",
    usage: [
      "bun scripts/cli.ts codex deploy <commitId> # disabled legacy deployment entry",
@@ -268,6 +269,7 @@ function codexHelp(): unknown {
      "bun scripts/cli.ts codex pr-preflight [--remote] [--push-dry-run --push-dry-run-ref refs/heads/probe/<name>] [--pr-create-dry-run --pr-create-dry-run-head <head>] [--issue N] [--full|--raw]",
      "bun scripts/cli.ts codex judge <taskId> --attempt N [--dry-run] [--include-prompt]",
      "bun scripts/cli.ts codex steer <taskId> [prompt|--prompt-file path|--prompt-stdin] [--steer-id id] [--dry-run] [--no-retry|--retry-attempts N] [--full|--raw]",
+      "bun scripts/cli.ts codex resume <taskId> [prompt|--prompt-file path|--prompt-stdin] [--resume-id id] [--dry-run] [--full|--raw]",
      "bun scripts/cli.ts codex steer-confirm <taskId> --steer-id <id> [--raw]",
      "bun scripts/cli.ts codex interrupt|cancel <taskId>",
      "bun scripts/cli.ts codex queues [--full|--all] [--limit N] [--page N|--offset N] | queue create <queueId> | queue merge <sourceQueueId> --into <targetQueueId> | move <taskId> --queue <queueId>",