archal 0.9.18 → 0.9.20

package/README.md

@@ -108,11 +108,16 @@ 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 autoloop <uuid>` | Use an existing hosted 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 preprod plan` | Inspect a repo and propose a pre-production scenario loop |
+| `archal preprod run [scenarios...]` | Run scenarios through a bounded fix/rerun loop |
+| `archal autoloop [trace-dir] --repo <dir>` | Register a read-only trace source or start a local trace loop |
+| `archal autoloop-status` | Show local autoloop trace job status |
+| `archal 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 |
@@ -121,6 +126,9 @@ config looks like this:
 
 Run `archal <command> --help` for flag details.
 
+For terminal-first autonomous loops, see
+<https://docs.archal.ai/guides/autoloop-production-traces>.
+
 ## Vitest integration (secondary use case)
 
 You can also import `archal/vitest` to route SDK traffic from a vitest

package/agents/github-octokit/.archal.json

@@ -0,0 +1,8 @@
+{
+  "description": "A thin single-file Octokit GitHub agent.",
+  "agent": {
+    "command": "node",
+    "args": ["agent.mjs"]
+  },
+  "clones": ["github"]
+}

package/agents/github-octokit/Dockerfile

@@ -0,0 +1,8 @@
+FROM node:22-bookworm
+
+WORKDIR /app
+COPY package.json ./
+RUN npm install --omit=dev
+COPY agent.mjs ./
+
+CMD ["node", "agent.mjs"]

package/agents/github-octokit/README.md

@@ -0,0 +1,113 @@
+# GitHub Octokit Harness
+
+This example shows how to run `@octokit/rest` against the Archal GitHub clone
+without changing the client-visible GitHub API origin.
+
+The harness owns its own REST calls. It does not expose `archal-*` tools to a
+model — it thinks it is talking to GitHub's API.
+
+## What this demonstrates
+
+- `GITHUB_TOKEN` is auto-seeded as `ghp_test_bootstrap_token` (from PR #2895).
+- The harness calls Octokit's normal `https://api.github.com` origin.
+- Docker harness networking maps that real domain to Archal's TLS intercept.
+- The clone speaks the same REST contract as `api.github.com`.
+
+Run this example with Docker routing as shown below. If you run the same
+Octokit code as an uncontainerized local harness, `https://api.github.com`
+is the real GitHub API; configure Octokit's `baseUrl` to the clone REST URL
+pattern from `archal clone start github` / `archal clone status`, and use
+`ARCHAL_TOKEN` for that request.
+
+## Install
+
+```bash
+cd examples/agents/github-octokit
+npm install
+```
+
+`@octokit/rest` is the only dependency.
+
+## Syntax check
+
+```bash
+node --check agent.mjs
+```
+
+## Seed and auth requirements
+
+This example requires the `small-project` seed (declared in the scenario
+file). The seed pre-populates:
+
+- An authenticated user (`octocat`) mapped to the bootstrap token
+- A public repository `octocat/webapp`
+
+The bootstrap token `ghp_test_bootstrap_token` is injected as `GITHUB_TOKEN`
+by the Archal Docker harness. `GET /user` authenticates against this token
+and returns the seeded `octocat` user. If you reuse an existing clone session
+with `--keep-state`, make sure the session was started with the
+`small-project` seed -- otherwise `GET /user` will return 403 because the
+bootstrap token is not present in the clone's auth state.
+
+## Run manually with a live clone
+
+```bash
+cd examples/agents/github-octokit
+archal run scenarios/test-repo-access.md \
+  --harness . \
+  --dockerfile Dockerfile \
+  -n 1
+```
+
+The scenario declares the hosted `small-project` GitHub seed so SDK smoke runs
+use stable catalog state instead of dynamic seed generation. Docker mode
+(`--dockerfile`) is required for TLS interception of `api.github.com`.
+
+To run without a model (harness-only, no LLM evaluation):
+
+```bash
+archal run scenarios/test-repo-access.md \
+  --harness . \
+  --dockerfile Dockerfile \
+  --agent-model none \
+  -n 1
+```
+
+## Wire into `.archal.json`
+
+The `.archal.json` in this directory is already configured:
+
+```json
+{
+  "agent": {
+    "command": "node",
+    "args": ["agent.mjs"]
+  },
+  "clones": ["github"]
+}
+```
+
+From the project root, bare `archal run` picks up the config automatically when
+run from inside the `examples/agents/github-octokit/` directory.
+
+## Environment variables
+
+| Variable       | Source             | Value                      |
+| -------------- | ------------------ | -------------------------- |
+| `GITHUB_TOKEN` | Injected by Archal | `ghp_test_bootstrap_token` |
+
+The token is automatically seeded into the clone's auth state by the
+`small-project` seed. The Docker harness injects it as an environment
+variable so Octokit picks it up without code changes.
+
+## Further reading
+
+See `apps/web/docs/quickstart.mdx` for the full conceptual model: how runs
+work, what service clones are, and how the harness fits into the `archal run`
+loop.
+
+## Relationship to other examples
+
+The `google-workspace-local-tools` example uses the same local-tools
+interception pattern but targets the Google Workspace clone via raw `fetch`
+calls. This example is the GitHub equivalent, using `@octokit/rest` instead.

