@cadraos/sdk 0.3.8 → 0.3.10

package/dist/kanban/engine/index.cjs

@@ -12,6 +12,10 @@ function mapHandler(h) {
     type: h.type,
     agentUuid: h.agent_uuid,
     teamUuid: h.team_uuid,
+    // FINDING-6: carry the remote_agent binding through the wire parse. The
+    // engine's remote_agent dispatch reads `remoteAgentUuid`; dropping it here
+    // made every published remote_agent lane dispatch-dead.
+    remoteAgentUuid: h.remote_agent_uuid,
     agentRef: h.agent_ref,
     webhook: h.webhook ? {
       url: h.webhook.url,
@@ -321,6 +325,8 @@ async function dispatchStageHandler(ctx, cadra, webhookOpts) {
         orgId: ctx.orgId,
         input: ctx.input,
         idemKey: runIdemKey,
+        // Board/headless dispatch always disables ask_user (spec §6.5 / FINDING-5).
+        allowAskUser: false,
         callbackRef: ctx.callbackUrl
       });
       return { dispatched: true, executionUuid };
@@ -334,6 +340,8 @@ async function dispatchStageHandler(ctx, cadra, webhookOpts) {
         orgId: ctx.orgId,
         input: ctx.input,
         idemKey: runIdemKey,
+        // Board/headless dispatch always disables ask_user (spec §6.5 / FINDING-5).
+        allowAskUser: false,
         callbackRef: ctx.callbackUrl
       });
       return { dispatched: true, executionUuid };
@@ -384,10 +392,25 @@ function nextId(prefix) {
   idSeq += 1;
   return `${prefix}-${idSeq}`;
 }
