Direction.

Everything in the current specification defines Batch Mode — one process invocation per operation, JSONL on stdout, terminal aoi:summary, clean exit. Batch Mode covers the vast majority of agent‑tool interactions today and is the only normative mode in v0.2.

Session Mode is the next mode under design — a long‑lived process that accepts a sequence of requests over stdin and emits responses and server‑initiated notifications over stdout. This is the LSP / MCP shape, generalized for any agent‑operable CLI: JSON‑RPC 2.0 messages, one per line (NDJSON framing), with id correlation for multiple in‑flight requests and $/event notifications for server pushes.

01$ outline --mode session
02{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocol_version":"0.3","client":{"name":"my-agent","version":"1.0.0"}}}
03{"jsonrpc":"2.0","id":1,"result":{"tool":"outline","tool_version":"1.8.2","capabilities":{"commands":["search","watch"],"wire_formats":["jsonl","cbor"],"push_notifications":true}}}
04{"jsonrpc":"2.0","id":2,"method":"search","params":{"query":"agent operable","limit":2}}
05{"jsonrpc":"2.0","method":"$/event","params":{"type":"hit","rank":1,"id":"doc_91"}}
06{"jsonrpc":"2.0","method":"$/event","params":{"type":"hit","rank":2,"id":"doc_177"}}
07{"jsonrpc":"2.0","id":2,"result":{"type":"aoi:summary","ok":true,"count":2,"truncated":false}}

• NDJSON framing (one JSON message per line) rather than LSP's Content-Length headers — same choice MCP made, simpler to implement, and means the transport is shared across both AOI Session Mode tools and MCP servers.
• Each event from the Batch Mode vocabulary (hit, match, aoi:warning, …) is delivered as a $/event notification with the event object as params. The terminal aoi:summary is delivered as the JSON‑RPC result. Same vocabulary, different transport.
• Multiplexing is inherited from JSON‑RPC id correlation — multiple in‑flight requests, responses interleave as they complete. No separate spec needed.

JSONL is the only normative wire format in v0.2 and will remain the required baseline for every conforming tool. Human inspectability of the wire is a feature, not a compromise.

A tool may additionally offer compact binary encodings, advertised in capabilities and selected via HTTP‑style content negotiation:

Negotiation example (HTTP‑style Accept header in spirit):

outline search "x" --output jsonl --accept "application/cbor, application/x-ndjson;q=0.5"

When negotiation produces no overlap, the tool must fall back to the baseline (JSON / JSONL) rather than fail.

Until you are credibly emitting thousands of events per second, or shipping large binary payloads, JSONL is the right answer.

AOI‑CLI is the first formal profile of the Machine Mode standard. Different interface surfaces have different operational primitives — process boundaries, HTTP connections, message queues, physical actuators don't share I/O, framing, error, or cancellation models. Each surface gets its own profile.

The ten characteristics are normative across every profile. What changes per profile is how each characteristic gets expressed at that surface's operational layer.

OpenAPI is the existing, mature, overwhelmingly adopted standard for describing HTTP service interfaces. The Machine Mode HTTP profile, when authored, will not reinvent OpenAPI — it will reference OpenAPI as the wire format and add the remaining characteristics (idempotency keys, terminal completion signals, dry‑run plans, structured error retryability) as a profile / style guide on top, likely as OpenAPI vendor extensions (x-aoi-*) plus a conformance document.

A well‑designed OpenAPI service already satisfies most of the ten characteristics implicitly. AOI‑CLI exists because no equivalent standard exists for the command‑line surface — and the characteristics that apply to OpenAPI apply to CLIs too, but the expression of those characteristics is operationally different at the process boundary.

The detailed argument for why CLIs need their own profile rather than just becoming HTTP services lives in § 05 of the essay.

The Model Context Protocol standardizes how an agent discovers and invokes tools. MCP is a transport and invocation layer. AOI is an operating contract— what a tool does once invoked. They compose: AOI Session Mode (§ 01 above) uses the same transport MCP uses. A conforming AOI‑CLI tool can be exposed as an MCP server with a thin adapter, and an MCP server that follows the AOI characteristics is, by construction, an AOI‑conforming tool.

Authentication is deliberately out of scope

AOI does not standardize authentication. This is a feature, not a gap. A CLI runs as the invoking user, with the user's existing credential ecosystem already in place — keychain, AWS credential chain, kubeconfig, ssh agent, gpg keyring, Vault token, gh PAT, corporate SSO session. Decades of investment in MFA, role assumption, certificate pinning, browser‑based flows, and credential renewal lives in those ecosystems. AOI tools inherit all of it by inheriting the process environment.

Protocols that try to centralize auth at the wire layer — MCP's evolving OAuth profile included — keep running into real‑world federated identity. AOI sidesteps that by not solving it. Authentication happens beneath the AOI invocation, not at it. What AOI does specify is how a tool reports auth state — via the standard error categories authn and authz, and via aoi:check events from doctor.

AOI is not the first standard to formalize typed event streams between processes. It sits in a long lineage of stream‑processing systems — Kafka, Flink, Spark Streaming, Apache Beam, materialized views, the whole data‑engineering layer — and it deliberately occupies the smallest, simplest slice of that lineage.

The conceptual parallels are direct:

What AOI borrows from the lineage

The producer / consumer / transformer / sink vocabulary, used consistently throughout the spec. The schema‑registry concept, long‑term — eventually a centralized index of schema names so a consumer can fetch the schema for a tool it doesn't have installed. Idempotent‑write semantics via --idempotency-key. Explicit truncation and cursor patterns. Backpressure via clean pipe‑close handling. Dead‑letter patterns for malformed input.

What AOI deliberately doesn't

Distributed runtime semantics — event time vs processing time, watermark generation, state backends, exactly‑once‑across‑failures — stay out. Operator DAGs and query planners stay out; shell pipes already compose at AOI's scale and they do it naively well. Stateful operators (windowing, joins, aggregations) stay out — a single AOI invocation is the state lifecycle. Cluster topology, broker coordination, and query languages on top all stay out. AOI is a contract at a single process boundary, not a runtime system that manages clusters of them.

The relationship is composition, not competition

AOI is the Unix‑pipe‑shaped version of the same idea — same vocabulary about streams, radically smaller operational scope. AOI tools compose with stream processors. You can pipe AOI output into a Flink job that ingests JSONL. You can write a Kafka consumer that feeds an AOI sink over stdin. The contracts bridge cleanly, and the same schema discipline applies on both sides.

The single largest pain agents experience in shell sessions today is not fancy tools — it's coreutils. Every shell invocation reaches for ls, find, grep, cat, wc, head, tail, sort, uniq, du, stat, cp, mv, rm, awk, sed, xargs. None of them speak AOI. All of them emit ad‑hoc text formatted for human eyes, with formats that vary across GNU vs BSD, locale, terminal width, and tool version.

A typical agent shell session is 80% coreutils invocations. As long as those return human‑formatted text, the agent is parsing line‑by‑line — hallucinating columns, mis‑interpreting trailing whitespace, getting confused by locale‑dependent date formats, and burning context on header rows it can't tell are header rows. The most leverage AOI can provide on agent quality of life is here.

Two complementary strategies

These are complementary, not competing. machinemode gives the agent broad coverage today against whatever the system already has installed. aoi-coreutils gives the most‑critical tools a reliable, OS‑independent native implementation for cases where parser brittleness or cross‑platform consistency matters.

The seed set

The first ten to twenty utilities cover the vast majority of shell session usage. In rough order of priority for both projects:

• Filesystem inventory: ls, find, stat, du
• Text inspection: cat, head, tail, wc
• Search: grep, rg (ripgrep)
• Mutation: cp, mv, rm, mkdir
• Streaming transforms: sort, uniq, cut, tr, awk, sed, xargs
• Network / data: curl, jq, git log

Each one is a single PR's worth of work in machinemode(a wrapper module per tool) or a small standalone project in aoi-coreutils. The "thousand‑small‑adapters" shape is precisely where agent‑driven code generation pays off — write one well by hand, then iterate.

See the registry for machinemode and aoi-coreutils.

• Should Session Mode use NDJSON (MCP‑compatible) or Content-Length framing (LSP‑compatible) as default? Currently leaning NDJSON.
• Should the AOI‑HTTP profile, when authored, define its own conformance lint or extend aoi-lint to drive OpenAPI documents through the same characteristic checks?
• Should AOI‑Queue (when designed) inherit Session Mode framing over a different transport, or define its own?
• Should the per‑characteristic conformance reporting from aoi-lint follow a standard JSON Schema so consumers can ingest lint reports as data?
• What's the right cadence for promoting a forthcoming mode (e.g. Session) from "design committed" to "normative in next minor version" without forcing existing tools to immediately add support?