Agent Exec Protocol v1: When Two Products Ship the Same Integration on the Same Day

1. What Agent Exec Protocol Actually Is

A versioned subprocess contract exposing monomind's AgentRunner engine to external callers

Agent Exec Protocol v1 is a public, versioned subprocess contract that exposes monomind's AgentRunner engine—13 local agent CLI runners including Claude Code, Aider, OpenHands, and others—to external callers via stable NDJSON streams over stdio. It's documented in doc/agent-exec-protocol.md (294 lines, revision 4 as of the v2.10.0 release) and shipped with six golden test fixtures in doc/agent-exec-protocol/fixtures/ as contract-testing artifacts.

The protocol's surface is deliberately minimal: monomind agent exec --runtime <id> --prompt <text> for one-shot agent turns over NDJSON stdout, monomind agent scan --json for parallel runner detection across all installed agent CLIs, and monomind --version --json for capability handshake (declaring agent-exec, agent-scan, and org-json-v1 capabilities). The protocol version is 1, and it requires monomind 2.10.0 or later.

Beyond agent execution, monomind 2.10.0 added --format json to existing org commands and introduced monomind org events --ndjson [--follow] [--since] to live-tail the org event bus (bus.jsonl) as NDJSON. The agent exec surface also supports --tools-file for bridging JSON-Schema tool definitions to caller-side handlers over stdio, making it possible for an external caller to extend an agent's tooling without modifying monomind's internals.

# Capability handshake - what does this monomind install support?
monomind --version --json
# {"v": 1, "version": "2.10.0", "capabilities": ["agent-exec", "agent-scan", "org-json-v1"]}

# Scan for available agent runtimes
monomind agent scan --json
# [{"id": "claude", "installed": true, "binary": "/usr/local/bin/claude", ...}, ...]

# Execute a one-shot agent turn over NDJSON stdout
monomind agent exec --runtime claude --prompt "What files changed in the last commit?"
# {"type": "start", ...}
# {"type": "session", ...}
# {"type": "assistant", "text": "Let me check the git log...", ...}
# {"type": "result", "output": "...", ...}
# {"type": "done", "stop_reason": "end_turn", ...}

2. Same-Day Adoption: mono-agent 0.31.0

2,364 lines added in commit 83aee33, implementing the protocol as mono-agent's sole AI delegation path

mono-agent v0.31.0, released August 25, 2026 at 21:37:32 UTC (same day as monomind 2.10.0's 21:22:43 UTC release), adopted Agent Exec Protocol v1 as its sole AI delegation path. The implementation landed in commit 83aee33 (2026-08-25 10:43:47+02:00), titled 'feat(monomind): Phase 1 — delegate AI chat to local agent runtimes via monomind', adding +2,364 lines including a 179-line protocol type layer in internal/monomind/types.go, CLI commands, and Wails bindings.

The commit message explicitly states: 'Implements the Phase-1 gate of docs/plans/local-agent-monomind-delegation.md against monomind 2.10.0's Agent Exec Protocol v1.' The protocol type layer at internal/monomind/types.go (179 lines) defines the contract's structured event types, error codes, and tool specs. The full internal/monomind/ directory implementation (1,357 lines of production Go code) includes the discovery ladder (checking MONOMIND_BIN environment variable, then PATH, then npm global/local roots), capability handshake with actionable install errors, subprocess NDJSON event stream parsing, and bidirectional stdio tool bridge via --tools-file.

What makes this adoption notable is the exclusivity: mono-agent never learns the wire formats of individual agent CLIs (Claude Code's JSON-RPC, Aider's message format, etc.)—it only speaks Agent Exec Protocol. The entire client implementation is devoted to one contract: protocol handshake, event parsing (start, session, assistant, tool_call, tool_result, usage, result, error, done per protocol §3.2), error-code handling (auth, quota, missing-binary, no-runner, budget, runner-error, timeout, cancelled, bad-frame per §3.4), and tool-schema bridging per §4.1.

“mono-agent never learns agent-CLI wire formats—only this protocol. The internal/monomind/ client (1,357 LOC production code, 179-line type layer) is a pure protocol implementation: discovery, handshake, NDJSON event stream, bidirectional stdio tool bridge.”

- mono-agent commit 83aee33 implementation

3. What Same-Day Cross-Product Delivery Actually Required

Public spec, golden fixtures, and a contract-first integration pattern

Shipping a cross-product integration on the same day isn't a coordination accident—it requires deliberate contract design. The Agent Exec Protocol v1 spec (doc/agent-exec-protocol.md, rev 4, 294 lines) is a public, versioned document that both products build against. The six golden fixtures in doc/agent-exec-protocol/fixtures/ are executable contract tests: concrete NDJSON sequences (bad-frame, cancel, fatal-auth, success, timeout, tool-loop) representing success cases, error cases, and edge cases that both the server-side (monomind) and client-side (mono-agent) implementations must handle identically.

The protocol's error handling is not advisory—it's structural. When monomind's agent exec encounters an error, it emits a {"type": "error", "code": "<error-code>", "message": "...", "fatal": true|false} event per §3.4, and mono-agent's Go client (internal/monomind/types.go) parses that into a typed ProtocolError with Code, Message, Fatal, and ExitCode fields. Error codes like missing-binary, no-runner, quota, and auth map to actionable install hints that mono-agent surfaces to users without hard-coding agent-CLI-specific messages.

The integration is also forward-compatible by design: monomind's --version --json handshake returns a capabilities array (agent-exec, agent-scan, org-json-v1 as of 2.10.0), and mono-agent checks for required capabilities before attempting execution. If a future monomind version introduces agent-exec-v2 or a new capability, mono-agent's handshake can gracefully detect it and either adopt the new feature or fail with a clear version-mismatch error instead of a cryptic subprocess crash.

// Agent Exec Protocol v1/rev 4 - protocol version and capabilities
const ProtocolVersion = 1
const MinMonomindVersion = "2.10.0"
var RequiredCapabilities = []string{"agent-exec", "agent-scan", "org-json-v1"}

// Event types per §3.2 (179-line type layer defines full contract)
type Event struct {
    V    int    `json:"v"`
    Type string `json:"type"` // start, session, assistant, tool_call, result, done, error
    // ... event-specific fields
}

// Error codes per §3.4
type ProtocolError struct {
    Code     string `json:"code"`     // auth, quota, missing-binary, no-runner, ...
    Message  string `json:"message"`
    Fatal    bool   `json:"fatal"`
    ExitCode int    `json:"exit_code,omitempty"`
}