@alignfirst/openclaw-test 0.20.0

package/dist/transcript-log.js

@@ -0,0 +1,199 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync, rmSync } from "node:fs";
+import { getQaBusState } from "@alignfirst/openclaw-channel-mock-core";
+import { execInGateway, IPC_DIR } from "./exec-rpc.js";
+// OpenClaw persists each session's transcript as SQLite rows in the gateway's
+// per-agent store — the full-fidelity record the gateway itself replays,
+// appended per message. That store lives outside the shared mounts, so the
+// runner extracts a conversation's session transcripts through the
+// exec-watcher RPC: the dump script (shipped in this package's dist, mounted
+// into the gateway) writes them as JSON into the shared IPC volume.
+const DUMP_SCRIPT = "/opt/openclaw-test/src/dist/transcript-dump.js";
+const BUS_URL = process.env.OPENCLAW_TEST_BUS_URL ?? "http://bus:43123";
+/** The transcripts of the conversation and its bus-owned thread sessions. */
+export async function fetchTranscriptSnapshot(opts) {
+    const outPath = `${IPC_DIR}/${randomUUID()}.transcript.json`;
+    try {
+        const { threads } = await getQaBusState(BUS_URL);
+        const conversationId = opts.conversationId.toLowerCase();
+        const threadIds = threads
+            .filter((thread) => thread.conversationId.toLowerCase() === conversationId)
+            .map((thread) => thread.id);
+        const result = await execInGateway(["node", DUMP_SCRIPT, opts.startedAtIso, opts.conversationId, outPath, ...threadIds], 
+        // A whole conversation can take a while to serialize; the default 30s
+        // exec timeout is too tight for long cells.
+        { timeoutMs: 60_000 });
+        if (result.exitCode !== 0) {
+            const error = `transcript dump failed (exit ${result.exitCode}): ${result.stderr}`;
+            console.warn(`openclaw-test: ${error}`);
+            return { databases: 0, sessions: [], error };
+        }
+        const raw = readFileSync(outPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const error = `transcript dump failed: ${String(err)}`;
+        console.warn(`openclaw-test: ${error}`);
+        return { databases: 0, sessions: [], error };
+    }
+    finally {
+        rmSync(outPath, { force: true });
+    }
+}
+/**
+ * Polls the transcripts until they are *quiescent* for this conversation — no
+ * new message for `settleMs` AND no session's turn is demonstrably open — or
+ * the budget expires. The transcript is appended per message, so a settle
+ * window alone would return between two tool calls of one turn (a single
+ * model round-trip routinely exceeds it); the open-turn gate holds until the
+ * turn-final assistant message — the one carrying `usage.cost.total` — has
+ * landed. A conversation spans multiple OpenClaw sessions (e.g. Discord's
+ * channel session plus a per-thread session).
+ */
+export async function waitForTranscriptQuiescence(opts) {
+    const maxWaitMs = opts.maxWaitMs ?? 60_000;
+    const pollMs = opts.pollMs ?? 1_000;
+    const settleMs = opts.settleMs ?? 4_000;
+    const deadline = Date.now() + maxWaitMs;
+    let lastCount = 0;
+    let lastChangeAt = Date.now();
+    let seenAny = false;
+    while (Date.now() < deadline) {
+        const { sessions } = await fetchTranscriptSnapshot(opts);
+        const count = sessions.reduce((sum, s) => sum + s.messages.length, 0);
+        if (count > 0)
+            seenAny = true;
+        if (count !== lastCount) {
+            lastCount = count;
+            lastChangeAt = Date.now();
+        }
+        else if (seenAny && !hasOpenTurn(sessions) && Date.now() - lastChangeAt >= settleMs) {
+            return;
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+}
+/**
+ * A turn is open when a session's last message is a tool result or an
+ * assistant stop for tool use — more of the turn is coming. A trailing user
+ * message does not count as open: some sessions of a conversation never get a
+ * reply (the agent answers in a sibling session), and treating them as open
+ * would burn the whole budget on every cell.
+ */
+export function hasOpenTurn(sessions) {
+    return sessions.some((session) => {
+        const last = session.messages.at(-1);
+        if (!isRecord(last))
+            return false;
+        if (last.role === "toolResult")
+            return true;
+        return last.role === "assistant" && last.stopReason === "toolUse";
+    });
+}
+/**
+ * Cost lives per assistant message, as `usage.cost.total`. Sum across every
+ * session of the conversation; `turns` counts the cost-bearing messages.
+ */
+export function readTranscriptCost(snapshot) {
+    let cost = 0;
+    let turns = 0;
+    for (const session of snapshot.sessions) {
+        for (const msg of session.messages) {
+            if (!isRecord(msg) || msg.role !== "assistant")
+                continue;
+            const total = assistantCostTotal(msg);
+            if (typeof total !== "number")
+                continue;
+            cost += total;
+            turns += 1;
+        }
+    }
+    return { cost, turns };
+}
+function assistantCostTotal(msg) {
+    const usage = msg.usage;
+    if (!isRecord(usage))
+        return;
+    const cost = usage.cost;
+    if (!isRecord(cost))
+        return;
+    return typeof cost.total === "number" ? cost.total : undefined;
+}
+/** One-shot fetch + aggregation of the conversation's agent tool calls. */
+export async function parseAgentToolCalls(opts) {
+    const { sessions } = await fetchTranscriptSnapshot(opts);
+    return aggregateAgentToolCalls(sessions);
+}
+/**
+ * Walk each session's messages collecting assistant `toolCall` blocks matched
+ * with `toolResult` messages, then union across sessions deduped by
+ * `toolUseId`.
+ */
+export function aggregateAgentToolCalls(sessions) {
+    const calls = [];
+    const seen = new Set();
+    for (const session of sessions) {
+        const results = collectToolResults(session.messages);
+        for (const call of collectToolUses(session.messages, results, session.sessionKey)) {
+            if (seen.has(call.toolUseId))
+                continue;
+            seen.add(call.toolUseId);
+            calls.push(call);
+        }
+    }
+    return calls;
+}
+function collectToolResults(messages) {
+    const results = new Map();
+    for (const msg of messages) {
+        if (!isRecord(msg) || msg.role !== "toolResult")
+            continue;
+        const toolCallId = msg.toolCallId;
+        if (typeof toolCallId !== "string")
+            continue;
+        results.set(toolCallId, { isError: msg.isError === true, content: msg.content ?? null });
+    }
+    return results;
+}
+function collectToolUses(messages, results, sessionKey) {
+    const calls = [];
+    let turn = 0;
+    for (const msg of messages) {
+        if (!isRecord(msg) || msg.role !== "assistant" || !Array.isArray(msg.content))
+            continue;
+        turn += 1;
+        for (const block of msg.content) {
+            if (!isRecord(block) || block.type !== "toolCall")
+                continue;
+            const toolUseId = typeof block.id === "string" ? block.id : "";
+            const toolName = typeof block.name === "string" ? block.name : "";
+            if (!toolUseId || !toolName)
+                continue;
+            const startedAt = messageTimestampIso(msg);
+            const call = {
+                toolName,
+                toolUseId,
+                ...(sessionKey !== undefined ? { sessionKey } : {}),
+                input: block.arguments ?? null,
+                ...(startedAt !== undefined ? { startedAt } : {}),
+                turn,
+            };
+            const result = results.get(toolUseId);
+            if (result)
+                call.result = result;
+            calls.push(call);
+        }
+    }
+    return calls;
+}
+function messageTimestampIso(msg) {
+    const ts = msg.timestamp;
+    if (typeof ts === "number")
+        return new Date(ts).toISOString();
+    if (typeof ts === "string")
+        return ts;
+    return undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/transcript-store.d.ts

@@ -0,0 +1,6 @@
+export interface DumpedSession {
+    sessionKey: string;
+    sessionId: string;
+    messages: unknown[];
+}
+export declare function readConversationSessions(dbPath: string, sinceMs: number, conversationId: string, threadIds: string[]): DumpedSession[];

package/dist/transcript-store.js

@@ -0,0 +1,69 @@
+import { DatabaseSync } from "node:sqlite";
+export function readConversationSessions(dbPath, sinceMs, conversationId, threadIds) {
+    let db;
+    try {
+        db = new DatabaseSync(dbPath, { readOnly: true });
+    }
+    catch {
+        return [];
+    }
+    try {
+        db.exec("PRAGMA busy_timeout = 2000;");
+        const wanted = conversationId.toLowerCase();
+        const nodes = db.prepare("SELECT session_key, current_session_id FROM session_nodes").all();
+        const sessions = [];
+        for (const node of nodes) {
+            const segments = node.session_key.toLowerCase().split(":");
+            if (!segments.includes(wanted) && !threadIds.some((id) => segments.includes(id)))
+                continue;
+            sessions.push({
+                sessionKey: node.session_key,
+                sessionId: node.current_session_id,
+                messages: readNodeMessages(db, node, sinceMs),
+            });
+        }
+        return sessions;
+    }
+    catch {
+        // Fresh store without the tables yet, or a transient lock: the runner's
+        // next poll retries.
+        return [];
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * A session key can span several session windows: compaction, reset, or
+ * recovery mints a successor id that `current_session_id` then advances to,
+ * and `transcript_events` rows stay keyed to the window that wrote them.
+ * Union every window of the key (in creation order) so earlier tool calls and
+ * costs survive a mid-run rollover.
+ */
+function readNodeMessages(db, node, sinceMs) {
+    const windows = db
+        .prepare("SELECT session_id FROM session_windows WHERE session_key = ? ORDER BY created_at")
+        .all(node.session_key);
+    const sessionIds = windows.map((w) => w.session_id);
+    if (!sessionIds.includes(node.current_session_id))
+        sessionIds.push(node.current_session_id);
+    return sessionIds.flatMap((id) => readSessionMessages(db, id, sinceMs));
+}
+function readSessionMessages(db, sessionId, sinceMs) {
+    const rows = db
+        .prepare("SELECT event_json FROM transcript_events WHERE session_id = ? AND created_at >= ? ORDER BY seq")
+        .all(sessionId, sinceMs);
+    const messages = [];
+    for (const row of rows) {
+        let event;
+        try {
+            event = JSON.parse(row.event_json);
+        }
+        catch {
+            continue;
+        }
+        if (event.type === "message" && event.message !== undefined)
+            messages.push(event.message);
+    }
+    return messages;
+}

package/docker-compose.yml

@@ -0,0 +1,83 @@
+x-common-build: &common-build
+  context: ${OPENCLAW_TEST_PROJECT_DIR}
+  dockerfile: Dockerfile
+  args:
+    OPENCLAW_TEST_BASE_TAG: ${OPENCLAW_TEST_BASE_TAG}
+
+# Single source of truth for service mounts. `openclaw-test-ipc` is only used by gateway
+# (writer) and runner (reader), but mounting it on `bus` too is harmless and
+# lets all three services share one anchor.
+x-common-volumes: &common-volumes
+  - ${OPENCLAW_WORKSPACE_DIR}:/home/assistant/.openclaw/workspace
+  - ${OPENCLAW_CONFIG_PATH}:/home/assistant/.openclaw/openclaw.json
+  - ${OPENCLAW_TEST_PACKAGE_DIR}/dist/:/opt/openclaw-test/src/dist
+  - ${OPENCLAW_TEST_SCENARIOS_DIR}:/opt/openclaw-test/src/scenarios
+  - ${OPENCLAW_TEST_ARTIFACTS_DIR}:/opt/openclaw-test/artifacts
+  - ${OPENCLAW_TEST_GATEWAY_LOGS_DIR}:/home/assistant/.openclaw/logs
+  - openclaw-test-ipc:/var/run/openclaw-test-ipc
+
+volumes:
+  openclaw-test-ipc:
+
+# All three services run the same image. The explicit shared `image:` keeps worker
+# Compose projects (`<base>-w<i>`) from each building/looking up their own
+# project-named image; the CLI injects OPENCLAW_TEST_CONSUMER_IMAGE.
+services:
+  bus:
+    build: *common-build
+    image: ${OPENCLAW_TEST_CONSUMER_IMAGE}
+    user: assistant
+    working_dir: /opt/openclaw-test/src
+    command: ["node", "/opt/openclaw-test/src/dist/bus.js"]
+    volumes: *common-volumes
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:43123/v1/state"]
+      interval: 2s
+      timeout: 2s
+      retries: 10
+
+  gateway:
+    build: *common-build
+    image: ${OPENCLAW_TEST_CONSUMER_IMAGE}
+    user: assistant
+    working_dir: /opt/openclaw-test/src
+    environment:
+      OPENCLAW_CONFIG_PATH: /home/assistant/.openclaw/openclaw.json
+      OPENCLAW_CONFIG_READONLY: "1"
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+      OPENROUTER_API_KEY: ${OPENROUTER_API_KEY:-}
+      OPENCLAW_RAW_STREAM: ${OPENCLAW_RAW_STREAM:-}
+      OPENCLAW_TEST_RUNNER_URL: "http://runner:43124"
+      PATH: "/opt/openclaw-test/mocks/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+    # Watcher in the background, then exec openclaw as PID 1's foreground process.
+    command:
+      ["sh", "-c",
+       "/usr/local/bin/exec-watcher & exec npx openclaw gateway run --port 18789 --bind loopback --auth none"]
+    volumes: *common-volumes
+    depends_on:
+      bus:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "node -e \"require('net').connect(18789, '127.0.0.1').on('connect', () => process.exit(0)).on('error', () => process.exit(1))\""]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 30s
+
+  runner:
+    build: *common-build
+    image: ${OPENCLAW_TEST_CONSUMER_IMAGE}
+    user: assistant
+    working_dir: /opt/openclaw-test/src
+    environment:
+      OPENCLAW_TEST_BUS_URL: http://bus:43123
+      OPENCLAW_CONFIG_PATH: /home/assistant/.openclaw/openclaw.json
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+      OPENROUTER_API_KEY: ${OPENROUTER_API_KEY:-}
+    entrypoint: ["node", "/opt/openclaw-test/src/dist/runner.js"]
+    volumes: *common-volumes
+    depends_on:
+      bus:
+        condition: service_healthy
+      gateway:
+        condition: service_healthy

package/exec-watcher.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+
+const IPC_DIR = "/var/run/openclaw-test-ipc";
+const MAX_OUTPUT_BYTES = 1_048_576;
+const POLL_INTERVAL_MS = 100;
+const STALE_SUFFIXES = [
+  ".req.json",
+  ".req.json.processing",
+  ".res.json",
+  ".res.json.tmp",
+  ".transcript.json",
+  ".transcript.json.tmp",
+];
+
+mkdirSync(IPC_DIR, { recursive: true });
+
+// Sweep stale IPC artifacts left by a killed predecessor in the (named-volume,
+// persistent) IPC dir, so the next runner cycle starts clean.
+try {
+  for (const f of readdirSync(IPC_DIR)) {
+    if (STALE_SUFFIXES.some((suffix) => f.endsWith(suffix))) {
+      try {
+        rmSync(`${IPC_DIR}/${f}`, { force: true });
+      } catch (err) {
+        console.error(`exec-watcher: failed to clean stale IPC file ${f}:`, err);
+      }
+    }
+  }
+} catch (err) {
+  console.error(`exec-watcher: failed to scan IPC dir ${IPC_DIR}:`, err);
+}
+
+async function main() {
+  for (;;) {
+    let entries;
+    try {
+      entries = readdirSync(IPC_DIR);
+    } catch {
+      entries = [];
+    }
+    const reqFiles = entries.filter((f) => f.endsWith(".req.json"));
+    for (const f of reqFiles) {
+      const reqPath = `${IPC_DIR}/${f}`;
+      const claimed = `${reqPath}.processing`;
+      try {
+        renameSync(reqPath, claimed);
+      } catch {
+        continue;
+      }
+      processRequest(claimed).catch((err) => {
+        console.error("exec-watcher: internal error", err);
+      });
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+}
+
+async function processRequest(claimedPath) {
+  let id = "unknown";
+  try {
+    const raw = readFileSync(claimedPath, "utf8");
+    const req = JSON.parse(raw);
+    id = req.id;
+    const result = await runChild(req);
+    writeResult(id, result);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    writeResult(id, { exitCode: 255, stdout: "", stderr: `watcher error: ${message}` });
+  } finally {
+    rmSync(claimedPath, { force: true });
+  }
+}
+
+function runChild(req) {
+  const { argv, cwd, env, stdin, timeoutMs = 30_000 } = req;
+  return new Promise((resolve) => {
+    const child = spawn(argv[0], argv.slice(1), {
+      cwd,
+      env: { ...process.env, ...(env ?? {}) },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let stdoutDropped = 0;
+    let stderrDropped = 0;
+    let killedByTimeout = false;
+
+    child.stdout.on("data", (chunk) => {
+      const s = chunk.toString();
+      if (stdout.length + s.length > MAX_OUTPUT_BYTES) {
+        const room = Math.max(0, MAX_OUTPUT_BYTES - stdout.length);
+        stdout += s.slice(0, room);
+        stdoutDropped += s.length - room;
+      } else {
+        stdout += s;
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      const s = chunk.toString();
+      if (stderr.length + s.length > MAX_OUTPUT_BYTES) {
+        const room = Math.max(0, MAX_OUTPUT_BYTES - stderr.length);
+        stderr += s.slice(0, room);
+        stderrDropped += s.length - room;
+      } else {
+        stderr += s;
+      }
+    });
+
+    if (stdin !== undefined) {
+      child.stdin.write(stdin);
+    }
+    child.stdin.end();
+
+    const timer = setTimeout(() => {
+      killedByTimeout = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({
+        exitCode: 255,
+        stdout,
+        stderr: `${stderr}\nspawn error: ${err.message}`,
+      });
+    });
+    child.on("exit", (code, signal) => {
+      clearTimeout(timer);
+      if (stdoutDropped > 0) stdout += `\n…[truncated ${stdoutDropped} bytes]`;
+      if (stderrDropped > 0) stderr += `\n…[truncated ${stderrDropped} bytes]`;
+      if (killedByTimeout) {
+        resolve({
+          exitCode: 124,
+          stdout,
+          stderr: `${stderr}\n…[killed by watcher timeout after ${timeoutMs}ms]`,
+        });
+        return;
+      }
+      const exitCode = code ?? (signal ? 128 : 1);
+      resolve({ exitCode, stdout, stderr });
+    });
+  });
+}
+
+function writeResult(id, result) {
+  const finalPath = `${IPC_DIR}/${id}.res.json`;
+  const tmp = `${finalPath}.tmp`;
+  writeFileSync(tmp, JSON.stringify(result));
+  renameSync(tmp, finalPath);
+}
+
+void main();

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@alignfirst/openclaw-test",
+  "version": "0.20.0",
+  "description": "Dockerised regression-test framework for OpenClaw workspaces: bus, scenario driver, judge, Compose stack.",
+  "keywords": [
+    "openclaw",
+    "test",
+    "testing",
+    "harness",
+    "scenario",
+    "docker"
+  ],
+  "license": "MIT",
+  "author": "Thomas MUR",
+  "homepage": "https://alignfirst.paroi.tech/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paleo/alignfirst.git",
+    "directory": "packages/openclaw-test"
+  },
+  "engines": {
+    "node": ">=24.16.0 <25 || >=26.1.0"
+  },
+  "packageManager": "npm@11.19.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "openclaw-test": "./bin/cli.mjs"
+  },
+  "exports": "./dist/index.js",
+  "files": [
+    "dist/",
+    "bin/",
+    "templates/",
+    "docker-compose.yml",
+    "Dockerfile.base",
+    "exec-watcher.mjs",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "dependencies": {
+    "@alignfirst/openclaw-channel-mock-core": "0.9.0",
+    "@alignfirst/openclaw-discord-mock": "0.5.0",
+    "@alignfirst/openclaw-slack-mock": "0.5.0",
+    "@anthropic-ai/sdk": "~0.122.0",
+    "openai": "~7.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "~26.5.0",
+    "openclaw": "~2026.9.3",
+    "rimraf": "~6.1.3",
+    "typescript": "~7.0.2",
+    "vitest": "~4.1.11"
+  }
+}

package/templates/.env.local.example

@@ -0,0 +1,28 @@
+ANTHROPIC_API_KEY=
+
+# Required only when running a Qwen model (OpenRouter); harmlessly empty otherwise.
+OPENROUTER_API_KEY=
+
+# Agent model catalog. Comma list of full LiteLLM provider/model refs — the only
+# place the provider/ prefix appears. `run --model <id>` and OPENCLAW_DEFAULT_TEST_MODEL
+# use the bare id (the suffix after the last "/"). `--model all` runs every entry and
+# needs the API key for each referenced provider.
+OPENCLAW_TEST_MODELS=anthropic/claude-sonnet-4-6,custom-openrouter/qwen/qwen3.6-plus
+OPENCLAW_DEFAULT_TEST_MODEL=claude-sonnet-4-6
+
+# Required: host path to the OpenClaw workspace (mounted into the gateway).
+OPENCLAW_WORKSPACE_DIR=
+
+# Optional: run N matrix cells concurrently, each on its own worker stack
+# (`run --parallel` wins over this).
+# OPENCLAW_TEST_PARALLEL=4
+
+# Optional overrides (defaults relative to the project dir):
+# OPENCLAW_CONFIG_PATH=./openclaw.json
+# OPENCLAW_TEST_SCENARIOS_DIR=./scenarios
+# OPENCLAW_TEST_ARTIFACTS_DIR=./artifacts
+# OPENCLAW_TEST_GATEWAY_LOGS_DIR=./.gateway-logs
+
+# Opt-in: also write raw-stream.jsonl alongside the always-on provider-neutral
+# trajectory log (one <sessionId>.jsonl per session under .gateway-logs/trajectory/).
+# OPENCLAW_RAW_STREAM=1

package/templates/Dockerfile

@@ -0,0 +1,47 @@
+# Consumer-side test runner image. Extends the consumer-agnostic base built locally
+# by `openclaw-test env build` and tagged `paleo/openclaw-test-base:<pkg-version>`.
+# The CLI passes the matching tag via the OPENCLAW_TEST_BASE_TAG build arg.
+#
+# Build context is the project dir.
+
+ARG OPENCLAW_TEST_BASE_TAG=__SET_VIA_OPENCLAW_TEST_CLI__
+FROM paleo/openclaw-test-base:${OPENCLAW_TEST_BASE_TAG}
+
+COPY --chown=assistant:assistant package.json package-lock.json /opt/openclaw-test/src/
+COPY --chown=assistant:assistant openclaw.json /home/assistant/.openclaw/openclaw.json
+
+RUN npm ci --include=dev && \
+    OPENCLAW_CONFIG_PATH=/home/assistant/.openclaw/openclaw.json npx openclaw plugins registry --refresh
+
+# Consumer customizations below. Add RUN/COPY/ENV as needed. The base image
+# is deliberately minimal — add only what your fixtures and scenarios need.
+# Common patterns:
+#
+# * System tools the fixtures invoke (under USER root):
+#     RUN apk add --no-cache git
+#     RUN npm install --global corepack@0.36.0 && \
+#         corepack enable && corepack prepare pnpm@latest --activate
+#
+# * Per-command mock-CLI symlinks (the base ships only the bare shim;
+#   consumers pick which commands to intercept):
+#     USER root
+#     RUN for name in claude gh; do \
+#           ln -sf mock-cli-shim "/opt/openclaw-test/mocks/bin/$name"; \
+#         done
+#     USER assistant
+#
+# * Helper scripts invoked from scenarios via `ctx.execInGateway(...)`:
+#     USER root
+#     COPY --chown=root:root scripts/ /opt/openclaw-test/scripts/
+#     RUN chmod +x /opt/openclaw-test/scripts/*.mjs
+#     USER assistant
+#
+# * Project fixtures baked into the image (typical with a named-volume
+#   /home/assistant/projects, then reset/seeded per scenario):
+#     COPY --chown=assistant:assistant projects-fixture/<name>/ /opt/<consumer>/fixtures/<name>/
+#     RUN cd /opt/<consumer>/fixtures/<name> && pnpm install --frozen-lockfile
+#
+# * Skills under /home/assistant/.agents/skills/ for the assistant to discover
+#   (e.g. installed with the `skills` CLI from any repo or registry):
+#     RUN npx -y skills add <skills-source> --global --yes \
+#           --agent claude-code --skill <name> [--skill <name> …]

package/templates/docker-compose.yml

@@ -0,0 +1,10 @@
+# Thin consumer overlay. Pulls in the parameterized base from
+# @alignfirst/openclaw-test. Requires Docker Compose v2.20+.
+#
+# `.env.local` only needs ANTHROPIC_API_KEY and OPENCLAW_WORKSPACE_DIR.
+# All other paths default to subdirs of the project dir; override in
+# .env.local if you need a different layout. OPENCLAW_TEST_PROJECT_DIR, OPENCLAW_TEST_PACKAGE_DIR,
+# ASSISTANT_UID, ASSISTANT_GID are set automatically by `openclaw-test env|run`.
+
+include:
+  - ./node_modules/@alignfirst/openclaw-test/docker-compose.yml