@cadraos/sdk 0.3.13 → 0.3.14-p46.0

package/dist/board-host/server/index.d.ts

@@ -443,7 +443,17 @@ interface KanbanLane {
      * a tick fans out ⌈cap / chunkSize⌉ runs. Ignored for `per-card`/`event` lanes.
      */
     chunkSize?: number;
+    /**
+     * p46 Handoff contract, OPT-IN per lane (D1). Absent ⇒ `off` (existing boards
+     * are byte-identical). `verdict` ⇒ the engine sends
+     * `HANDOFF_VERDICT_JSON_SCHEMA` as the run's `context.outputSchema` and a
+     * completion MUST carry a valid verdict (else the run fails with a FAILED
+     * handoff). Active only on hosts whose adapter implements the ledger group.
+     */
+    handoff?: KanbanLaneHandoffMode;
 }
+/** Per-lane Handoff mode (p46 D1). */
+type KanbanLaneHandoffMode = "off" | "verdict";
 /**
  * A declared edge between two lanes in the lifecycle.
  *
@@ -720,6 +730,107 @@ interface ApplyTransitionInput {
     executionUuid?: string;
 }
 
+/**
+ * Handoff v1 — the one AI↔human contract every board lane speaks (p46 §0.3).
+ *
+ * A Handoff is the record written whenever work crosses between an agent and a
+ * person on a card: an agent's verdict ("decide A/B/C", "approve", "test this"),
+ * an engine-written FAILED / BLOCKED, or the human's answer carried forward to
+ * the next agent (`human_to_ai`). Every worker type produces the same object and
+ * every host reads it.
+ *
+ * This module is DEPENDENCY-FREE and client-safe (types, the verdict JSON
+ * schema, the prompt renderer, the link guard). The ajv-backed verdict PARSER
+ * lives in `./handoff-parse.ts` and is exported only from the server engine
+ * entry (`@cadraos/sdk/kanban/engine`), so the browser bundle never carries ajv.
+ *
+ * @module @cadraos/sdk/kanban
+ */
+type HandoffKind = "DECIDE" | "APPROVE" | "TEST" | "REVIEW" | "FAILED" | "BLOCKED" | "FYI";
+interface HandoffOption {
+    /** Single capital letter, `^[A-Z]$`. */
+    id: string;
+    /** ≤80 chars. */
+    label: string;
+    /** ≤300 chars. */
+    consequence: string;
+}
+interface HandoffDecision {
+    /** ≤500 chars. */
+    question: string;
+    /** 2–4 options. */
+    options: HandoffOption[];
+    /** ∈ options[].id */
+    recommended: string;
+    /** ∈ options[].id */
+    defaultIfSilent?: string;
+}
+interface HandoffState {
+    repos: string[];
+    tests: string | null;
+    story: string | null;
+    costUsd: number | null;
+}
+interface HandoffAnswer {
+    option: string | null;
+    /** ≤4000 chars. */
+    text: string | null;
+    by: string;
+    at: string;
+    via: "board" | "channel";
+    source: string;
+}
+interface HandoffV1 {
+    v: 1;
+    /** = agentic_handoff.uuid */
+    id: string;
+    /** Card uuid. */
+    cardId: string;
+    direction: "ai_to_human" | "human_to_ai";
+    /** Lane KEYS. */
+    fromLane: string;
+    toLane: string;
+    /** ISO-8601. */
+    at: string;
+    by: {
+        type: "session" | "user" | "watchdog" | "timeout" | "health";
+        id: string;
+    };
+    kind: HandoffKind;
+    /** ≤200 chars. */
+    headline: string;
+    /** ≤20 × ≤300 chars. */
+    done: string[];
+    state: HandoffState;
+    decision?: HandoffDecision;
+    /** ≤300 chars. */
+    howToAnswer: string;
+    /** ≤10; url must be http(s): or a same-origin path starting "/". */
+    links: {
+        label: string;
+        url: string;
+    }[];
+    session: {
+        id: string | null;
+        runnerId: string | null;
+        resumableUntil: string | null;
+    };
+    /** BLOCKED only. */
+    blocked?: {
+        check: string;
+        reason: string;
+        fixUrl: string;
+    };
+    answer?: HandoffAnswer;
+}
+/** Ledger lifecycle of a stored handoff. */
+type HandoffStatus = "open" | "answered" | "resolved" | "consumed";
+/** A stored handoff: the v1 payload plus its ledger status. */
+type HandoffRecord = HandoffV1 & {
+    status: HandoffStatus;
+    consumedAt: string | null;
+};
+
 /**
  * KanbanStorageAdapter — the SERVER-ENGINE persistence contract.
  *
@@ -917,7 +1028,7 @@ interface KanbanStorageAdapter {
         toLane?: string;
         contextPatch?: Record<string, unknown>;
         actor: Actor;
-    }): Promise<{
+    } & StageRunLedgerWrite): Promise<{
         applied: boolean;
     }>;
     /**
@@ -930,7 +1041,7 @@ interface KanbanStorageAdapter {
      */
     failStageRun(idemKey: string, f: {
         error: string;
-    }): Promise<void>;
+    } & StageRunLedgerWrite): Promise<void>;
     /**
      * OPTIONAL: record that a stage run was dispatched — set status `running`
      * and stamp the `executionUuid` (so the UI can stream the live run before
@@ -944,6 +1055,65 @@ interface KanbanStorageAdapter {
      * Read a stage run by its idempotency key, or null if none.
      */
     getStageRun(idemKey: string): Promise<StageRun | null>;
