From bb5cecb348bf06c8e4ac9618a580c2405436d241 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Wed, 2 Sep 2026 21:18:07 -0500 Subject: [PATCH] feat(adapters): adapter contract, dispatch, pi + mock adapters (#16) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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//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 --- Containerfile | 7 +++-- RELEASE | 2 +- adapters/README.md | 54 +++++++++++++++++++++++++++++++++++++ adapters/mock/adapter.sh | 13 +++++++++ adapters/pi/adapter.sh | 33 +++++++++++++++++++++++ compose.yaml | 7 +++++ scripts/common.sh | 2 +- scripts/mosaic-config.mjs | 12 ++++++++- src/load-contracts.sh | 18 +++++++++++++ src/run-agent.sh | 57 ++++++++++++++++++--------------------- 10 files changed, 169 insertions(+), 36 deletions(-) create mode 100644 adapters/README.md create mode 100644 adapters/mock/adapter.sh create mode 100644 adapters/pi/adapter.sh diff --git a/Containerfile b/Containerfile index 97e777dc..42aca597 100644 --- a/Containerfile +++ b/Containerfile @@ -18,11 +18,14 @@ WORKDIR /opt/app COPY package.json package-lock.json ./ RUN npm ci --ignore-scripts -# Immutable contract fixtures (required location) and runtime scripts. +# Immutable contract fixtures (required location), runtime scripts, and +# runtime adapters. COPY contracts /opt/mosaic/contracts COPY src /opt/mosaic/src +COPY adapters /opt/mosaic/adapters RUN chmod 0555 /opt/mosaic/contracts /opt/mosaic/contracts/* \ - && chmod 0555 /opt/mosaic/src /opt/mosaic/src/*.sh + && chmod 0555 /opt/mosaic/src /opt/mosaic/src/*.sh \ + && chmod 0555 /opt/mosaic/adapters /opt/mosaic/adapters/*/adapter.sh # Writable state, workspace, and pi agent directory (auth.json is # bind-mounted read-only at runtime; nothing is copied into the image). diff --git a/RELEASE b/RELEASE index bcab45af..bbdeab62 100644 --- a/RELEASE +++ b/RELEASE @@ -1 +1 @@ -0.0.3 +0.0.5 diff --git a/adapters/README.md b/adapters/README.md new file mode 100644 index 00000000..33ed6ded --- /dev/null +++ b/adapters/README.md @@ -0,0 +1,54 @@ +# 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: + +```text +/opt/mosaic/adapters//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 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-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. diff --git a/adapters/mock/adapter.sh b/adapters/mock/adapter.sh new file mode 100644 index 00000000..e5fb505a --- /dev/null +++ b/adapters/mock/adapter.sh @@ -0,0 +1,13 @@ +#!/bin/sh +# Mock adapter: deterministic response for seam tests. NEVER use where a +# real model response is required. +# +# Contract: see /opt/mosaic/adapters/README.md. +set -eu + +[ -n "${MOSAIC_SYSTEM_PROMPT_FILE:-}" ] || { echo "mock adapter: MOSAIC_SYSTEM_PROMPT_FILE is required" >&2; exit 2; } +[ -n "${MOSAIC_REQUEST:-}" ] || { echo "mock adapter: MOSAIC_REQUEST is required" >&2; exit 2; } +[ -r "$MOSAIC_SYSTEM_PROMPT_FILE" ] || { echo "mock adapter: system prompt not readable: $MOSAIC_SYSTEM_PROMPT_FILE" >&2; exit 2; } + +echo "mock adapter: responding verbatim from MOSAIC_MOCK_RESPONSE" >&2 +printf '%s\n' "${MOSAIC_MOCK_RESPONSE:-}" diff --git a/adapters/pi/adapter.sh b/adapters/pi/adapter.sh new file mode 100644 index 00000000..3a9bc251 --- /dev/null +++ b/adapters/pi/adapter.sh @@ -0,0 +1,33 @@ +#!/bin/sh +# Pi adapter: implements the Mosaic adapter contract for the pinned +# @earendil-works/pi-coding-agent CLI. +# +# Contract: see /opt/mosaic/adapters/README.md. stdout = response only. +set -eu + +[ -n "${MOSAIC_SYSTEM_PROMPT_FILE:-}" ] || { echo "pi adapter: MOSAIC_SYSTEM_PROMPT_FILE is required" >&2; exit 2; } +[ -n "${MOSAIC_REQUEST:-}" ] || { echo "pi adapter: MOSAIC_REQUEST is required" >&2; exit 2; } +[ -r "$MOSAIC_SYSTEM_PROMPT_FILE" ] || { echo "pi adapter: system prompt not readable: $MOSAIC_SYSTEM_PROMPT_FILE" >&2; exit 2; } + +: "${PI_PROVIDER:?pi adapter: PI_PROVIDER is required}" +: "${PI_MODEL:?pi adapter: PI_MODEL is required}" + +# All flags documented in the pi package README (CLI Reference): +# -p/--print noninteractive: print the response and exit +# --system-prompt replace the default prompt with the generated one +# --no-* no ambient context/skills/extensions/templates/themes +# --no-session ephemeral; --no-tools this runtime needs no tools +# --offline no startup network operations (update checks/telemetry) +exec pi \ + --offline \ + --no-session \ + --no-extensions \ + --no-skills \ + --no-prompt-templates \ + --no-themes \ + --no-context-files \ + --no-tools \ + --provider "$PI_PROVIDER" \ + --model "$PI_MODEL" \ + --system-prompt "$(cat "$MOSAIC_SYSTEM_PROMPT_FILE")" \ + -p "$MOSAIC_REQUEST" diff --git a/compose.yaml b/compose.yaml index 0defc3a1..027ddca4 100644 --- a/compose.yaml +++ b/compose.yaml @@ -10,6 +10,13 @@ services: # Required: compose fails fast when the launcher did not supply them. PI_PROVIDER: ${MOSAIC_PROVIDER:?MOSAIC_PROVIDER must be set by scripts/load_config (run via scripts/*.sh)} PI_MODEL: ${MOSAIC_MODEL:?MOSAIC_MODEL must be set by scripts/load_config (run via scripts/*.sh)} + # Adapter selection (resolved from config execution.adapter; default pi) + MOSAIC_ADAPTER: ${MOSAIC_ADAPTER:-pi} + # Mission directives injection point (set by the task runner when the + # task references a mission; container path of the run snapshot) + MOSAIC_MISSION_FILE: ${MOSAIC_MISSION_FILE:-} + # mock adapter only: verbatim response for deterministic seam tests + MOSAIC_MOCK_RESPONSE: ${MOSAIC_MOCK_RESPONSE:-} # Documented container auth alternative: provider API key via # runtime environment variable. Empty by default; when empty Pi # falls back to the read-only mounted auth.json credential file. diff --git a/scripts/common.sh b/scripts/common.sh index b62e6a59..dc8d61ff 100755 --- a/scripts/common.sh +++ b/scripts/common.sh @@ -15,7 +15,7 @@ load_config() { exit 1 fi eval "$config_env" - export MOSAIC_DATA_ROOT MOSAIC_PROVIDER MOSAIC_MODEL + export MOSAIC_DATA_ROOT MOSAIC_PROVIDER MOSAIC_MODEL MOSAIC_ADAPTER MOSAIC_DEV_DIR="$MOSAIC_DATA_ROOT" } diff --git a/scripts/mosaic-config.mjs b/scripts/mosaic-config.mjs index c209e255..cd66560d 100755 --- a/scripts/mosaic-config.mjs +++ b/scripts/mosaic-config.mjs @@ -30,6 +30,7 @@ import process from "node:process"; const SUPPORTED_CONFIG_VERSION = 1; const SUPPORTED_ENVIRONMENTS = new Set(["development", "production"]); const SUPPORTED_BACKENDS = new Set(["docker"]); +const SUPPORTED_ADAPTERS = new Set(["pi", "mock"]); // mock: test-only, see adapters/README.md const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/; function fail(exitCode, message) { @@ -127,7 +128,7 @@ function validate(document, file) { if (!isPlainObject(document.execution)) { fail(2, '"execution" must be a JSON object'); } - rejectUnknownKeys(document.execution, ["backend", "provider", "model"], '"execution"'); + rejectUnknownKeys(document.execution, ["backend", "provider", "model", "adapter"], '"execution"'); if (!SUPPORTED_BACKENDS.has(document.execution.backend)) { fail(2, `unsupported execution.backend: ${JSON.stringify(document.execution.backend)} (supported: ${[...SUPPORTED_BACKENDS].join(", ")})`); } @@ -138,6 +139,13 @@ function validate(document, file) { } } + const adapter = document.execution.adapter === undefined || document.execution.adapter === null + ? "pi" + : document.execution.adapter; + if (typeof adapter !== "string" || !SUPPORTED_ADAPTERS.has(adapter)) { + fail(2, `unsupported execution.adapter: ${JSON.stringify(adapter)} (supported: ${[...SUPPORTED_ADAPTERS].join(", ")})`); + } + return { configVersion: document.configVersion, environment: document.environment, @@ -146,6 +154,7 @@ function validate(document, file) { backend: document.execution.backend, provider: document.execution.provider, model: document.execution.model, + adapter, }, }; } @@ -222,6 +231,7 @@ switch (operation) { `MOSAIC_DATA_ROOT=${shellQuote(resolved.dataRoot)}`, `MOSAIC_PROVIDER=${shellQuote(resolved.execution.provider)}`, `MOSAIC_MODEL=${shellQuote(resolved.execution.model)}`, + `MOSAIC_ADAPTER=${shellQuote(resolved.execution.adapter)}`, "", ].join("\n"), ); diff --git a/src/load-contracts.sh b/src/load-contracts.sh index 4c4d58fe..d1e771af 100755 --- a/src/load-contracts.sh +++ b/src/load-contracts.sh @@ -33,5 +33,23 @@ for f in $FILES; do printf '\n' >> "$TEMP" done +# Sanctioned mission injection point (M4): when the task runner provides a +# mission snapshot, its objective and directives are appended AFTER the +# immutable contracts. Runtime data; never part of the contract fixtures. +if [ -n "${MOSAIC_MISSION_FILE:-}" ]; then + if [ ! -r "$MOSAIC_MISSION_FILE" ]; then + echo "load-contracts: MOSAIC_MISSION_FILE set but not readable: $MOSAIC_MISSION_FILE" >&2 + rm -f "$TEMP" + exit 1 + fi + printf '===== MISSION (runtime) =====\n' >> "$TEMP" + node -e ' +const m = JSON.parse(require("fs").readFileSync(process.env.MOSAIC_MISSION_FILE, "utf8")); +process.stdout.write("Objective: " + m.objective + "\n"); +for (const d of m.directives ?? []) process.stdout.write("- " + d + "\n"); +' >> "$TEMP" + printf '\n' >> "$TEMP" +fi + mv "$TEMP" "$OUT" echo "load-contracts: wrote $OUT from $CONTRACT_DIR" >&2 diff --git a/src/run-agent.sh b/src/run-agent.sh index 2bd804fa..d777a4fc 100755 --- a/src/run-agent.sh +++ b/src/run-agent.sh @@ -1,38 +1,33 @@ #!/bin/sh -# One-shot Pi agent runner inside the container. -# Loads the contract-generated system prompt, then sends exactly one -# user request through Pi's documented noninteractive mode and prints -# the model response on stdout. +# One-shot agent dispatcher inside the container. +# +# 1. Loads the contract-generated system prompt (contracts + optional +# mission section from MOSAIC_MISSION_FILE). +# 2. Dispatches to /opt/mosaic/adapters//adapter.sh per +# the contract in /opt/mosaic/adapters/README.md. set -eu -: "${PI_PROVIDER:=zai}" -: "${PI_MODEL:=glm-5.3-flash}" -export PI_PROVIDER PI_MODEL - REQUEST="${*:-Return your startup marker and nothing else.}" +ADAPTER="${MOSAIC_ADAPTER:-pi}" +case "$ADAPTER" in + # Allowlist mirrors scripts/mosaic-config.mjs; pattern check first so a + # crafted name cannot escape the adapters directory. + *[!A-Za-z0-9._-]*|'') + echo "run-agent: invalid adapter name: '$ADAPTER'" >&2 + exit 2 + ;; +esac + +ADAPTER_SCRIPT="/opt/mosaic/adapters/$ADAPTER/adapter.sh" +if [ ! -x "$ADAPTER_SCRIPT" ]; then + echo "run-agent: unknown or non-executable adapter: $ADAPTER" >&2 + exit 2 +fi + /opt/mosaic/src/load-contracts.sh /opt/mosaic/contracts /var/lib/mosaic/system-prompt.md -# All flags are documented in the package README (CLI Reference): -# -p / --print noninteractive: print the response and exit -# --system-prompt replace the default system prompt with the -# contract-generated prompt -# --no-* switches prevent ambient context files, skills, extensions, -# prompt templates, and themes from being appended -# --no-session ephemeral: no persistent agent session -# --no-tools the startup request needs no tool execution -# --offline disable startup network operations (update checks, -# package update checks, install/update telemetry) -exec pi \ - --offline \ - --no-session \ - --no-extensions \ - --no-skills \ - --no-prompt-templates \ - --no-themes \ - --no-context-files \ - --no-tools \ - --provider "$PI_PROVIDER" \ - --model "$PI_MODEL" \ - --system-prompt "$(cat /var/lib/mosaic/system-prompt.md)" \ - -p "$REQUEST" +export MOSAIC_SYSTEM_PROMPT_FILE="/var/lib/mosaic/system-prompt.md" +export MOSAIC_REQUEST="$REQUEST" + +exec "$ADAPTER_SCRIPT"