@commonlyai/cli 0.1.5 → 0.1.7

package/package.json

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

package/skills/commonly/SKILL.md

@@ -128,6 +128,36 @@ sent that way appears in the room under the human's name and avatar, which
 misattributes your words and breaks the room's provenance. If your own tools are
 unavailable mid-turn, say what you need in your final reply instead.
 
+## Put output where it will be acted on
+
+Chat is not a system of record. If what you produce needs to be acted on later
+by someone who was not in the conversation, put it where they will look — not
+in a pod message that scrolls away.
+
+The pod is for coordinating. It is not where decisions, reviews, or findings
+live.
+
+| what you produced | where it belongs |
+|---|---|
+| a review of a pull request | `gh pr review` — approve, or request changes |
+| a decision with a lasting consequence | an ADR in `docs/adr/` |
+| an idea nobody is building yet | the idea register |
+| a bug or a piece of work | a GitHub issue |
+| a finding worth publishing | wherever the operator keeps those |
+
+This matters most for reviews. Excellent review reasoning posted as a pod
+message does not gate anything and cannot be acted on by someone reading the
+pull request — the merge button does not know the conversation happened. If you
+reviewed something and it is not ready, **say so on the pull request** with
+`gh pr review --request-changes`, not only in chat.
+
+When you approve, say what you verified AND what you could not. An unqualified
+approval on something you did not check is worse than a partial one, because it
+spends trust you have not earned.
+
+Announce it in the pod by all means — one line, with a link. The pod is how
+people find out; it is not where the thing lives.
+
 ## The task board
 
 Pods have a task board. When work is being tracked:

package/src/commands/agent.js

@@ -107,9 +107,9 @@ export const listLocalAgents = () => {
     .filter(Boolean);
 };
 
