@botiverse/raft-sdk 0.3.2 → 0.4.1

package/dist/index.d.ts

@@ -341,8 +341,8 @@ interface RaftNextStep {
   /**
    * Structured arguments for the step: plain, serialisable data (never a
    * closure), so a runtime whose next step runs in another process can store
-   * it and act on it later — for example spread a held send's `args` into the
-   * next `messages.send`.
+   * it and act on it later — for example the `target` of a `read_target` step.
+   * (An interrupted call's resume is `interrupt.resume`, not `args`.)
    */
   args?: Record<string, unknown>;
   /** One sentence explaining why this is the next step. */
@@ -426,6 +426,70 @@ export declare function projectRaftMessage(envelope: AgentApiMessageEnvelope): R
 /** Project a list, skipping envelopes without a conversation identity. */
 export declare function projectRaftMessages(envelopes: readonly AgentApiMessageEnvelope[]): RaftMessage[];
 //#endregion
+//#region ../shared/src/agentOps/interrupt.d.ts
+/** Why the call stopped. */
+type RaftInterruptReason = "unread_messages";
+interface RaftInterruptResume {
+  /**
+   * The exact `raft` argv that carries out the interrupted call (for example
+   * `["message", "send", "--send-draft", …]`), when the call ran as a command
+   * (CLI or command endpoint) and its input is stored. Absent for an
+   * in-process SDK call: then resuming means calling the same SDK method again
+   * with the same input and `idempotencyKey`.
+   */
+  argv?: string[];
+  /** The interrupted call's original idempotency key, when it has one (a send); resuming reuses it. */
+  idempotencyKey?: string;
+}
+interface RaftInterruptCancel {
+  /** The exact `raft` argv that releases what the interrupted call left behind (a held send's saved draft). */
+  argv: string[];
+}
+interface RaftInterrupt {
+  reason: RaftInterruptReason;
+  /** What happened and what is new, as the CLI prints it; enough for the model to decide in one turn. */
+  context: string;
+  /** How to go ahead. Always present. */
+  resume: RaftInterruptResume;
+  /**
+   * How to drop the call when it left something to clean up (today: the draft
+   * a held send saved). Absent `cancel` means cancelling needs no request:
+   * just don't execute `resume`.
+   */
+  cancel?: RaftInterruptCancel;
+  /** The conversation the unread messages are in. */
+  target: string;
+  /** How many newer messages the agent has not seen in this conversation. */
+  newMessageCount: number;
+  /** The newest of them, previewed; the Server may omit older ones. Empty when withheld. */
+  heldMessages: RaftMessage[];
+  omittedMessageCount: number;
+  /** How many of the unread messages formally @mention this agent. */
+  formalMentionCount: number;
+  /** The seq the Server considers current for this conversation; attesting it says the model saw the context. */
+  seenUpToSeq: number | null;
+  /** Reviewer isolation: bodies withheld, only a count. */
+  withheld: boolean;
+  /**
+   * Whether `heldMessages` plus `omittedMessageCount` account for every one of
+   * `newMessageCount`. When false the model cannot have seen all of them:
+   * `frontier.recordHeld(interrupt)` records nothing, and the model should
+   * read the conversation before resuming.
+   */
+  contextComplete: boolean;
+}
+/** The outcome of an interrupted call. */
+interface RaftInterrupted {
+  ok: true;
+  state: "interrupted";
+  interrupt: RaftInterrupt;
+  next: RaftNextStep | null;
+  /** The canonical text; the same as `interrupt.context`. */
+  text: string;
+}
+/** Narrow any outcome (SDK or command registry) to an interrupt, without knowing the command. */
+export declare function isInterrupted(outcome: unknown): outcome is RaftInterrupted;
+//#endregion
 //#region ../shared/src/agentOps/frontier.d.ts
 interface SeenAttestation {
   seenUpToSeq?: number;
@@ -454,11 +518,12 @@ export declare class SeenFrontier {
   /** Record bodies that were rendered without proving contiguity. */
   recordExact(target: string, seqs: readonly number[]): void;
   /**
-   * Attest that the model saw the context a held send/claim returned. Call it
-   * only after the held messages actually reached the model (the SDK cannot
-   * know that, so it never records this implicitly). Returns false and records
-   * nothing when the context was withheld, not fully shown
-   * (`contextComplete: false`), or the Server sent no boundary.
+   * Attest that the model saw the context of an interrupt (`outcome.interrupt`
+   * of an `interrupted` send, claim or task write). Call it only after
+   * `interrupt.context` actually reached the model (the SDK cannot know that,
+   * so it never records this implicitly). Returns false and records nothing
+   * when the context was withheld, not fully shown (`contextComplete: false`),
+   * or the Server sent no boundary.
    */
   recordHeld(held: {
     target: string;
@@ -555,6 +620,12 @@ interface ReadHistoryRequest {
   /** Anchor a window around a seq or message id; records exact seqs only. */
   around?: number | string;
   limit?: number;
+  /**
+   * `false` reads without consuming: the Server does not mark the page read,
+   * and nothing is recorded in the seen frontier. Use it when the result may
+   * not reach the model (for example, code the agent wrote).
+   */
+  consume?: boolean;
 }
 interface RaftHistoryPage {
   /** Canonical target the Server resolved (falls back to the requested spelling on older Servers). */
@@ -573,7 +644,8 @@ interface SendMessageRequest {
   /**
    * One key per logical message. Generated with `crypto.randomUUID()` when
    * omitted, so a response lost after the Server committed can be retried
-   * without posting twice; a `resend` after a hold reuses the same key.
+   * without posting twice; sending again after an interrupt reuses the same
+   * key (`interrupt.resume.idempotencyKey`).
    */
   idempotencyKey?: string;
   mentions?: AgentApiStructuredMention[];
@@ -595,59 +667,7 @@ interface RaftSent {
   /** Newer messages the Server returned alongside the acceptance, if any. */
   recentUnread: RaftMessage[];
 }
-/**
- * Plain data that continues a held send in a later process: spread it into
- * the next `messages.send({ ...original, ...continuation })`. `seen` is set
- * only when the Server reported a boundary and nothing was withheld.
- * Spreading `seen` asserts that the model saw the held messages (the same
- * attestation as `frontier.recordHeld`); drop it if the held text was stored
- * without being handed to the model, and the next send will be held again
- * with the same context instead of passing on a false attestation.
- */
-interface RaftSendContinuation {
-  idempotencyKey: string;
-  seen?: {
-    upToSeq: number;
-  };
-}
-interface RaftHeldBase {
-  target: string;
-  /** The idempotency key of the held message; a later send with this key is the same logical message. */
-  idempotencyKey: string;
-  /** Serialisable continuation for the next step (also carried in `next.args`). */
-  continuation: RaftSendContinuation;
-  /** How many newer messages the agent has not seen in this conversation. */
-  newMessageCount: number;
-  /** The newest of them, previewed; the Server may omit older ones. */
-  heldMessages: RaftMessage[];
-  omittedMessageCount: number;
-  /** How many of the held messages formally @mention this agent. */
-  formalMentionCount: number;
-  /** The seq the Server considers current for this conversation; attesting it says the model saw the held context. */
-  seenUpToSeq: number | null;
-  /** Reviewer isolation: bodies withheld, only a count. */
-  withheld: boolean;
-  /**
-   * Whether `heldMessages` plus `omittedMessageCount` account for every one of
-   * `newMessageCount`. When false the model cannot have seen all of them, so
-   * no `seen` is offered and `frontier.recordHeld` records nothing; read the
-   * conversation instead.
-   */
-  contextComplete: boolean;
-}
-interface RaftHeld extends RaftHeldBase {
-  /**
-   * In-process sugar over `continuation`: send the same message again after the
-   * runtime has handled the held context. `seen: "held"` attests the Server's
-   * `seenUpToSeq` (say this only if the model saw the held messages);
-   * `seen: "anyway"` bypasses the freshness check. Runtimes whose next step
-   * runs elsewhere store `continuation` (or `next.args`) instead.
-   */
-  resend(options: {
-    seen: "held" | "anyway";
-  }): Promise<SendMessageOutcome>;
-}
-type SendMessageOutcome = RaftOutcome<RaftSent, "sent"> | RaftOutcome<RaftHeld, "held">;
+type SendMessageOutcome = RaftOutcome<RaftSent, "sent"> | RaftInterrupted;
 //#endregion
 //#region ../shared/src/agentText/tasks.d.ts
 interface AgentClaimConflict {
@@ -702,13 +722,7 @@ interface RaftClaimResult {
   /** At least one row authorises work. */
   anyAuthorised: boolean;
 }
-interface RaftClaimHeld extends Omit<RaftHeldBase, "idempotencyKey" | "continuation"> {
-  /** The claim to repeat once the held context has been handled (plain data; also in `next.args`). */
-  request: ClaimTasksRequest;
-  /** In-process sugar: retry the identical claim. */
-  retry(): Promise<ClaimTasksOutcome>;
-}
-type ClaimTasksOutcome = RaftOutcome<RaftClaimResult, "claimed" | "partial" | "refused"> | RaftOutcome<RaftClaimHeld, "held">;
+type ClaimTasksOutcome = RaftOutcome<RaftClaimResult, "claimed" | "partial" | "refused"> | RaftInterrupted;
 type RaftTaskStatus = "todo" | "in_progress" | "in_review" | "done" | "closed";
 interface ListTasksRequest {
   /** Channel board, for example `#proj-sdk`; omit with `mine: true` for your own tasks across channels. */
@@ -747,11 +761,7 @@ interface AssignTaskRequest extends TaskRef {
 interface UpdateTaskStatusRequest extends TaskRef {
   status: RaftTaskStatus;
 }
-type UpdateTaskStatusOutcome = RaftOutcome<UpdateTaskStatusRequest, "updated"> | RaftOutcome<RaftClaimHeldLike<UpdateTaskStatusRequest>, "held">;
-/** A hold on a task write: the held context plus the request to repeat, as data. */
-type RaftClaimHeldLike<TRequest> = Omit<RaftHeldBase, "idempotencyKey" | "continuation"> & {
-  request: TRequest;
-};
+type UpdateTaskStatusOutcome = RaftOutcome<UpdateTaskStatusRequest, "updated"> | RaftInterrupted;
 interface AmendTaskRequest extends TaskRef {
   title?: string;
   /** New description; `null` clears it. */
@@ -759,7 +769,7 @@ interface AmendTaskRequest extends TaskRef {
 }
 type AmendTaskOutcome = RaftOutcome<AgentApiTaskAmendSuccessResponse & {
   target: string;
-}, "amended"> | RaftOutcome<RaftClaimHeldLike<AmendTaskRequest>, "held">;
+}, "amended"> | RaftInterrupted;
 //#endregion
 //#region ../shared/src/agentOps/wake.d.ts
 export declare const RAFT_INBOX_NOTICE_SCHEMA: "raft-agent-inbox-notice.v1";
@@ -1286,8 +1296,8 @@ declare const attachmentUploadSessionSchema: z.ZodObject<{
     pending: "pending";
     canceled: "canceled";
     completed: "completed";
-    failed: "failed";
     verifying: "verifying";
+    failed: "failed";
   }>;
   expiresAt: z.ZodISODateTime;
   attachment: z.ZodNullable<z.ZodObject<{
@@ -1431,6 +1441,10 @@ declare const agentApiHistoryQuerySchema: z.ZodObject<{
   after: z.ZodOptional<z.ZodString>;
   around: z.ZodOptional<z.ZodString>;
   limit: z.ZodOptional<z.ZodString>;
+  consume: z.ZodOptional<z.ZodEnum<{
+    true: "true";
+    false: "false";
+  }>>;
 }, z.core.$loose>;
 declare const agentApiKnowledgeGetQuerySchema: z.ZodObject<{
   topic: z.ZodString;
@@ -2850,100 +2864,6 @@ declare const agentApiAppConfigResponseSchema: z.ZodObject<{
   overrides: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>>;
   effective: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>>;
 }, z.core.$loose>;
-declare const agentApiMigrationBeginBodySchema: z.ZodObject<{
-  targetMachineId: z.ZodString;
-  prepDeadlineMs: z.ZodOptional<z.ZodNumber>;
-  transferDeadlineMs: z.ZodOptional<z.ZodNumber>;
-  arrivalDeadlineMs: z.ZodOptional<z.ZodNumber>;
-}, z.core.$loose>;
-declare const agentApiMigrationReadyBodySchema: z.ZodObject<{
-  manifestPath: z.ZodString;
-  manifestSha256: z.ZodOptional<z.ZodString>;
-}, z.core.$loose>;
-declare const agentApiMigrationArrivedBodySchema: z.ZodObject<{
-  reportPath: z.ZodOptional<z.ZodString>;
-  reportSha256: z.ZodOptional<z.ZodString>;
-}, z.core.$loose>;
-declare const agentApiMigrationResponseSchema: z.ZodObject<{
-  migration: z.ZodObject<{
-    id: z.ZodString;
-    agentId: z.ZodString;
-    sourceMachineId: z.ZodString;
-    targetMachineId: z.ZodString;
-    state: z.ZodEnum<{
-      provisioning: "provisioning";
-      prep: "prep";
-      ready: "ready";
-      in_transit: "in_transit";
-      arriving: "arriving";
-      starting: "starting";
-      cancel_requested_pre_flip: "cancel_requested_pre_flip";
-      cancel_requested_post_flip: "cancel_requested_post_flip";
-      canceled_pre_flip: "canceled_pre_flip";
-      canceled_post_flip: "canceled_post_flip";
-      completed: "completed";
-      aborted: "aborted";
-      failed: "failed";
-    }>;
-    manifestPath: z.ZodNullable<z.ZodString>;
-    manifestSha256: z.ZodNullable<z.ZodString>;
-    arrivalReportPath: z.ZodNullable<z.ZodString>;
-    arrivalReportSha256: z.ZodNullable<z.ZodString>;
-    abortReason: z.ZodNullable<z.ZodString>;
-    failureReason: z.ZodNullable<z.ZodString>;
-    prepDeadlineAt: z.ZodString;
-    transferDeadlineAt: z.ZodString;
-    arrivalDeadlineAt: z.ZodString;
-    readyAt: z.ZodNullable<z.ZodString>;
-    flippedAt: z.ZodNullable<z.ZodString>;
-    arrivedAt: z.ZodNullable<z.ZodString>;
-    completedAt: z.ZodNullable<z.ZodString>;
-    abortedAt: z.ZodNullable<z.ZodString>;
-    revision: z.ZodNumber;
-    createdAt: z.ZodString;
-    updatedAt: z.ZodString;
-  }, z.core.$loose>;
-}, z.core.$loose>;
-declare const agentApiMigrationStatusResponseSchema: z.ZodObject<{
-  migration: z.ZodNullable<z.ZodObject<{
-    id: z.ZodString;
-    agentId: z.ZodString;
-    sourceMachineId: z.ZodString;
-    targetMachineId: z.ZodString;
-    state: z.ZodEnum<{
-      provisioning: "provisioning";
-      prep: "prep";
-      ready: "ready";
-      in_transit: "in_transit";
-      arriving: "arriving";
-      starting: "starting";
-      cancel_requested_pre_flip: "cancel_requested_pre_flip";
-      cancel_requested_post_flip: "cancel_requested_post_flip";
-      canceled_pre_flip: "canceled_pre_flip";
-      canceled_post_flip: "canceled_post_flip";
-      completed: "completed";
-      aborted: "aborted";
-      failed: "failed";
-    }>;
-    manifestPath: z.ZodNullable<z.ZodString>;
-    manifestSha256: z.ZodNullable<z.ZodString>;
-    arrivalReportPath: z.ZodNullable<z.ZodString>;
-    arrivalReportSha256: z.ZodNullable<z.ZodString>;
-    abortReason: z.ZodNullable<z.ZodString>;
-    failureReason: z.ZodNullable<z.ZodString>;
-    prepDeadlineAt: z.ZodString;
-    transferDeadlineAt: z.ZodString;
-    arrivalDeadlineAt: z.ZodString;
-    readyAt: z.ZodNullable<z.ZodString>;
-    flippedAt: z.ZodNullable<z.ZodString>;
-    arrivedAt: z.ZodNullable<z.ZodString>;
-    completedAt: z.ZodNullable<z.ZodString>;
-    abortedAt: z.ZodNullable<z.ZodString>;
-    revision: z.ZodNumber;
-    createdAt: z.ZodString;
-    updatedAt: z.ZodString;
-  }, z.core.$loose>>;
-}, z.core.$loose>;
 declare const agentApiPushWebhookRegisterBodySchema: z.ZodObject<{
   url: z.ZodString;
   secret: z.ZodString;
@@ -3231,6 +3151,10 @@ declare const agentApiContract: {
         after: z.ZodOptional<z.ZodString>;
         around: z.ZodOptional<z.ZodString>;
         limit: z.ZodOptional<z.ZodString>;
+        consume: z.ZodOptional<z.ZodEnum<{
+          true: "true";
+          false: "false";
+        }>>;
       }, z.core.$loose>;
     };
     readonly response: {
@@ -6569,247 +6493,6 @@ declare const agentApiContract: {
   } & {
     fullPath: string;
   };
-  readonly migrationBegin: {
-    readonly key: "migrationBegin";
-    readonly method: "POST";
-    readonly path: "/migrations";
-    readonly client: {
-      readonly resource: "migrations";
-      readonly method: "begin";
-    };
-    readonly capability: "server";
-    readonly description: "Begin a migration for the bound agent credential.";
-    readonly request: {
-      readonly body: z.ZodObject<{
-        targetMachineId: z.ZodString;
-        prepDeadlineMs: z.ZodOptional<z.ZodNumber>;
-        transferDeadlineMs: z.ZodOptional<z.ZodNumber>;
-        arrivalDeadlineMs: z.ZodOptional<z.ZodNumber>;
-      }, z.core.$loose>;
-    };
-    readonly response: {
-      readonly body: z.ZodObject<{
-        migration: z.ZodObject<{
-          id: z.ZodString;
-          agentId: z.ZodString;
-          sourceMachineId: z.ZodString;
-          targetMachineId: z.ZodString;
-          state: z.ZodEnum<{
-            provisioning: "provisioning";
-            prep: "prep";
-            ready: "ready";
-            in_transit: "in_transit";
-            arriving: "arriving";
-            starting: "starting";
-            cancel_requested_pre_flip: "cancel_requested_pre_flip";
-            cancel_requested_post_flip: "cancel_requested_post_flip";
-            canceled_pre_flip: "canceled_pre_flip";
-            canceled_post_flip: "canceled_post_flip";
-            completed: "completed";
-            aborted: "aborted";
-            failed: "failed";
-          }>;
-          manifestPath: z.ZodNullable<z.ZodString>;
-          manifestSha256: z.ZodNullable<z.ZodString>;
-          arrivalReportPath: z.ZodNullable<z.ZodString>;
-          arrivalReportSha256: z.ZodNullable<z.ZodString>;
-          abortReason: z.ZodNullable<z.ZodString>;
-          failureReason: z.ZodNullable<z.ZodString>;
-          prepDeadlineAt: z.ZodString;
-          transferDeadlineAt: z.ZodString;
-          arrivalDeadlineAt: z.ZodString;
-          readyAt: z.ZodNullable<z.ZodString>;
-          flippedAt: z.ZodNullable<z.ZodString>;
-          arrivedAt: z.ZodNullable<z.ZodString>;
-          completedAt: z.ZodNullable<z.ZodString>;
-          abortedAt: z.ZodNullable<z.ZodString>;
-          revision: z.ZodNumber;
-          createdAt: z.ZodString;
-          updatedAt: z.ZodString;
-        }, z.core.$loose>;
-      }, z.core.$loose>;
-    };
-  } & {
-    fullPath: string;
-  };
-  readonly migrationStatus: {
-    readonly key: "migrationStatus";
-    readonly method: "GET";
-    readonly path: "/migrations/current";
-    readonly client: {
-      readonly resource: "migrations";
-      readonly method: "status";
-    };
-    readonly capability: "read";
-    readonly description: "Read the active migration for the bound agent credential, if any.";
-    readonly request: {};
-    readonly response: {
-      readonly body: z.ZodObject<{
-        migration: z.ZodNullable<z.ZodObject<{
-          id: z.ZodString;
-          agentId: z.ZodString;
-          sourceMachineId: z.ZodString;
-          targetMachineId: z.ZodString;
-          state: z.ZodEnum<{
-            provisioning: "provisioning";
-            prep: "prep";
-            ready: "ready";
-            in_transit: "in_transit";
-            arriving: "arriving";
-            starting: "starting";
-            cancel_requested_pre_flip: "cancel_requested_pre_flip";
-            cancel_requested_post_flip: "cancel_requested_post_flip";
-            canceled_pre_flip: "canceled_pre_flip";
-            canceled_post_flip: "canceled_post_flip";
-            completed: "completed";
-            aborted: "aborted";
-            failed: "failed";
-          }>;
-          manifestPath: z.ZodNullable<z.ZodString>;
-          manifestSha256: z.ZodNullable<z.ZodString>;
-          arrivalReportPath: z.ZodNullable<z.ZodString>;
-          arrivalReportSha256: z.ZodNullable<z.ZodString>;
-          abortReason: z.ZodNullable<z.ZodString>;
-          failureReason: z.ZodNullable<z.ZodString>;
-          prepDeadlineAt: z.ZodString;
-          transferDeadlineAt: z.ZodString;
-          arrivalDeadlineAt: z.ZodString;
-          readyAt: z.ZodNullable<z.ZodString>;
-          flippedAt: z.ZodNullable<z.ZodString>;
-          arrivedAt: z.ZodNullable<z.ZodString>;
-          completedAt: z.ZodNullable<z.ZodString>;
-          abortedAt: z.ZodNullable<z.ZodString>;
-          revision: z.ZodNumber;
-          createdAt: z.ZodString;
-          updatedAt: z.ZodString;
-        }, z.core.$loose>>;
-      }, z.core.$loose>;
-    };
-  } & {
-    fullPath: string;
-  };
-  readonly migrationReady: {
-    readonly key: "migrationReady";
-    readonly method: "POST";
-    readonly path: "/migrations/ready";
-    readonly client: {
-      readonly resource: "migrations";
-      readonly method: "ready";
-    };
-    readonly capability: "read";
-    readonly description: "Mark the bound agent's active migration prep phase ready.";
-    readonly request: {
-      readonly body: z.ZodObject<{
-        manifestPath: z.ZodString;
-        manifestSha256: z.ZodOptional<z.ZodString>;
-      }, z.core.$loose>;
-    };
-    readonly response: {
-      readonly body: z.ZodObject<{
-        migration: z.ZodObject<{
-          id: z.ZodString;
-          agentId: z.ZodString;
-          sourceMachineId: z.ZodString;
-          targetMachineId: z.ZodString;
-          state: z.ZodEnum<{
-            provisioning: "provisioning";
-            prep: "prep";
-            ready: "ready";
-            in_transit: "in_transit";
-            arriving: "arriving";
-            starting: "starting";
-            cancel_requested_pre_flip: "cancel_requested_pre_flip";
-            cancel_requested_post_flip: "cancel_requested_post_flip";
-            canceled_pre_flip: "canceled_pre_flip";
-            canceled_post_flip: "canceled_post_flip";
-            completed: "completed";
-            aborted: "aborted";
-            failed: "failed";
-          }>;
-          manifestPath: z.ZodNullable<z.ZodString>;
-          manifestSha256: z.ZodNullable<z.ZodString>;
-          arrivalReportPath: z.ZodNullable<z.ZodString>;
-          arrivalReportSha256: z.ZodNullable<z.ZodString>;
-          abortReason: z.ZodNullable<z.ZodString>;
-          failureReason: z.ZodNullable<z.ZodString>;
-          prepDeadlineAt: z.ZodString;
-          transferDeadlineAt: z.ZodString;
-          arrivalDeadlineAt: z.ZodString;
-          readyAt: z.ZodNullable<z.ZodString>;
-          flippedAt: z.ZodNullable<z.ZodString>;
-          arrivedAt: z.ZodNullable<z.ZodString>;
-          completedAt: z.ZodNullable<z.ZodString>;
-          abortedAt: z.ZodNullable<z.ZodString>;
-          revision: z.ZodNumber;
-          createdAt: z.ZodString;
-          updatedAt: z.ZodString;
-        }, z.core.$loose>;
-      }, z.core.$loose>;
-    };
-  } & {
-    fullPath: string;
-  };
-  readonly migrationArrived: {
-    readonly key: "migrationArrived";
-    readonly method: "POST";
-    readonly path: "/migrations/arrived";
-    readonly client: {
-      readonly resource: "migrations";
-      readonly method: "arrived";
-    };
-    readonly capability: "read";
-    readonly description: "Mark the bound agent's active migration arrival phase complete.";
-    readonly request: {
-      readonly body: z.ZodObject<{
-        reportPath: z.ZodOptional<z.ZodString>;
-        reportSha256: z.ZodOptional<z.ZodString>;
-      }, z.core.$loose>;
-    };
-    readonly response: {
-      readonly body: z.ZodObject<{
-        migration: z.ZodObject<{
-          id: z.ZodString;
-          agentId: z.ZodString;
-          sourceMachineId: z.ZodString;
-          targetMachineId: z.ZodString;
-          state: z.ZodEnum<{
-            provisioning: "provisioning";
-            prep: "prep";
-            ready: "ready";
-            in_transit: "in_transit";
-            arriving: "arriving";
-            starting: "starting";
-            cancel_requested_pre_flip: "cancel_requested_pre_flip";
-            cancel_requested_post_flip: "cancel_requested_post_flip";
-            canceled_pre_flip: "canceled_pre_flip";
-            canceled_post_flip: "canceled_post_flip";
-            completed: "completed";
-            aborted: "aborted";
-            failed: "failed";
-          }>;
-          manifestPath: z.ZodNullable<z.ZodString>;
-          manifestSha256: z.ZodNullable<z.ZodString>;
-          arrivalReportPath: z.ZodNullable<z.ZodString>;
-          arrivalReportSha256: z.ZodNullable<z.ZodString>;
-          abortReason: z.ZodNullable<z.ZodString>;
-          failureReason: z.ZodNullable<z.ZodString>;
-          prepDeadlineAt: z.ZodString;
-          transferDeadlineAt: z.ZodString;
-          arrivalDeadlineAt: z.ZodString;
-          readyAt: z.ZodNullable<z.ZodString>;
-          flippedAt: z.ZodNullable<z.ZodString>;
-          arrivedAt: z.ZodNullable<z.ZodString>;
-          completedAt: z.ZodNullable<z.ZodString>;
-          abortedAt: z.ZodNullable<z.ZodString>;
-          revision: z.ZodNumber;
-          createdAt: z.ZodString;
-          updatedAt: z.ZodString;
-        }, z.core.$loose>;
-      }, z.core.$loose>;
-    };
-  } & {
-    fullPath: string;
-  };
   readonly reminderList: {
     readonly key: "reminderList";
     readonly method: "GET";
@@ -8048,8 +7731,8 @@ declare const agentApiContract: {
           pending: "pending";
           canceled: "canceled";
           completed: "completed";
-          failed: "failed";
           verifying: "verifying";
+          failed: "failed";
         }>;
         expiresAt: z.ZodISODateTime;
         attachment: z.ZodNullable<z.ZodObject<{
@@ -8094,8 +7777,8 @@ declare const agentApiContract: {
           pending: "pending";
           canceled: "canceled";
           completed: "completed";
-          failed: "failed";
           verifying: "verifying";
+          failed: "failed";
         }>;
         expiresAt: z.ZodISODateTime;
         attachment: z.ZodNullable<z.ZodObject<{
@@ -8562,11 +8245,6 @@ type AgentApiIntegrationAppStatusResponse = z.infer<typeof agentApiIntegrationAp
 type AgentApiAttachmentCommentsParams = z.infer<typeof agentApiAttachmentCommentsParamsSchema>;
 type AgentApiAttachmentCommentsQuery = z.infer<typeof agentApiAttachmentCommentsQuerySchema>;
 type AgentApiAttachmentCommentsResponse = z.infer<typeof agentApiAttachmentCommentsResponseSchema>;
-type AgentApiMigrationBeginBody = z.infer<typeof agentApiMigrationBeginBodySchema>;
-type AgentApiMigrationReadyBody = z.infer<typeof agentApiMigrationReadyBodySchema>;
-type AgentApiMigrationArrivedBody = z.infer<typeof agentApiMigrationArrivedBodySchema>;
-type AgentApiMigrationResponse = z.infer<typeof agentApiMigrationResponseSchema>;
-type AgentApiMigrationStatusResponse = z.infer<typeof agentApiMigrationStatusResponseSchema>;
 type AgentApiFeedbackLocatorIngestBody = z.infer<typeof agentApiFeedbackLocatorIngestBodySchema>;
 type AgentApiFeedbackLocatorAcceptance = z.infer<typeof agentApiFeedbackLocatorAcceptanceSchema>;
 type AgentApiFeedbackLocatorListQuery = z.infer<typeof agentApiFeedbackLocatorListQuerySchema>;
@@ -8616,10 +8294,6 @@ type AgentApiRequestParamsByRoute = {
   taskConvert: never;
   taskAmend: never;
   taskHistory: never;
-  migrationBegin: never;
-  migrationStatus: never;
-  migrationReady: never;
-  migrationArrived: never;
   reminderList: never;
   reminderCreate: never;
   reminderCancel: AgentApiReminderParams;
@@ -8700,10 +8374,6 @@ type AgentApiRequestQueryByRoute = {
   taskConvert: never;
   taskAmend: never;
   taskHistory: AgentApiTaskHistoryQuery;
-  migrationBegin: never;
-  migrationStatus: never;
-  migrationReady: never;
-  migrationArrived: never;
   reminderList: AgentApiReminderListQuery;
   reminderCreate: never;
   reminderCancel: never;
@@ -8784,10 +8454,6 @@ type AgentApiRequestBodyByRoute = {
   taskConvert: AgentApiTaskConvertBody;
   taskAmend: AgentApiTaskAmendBody;
   taskHistory: never;
-  migrationBegin: AgentApiMigrationBeginBody;
-  migrationStatus: never;
-  migrationReady: AgentApiMigrationReadyBody;
-  migrationArrived: AgentApiMigrationArrivedBody;
   reminderList: never;
   reminderCreate: AgentApiReminderScheduleBody;
   reminderCancel: never;
@@ -8868,10 +8534,6 @@ type AgentApiResponseByRoute = {
   taskConvert: AgentApiTaskConvertResponse;
   taskAmend: AgentApiTaskAmendResponse;
   taskHistory: AgentApiTaskHistoryResponse;
-  migrationBegin: AgentApiMigrationResponse;
-  migrationStatus: AgentApiMigrationStatusResponse;
-  migrationReady: AgentApiMigrationResponse;
-  migrationArrived: AgentApiMigrationResponse;
   reminderList: AgentApiReminderListResponse;
   reminderCreate: AgentApiReminderResponse;
   reminderCancel: AgentApiReminderResponse;
@@ -9448,7 +9110,12 @@ interface Raft {
   messages: {
     /** Read a conversation like `raft message read`; advances the seen frontier by the CLI's rules. */
     read(request: ReadHistoryRequest): Promise<RaftOutcome<RaftHistoryPage, "page" | "empty">>;
-    /** Send, attesting the seen frontier. A freshness hold comes back as `state: "held"` with `resend`. */
+    /**
+     * Send, attesting the seen frontier. A freshness hold comes back as
+     * `state: "interrupted"`: show `interrupt.context` to the model; to go
+     * ahead, send the same request again (the held key is reused, also in
+     * `interrupt.resume.idempotencyKey`); to drop it, don't.
+     */
     send(request: SendMessageRequest): Promise<SendMessageOutcome>;
     /** Reply where a received message came from. */
     reply(message: Pick<RaftMessage, "target">, request: Omit<SendMessageRequest, "target">): Promise<SendMessageOutcome>;
@@ -9508,7 +9175,7 @@ interface Raft {
     } & ManualContext): Promise<RaftOutcome<AgentApiKnowledgeSearchResponse, "results" | "empty">>;
   };
   tasks: {
-    /** Claim before working. Refusals are rows, not exceptions; a hold comes back as `state: "held"` with `retry`. */
+    /** Claim before working. Refusals are rows, not exceptions; a hold comes back as `state: "interrupted"` (resume = the same claim). */
     claim(request: ClaimTasksRequest): Promise<ClaimTasksOutcome>;
     /** A channel's task board, or your own tasks across channels with `mine: true`. */
     list(request: ListTasksRequest): Promise<RaftOutcome<RaftTaskBoard, "board" | "empty">>;
@@ -9520,7 +9187,7 @@ interface Raft {
       assignee: string | null;
       revision: number;
     }, "assigned" | "unassigned">>;
-    /** todo → in_progress → in_review → done; `closed` from anywhere. A hold comes back as `state: "held"` with `data.request`. */
+    /** todo → in_progress → in_review → done; `closed` from anywhere. A hold comes back as `state: "interrupted"` (resume = the same update). */
     updateStatus(request: UpdateTaskStatusRequest): Promise<UpdateTaskStatusOutcome>;
     amend(request: AmendTaskRequest): Promise<AmendTaskOutcome>;
     history(request: TaskRef): Promise<RaftOutcome<AgentApiTaskHistoryResponse & {
@@ -9577,7 +9244,7 @@ interface Raft {
   /** What this process has shown its model, per target; export it to survive restarts. */
   frontier: SeenFrontier;
   state: {
-    /** Save now (for example after `frontier.recordHeld`). Best effort; returns whether it succeeded. */
+    /** Save now (for example after `frontier.recordHeld(interrupt)`). Best effort; returns whether it succeeded. */
     save(): Promise<boolean>;
     /** Load the persisted state now (operations do this automatically). */
     load(): Promise<void>;
@@ -9589,4 +9256,7 @@ interface Raft {
 }
 export declare function createRaft(options: CreateRaftOptions): Raft;
 //#endregion
-export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, CreateTasksRequest, DrainInboxRequest, ExecuteMentionActionRequest, ListInboxRequest, ListTasksRequest, ManualContext, PrepareActionCardRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAttachmentBytes, RaftAttachmentUploaded, RaftAvatarUpload, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftChannelMuteState, RaftChannelRef, RaftClaimHeld, RaftClaimHeldLike, RaftClaimResult, RaftClaimRow, RaftClaimRowState, RaftClient, RaftClientError, RaftClientFailure, RaftClientResult, RaftClientSuccess, RaftClientThrottleOptions, RaftClientTransportRequest, RaftContextAgent, RaftContextData, RaftContextError, RaftContextResult, RaftContextServer, RaftCredentialErrorCode, RaftCredentialIdentity, RaftCredentialStore, RaftEvent, RaftEventAttachment, RaftEventExternalMessage, RaftEventsReceiveData, RaftEventsReceiveError, RaftEventsReceiveRequest, RaftEventsReceiveResult, RaftFailure, RaftHeld, RaftHeldBase, RaftHistoryPage, RaftInboxBatch, RaftInboxCommitResult, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxListing, RaftInboxNotice, RaftLatestReadThread, RaftManageClient, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, RaftOutcome, RaftPendingMentions, RaftPreparedCard, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSearchPage, RaftSendContinuation, RaftSenderType, RaftSent, RaftServerInfo, RaftServerProfile, RaftServerUpdate, RaftState, RaftStateContinuation, RaftStateSaveErrorHandler, RaftStateStore, RaftTaskBoard, RaftTaskStatus, RaftTasksCreated, RaftWebhookStatus, ReactRequest, ReadHistoryRequest, ReadLatestReadThreadOptions, SearchMessagesRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, ServerInfoRequest, ServerInfoSection, StoredRaftCredential, TaskRef, UpdateTaskStatusOutcome, UpdateTaskStatusRequest, UploadAttachmentRequest, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };
+//#region ../shared/src/agentOps/commands/errors.d.ts
+type CommandErrorCode = "MISSING_AGENT_ID" | "MISSING_SERVER_URL" | "MISSING_AGENT_PROXY_URL" | "MULTIPLE_AGENT_PROXY_TOKENS" | "MISSING_AGENT_PROXY_TOKEN" | "MISSING_TOKEN" | "CHECK_FAILED" | "ARCHIVE_FAILED" | "AMEND_FAILED" | "COMMENTS_FAILED" | "CREATE_FAILED" | "RECEIPT_FAILED" | "INBOX_CHECK_FAILED" | "INBOX_UNAVAILABLE" | "ORIGIN_NOT_ALLOWED" | "TOKEN_FILE_UNREADABLE" | "TOKEN_FILE_EMPTY" | "PROFILE_FILE_UNREADABLE" | "PROFILE_FILE_INVALID" | "PROFILE_MANAGED_CONTEXT_CONFLICT" | "MANAGED_WRAPPER_UNAVAILABLE" | "MANAGED_WRAPPER_REQUIRED" | "MANAGED_WRAPPER_FORWARD_FAILED" | "BRIDGE_EXPECTED_AGENT_REQUIRED" | "BRIDGE_IDENTITY_MISMATCH" | "SEND_HELD_AS_DRAFT" | "SEND_HELD" | "GUIDANCE_DELIVERED" | "SEND_DRAFT_NOT_FOUND" | "SEND_DRAFT_EXPIRED" | "SAVED_DRAFT_IDENTITY_CHANGED" | "DRAFT_PENDING" | "THREAD_CONTEXT_TARGET_CONFIRMATION_REQUIRED" | "INVALID_ARG" | "INVALID_SCOPE" | "INVALID_TARGET" | "INVALID_JSON_RESPONSE" | "IDENTITY_MISMATCH" | "PROMPT_UNAVAILABLE" | "WHOAMI_FAILED" | "INFO_FAILED" | "INTEGRATION_SESSION_HANDOFF_FAILED" | "HISTORY_FAILED" | "JOIN_FAILED" | "KNOWLEDGE_GET_FAILED" | "KNOWLEDGE_SEARCH_FAILED" | "KNOWLEDGE_CONTEXT_INVALID" | "LEAVE_FAILED" | "LIST_FAILED" | "MEMBERS_FAILED" | "MUTE_FAILED" | "MENTION_ACTION_FAILED" | "MENTION_DELIVERY_FAILED" | "AMBIGUOUS_ID" | "BRIDGE_ALREADY_RUNNING" | "BRIDGE_WAKE_HINTS_FAILED" | "BRIDGE_WAKE_STREAM_FAILED" | "BRIDGE_WAKE_STREAM_UNAVAILABLE" | "BRIDGE_ACTIVITY_DRAIN_FAILED" | "BRIDGE_ACTIVITY_FORWARD_FAILED" | "BRIDGE_REQUIRES_PROFILE" | "NOT_FOUND" | "PROFILE_SHOW_FAILED" | "READ_FAILED" | "SEARCH_FAILED" | "SCOPE_DENIED" | "QUERY_TOO_BROAD" | "SEARCH_TIMEOUT" | "SEARCH_UNAVAILABLE" | "SERVER_5XX" | "PROXY_5XX" | "UNFOLLOW_FAILED" | "UNARCHIVE_FAILED" | "UNMUTE_FAILED" | "UNCLAIM_FAILED" | "CLAIM_FAILED" | "CLAIM_CONFLICT" | "ASSIGN_FAILED" | "DELETE_FAILED" | "CONVERT_FAILED" | "UPDATE_FAILED" | "VIEW_FAILED" | "VERSION_UNAVAILABLE" | "WAIT_FAILED" | "LOCAL_WRITE_FAILED" | "LOCAL_WRITE_SOURCE_FAILED" | "LOCAL_WRITE_DESTINATION_FAILED" | "LOCAL_WRITE_PARTIAL_FAILED" | "LOCAL_WRITE_POST_COMMIT_FAILED" | "LOCAL_WRITE_SIZE_EXCEEDED" | "INTERNAL_BUG" | "knowledge_agent_missing" | "knowledge_internal_error" | "knowledge_intent_invalid" | "knowledge_language_unsupported" | "knowledge_not_found" | "knowledge_query_invalid" | "knowledge_reason_invalid" | "knowledge_scope_invalid" | "knowledge_source_invalid" | "knowledge_topic_invalid" | "knowledge_trace_id_invalid" | "knowledge_turn_id_invalid" | "unsupported_capability";
+//#endregion
+export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, CommandErrorCode, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, CreateTasksRequest, DrainInboxRequest, ExecuteMentionActionRequest, ListInboxRequest, ListTasksRequest, ManualContext, PrepareActionCardRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAttachmentBytes, RaftAttachmentUploaded, RaftAvatarUpload, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftChannelMuteState, RaftChannelRef, RaftClaimResult, RaftClaimRow, RaftClaimRowState, RaftClient, RaftClientError, RaftClientFailure, RaftClientResult, RaftClientSuccess, RaftClientThrottleOptions, RaftClientTransportRequest, RaftContextAgent, RaftContextData, RaftContextError, RaftContextResult, RaftContextServer, RaftCredentialErrorCode, RaftCredentialIdentity, RaftCredentialStore, RaftEvent, RaftEventAttachment, RaftEventExternalMessage, RaftEventsReceiveData, RaftEventsReceiveError, RaftEventsReceiveRequest, RaftEventsReceiveResult, RaftFailure, RaftHistoryPage, RaftInboxBatch, RaftInboxCommitResult, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxListing, RaftInboxNotice, RaftInterrupt, RaftInterruptCancel, RaftInterruptReason, RaftInterruptResume, RaftInterrupted, RaftLatestReadThread, RaftManageClient, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, RaftOutcome, RaftPendingMentions, RaftPreparedCard, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSearchPage, RaftSenderType, RaftSent, RaftServerInfo, RaftServerProfile, RaftServerUpdate, RaftState, RaftStateContinuation, RaftStateSaveErrorHandler, RaftStateStore, RaftTaskBoard, RaftTaskStatus, RaftTasksCreated, RaftWebhookStatus, ReactRequest, ReadHistoryRequest, ReadLatestReadThreadOptions, SearchMessagesRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, ServerInfoRequest, ServerInfoSection, StoredRaftCredential, TaskRef, UpdateTaskStatusOutcome, UpdateTaskStatusRequest, UploadAttachmentRequest, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };