feat(adapters): adapter contract, dispatch, pi + mock adapters (#16)

- 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

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

RELEASE

@@ -1 +1 @@
-0.0.3
+0.0.5

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

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

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"

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.

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

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"),
     );

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

src/run-agent.sh

@@ -1,38 +1,33 @@
 #!/bin/sh
-# One-shot Pi agent runner inside the container.
+# One-shot agent dispatcher inside the container.
-# Loads the contract-generated system prompt, then sends exactly one
+#
-# user request through Pi's documented noninteractive mode and prints
+# 1. Loads the contract-generated system prompt (contracts + optional
-# the model response on stdout.
+#    mission section from MOSAIC_MISSION_FILE).
+# 2. Dispatches to /opt/mosaic/adapters/<MOSAIC_ADAPTER>/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):
+export MOSAIC_SYSTEM_PROMPT_FILE="/var/lib/mosaic/system-prompt.md"
-#   -p / --print        noninteractive: print the response and exit
+export MOSAIC_REQUEST="$REQUEST"
-#   --system-prompt     replace the default system prompt with the
+
-#                       contract-generated prompt
+exec "$ADAPTER_SCRIPT"
-#   --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"