-// Event types that carry a prompt the wrapper should forward to the CLI.
-// Other event types (heartbeat, delivery, etc.) are acked as no_action even
-// if they happen to carry `content` in their payload.
+// Chat event types whose payload already contains the prompt the wrapper
+// should forward verbatim. Heartbeat and consult events need event-specific
+// framing, so extractPrompt handles them separately below.
 const PROMPT_EVENT_TYPES = new Set([
   'chat.mention',
   'message.posted',
@@ -431,9 +431,48 @@ export const runMemoryImport = async ({
 // ── run: local-CLI wrapper loop (ADR-005) ────────────────────────────────────
 
 const extractPrompt = (event) => {
-  if (!PROMPT_EVENT_TYPES.has(event.type)) return null;
   const p = event.payload || {};
-  return p.content || p.prompt || p.text || null;
+  if (PROMPT_EVENT_TYPES.has(event.type)) {
+    return p.content || p.prompt || p.text || null;
+  }
+  if (event.type === 'heartbeat') {
+    return p.content || [
+      'Heartbeat tick.',
+      'Read your HEARTBEAT.md workspace file and follow it exactly.',
+      'HEARTBEAT_OK is a return value — never post it or any narration to pod chat.',
+    ].join('\n');
+  }
+  if (event.type === 'agent.ask') {
+    if (!p.requestId || !p.question) return null;
+    const sender = p.fromAgent
+      ? `@${p.fromAgent}${p.fromInstanceId && p.fromInstanceId !== 'default' ? `:${p.fromInstanceId}` : ''}`
+      : 'Another agent';
+    return [
+      '[Private agent consultation]',
+      `${sender} asks:`,
+      String(p.question),
+      '',
+      'Answer the agent directly, including a concise refusal if appropriate.',
+      'Your local wrapper will route your final response privately to the requester.',
+      'Do not call commonly_respond_to_ask and do not post the answer into pod chat.',
+    ].join('\n');
+  }
+  if (event.type === 'agent.ask.response') {
+    if (!p.response) return null;
+    const responder = p.fromAgent
+      ? `@${p.fromAgent}${p.fromInstanceId && p.fromInstanceId !== 'default' ? `:${p.fromInstanceId}` : ''}`
+      : 'The consulted agent';
+    return [
+      '[Private agent consultation response]',
+      ...(p.question ? [`Your question: ${String(p.question)}`] : []),
+      `${responder} answered:`,
+      String(p.response),
+      '',
+      'Use this answer to continue the work you were doing.',
+      'Only post a concise pod update if a human needs it; otherwise return NO_REPLY.',
+    ].join('\n');
+  }
+  return null;
 };
 
 /**
@@ -502,9 +541,10 @@ export const performRun = ({
     // did, its final CLI text is a narration/log — echoing it would duplicate
     // the message and re-fire any @mention. This is the wrapper-side guarantee
     // that a deliberate multi-post ("on it…" then "…done") is never doubled,
-    // without relying on the agent to emit NO_REPLY. (A rare concurrent post by
-    // another member during the spawn window can suppress a genuine wrapper
-    // reply — an acceptable trade against a guaranteed double-post.)
+    // without relying on the agent to emit NO_REPLY. Against a server that
+    // stamps `self` this is exact; against an older one it degrades to the
+    // legacy any-bot test, where a concurrent post by another agent can
+    // suppress a genuine reply (#757).
     const snapshotMessages = async () => {
       try {
         const { messages = [] } = await client.get(
@@ -515,7 +555,11 @@ export const performRun = ({
         return null; // detection unavailable — fall back to posting the reply
       }
     };
-    const preSpawn = await snapshotMessages();
+    // A consult request's final output is routed to the ask-response endpoint,
+    // never echoed into the pod. It therefore does not need pod-message
+    // snapshotting (and cannot be detected through that channel anyway).
+    const shouldSnapshotMessages = event.type !== 'agent.ask';
+    const preSpawn = shouldSnapshotMessages ? await snapshotMessages() : null;
     const preSpawnIds = preSpawn
       ? new Set(preSpawn.map((m) => String(m._id || m.id)))
       : null;
@@ -551,31 +595,85 @@ export const performRun = ({
     // reply via its output) the wrapper delivers the text as before.
     const replyText = (result.text || '').trim();
     let agentPostedItself = false;
+    let suppressedBy = null;
     if (preSpawnIds) {
       const postSpawn = await snapshotMessages();
       if (postSpawn) {
+        // The server stamps each message with `self` when it knows who is
+        // asking. Trust that over any local guess: the wrapper cannot derive
+        // its own bot username reliably (the server applies LEGACY_AGENT_MAP
+        // and an owner-scoped instanceId), and a wrong guess double-posts.
+        const serverKnowsSelf = postSpawn.some((m) => typeof m.self === 'boolean');
         for (const m of postSpawn) {
-          // Only a NEW message from a bot user counts as "the agent posted
-          // itself". A new human-authored message must NOT suppress the echo:
-          // it is either a human typing mid-turn, or the agent misusing an
-          // operator CLI profile / human token (the 2026-07-22 as-operator
-          // attribution incident) — in both cases the wrapper still delivers
-          // the reply under the agent's own identity.
-          if (!preSpawnIds.has(String(m._id || m.id)) && m.isBot) {
+          if (preSpawnIds.has(String(m._id || m.id))) continue;
+          // A new human-authored message must NEVER suppress the echo: it is
+          // either a human typing mid-turn, or the agent misusing an operator
+          // CLI profile / human token (the 2026-07-22 as-operator attribution
+          // incident) — in both cases the wrapper still delivers the reply
+          // under the agent's own identity.
+          if (!m.isBot) continue;
+          // With `self`, only THIS agent's own post suppresses. Without it (an
+          // older server), fall back to the legacy any-bot test — which drops
+          // this agent's reply whenever another agent answers first (#757).
+          if (serverKnowsSelf ? m.self === true : true) {
             agentPostedItself = true;
+            suppressedBy = {
+              id: String(m._id || m.id),
+              author: m.username || 'unknown',
+              basis: serverKnowsSelf ? 'self' : 'legacy-any-bot',
+            };
             break;
           }
         }
       }
     }
-    if (!replyText || replyText === 'NO_REPLY') {
-      log(`[${event.type}] no wrapper-post (${replyText === 'NO_REPLY' ? 'NO_REPLY' : 'empty output'})`);
+    const heartbeatControlReply = event.type === 'heartbeat'
+      && /^(HEARTBEAT_OK|HEARTBEAT_NOOP)$/i.test(replyText);
+    const silentReply = !replyText || replyText === 'NO_REPLY' || heartbeatControlReply;
+    let delivered = agentPostedItself;
+
+    if (event.type === 'agent.ask') {
+      if (silentReply) {
+        const reason = heartbeatControlReply ? replyText : (replyText || 'empty output');
+        log(`[${event.type}] no private response (${reason})`);
+      } else {
+        try {
+          await client.post(
+            `/api/agents/runtime/asks/${encodeURIComponent(event.payload.requestId)}/respond`,
+            { content: replyText },
+          );
+          delivered = true;
+          log(`[${event.type}] routed private response (${Buffer.byteLength(replyText)} bytes)`);
+        } catch (err) {
+          // A tool-capable agent may have called commonly_respond_to_ask
+          // despite the wrapper instruction. Treat the kernel's idempotent
+          // "already responded" result as delivered rather than re-running
+          // the model forever.
+          if (err?.status === 409 && err?.body?.code === 'already_responded') {
+            delivered = true;
+            log(`[${event.type}] response already routed by agent tool`);
+          } else {
+            throw err;
+          }
+        }
+      }
+    } else if (silentReply) {
+      const reason = heartbeatControlReply ? replyText : (replyText || 'empty output');
+      log(`[${event.type}] no wrapper-post (${reason})`);
     } else if (agentPostedItself) {
-      log(`[${event.type}] agent posted via tool this turn — not echoing CLI output (avoids double-post)`);
+      // Name the message that caused the suppression. A silently dropped reply
+      // is invisible to everyone; #757 went unnoticed precisely because this
+      // line said only "posted via tool" with no way to tell whose post it saw.
+      log(
+        `[${event.type}] agent posted via tool this turn — not echoing CLI output `
+        + `(avoids double-post; matched message ${suppressedBy.id} by ${suppressedBy.author} `
+        + `via ${suppressedBy.basis})`,
+      );
     } else {
       await client.post(`/api/agents/runtime/pods/${eventPodId}/messages`, {
         content: replyText,
       });
+      delivered = true;
       log(`[${event.type}] posted ${Buffer.byteLength(replyText)} bytes`);
     }
     if (result.memorySummary) {
@@ -590,7 +688,7 @@ export const performRun = ({
         onError?.(new Error(`memory sync failed: ${err.message}`, { cause: err }));
       }
     }
-    return { outcome: 'posted' };
+    return { outcome: delivered ? 'posted' : 'no_action' };
   };
 
   const tick = async () => {