jason.woltje
bb5cecb348
- adapters/README.md: the harness boundary contract (env in, response on stdout, diagnostics stderr, exit 0 success) - adapters/pi: extracted current invocation unchanged - adapters/mock: deterministic MOSAIC_MOCK_RESPONSE echo (test-only) - run-agent.sh: name-validated dispatch to adapters/<name>/adapter.sh - config: optional execution.adapter (pi|mock), default pi, configVersion stays 1 — existing configs remain valid; selection authority is the config file (load_config exports it) - compose: MOSAIC_ADAPTER / MOSAIC_MOCK_RESPONSE passthrough; Containerfile installs adapters read-only; RELEASE -> 0.0.5 Verified: hello unchanged; mock verbatim via config; unknown adapter and path-traversal names refused in-container; invalid adapter exits 2. Closes #16
1.9 KiB
1.9 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 capturesstderr: diagnostics (never credentials)- exit
0: success; nonzero: failure
Rules
- Adapters print ONLY the response on stdout. Status lines go to stderr.
- Adapters never read configuration files; the resolved settings arrive via environment.
- Adapters never write outside
/var/lib/mosaic. - Adding an adapter requires: a new directory, the contract implementation, and
adding the name to the allowlist in
scripts/mosaic-config.mjs.
Included adapters
pi— the pinned@earendil-works/pi-coding-agentCLI in noninteractive print mode (-p), ambient discovery disabled, stdin detached.mock— deterministic echo ofMOSAIC_MOCK_RESPONSE. Test-only: never use it where a real model response is required.