From bb5cecb348bf06c8e4ac9618a580c2405436d241 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Wed, 2 Sep 2026 21:18:07 -0500 Subject: [PATCH 1/4] 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" From 4ebb123ba36ab2c97403de18dc8197e464d0c03e Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Wed, 2 Sep 2026 21:19:22 -0500 Subject: [PATCH 2/4] feat(adapters): sanctioned mission directives injection (#17) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - load-contracts.sh: MOSAIC_MISSION_FILE (readable) appends a MISSION (runtime) section — objective + directives — after the immutable contracts; unreadable path is a hard error, absent env changes nothing - mosaic-task.mjs: exports MOSAIC_MISSION_FILE as the run snapshot's container path (/var/lib/mosaic/runs//mission.json), with an outside-dataRoot guard; also exports the configured adapter Verified: contract-only prompt has no mission section; mission-bearing run shows objective + directives in the generated prompt, snapshot recorded, real provider returns exactly MOSAIC_HELLO_OK. Closes #17 --- scripts/mosaic-task.mjs | 15 ++++++++++++++- scripts/test-config.sh | 14 ++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/scripts/mosaic-task.mjs b/scripts/mosaic-task.mjs index 12610036..b224cf43 100755 --- a/scripts/mosaic-task.mjs +++ b/scripts/mosaic-task.mjs @@ -210,12 +210,25 @@ function runTask(taskFile) { const startedAt = new Date(); const stderrFile = path.join(runDir, "stderr.txt"); + + // Sanctioned mission injection: point the container at the run snapshot's + // CONTAINER path (dataRoot maps to /var/lib/mosaic in the image). + const spawnEnv = { ...process.env }; + spawnEnv.MOSAIC_ADAPTER = resolved.execution.adapter; + if (task.missionSnapshot) { + const relative = path.relative(resolved.dataRoot, runDir); + if (relative.startsWith("..") || path.isAbsolute(relative)) { + fail(4, `run directory is outside the configured dataRoot: ${runDir}`); + } + spawnEnv.MOSAIC_MISSION_FILE = `/var/lib/mosaic/${relative.split(path.sep).join("/")}/mission.json`; + } + const proc = spawnSync( "docker", ["compose", "run", "--rm", "-T", "mosaic-agent", task.prompt], { cwd: PROJECT_ROOT, - env: process.env, // MOSAIC_DATA_ROOT / MOSAIC_PROVIDER / MOSAIC_MODEL resolved by run-task.sh + env: spawnEnv, input: "", // stdin detached: print mode must never wait on a terminal (see issue #5) encoding: "utf8", maxBuffer: 16 * 1024 * 1024, diff --git a/scripts/test-config.sh b/scripts/test-config.sh index cc5e34b5..b1b5d5a1 100755 --- a/scripts/test-config.sh +++ b/scripts/test-config.sh @@ -40,6 +40,20 @@ cfg() { printf '%s' "$2" > "$SANDBOX/$1"; } DATA_ROOT="$SANDBOX/data" +# --- adapter selection (M4) --- +cfg default-adapter.json '{"configVersion":1,"environment":"development","dataRoot":"'$DATA_ROOT'","execution":{"backend":"docker","provider":"zai","model":"m"}}' +MOSAIC_CONFIG="$SANDBOX/default-adapter.json" $CONFIG_OP validate | grep -q '"adapter": "pi"' +check "absent adapter defaults to pi" $? + +cfg mock-adapter.json '{"configVersion":1,"environment":"development","dataRoot":"'$DATA_ROOT'","execution":{"backend":"docker","provider":"zai","model":"m","adapter":"mock"}}' +expect_exit "adapter mock validates" 0 -- env MOSAIC_CONFIG="$SANDBOX/mock-adapter.json" $CONFIG_OP validate + +cfg bad-adapter.json '{"configVersion":1,"environment":"development","dataRoot":"'$DATA_ROOT'","execution":{"backend":"docker","provider":"zai","model":"m","adapter":"claude"}}' +expect_exit "unsupported adapter exits 2" 2 -- env MOSAIC_CONFIG="$SANDBOX/bad-adapter.json" $CONFIG_OP validate + +MOSAIC_CONFIG="$SANDBOX/mock-adapter.json" $CONFIG_OP env | grep -q "MOSAIC_ADAPTER='mock'" +check "env exports adapter" $? + # --- bootstrap --- rm -f "$SANDBOX/config.json" expect_exit "bootstrap creates default when absent" 0 -- \ From 3c1ffd2c2df618941aee804c3e3d0d090d15eb54 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Wed, 2 Sep 2026 21:28:57 -0500 Subject: [PATCH 3/4] =?UTF-8?q?test(adapters):=20seam=20selftests=20?= =?UTF-8?q?=E2=80=94=20deterministic=20mock=20cases=20+=20mission=20inject?= =?UTF-8?q?ion=20(#18)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - test-config: absent adapter defaults to pi; mock validates; unknown adapter exits 2; env exports MOSAIC_ADAPTER (24 cases total) - test-task: mock adapter gate pass/mismatch (no provider needed), mismatch reason asserted, unknown adapter fails closed, mission section injected into generated prompt asserted by content (24 cases total) - harness fixes: helpers defined before use; per-case config files (no cross-case leakage); newest-run selection for the live case; deduped accidentally duplicated live block Closes #18 --- README.md | 20 +++++++++++++- scripts/test-config.sh | 4 +++ scripts/test-task.sh | 59 ++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 80 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3788bc93..3e7c3efb 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,24 @@ scripts/test-release.sh # release selftests A failed health check never activates; the previously active release remains deployed. Updating the software therefore cannot corrupt the running installation: package beside, gate, then flip. Verified by the update/refusal/rollback drills in BUILD-LOG Phase 7. +## Runtime adapters (M4) + +The harness boundary is formalized: everything upstream (config, contracts, missions, tasks, run records) is harness-agnostic; everything inside an adapter belongs to one runtime. + +```text +adapters//adapter.sh env in: MOSAIC_SYSTEM_PROMPT_FILE, MOSAIC_REQUEST, + MOSAIC_PROVIDER, MOSAIC_MODEL + stdout: response only; stderr: diagnostics +``` + +- Selection: `execution.adapter` in config.json (optional; `pi` default; allowlist `pi`, `mock`) +- `pi` — pinned Pi CLI, noninteractive print mode, ambient discovery off +- `mock` — deterministic test adapter; never for real verification +- Mission directives have a sanctioned injection point: when a task references a mission, the task runner mounts the run snapshot and the generated prompt gains a `MISSION (runtime)` section (objective + directives) after the four immutable contracts +- Adding a harness (Claude, Codex, OpenCode) later means adding one directory — no orchestrator changes + +See `adapters/README.md` for the full contract. + See `docs/plans/2026-09-02_atomic-mosaic-foundation.md` for the full plan. Inside the container: @@ -137,7 +155,7 @@ scripts/verify.sh # full gated test; exit 0 only on exact MOSAIC_HELLO_OK scripts/run-task.sh # run a mission/task file (see Missions & tasks) scripts/release.sh # package / activate / rollback / status (see Release model) scripts/test-config.sh # fast config-layer selftests (no Docker) -scripts/test-task.sh # mission/task selftests (schema + live runs) +scripts/test-task.sh # mission/task selftests (schema + adapter seam + live runs) scripts/test-release.sh # release selftests scripts/reset.sh # delete the configured data root (safety-checked) ``` diff --git a/scripts/test-config.sh b/scripts/test-config.sh index b1b5d5a1..6aaba50d 100755 --- a/scripts/test-config.sh +++ b/scripts/test-config.sh @@ -12,6 +12,10 @@ trap 'rm -rf "$SANDBOX"' EXIT PASS=0 FAIL=0 +check() { + if [ "$2" = "0" ]; then PASS=$((PASS+1)); echo "ok $1"; else FAIL=$((FAIL+1)); echo "FAIL $1"; fi +} + # expect_exit NAME EXPECTED_RC -- command... expect_exit() { local name="$1" expected="$2" diff --git a/scripts/test-task.sh b/scripts/test-task.sh index c6e421b4..d5506f3d 100755 --- a/scripts/test-task.sh +++ b/scripts/test-task.sh @@ -30,6 +30,16 @@ check() { if [ "$2" = "0" ]; then PASS=$((PASS+1)); echo "ok $1"; else FAIL=$((FAIL+1)); echo "FAIL $1"; fi } +latest_reason() { + local latest + latest="$(ls -dt "$SANDBOX/data/runs"/r-* 2>/dev/null | head -1)" + [ -n "$latest" ] && node -e 'try{const r=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));console.log(r.reason??"")}catch{console.log("")}' "$latest/result.json" 2>/dev/null +} + +check() { + if [ "$2" = "0" ]; then PASS=$((PASS+1)); echo "ok $1"; else FAIL=$((FAIL+1)); echo "FAIL $1"; fi +} + CONFIG="$SANDBOX/config.json" DATA_ROOT="$SANDBOX/data" mkdir -p "$DATA_ROOT" @@ -92,6 +102,50 @@ $TASK validate "$SANDBOX/ok.json" >/dev/null 2>&1 M2=$(stat -c %Y "$SANDBOX/ok.json") [ "$M1" = "$M2" ] && check "validation does not modify the task file" 0 || check "validation does not modify the task file" 1 +# ---------- adapter seam: deterministic mock cases (Docker, no provider) ---------- +if docker info >/dev/null 2>&1; then + good_task "$SANDBOX/ok.json" + mock_config() { # file adapter + cat > "$SANDBOX/$1" < "$SANDBOX/mission-task.json" + # Dedicated mission with distinctive directives for the injection assertion. + cat > "$SANDBOX/m-seam.json" <<'EOF' +{"missionVersion":1,"id":"m-seam","objective":"Prove the mission injection point.","directives":["Seam directive A.","Seam directive B."]} +EOF + printf '{"taskVersion":1,"id":"t-mission-seam","prompt":"ignored by mock","mission":"m-seam.json"}' > "$SANDBOX/seam-task.json" + expect_exit "mission task runs via mock adapter" 0 -- \ + env MOSAIC_CONFIG="$SANDBOX/mock-adapters.json" MOSAIC_MOCK_RESPONSE=MOCKED \ + scripts/run-task.sh run "$SANDBOX/seam-task.json" + grep -q 'MISSION (runtime)' "$SANDBOX/data/system-prompt.md" \ + && grep -q 'Seam directive A.' "$SANDBOX/data/system-prompt.md" \ + && check "mission section injected into generated prompt" 0 \ + || check "mission section injected into generated prompt" 1 +else + echo "skip adapter seam cases (docker daemon unavailable)" +fi + # ---------- live: real runs (Docker + credentials required) ---------- # On failure, surface the run record + agent stderr BEFORE the sandbox # cleanup destroys them. Never let a wrong-exit mask the real reason. @@ -115,14 +169,15 @@ latest_reason() { } if docker info >/dev/null 2>&1; then + RUNS1=$(ls "$DATA_ROOT/runs" 2>/dev/null | wc -l) if scripts/run-task.sh run "$SANDBOX/ok.json" >/dev/null 2>&1; then PASS=$((PASS+1)); echo "ok live hello task succeeds with exact marker" else FAIL=$((FAIL+1)); echo "FAIL live hello task succeeds with exact marker" >&2 dump_latest_run fi - [ -f "$DATA_ROOT/runs" ] && RUNS1=$(ls "$DATA_ROOT/runs" | wc -l) - R1="$(ls "$DATA_ROOT/runs" | head -1)" + + R1="$(ls -t "$DATA_ROOT/runs" | head -1)" # newest = the live run above [ -f "$DATA_ROOT/runs/$R1/result.json" ] && check "result.json written in run dir" 0 || check "result.json written in run dir" 1 node -e ' const r = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")); From 594b8d711c1238cbdbc5b13284a00f222e6cf9d2 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Wed, 2 Sep 2026 21:30:35 -0500 Subject: [PATCH 4/4] docs(adapters): adapter seam docs + recorded M4 E2E, release 0.0.5 (#19) - README: Runtime adapters section (contract summary, selection, mission injection point); BUILD-LOG Phase 8 entries - E2E: 24+24+14 selftests green; verify PASS; 0.0.5 packaged and health-gated activated; mission-bearing fixture task succeeded through the real pi adapter; config checksum unchanged Closes #19 --- BUILD-LOG.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/BUILD-LOG.md b/BUILD-LOG.md index 19d91652..1d40b4b4 100644 --- a/BUILD-LOG.md +++ b/BUILD-LOG.md @@ -192,4 +192,33 @@ Mission/task layer verified end-to-end. `main` merged with M2 and tagged `missio Release model and safe updates verified by drills. `main` merged with M3 and tagged `release-model-v1`. +--- + +## Phase 8: Runtime adapter seam (M4) + +### Entry 8.1 — before + +- Timestamp: 2026-09-03 +- Intended action: Formalize the harness boundary (Gitea milestone M4, issues #16-#19): documented adapter contract under /opt/mosaic/adapters//adapter.sh; run-agent.sh becomes a dispatcher; pi extracted unchanged; deterministic mock adapter for provider-free seam tests; config gains optional execution.adapter (default pi, configVersion unchanged); mission directives gain their sanctioned injection point via the run snapshot; RELEASE bumps to 0.0.5 with a health-gated activation. +- Reason: Future harnesses (Claude, Codex, OpenCode) must be additive — one directory each — and mission content needs a single sanctioned path into the runtime. +- Expected result: All suites green including new deterministic seam cases; 0.0.5 activated by health gate; mission-bearing run recorded. + +### Entry 8.2 — after + +- Timestamp: 2026-09-03 +- Commands run: scripts/test-config.sh; scripts/test-task.sh; scripts/test-release.sh; manual seam drills (mock verbatim, unknown/traversal adapter refusal); mission injection checks; release package + activate for 0.0.5. +- Observed result: + - Config suite 24/24 (adapter default/validation/env export). + - Task suite 24/24 including deterministic mock cases (gate pass, expect-mismatch with reason, unknown adapter fail-closed) and mission injection asserted by prompt content. + - Release suite 14/14; image mosaic-poc-agent:0.84.4-r0.0.5 packaged and activated via exact-marker health gate. + - Mission directives now flow: task -> run snapshot -> container env -> generated prompt MISSION (runtime) section. +- Failure or correction: + 1. Selection authority settled: load_config always exports MOSAIC_ADAPTER from config; environment overrides for scripts are therefore not a supported selection path (by design). + 2. Selftest harness: three authoring defects fixed (helpers used before definition; one config file reused across cases leaking adapter state; a static mission fixture asserted against distinctive seam directives; plus an accidentally duplicated live block removed). +- Credential check: no credential material in adapters, prompts, run records, or logs. + +## Result (M4) + +Adapter seam verified; harness boundary is now additive by construction. `main` merged with M4 and tagged `adapter-seam-v1`. +