+    /** OPTIONAL (ledger): insert a handoff (adapter assigns `id`), or read the existing one on conflict. */
+    appendHandoff?(h: {
+        card: KanbanCard;
+        stageId: string;
+        configVersion: number;
+        idemKey?: string;
+        attempt?: number;
+        dedupeKey?: string;
+        payload: Omit<HandoffV1, "id">;
+    }): Promise<{
+        created: boolean;
+        handoff: HandoffV1;
+    }>;
+    /** OPTIONAL (ledger): a card's handoffs, NEWEST FIRST. */
+    listHandoffs?(cardId: string, opts?: {
+        limit?: number;
+    }): Promise<HandoffRecord[]>;
+    /** OPTIONAL (ledger): CAS `open → answered` (ai_to_human, kind ∈ DECIDE|APPROVE|TEST|REVIEW). */
+    answerHandoff?(cardId: string, handoffId: string, answer: NonNullable<HandoffV1["answer"]>, userId?: number): Promise<{
+        applied: boolean;
+    }>;
+    /** OPTIONAL (ledger): CAS `open → resolved` (BLOCKED / FAILED). */
+    resolveHandoff?(handoffId: string): Promise<{
+        applied: boolean;
+    }>;
+    /** OPTIONAL (ledger): `human_to_ai` rows `open → consumed` by the dispatch `idemKey`. */
+    consumeHandoffs?(ids: string[], idemKey: string): Promise<void>;
+    /** OPTIONAL (outbox): insert-or-read an op; `run: false` iff it is already `done`. */
+    claimOp?(op: {
+        opId: string;
+        kind: string;
+        cardId?: string;
+        handoffId?: string;
+        payload: unknown;
+    }): Promise<{
+        run: boolean;
+    }>;
+    /** OPTIONAL (outbox): mark an op `done`. */
+    completeOp?(opId: string): Promise<void>;
+    /** OPTIONAL (outbox): mark an op `failed` with its error (replayable). */
+    failOp?(opId: string, error: string): Promise<void>;
+}
+/**
+ * The optional ledger write carried on `completeStageRun` / `failStageRun`
+ * (p46 F3). Ignored by adapters without the ledger group.
+ *
+ * When present, the adapter writes — INSIDE THE SAME TRANSACTION as the run /
+ * card update — the `agentic_handoff` row (using `payload.id` as its uuid;
+ * `ON CONFLICT (dedupe_key) DO NOTHING`) and, only when that row was newly
+ * inserted, a `pending` op row with id `notifyOpId`. If the run update is a
+ * no-op (`completeStageRun` on an already-completed run; `failStageRun` on a
+ * completed run) nothing is written. A throw anywhere rolls ALL of it back.
+ */
+interface StageRunLedgerWrite {
+    handoff?: {
+        payload: HandoffV1;
+        dedupeKey: string;
+    };
+    notifyOpId?: string;
 }
 
 /**
@@ -1418,6 +1588,8 @@ interface WireStage {
      */
     dispatch?: KanbanLaneDispatch;
     chunk_size?: number | null;
