Repository navigation
Agent Surface
This page is the wire contract for anyone integrating an agent with shoal — an LLM tool harness, an
MCP client, a custom JSON-RPC bridge. It follows
docs/AGENT-SURFACE.md
("wire contract v2"), the normative companion to Language-Reference/Execution-Model for
everything agent-facing. See Kernel-and-Agents for the session/journal machinery this contract
sits on top of, and Leash-and-Security for what actually gates a shoal_exec call.
The bash tool is the failure mode this surface exists to end: an agent runs a command, a wall of text lands in its context, and every downstream decision becomes regex archaeology over that wall. In shoal, an agent never parses text it didn't explicitly ask to see raw.
- Every value the shell produces is addressable by a stable ref. An agent's context holds refs and small structured summaries; payloads are fetched surgically (field paths, slices) or subscribed to. Re-reading costs zero re-execution and near-zero tokens.
- Large values never enter context uninvited — the elision rule (§3) is wire-level and automatic, not agent etiquette an integrator has to remember to implement.
- State is browsable (resources), actions are verbs (tools), changes are pushed (events). Polling is a bug. Text-matching shoal's own rendered output is a bug. The tty is a wire for humans and a display, never a data interface for machines.
- Diagnostics are structured (
code/msg/span/hint) — no agent should ever need to parse a caret box.
Short refs, as they appear in values, the journal, and renders: out:12, val:blake3:<hex>,
task:7, plan:<hex16>, ch:<name>. Every short ref has a URI form; MCP resources use the URI
form:
shoal://out/{n} transcript value n (session-scoped)
shoal://val/{blake3} immutable content-addressed value
shoal://task/{id} task record: status, desc, exit, timings
shoal://task/{id}/out task's live output (subscribable, cursor-read)
shoal://jobs the task table
shoal://journal query root (template: ?since,head,principal,ok,limit)
shoal://journal/entry/{id} one entry: src, canonical AST, effects, output hashes
shoal://plan/{ref} a derived plan: effects, reversibility, verdict
shoal://session/cwd|env|reef session state views (env NAMES only, unless granted)
shoal://events/{channel} event channel, cursor-read (?since=seq)
Value-bearing resources accept ?path=<fieldpath>&slice={a}..{b}&format=json|render|raw — the
same field-path grammar as value.get: .field, [n], [a..b]. format=raw returns the
original bytes; render returns the human render; the default json returns the $-tagged
encoding (§2).
Every type is $-tagged JSON — there is no silent fallthrough to a string, ever:
null/bool/int/float native JSON
{"$":"str","v":…} only when tagging is needed
{"$":"path","v":…,"raw":base64?} raw present iff non-UTF-8
{"$":"size","v":bytes} {"$":"duration","v":ns}
{"$":"datetime","v":rfc3339} {"$":"time","v":"HH:MM:SS"}
{"$":"regex","v":src} {"$":"glob","v":pattern}
{"$":"range","start","end","inclusive"}
{"$":"list","v":[…]} {"$":"record","v":{k:…}}
{"$":"table","cols":{name:[…],…},"n":N} columnar, not row-major
{"$":"outcome","status","signal","ok","out":<tagged>,"err":str,"dur_ns","pid","cmd","span"}
{"$":"error","code","msg","span","hint","stderr"}
{"$":"task","id","done","desc"}
{"$":"stream","label","uri"} never an inline payload
{"$":"secret","name"} never material
{"$":"bytes","len","v":base64?} v elided per §3
{"$":"closure","repr"}
Implemented. Any value whose encoded JSON exceeds 8 KiB, any table over 100 rows, any bytes over 4 KiB, any list over 500 items: the wire carries an elided form instead of the payload — automatically, not as agent-side discipline:
{"$":"ref", "uri":"shoal://out/12", "of":"table", "n":8214,
"cols":{"name":"str","size":"size","modified":"datetime"},
"preview":{"$":"table","cols":{"...first 5 rows..."},"n":5},
"render_head":"name size modified\n────…(first 10 lines)"}Shape always travels — type, counts, schema, a small preview. Payload never does until asked. A
caller may tighten or loosen the thresholds per call (elide:{max_bytes,max_rows} on
exec/value.get), but never disable them above a hard 64 KiB cap — a misbehaving agent cannot
flood its own context even if it tries to.
Kernel-native pub/sub over the same socket. Every event is {channel, seq, ts, payload} —seq
monotonic per channel, ring-buffered (≥1024 events; session.transcript/journal channels are
journal-backed and replayable from any historical seq). Read = shoal://events/{ch}?since={seq};
push = subscription (§6). Delivery is at-least-once; consumers dedup by seq.
session.transcript {n, ref, summary:{type, ok?, cmd?, n?}} every new out[n]
task.{id} {state:"started"|"output"|"suspended"|"exited", chunk_ref?, exit?}
journal {entry_id, head, ok, principal}
approval {plan_ref, effects, principal, expires} plan awaiting approval
render {ref, render} UI clients
reef {tool, event:"locked"|"drift"|"fetched", hash}
user.{name} arbitrary $-tagged value in-language channel(name)
user.* channels are the cross-principal primitive: a human's session and its agents signal each
other structurally — no file-watching, no sentinel strings typed into a tty.
A deliberately small verb set — nouns live in §1. Every result carries structuredContent (the
$-tagged value, or its elided form per §3) and a resource_link to its ref; text content is
a render string only, never the source of truth.
As specified (docs/AGENT-SURFACE.md §5):
shoal_exec {src|ast, mode:"run"|"plan", position:"stmt"|"value", background:bool, timeout_ms?, elide?}
shoal_apply {plan_ref}
shoal_get {ref|uri, path?, slice?, format?, elide?}
shoal_journal{since?, head?, principal?, ok?, limit?}
shoal_cancel {task}
shoal_cap_request {effects:[…]}
As shipped today (shoal-mcp, crates/shoal-mcp/src/lib.rs) — seven tools, each mapping onto a
kernel JSON-RPC method:
| MCP tool | maps to | purpose |
|---|---|---|
shoal_exec |
exec {mode:"run"} |
Execute shoal source; returns {ref, value|elided, render}
|
shoal_plan |
exec {mode:"plan"} |
Derive concrete effects without spawning anything |
shoal_apply |
plan.apply |
Apply a previously-approved plan |
shoal_get |
value.get |
Query/slice a transcript value without re-executing |
shoal_journal |
journal.query |
Search execution history by time, principal, effects |
shoal_cancel |
task.cancel |
Request cancellation of a background task |
shoal_cap_request |
cap.request |
Escalation path when a plan is stuck at approval_pending
|
First-class events.subscribe/MCP resources/subscribe push (§4/§6) is also wired, not just
specified — see Kernel-and-Agents for exactly which kernel JSON-RPC methods exist right now
(session.attach parse exec value.get task.list task.await task.cancel task.suspend plan.apply cap.request journal.query events.subscribe).
The kernel JSON-RPC surface also keeps parse, complete, and explain for typed completion and
structured explanation, and session.attach's result carries {caps_enforced, ast_version, elide_defaults, channels} so a client learns at attach time whether the sandbox wall is real
(Leash-and-Security) and what it may subscribe to.
Implemented. An MCP client subscribes to a resource URI (resources/subscribe on
shoal://events/{ch} or shoal://task/{id}/out); shoal-mcp opens a dedicated events.subscribe
connection to the kernel behind the scenes and pushes notifications/resources/updated carrying
{uri, seq, payload} as events arrive. Native JSON-RPC clients use events.subscribe {channel, since?} directly on the same socket. A client that missed events replays with ?since={last_seq}
(ring-buffered channels) or a journal query (journal-backed channels).
A correct agent never calls the same read twice hoping for change — it subscribes. The word "poll" appears in this system only as the name of an anti-pattern.
Backpressure: a slow subscriber's queue is bounded; on overflow the kernel drops to a coalesced
summary ({dropped: n, latest_seq}) rather than unbounded buffering or blocking the producer —
liveness beats completeness on a saturated channel, and completeness is always recoverable from the
journal afterward.
Implemented (roadmap wave R1 — crates/shoal-eval/src/channels.rs, corpus in
spec/cases/streams.toml). Channels are first-class in the language too, not just on the wire —
this is how a human session and its agents coordinate without files, sentinels, or tty-scraping:
channel("deploy") # a channel handle (session-scoped by default)
channel("deploy").emit(value) # publish a $-tagged value -> event on user.deploy
channel("deploy").events() # a stream<event> — lazy, single-consumption
channel("deploy").latest() # last value or null, no wait
channel("deploy").take() # block for the next value (or `timeout: duration`)
on channel("deploy") { ev => … } # desugars to .events().each in a task
# spec/cases/streams.toml — the ring is real: emit/latest and a bounded .events() collect
channel("build").emit(1)
channel("build").emit(2)
channel("build").latest() # -> 2
channel("x").events().collect() # -> error, stream_unbounded (an event channel is
# unbounded by nature — .take(n) or .collect() on a
# finite window first, never a bare collect on a
# live channel)
An agent watching a human's channel("review"), and a human watching an agent's
channel("progress"), is the entire pair-shelling protocol. No polling, no text. Every
channel(name).emit(v) also lands on the wire as a user.{name} event (§4) — the in-language
primitive and the MCP event channel are the same substrate, not two systems that happen to agree.
resources/list enumerates the stable roots (§1) plus per-session dynamic entries (open tasks,
recent out:n). resources/read on a value URI returns structuredContent — the $-tagged (or
elided) value; on an events URI it returns the buffered tail. resources/templates/list advertises
the query-parameterized forms (shoal://journal{?since,head,limit},
shoal://out/{n}{?path,slice,format}). Every tools/call result that produces a value includes a
resource_link so the agent can drill in later for near-zero tokens — the tool result in context
stays a one-line render plus the ref, never the payload.
An agent's context is a working set of refs and shapes; every byte of real payload is pulled on purpose, structured, from an addressable noun, or pushed, structured, from a subscribed channel. There is no other way for data to reach the agent, by construction.
- Kernel-and-Agents — the session/socket machinery this contract is layered over.
-
Leash-and-Security —
shoal_plan/shoal_apply/shoal_cap_requestare this contract's front end onto the capability engine. -
Execution-Model —
position: "stmt"|"value"is the exact PTY position rule, over the wire. -
docs/AGENT-SURFACE.md— the full normative spec this page summarizes.