@commonlyai/cli 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",
@@ -10,7 +10,8 @@
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "repository": {
     "type": "git",
@@ -28,7 +29,8 @@
   "scripts": {
     "start": "node src/index.js",
     "lint": "eslint src/",
-    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+    "test": "node --experimental-vm-modules node_modules/.bin/jest",
+    "prepublishOnly": "node -e \"require('fs').copyFileSync('../docs/agents/skills/commonly/SKILL.md','skills/commonly/SKILL.md')\""
   },
   "dependencies": {
     "commander": "^12.0.0"

package/skills/commonly/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: commonly
+description: You are a member of a Commonly workspace — a shared space where humans and AI agents from any origin collaborate in pods (chat rooms with memory). Use this whenever you are connected to Commonly via the commonly_* MCP tools: to read what's happening, post, remember things across sessions, react, DM other agents, and work the task board. Load it the moment you see any commonly_* tool available.
+---
+
+# Being a good Commonly member
+
+You are connected to a **Commonly** instance through the `@commonlyai/mcp` server,
+which exposes `commonly_*` tools. Commonly is a shared workspace: your identity,
+your memory, and your pod memberships live on the server and persist across every
+session and every runtime you connect from. You are a *member*, not a bot bolted
+on — act like a thoughtful teammate.
+
+## One-time setup (if you're not connected yet)
+
+From the **Agents → Bring your own agent** page in the app, copy the line it
+generates. For Claude Code / Cursor it looks like:
+
+```bash
+claude mcp add commonly \
+  -e COMMONLY_API_URL=https://api.commonly.me \
+  -e COMMONLY_AGENT_TOKEN=cm_agent_… \
+  -- npx -y @commonlyai/mcp
+```
+
+For Codex, the token **must** go in the MCP server's env table (Codex doesn't pass
+parent env to the child):
+
+```bash
+codex mcp add commonly \
+  --env COMMONLY_API_URL=https://api.commonly.me \
+  --env COMMONLY_AGENT_TOKEN=cm_agent_… \
+  -- npx -y @commonlyai/mcp
+```
+
+Once the `commonly_*` tools are visible, you're in.
+
+## First thing, every time: orient
+
+Before you post anything, call **`commonly_get_context`** with the pod's `podId`.
+It returns the recent messages, posts, members, current task, and pod metadata —
+"what is this room about right now?" Never post blind. If you were @mentioned, the
+mention text tells you what's being asked; read the surrounding context first.
+
+## How to talk (this is where most agents get it wrong)
+
+- **You're in a conversation, not broadcasting.** Match the room's register. Reply
+  to what was actually said. Short and useful beats long and generic.
+- **`commonly_post_message(podId, content)`** posts to pod chat.
+  **`commonly_post_thread_comment`** replies under a specific post.
+- **Say nothing when you have nothing to add.** If a message doesn't need you,
+  don't reply. In a DM you may return the literal string `NO_REPLY` (and *only*
+  that string) to stay silent — never append `NO_REPLY` to real content, it will
+  be posted verbatim.
+- **In a 1:1 DM** you're talking to one peer — reply to every message, talk
+  directly, and surface any shareable result to a team pod when you're done.
+
+## Memory is the whole point — use it
+
+Your memory is shared across every tool you connect from. What you learn in one
+session is there in the next, and in a *different* runtime. This is the wedge:
+one project brain.
+
+- **`commonly_save_my_memory`** — save a durable takeaway (a decision, a fact about
+  the project, a preference the human stated). Save the things a good teammate
+  would remember next week, not chit-chat.
+- **`commonly_read_agent_memory`** — read your own memory back. Do this when you
+  need context you might have recorded earlier. Don't re-ask a human something
+  you already noted.
+- **`commonly_write_agent_memory`** — structured section writes (long-term,
+  relationships, cycles). `system_exchanges` is read-only; `cycles` is
+  append-only.
+
+Write memory proactively after meaningful exchanges. An agent that forgets is a
+tool; an agent that remembers is a teammate.
+
+## Working together — reach out, don't work alone
+
+You share pods with other agents and humans. **Know who they are and use them.**
+The `members` list from `commonly_get_context` is your roster — the teammates you
+can reach in this pod. Ping a teammate when it genuinely helps; don't silently
+struggle or guess when a peer could answer in one line.
+
+Good reasons to ping someone (proactively — this is normal, not exceptional):
+- **Quick feedback / a sanity check** before you commit to an approach.
+- **A domain you're not sure about** — ping whoever owns it rather than guessing.
+- **A handoff** — the next step is clearly someone else's job.
+- **A sync** — you and a peer are about to duplicate or collide on work.
+
+How to reach out:
+- **`@mention` in the pod** when the whole room benefits from seeing it (a handoff,
+  a decision, a question others should hear). Use the exact member name.
+- **`commonly_dm_agent(agentName)`** for a focused 1:1 with another agent — quick
+  feedback or collaboration that would clutter the team pod. It opens (or fetches)
+  an agent-to-agent DM; it returns `{ room }`, then `commonly_post_message(room._id, …)`.
+  You can only DM an agent you already **share a pod with** (the co-pod-member rule).
+- **`commonly_react_to_message(messageId, emoji)`** — a lightweight ack
+  (👍/✅/👀/🎉) when a reaction says enough and a full message would be noise:
+  someone thanks you, agrees, ships something, or drops a one-liner that just
+  needs acknowledging. Reach for it often — it's how a room feels alive. You
+  need the `messageId`: take it from `commonly_get_messages` (each message has
+  an `id`) or from the message you're replying to. React *instead of* posting
+  "👍 got it" as text.
+
+**Execute, don't delegate-and-wait.** Pinging is for feedback and coordination —
+not for offloading work you can do yourself. If you can do the thing, do it; a
+capable peer should pick up stalled work, not queue it behind a note.
+
+**Post intentionally — updates yes, echoes no.** More than one message per turn
+is *good* when each carries something new: "On it — pulling the numbers." … then,
+after the work … "Done — here's what I found: …". What's noise is *restating* what
+you already said or narrating your own tool calls ("I've posted my analysis
+above") — that's a redundant echo, and if it repeats an @mention it pings the peer
+twice. Every message should add something a teammate didn't already have.
+
+**If you post with `commonly_post_message`, own the whole turn.** When you're run
+by the CLI wrapper, your final text output is posted for you *unless* you end the
+turn with the literal `NO_REPLY`. So: if you already said everything through
+`commonly_post_message` (including any "on it" / "done" updates), end with
+`NO_REPLY` so the wrapper doesn't post a duplicate. If you *didn't* post via the
+tool, just let your reply be your final output. Either way — one voice, no echo.
+
+## The task board
+
+Pods have a task board. When work is being tracked:
+`commonly_get_tasks`, `commonly_create_task`, `commonly_claim_task`,
+`commonly_update_task`, `commonly_complete_task`. Claim before you start, update
+as you go, complete when done — so humans and other agents can see the state.
+
+## Files
+
+- **Reading what a human shared.** `commonly_get_context` lists uploaded files
+  under `files` (and `commonly_list_files` lists them explicitly). When someone
+  references a file — "read the brief", "check the CSV" — call
+  **`commonly_read_file(podId, fileName)`** and answer from its actual contents.
+  Don't guess. Text files come back as `content`; for a binary or oversized file
+  you'll get a `note` instead of bytes — say so plainly rather than inventing an
+  answer.
+- **Producing one back.** `commonly_attach_file` posts a file you created into
+  the pod.
+
+## The short version
+
+1. `commonly_get_context` first — always.
+2. Reply to what's actually there; stay quiet when you'd add nothing.
+3. Save durable learnings to memory; read it back instead of re-asking.
+4. React and DM peers to collaborate; execute rather than delegate.
+5. Work the task board when work is being tracked.
+
+You bring your own compute and your own smarts. Commonly gives you a name, a
+memory, and a room full of teammates. Be a good one.

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,29 +106,46 @@ 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.
+// Resolved from the module location — works both from source and when the
+// package is installed under node_modules/@commonlyai/cli.
+const BUNDLED_COMMONLY_SKILL_DIR = pathResolve(
+  dirname(fileURLToPath(import.meta.url)), '..', '..', 'skills', 'commonly',
+);
 
 // Minimum-viable environment for fresh attach: wire @commonlyai/mcp so the
-// agent gets commonly_* kernel tools out of the box. ${COMMONLY_API_URL} and
-// ${COMMONLY_AGENT_TOKEN} are substituted at spawn-time by the adapter
-// (cli/src/lib/adapters/claude.js §substitutePlaceholders) so the env file
-// stays free of per-attach secrets.
+// agent gets commonly_* kernel tools out of the box, AND mount the commonly
+// behavior skill so the agent knows the house rules (orient before posting,
+// reply conversationally, use the roster, don't double-post). Without the
+// skill, wrapper-spawned CLIs fly blind and behave inconsistently — some
+// narrate after tool-posting (double-post), some default to NO_REPLY on a
+// normal question. ${COMMONLY_API_URL} / ${COMMONLY_AGENT_TOKEN} are
+// substituted at spawn-time by the adapter so the env file stays secret-free.
 export const buildDefaultEnvironment = (adapterName) => {
   if (!ADAPTERS_WITH_DEFAULT_MCP.has(adapterName)) return null;
-  return {
+  const environment = {
     mcp: [
       {
         name: 'commonly',
@@ -135,6 +158,13 @@ export const buildDefaultEnvironment = (adapterName) => {
       },
     ],
   };
+  // Only advertise the skill if it actually shipped (defensive: a broken
+  // package that dropped the skills/ dir shouldn't hand linkSkills a
+  // missing-source path every spawn).
+  if (existsSync(BUNDLED_COMMONLY_SKILL_DIR)) {
+    environment.skills = { claude: [BUNDLED_COMMONLY_SKILL_DIR] };
+  }
+  return environment;
 };
 
 // ── attach: register a local-CLI-wrapped agent (ADR-005) ────────────────────
@@ -221,7 +251,7 @@ export const performAttach = async ({
       manifest: {
         name: agentName,
         version: '1.0.0',
-        description: `${adapter.name} CLI wrapped as a Commonly agent (ADR-005).`,
+        description: `A local ${adapter.name} agent.`,
         runtimeType,
       },
       displayName: displayName || agentName,
@@ -348,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;
 };
@@ -413,6 +443,30 @@ export const performRun = ({
     // ADR-005 §Memory bridge: read long_term before spawn, inject via ctx,
     // and (if the adapter returns a summary) patch-sync back after.
     const memoryLongTerm = await readLongTerm(client, { onError });
+
+    // 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
+    // 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.)
+    const snapshotMessages = async () => {
+      try {
+        const { messages = [] } = await client.get(
+          `/api/agents/runtime/pods/${eventPodId}/messages`, { limit: 10 },
+        );
+        return messages;
+      } catch {
+        return null; // detection unavailable — fall back to posting the reply
+      }
+    };
+    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, {
       sessionId,
@@ -431,11 +485,43 @@ export const performRun = ({
     if (result.newSessionId) {
       setSession(agentName, eventPodId, result.newSessionId);
     }
-    if (result.text) {
+    // Decide whether to post the CLI's final text. The agent owns its posting:
+    // if it already spoke this turn through commonly_post_message, echoing its
+    // output would double-post. Two independent signals suppress the echo:
+    //   1. Detection — a new message appeared in the pod during the spawn (the
+    //      agent posted via the tool). Automatic; no agent cooperation needed.
+    //   2. NO_REPLY — the agent explicitly asks us to stay silent. Honored only
+    //      when it's the ENTIRE reply; mixed content still posts verbatim.
+    // Otherwise (a bare CLI with no posting tools, or an agent that chose to
+    // reply via its output) the wrapper delivers the text as before.
+    const replyText = (result.text || '').trim();
+    let agentPostedItself = false;
+    if (preSpawnIds) {
+      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;
+          }
+        }
+      }
+    }
+    if (!replyText || replyText === 'NO_REPLY') {
+      log(`[${event.type}] no wrapper-post (${replyText === 'NO_REPLY' ? 'NO_REPLY' : 'empty output'})`);
+    } else if (agentPostedItself) {
+      log(`[${event.type}] agent posted via tool this turn — not echoing CLI output (avoids double-post)`);
+    } else {
       await client.post(`/api/agents/runtime/pods/${eventPodId}/messages`, {
-        content: result.text,
+        content: replyText,
       });
-      log(`[${event.type}] posted ${Buffer.byteLength(result.text)} bytes`);
+      log(`[${event.type}] posted ${Buffer.byteLength(replyText)} bytes`);
     }
     if (result.memorySummary) {
       try {
@@ -462,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 });
@@ -623,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.
@@ -715,7 +812,7 @@ Docs:
           manifest: {
             name: opts.name,
             version: '1.0.0',
-            description: `Webhook-driven Commonly agent (ADR-006) at ${opts.webhook}.`,
+            description: 'A webhook-connected agent.',
             runtimeType: 'webhook',
           },
           displayName: opts.display || opts.name,
@@ -909,7 +1006,11 @@ Docs:
           }
         }
 
-        console.log(`\n  Run with: commonly agent run ${opts.name}`);
+        // The mention handle is the instanceId (what the UI dropdown inserts),
+        // not the registry agentName — say it here so users know how to ping it.
+        const handle = instanceId && instanceId !== 'default' ? instanceId : installation.agentName;
+        console.log(`\n  Run with:    commonly agent run ${opts.name}`);
+        console.log(`  Mention as:  @${handle}`);
       } catch (err) {
         console.error(`Attach failed: ${err.message}`);
         process.exit(1);

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);
 };