package/agents/github-octokit/agent.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// GitHub Octokit harness — docs-as-code example for Archal.
+//
+// The harness uses Octokit's default API origin, https://api.github.com.
+// In Docker harness runs, Archal maps that real domain to the TLS intercept
+// listener and routes the requests to the GitHub clone underneath the process.
+//
+// This file is intentionally simple: two calls, stdout output, exit 0.
+// Copy it as a starting point for your own GitHub harness.
+
+import { Octokit } from '@octokit/rest';
+
+// Optional manual smoke test: run with ARCHAL_PREFLIGHT=1 to verify this file
+// starts without making service calls.
+if (process.env.ARCHAL_PREFLIGHT === '1') {
+  console.log('OK');
+  process.exit(0);
+}
+
+const token = process.env.GITHUB_TOKEN?.trim() || 'ghp_test_bootstrap_token';
+
+const octokit = new Octokit({ auth: token });
+
+async function main() {
+  // Call 1: prove auth + routing work.
+  // The clone returns a realistic user object from the default seed.
+  const { data: user } = await octokit.rest.users.getAuthenticated();
+
+  // Call 2: prove stateful object access works.
+  // The scenario pins the small-project seed, which includes octocat/webapp.
+  const { data: repo } = await octokit.rest.repos.get({
+    owner: 'octocat',
+    repo: 'webapp',
+  });
+
+  // Print to stdout so the trace captures the result.
+  console.log(JSON.stringify({
+    user: {
+      login: user.login,
+      id: user.id,
+      type: user.type,
+    },
+    repo: {
+      full_name: repo.full_name,
+      private: repo.private,
+      default_branch: repo.default_branch,
+    },
+  }, null, 2));
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/agents/github-octokit/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@archal-examples/github-octokit",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "dependencies": {
+    "@octokit/rest": "^22.0.1"
+  }
+}

package/agents/github-octokit/scenarios/test-repo-access.md

@@ -0,0 +1,27 @@
+# Test GitHub Repository Access
+
+## Setup
+
+The GitHub clone starts with the `small-project` seed, which includes:
+
+- an authenticated user (`octocat`)
+- a public repository `octocat/webapp`
+
+## Prompt
+
+Fetch the authenticated user and retrieve the `octocat/webapp` repository. Print both results.
+
+## Success Criteria
+
+- [D] The run exits successfully
+- [D] The harness prints a `user.login` field
+- [D] The harness prints a `repo.full_name` of `octocat/webapp`
+- [P] The output contains realistic GitHub-shaped fields (id, type, private, default_branch)
+
+## Config
+
+clones: github
+seed: small-project
+timeout: 60
+runs: 1
+tags: smoke, github, harness

package/agents/google-workspace-local-tools/Dockerfile

@@ -0,0 +1,6 @@
+FROM node:22-bookworm
+
+WORKDIR /app
+COPY agent.mjs ./
+
+CMD ["node", "agent.mjs"]

package/agents/google-workspace-local-tools/README.md

