archal 0.9.19 → 0.10.0

package/README.md

@@ -9,9 +9,9 @@ Ramp, Apify, Tavily, Supabase, and Google Workspace.
 - `npm install -g archal` may print peer-dependency warnings from the
   vendored CLI runtime. These are safe to ignore; all required modules
   are bundled.
-- The `vitest` integration under `archal/vitest` requires `vitest@^2.1.0`.
-  Projects on vitest 3 should pin a workspace to vitest 2 for Archal tests
-  to avoid duplicate module resolution.
+- The `vitest` integration under `archal/vitest` supports `vitest@>=2.1.0 <3`.
+  Projects on Vitest 3 should pin a workspace to Vitest 2 for Archal tests
+  until the integration supports Vitest 3's reporter/runtime APIs.
 
 File issues at <https://github.com/Archal-Labs/archal/issues>.
 
@@ -37,6 +37,41 @@ cannot manage audit events or workspace API keys. Use an owner/admin user
 credential, either `archal login` or a dashboard-issued user API key, for
 workspace administration.
 
+## SDK
+
+The `archal` root import exposes the code-first SDK primitives: provision
+clones, run your agent, collect an outcome, and judge it — all in one
+package, no separate installs.
+
+```js
+import { clones, criterion, judge, reportAgentMetrics, version } from 'archal';
+
+const session = await clones(['github'], { seed: { github: 'small-project' } });
+try {
+  // call your agent, pointing it at session.url('github')
+  const outcome = await session.outcome();
+  const judgment = await judge(outcome, [
+    criterion('The agent created an issue with the right title'),
+  ]);
+  console.log(judgment.score, judgment.passed);
+} finally {
+  await session.stop();
+}
+```
+
+Available exports from `archal`:
+
+| Export | Type | Description |
+|---|---|---|
+| `clones(services, opts?)` | function | Provision a hosted clone session |
+| `criterion(text, opts?)` | function | Create an LLM-judged criterion |
+| `judge(outcome, criteria, opts?)` | function | Grade an outcome against criteria |
+| `reportAgentMetrics(metrics)` | function | Write token usage from a harness before exit |
+| `version` | string | Package version |
+
+The Vitest integration lives at `archal/vitest`. See
+<https://docs.archal.ai/guides/vitest>.
+
 ## CLI
 
 The CLI is the primary interface. `archal run` executes a
@@ -55,8 +90,8 @@ archal init
 
 # 3. Edit .archal/harness.mjs to call your agent
 
-# 4. Run the starter scenario from .archal.json
-archal run
+# 4. Run the starter scenario from .archal.json with controlled routing
+archal run --docker
 ```
 
 `archal init` creates `.archal.json`, `.archal/harness.mjs`, and
@@ -71,7 +106,10 @@ config looks like this:
 {
   "agent": {
     "command": "node",
-    "args": [".archal/harness.mjs"]
+    "args": [".archal/harness.mjs"],
+    "env": {
+      "OPENAI_API_KEY": "${OPENAI_API_KEY}"
+    }
   },
   "scenarios": ["scenarios/first-run.md"],
   "clones": ["github", "stripe"],
@@ -79,23 +117,12 @@ config looks like this:
 }
 ```
 
-### Supported clones
+The harness only receives variables declared in `agent.env`; use `${VAR}`
+interpolation for shell secrets.
 
-`archal clone` lists the eleven clones available today:
+### Supported clones
 
-| Clone | Notes |
-|---|---|
-| Discord | Guilds, channels, messages, members |
-| GitHub | Repos, issues, PRs, labels, reviews |
-| Slack | Channels, messages, users, reactions |
-| Stripe | Customers, subscriptions, invoices, products |
-| Linear | Teams, issues, projects, cycles |
-| Jira | Projects, issues, workflows, components |
-| Ramp | Cards, transactions, reimbursements, users |
-| Apify | Actors, tasks, runs, datasets |
-| Tavily | Search and extraction responses |
-| Supabase | Auth, Postgres, storage, edge functions |
-| Google Workspace | Gmail, Drive, Calendar, Docs, People |
+Run `archal clone` for the current hosted catalog, and `archal clone list` for active clone sessions.
 
 ### Command reference
 
