@cadraos/sdk 0.3.12 → 0.3.14-p102.1

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

@@ -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.
  *
@@ -539,6 +549,11 @@ interface KanbanCard {
     configVersion?: number;
     /** Arbitrary shared context carried across transitions. */
     sharedContext?: Record<string, unknown>;
+    /**
+     * p46 (P46-002): the card's id in an external host (a Jira issue key).
+     * Absent on native / crm / yobo cards.
+     */
+    externalRef?: string;
     /**
      * Execution UUID of the card's current/last run, if any.
      *
@@ -601,6 +616,18 @@ interface CreateCardInput {
      * in the lifecycle's initial lane.
      */
     lane?: string;
+    /**
+     * p46 (P46-002): the card's id in an EXTERNAL host (a Jira issue key, e.g.
+     * `CAD-231`). Optional. When set, a card is created at most ONCE per
+     * `(boardConfigUuid, externalRef)`: a repeat create returns the existing card
+     * and dispatches nothing. Hosts that don't store it simply ignore it.
+     */
+    externalRef?: string;
+    /**
+     * p46 (P46-002): opaque host facts stored with the card (Jira `statusId`,
+     * `mover`, `detached`, …). Passed through to `adapter.createCard` untouched.
+     */
+    externalMeta?: Record<string, unknown>;
 }
 /**
  * Who performed a transition / stage-run (server-engine side).
@@ -718,7 +745,125 @@ interface ApplyTransitionInput {
     contextPatch?: Record<string, unknown>;
     /** Execution UUID to stamp on the card (handler advances). */
     executionUuid?: string;
+    /**
+     * p46 (P46-002, F8): set ONLY by `engine.hostMove` (a move the external host
+     * made — e.g. a Jira drag mirrored by the sync). A host-aware adapter, inside
+     * the same card lock as the `fromLane` CAS, (1) refuses the move with a
+     * `HostFenceError` while the card has any `host.*` op `pending` (D19 — never
+     * mistake our own half-done move for a human one), (2) writes `externalMeta`,
+     * then (3) moves. Adapters that don't know it ignore it (optional, additive).
+     */
+    hostObservation?: {
+        externalMeta?: Record<string, unknown>;
+        /**
+         * ISO time the host state was READ. The fence also refuses the move when a
+         * `host.*` op for the card settled (done/failed) after this instant — the
+         * read may predate our own write landing in the host.
+         */
+        observedAt?: 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.
@@ -801,6 +946,16 @@ interface KanbanStorageAdapter {
      * config and passes it as `initialLane`.
      */
     createCard(input: CreateCardServerInput): Promise<KanbanCard>;
+    /**
+     * p46 (P46-002) OPTIONAL: the card with this `externalRef` on this board, or
+     * null. When present, `engine.createCard({externalRef})` looks it up first and
+     * returns an existing card WITHOUT dispatching (exactly-once create per issue
+     * key). A host that stores `externalRef` SHOULD also make `createCard` itself
+     * idempotent on `(boardConfigUuid, externalRef)` (unique index + `ON CONFLICT
+     * DO NOTHING` → return the existing row) for the lookup/insert race. Hosts
+     * without external refs (crm/yobo) omit it.
+     */
+    getCardByExternalRef?(boardConfigUuid: string, externalRef: string): Promise<KanbanCard | null>;
     /**
      * Patch a card's mutable fields.
      */
@@ -917,7 +1072,7 @@ interface KanbanStorageAdapter {
         toLane?: string;
         contextPatch?: Record<string, unknown>;
         actor: Actor;
-    }): Promise<{
+    } & StageRunLedgerWrite): Promise<{
         applied: boolean;
     }>;
     /**
@@ -930,7 +1085,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 +1099,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 +1632,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/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.
  *
@@ -539,6 +549,11 @@ interface KanbanCard {
     configVersion?: number;
     /** Arbitrary shared context carried across transitions. */
     sharedContext?: Record<string, unknown>;
+    /**
+     * p46 (P46-002): the card's id in an external host (a Jira issue key).
+     * Absent on native / crm / yobo cards.
+     */
+    externalRef?: string;
     /**
      * Execution UUID of the card's current/last run, if any.
      *
@@ -601,6 +616,18 @@ interface CreateCardInput {
      * in the lifecycle's initial lane.
      */
     lane?: string;
+    /**
+     * p46 (P46-002): the card's id in an EXTERNAL host (a Jira issue key, e.g.
+     * `CAD-231`). Optional. When set, a card is created at most ONCE per
+     * `(boardConfigUuid, externalRef)`: a repeat create returns the existing card
+     * and dispatches nothing. Hosts that don't store it simply ignore it.
+     */
+    externalRef?: string;
+    /**
+     * p46 (P46-002): opaque host facts stored with the card (Jira `statusId`,
+     * `mover`, `detached`, …). Passed through to `adapter.createCard` untouched.
+     */
+    externalMeta?: Record<string, unknown>;
 }
 /**
  * Who performed a transition / stage-run (server-engine side).
@@ -718,7 +745,125 @@ interface ApplyTransitionInput {
     contextPatch?: Record<string, unknown>;
     /** Execution UUID to stamp on the card (handler advances). */
     executionUuid?: string;
+    /**
+     * p46 (P46-002, F8): set ONLY by `engine.hostMove` (a move the external host
+     * made — e.g. a Jira drag mirrored by the sync). A host-aware adapter, inside
+     * the same card lock as the `fromLane` CAS, (1) refuses the move with a
+     * `HostFenceError` while the card has any `host.*` op `pending` (D19 — never
+     * mistake our own half-done move for a human one), (2) writes `externalMeta`,
+     * then (3) moves. Adapters that don't know it ignore it (optional, additive).
+     */
+    hostObservation?: {
+        externalMeta?: Record<string, unknown>;
+        /**
+         * ISO time the host state was READ. The fence also refuses the move when a
+         * `host.*` op for the card settled (done/failed) after this instant — the
+         * read may predate our own write landing in the host.
+         */
+        observedAt?: 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.
@@ -801,6 +946,16 @@ interface KanbanStorageAdapter {
      * config and passes it as `initialLane`.
      */
     createCard(input: CreateCardServerInput): Promise<KanbanCard>;
+    /**
+     * p46 (P46-002) OPTIONAL: the card with this `externalRef` on this board, or
+     * null. When present, `engine.createCard({externalRef})` looks it up first and
+     * returns an existing card WITHOUT dispatching (exactly-once create per issue
+     * key). A host that stores `externalRef` SHOULD also make `createCard` itself
+     * idempotent on `(boardConfigUuid, externalRef)` (unique index + `ON CONFLICT
+     * DO NOTHING` → return the existing row) for the lookup/insert race. Hosts
+     * without external refs (crm/yobo) omit it.
+     */
+    getCardByExternalRef?(boardConfigUuid: string, externalRef: string): Promise<KanbanCard | null>;
     /**
      * Patch a card's mutable fields.
      */
@@ -917,7 +1072,7 @@ interface KanbanStorageAdapter {
         toLane?: string;
         contextPatch?: Record<string, unknown>;
         actor: Actor;
-    }): Promise<{
+    } & StageRunLedgerWrite): Promise<{
         applied: boolean;
     }>;
     /**
@@ -930,7 +1085,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 +1099,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 +1632,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`