@cabane/companion 0.6.87 → 0.6.88

package/dist/cli.js

@@ -2647,6 +2647,35 @@ var CabaneApi = class {
       signal
     );
   }
+  // CT1357: post ONE ordinary addressed message — not turn speech, no `turnId`
+  // — so `dispatch` is honoured and the target agent is woken. The turn-commit
+  // fork ignores `dispatch` (an act rides its own call now), which leaves this
+  // as the only way a companion can address a peer OUTSIDE a running turn.
+  //
+  // The prepare-failure handback is exactly that case and the reason this
+  // exists. It fires before the turn is ever admitted — the active-run PATCH
+  // that admits it comes after the prepare hook — so `turnAct` is not available:
+  // its route resolves the turn first and 404s when there is none. The failure
+  // notice's own commit is what admits the turn, and by then it has also settled
+  // it. An ordinary addressed post depends on no lease at all, which is what
+  // makes it the right shape here.
+  //
+  // Retried like any durable write, and therefore REQUIRING `idempotencyKey`:
+  // this is not outbox-queued (there is no `(turnId, seq)` for a non-turn row),
+  // so without a key a committed request whose response was lost — or a
+  // redelivered dispatch event — writes a second row and wakes the peer twice.
+  // The server dedupes on `(conversation_id, idempotency_key)`: the repeat
+  // returns the existing row and raises no second dispatch (CT239). Required,
+  // not optional, so a future caller cannot omit it and silently lose the
+  // guarantee.
+  postAddressedMessage(workspaceId, conversationId, body, signal) {
+    return this.request(
+      "POST",
+      `/api/workspaces/${workspaceId}/conversations/${conversationId}/messages`,
+      body,
+      signal ? { retry: true, signal } : { retry: true }
+    );
+  }
   // SJ477: report one tool-activity transition (start / done / error) for the
   // live activity cards. Transient — the server publishes an `agent_activity`
   // SSE and writes no row. Agent-PAT authed; the URL `:agentId` must match the
@@ -8617,12 +8646,31 @@ var TurnExecution = class {
     }
     let hookEnv;
     const triggerIsPrepareFailure = this.turnContext.message.body.startsWith(PREPARE_FAILED_PREFIX);
-    const prepareFailureDispatch = this.turnContext.dispatchedByAgentId && !triggerIsPrepareFailure ? {
-      dispatch: this.turnContext.dispatchedByAgentId,
-      dispatchBody: `${PREPARE_FAILED_PREFIX}
+    const sendPrepareFailureHandback = async () => {
+      if (!this.turnContext.dispatchedByAgentId || triggerIsPrepareFailure) return;
+      try {
+        await this.opts.api.postAddressedMessage(workspaceId, payload.conversationId, {
+          body: `${PREPARE_FAILED_PREFIX}
 
-The dispatched turn could not start. Re-dispatch it after repairing the preparation failure shown in this conversation.`
-    } : {};
+The dispatched turn could not start. Re-dispatch it after repairing the preparation failure shown in this conversation.`,
+          dispatch: this.turnContext.dispatchedByAgentId,
+          // Keyed on the TRIGGER, not the turn: a redelivered dispatch event is
+          // the replay this has to survive, and it mints a fresh `turnId` while
+          // carrying the same `messageId`. One handback per failed pickup of a
+          // given trigger — which is also CT992's rule, that the first failure
+          // is the one carrying information. A genuine re-dispatch after a
+          // repair authors a NEW trigger message, so it keys differently and
+          // hands back again.
+          idempotencyKey: `prepare-failure-handback:${payload.messageId}`,
+          parentMessageId: payload.messageId
+        });
+      } catch (err) {
+        turnLog.warn(
+          { err: err instanceof Error ? err.message : String(err) },
+          "dispatcher: prepare-failure handback failed"
+        );
+      }
+    };
     if (prepareHook) {
       let cached2 = readPrepared(workspaceId, payload.conversationId, payload.agentId);
       if (cached2 && !checkoutState(cached2.cwd).ok) {
@@ -8661,8 +8709,7 @@ The dispatched turn could not start. Re-dispatch it after repairing the preparat
 ${reason}`,
                 kind: "final",
                 turnId,
-                parentMessageId: payload.messageId,
-                ...prepareFailureDispatch
+                parentMessageId: payload.messageId
               });
             } catch (postErr) {
               turnLog.warn(
@@ -8670,6 +8717,7 @@ ${reason}`,
                 "dispatcher: prepare-rejection post failed"
               );
             }
+            await sendPrepareFailureHandback();
             throw this.concluded(`prepare_failed: ${reason}`);
           }
         }
@@ -8737,8 +8785,7 @@ ${reason}`,
               kind: "final",
               turnId,
               // CT113: stamp the parent even on the prepare-failed close.
-              parentMessageId: payload.messageId,
-              ...prepareFailureDispatch
+              parentMessageId: payload.messageId
             });
           } catch (postErr) {
             turnLog.warn(
@@ -8746,6 +8793,7 @@ ${reason}`,
               "dispatcher: prepare-failure post failed"
             );
           }
+          await sendPrepareFailureHandback();
           const failReason = `prepare_failed: ${reason}`;
           throw this.concluded(failReason);
         }

package/dist/runtime.js

@@ -2065,6 +2065,35 @@ var CabaneApi = class {
       signal
     );
   }
