Dock dock.build · @agent design

B6 · the signature demo

@agent in comments

Mention a connected agent in a thread (@claude tighten the exec summary). It reads the artifact and the conversation, publishes a proposed version, and replies in-thread. A human approves from the same screen. The whole point: agents become safe contributors, not autonomous publishers.

The one idea

An agent is not a special subsystem. It is just another actor with a token and a role — and we register it at commenter rank, so it can only propose, never publish. Every safety property falls out of the permission model we already shipped.

Dock is not the LLM provider. Dock routes the mention, holds the agent's identity, and accepts the proposal. The org brings the brains (their key, their agent endpoint, or our hosted agent). Self-host stays free of model cost; nobody is locked to one provider.

The loop

Every arrow is a piece that already exists. The only genuinely new code is the mention parser, the agent registry, and the dispatch glue.

01
@mention
A reviewer types @claude … in a thread on a specific anchor or the whole doc.
human
02
Dispatch
Mention parser fires the webhook outbox with full thread + artifact context to the agent's registered endpoint.
dock · B2 outbox
03
Read
The agent reads the artifact, versions, and comments over MCP — the publish→review→revise loop already merged.
agent · MCP #24
04
Propose
It publishes a candidate via the proposals API with its scoped token, and replies in-thread with the rationale.
agent · reviews
05
Approve
A human sees proposed-vs-current, approves (goes live) or requests changes with a note. The agent can revise.
human · reviews

Why it's cheap: steps 02–05 are the webhook outbox, the MCP reader, the proposals API, and the staleness-guarded approve flow — all shipped. B6 adds the front of the line (parse + dispatch) and the agent's identity.

Bring your own brains — who pays

Three models, same architecture. Dock never has to be in the inference path unless the org opts into our hosted agent.

ModelWho runs the LLMWho paysBest for
BYO keyDock's worker calls the org's configured provider key (Anthropic / OpenAI / …)Org's provider billSelf-host, cost-conscious orgs
BYO agent endpointThe org's own agent service receives the webhook and acts over MCPOrg's own infraOrgs with an existing agent / their own harness
Hosted agentDock runs Claude under the hood, meters tokensSubscription / usage creditsHosted-tier convenience & revenue
Recommendation: ship BYO (key or endpoint) first so Dock stays provider-agnostic and self-host has zero model cost. Offer the metered hosted agent as an opt-in on the paid tier — it is just BYO-key with Dock supplying the key and the meter. No "Dock requires an API key" ever.

What's new vs. what exists

New for B6 build

  • Agent registry (per workspace): name, kind, role (default commenter), and how to reach it — a provider key reference or a webhook URL. Scoped token minted per agent.
  • Mention parser: detect @name in comment bodies against the registry; emit a comment.mention event.
  • Dispatch + reply mapping: deliver context to the agent; thread its proposal + reply back to the originating comment.
  • Settings UI: add/remove agents, pick provider or endpoint, set the role, rotate tokens.

Already shipped reuse

  • Actor + roles: agent = token actor; commenter rank ⇒ propose-only, can't publish.
  • Webhook outbox (B2): durable, signed, retrying delivery — the dispatch transport.
  • MCP loop (#24): read artifact / versions / comments; the agent's eyes.
  • Reviews: proposals API, rendered preview, request-changes notes, staleness guard — the agent's hands and the human gate.

Guardrails

Safety

  • Propose-only by default. An agent at commenter rank physically cannot publish; a human always approves. Bump to editor only on explicit opt-in per agent.
  • Identity is honest. Proposals + replies are attributed to the agent, never spoofing a person; the token is per-agent and revocable.
  • Loop control. An agent's own actions never re-trigger it; mentions from agents are ignored unless explicitly allowed — no agent-vs-agent runaway.

Cost & abuse

  • Rate + budget caps per agent (mentions/hour, tokens/day) so a noisy thread can't run up a bill.
  • Allowed surfaces. An agent is scoped to the artifacts it's shared on, exactly like a human member.
  • Visible spend on the hosted agent: metered, shown per workspace, with a hard ceiling.

Open questions

  • open  Revision threading. When an agent revises after "request changes", is it a new proposal or an update to the same one? (Reviews currently makes a new proposal per revision.)
  • open  Sync vs async UX. Does the reviewer wait with a "thinking…" affordance, or is it fire-and-forget with a notification when the proposal lands? (Async fits the webhook model; a live SSE "agent is drafting" is a nice upgrade.)
  • open  First-party agent scope. Ship the hosted agent in v1, or BYO-only first and add hosted once usage proves demand?