@@ -108,151 +135,32 @@ config looks like this:
 | `archal clone status` | Inspect the active session |
 | `archal clone stop` | Stop the active session |
 | `archal clone list` | List all your active sessions |
-| `archal clone attach <uuid>` | Reattach to a session by id |
 | `archal clone renew <seconds>` | Extend the session lifetime |
 | `archal clone reset` | Reset clone state without tearing down the session |
 | `archal clone seed <clone> <name>` | Load a named seed into a running clone |
 | `archal run [scenario]` | Run a scenario file (or use `--config` for `.archal.json`) |
+| `archal workspace api-keys` | List workspace API keys with an owner/admin user session |
+| `archal workspace api-key create <label>` | Create a workspace API key for CI/runtime auth |
+| `archal workspace api-key revoke <key-id>` | Revoke a workspace API key |
+| `archal autoloop [trace-dir] --repo <dir>` | Register a read-only trace source or start a local trace loop |
+| `archal autoloop status [run-id]` | Show local trace job status or hosted run evidence |
+| `archal autoloop detach <trace-dir>` | Stop a local file-backed autoloop loop |
 | `archal scenario list` | Browse local and hosted scenarios |
 | `archal seed list [clone]` | List prebuilt clone seeds |
-| `archal trace` | View recent scenario traces |
-| `archal trace <name>` | View trace details for a run |
+| `archal traces list` | View recent scenario traces |
+| `archal traces detail <name|id>` | View trace details for a run |
 | `archal usage` | Check active workspace session-minutes and plan |
 
 Run `archal <command> --help` for flag details.
 
-## Vitest integration (secondary use case)
-
-You can also import `archal/vitest` to route SDK traffic from a vitest
-suite through a hosted clone, with no code changes to your production
-code. This is useful if you want to test the HTTP side of an integration
-without hitting real provider APIs.
-
-> The vitest helper supports the hosted route-mode clone catalog: Apify,
-> Discord, GitHub, Google Workspace, Jira, Linear, Ramp, Slack, Stripe,
-> Supabase, and Tavily.
-> If you only need scenario-level evaluation, the CLI flow above is
-> simpler to set up.
-
-### Minimal config
-
-```ts
-import { defineConfig } from 'vitest/config';
-import { withArchal } from 'archal/vitest';
-
-export default defineConfig({
-  test: withArchal(
-    {
-      // everything you already had in test:, unchanged
-      globals: true,
-      coverage: { provider: 'v8' },
-    },
-    {
-      services: {
-        stripe: { mode: 'route', seed: 'small-business' },
-      },
-    },
-  ),
-});
-```
-
-`withArchal(existingTest, { services })` wraps an existing `vitest.config.ts`'s `test:` block, preserving every field you already had. Pass `{}` as the first argument if you're starting from scratch.
+For terminal-first autonomous loops, see
+<https://docs.archal.ai/guides/autoloop-production-traces>.
 
-Your existing tests work unchanged:
+## Vitest integration
 
