Files
stack/adapters/README.md
T
jason.woltje 361ba2387f row 213: Case 2 C2-08 creative roles, persona file and block, M1, M2, M6, M10, prompt passed by file (#1714)
Lands Morgana's round 4 candidate, 2b3e67e36 (base c771a36f4, branch morgana/row213-r4), approved by Webby
(webby-0071, REVIEW-r4 02bb0afb3, rev 2775). Manifest digest 26d4d0ecff56, 35 paths, plus Morgana's
four packet files under agents/morgana/work/queue-213/ (base.txt, BUILD.md, candidate-manifest.sha256,
mutants.py): 39 paths, blobs and modes from the candidate. No 213 path changed between c771a36f4 and
this commit's parent. Patch-id f313e69b6f7e, the same as c771a36f4..2b3e67e36.

Evidence: Morgana's slot run on 2b3e67e36 (sage-1844): singles 191/0 and 31/31 mutants killed.
Gate on my slot (sage-r195land, base 38b83ea5c plus 195's 5 and 213's 39 paths, 09:45:52-09:57:52Z): business 200/0, bus 542/0, harness 140/0, cli 663/0; scripts auth 15/0, conductor 17/0, config 31/0, discord 78/0, extension-package 18/0, foundation 44/0, land-work 86/0, queue 156/0 plus 28/0, release 14/0, task 98/0; the models mutant L1 killed (launch-settings 15/1), restore matched.
Between the gate base 38b83ea5c and 4364dddb0 only docs/plans/2026-10-20_host-credentials.md changed (01e1fe512, 4364dddb0), which no test reads. Row 195 landed as this commit's parent; it shares no path with 213.
Webby's N2 (a host grant for a creative role) is a row 235 acceptance item (mos-1163), not a deferral.
2026-10-21 04:58:30 -05:00

5.7 KiB

Mosaic runtime adapters

An adapter is the entire harness-specific surface of the system. Everything upstream of an adapter — configuration, contracts, missions, tasks, run records — is harness-agnostic; everything inside an adapter may assume one specific agent runtime.

Contract

An adapter lives at:

/opt/mosaic/adapters/<name>/adapter.sh

and must be executable. The dispatcher (/opt/mosaic/src/run-agent.sh) selects it via MOSAIC_ADAPTER (default: pi) and execs it after the system prompt has been generated.

Inputs (environment):

Variable Meaning
MOSAIC_SYSTEM_PROMPT_FILE Absolute path to the generated system prompt (contracts + optional mission section). Read it; do not modify it.
MOSAIC_REQUEST The exact user request text (may contain newlines).
MOSAIC_PROVIDER Configured provider name.
MOSAIC_MODEL Configured model id.

Optional, adapter-specific (documented per adapter):

Variable Meaning
MOSAIC_MOCK_RESPONSE mock only: the verbatim response to emit

Outputs:

  • stdout: the model response text — the only channel the orchestrator captures
  • stderr: diagnostics (never credentials)
  • exit 0: success; nonzero: failure

Rules

  1. Adapters print ONLY the response on stdout. Status lines go to stderr.
  2. Adapters never read configuration files; the resolved settings arrive via environment.
  3. Adapters never write outside /var/lib/mosaic.
  4. Adding a worker adapter requires: a new directory, the contract implementation, and adding the name to the allowlist in scripts/mosaic-config.mjs. A managed-session adapter (below) is selected by the launch bundle, not by execution.adapter, and is not on that allowlist unless it also works as a worker adapter.

Included adapters

  • pi — the pinned @earendil-works/pi-coding-agent CLI in noninteractive print mode (-p), ambient discovery disabled, stdin detached.
  • mock — deterministic echo of MOSAIC_MOCK_RESPONSE. Test-only: never use it where a real model response is required.
  • claude — the host's claude CLI, for managed sessions only (below): MOSAIC_CLAUDE_BIN when set, else claude on PATH. Not a worker adapter: the image has no claude, and the adapter refuses without the bundle's hook and MCP files.

Managed sessions (slice 1 S6)

The session runner (packages/harness/src/runner.mjs) runs one adapter call per turn on the host, as /bin/sh <adapters/<name>/adapter.sh> (the repository keeps adapters 0644; only the image sets the mode), in the session's workspace and its own process group. Same contract, plus:

Variable Meaning
MOSAIC_WORKSPACE The session's workspace; the adapter runs there.
MOSAIC_SESSION_DIR The session's persistent directory; later turns resume the session kept there.
MOSAIC_TOOLS The built-in tool limit (pi names for pi, Claude Code names for claude), comma-separated.
MOSAIC_POLICY_FILE, MOSAIC_TOOLS_FILE The bundle's gate policy and typed tools.
MOSAIC_TOOL_SOCKET The runner's tool socket, which the typed tools call.
MOSAIC_TURN_MARKER pi: the extension writes it at agent_end; a pi turn that exits 0 without it failed.
MOSAIC_EXTENSIONS pi only: extension files loaded with -e; a missing one exits 2.
MOSAIC_CLAUDE_SETTINGS, MOSAIC_CLAUDE_MCP_CONFIG claude only: the bundle's gate hook and MCP server; required.
MOSAIC_THINKING The route's thinking level (row 65), which the harness module's levels() already checked. pi passes --thinking (off, minimal, low, medium, high, xhigh, max) and omits it when unset, as for run-task.sh workers. claude passes --effort (low, medium, high, xhigh, max) and requires it; unset exits 2.
MOSAIC_CLAUDE_BIN claude only: absolute path of the CLI to run, from the host's environment (the bus unit pins it). Unset or empty runs claude from PATH; a relative path or a non-executable file exits 2.

The layers each adapter relies on, and what they don't cover, are in packages/harness/README.md.

A role's skills (row 64)

A managed session's skills reach both adapters as text in the bundle's prompt.md, which they pass as a file: pi with --system-prompt <path> and claude with --system-prompt-file <path> (row 213). Neither adapter loads a skill of its own: pi keeps --no-skills, since role sessions never get MOSAIC_SKILLS, and claude keeps --disable-slash-commands and --restricted. Sage chose this on 2026-10-19 from a probe, recorded in agents/sage/work/queue-64/probe.md:

  • Pi's --skill puts only a skill's name and description in the prompt, and the model has to read the SKILL.md itself. The gate refuses every file-tool path outside the workspace, so the session couldn't open its own skills. Opening the gate to the bundle would change a security boundary.
  • Claude Code loads a bundle-local --plugin-dir skill under --restricted only with its Skill tool on, and then it also offers its own bundled skills. Which ones it offers changes with the Claude Code version, and the Skill tool would pass through the gate hook.

The cost is prompt size: a role's skill text is in every turn, where the other routes load a skill when it's used. The bundle caps a role's skills at 64 KiB together. The cap dates from when claude passed prompt.md as one argument, which Linux caps at 128 KiB; row 213 passes the file instead, so no local user reads the prompt in /proc/<pid>/cmdline. Pi 0.85.1 uses the path string itself as the prompt when the file is missing or can't be read, so the pi adapter exits 2 unless the path is a readable regular file.