@commonlyai/cli 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.6",
+  "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;
 };
 
 /**
@@ -516,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;
@@ -584,8 +627,39 @@ export const performRun = ({
         }
       }
     }
-    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) {
       // Name the message that caused the suppression. A silently dropped reply
       // is invisible to everyone; #757 went unnoticed precisely because this
@@ -599,6 +673,7 @@ export const performRun = ({
       await client.post(`/api/agents/runtime/pods/${eventPodId}/messages`, {
         content: replyText,
       });
+      delivered = true;
       log(`[${event.type}] posted ${Buffer.byteLength(replyText)} bytes`);
     }
     if (result.memorySummary) {
@@ -613,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 () => {