-```ts
-import { it, expect } from 'vitest';
-import Stripe from 'stripe';
-
-it('creates a customer', async () => {
-  const stripe = new Stripe('sk_test_fake');        // fake key is fine
-  const customer = await stripe.customers.create({  // goes to clone, not real Stripe
-    email: 'test@example.com',
-  });
-  expect(customer.id).toMatch(/^cus_/);
-});
-```
-
-### Per-test state isolation
-
-```ts
-import { beforeEach } from 'vitest';
-import { resetArchalClones } from 'archal/vitest';
-
-beforeEach(async () => {
-  await resetArchalClones();
-});
-```
-
-### Webhook testing
-
-The hosted clone runs in AWS ECS, so it can't POST to your localhost.
-Instead, your test pulls queued deliveries with `waitForArchalWebhook()`
-and invokes your handler directly with the exact payload the clone would
-have sent.
-
-```ts
-import { it, expect } from 'vitest';
-import Stripe from 'stripe';
-import { waitForArchalWebhook } from 'archal/vitest';
-import { handleStripeWebhook } from './src/webhooks';
-
-const stripe = new Stripe('sk_test_fake');
-
-it('records a subscription when customer.subscription.created fires', async () => {
-  // 1. Register a webhook endpoint (the clone needs to know what events to queue)
-  await stripe.webhookEndpoints.create({
-    url: 'http://test.local/stripe-wh',
-    enabled_events: ['customer.subscription.created'],
-  });
-
-  // 2. Trigger the event
-  const customer = await stripe.customers.create({ email: 'wh@x.com' });
-  const sub = await stripe.subscriptions.create({
-    customer: customer.id,
-    items: [{ price: 'price_existing_in_seed' }],
-  });
-
-  // 3. Pull the queued delivery
-  const event = await waitForArchalWebhook('stripe', 'customer.subscription.created');
-  expect(event.payload.data.object.id).toBe(sub.id);
-
-  // 4. Invoke your handler with the exact payload
-  await handleStripeWebhook(event.body, event.headers['Stripe-Signature'], process.env.STRIPE_WEBHOOK_SECRET);
-});
-```
-
-**Webhook coverage**:
-
-| Service | Support | Notes |
-|---|---|---|
-| Stripe | ✅ | |
-| GitHub | ✅ | |
-| Slack | ✅ | Receiver-side signature only |
-| Jira | ✅ | Delivered via history buffer (also POSTed to registered URLs) |
-| Linear | ✅ | Delivered via history buffer (also POSTed to registered URLs) |
-| Supabase | ❌ | Database-triggered; test against real Postgres |
-| Google Workspace | ❌ | GCP Pub/Sub push notifications, not webhooks |
-
-**Parallel workers caveat**: `waitForArchalWebhook()` consumes deliveries
-from a shared queue by default. When vitest runs test files in parallel
-across workers, worker A can swallow worker B's event. If your tests
-depend on webhook events, set `testIsolation: 'serial'` in your config.
-
-### Test isolation across parallel workers
-
-Each vitest worker is routed to its own per-worker state on the clone,
-so parallel tests across workers don't see each other's writes. The
-integration reads `VITEST_WORKER_ID` in each worker process and tags
-every outbound SDK request with an `X-Archal-Worker-Id` header. The clone
-maintains a separate state engine per worker id, seeded from the
-baseline on first request.
-
-**Isolation-enabled clones**: Stripe, GitHub, Slack, Jira, Linear.
-
-**Clones without isolation** (Supabase, Google Workspace, Ramp) fall back
-to shared state. If your tests depend on global assertions against those
-clones, set `testIsolation: 'serial'`.
+The package also exposes `archal/vitest` for routing SDK traffic from a Vitest
+suite through hosted clones. The stable guide lives at
+<https://docs.archal.ai/guides/vitest>.
 
 ## Authentication
 

package/agents/openclaw/.archal.json

@@ -0,0 +1,8 @@
+{
+  "description": "The real OpenClaw gateway agent (successor to the legacy --sandbox path).",
+  "agent": {
+    "command": "node",
+    "args": ["drive.mjs"]
+  },
+  "clones": ["github"]
+}

package/agents/openclaw/Dockerfile

