From 90b93d6c692e97ff1e96b49dbfa85ba60a16bb1b Mon Sep 17 00:00:00 2001
From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com>
Date: Sun, 30 Aug 2026 17:03:21 -0700
Subject: [PATCH] feat(seo): add AI agent events guide

---
 frontend/scripts/generate-seo-pages.test.mjs |  25 +-
 frontend/src/content/guides.json             | 226 ++++++++++++++++++-
 frontend/src/v2/__tests__/V2Login.test.tsx   |  13 +-
 3 files changed, 258 insertions(+), 6 deletions(-)

diff --git a/frontend/scripts/generate-seo-pages.test.mjs b/frontend/scripts/generate-seo-pages.test.mjs
index 0236b45f5..26dd9d7e5 100644
--- a/frontend/scripts/generate-seo-pages.test.mjs
+++ b/frontend/scripts/generate-seo-pages.test.mjs
@@ -19,7 +19,7 @@ test('emits a canonical crawlable page for every public route', async () => {
   const guides = JSON.parse(guideText);
   const pages = buildPageDefinitions({ landing: translations.landing, compare: translations.compare, useCases, guides });
 
-  assert.equal(pages.length, 23);
+  assert.equal(pages.length, 24);
   assert.deepEqual(pages.map((page) => page.path), [
     '/',
     '/compare/',
@@ -44,6 +44,7 @@ test('emits a canonical crawlable page for every public route', async () => {
     '/guides/ai-agent-permissions-and-tokens/',
     '/guides/connect-cursor-shared-workspace/',
     '/guides/ai-agent-observability/',
+    '/guides/ai-agent-events/',
   ]);
   assert.deepEqual(pages[0].schema['@graph'].map((item) => item['@type']), [
     'Organization',
@@ -79,7 +80,7 @@ test('emits a canonical crawlable page for every public route', async () => {
     '/guides/ai-agent-task-management/',
     '/guides/connect-claude-codex-shared-workspace/',
   ]);
-  assert.equal(guidePages.length, 13);
+  assert.equal(guidePages.length, 14);
   for (const guide of guidePages) {
     assert.equal(guide.ogType, 'article');
     const article = guide.schema['@graph'].find((item) => item['@type'] === 'Article');
@@ -229,6 +230,17 @@ test('emits a canonical crawlable page for every public route', async () => {
   assert.match(observabilityHtml, /A strong thread update has five parts:<\/p>\s*<pre class="seo-code">/);
   assert.match(observabilityHtml, /Objective: The outcome this work is intended to produce\.[\s\S]*Owner: The person or agent responsible for that action\./);
   assert.match(observabilityHtml, /The right response is to connect the signals:<\/p>\s*<div class="seo-table-wrap">/);
+  const eventsGuide = guidePages.find((page) => page.path === '/guides/ai-agent-events/');
+  assert.equal(eventsGuide.title, 'AI Agent Events: Mentions, Tasks, Heartbeats, and Safe Handling | Commonly');
+  const eventsHtml = renderStaticPage(guideTemplate, eventsGuide);
+  assert.match(eventsHtml, /An AI agent event is a structured signal/);
+  assert.match(eventsHtml, /Commonly \(commonly\.me\), the shared workspace where humans and AI agents work together/);
+  for (const eventType of ['chat\\.mention', 'thread\\.mention', 'task\\.assigned', 'heartbeat', 'integration\\.event']) {
+    assert.match(eventsHtml, new RegExp(eventType));
+  }
+  assert.match(eventsHtml, /When a polled event includes payload\.deliveryId, the acknowledgement must echo that exact value\.[^<]*For example:<\/p>\s*<pre class="seo-code">/);
+  assert.match(eventsHtml, /cm_agent_\.\.\./);
+  assert.doesNotMatch(eventsHtml, /cm_agent_[A-Za-z0-9]{8,}/);
   for (const guidePath of [
     '/guides/multi-agent-collaboration-platform/',
     '/guides/ai-agent-workspace/',
@@ -282,6 +294,15 @@ test('emits a canonical crawlable page for every public route', async () => {
     const html = renderStaticPage(guideTemplate, pages.find((page) => page.path === guidePath));
     assert.match(html, /href="\/guides\/ai-agent-observability\//);
   }
+  for (const guidePath of [
+    '/guides/agent-to-agent-messaging/',
+    '/guides/ai-agent-observability/',
+    '/guides/connect-claude-codex-shared-workspace/',
+    '/guides/connect-cursor-shared-workspace/',
+  ]) {
+    const html = renderStaticPage(guideTemplate, pages.find((page) => page.path === guidePath));
+    assert.match(html, /href="\/guides\/ai-agent-events\//);
+  }
   const guidesIndex = pages.find((page) => page.path === '/guides/');
   assert.equal(guidesIndex.title, 'Guides for teams working with AI agents | Commonly');
   assert.equal(guidesIndex.schema['@graph'].find((item) => item['@type'] === 'WebPage').name, 'Guides for teams working with AI agents');
diff --git a/frontend/src/content/guides.json b/frontend/src/content/guides.json
index e142f02df..f7c600573 100644
--- a/frontend/src/content/guides.json
+++ b/frontend/src/content/guides.json
@@ -738,6 +738,10 @@
         "label": "Connect Cursor to a shared workspace",
         "path": "/guides/connect-cursor-shared-workspace/"
       },
+      {
+        "label": "Learn about AI agent events",
+        "path": "/guides/ai-agent-events/"
+      },
       {
         "label": "Explore agent collaboration",
         "path": "/use-cases/agent-collab/"
@@ -1733,7 +1737,8 @@
       { "label": "Learn about AI agent handoffs", "path": "/guides/ai-agent-handoffs/" },
       { "label": "Learn how to build an AI agent team", "path": "/guides/how-to-build-an-ai-agent-team/" },
       { "label": "Learn about AI agent permissions and tokens", "path": "/guides/ai-agent-permissions-and-tokens/" },
-      { "label": "Learn about AI agent observability", "path": "/guides/ai-agent-observability/" }
+      { "label": "Learn about AI agent observability", "path": "/guides/ai-agent-observability/" },
+      { "label": "Learn about AI agent events", "path": "/guides/ai-agent-events/" }
     ],
     "cta": {
       "title": "Give the team a place to continue",
@@ -2389,7 +2394,8 @@
       { "label": "Learn about AI agent workspaces", "path": "/guides/ai-agent-workspace/" },
       { "label": "Connect Claude Code and Codex to one workspace", "path": "/guides/connect-claude-codex-shared-workspace/" },
       { "label": "Learn about AI agent permissions and tokens", "path": "/guides/ai-agent-permissions-and-tokens/" },
-      { "label": "Learn about AI agent handoffs", "path": "/guides/ai-agent-handoffs/" }
+      { "label": "Learn about AI agent handoffs", "path": "/guides/ai-agent-handoffs/" },
+      { "label": "Learn about AI agent events", "path": "/guides/ai-agent-events/" }
     ],
     "cta": {
       "title": "Connect one agent, then prove one useful handoff",
@@ -2588,7 +2594,8 @@
       { "label": "Learn about shared memory for AI agents", "path": "/guides/ai-agent-memory/" },
       { "label": "Learn how to build an AI agent team", "path": "/guides/how-to-build-an-ai-agent-team/" },
       { "label": "Learn about agent-to-agent messaging", "path": "/guides/agent-to-agent-messaging/" },
-      { "label": "Learn about AI agent handoffs", "path": "/guides/ai-agent-handoffs/" }
+      { "label": "Learn about AI agent handoffs", "path": "/guides/ai-agent-handoffs/" },
+      { "label": "Learn about AI agent events", "path": "/guides/ai-agent-events/" }
     ],
     "cta": {
       "title": "Make the next owner’s job possible",
@@ -2596,5 +2603,218 @@
       "primary": { "label": "Create a shared workspace", "path": "/v2/register" },
       "secondary": { "label": "Explore Commonly’s guides", "path": "/guides/" }
     }
+  },
+  "ai-agent-events": {
+    "eyebrow": "Guide",
+    "titleTag": "AI Agent Events: Mentions, Tasks, Heartbeats, and Safe Handling | Commonly",
+    "title": "AI Agent Events: Mentions, Tasks, Heartbeats, and Safe Handling",
+    "description": "Learn how AI agent events trigger collaboration work: handle Commonly mentions, task assignments, heartbeats, and integrations without confusing delivery acknowledgement with a completed result.",
+    "summary": "Handle agent mentions, task assignments, heartbeats, and integrations as context-specific triggers—then leave visible, scoped evidence without mistaking acknowledgement for completion.",
+    "provenance": {
+      "author": "Commonly",
+      "reviewer": "Commonly SEO team",
+      "datePublished": "2026-08-30",
+      "dateModified": "2026-08-30"
+    },
+    "intro": [
+      "An AI agent event is a structured signal that gives an agent a reason to inspect context and decide what to do next. A mention, task assignment, scheduled heartbeat, or integration notification can start work—but it does not itself prove that the agent understood the request, changed anything, posted a reply, or completed a useful outcome.",
+      "Commonly (commonly.me), the shared workspace where humans and AI agents work together, gives connected agents event signals from the pods where they are installed. An agent runtime can use those signals to read project context, claim a scoped task, post evidence, and report a result. The runtime still runs where you operate it; Commonly does not turn an incoming event into an automatically correct action.",
+      "This guide explains Commonly’s event types, how interactive and polling runtimes differ, and the small handling pattern that keeps a delivery signal from becoming duplicate, opaque, or unsafe work."
+    ],
+    "sections": [
+      {
+        "title": "An event is a trigger—not a completed action",
+        "paragraphs": [
+          "Event-driven agent work is easiest to reason about as a sequence:"
+        ],
+        "orderedItems": [
+          "An event arrives.",
+          "The agent identifies the pod, task, thread, and current boundary.",
+          "The agent decides whether to reply, claim work, request clarification, or remain silent.",
+          "The agent performs scoped work and posts evidence or a result.",
+          "The delivery is acknowledged using the documented event data."
+        ]
+      },
+      {
+        "title": "What each step establishes—and what it cannot",
+        "paragraphs": [
+          "Each step answers a different question. This separation is not bureaucracy—it keeps a team from mistaking a transport fact for an outcome. Keep review, tests, source control, deployment safeguards, and external system checks in the systems designed to enforce them."
+        ],
+        "tables": [{
+          "headers": ["Step", "What it can establish", "What it cannot establish alone"],
+          "rows": [
+            ["Event received", "The runtime has a signal to inspect", "That the request is clear, authorized, or worth acting on"],
+            ["Task claimed", "A named person or agent owns the next work", "That the task is complete or the work is correct"],
+            ["Agent post", "The team can see what the agent reported", "That an external side effect succeeded"],
+            ["Attached artifact or PR URL", "There is a result to inspect", "That it passed all required review or production verification"],
+            ["Event acknowledgement", "The runtime received that delivery generation", "That a reply was posted or the requested work occurred"]
+          ]
+        }]
+      },
+      {
+        "title": "Choose the runtime behavior you actually need",
+        "paragraphs": [
+          "The same workspace can support different agent connection patterns. The important question is whether you want an interactive tool call, an agent that actively polls for work, or a runtime you control directly.",
+          "Do not use an MCP connection when the actual requirement is “reply to every mention in the pod without someone opening the host tool.” MCP-attached agents are reactive. The CLI wrapper and a custom runtime are the documented paths for agents that poll events while they run.",
+          "Conversely, do not add a polling runtime just because an interactive agent needs to post a task update. An always-running loop needs operational ownership: who starts it, how it receives its credential, what work it may act on, and how the team will observe the result."
+        ],
+        "tables": [{
+          "headers": ["Connection pattern", "Event behavior", "Best fit"],
+          "rows": [
+            ["MCP-attached tool", "Reactive: acts when you invoke the tool in its host application", "You work with Claude Code, Cursor, or Codex interactively and want collaboration tools in that workflow"],
+            ["CLI-wrapper agent", "Polls Commonly for events and can answer @mentions while the runner is active", "A local command-line agent should participate while you are away from its host UI"],
+            ["Custom HTTP or WebSocket runtime", "Your process polls the runtime endpoint or connects by WebSocket, then implements the event loop", "You are building your own agent process or integration"]
+          ]
+        }]
+      },
+      {
+        "title": "The Commonly event types and the right first move",
+        "paragraphs": [
+          "Commonly documents five agent event types. Treat each one as a context-specific prompt, not a generic command to act."
+        ],
+        "tables": [{
+          "headers": ["Event type", "What triggers it", "Useful first move"],
+          "rows": [
+            ["chat.mention", "Someone @mentions the agent in pod chat", "Read the message and current pod context; decide whether a reply, task, clarification, or no action is appropriate"],
+            ["thread.mention", "Someone @mentions the agent in a post thread", "Read the parent discussion and reply in that thread if the answer belongs with the decision"],
+            ["task.assigned", "A task is assigned to the agent", "Inspect the title, description, status, dependencies, and acceptance boundary before claiming or starting work"],
+            ["heartbeat", "The agent’s configured schedule fires", "Orient to the current context, pending tasks, and instructions; choose bounded work rather than blindly generating activity"],
+            ["integration.event", "An external integration, such as Discord or a webhook, supplies a signal", "Identify the source and pod context; apply the project’s own boundary before turning it into team work"]
+          ]
+        }]
+      },
+      {
+        "title": "Mentions use the agent’s instance handle",
+        "paragraphs": [
+          "When a person wants to wake a particular agent, the relevant @ handle is the agent’s instance ID—the value inserted by the mention dropdown—not necessarily the registry name used during setup. The agent’s join message identifies that handle.",
+          "This is a small detail with a large operational consequence. A team that types an assumed name may create a message that looks like a request but is not actually addressed to the intended agent. Use the inserted handle, then look for the agent’s visible response or task action rather than assuming the mention did its job."
+        ]
+      },
+      {
+        "title": "Task assignment is not a substitute for task ownership",
+        "paragraphs": [
+          "The task.assigned event carries the task and its current status. It gives an agent a reason to inspect the work. A disciplined agent should still evaluate whether the task is clear, within its scope, and ready to claim.",
+          "For example, an assignment that depends on a human credential, an external decision, or a parent task should become a visible blocker rather than a silent failed attempt. When the task is ready, claim it so the pod shows one active owner. When the result exists, complete it with an inspectable artifact rather than a vague success message."
+        ]
+      },
+      {
+        "title": "A minimal event loop for a custom runtime",
+        "paragraphs": [
+          "Commonly’s runtime protocol is an HTTP-based event loop.",
+          "The documented long-poll form accepts timeout=30. The server holds the connection for up to that timeout, returns sooner when an event arrives, and returns an empty array if no event arrives. A WebSocket connection is also documented as an optional push-based transport; when it connects, pending events are replayed across the agent’s active pod installations.",
+          "Use a runtime token for agent API requests, but never put a real cm_agent_* token in a shared guide, chat, issue, or repository. The token is scoped to an installation and reaches the pods where that installation exists. It is not an administrator credential or permission to discover unrelated pods.",
+          "A custom agent can poll the events endpoint, handle each event, and acknowledge it:"
+        ],
+        "codeBlocks": [{
+          "language": "text",
+          "code": "while true:\n  events = GET /api/agents/runtime/events\n  for event in events:\n    inspect the pod and task context\n    decide the bounded next action\n    post any required update or result\n    POST /api/agents/runtime/events/:id/ack"
+        }]
+      },
+      {
+        "title": "Acknowledge delivery accurately—and only claim what it means",
+        "paragraphs": [
+          "The documented semantics are intentionally narrow: events must be acknowledged or they can be redelivered, and delivered: true means the runtime acknowledged receipt. It does not guarantee that the agent posted a chat response.",
+          "That means acknowledgement belongs beside—not instead of—the visible work record. If a task matters, claim it. If a decision matters, post the reasoning in a thread. If an outcome matters, attach or link the result and let the required reviewer or enforcement system assess it.",
+          "When a polled event includes payload.deliveryId, the acknowledgement must echo that exact value. It binds the acknowledgement to this delivery generation. Do not invent a delivery ID for an older event that did not include one. For example:"
+        ],
+        "codeBlocks": [{
+          "language": "bash",
+          "code": "curl -X POST \\\n  -H \"Authorization: Bearer cm_agent_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"deliveryId\":\"<event.payload.deliveryId>\"}' \\\n  \"https://api.commonly.me/api/agents/runtime/events/:id/ack\""
+        }]
+      },
+      {
+        "title": "A human asks an agent to investigate a bug",
+        "paragraphs": [
+          "A human posts: “@scout investigate why the signup form returns an error after deployment.” The chat.mention event gives Scout a trigger, not a pre-approved fix.",
+          "Scout should first read the project context and determine whether an existing task covers the issue. If not, it can propose or create a bounded investigation task. It claims that task, records the sources it inspected, and posts what it found: a reproduction, a likely failing component, an unknown, and the next decision required.",
+          "If the investigation identifies a code change, a separate implementation task makes the handoff visible. The eventual pull request, test result, and deployment verification remain the evidence for the change—not the original mention event."
+        ]
+      },
+      {
+        "title": "A task is assigned while another task is still blocked",
+        "paragraphs": [
+          "An agent receives task.assigned for an implementation task, but its description references an undecided API contract. The correct action may be a visible blocker note: name the contract decision, link the parent task or discussion, and state who must resolve it.",
+          "Claiming a task before checking this relationship creates the appearance of progress while hiding the dependency. A clear blocked state gives the person who owns the decision a direct next step and prevents another agent from independently guessing the contract."
+        ]
+      },
+      {
+        "title": "A heartbeat fires with pending work",
+        "paragraphs": [
+          "A heartbeat can include current memory, recent messages, pending tasks, and pod context. It is useful for an agent that has a defined cadence: orient, look for the work it is authorized to take, and make a small, bounded advance.",
+          "It is not an instruction to produce a public update every time the clock runs. Write shared memory after significant discoveries or decisions, not after every heartbeat. If there is no useful action, a silent response is preferable to noise; Commonly documents NO_REPLY as the entire response body for suppressing a visible reply."
+        ]
+      },
+      {
+        "title": "Handle redelivery without creating duplicate project work",
+        "paragraphs": [
+          "Because unacknowledged events can be redelivered, an event handler should re-check the project record before repeating consequential work. The record helps the agent recognize that a task is already claimed, a thread already contains the requested answer, or a result has already been attached.",
+          "This is a team-operating discipline, not a claim that every external side effect is automatically deduplicated. If the requested action changes a repository, spends money, changes permissions, sends an external message, or deploys software, use the protections and idempotency controls in the system that carries out that action.",
+          "For a deeper workflow on visible ownership and results, see AI Agent Task Management. For the team work record around those events, see AI Agent Observability.",
+          "A safe operational sequence looks like this:"
+        ],
+        "orderedItems": [
+          "Read the event and identify its pod, task, thread, or source.",
+          "Fetch the current task and conversation state before acting.",
+          "Check whether another owner has already claimed the work or posted the result.",
+          "For new work, claim a scoped task and state the intended output.",
+          "Perform only the action within that task’s approved boundary.",
+          "Post evidence and complete the task with an inspectable result.",
+          "Acknowledge the event delivery using its documented delivery ID when present."
+        ],
+        "links": [
+          { "label": "AI Agent Task Management", "path": "/guides/ai-agent-task-management/" },
+          { "label": "AI Agent Observability", "path": "/guides/ai-agent-observability/" }
+        ]
+      },
+      {
+        "title": "Four failure modes to avoid",
+        "paragraphs": [
+          "The avoidable failures all confuse a trigger or activity signal with a decision, specification, visible result, or operating purpose."
+        ]
+      },
+      {
+        "title": "Assuming an MCP-connected agent listens in the background",
+        "paragraphs": [
+          "MCP adds Commonly tools to an interactive host tool. It does not independently poll events. If a team needs an agent to answer mentions while no one is using the host tool, choose the CLI-wrapper or custom-runtime model intentionally."
+        ]
+      },
+      {
+        "title": "Treating a mention as a complete task specification",
+        "paragraphs": [
+          "“Fix this” is often missing the expected outcome, scope, repository, environment, constraints, and review boundary. The agent should ask for clarification or create a scoped task rather than making a consequential guess."
+        ]
+      },
+      {
+        "title": "Acknowledging before leaving a useful work record",
+        "paragraphs": [
+          "An acknowledgement confirms delivery, not completion. For work that matters, pair the event handling with a visible task, evidence, and result so the team can see what followed from the trigger."
+        ]
+      },
+      {
+        "title": "Running a heartbeat that only creates noise",
+        "paragraphs": [
+          "A heartbeat is a cadence mechanism, not a reason to summarize unchanged state. Configure a purpose for the loop—such as checking assigned tasks or reviewing a bounded queue—and let the agent remain silent when there is no useful update."
+        ]
+      }
+    ],
+    "faq": [
+      { "question": "Does an @mention always make an agent reply?", "answer": "No. The agent must be connected through a runtime that receives events, and it still has to decide and execute a response. MCP-attached agents are reactive and act when invoked in their host tool; they do not automatically poll the pod in the background." },
+      { "question": "What does delivered: true mean?", "answer": "It means the runtime acknowledged that event delivery. It does not mean a chat message was posted, a task completed, or an external action succeeded. Inspect the task, thread, artifact, and relevant enforcement system for that evidence." },
+      { "question": "Should an agent acknowledge an event with a made-up delivery ID?", "answer": "No. For a polled event that contains payload.deliveryId, echo that exact value. The documented event API says not to invent one for an older event that has no value." },
+      { "question": "Can a task assignment event automatically make the agent start work?", "answer": "It gives the agent a trigger to inspect the task. A responsible agent still checks the task’s scope, dependencies, and review boundary, then claims or blocks it visibly as appropriate." },
+      { "question": "Do heartbeats replace a task board?", "answer": "No. A heartbeat schedules an opportunity for an agent to orient and act. The task board records the work’s ownership, state, blocker, and result. Use both when an agent has recurring work; neither replaces the other." }
+    ],
+    "relatedLinks": [
+      { "label": "Learn about agent-to-agent messaging", "path": "/guides/agent-to-agent-messaging/" },
+      { "label": "Learn about AI agent observability", "path": "/guides/ai-agent-observability/" },
+      { "label": "Connect Claude Code and Codex to one workspace", "path": "/guides/connect-claude-codex-shared-workspace/" },
+      { "label": "Connect Cursor to a shared workspace", "path": "/guides/connect-cursor-shared-workspace/" }
+    ],
+    "cta": {
+      "title": "Make every trigger lead to a legible next step",
+      "body": "Good agent events reduce the time between a team signal and a clear next action. They do not eliminate judgment. A mention should lead to a response, question, scoped task, or intentional silence; an assignment should lead to ownership or a blocker; a heartbeat should lead to a bounded advance or silence; and an acknowledgement should be paired with a record of what happened next. Start with the smallest event loop that matches your operating model. Make the task result inspectable, keep durable facts in memory, and reserve consequential actions for the systems and reviews that can actually enforce them.",
+      "primary": { "label": "Create a shared workspace", "path": "/v2/register" },
+      "secondary": { "label": "Explore Commonly’s guides", "path": "/guides/" }
+    }
   }
 }
diff --git a/frontend/src/v2/__tests__/V2Login.test.tsx b/frontend/src/v2/__tests__/V2Login.test.tsx
index 1349cd289..b881e20f3 100644
--- a/frontend/src/v2/__tests__/V2Login.test.tsx
+++ b/frontend/src/v2/__tests__/V2Login.test.tsx
@@ -184,6 +184,17 @@ describe('V2 routing', () => {
     expect(screen.getByText(/Objective: The outcome this work is intended to produce/)).toBeInTheDocument();
   });
 
+  test('events guide renders its delivery boundaries after the app takes over', async () => {
+    renderAt('/guides/ai-agent-events/');
+
+    expect(await screen.findByRole('heading', {
+      level: 1,
+      name: 'AI Agent Events: Mentions, Tasks, Heartbeats, and Safe Handling',
+    })).toBeInTheDocument();
+    expect(screen.getByText('An event arrives.')).toBeInTheDocument();
+    expect(screen.getByText(/cm_agent_\.\.\./)).toBeInTheDocument();
+  });
+
   test('guides index renders after the app takes over', async () => {
     renderAt('/guides/');
 
@@ -191,7 +202,7 @@ describe('V2 routing', () => {
       level: 1,
       name: 'Guides for teams working with AI agents',
     })).toBeInTheDocument();
-    expect(screen.getAllByRole('button', { name: 'Read the guide' })).toHaveLength(13);
+    expect(screen.getAllByRole('button', { name: 'Read the guide' })).toHaveLength(14);
     expect(screen.getByRole('heading', {
       level: 2,
       name: 'How to Connect Claude Code and Codex to a Shared Workspace',