ADR-0016: Agent Reverse Channel = JSONL File, Not RPC

Status: Accepted
Date: 2026-07-06

Context

After M3 (Popen + streaming + cancel), agents could only communicate with the host in one direction: stdout → engine. There was no path for an agent to push progress updates, clarification questions, or “approval_request” events back to the host without the engine killing the process and reading JSON.

The agent-as-agent use case (one agent spawning sub-agents that report back, or a long-running agent that wants to checkpoint intermediate results) needed a reverse channel. OpenOPC — which this PRD is partly modeled on — solves this with FIFO / TCP RPC: every agent process gets an RPC server address via OPC_COLLAB_RPC_* env vars, and the agent’s SDK calls chat.abort, send_message, etc. via that RPC. The RPC is a real two-way protocol over Unix FIFO or TCP socket.

We had to choose: replicate OpenOPC’s RPC, or pick something simpler.

Why OpenOPC chose RPC

OpenClaw-style agents (and OpenOPC’s agents) often need to call back into the host for things like:

“I need user input — pause me and prompt”
“Here’s a partial result, write it but keep going”
“Cancel this sub-task I spawned”
“Subscribe to events from another agent”

The RPC model gives you bidirectional channels with request/reply semantics, auth, structured errors, and back-pressure. All of these are real needs in agent orchestration.

Why that model is overkill for v1

We surveyed what agents actually need to push back in the v1 use cases:

Progress updates — fire-and-forget text strings. No reply needed.
Clarification requests — text questions. Reply is async (human responds hours later via Obsidian frontmatter), not in-process.
Result checkpoints — partial outputs to persist before failure. Write-only.
Done signals — explicit completion marker (in case exit code is unreliable). Write-only.
Approval requests — agent wants human review before continuing. Write-only.

Every v1 use case is write-only fire-and-forget. None of them need request/reply, structured errors, or back-pressure. RPC is over-engineered for what we need today.

What JSONL gives us

$RUNEX_INBOX_PATH — a file path env var injected into the agent subprocess. The agent writes JSON lines (echo {...} >> "$RUNEX_INBOX_PATH"). The engine’s drain thread tails the file (byte-offset-tracked, like tail -f).

For every v1 use case:

Progress: echo '{"type":"progress","text":"step 3"}' >> "$RUNEX_INBOX_PATH"
Clarification: echo '{"type":"clarification","q":"which model?"}' >>
Checkpoint: echo '{"type":"result_partial","note":"…"}' >>
Done: echo '{"type":"done","summary":"…"}' >>
Approval: echo '{"type":"approval_request","reason":"…"}' >>

The agent needs zero SDK — just echo and a shell. Any agent that can write to a file can participate.

Decision

Agent → host reverse channel = a per-run JSONL file at $RUNEX_INBOX_PATH. No FIFO, no TCP socket, no RPC SDK. The agent writes lines; the engine drains them; each line becomes one InboxMessage graph node.

Alternatives

方案 A — OpenOPC-style FIFO/TCP RPC (rejected for v1)

Env vars OPC_COLLAB_RPC_TRANSPORT=fifo, OPC_COLLAB_RPC_PATH=/path/to/fifo, OPC_COLLAB_RPC_TOKEN=…. Agent calls opc-collab chat.abort --run-id … via the RPC. Host receives the RPC, validates the token, and acts.

Pros:

Real bidirectional channels
Auth tokens, structured errors, back-pressure
Matches OpenOPC exactly — agent SDKs written for OpenOPC work unmodified

Cons (the reason rejected for v1):

Every agent process needs to know the RPC URL — can’t be claude -c, has to be a custom SDK wrapping the CLI
FIFO setup requires mkfifo + non-blocking open + careful cleanup; TCP needs port allocation + auth
Engine needs to fork an RPC server alongside the agent process; one more thing to crash
For 5 v1 use cases, the RPC adds 500+ lines of code in the engine and ~50 lines per agent SDK. JSONL is ~80 lines total.

方案 B — HTTP localhost server (rejected)

Engine spawns an HTTP server on 127.0.0.1:<random_port>, injects the URL via RUNEX_INBOX_URL. Agent POSTs JSON.

Pros:

Standard protocol, easy to debug (curl)
Auth via header token

Cons:

Port allocation, race conditions on port reuse, firewall quirks
Agent needs curl or any HTTP client — echo no longer works
Same infrastructure overhead as RPC, without FIFO’s file-as-queue advantage

方案 C — Chosen: JSONL file (ADR-0016)

Env var RUNEX_INBOX_PATH=/Users/.../runex/inbox/<run_key>.jsonl. Agent appends JSON lines. Engine spawns a daemon thread that tails the file (byte offset tracked) and emits one InboxMessage per line.

Pros (the reason chosen):

Zero new infrastructure — echo >> file is in POSIX
Crash-safe — half-written lines are skipped by parser; full lines survive agent kills (WAL-mode SQLite + atomic appends are reliable enough)
Agent needs zero SDK — bash echo, Python print(..., file=open(p,'a')), any tool that can write a file works
Observable — user can tail -f "$RUNEX_INBOX_PATH" while the agent runs and see exactly what it’s pushing
Replayable — drain can re-read the file (idempotent msg_key); if the engine restarts mid-run, no message is lost
Capacity — append-only JSONL is unbounded; a 1GB inbox is the same as a 1KB one to the engine (linear scan on drain)
Testable — echo '{"type":"progress","text":"x"}' >> /tmp/test.jsonl in a test fixture; no socket mocking