@@ -0,0 +1,97 @@
+# OpenClaw agent harness — runs the real OpenClaw agent against Archal clones.
+#
+# This is the packaged-agent successor to the legacy `--sandbox` path. Instead of
+# a fixed `archal/sandbox` image with a baked-in proxy + entrypoint, OpenClaw runs
+# here as an ordinary packaged agent through the generic Docker-harness sidecar
+# engine (the sidecar owns network interception).
+#
+# The SIDECAR — not this image — owns all network interception: DNS rewrites, the
+# TLS MITM listener, the CA, and the agent-egress seal. This image therefore runs
+# NO in-container proxy, NO `/etc/hosts` rewrite, and NO iptables. The agent keeps
+# calling the real service domains (e.g. api.github.com); the sidecar transparently
+# routes that traffic to the seeded clone, and `api.openai.com` /
+# `api.anthropic.com` are forwarded to the real model with the host key injected by
+# the proxy. The sidecar writes its CA to /agent-output/ca.crt and the harness sets
+# NODE_EXTRA_CA_CERTS to it, so child processes trust the intercept automatically.
+FROM node:22-bookworm-slim
+
+# Pin the agent version. Override at build time:
+#   --build-arg OPENCLAW_VERSION=2026.6.6
+# When no build-arg is passed, the pinned version is read from the colocated
+# package.json `dependencies.openclaw`, which Dependabot's npm updater keeps
+# current (see .github/dependabot.yml). Do NOT use a floating tag — the agent is
+# the highest-blast-radius surface and `latest` is a supply-chain attack surface.
+ARG OPENCLAW_VERSION=
+
+ENV OPENCLAW_DISABLE_BONJOUR=1
+
+# System tools OpenClaw's shell/exec tools expect:
+#   ca-certificates - lets `update-ca-certificates` consume the sidecar CA
+#   curl            - gateway health checks + agent HTTP calls
+#   git             - required by gh and common agent workflows
+#   jq              - JSON shaping in agent shell steps
+#   ripgrep         - fast source/search tool used by coding agents
+# gh (GitHub CLI) is installed from the official apt repo below.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      ca-certificates \
+      curl \
+      git \
+      jq \
+      ripgrep \
+ && rm -rf /var/lib/apt/lists/*
+
+# GitHub CLI from the official apt repo. OpenClaw reaches GitHub clones by
+# shelling out to `gh` (and direct curl to api.github.com) — there is no GitHub
+# MCP server in this harness.
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+      | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+      > /etc/apt/sources.list.d/github-cli.list \
+ && apt-get update \
+ && apt-get install -y gh \
+ && rm -rf /var/lib/apt/lists/*
+
+# Install the agent and run its bundled-plugin postinstall so the stock
+# extensions (browser, etc.) materialize under dist/extensions. Fail the build
+# loudly if the extension root is missing.
+#
+# Copy the version manifest to a temp path so it is available to the install RUN
+# below; the RUN deletes it so it never lands in the shipped image.
+COPY package.json /tmp/openclaw-pin/package.json
+# Version source of truth: an explicit `--build-arg OPENCLAW_VERSION` wins; otherwise
+# the version pinned in package.json (Dependabot-managed) is used. Docker expands the
+# `${OPENCLAW_VERSION:-…}` default, and the `$(node -p …)` runs in the shell. This is a
+# SINGLE reference on purpose: Docker textually substitutes every `${OPENCLAW_VERSION}`
+# in a RUN with the build-arg value before the shell runs, so a second reference (or a
+# reused shell var of the same name) would be clobbered. A missing/malformed pin yields
+# `openclaw@undefined` / `openclaw@`, which npm rejects loudly — never a floating install.
+RUN npm install -g "openclaw@${OPENCLAW_VERSION:-$(node -p "require('/tmp/openclaw-pin/package.json').dependencies.openclaw")}" \
+ && node /usr/local/lib/node_modules/openclaw/scripts/postinstall-bundled-plugins.mjs \
+ && test -d /usr/local/lib/node_modules/openclaw/dist/extensions \
+ && rm -rf /tmp/openclaw-pin
+
+# Pre-configure the gh CLI with a format-valid dummy token. The sidecar replaces
+# the Authorization header on every forwarded request with supervisor-owned
+# credentials, so this token only needs to pass gh's local format check — a
+# `gho_` prefix makes gh treat it as a valid OAuth token. DO NOT set GH_TOKEN:
+# it takes precedence over hosts.yml and gh validates it with a direct API call
+# that bypasses the proxy's header replacement.
+RUN mkdir -p /root/.config/gh \
+ && printf '%s\n' \
+      'github.com:' \
+      '  oauth_token: gho_AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTt' \
+      '  user: workflow-bot' \
+      '  git_protocol: https' \
+      > /root/.config/gh/hosts.yml
+
+WORKDIR /app
+
+# The drive entrypoint + the agent's persona/workspace assets. The drive script
+# copies the workspace into ~/.openclaw/workspace at boot.
+COPY drive.mjs   /app/drive.mjs
+COPY extract-openclaw-response-text.mjs /app/extract-openclaw-response-text.mjs
+COPY workspace/  /app/workspace/
+
+# The .archal.json launch command overrides this; kept for standalone debugging.
+CMD ["node", "/app/drive.mjs"]

package/agents/openclaw/README.md

@@ -0,0 +1,113 @@
+# OpenClaw Agent Harness
+
+This example runs the **real OpenClaw agent** against an Archal clone, packaged as
+an ordinary agent and executed through the generic Docker-harness **sidecar**
+engine.
+
+It is the agent behind `archal run <scenario>.md --sandbox`. The `--sandbox` flag
+no longer runs a bespoke in-container engine: the legacy path — a fixed
+`archal/sandbox` image with an in-container TLS proxy, DNS rewrites, a baked
+entrypoint, and the `runSandboxed` special case — has been removed. `--sandbox`
+now launches this packaged agent through the generic Docker-harness **sidecar**,
+which owns all network interception while this image just runs the agent.
+
+> **Status: live.** `archal run <scenario>.md --sandbox` resolves to this bundled
+> package. There is no separate `--agent` flag — the packaged-agent selector was
+> removed; other packaged agents run via `--harness <dir> --dockerfile <dir>/Dockerfile`.
+
+## What this demonstrates
+
+- A full external agent (the OpenClaw gateway + its shell/exec tools) packaged
+  into one image, driven once per task and printing its answer to stdout.
+- **Transparent interception by the sidecar**: the agent's `gh` / `curl` calls to
+  `api.github.com` are routed to the clone via the sidecar's DNS + TLS MITM — no
+  base-URL override, no code change. The sidecar writes its CA to
+  `/agent-output/ca.crt`; the harness sets `NODE_EXTRA_CA_CERTS` to it, so the CA
+  is trusted by the agent and its child processes.
+- **No in-container network plumbing**: this image runs **no** proxy, **no**
+  `/etc/hosts` rewrite, and **no** iptables. That was the old single-container
+  model; the sidecar replaces it.
+- **Real model, fake services**: provider domains (`api.openai.com`,
+  `api.anthropic.com`, …) are forwarded to the real model with the host key
+  injected by the proxy; only clone domains are intercepted.
+- **Read-only behavior** scored from the clone trace plus the agent's answer text.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `Dockerfile` | Packages `openclaw` (version pinned in `package.json`, overridable via `--build-arg OPENCLAW_VERSION`) + the `gh` CLI |
+| `package.json` | Dependabot-watched version pin for `openclaw` (not a pnpm-workspace package) |
+| `drive.mjs` | Entrypoint: reads `AGENT_TASK`, starts the local gateway, sends the task, prints the answer to stdout |
+| `extract-openclaw-response-text.mjs` | Shared Responses-API answer parser (canonical copy in `packages/sandbox-runtime`) |
+| `workspace/` | A **generic demo persona** (`IDENTITY.md`, `SOUL.md`, `AGENTS.md`, `TOOLS.md`) — swap or mount your agent's real persona to run it as itself |
+| `.archal.json` | Declares the agent command + the `github` clone |
+| `scenarios/` | GitHub triage and live-acceptance scenarios |
+
+## How `drive.mjs` works
+
+It reproduces the **agent-side** of the legacy sandbox entrypoint; the
+**network-side** (proxy, CA install, DNS, iptables) is the sidecar's job and is
+intentionally absent here. The drive script:
+
+1. Stages the bundled `workspace/` into a writable `~/.openclaw/workspace` and
+   writes a minimal non-interactive `~/.openclaw/openclaw.json` (local gateway on
+   `:18789`, provider base URLs at their real defaults with `allowPrivateNetwork`,
+   shell/exec tools allowed).
+2. Starts the gateway: `openclaw gateway run --port 18789 --bind loopback`, and
+   waits for the `[gateway] ready` marker.
+3. Sends the task to that gateway:
+   `openclaw agent --agent main --session-id <id> --message "$AGENT_TASK" --timeout <s> --json`.
+4. Parses the agent's final answer via `extract-openclaw-response-text.mjs` and
+   prints it to stdout for the evaluator.
+
+## Syntax check
+
+```bash
+node --check drive.mjs
+ARCHAL_PREFLIGHT=1 node drive.mjs   # only meaningful inside the built image
+```
+
+## Run
+
+`archal run <scenario>.md --sandbox` is the one-flag shortcut for this bundled
+package. To run it explicitly as a packaged agent — the same path `--sandbox`
+resolves to internally — point the generic harness flags at this directory:
+
+```bash
+cd examples/agents/openclaw
+# Set the key for the model's provider (see the env-var table below):
+# OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY.
+export OPENAI_API_KEY=...
+archal run scenarios/github-issue-triage-read-only.md \
+  --harness . \
+  --dockerfile Dockerfile \
+  -n 1
+```
+
+Docker mode is required so the sidecar can control DNS and TLS trust for
+`api.github.com`.
+
+## Build args
+
+| Arg | Default | Notes |
+|-----|---------|-------|
+| `OPENCLAW_VERSION` | from `package.json` (`dependencies.openclaw`, Dependabot-managed) | Pin the agent version. Defaults to the pinned `package.json` version; override with `docker build --build-arg OPENCLAW_VERSION=2026.6.6 ...` or the equivalent harness option. Do not use a floating tag. |
+
+## Environment variables
+
+| Variable | Source | Notes |
+|----------|--------|-------|
+| `AGENT_TASK` | Injected by Archal | The scenario prompt |
+| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` | Host → proxy | Real key on the host; the sidecar injects the matching provider's native auth header. Each provider is pinned to its native wire API (`openai-responses` / `anthropic-messages` / `google-generative-ai`), so non-OpenAI models hit their native paths (`/v1/messages`, `:generateContent`) instead of OpenAI-compat `/chat/completions`. |
+| `AGENT_MODEL` | Injected by Archal (optional) | Overrides the gateway's default model. Use a provider-prefixed id (e.g. `anthropic/claude-sonnet-4-6`, `google/gemini-2.5-flash`) |
+| `AGENT_ID` | Optional | Selects the agent (default `main`) |
+| `AGENT_DISABLE_PLUGINS` / `AGENT_EVAL_MODE=isolated` | Optional | Eval mode — runs with an isolated config and no business-tool plugins (GitHub is reached via the `gh` CLI, not a plugin) |
+| `ARCHAL_TIMEOUT` | Optional | Per-task agent timeout in seconds (default `120`) |
+
+## Read-only home / workspace
+
+The demo persona is shipped read-only-friendly: `drive.mjs` copies the bundled
+`workspace/` into a writable `~/.openclaw/workspace`, so the source assets can be
+mounted **read-only**. Pass `--openclaw-home` to mount your own OpenClaw home at
+`/openclaw-home` inside the container.