+var DEFAULT_STALE_QUEUED_MS = 15 * 6e4;
 var InMemoryStorageAdapter = class {
   cards = /* @__PURE__ */ new Map();
   logs = /* @__PURE__ */ new Map();
   runs = /* @__PURE__ */ new Map();
+  /**
+   * A `queued` stage-run older than this (ms) is STALE and re-claimable by
+   * `beginStageRun` (design §10) — it models a run whose process died between
+   * `beginStageRun` and dispatch, so `failStageRun` never ran. A `failed` run is
+   * re-claimable regardless of age. Must comfortably exceed the dispatch time so
+   * a genuinely in-flight `queued` run is never re-claimed out from under it.
+   */
+  staleQueuedMs;
+  /** Injectable clock (ms) — real hosts use `Date.now`; tests pin it. */
+  now;
+  constructor(opts) {
+    this.staleQueuedMs = opts?.staleQueuedMs ?? DEFAULT_STALE_QUEUED_MS;
+    this.now = opts?.now ?? (() => Date.now());
+  }
   // ----- Cards -----
   async listCards(boardConfigUuid) {
     return [...this.cards.values()].filter((c) => c.boardConfigUuid === boardConfigUuid).map((c) => this.publicCard(c));
@@ -487,18 +510,48 @@ var InMemoryStorageAdapter = class {
   // ----- Stage runs -----
   async beginStageRun(cardId, r) {
     const existing = this.runs.get(r.idemKey);
-    if (existing) return { created: false, run: { ...existing } };
+    if (existing) {
+      if (this.isReclaimable(existing)) {
+        const run2 = {
+          idemKey: r.idemKey,
+          cardId,
+          stageId: r.stageId,
+          handlerType: r.handlerType,
+          status: "queued",
+          attempts: (existing.attempts ?? 1) + 1,
+          createdAt: new Date(this.now()).toISOString()
+        };
+        this.runs.set(r.idemKey, run2);
+        return { created: true, run: { ...run2 } };
+      }
+      return { created: false, run: { ...existing } };
+    }
     const run = {
       idemKey: r.idemKey,
       cardId,
       stageId: r.stageId,
       handlerType: r.handlerType,
       status: "queued",
-      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      attempts: 1,
+      createdAt: new Date(this.now()).toISOString()
     };
     this.runs.set(r.idemKey, run);
     return { created: true, run: { ...run } };
   }
+  /**
+   * A stranded stage-run the next `beginStageRun` may re-claim (design §10): a
+   * `failed` run (dispatch threw), or a `queued` run older than `staleQueuedMs`
+   * (a process died before dispatch flipped it). `running`/`completed` runs are
+   * never re-claimed.
+   */
+  isReclaimable(run) {
+    if (run.status === "failed") return true;
+    if (run.status === "queued") {
+      const age = this.now() - Date.parse(run.createdAt);
+      return Number.isFinite(age) && age >= this.staleQueuedMs;
+    }
+    return false;
+  }
   async completeStageRun(idemKey, c) {
     const run = this.runs.get(idemKey);
     if (!run) throw new Error(`No stage run for idemKey ${idemKey}`);
@@ -1193,6 +1246,14 @@ function runAdapterConformance(makeAdapter, runner) {
       expect(still.lane).toBe("generate");
     });
     const asConductor = (adapter) => adapter.listDueCards && adapter.countsByLane && adapter.capabilities ? adapter : null;
+    const supportsField = (adapter, field) => {
+      const fields = adapter.capabilities().dueRuleFields;
+      return fields.includes("*") || fields.includes(field);
+    };
+    const supportsPredicate = (adapter, ref) => {
+      const preds = adapter.capabilities().dueRulePredicates;
+      return preds.includes("*") || preds.includes(ref);
+    };
     it("listDueCards {kind:'always'} returns every card in the lane", async () => {
       const base = await makeAdapter();
       const adapter = asConductor(base);
@@ -1224,6 +1285,7 @@ function runAdapterConformance(makeAdapter, runner) {
       const base = await makeAdapter();
       const adapter = asConductor(base);
       if (!adapter) return;
+      if (!supportsField(adapter, "next_touch_at")) return;
       const past = new Date(Date.now() - 6e4).toISOString();
       const future = new Date(Date.now() + 6e4).toISOString();
       await seedCard(adapter, "scheduled", "due", { next_touch_at: past });
@@ -1245,6 +1307,7 @@ function runAdapterConformance(makeAdapter, runner) {
       const base = await makeAdapter();
       const adapter = asConductor(base);
       if (!adapter) return;
+      if (!supportsPredicate(adapter, "status")) return;
       await seedCard(adapter, "queued", "approved", { status: "approved" });
       await seedCard(adapter, "queued", "draft", { status: "draft" });
       const rule = {
@@ -1261,6 +1324,8 @@ function runAdapterConformance(makeAdapter, runner) {
       const base = await makeAdapter();
       const adapter = asConductor(base);
       if (!adapter) return;
+      if (!supportsField(adapter, "next_touch_at") || !supportsPredicate(adapter, "status"))
+        return;
       const past = new Date(Date.now() - 6e4).toISOString();
       const future = new Date(Date.now() + 6e4).toISOString();
       await seedCard(adapter, "queued", "send-me", {
@@ -1523,20 +1588,28 @@ function createEngine(options) {
     if (!begin.created) {
       return { dispatched: false, executionUuid: begin.run.executionUuid };
     }
-    const result = await dispatchStageHandler(
-      {
-        cardId,
-        boardConfigUuid: card.boardId,
-        configVersion: cfg.version,
-        stage,
-        idemKey,
-        input: cardContext(card, stage),
-        orgId: options.orgId,
-        callbackUrl
-      },
-      cadraClient,
-      webhookOptions
-    );
+    let result;
+    try {
+      result = await dispatchStageHandler(
+        {
+          cardId,
+          boardConfigUuid: card.boardId,
+          configVersion: cfg.version,
+          stage,
+          idemKey,
+          input: cardContext(card, stage),
+          orgId: options.orgId,
+          callbackUrl
+        },
+        cadraClient,
+        webhookOptions
+      );
+    } catch (err) {
+      await adapter.failStageRun(idemKey, {
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
+    }
     if (result.executionUuid && adapter.markStageRunDispatched) {
       await adapter.markStageRunDispatched(idemKey, {
         executionUuid: result.executionUuid
@@ -1605,21 +1678,30 @@ function createEngine(options) {
     }));
     batchMembers.set(batchKey, batchCards.map((c) => c.idemKey));
     const lead = eligible[0].card;
-    const result = await dispatchStageHandler(
-      {
-        cardId: lead.id,
-        boardConfigUuid: lead.boardId,
-        configVersion: cfg.version,
-        stage,
-        idemKey: eligible[0].idemKey,
-        input: batchContext(lead, stage, batchCards),
-        orgId: options.orgId,
-        callbackUrl,
-        batch: { batchKey, cards: batchCards }
-      },
-      cadraClient,
-      webhookOptions
-    );
+    let result;
+    try {
+      result = await dispatchStageHandler(
+        {
+          cardId: lead.id,
+          boardConfigUuid: lead.boardId,
+          configVersion: cfg.version,
+          stage,
+          idemKey: eligible[0].idemKey,
+          input: batchContext(lead, stage, batchCards),
+          orgId: options.orgId,
+          callbackUrl,
+          batch: { batchKey, cards: batchCards }
+        },
+        cadraClient,
+        webhookOptions
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      for (const { idemKey } of eligible) {
+        await adapter.failStageRun(idemKey, { error: msg });
+      }
+      throw err;
+    }
     if (result.executionUuid && adapter.markStageRunDispatched) {
       for (const { idemKey } of eligible) {
         await adapter.markStageRunDispatched(idemKey, {