@@ -0,0 +1,58 @@
+# Google Workspace Local-Tools Harness
+
+This example packages the same shape we proved with Exo:
+
+- the harness owns its own local tools
+- those local tools call the normal Google REST endpoints
+- Archal sits underneath the Google traffic and intercepts it into the hosted Google Workspace clone
+
+It does not expose `archal-*` tools to the model. The harness thinks it is talking to Google.
+
+## Current status
+
+This fixture is the reference shape and the hosted path now works end to end. It is the lightest way to validate the same local-tools interception pattern we proved with Exo.
+
+## Intended run command
+
+```bash
+archal run examples/agents/google-workspace-local-tools/scenario.md \
+  --harness examples/agents/google-workspace-local-tools \
+  --dockerfile Dockerfile \
+  -n 1
+```
+
+Or use the structured task-first input path:
+
+```bash
+archal run --input examples/agents/google-workspace-local-tools/run-input.yaml \
+  --harness examples/agents/google-workspace-local-tools \
+  --dockerfile Dockerfile \
+  -n 1
+```
+
+The harness uses three local tools:
+
+- `read_email`
+- `get_calendar`
+- `generate_draft`
+
+Under the hood those tools call the real Google Workspace API origins:
+
+- `GET https://gmail.googleapis.com/gmail/v1/users/me/messages`
+- `GET https://gmail.googleapis.com/gmail/v1/users/me/messages/:id`
+- `GET https://calendar.googleapis.com/calendar/v3/calendars/primary/events`
+- `POST https://gmail.googleapis.com/gmail/v1/users/me/drafts`
+
+The default bearer token is `ya29.self-local-invalid`, which matches the default `assistant-baseline` Google Workspace seed.
+
+## Why this example exists
+
+Exo is a real Electron app with its own tool server and Google SDK clients. That is the strongest proof, but it is heavy for regression coverage and contributor onboarding.
+
+This example is the lightweight reference fixture:
+
+- same local-tools interception pattern
+- much smaller than Exo
+- easy to inspect and adapt under `archal run --harness`
+
+If you want to write your own Gmail/Calendar smoke test, copy either `scenario.md` or `run-input.yaml`. They both encode the same read-email, inspect-calendar, and draft-reply flow, and Google Workspace falls back to `assistant-baseline` automatically when you do not pin a seed.

