ADR-020 — Agent protocols: which one YazSes needs, and which it must not adopt¶

Status: Accepted (2026-08-15) Deciders: Mohsen Seyedkazemi Ardebili Context links: [[adr-v2-006-spoken-mcp]] (YazSes as an MCP client — already decided), [[adr-019-egress-inventory-and-escalation]] (the AF_UNIX boundary this leans on), [[adr-011]], [[adr-018-feature-packs-and-the-plugin-question]], the problem space §B1–B2

Context¶

The question was whether YazSes needs agent-to-agent communication, MCP, FastMCP, or FastAPI — and in which scenario. Four different things are routinely conflated under "agent protocol", and the answer is different for each:

Treating them as one question is how a project ends up adopting a protocol because it is current rather than because something needed it.

Decision¶

1. MCP server: yes, for exactly two tools, over stdio only¶

The genuinely novel thing YazSes could offer another agent is not transcription — it is a human. An agent that has stalled on a decision only a person can make currently has one way to ask: put text on a screen and wait for someone to notice, read and type. Voice is the cheapest interrupt a working human can service, because it needs neither their eyes nor their hands.

Two tools, and only two:

• transcribe(path) — an offline transcript of a file. Useful, unglamorous, and already the CLI; exposing it costs nothing new.
• ask_human(question, timeout) — speak a question, capture the spoken answer, return it as text. This is the one that does not exist anywhere else.

Over stdio, never HTTP. MCP's stdio transport keeps the server a child process of the thing that spawned it — the same property that makes YazSes's own IPC safe. Which brings us to the next decision, because it is the same decision.

2. FastAPI / any HTTP server: no, and the reason is structural¶

YazSes's IPC is JSON-RPC over an AF_UNIX socket. ADR-019 records why that matters and enforces it with a test: AF_UNIX is a filesystem object, not an address, so the daemon is unreachable from another machine by construction rather than by configuration. There is no port to leave open, no bind address to get wrong, no firewall rule standing between a user's dictation and the network.

Adding FastAPI would replace that structural guarantee with a configuration one. The daemon holds a live microphone and can type into any focused window; "we bound to 127.0.0.1" is a much weaker sentence than "there is no socket that could reach the network." An HTTP surface is also precisely what an ADR-018-style plug-in would have been: a general-purpose door onto the dictation hot path.

If a genuine need for HTTP appears — a browser client is the plausible one — it is a new ADR that supersedes this, with an isolation story, not a dependency added to pyproject.toml.

FastMCP is a library for building MCP servers, not a separate protocol; where it is convenient for the stdio server above, it is an implementation detail governed by ADR-016 like any other dependency.

3. Agent-to-agent (A2A): no, because YazSes is not an agent¶

A2A protocols assume autonomous peers that negotiate, delegate and pursue goals. YazSes does not have goals. It is an input device with a state machine — it turns held keys and speech into text and keystrokes, and every decision it makes is a classification, not an intention.

Adopting A2A would mean inventing agency in order to have something to negotiate with. The scenarios that sound like they need it — "the coding agent asks YazSes to dictate", "YazSes delegates transcription to a bigger model" — are a tool call and a config option respectively. MCP already covers both directions of the only relationship that exists: YazSes calls tools (ADR-v2-006), tools call YazSes (§1).

4. The hard part is the interrupt budget, not the plumbing¶

ask_human is where the real design problem is, and it is not a protocol problem.

An agent that can speak to you at will can interrupt you at will. A voice interrupt is cheap for the agent and expensive for the human, which is exactly the asymmetry that produces notification fatigue — and this one arrives in the middle of the user's sentence, on the same audio channel they are dictating into.

So ask_human ships with these, or does not ship:

• Off by default, like everything else.
• A budget — a configurable maximum number of interrupts per hour, and no way for a caller to exceed it by asking harder.
• Never during a hold. The user is speaking; the daemon knows it; the question waits.
• The caller is named in the spoken question, so "who is asking" is never ambiguous.
• The answer goes back to the caller, not into the focused window. A dictation burst answering an agent must not also type into whatever the user had open — the no-text-target guard's failure mode in reverse.

5. Nothing here is scheduled¶

This ADR decides what would be acceptable, not what happens next. The MCP client from ADR-v2-006 is itself still unwired, and wiring a server before the client is finished would add surface to something incomplete. The agent slug stays in _UNWIRED until someone takes it.

Consequences¶

Good. The question "should we add FastAPI?" now has a written answer with a reason stronger than taste. The one genuinely novel capability — an agent asking a human a question out loud — is described precisely enough that someone could build it, including the part that makes it survivable.

Accepted cost. Choosing stdio over HTTP means YazSes cannot be called by something on another machine. That is the intended property, not a limitation to work around later.

What would reverse this. For §2: a real user need for a browser client, plus an isolation design. For §3: YazSes acquiring goals of its own, which would be a different product. For §1: nothing — it is already the narrow version.