Documentation/07 · Three kinds of reach

Modalities: how steps reach the world

Where you are in the journey: you've built plays whose steps run local processes. But the work you'll want to crystallize lives everywhere — behind APIs, on your machine, and on web pages with no API at all. This section introduces the product's three kinds of reach, and the routing instinct for choosing between them.

The product phrase is "three kinds of reach and one memory". Before meeting the three reaches, meet the one memory they all share.

First, the workspace: a trace sandbox

A workspace is where every reach lands. Think of it as a trace sandbox: an isolated recording surface that persists every event of a working turn — each API call, each process you run, each page you visit — as it happens, in order, with nothing scrolling away.

rote init triage-outage --seq     # open the sandbox; you're now on the record

From that moment, every call any reach makes becomes a numbered, durable event:

ROTE/text3 lines
@1   an API response        (adapter call)@2   a process capture      (shell)@3   a page snapshot        (browser)

Three properties make this a sandbox rather than a log:

  • Isolated — one workspace per task. Events from your outage triage don't mingle with yesterday's release work; each canvas is its own addressing space, archived independently.
  • Persistent — the events are Context Addressable Units: immutable once created, queryable forever (rote query @2 '.field' -r), surviving the end of the session and the agent's context window alike. The turn's thinking may be ephemeral; the turn's evidence is not.
  • Uniform — an API response, a process capture, and a page snapshot are peers. Whatever reach produced an event, downstream work holds a reference to it (@N), never a pasted payload.

That last property is why the modalities below compose so freely: the workspace doesn't care how you reached the world, only what came back. And because later events reference earlier ones by @N{.field}, the sandbox's trace is silently accumulating the dataflow graph your play will crystallize from (that's section 8's story).

The product's own metaphor: "a rote workspace is a flight recorder." Everything below writes into it.

The three reaches

All three write into that same workspace, where their events sit side by side as @1, @2, @3.

Three kinds of reach, one memory

Reach 1 · APIs — adapters

An adapter connects rote to any service with a machine-readable description: OpenAPI, GraphQL, gRPC, Google Discovery, or a live MCP server. There's a catalog of 870+ known APIs, so most services are one command away:

rote adapter new github

The mental shift from MCP-as-you-know-it, in the product's words:

MCP servers say "here's a process that wraps an API." Adapters say "here's an API — the spec is the server."

Every adapter exposes the probe/call pattern — search first, never load everything:

ROTE/bash5 lines
# probe: semantic search over the API's capabilities, by intentgithub_probe   "list pull requests for a repository" # call: execute the discovered operationgithub_call    pulls.list  owner=modiqo repo=rote state=open

During exploration you drive probe/call from the workspace; each call lands as a CAU. When you crystallize, adapter calls become adapter steps in the DAG:

ROTE/yaml11 lines
steps:  ensure_auth:    type: adapter.auth.ensure    endpoint: adapter/github    on_missing: authorize    on_expired: refresh  list_pulls:    type: adapter/github          # endpoint: adapter/<installed-adapter-id>    method: pulls.list    params: { owner: modiqo, repo: rote, state: open }    depends_on: [ensure_auth]

One publishing rule to know early: a play whose steps call an adapter must declare it in requires_endpoints — that field is the only input to adapter installation for whoever pulls your play, and the registry refuses a push that omits it.

Cross-service discovery, when you don't know which adapter you need:

rote explore "send a message to a slack channel"

Reach 2 · Shell — recorded processes

You've been using this one since section 3. rote proc run executes a local process and captures it — stdout, stderr, exit status — as a CAU instead of terminal scrollback:

ROTE/bash3 lines
rote proc run gh pr list --json number,titlerote proc run python3 analyze.py --input data.csvrote query @1 '.stdout.text | fromjson | .[0].title' -r

Two properties make this more than a fancy $(...):

  • A policy engine classifies risk and blocks destructive commands before they spawn — while still recording the attempt.
  • The capture is queryable forever. A 40k-token command output doesn't re-enter anyone's context window; you read fields out of it by reference.

In a crystallized play, shell work becomes the process.exec steps you already know from section 6 — including the exit contract: the child's exit status is the DAG's failure signal, stdout is data. And because steps have no TTY, any subcommand that would prompt needs its consent flag (--yes) passed explicitly inside the step.

Reach 3 · Browser — drive the web

For the parts of the world with no API: the browser reach drives the web, including attaching to your own logged-in browser session. Login walls, CAPTCHAs, and human-approval moments are detected and surfaced rather than fumbled.

rote browse https://news.ycombinator.com

Exploration follows a mandatory chain — navigate → wait → snapshot → slice — never a raw page dump:

ROTE/bash3 lines
rote browse wait --text "login"        # settle firstrote browse snapshot                   # capture as a CAU# then slice what you need: clickable | links | headings | forms | errors

Crystallized, browser work becomes typed browser steps:

ROTE/yaml14 lines
steps:  open_page:    type: browser.navigate    url: https://example.com/status  settle:    type: browser.wait    text: "All systems"    timeout_ms: 15000    depends_on: [open_page]  read_status:    type: browser.extract    slice: headings    limit: 10    depends_on: [settle]

(browser.click and browser.type exist for interactions, targeting elements by snapshot ref or visible text.)

The routing instinct: lightest first

When a task could be reached more than one way, the product's substrate router rule is lightest-first:

  1. Installed adapter — typed, authenticated, drift-fingerprinted. Best when it exists.
  2. Shell + public JSON — a curl/CLI capture is often all a public endpoint needs.
  3. Headless browse — the heaviest reach; reserve it for pages that genuinely have no API.

Choose per reading, not per play — a single play can probe an API, run a local tool, and read one stubborn web page, each as its own step. The workspace doesn't care: every reach lands the same way, and the crystallizer compiles them into one DAG.

A real example of the choice mattering: modiqo/whale-flow-monitor originally drove two MCP adapters. Both merely wrapped public REST APIs — so its steps now call the endpoints directly, which dropped the adapter setup requirement entirely and exposed a rotted endpoint path the adapter had been hiding. Lightest-first isn't just cheaper; it's more honest.

Next: 8 · The workspace, CAUs, and the DAG underneath →