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:
1 parent
fea55eecde
commit
6a40c7e2e4
6 files changed
+473
-11
No files matched your search
+26
-1
@@ -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
|
||||
|
||||
Reference in new issue
Block a user