Skip to content

Agent Surface

Allie Coleman edited this page Jul 11, 2026 · 2 revisions

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.

0. The doctrine — anti-bash-tool

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.

  1. 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.
  2. 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.
  3. 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.
  4. Diagnostics are structured (code/msg/span/hint) — no agent should ever need to parse a caret box.

1. Refs and URIs

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).

2. Value encoding

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"}

3. The elision rule — wire-level, automatic

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.

4. Events — channels, cursors, push

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.

5. Tools (verbs)

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.

6. Subscriptions — push, never poll

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.

7. In-language channels — the pair-shelling primitive

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.

8. MCP resource mechanics

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.

The contract, in one sentence

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.

Cross-links

  • Kernel-and-Agents — the session/socket machinery this contract is layered over.
  • Leash-and-Security — shoal_plan/shoal_apply/shoal_cap_request are 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.