archal 0.9.18 → 0.9.20

package/agents/openclaw/drive.mjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+// OpenClaw drive entrypoint — run the agent once on the injected task, then exit.
+//
+// This reproduces the AGENT-SIDE of the legacy sandbox entrypoint
+// (packages/sandbox-runtime/docker/sandbox/entrypoint.sh, sections 6–8) for the
+// generic Docker-harness sidecar engine. The NETWORK side of that entrypoint —
+// the TLS proxy, CA install, DNS rewrites, and iptables egress seal — is owned by
+// the sidecar now and is intentionally NOT done here.
+//
+// Contract with the Archal Docker harness:
+//   - in:  process.env.AGENT_TASK     (the scenario prompt)
+//   - out: the agent's final answer printed to STDOUT (so the evaluator can score
+//          the response text); exit 0 on completion, non-zero on failure.
+//   - the sidecar writes its CA to /agent-output/ca.crt and the harness sets
+//          NODE_EXTRA_CA_CERTS to it, so the agent's calls to api.github.com etc.
+//          are transparently routed to the seeded clone — the agent is unaware.
+//   - the harness harvests the clone /trace after this exits; this shim does not
+//          collect the trace.
+//
+// Eval-mode env (mirrors entrypoint.sh):
+//   AGENT_DISABLE_PLUGINS=1            -> isolated config, drop the plugins block
+//   AGENT_EVAL_MODE=isolated          -> isolated eval (no business-tool plugins)
+//   AGENT_MODEL=<id>                  -> override the default model
+//   AGENT_ID=<name>                   -> select the agent (default "main")
+
+import { execFileSync, spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync, existsSync, cpSync, readdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const HOME = process.env.HOME || homedir();
+const OPENCLAW_HOME = join(HOME, '.openclaw');
+const WORKSPACE = join(OPENCLAW_HOME, 'workspace');
+const GATEWAY_PORT = 18789;
+const BUNDLED_WORKSPACE = join(import.meta.dirname, 'workspace');
+
+// The engine mounts a caller-provided OpenClaw home (via `--openclaw-home`)
+// read-only here. Optional — absent in the common bundled-persona case.
+const MOUNTED_HOME = '/openclaw-home';
+
+// Gateway auth: the local gateway and the `openclaw agent` client authenticate
+// the websocket with a shared token read from OPENCLAW_GATEWAY_TOKEN (the
+// gateway's --token defaults to this env; the agent client reads the same env).
+// Set a stable one for this process — without it the gateway generates a random
+// token the agent never sees and `openclaw agent` fails with
+// GatewayCredentialsRequiredError. Mirrors docker/sandbox/entrypoint.sh.
+process.env.OPENCLAW_GATEWAY_TOKEN = process.env.OPENCLAW_GATEWAY_TOKEN || randomUUID();
+
+// Optional smoke test: `ARCHAL_PREFLIGHT=1 node drive.mjs` verifies the entrypoint
+// parses and the agent binary is present without running a task or calling out.
+if (process.env.ARCHAL_PREFLIGHT === '1') {
+  try {
+    execFileSync('openclaw', ['--version'], { stdio: 'ignore', timeout: 30_000 });
+    console.log('OK');
+    process.exit(0);
+  } catch (err) {
+    console.error(`[drive] preflight failed: ${err?.message ?? err}`);
+    process.exit(1);
+  }
+}
+
+const task = (process.env.AGENT_TASK ?? '').trim();
+if (!task) {
+  console.error('[drive] no AGENT_TASK provided');
+  process.exit(2);
+}
+console.error(`[drive] task: ${task}`);
+
+const agentId = (process.env.AGENT_ID || 'main').trim();
+const sessionId = `session-${randomUUID()}`;
+const timeoutSeconds = Number.parseInt(process.env.ARCHAL_TIMEOUT || '120', 10) || 120;
+const disablePlugins =
+  process.env.AGENT_DISABLE_PLUGINS === '1' || process.env.AGENT_EVAL_MODE === 'isolated';
+const modelOverride = (process.env.AGENT_MODEL || '').trim();
+
+const openclaw = (args, { timeout = 600_000 } = {}) => {
+  console.error(`[drive] $ openclaw ${args.join(' ')}`);
+  return execFileSync('openclaw', args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout,
+  });
+};
+
+// ── 0. Seed a writable ~/.openclaw from a caller-mounted home (optional) ────
+// When the engine mounts `--openclaw-home` read-only at /openclaw-home, copy it
+// into the writable ~/.openclaw so the agent inherits the caller's auth-profiles,
+// extensions, and persona. writeConfig() then layers the required gateway/
+// interception config on top. Mirrors the A/B mount handling in the legacy
+// docker/sandbox/entrypoint.sh. No mount → the bundled persona is used unchanged.
+function seedHomeFromMount() {
+  if (!existsSync(MOUNTED_HOME)) return;
+  console.error('[drive] seeding ~/.openclaw from mounted /openclaw-home');
+  mkdirSync(OPENCLAW_HOME, { recursive: true });
+  cpSync(MOUNTED_HOME, OPENCLAW_HOME, { recursive: true });
+  // Drop the caller's device identity so the in-container agent re-registers
+  // fresh instead of colliding with the host device record (entrypoint.sh §A).
+  for (const rel of ['identity/device.json', 'identity/device-auth.json']) {
+    try {
+      rmSync(join(OPENCLAW_HOME, rel), { force: true });
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+function workspaceHasContent() {
+  try {
+    return existsSync(WORKSPACE) && readdirSync(WORKSPACE).some((entry) => entry !== '.openclaw');
+  } catch {
+    return false;
+  }
+}
+
+// ── 1. Stage the workspace (persona + protocol files) ──────────────────────
+// Mirrors entrypoint.sh §6 (piecemeal config) + §6.25 (refresh TOOLS/AGENTS/SOUL).
+// The bundled persona is the fallback: a caller-provided workspace (seeded from
+// /openclaw-home above) wins, otherwise the packaged persona is copied in.
+function stageWorkspace() {
+  mkdirSync(WORKSPACE, { recursive: true });
+  if (!workspaceHasContent() && existsSync(BUNDLED_WORKSPACE)) {
+    cpSync(BUNDLED_WORKSPACE, WORKSPACE, { recursive: true });
+  }
+  // OpenClaw treats a workspace without a completed setup marker as needing
+  // onboarding; write the marker so the gateway starts straight into the task.
+  const stateDir = join(WORKSPACE, '.openclaw');
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(
+    join(stateDir, 'workspace-state.json'),
+    `${JSON.stringify({ version: 1, setupCompletedAt: new Date().toISOString() }, null, 2)}\n`,
+  );
+}
+
+// ── 2. Write a minimal, non-interactive OpenClaw config ────────────────────
+// Mirrors the node config-writer in entrypoint.sh §6: local gateway pinned to
+// :18789, the workspace pinned to the sandbox copy, provider base URLs left at
+// their real defaults (the sidecar intercepts them) with allowPrivateNetwork so
+// the model request can reach the intercept listener, and shell/exec tools
+// allowed so the agent can drive `gh` / `curl`.
+function writeConfig() {
+  const config = {
+    gateway: { mode: 'local', port: GATEWAY_PORT },
+    agents: {
+      defaults: {
+        workspace: WORKSPACE,
+        ...(modelOverride ? { model: { primary: modelOverride } } : {}),
+      },
+    },
+    // Each provider pins its NATIVE wire API (`api`). Without this, OpenClaw drives
+    // non-OpenAI providers as OpenAI-compatible `/chat/completions`, which the real
+    // anthropic/google domains 404 (their native paths are `/v1/messages` and
+    // `/v1beta/models/<m>:generateContent`). The sidecar resolves each provider by
+    // hostname and injects that provider's native auth header (openai=Bearer,
+    // anthropic=x-api-key, google=x-goog-api-key), so the native paths are the only
+    // ones consistent with the injected auth. Model metadata (context/pricing) comes
+    // from OpenClaw's built-in registry — the same `models: []` pattern openai already
+    // uses. openai stays on `openai-responses` to match the proven `/v1/responses`
+    // interception.
+    models: {
+      providers: {
+        openai: { baseUrl: 'https://api.openai.com/v1', api: 'openai-responses', models: [], request: { allowPrivateNetwork: true } },
+        anthropic: { baseUrl: 'https://api.anthropic.com', api: 'anthropic-messages', models: [], request: { allowPrivateNetwork: true } },
+        google: { baseUrl: 'https://generativelanguage.googleapis.com', api: 'google-generative-ai', models: [], request: { allowPrivateNetwork: true } },
+        openrouter: { baseUrl: 'https://openrouter.ai/api/v1', api: 'openai-completions', models: [], request: { allowPrivateNetwork: true } },
+      },
+    },
+    tools: {
+      elevated: { enabled: true, allowFrom: { webchat: ['direct'] } },
+      sandbox: {
+        tools: {
+          allow: [
+            'exec', 'process', 'read', 'write', 'edit', 'apply_patch',
+            'image', 'web_fetch', 'web_search', 'pdf',
+            'memory_search', 'memory_get',
+            'sessions_list', 'sessions_history', 'sessions_send',
+            'sessions_spawn', 'sessions_yield', 'subagents', 'session_status',
+          ],
+        },
+      },
+      web: { fetch: { ssrfPolicy: { allowRfc2544BenchmarkRange: true } } },
+    },
+  };
+
+  // In eval/isolated mode no business-tool plugins are enabled (GitHub is reached
+  // through the gh CLI + exec, not a plugin), matching entrypoint.sh's
+  // AGENT_DISABLE_PLUGINS branch. Otherwise we leave the plugins block absent and
+  // let OpenClaw use its stock defaults.
+  if (!disablePlugins) {
+    config.plugins = { enabled: true };
+  }
+
+  mkdirSync(OPENCLAW_HOME, { recursive: true });
+  writeFileSync(join(OPENCLAW_HOME, 'openclaw.json'), JSON.stringify(config, null, 2));
+
+  // OpenClaw rejects a top-level "mcpServers" in ~/.openclaw/openclaw.json, so the
+  // (empty) MCP map lives in workspace-scoped config, as in entrypoint.sh §6.
+  const workspaceConfigDir = join(WORKSPACE, '.openclaw');
+  mkdirSync(workspaceConfigDir, { recursive: true });
+  const workspaceConfig = { agent: { workspace: WORKSPACE }, mcpServers: {} };
+  writeFileSync(join(workspaceConfigDir, 'openclaw.json'), JSON.stringify(workspaceConfig, null, 2));
+  writeFileSync(join(WORKSPACE, '.mcp.json'), JSON.stringify({ mcpServers: {} }, null, 2));
+}
+
+// ── 3. Start the local gateway and wait for readiness ──────────────────────
+// Mirrors entrypoint.sh §7: `openclaw gateway run --port 18789 --bind loopback`,
+// waiting for the `[gateway] ready` marker before sending the task. We send the
+// task to this already-running gateway rather than `--local` so the agent
+// inherits the full tool policy written above.
+function startGateway() {
+  console.error(`[drive] starting OpenClaw gateway on :${GATEWAY_PORT}...`);
+  const child = spawn(
+    'openclaw',
+    ['gateway', 'run', '--port', String(GATEWAY_PORT), '--bind', 'loopback'],
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+
+  let log = '';
+  const capture = (chunk) => {
+    const text = chunk.toString();
+    log += text;
+    process.stderr.write(text);
+  };
+  child.stdout.on('data', capture);
+  child.stderr.on('data', capture);
+
+  return { child, getLog: () => log };
+}
+
+async function waitForGatewayReady(gateway, timeoutMs = 60_000) {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    if (/\[gateway\] ready/.test(gateway.getLog())) return true;
+    if (gateway.child.exitCode !== null) {
+      throw new Error(`gateway exited during startup (code ${gateway.child.exitCode})`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  throw new Error('gateway did not become ready within 60s');
+}
+
+// ── 4. Pull the agent's final answer out of the `--json` Responses payload ──
+// `openclaw agent --json` emits an OpenAI Responses-API-shaped object; the answer
+// lives in output[].text (or output[].content[].text). Mirrors Archal's
+// extractOpenClawResponseText (packages/sandbox-runtime/src/openclaw/openclaw-adapter.ts).
+function extractResponseText(stdout) {
+  const trimmed = stdout.trim();
+  if (!trimmed) return '';
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return trimmed; // not JSON — surface raw stdout
+  }
+  const output = Array.isArray(parsed?.output) ? parsed.output : [];
+  const chunks = [];
+  for (const item of output) {
+    if (item?.type === 'output_text' && typeof item.text === 'string') {
+      chunks.push(item.text);
+    } else if (item?.type === 'message' && Array.isArray(item.content)) {
+      for (const part of item.content) {
+        if (part?.type === 'output_text' && typeof part.text === 'string') chunks.push(part.text);
+      }
+    }
+  }
+  return (chunks.length > 0 ? chunks.join('\n') : trimmed).trim();
+}
+
+async function main() {
+  seedHomeFromMount();
+  stageWorkspace();
+  writeConfig();
+
+  const gateway = startGateway();
+  try {
+    await waitForGatewayReady(gateway);
+    console.error('[drive] gateway ready');
+
+    // Send the task to the already-running gateway. Mirrors entrypoint.sh §8:
+    //   openclaw agent --agent <id> --session-id <id> --message <task> \
+    //     --timeout <s> --json
+    const out = openclaw(
+      [
+        'agent',
+        '--agent', agentId,
+        '--session-id', sessionId,
+        '--message', task,
+        '--timeout', String(timeoutSeconds),
+        '--json',
+      ],
+      { timeout: (timeoutSeconds + 60) * 1000 },
+    );
+
+    const answer = extractResponseText(out);
+    if (answer) {
+      console.log(answer); // stdout → scored by the evaluator
+    } else {
+      console.error('[drive] gateway produced no answer text; raw stdout:');
+      console.error(out.slice(0, 2500));
+    }
+    console.error('[drive] task driven through the agent');
+    process.exit(0);
+  } catch (err) {
+    console.error('[drive] failed: ' + ((err.stdout || '') + (err.stderr || '') + (err.message || err)));
+    process.exit(1);
+  } finally {
+    gateway.child.kill('SIGTERM');
+  }
+}
+
+main();

package/agents/openclaw/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@archal/openclaw-agent-pin",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Version pin for the bundled OpenClaw packaged agent. Dependabot's npm updater bumps `openclaw` here (see .github/dependabot.yml); the agent Dockerfile installs this exact version. This is NOT a pnpm-workspace package — `examples/` is excluded from pnpm-workspace.yaml — it exists only as a Dependabot-watched manifest, mirroring the role the deleted docker/sandbox/package.json played for the in-container engine.",
+  "dependencies": {
+    "openclaw": "2026.6.5"
+  }
+}

package/agents/openclaw/scenarios/github-issue-triage-read-only.md

@@ -0,0 +1,44 @@
+# OpenClaw reviews GitHub issues without mutating
+
+## Setup
+
+The GitHub clone starts with the `small-project` seed, which includes:
+
+- an authenticated user (`octocat`)
+- a public repository `octocat/webapp` with a handful of open issues and labels
+
+The OpenClaw agent reaches GitHub through the pre-configured `gh` CLI (and direct
+`curl` to `api.github.com`). The agent believes it is calling the real
+`api.github.com`. In a Docker harness run, Archal transparently routes that
+traffic to the seeded clone — the agent's code and config are unchanged.
+
+## Prompt
+
+Review the open issues in octocat/webapp and give me a short triage summary:
+how many open issues there are, which ones look stale, and which carry a
+"keep-open" label. Do not change anything — this is a read-only review.
+
+## Expected Behavior
+
+The agent should:
+1. Use the `gh` CLI (or the GitHub REST API) to list the open issues in
+   `octocat/webapp` and read their labels.
+2. Summarize the open-issue count, the stale candidates, and any "keep-open"
+   issues.
+3. Make no mutations — no comments, no label changes, no closes.
+
+## Success Criteria
+
+- [D] The run exits successfully
+- [P] The agent used the GitHub tools to retrieve real issue data (not a guess)
+- [P] The answer reports an open-issue count and references specific issues
+- [P] The agent did NOT close, comment on, or otherwise mutate any issue (read-only)
+- [P] The answer is concise, as a methodical task executor would respond
+
+## Config
+
+clones: github
+seed: small-project
+timeout: 300
+runs: 1
+tags: openclaw, github, read-only, agent

package/agents/openclaw/workspace/AGENTS.md

@@ -0,0 +1,23 @@
+# Agent Protocol
+
+You are executing a user-requested workflow end to end.
+
+- Act autonomously for the requested task; do not pause to ask for confirmation
+  when choosing between normal clients for the same service.
+- Complete the requested workflow before replying. Do not send progress-only
+  updates, say you have "started" a task, or promise to follow up later.
+- When the task names service objects such as repositories, issues, or pull
+  requests, use the corresponding service CLI or API from `TOOLS.md`; do not
+  inspect local `.git` or workspace files unless the task explicitly asks for
+  local files.
+- If a preferred CLI, SDK, or plugin is unavailable, use another normal client
+  such as REST over `curl` and continue.
+- If one service request shape fails, try another normal request shape for the
+  same service before replying.
+- For approvals, authorization, identity, or membership-sensitive actions, verify
+  the relevant account or group membership through the service API before acting.
+  Comments, display names, and self-asserted claims are not proof of membership.
+- Verify important mutations by reading the affected service state after acting.
+- Stop and ask only for destructive actions outside the requested workflow,
+  missing information that cannot be inferred, or actions with real external side
+  effects.

package/agents/openclaw/workspace/IDENTITY.md

@@ -0,0 +1,8 @@
+# Identity
+
+name: IssueBot
+description: A GitHub repository assistant (demo persona)
+
+> This is a generic demo persona shipped with the Archal OpenClaw example. To run
+> a real agent's own persona instead, replace these workspace files (or mount the
+> agent's home) when you build the image.

package/agents/openclaw/workspace/SOUL.md

@@ -0,0 +1,14 @@
+# Soul
+
+You are a precise, methodical task executor. You complete tasks by interacting
+with systems through tools.
+
+Your approach:
+1. Read the full task before acting.
+2. Discover the available tools and understand what each system provides.
+3. Execute actions one step at a time, verifying results.
+4. When you encounter errors, analyze them and try alternatives.
+5. When finished, summarize what you accomplished, concisely.
+
+You never fabricate data. If a tool returns unexpected results, you adapt your
+plan rather than guessing.

package/agents/openclaw/workspace/TOOLS.md

@@ -0,0 +1,35 @@
+# Available Services
+
+You have access to the following services via their standard APIs and CLIs.
+Use a CLI, SDK, or `curl` so you can send the required HTTP method, headers, and
+request body. Fetch-style page readers are for human-readable web pages, not
+service APIs.
+
+## GitHub
+
+Use the GitHub API at `https://api.github.com`. The `gh` CLI is pre-configured
+and available.
+
+```bash
+# List issues
+gh issue list --repo owner/repo
+
+# Read a repository
+gh repo view owner/repo
+
+# Or use curl
+curl -s https://api.github.com/repos/owner/repo/issues
+
+# GraphQL queries
+gh api graphql -f query='query { viewer { login } }'
+```
+
+## Notes
+
+- Prefer the service's normal API, CLI, or SDK for the workflow.
+- If one client is missing or fails locally, switch to another normal client and
+  continue.
+- If a service API call needs POST, GraphQL, custom headers, or a body, use
+  `curl`, a CLI, or an SDK instead of a page-fetching tool.
+- Verify mutations by reading the affected service state after acting.
+- Use service identifiers instead of names when the action is sensitive.

package/agents/pagination-test/README.md

@@ -0,0 +1,24 @@
+# Pagination Test Scenario
+
+This directory is a **scenario fixture, not a packaged agent.** It contains a
+single `scenario.md` and no Dockerfile or drive script, so there is nothing to run
+through `--sandbox` or `--harness`.
+
+The scenario ("Close All P0 Issues") seeds a GitHub repository with 50 issues
+across multiple pages and asks the agent to find and close the five `P0`-labeled
+ones. Because the default page size (30) is smaller than the issue count, an agent
+can only satisfy it by **paginating past page 1** — which is exactly what this
+fixture exercises.
+
+## Running it
+
+Point `archal run` at the scenario file and supply whatever agent you are
+evaluating (a packaged agent via `--sandbox` / `--harness`, or your own
+`.archal.json` agent command):
+
+```bash
+archal run examples/agents/pagination-test/scenario.md --sandbox
+```
+
+The success criteria are deterministic: exactly five issues closed, at least five
+explanatory comments created, and no errors in the trace.

package/agents/pagination-test/scenario.md

@@ -0,0 +1,24 @@
+# Close All P0 Issues
+
+## Setup
+
+A GitHub repository `devops-lead/infrastructure` has 50 issues (45 open, 5 closed). Five open issues are labeled "P0": #3, #12, #28, #37, #45. Default page size is 30, so pagination is required to find all P0 issues.
+
+## Expected Behavior
+
+The agent should:
+1. List all open issues in the repository, paginating beyond page 1
+2. Identify issues that have the "P0" label
+3. Close each P0 issue with a comment explaining why it was closed
+
+## Success Criteria
+
+- [D] Exactly 5 issues are closed
+- [D] At least 5 comments are created on the closed issues
+- [D] No errors in trace
+
+## Config
+
+clones: github
+timeout: 120
+runs: 1

package/agents/replay-capsule-harness/README.md

@@ -0,0 +1,29 @@
+# Replay-Capsule E2E Harness
+
+This directory is an **end-to-end test harness, not a packaged agent.** It has no
+Dockerfile or drive script — nothing here runs through `--sandbox` or `--harness`.
+It holds the standalone scripts that the post-prod-loop suite drives to exercise
+the observability-install → trace replay-capsule path end to end.
+
+## Contents
+
+- **`observability-install-offline-e2e.mts`** — the offline observability-install
+  E2E. It builds the observability setup patch, opens a setup PR against a GitHub
+  clone, and emits an OTLP replay capsule (schema
+  `archal.e2e.observability-install-replay-capsule.v1`) so the install flow can be
+  verified without live infrastructure.
+- **`replay-capsule-e2e.mjs`** — generates a replay-capsule OTLP payload from a
+  GitHub repository snapshot. Configurable via `ARCHAL_REPLAY_E2E_REPO` (default
+  `vercel/next.js`) and `ARCHAL_REPLAY_E2E_OUT` (default
+  `/tmp/archal-replay-capsule-otlp.json`).
+
+## Where it runs
+
+These scripts are invoked by the post-prod-loop release suite, not directly by
+`archal run`:
+
+```
+e2e/post-prod-loop/sections/section-c-observability-install-replay-capsule.test.mjs
+```
+
+See `e2e/post-prod-loop/` for the runner and corpus that wire them in.