Single-source agent protocol with stdio as the default transport

[metasmile]

Priority: high. Design issue, no code change requested yet.

Context

Telos will be embedded as one of several independent agent executables, each running as its own process under a supervisor (actus today, other hosts later). The product direction is an N-agent swarm over separate processes, where licensing forces telos to remain a standalone external process (actus/rem never link it). Regardless of licensing, process separation is the architecture for parallel agents.

Today the tel binary communicates only over an outbound WebSocket (external_websocket_sync) that actus listens on. There is no stdio JSON-lines mode. LLM streams are already emitted as structured events over the WS contract, but the transport is single-channel and WS-only.

The industry standard for a supervisor integrating N local executables is stdio (LSP spawns language servers over stdio JSON-RPC; MCP uses stdio as its default local transport and Streamable HTTP for remote). WebSocket is the standard for remote/coordinator-callback topologies (Helix to Zed, browser to server), not for local supervisor spawns.

Proposal

Make the core contract transport-agnostic and single-source, then attach transport codecs to it.

1. telos-protocol becomes the single source of truth:
   • event and command types (thread events, turn semantics, cumulative content, tool calls, approvals),
   • framing rules (JSON-RPC 2.0 style or JSON-lines),
   • ordering and lifecycle semantics.
2. Transports are thin codecs over the same types, never owners of semantics:
   • stdio: default local transport for supervisor spawns (events out on stdout as JSON-lines, commands in on stdin, logs on stderr),
   • WebSocket: existing outbound channel retained as the remote/coordinator codec,
   • future: HTTP/SSE if remote service mode is needed.
3. --stdio mode added to the tel binary as an additive flag, reusing the same event/command handling as the WS path. No rewrite of the agent core.
4. Conformance: a mock agent must emit the same event sequences over stdio and WS; the conformance suite gates both transports so adding stdio cannot regress the WS contract.

Scope / acceptance

• Spec document in telos-protocol: framing, event/command tables, transport-agnostic semantics.
• tel --stdio mode with JSON-lines stdin/stdout and stderr for logs.
• WS path unchanged and still gated by the existing conformance suite.
• Conformance runs over both transports with identical expected event sequences.
• Supervisor (actus AgentBackend) can spawn telos via stdio without ports or listeners.

Rationale

• One protocol definition, N transports (stdio local, WS remote) is the MCP/LSP pattern.
• Stdio as the reference transport keeps supervisor integration, tests, and conformance simple (no ports, natural backpressure, clean process termination).
• WS remains for remote and coordinator-callback use cases and is not wrapped over stdio; both implement the same single-source contract.

Open questions

• Exact framing: reuse existing WS event/command JSON shapes verbatim on stdio, or normalize to JSON-RPC 2.0 envelopes?
• Should actus keep WS as its default telos transport for now, with stdio added when a spawn supervisor adapter lands?