package/agents/google-workspace-local-tools/agent.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+const originalGoogleBearer = process.env.EXAMPLE_GOOGLE_ACCESS_TOKEN?.trim() || 'ya29.self-local-invalid';
+const calendarDate = process.env.EXAMPLE_CALENDAR_DATE?.trim() || '2026-03-29';
+const task = process.env.AGENT_TASK?.trim()
+  || 'Read the unread inbox email, inspect the next calendar event, and create a draft reply.';
+
+function toBase64Url(input) {
+  return Buffer.from(input, 'utf-8').toString('base64url');
+}
+
+function getGoogleHeaders(json = false) {
+  return {
+    authorization: `Bearer ${originalGoogleBearer}`,
+    ...(json ? { 'content-type': 'application/json' } : {}),
+  };
+}
+
+function toGoogleUrl(path) {
+  if (path.startsWith('/gmail/')) {
+    return `https://gmail.googleapis.com${path}`;
+  }
+  if (path.startsWith('/calendar/')) {
+    return `https://calendar.googleapis.com${path}`;
+  }
+  throw new Error(`Unsupported Google Workspace API path: ${path}`);
+}
+
+async function fetchJson(path, options = {}) {
+  const url = toGoogleUrl(path);
+  let response;
+  try {
+    response = await fetch(url, options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`fetch failed for ${url}: ${message}`);
+  }
+  const text = await response.text();
+  let body = null;
+  if (text.length > 0) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+  }
+
+  if (!response.ok) {
+    throw new Error(`Request failed ${response.status} for ${path}: ${JSON.stringify(body)}`);
+  }
+
+  return body;
+}
+
+function getHeader(payload, name) {
+  const headers = Array.isArray(payload?.headers) ? payload.headers : [];
+  const match = headers.find(
+    (header) =>
+      header
+      && typeof header.name === 'string'
+      && header.name.toLowerCase() === name.toLowerCase(),
+  );
+  return typeof match?.value === 'string' ? match.value : null;
+}
+
+async function readEmail() {
+  const unreadQuery = encodeURIComponent('is:unread in:inbox');
+  const unreadList = await fetchJson(`/gmail/v1/users/me/messages?q=${unreadQuery}&maxResults=1`, {
+    headers: getGoogleHeaders(),
+  });
+  const list = Array.isArray(unreadList?.messages) && unreadList.messages.length > 0
+    ? unreadList
+    : await fetchJson('/gmail/v1/users/me/messages?maxResults=1', {
+      headers: getGoogleHeaders(),
+    });
+
+  const [messageRef] = Array.isArray(list?.messages) ? list.messages : [];
+  if (!messageRef?.id) {
+    throw new Error('No Gmail message available in the selected seed');
+  }
+
+  const message = await fetchJson(
+    `/gmail/v1/users/me/messages/${encodeURIComponent(String(messageRef.id))}?format=full`,
+    { headers: getGoogleHeaders() },
+  );
+  const payload = message?.payload ?? {};
+
+  return {
+    id: String(message.id),
+    threadId: String(message.threadId),
+    subject: getHeader(payload, 'Subject'),
+    from: getHeader(payload, 'From'),
+    snippet: typeof message.snippet === 'string' ? message.snippet : null,
+  };
+}
+
+function buildDayWindow(dateString) {
+  const start = new Date(`${dateString}T00:00:00.000Z`);
+  if (Number.isNaN(start.valueOf())) {
+    throw new Error(`Invalid EXAMPLE_CALENDAR_DATE: ${dateString}`);
+  }
+  const end = new Date(start);
+  end.setUTCDate(end.getUTCDate() + 1);
+  return {
+    timeMin: start.toISOString(),
+    timeMax: end.toISOString(),
+  };
+}
+
+async function getCalendar() {
+  const { timeMin, timeMax } = buildDayWindow(calendarDate);
+  const query = new URLSearchParams({
+    maxResults: '5',
+    singleEvents: 'true',
+    orderBy: 'startTime',
+    timeMin,
+    timeMax,
+  });
+  const response = await fetchJson(`/calendar/v3/calendars/primary/events?${query.toString()}`, {
+    headers: getGoogleHeaders(),
+  });
+  const [firstEvent] = Array.isArray(response?.items) ? response.items : [];
+  if (!firstEvent) {
+    throw new Error(`No calendar event found for ${calendarDate}`);
+  }
+
+  return {
+    id: String(firstEvent.id),
+    summary: typeof firstEvent.summary === 'string' ? firstEvent.summary : null,
+    start: firstEvent.start ?? null,
+  };
+}
+
+function parseEmailAddress(value) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    return 'self@local.invalid';
+  }
+  const bracketMatch = value.match(/<([^>]+)>/);
+  if (bracketMatch?.[1]) {
+    return bracketMatch[1];
+  }
+  const directMatch = value.match(/[^\s<>,;]+@[^\s<>,;]+/);
+  return directMatch?.[0] ?? 'self@local.invalid';
+}
+
+async function generateDraft(email, calendarEvent) {
+  const replyTo = parseEmailAddress(email.from);
+  const draftMime = [
+    `To: ${replyTo}`,
+    `Subject: Re: ${email.subject ?? 'Quick follow-up'}`,
+    '',
+    `Thanks for the note. I saw your message and my next event is "${calendarEvent.summary ?? 'scheduled'}".`,
+  ].join('\r\n');
+
+  const response = await fetchJson('/gmail/v1/users/me/drafts', {
+    method: 'POST',
+    headers: getGoogleHeaders(true),
+    body: JSON.stringify({
+      message: {
+        threadId: email.threadId,
+        raw: toBase64Url(draftMime),
+      },
+    }),
+  });
+
+  return {
+    id: typeof response?.id === 'string' ? response.id : null,
+    messageId: response?.message?.id ?? null,
+  };
+}
+
+async function main() {
+  const toolCalls = [];
+
+  toolCalls.push('read_email');
+  const email = await readEmail();
+
+  toolCalls.push('get_calendar');
+  const calendarEvent = await getCalendar();
+
+  toolCalls.push('generate_draft');
+  const draft = await generateDraft(email, calendarEvent);
+
+  console.log(JSON.stringify({
+    task,
+    toolCalls,
+    email,
+    calendarEvent,
+    draft,
+  }, null, 2));
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/agents/google-workspace-local-tools/archal-harness.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "local": {
+    "command": "node",
+    "args": ["agent.mjs"]
+  }
+}

