@commonlyai/cli 0.1.1 → 0.1.2

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "Apache-2.0",
-  "description": "The Commonly CLI \u2014 connect agents, manage pods, iterate fast",
+  "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",
   "main": "./src/index.js",
   "bin": {

package/src/commands/agent.js

@@ -21,7 +21,13 @@ import { getToken, resolveInstanceUrl } from '../lib/config.js';
 import { startPoller } from '../lib/poller.js';
 import { startWebhookServer, forwardToLocalWebhook } from '../lib/webhook-server.js';
 import { getAdapter, listAdapterNames } from '../lib/adapters/index.js';
-import { getSession, setSession, clearSessions } from '../lib/session-store.js';
+import {
+  getSession,
+  setSession,
+  clearSessions,
+  wasEventHandled,
+  recordHandledEvent,
+} from '../lib/session-store.js';
 import { readLongTerm, syncBack } from '../lib/memory-bridge.js';
 import { detectMemorySources, composeImport, importMemory } from '../lib/memory-import.js';
 import { detectSkills, importSkills } from '../lib/skills-import.js';
@@ -100,20 +106,26 @@ export const listLocalAgents = () => {
     .filter(Boolean);
 };
 
-// Event types that carry a human/agent-authored 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.
-const CHAT_EVENT_TYPES = new Set(['chat.mention', 'message.posted', 'dm.message']);
+// 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.
+const PROMPT_EVENT_TYPES = new Set([
+  'chat.mention',
+  'message.posted',
+  'dm.message',
+  'first_contact',
+]);
 
 // ── default environment for adapters that benefit from auto-MCP wiring ─────
 
 // Adapters that can consume `mcp[]` from the resolved environment spec.
-// `claude` reads it via --mcp-config (see adapters/claude.js). `codex` and
-// `stub` do not (codex uses ~/.codex/config.toml at boot, set up server-side
-// for cloud-codex; the local codex wrapper doesn't ship MCP wiring yet —
-// follow-up after #440). Returning null means "no default" — the wrapper
-// proceeds with environment=null exactly like before this change.
-const ADAPTERS_WITH_DEFAULT_MCP = new Set(['claude']);
+// `claude` reads it via --mcp-config (see adapters/claude.js); `codex` via
+// `-c mcp_servers.*` config overrides (see adapters/codex.js — added after
+// the 2026-07-22 as-operator attribution incident, where an MCP-less codex
+// agent posted through the operator's CLI profile because it had no
+// commonly_* tools of its own). `stub` does not. Returning null means "no
+// default" — the wrapper proceeds with environment=null exactly like before.
+const ADAPTERS_WITH_DEFAULT_MCP = new Set(['claude', 'codex']);
 
 // The commonly behavior skill ships inside this package (cli/skills/commonly)
 // so a fresh attach can mount it into the agent without a network fetch.
@@ -366,7 +378,7 @@ export const runMemoryImport = async ({
 // ── run: local-CLI wrapper loop (ADR-005) ────────────────────────────────────
 
 const extractPrompt = (event) => {
-  if (!CHAT_EVENT_TYPES.has(event.type)) return null;
+  if (!PROMPT_EVENT_TYPES.has(event.type)) return null;
   const p = event.payload || {};
   return p.content || p.prompt || p.text || null;
 };
@@ -432,7 +444,7 @@ export const performRun = ({
     // and (if the adapter returns a summary) patch-sync back after.
     const memoryLongTerm = await readLongTerm(client, { onError });
 
-    // Snapshot the pod's recent message ids so that, after the spawn, we can
+    // Snapshot the pod's recent messages so that, after the spawn, we can
     // tell whether the agent posted itself via commonly_post_message. If it
     // 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
@@ -440,17 +452,20 @@ export const performRun = ({
     // 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.)
-    const snapshotMessageIds = async () => {
+    const snapshotMessages = async () => {
       try {
         const { messages = [] } = await client.get(
           `/api/agents/runtime/pods/${eventPodId}/messages`, { limit: 10 },
         );
-        return new Set(messages.map((m) => String(m._id || m.id)));
+        return messages;
       } catch {
         return null; // detection unavailable — fall back to posting the reply
       }
     };
-    const preSpawnIds = await snapshotMessageIds();
+    const preSpawn = await snapshotMessages();
+    const preSpawnIds = preSpawn
+      ? new Set(preSpawn.map((m) => String(m._id || m.id)))
+      : null;
 
     log(`[${event.type}] spawning ${adapter.name}`);
     const result = await adapter.spawn(prompt, {
@@ -482,10 +497,19 @@ export const performRun = ({
     const replyText = (result.text || '').trim();
     let agentPostedItself = false;
     if (preSpawnIds) {
-      const postSpawnIds = await snapshotMessageIds();
-      if (postSpawnIds) {
-        for (const id of postSpawnIds) {
-          if (!preSpawnIds.has(id)) { agentPostedItself = true; break; }
+      const postSpawn = await snapshotMessages();
+      if (postSpawn) {
+        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) {
+            agentPostedItself = true;
+            break;
+          }
         }
       }
     }
@@ -524,13 +548,23 @@ export const performRun = ({
       for (const event of events) {
         if (!running) break;
         let result;
-        try {
-          result = await processEvent(event);
-        } catch (err) {
-          // Spawn failed — skip ack, let kernel re-deliver (ADR-005).
-          log(`[${event.type}] spawn error: ${err.message}`);
-          onError?.(err);
-          continue;
+        if (wasEventHandled(agentName, event._id)) {
+          result = { outcome: 'no_action', reason: 'duplicate-delivery' };
+          log(`[${event.type}] duplicate delivery ${event._id} — skipping spawn and re-acking`);
+        } else {
+          try {
+            result = await processEvent(event);
+          } catch (err) {
+            // Spawn failed — do not record or ack, so the kernel can re-deliver
+            // the event after the local runtime recovers (ADR-005).
+            log(`[${event.type}] spawn error: ${err.message}`);
+            onError?.(err);
+            continue;
+          }
+          // Record after successful processing but before ack. If the ack
+          // fails, the next delivery is skipped and re-acked instead of
+          // burning a second model turn for work that already completed.
+          recordHandledEvent(agentName, event._id);
         }
         try {
           await client.post(`/api/agents/runtime/events/${event._id}/ack`, { result });
@@ -685,7 +719,8 @@ export const performInit = async ({
  *      7 days after all installs go inactive — we don't force-revoke here
  *      because the token may legitimately still be in use for another pod.
  *   2. Local token file at ~/.commonly/tokens/<name>.json
- *   3. Local session store at ~/.commonly/sessions/<name>.json
+ *   3. Local session + handled-event stores at
+ *      ~/.commonly/sessions/<name>{,.events}.json
  *
  * Idempotent: if the backend returns 404 (already uninstalled elsewhere), we
  * still clean up local files so the CLI state stays in sync with reality.

package/src/lib/adapters/codex.js

@@ -71,10 +71,64 @@ const buildPrompt = (prompt, memoryLongTerm) => {
   return `=== Context (your persistent memory) ===\n${memoryLongTerm}\n=== Current turn ===\n${prompt}`;
 };
 
+// ── MCP wiring — codex consumes MCP servers via `-c mcp_servers.*` overrides ─
+//
+// Same substitution contract as claude.js (see that file for the placeholder
+// rationale): ${COMMONLY_AGENT_TOKEN} / ${COMMONLY_API_URL} in the declared
+// env spec are replaced with the wrapper's per-(agent, pod) runtime values at
+// spawn time. Before this block the codex adapter silently ignored
+// `environment.mcp`, so a codex agent had NO sanctioned posting tool — the
+// 2026-07-22 as-operator attribution incident was a codex agent falling back
+// to the operator's CLI profile because commonly_* tools were never wired.
+//
+// Codex-specific constraints:
+//   - stdio/command servers only (no url transport here); url-only entries
+//     are skipped rather than half-wired.
+//   - Declared env MUST ride inside the mcp_servers.<name>.env table — codex
+//     does not pass its parent env to the MCP child it spawns (the PR #398
+//     cloud-codex lesson; same failure mode locally).
+const SUBSTITUTION_KEYS = ['COMMONLY_AGENT_TOKEN', 'COMMONLY_API_URL', 'COMMONLY_INSTANCE_URL'];
+const PLACEHOLDER_RE = /\$\{(COMMONLY_[A-Z_]+)\}/g;
+
+const substitutePlaceholders = (value, ctx) => {
+  if (typeof value !== 'string') return value;
+  if (!value.includes('${COMMONLY_')) return value;
+  const subs = {
+    COMMONLY_AGENT_TOKEN: ctx.runtimeToken || '',
+    COMMONLY_API_URL: ctx.instanceUrl || '',
+    COMMONLY_INSTANCE_URL: ctx.instanceUrl || '',
+  };
+  return value.replace(PLACEHOLDER_RE, (whole, key) => (
+    SUBSTITUTION_KEYS.includes(key) && subs[key] ? subs[key] : whole
+  ));
+};
+
+// JSON string escaping is a valid subset of TOML basic-string escaping, so
+// JSON.stringify doubles as the TOML quoter for command/args/env values.
+const toml = (s) => JSON.stringify(String(s));
+
+const buildMcpOverrideArgs = (mcpServers, ctx = {}) => {
+  const flags = [];
+  for (const server of mcpServers || []) {
+    if (!server?.name || !Array.isArray(server.command) || !server.command.length) continue;
+    const [command, ...rest] = server.command.map((a) => substitutePlaceholders(a, ctx));
+    flags.push('-c', `mcp_servers.${server.name}.command=${toml(command)}`);
+    if (rest.length) {
+      flags.push('-c', `mcp_servers.${server.name}.args=[${rest.map(toml).join(',')}]`);
+    }
+    const envEntries = Object.entries(server.env || {})
+      .map(([k, v]) => `${k} = ${toml(substitutePlaceholders(v, ctx))}`);
+    if (envEntries.length) {
+      flags.push('-c', `mcp_servers.${server.name}.env={${envEntries.join(', ')}}`);
+    }
+  }
+  return flags;
+};
+
 // Build the argv after the `codex` binary. Resume vs new turn is a
 // subcommand-level distinction in modern codex, not an option flag — keep
 // that detail isolated here so the spawn path stays linear.
-const buildArgs = ({ sessionId, prompt, outputFile }) => {
+const buildArgs = ({ sessionId, prompt, outputFile, mcpFlags = [] }) => {
   // `--dangerously-bypass-approvals-and-sandbox` disables codex CLI's
   // bubblewrap (bwrap) sandbox + approval prompts. bwrap needs CAP_SYS_ADMIN
   // or unprivileged user-namespaces — neither available to standard k8s
@@ -90,6 +144,7 @@ const buildArgs = ({ sessionId, prompt, outputFile }) => {
     '--json',
     '--skip-git-repo-check',
     '--dangerously-bypass-approvals-and-sandbox',
+    ...mcpFlags,
     '-o',
     outputFile,
   ];
@@ -219,6 +274,10 @@ export default {
         sessionId: ctx.sessionId || null,
         prompt: fullPrompt,
         outputFile,
+        mcpFlags: buildMcpOverrideArgs(ctx.environment?.mcp, {
+          runtimeToken: ctx.runtimeToken,
+          instanceUrl: ctx.instanceUrl,
+        }),
       });
 
       const { threadId } = await runCodex({

package/src/lib/session-store.js

@@ -14,6 +14,11 @@
  *   }
  *
  * CLIs without sessions simply never call setSession — getSession returns null.
+ *
+ * Handled runtime-event IDs are intentionally persisted in a separate
+ * `<agent>.events.json` file. Keeping the bounded event ring separate means
+ * session-map readers retain their existing on-disk shape while a wrapper
+ * restart can still suppress a re-delivered event whose ack previously failed.
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'fs';
@@ -22,6 +27,9 @@ import { homedir } from 'os';
 
 const sessionsDir = () => join(homedir(), '.commonly', 'sessions');
 const sessionsFile = (agentName) => join(sessionsDir(), `${agentName}.json`);
+const handledEventsFile = (agentName) => join(sessionsDir(), `${agentName}.events.json`);
+const MAX_HANDLED_EVENTS = 500;
+const handledEventsCache = new Map();
 
 const readAgent = (agentName) => {
   const file = sessionsFile(agentName);
@@ -38,6 +46,42 @@ const writeAgent = (agentName, state) => {
   writeFileSync(sessionsFile(agentName), JSON.stringify(state, null, 2), 'utf8');
 };
 
+const readHandledEvents = (agentName) => {
+  const file = handledEventsFile(agentName);
+  if (!existsSync(file)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .filter((eventId) => typeof eventId === 'string' && eventId.length > 0)
+      .slice(-MAX_HANDLED_EVENTS);
+  } catch {
+    return [];
+  }
+};
+
+const getHandledEvents = (agentName) => {
+  const file = handledEventsFile(agentName);
+  // Tests, detach, or an operator may remove the file while this process is
+  // alive. Reset the mirror rather than retaining IDs that no longer exist on
+  // disk; a fresh process likewise hydrates from the persisted ring.
+  if (!existsSync(file)) {
+    const empty = { ids: [], set: new Set() };
+    handledEventsCache.set(agentName, empty);
+    return empty;
+  }
+  if (!handledEventsCache.has(agentName)) {
+    const ids = readHandledEvents(agentName);
+    handledEventsCache.set(agentName, { ids, set: new Set(ids) });
+  }
+  return handledEventsCache.get(agentName);
+};
+
+const writeHandledEvents = (agentName, ids) => {
+  if (!existsSync(sessionsDir())) mkdirSync(sessionsDir(), { recursive: true });
+  writeFileSync(handledEventsFile(agentName), JSON.stringify(ids, null, 2), 'utf8');
+};
+
 export const getSession = (agentName, podId) => {
   if (!agentName || !podId) return null;
   return readAgent(agentName)[podId]?.sessionId || null;
@@ -50,7 +94,26 @@ export const setSession = (agentName, podId, sessionId) => {
   writeAgent(agentName, state);
 };
 
+export const wasEventHandled = (agentName, eventId) => {
+  if (!agentName || !eventId) return false;
+  return getHandledEvents(agentName).set.has(String(eventId));
+};
+
+export const recordHandledEvent = (agentName, eventId) => {
+  if (!agentName || !eventId) return;
+  const normalizedId = String(eventId);
+  const current = getHandledEvents(agentName);
+  if (current.set.has(normalizedId)) return;
+
+  const ids = [...current.ids, normalizedId].slice(-MAX_HANDLED_EVENTS);
+  writeHandledEvents(agentName, ids);
+  handledEventsCache.set(agentName, { ids, set: new Set(ids) });
+};
+
 export const clearSessions = (agentName) => {
   const file = sessionsFile(agentName);
   if (existsSync(file)) rmSync(file);
+  const eventsFile = handledEventsFile(agentName);
+  if (existsSync(eventsFile)) rmSync(eventsFile);
+  handledEventsCache.delete(agentName);
 };