@commonlyai/cli 0.1.167 → 0.1.170

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.167",
+  "version": "0.1.170",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/agent.js

@@ -2035,15 +2035,32 @@ export const performRun = ({
     } else {
       // ADR-018 length gate: the tone contract is enforced here, where the
       // wrapper is the one posting. Split, attach — never truncate.
-      const delivery = await deliverChatReply({
-        client,
-        podId: eventPodId,
-        text: replyText,
-        limit: chatCharLimit,
-        maxChunks: maxChatChunks,
-        uploadName: `${agentName}-reply-${event._id}.md`,
-        log: (line) => log(`[${event.type}] ${line}`),
-      });
+      let delivery;
+      try {
+        delivery = await deliverChatReply({
+          client,
+          podId: eventPodId,
+          text: replyText,
+          limit: chatCharLimit,
+          maxChunks: maxChatChunks,
+          uploadName: `${agentName}-reply-${event._id}.md`,
+          log: (line) => log(`[${event.type}] ${line}`),
+        });
+      } catch (deliveryError) {
+        // TASK-535: every rung threw, so the reply reached nobody. The throw
+        // still leaves the events unacked for redelivery (unchanged), but the
+        // retry report is about the BATCH; this line is about the reply, and
+        // it names where it was going so a lost summary is never silent.
+        const eventCount = Array.isArray(event.payload?.batchEventIds)
+          ? event.payload.batchEventIds.length
+          : 1;
+        log(
+          `[${event.type}] ERROR reply NOT delivered to pod ${eventPodId} — `
+          + `${Buffer.byteLength(replyText)} bytes lost, ${eventCount} event${eventCount === 1 ? '' : 's'} `
+          + `left unacked for retry: ${deliveryError.message}`,
+        );
+        throw deliveryError;
+      }
       if (delivery.skipped) {
         // The server answered 200 and created nothing: a duplicate inside its
         // dedupe window, a silent body, a heartbeat it keeps. Nothing reached

package/src/commands/pod.js

@@ -55,6 +55,7 @@ Commonly instance (see: commonly login --help).
   pod
     .command('send <podId> <message>')
     .description('Post a message to a pod')
+    .option('--payload <json>', 'UI card JSON envelope; the message remains the required text fallback')
     .option('--instance <url>', 'Target Commonly instance')
     .action(async (podId, message, opts) => {
       const token = getToken(opts.instance);
@@ -63,12 +64,18 @@ Commonly instance (see: commonly login --help).
       const client = createClient({ instance: resolveInstanceUrl(opts.instance), token });
 
       try {
-        // Try agent runtime endpoint first (agent token), fall back to user endpoint
-        const result = await client.post(`/api/agents/runtime/pods/${podId}/messages`, {
-          content: message,
-        }).catch(() => client.post(`/api/messages/${podId}`, {
-          content: message,
-        }));
+        const body = { content: message };
+        if (opts.payload !== undefined) {
+          body.payload = JSON.parse(opts.payload);
+          body.messageType = 'card';
+        }
+        // UI cards use the validated agent endpoint only. A validation or
+        // authorization refusal must never retry through the human writer.
+        const result = await client.post(`/api/agents/runtime/pods/${podId}/messages`, body)
+          .catch((error) => {
+            if (opts.payload !== undefined) throw error;
+            return client.post(`/api/messages/${podId}`, body);
+          });
 
         console.log(`Sent (${result._id || result.id || 'ok'})`);
       } catch (err) {

package/src/lib/enforcement.js

@@ -18,6 +18,8 @@
  * stands the agent down, and both are logged with the reason.
  */
 
+import { isUnseenMessagesHold } from './pod-catch-up.js';
+
 // Event types whose payload.messageId identifies a claimable trigger message.
 // first_contact is deliberately absent: the welcome wake targets exactly one
 // agent, so there is nothing to contend for. Heartbeats have no message at
@@ -673,7 +675,49 @@ export const deliverChatReply = async ({
   // request, but no message was created. Keep that distinction at the client
   // boundary so every delivery mode shares it rather than treating a resolved
   // promise as proof of a post.
-  const postMessage = (body) => client.post(messagesPath, body);
+  //
+  // TASK-535 — the send-time freshness hold. The backend answers 409
+  // `unseen_messages` when other members posted after this seat's last
+  // recorded tail read. A turn that ran ~43 minutes (rhea, 2026-10-25 10:01Z)
+  // hit it on the thread headline, the attach card and the split fallback in
+  // turn, so the reply was lost and its 10 events re-ran. A retry without an
+  // override cannot succeed — every rung posts to the same guarded route.
+  //
+  // CTO ruling: on the FIRST hold of a delivery, re-read the pod tail once,
+  // then post with `continueAnyway: true`, and keep the override for every
+  // later post in THIS delivery (remaining chunks, later rungs). The re-read
+  // is GET /messages at the route's 50-row cap with no `before`/`threadRootId`
+  // — the read that records a seen cursor (AgentSendFreshness.recordRead). It
+  // advances the cursor only when the page holds EVERY message since the last
+  // recorded read. The wrapper's own post-turn snapshot is that same read at
+  // limit 10, which is why a 12-message gap stayed unseen. So a re-read alone
+  // passes a normal post only while the gap is ≤ 50 and nothing lands between
+  // read and post; the override is what delivers, and the read records what
+  // the wrapper saw, exactly as its snapshots already do. One re-read and one
+  // override per delivery; a post that still fails throws to the next rung as
+  // before. Nothing here loops.
+  let freshnessOverride = false;
+  const postMessage = async (body) => {
+    if (freshnessOverride) return client.post(messagesPath, { ...body, continueAnyway: true });
+    try {
+      return await client.post(messagesPath, body);
+    } catch (error) {
+      if (!isUnseenMessagesHold(error)) throw error;
+      freshnessOverride = true;
+      const unseen = error.body?.unseenCount;
+      log(
+        `reply held: ${Number.isFinite(unseen) ? unseen : 'some'} unseen message(s) in pod ${podId} `
+        + 'arrived during the turn — re-reading the pod once, then posting with continueAnyway (TASK-535)',
+      );
+      try {
+        await client.get(messagesPath, { limit: 50 });
+      } catch (readError) {
+        // The re-read is bookkeeping, not permission: the override delivers.
+        log(`pod re-read before the continueAnyway post failed (${readError.message}) — posting anyway`);
+      }
+      return client.post(messagesPath, { ...body, continueAnyway: true });
+    }
+  };
   const refused = (response, messages, attemptedMessages) => ({
     mode: 'refused',
     messages,

package/src/lib/pod-catch-up.js

@@ -1,3 +1,13 @@
+/**
+ * The backend's send-time freshness hold (agentSendFreshness.unseenMessages):
+ * HTTP 409 with `code: 'unseen_messages'`, surfaced by api.js as
+ * `error.status` + `error.body`. Shared by the turn-start probe below and the
+ * end-of-turn delivery in enforcement.js, so both read the hold the same way.
+ */
+export const isUnseenMessagesHold = (error) => (
+  error?.status === 409 && error?.body?.code === 'unseen_messages'
+);
+
 /** Explicit turn-start recovery for history that cannot fit in a tail read. */
 export const catchUpBeforeTurn = async (client, podId) => {
   const base = `/api/agents/runtime/pods/${encodeURIComponent(podId)}`;
@@ -9,13 +19,19 @@ export const catchUpBeforeTurn = async (client, podId) => {
     // Unknown freshness preserves existing turn behavior; the send-time auth
     // and freshness checks still decide whether output may be posted.
     if (error?.status !== 409) return '';
-    if (error?.body?.code !== 'unseen_messages') throw error;
+    if (!isUnseenMessagesHold(error)) throw error;
     unseenCount = error.body.unseenCount;
   }
   // Routine wakes retain the seat's existing read behavior and prompt size.
   if (!(unseenCount > 50)) return '';
-  // Never retry an already generated reply with continueAnyway. A catch-up
-  // supplies fresh conversation context BEFORE the model gets a turn.
+  // Before the turn, the answer to a hold is context, not an override: a
+  // catch-up supplies fresh conversation BEFORE the model gets a turn, so
+  // nothing here sends with continueAnyway. The one place an already
+  // generated reply IS retried with continueAnyway is end-of-turn delivery
+  // (deliverChatReply, TASK-535): a turn long enough for the pod to move on
+  // otherwise lost its whole reply to this same hold and left its events to
+  // re-run. That is a CTO ruling scoped to delivery; it does not license
+  // continueAnyway anywhere a fresh read can still reach the model.
   let body;
   try {
     body = await client.post(`${base}/catch-up`, { confirmSkipHistory: true });