package/agents/google-workspace-local-tools/run-input.yaml

@@ -0,0 +1,16 @@
+title: Google Workspace Local-Tools Reply Draft
+task: |
+  Read the unread inbox email, inspect the next calendar event for `2026-03-29`,
+  and create a draft reply.
+
+  Do not send the email.
+checks:
+  - The run exits successfully
+  - The harness reports the local tool calls `read_email`, `get_calendar`, and `generate_draft`
+  - The harness creates a Gmail draft id
+  - No `archal-*` tool prompting is required
+config:
+  clones: google-workspace
+  timeout: 120
+  runs: 1
+  tags: smoke, google-workspace, harness

package/agents/google-workspace-local-tools/scenario.md

@@ -0,0 +1,29 @@
+# Google Workspace Local-Tools Reply Draft
+
+## Setup
+
+The Google Workspace account has:
+
+- one unread inbox message in the primary mailbox
+- a primary calendar event on `2026-03-29`
+- a valid seed access token for the baseline account
+
+## Task
+
+Read the unread inbox email, inspect the next calendar event for `2026-03-29`, and create a draft reply.
+
+Do not send the email.
+
+## Checks
+
+- [D] The run exits successfully
+- [D] The harness reports the local tool calls `read_email`, `get_calendar`, and `generate_draft`
+- [D] The harness creates a Gmail draft id
+- [D] No `archal-*` tool prompting is required
+
+## Config
+
+clones: google-workspace
+timeout: 120
+runs: 1
+tags: smoke, google-workspace, harness

package/agents/hermes/.archal.json

@@ -0,0 +1,8 @@
+{
+  "description": "Hermes — a full third-party Stripe support agent.",
+  "agent": {
+    "command": "node",
+    "args": ["drive.mjs"]
+  },
+  "clones": ["stripe"]
+}

package/agents/hermes/Dockerfile

@@ -0,0 +1,46 @@
+# Hermes agent harness — runs the Nous Research `hermes-agent` against Archal clones.
+#
+# The harness keeps calling the real service domains (e.g. api.stripe.com). In a
+# Docker harness run, Archal maps those domains to the TLS intercept listener and
+# routes the requests to the clone underneath the process — the agent is unaware.
+# api.openai.com is allowlisted and forwarded to the real model with the host key
+# injected by the proxy, so the agent's reasoning runs against a real LLM.
+#
+# Because the harness blocks egress to everything except clones + LLM providers,
+# the Stripe MCP is installed at BUILD time and invoked by direct path (no runtime
+# `npx` registry fetch, which would 403).
+FROM node:22-bookworm-slim
+
+# Pin the agent version. Override at build time: --build-arg HERMES_VERSION=0.17.0
+ARG HERMES_VERSION=0.16.0
+
+ENV PYTHONUNBUFFERED=1 \
+    HERMES_HOME=/root/.hermes \
+    HERMES_ACCEPT_HOOKS=1 \
+    PATH="/opt/hermes-venv/bin:${PATH}"
+
+# Python (hermes core) + node/npx (base image, for @stripe/mcp) + tools hermes expects.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      python3 python3-venv python3-pip git ca-certificates ripgrep ffmpeg curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install the agent into an isolated venv, pinned to HERMES_VERSION.
+RUN python3 -m venv /opt/hermes-venv \
+    && /opt/hermes-venv/bin/pip install --no-cache-dir --upgrade pip \
+    && /opt/hermes-venv/bin/pip install --no-cache-dir "hermes-agent==${HERMES_VERSION}"
+
+# Pre-install the Stripe MCP so no runtime registry fetch is needed (egress is
+# blocked). The config invokes its cli.js directly. Fail the build loudly if the
+# entry path moves between @stripe/mcp releases.
+RUN npm install -g @stripe/mcp \
+    && test -f /usr/local/lib/node_modules/@stripe/mcp/dist/cli.js
+
+WORKDIR /app
+
+# Scoped, non-interactive config + the demo persona + the drive entrypoint.
+COPY config.yaml /root/.hermes/config.yaml
+COPY SOUL.md     /root/.hermes/SOUL.md
+COPY drive.mjs   /app/drive.mjs
+
+# The .archal.json launch command overrides this; kept for standalone debugging.
+CMD ["node", "/app/drive.mjs"]