+  // CT1357: post ONE ordinary addressed message — not turn speech, no `turnId`
+  // — so `dispatch` is honoured and the target agent is woken. The turn-commit
+  // fork ignores `dispatch` (an act rides its own call now), which leaves this
+  // as the only way a companion can address a peer OUTSIDE a running turn.
+  //
+  // The prepare-failure handback is exactly that case and the reason this
+  // exists. It fires before the turn is ever admitted — the active-run PATCH
+  // that admits it comes after the prepare hook — so `turnAct` is not available:
+  // its route resolves the turn first and 404s when there is none. The failure
+  // notice's own commit is what admits the turn, and by then it has also settled
+  // it. An ordinary addressed post depends on no lease at all, which is what
+  // makes it the right shape here.
+  //
+  // Retried like any durable write, and therefore REQUIRING `idempotencyKey`:
+  // this is not outbox-queued (there is no `(turnId, seq)` for a non-turn row),
+  // so without a key a committed request whose response was lost — or a
+  // redelivered dispatch event — writes a second row and wakes the peer twice.
+  // The server dedupes on `(conversation_id, idempotency_key)`: the repeat
+  // returns the existing row and raises no second dispatch (CT239). Required,
+  // not optional, so a future caller cannot omit it and silently lose the
+  // guarantee.
+  postAddressedMessage(workspaceId, conversationId, body, signal) {
+    return this.request(
+      "POST",
+      `/api/workspaces/${workspaceId}/conversations/${conversationId}/messages`,
+      body,
+      signal ? { retry: true, signal } : { retry: true }
+    );
+  }
   // SJ477: report one tool-activity transition (start / done / error) for the
   // live activity cards. Transient — the server publishes an `agent_activity`
   // SSE and writes no row. Agent-PAT authed; the URL `:agentId` must match the
@@ -8114,12 +8143,31 @@ var TurnExecution = class {
     }
     let hookEnv;
     const triggerIsPrepareFailure = this.turnContext.message.body.startsWith(PREPARE_FAILED_PREFIX);
-    const prepareFailureDispatch = this.turnContext.dispatchedByAgentId && !triggerIsPrepareFailure ? {
-      dispatch: this.turnContext.dispatchedByAgentId,
-      dispatchBody: `${PREPARE_FAILED_PREFIX}
+    const sendPrepareFailureHandback = async () => {
+      if (!this.turnContext.dispatchedByAgentId || triggerIsPrepareFailure) return;
+      try {
+        await this.opts.api.postAddressedMessage(workspaceId, payload.conversationId, {
+          body: `${PREPARE_FAILED_PREFIX}
 
-The dispatched turn could not start. Re-dispatch it after repairing the preparation failure shown in this conversation.`
-    } : {};
+The dispatched turn could not start. Re-dispatch it after repairing the preparation failure shown in this conversation.`,
+          dispatch: this.turnContext.dispatchedByAgentId,
+          // Keyed on the TRIGGER, not the turn: a redelivered dispatch event is
+          // the replay this has to survive, and it mints a fresh `turnId` while
+          // carrying the same `messageId`. One handback per failed pickup of a
+          // given trigger — which is also CT992's rule, that the first failure
+          // is the one carrying information. A genuine re-dispatch after a
+          // repair authors a NEW trigger message, so it keys differently and
+          // hands back again.
+          idempotencyKey: `prepare-failure-handback:${payload.messageId}`,
+          parentMessageId: payload.messageId
+        });
+      } catch (err) {
+        turnLog.warn(
+          { err: err instanceof Error ? err.message : String(err) },
+          "dispatcher: prepare-failure handback failed"
+        );
+      }
+    };
     if (prepareHook) {
       let cached2 = readPrepared(workspaceId, payload.conversationId, payload.agentId);
       if (cached2 && !checkoutState(cached2.cwd).ok) {
@@ -8158,8 +8206,7 @@ The dispatched turn could not start. Re-dispatch it after repairing the preparat
 ${reason}`,
                 kind: "final",
                 turnId,
-                parentMessageId: payload.messageId,
-                ...prepareFailureDispatch
+                parentMessageId: payload.messageId
               });
             } catch (postErr) {
               turnLog.warn(
@@ -8167,6 +8214,7 @@ ${reason}`,
                 "dispatcher: prepare-rejection post failed"
               );
             }
+            await sendPrepareFailureHandback();
             throw this.concluded(`prepare_failed: ${reason}`);
           }
         }
@@ -8234,8 +8282,7 @@ ${reason}`,
               kind: "final",
               turnId,
               // CT113: stamp the parent even on the prepare-failed close.
-              parentMessageId: payload.messageId,
-              ...prepareFailureDispatch
+              parentMessageId: payload.messageId
             });
           } catch (postErr) {
             turnLog.warn(
@@ -8243,6 +8290,7 @@ ${reason}`,
               "dispatcher: prepare-failure post failed"
             );
           }
+          await sendPrepareFailureHandback();
           const failReason = `prepare_failed: ${reason}`;
           throw this.concluded(failReason);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabane/companion",
-  "version": "0.6.87",
+  "version": "0.6.88",
   "type": "module",
   "description": "The Cabane Companion (headless): connect a coding agent on your machine to your Cabane workspace as a responder — drive work against your own codebase, files, and MCP servers without putting any of it in Cabane.",
   "license": "UNLICENSED",