docs(mcp): freeze the tool surface, and record what the in-process seam costs

`docs/CONTRACT-mcp.md` (mcp-v1) is the new interface, written the way this
repository writes interfaces: the tool names, the arguments each takes, the
flag form, what is deliberately absent and why, and a row per exit code saying
what it arrives as and what an agent should do about it. An agent that has
learned these names is a consumer like any other, so renaming one needs a
version bump.

README.md gains the section an operator reads: the `mcp.enable` option, the
`mcpServers` block to register it with, why both environment variables are
shown at their defaults, and what to do when `shot` cannot read the frame
socket. README.dev.md gains the `nix build .#hhstream-mcp` half of the build
section, the `vm-mcp` row, the new files in the layout, and the reason `mcp` is
in the unit check's environment. ARCHITECTURE.md gains the sixth box, drawn
above the CLI rather than beside the broker, because that is where it sits.

`docs/TODO/mcp-in-process-has-no-call-deadline.md` records the two things the
in-process seam costs, rather than leaving them to be rediscovered. A thread
cannot be interrupted, so there is no per-call deadline and a wedged call
queues every later one behind it; and `cli.main`'s `sg` re-exec is an `exec`
this server cannot perform, so a frame verb that cannot read the socket fails
where the CLI would have recovered. The second is the one an operator meets
first -- the CLI works from their shell and the tool does not -- which is why
the failure says what the CLI would have done and how to not need it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 06:33:07 +00:00
1 parent fea55eecde
commit 6a40c7e2e4
6 files changed
+473 -11

No files matched your search

+26 -1
View File
@@ -32,9 +32,17 @@
│ AF_UNIX control.sock, mode 0660
▼
hhstream session ... (the CLI an agent drives)
▲
│ in-process: argv in, exit code out
│
┌────────────┴──────────────┐
│ hhstream-mcp │ spawned per client, stdio only
│ 26 tools, one per verb │◀─── an MCP client's JSON-RPC
└───────────────────────────┘
```
Five pieces, deliberately separate:
Five pieces, deliberately separate, and a sixth that is deliberately not a
piece at all:
1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual
outputs. It knows nothing about frames on a socket.
@@ -53,6 +61,23 @@ Five pieces, deliberately separate:
a separate process because a Wayland client needs its own connection and a
driver blocked on the compositor must not stall session lifecycle.
And the sixth, which is a *shim* and not a layer:
6. **The MCP server** (`hhstream-mcp`, `docs/CONTRACT-mcp.md`) is the CLI with a
Model Context Protocol surface on it, so an agent calls typed tools instead
of writing command lines. It is drawn above the CLI rather than beside the
broker because that is where it sits: each tool builds the argv list the
CLI's parser takes and runs the CLI's own handler **in the same process**,
and it is the one component here that owns no state at all — not even the
pointer lease, which is an explicit argument on every gesture tool. Add it
to the diagram's list of things that can go wrong and nothing new appears:
every failure it reports is the CLI's or the broker's, carrying their exit
code.
It is also the only part with a third-party dependency (the `mcp` SDK),
which is why it is a separate derivation (`nix/mcp.nix`) and why
`packages.hhstream` — the compositor's own units — keeps the closure it had.
## Why containers are outputs
A session's container is a headless **output**, not just a workspace, and the