+    /** p46 Handoff mode (D1). Absent ⇒ `off`. Mapped to `KanbanLane.handoff`. */
+    handoff?: "off" | "verdict" | null;
 }
 /**
  * A resolved board config: stable uuid + version + the mapped `KanbanBoard`

package/dist/chat/index.d.cts

@@ -3724,7 +3724,17 @@ interface KanbanLane {
      * a tick fans out ⌈cap / chunkSize⌉ runs. Ignored for `per-card`/`event` lanes.
      */
     chunkSize?: number;
+    /**
+     * p46 Handoff contract, OPT-IN per lane (D1). Absent ⇒ `off` (existing boards
+     * are byte-identical). `verdict` ⇒ the engine sends
+     * `HANDOFF_VERDICT_JSON_SCHEMA` as the run's `context.outputSchema` and a
+     * completion MUST carry a valid verdict (else the run fails with a FAILED
+     * handoff). Active only on hosts whose adapter implements the ledger group.
+     */
+    handoff?: KanbanLaneHandoffMode;
 }
+/** Per-lane Handoff mode (p46 D1). */
+type KanbanLaneHandoffMode = "off" | "verdict";
 /**
  * A declared edge between two lanes in the lifecycle.
  *

package/dist/chat/index.d.ts

@@ -3724,7 +3724,17 @@ interface KanbanLane {
      * a tick fans out ⌈cap / chunkSize⌉ runs. Ignored for `per-card`/`event` lanes.
      */
     chunkSize?: number;
+    /**
+     * p46 Handoff contract, OPT-IN per lane (D1). Absent ⇒ `off` (existing boards
+     * are byte-identical). `verdict` ⇒ the engine sends
+     * `HANDOFF_VERDICT_JSON_SCHEMA` as the run's `context.outputSchema` and a
+     * completion MUST carry a valid verdict (else the run fails with a FAILED
+     * handoff). Active only on hosts whose adapter implements the ledger group.
+     */
+    handoff?: KanbanLaneHandoffMode;
 }
+/** Per-lane Handoff mode (p46 D1). */
+type KanbanLaneHandoffMode = "off" | "verdict";
 /**
  * A declared edge between two lanes in the lifecycle.
  *

package/dist/index.d.cts

@@ -2795,7 +2795,17 @@ interface KanbanLane {
      * a tick fans out ⌈cap / chunkSize⌉ runs. Ignored for `per-card`/`event` lanes.
      */
     chunkSize?: number;
+    /**
+     * p46 Handoff contract, OPT-IN per lane (D1). Absent ⇒ `off` (existing boards
+     * are byte-identical). `verdict` ⇒ the engine sends
+     * `HANDOFF_VERDICT_JSON_SCHEMA` as the run's `context.outputSchema` and a
+     * completion MUST carry a valid verdict (else the run fails with a FAILED
+     * handoff). Active only on hosts whose adapter implements the ledger group.
+     */
+    handoff?: KanbanLaneHandoffMode;
 }
+/** Per-lane Handoff mode (p46 D1). */
+type KanbanLaneHandoffMode = "off" | "verdict";
 /**
  * A declared edge between two lanes in the lifecycle.
  *

package/dist/index.d.ts

@@ -2795,7 +2795,17 @@ interface KanbanLane {
      * a tick fans out ⌈cap / chunkSize⌉ runs. Ignored for `per-card`/`event` lanes.
      */
     chunkSize?: number;
+    /**
+     * p46 Handoff contract, OPT-IN per lane (D1). Absent ⇒ `off` (existing boards
+     * are byte-identical). `verdict` ⇒ the engine sends
+     * `HANDOFF_VERDICT_JSON_SCHEMA` as the run's `context.outputSchema` and a
+     * completion MUST carry a valid verdict (else the run fails with a FAILED
+     * handoff). Active only on hosts whose adapter implements the ledger group.
+     */
+    handoff?: KanbanLaneHandoffMode;
 }
+/** Per-lane Handoff mode (p46 D1). */
+type KanbanLaneHandoffMode = "off" | "verdict";
 /**
  * A declared edge between two lanes in the lifecycle.
  *