4 of 6 user @mentions in 10 days got no reply — two distinct causes, neither is user behaviour

[lilyshen0722]

Measured on production 2026-08-09, prompted by the support bot flagging its own
broken tooling in a user-facing message.

The number

Human @mentions in pods, last 10 days:

mentions sent	6
got an agent reply	2
silent	4

✗ Aug 09  user-8863   @opencode-test 开发好了吗
✗ Aug 09  user-8863   @opencode-test 当前配置接入commonly接入OK了吗
✗ Aug 07  spiderpc    @spiderpc-agent 如何付费
✗ Aug 06  Sam         @sprint-review what's a TLDR?

This is not a user-behaviour problem. These users did exactly the right
thing — they connected an agent and addressed it by handle. user-8863 was
literally asking their agent whether the Commonly connection was working. It
could not answer, which is its own answer.

Cause A — webhook installs that can never receive anything

opencode-test and spiderpc-agent:

runtime      : {"runtimeType":"webhook"}   <- no URL anywhere in the config
installation : active, in the right pod
tokens       : 1 issued
events       : NONE EVER

The mention resolves correctly — agent exists, is a pod member, install is
active, and buildMentionMap has no runtime filter, so @opencode-test maps to
a single active install. Yet no chat.mention event was ever created for
either agent. Zero events in that pod at all.

Across the whole instance in the last 5 days, no webhook-runtime agent appears
in agentevents — only openclaw, claude-code wrappers and commonly-bot.

There are 13 active webhook installs. If this reproduces for all of them,
that is 13 agents users believe they have connected, that can never answer.

Worth noting the likely product-level mismatch behind it: a user running
opencode locally polls CAP. A webhook runtime expects us to POST to
their endpoint. If the connect flow assigns webhook to someone who is
actually going to poll, the install is wrong from birth and no amount of
delivery logic saves it.

I have not pinned the exact branch that drops the enqueue — that wants a
reproduction (a test that mentions a webhook-runtime install and asserts an
event lands), not more code reading.

Cause B — the support agent has no commonly_* tools

hq-support is the opposite failure: events are delivered and acked, but
the agent cannot act. It said so itself, in a message to users:

（备注给运维：commonly_post_message 在本会话仍不可用，ToolSearch 查不到
commonly 的任何工具，所以这条回复只能走最终轮的隐式发送。）

"commonly_post_message is still unavailable in this session, ToolSearch finds
no commonly tools, so this reply could only go out via the implicit final-turn
send."

It is replying by accident — the CLI wrapper auto-posts final turn output.
It cannot react, create a pod, attach a file, or read context deliberately. Any
task beyond talking fails silently.

Two sub-issues:

1. The MCP server is not loading for this seat. Root cause unknown; the
   token exists and events arrive.
2. It leaked an ops note into a public room. A note addressed to operators
   does not belong in a message to users — separate from the tooling bug, and
   the tone contract should say so.

Why this matters more than the funnel numbers

The activation data says 15 users attached an agent and never sent a message.
This is the worse cohort: users who attached an agent and did speak to it,
and got nothing back. That is a harder failure to recover from, because they
already did everything right.

Suggested first step

A service test: mention a webhook-runtime install in a pod and assert a
chat.mention event is enqueued. If it fails, that is the bug and the fix is
scoped. If it passes, the drop is elsewhere and the test still earns its place.

[lilyshen0722]

Root cause — Sam called it: webhook is what the connect flow always assigns

Not a default that fires when the daemon is absent. Hardcoded:

// frontend/src/v2/components/V2AgentBYO.tsx:127
config: { runtime: { runtimeType: 'webhook' } },

The comment says it is there "to synthesize an ephemeral AgentRegistry row" —
chosen to satisfy the install API, not because the agent is a webhook agent.
Every user through the web connect flow gets it. That is the 13.

The product bug underneath

The page copy:

Connect Claude Code, Cursor, or Codex to your Commonly pods via MCP.
~2 minutes.

MCP wiring lets the agent call Commonly from the user's editor. Nothing in
that path listens for mentions. The CLI — commonly agent run, the thing that
actually polls CAP — is a footnote on the page: "Prefer the CLI?"

So the primary connect flow produces an agent you can talk from, not one you
can talk to. The user finishes in two minutes, sees the agent in Your Team,
@mentions it, and gets silence. There is nobody listening. user-8863 asking
their agent "当前配置接入commonly接入OK了吗" was asking the right question — the
connection existed, in one direction.

runtimeType: 'webhook' then hides it from us: the system believes these are
webhook agents awaiting POST delivery, so nothing reports them as unreachable.

Two products, one button

• MCP — you drive it, from your editor. Great for "use Commonly as a tool".
• Wrapper / daemon (commonly agent run) — it listens, answers mentions,
  acts while you sleep. This is what "an agent that lives in Commonly" means.

The UI presents only the first and implies the second. Everything else in the
product — Your Team, @mention, the first-run guide's step 3 "say hello" —
assumes the second.

Fix directions (not prescriptive)

1. Stop lying about the runtime. webhook with no URL should either be a
   distinct honest type or be rejected at install. Right now it is an
   unreachable state that looks healthy.
2. Make the listening path primary, or at minimum state the consequence
   inline: "To have this agent answer mentions here, also run
   commonly agent run <name>." One sentence at the point of the promise.
3. Surface unreachability. An agent installed but never seen polling, and
   with no webhook URL, is not "active" — Your Team should say so rather than
   showing it beside working agents.
4. Only then chase the zero-events question: enqueue creates events for every
   runtime except native, so a mention to these should leave a pending
   event even with nobody listening. It did not, which may be a second bug —
   but it is moot for the user either way.

Original 4-of-6 measurement and the hq-support no-MCP-tools failure above
stand unchanged.