archal 0.9.19 → 0.10.0

package/skills/scenario/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scenario
-description: Write, edit, and validate Archal scenario files. Knows the markdown format, success criteria syntax, and config options.
+description: Write, edit, and validate Archal scenario markdown — the format, success criteria syntax, and config. USE THIS whenever the user wants to "write a scenario", "add a test for my agent", "fix/edit my scenario", asks "what's the success criteria syntax" or about `[D]`/`[P]` criteria, needs a multi-clone scenario, or is validating scenario files. Reach for it on any mention of authoring or fixing Archal scenarios.
 user-invocable: true
 argument-hint: "[scenario description or file path]"
 ---
@@ -15,7 +15,7 @@ You write and edit Archal scenario files. Scenarios are markdown files that defi
 # Scenario Title
 
 ## Setup
-Starting state described in plain English. Drives seed generation.
+Starting state context. Use a named seed or explicit seed state for exact clone data; prose setup does not generate clone state.
 
 ## Prompt
 The task instruction given to the agent.
@@ -38,7 +38,7 @@ runs: 3
 | Section | Required | Aliases | Purpose |
 |---------|----------|---------|---------|
 | `# Title` | yes | | Scenario name (H1 heading) |
-| `## Setup` | no | `Context`, `Initial State` | Starting state in plain English |
+| `## Setup` | no | `Context`, `Initial State` | Starting state context |
 | `## Prompt` | yes | `Task`, `Instruction`, `Instructions`, `Request` | Task given to the agent |
 | `## Expected Behavior` | no | `Expected Behaviour`, `Behavior`, `Behaviour`, `Judge Notes`, `Evaluation Notes` | Answer key for evaluator (never shown to agent) |
 | `## Success Criteria` | yes | `Success`, `Criteria`, `Checks`, `Assertions` | Evaluable checks |
@@ -92,19 +92,33 @@ Aliases for `evaluator-model`: `evaluator`, `evaluatormodel`, `model`.
 The full clone and seed surface is manifest-backed. Prefer `archal clone --json`
 and `archal seed list` over maintaining a separate list in this skill.
 
-| Clone | Seeds |
-|------|-------|
-| `apify` | `empty` |
-| `github` | `empty`, `small-project`, `enterprise-repo`, `ci-cd-pipeline`, `stale-issues`, `large-backlog` |
-| `slack` | `empty`, `engineering-team`, `busy-workspace`, `incident-active` |
-| `stripe` | `empty`, `small-business`, `checkout-flow`, `subscription-lifecycle`, `subscription-heavy` |
-| `jira` | `empty`, `small-project`, `enterprise`, `sprint-active`, `large-backlog` |
-| `linear` | `empty`, `small-team`, `engineering-org`, `multi-team`, `busy-backlog` |
-| `supabase` | `empty`, `small-project`, `saas-starter`, `ecommerce` |
-| `google-workspace` | `empty`, `assistant-baseline`, `gmail-busy-inbox`, `calendar-packed-week` |
-| `tavily` | `empty` |
-| `ramp` | `empty`, `default` |
-| `discord` | `empty`, `small-server`, `harvested` |
+| Clone | Seed lookup |
+|-------|-------------|
+| `apify` | `archal seed list apify --json` |
+| `calcom` | `archal seed list calcom --json` |
+| `clickup` | `archal seed list clickup --json` |
+| `customerio` | `archal seed list customerio --json` |
+| `datadog` | `archal seed list datadog --json` |
+| `discord` | `archal seed list discord --json` |
+| `github` | `archal seed list github --json` |
+| `gitlab` | `archal seed list gitlab --json` |
+| `google-workspace` | `archal seed list google-workspace --json` |
+| `hubspot` | `archal seed list hubspot --json` |
+| `jira` | `archal seed list jira --json` |
+| `linear` | `archal seed list linear --json` |
+| `ownerrez` | `archal seed list ownerrez --json` |
+| `pricelabs` | `archal seed list pricelabs --json` |
+| `ramp` | `archal seed list ramp --json` |
+| `sentry` | `archal seed list sentry --json` |
+| `slack` | `archal seed list slack --json` |
+| `stripe` | `archal seed list stripe --json` |
+| `supabase` | `archal seed list supabase --json` |
+| `tavily` | `archal seed list tavily --json` |
+| `unipile` | `archal seed list unipile --json` |
+| `webflow` | `archal seed list webflow --json` |
+
+Run `archal clone --json` for supported clones and
+`archal seed list <clone> --json` before naming a seed.
 
 ## Clone auto-detection from content
 
@@ -131,7 +145,11 @@ Use multiple clones by listing them in config:
 clones: github, slack
 ```
 
-The Setup section can describe state across both services. Each clone gets its own seed.
+The Setup section can describe context across both services. Attach explicit seed state per clone via `seed:` or `## Seed State` (see Seed state below).
+
+## Seed state
+
+Seeding is deterministic — explicit committed state, no LLM. Scenarios attach it via the `seed:` config key or a `## Seed State` section. To author or load explicit JSON/SQL/catalog state into a clone, delegate to the sibling `seed` skill (`packages/archal/skills/seed`) rather than handling the seeding mechanics here.
 
 ## Validation
 
@@ -147,7 +165,7 @@ Run `archal scenario list` to verify scenarios parse correctly. A valid scenario
 1. Writing `[D]` criteria that require subjective judgment
 2. Writing `[P]` criteria that could be checked deterministically
 3. Forgetting to specify which clone the scenario uses
-4. Writing Setup descriptions that are too vague for seed generation
+4. Relying on vague Setup text when the scenario needs exact seeded state
 5. Using seed names that don't exist (check the seed table above)
 
 ## Documentation

package/skills/seed/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: seed
+description: Craft and load explicit clone seed state for Archal, deterministically and with no LLM. This is the canonical "how to seed a clone" skill. Use it whenever you need to give a clone (github, stripe, supabase, slack, ...) a known starting state: writing or editing a JSON or SQL seed file, choosing a named catalog seed, wiring a scenario's seed, debugging "seed not found" / "seed_unavailable" / shape-mismatch / rollback errors, or deciding between an inline `## Seed State` block and a committed seed file. Reach for this any time the words seed, seed state, starting state, fixture data, or "set up the clone with..." appear.
+user-invocable: true
+argument-hint: "[clone + the state you want loaded]"
+---
+
+# Archal Seed State
+
+You craft and load explicit starting state for Archal clones. A seed is the
+clone's state before a run begins: the issues GitHub holds, the customers and
+subscriptions Stripe holds, the rows a Supabase database holds.
+
+The one rule that defines this skill: **seeds are explicit, committed, and
+deterministic. No LLM is involved.** You write the state, or you pick a named
+catalog seed someone already wrote. You never ask a model to invent it.
+
+The dedicated package that loads seed state, `@archal/seed-state`, says this in
+its own README and it is the mental model to hold:
+
+> This package intentionally contains no LLM calls, code generation, natural
+> language extraction, cache, repair, or scenario-to-state generation.
+
+## The four shapes a seed can take
+
+1. **A committed JSON seed file** — `clones/<clone>/seeds/<name>.json`. A
+   top-level object whose keys are the clone's collections and whose values are
+   arrays of entities. This is the common shape for object-graph clones
+   (github, stripe, slack, linear, jira). Example file:
+   `clones/github/seeds/small-project.json`.
+
+2. **A committed SQL seed file** — `clones/<clone>/seeds/<name>.sql`. A set of
+   `CREATE TABLE` + `INSERT` statements. The natural shape for relational
+   clones like `supabase`, whose seeds on disk are `.sql`, not `.json`. Example:
+   `clones/supabase/seeds/ecommerce.sql`.
+
+3. **A named catalog seed** — a seed that already lives on disk for a clone, so
+   you reference it by name instead of writing one. `github: small-project`,
+   `stripe: checkout-flow`, `supabase: saas-starter`. Browse them with
+   `archal seed list <clone>`.
+
+4. **An inline `## Seed State` block in a scenario** — explicit state written
+   directly in the scenario markdown. Use it when the state is small and tightly
+   coupled to that one scenario. For anything reused across scenarios, prefer a
+   committed file (shapes 1–3) so it has one home.
+
+Resolution on disk checks `<name>.json` first, then `<name>.sql`
+(`loadSeedStateFromPath` in `packages/seed-state/src/state.ts`). A clone can
+ship either form for a given seed name, not both.
+
+## How a scenario or the CLI selects a seed
+
+A seed value comes from one of two places, parsed identically:
+
+- The scenario `## Config` key `seed:`
+- The CLI flag `archal run --seed <name-or-path>`
+
+Both accept the same forms (verbatim from the `--seed` flag help):
+
+> Seed name (e.g. small-project), clone-prefixed name (github:small-project,
+> applies only to that clone), seed family (enterprise, stale, ...), or local
+> file path (.json / .md).
+
+So the two everyday shapes are:
+
+- **Bare name** — `seed: small-project`. Applies to every clone the scenario
+  declares.
+- **Clone-prefixed** — `seed: github:small-project`. Applies only to the named
+  clone. This matches `archal clone start --seed github:small-project`, so the
+  same string works in both commands.
+
+The prefix is validated: if you write `seed: payments:checkout-flow` but the
+scenario never declares a `payments` clone, you get a usage error naming the
+clones the scenario actually has, rather than a confusing `seed_unavailable`
+later from the runtime (`parseExplicitSeed` in
+`cli/src/runner/seed-resolution.ts`).
+
+One behavior to remember: a scenario with a `## Setup` section but **no**
+explicit `seed:` is forced to the `empty` seed, because Setup prose used to
+drive dynamic generation and a pre-populated seed would conflict with it. To
+combine a Setup description with a real seed, you must add an explicit `seed:`
+field. (See `resolveRunSeedPlan` in `cli/src/runner/seed-resolution.ts`.)
+
+### Command surface
+
+| Command | What it does |
+|---------|--------------|
+| `archal seed list` | One row per clone: clone, default seed, seed count |
+| `archal seed list <clone>` | Every seed for that clone, with the default marked |
+| `archal seed list <clone> --json` | Same, machine-readable |
+| `archal run <scenario>.md --seed <name-or-path>` | Override the seed for a run |
+| `archal run ... --fresh-seed` | On a reused clone session, reset and re-apply the seed |
+| `archal run ... --keep-state` | On a reused session, keep existing state, do not re-apply |
+| `archal clone start <clone> --seed <seeds...>` | Start a live clone pre-seeded |
+| `archal clone start <clone> --seed-file <path>` | Start a live clone, then load a JSON or SQL seed file |
+| `archal clone seed <clone> <name>` | Sideload a named catalog seed into a running clone |
+| `archal clone seed <clone> --file <path>` | Sideload a JSON or SQL seed file into a running clone |
+
+Prefer `archal seed list` over memorizing a seed table. The catalog is derived
+from `clones/<clone>/seeds/*.{json,sql}` on disk, so the CLI is always current.
+
+## The deterministic load flow
+
+When a run seeds a clone, the loader does this, in order
+(`packages/runtime/src/seed-loader.ts`):
+
+1. **Snapshot first.** `GET /state` on each target clone and keep the response
+   text. This is the rollback point (`snapshotSeedTargets` →
+   `fetchSeedStateSnapshot`).
+2. **Apply the seed.** `PUT /state` with the seed body — `application/json` for
+   a JSON seed, `text/sql` for a SQL seed — one clone at a time, tracking each
+   one that committed.
+3. **Roll back on failure.** If any clone's load throws, restore the clones that
+   already committed by replaying their snapshots, then re-throw the original
+   error (`restoreSeedTargets`). A clone is never left half-seeded.
+4. **Capture the baseline after seeding.** Once seeding succeeds, the post-seed
+   state is captured as the baseline by `@archal/vitest` bootstrap
+   (`captureBaselineCloneStates` in `packages/vitest/src/runtime/bootstrap.ts`).
+   Resets between runs restore *this* seeded baseline, not an empty clone — so
+   every run in a multi-run scenario starts from the same seeded state.
+
+### How state reaches the clone (the `/state` endpoint)
+
+The clone server exposes `/state` (`clones/core/src/rest/rest-built-in-endpoints.ts`):
+
+- `GET /state` — read the current state (used for the snapshot and baseline).
+- `PUT /state` — load state. The handler branches on `Content-Type`:
+  - `text/sql` or `application/sql` → parsed and loaded as SQL (only when the
+    clone exposes SQL loading; otherwise it returns a 400 telling you to send
+    JSON).
+  - otherwise → loaded as JSON state.
+  - `PUT /state?seed=<name>` with a `{}` body → load a named catalog seed
+    server-side, without sending a state body at all.
+- `DELETE /state` — wipe state (used by `--fresh-seed` before re-applying).
+
+A successful `PUT` returns `{ ok: true }`. The content-type the CLI sends is set
+in one place — `text/sql` when there is SQL, `application/json` otherwise
+(`pushStateToCloud` in `cli/src/runner/execution/agent-http.ts`); named-seed
+loads always send `application/json` with an empty body.
+
+## Do not do these
+
+- **Do not synthesize seed data from scenario prose.** A `## Setup` paragraph is
+  context for the evaluator, not a source you extract state from. If you need
+  populated state, write a committed seed (or pick a named one) and reference it
+  with `seed:`.
+- **Do not call an LLM to generate, repair, or "fill in" a seed.** The old
+  dynamic seed-generation path is being removed; `@archal/seed-state` was built
+  specifically to have none of it. Explicit committed seeds only.
+- **Do not invent collection names.** A JSON seed must use the clone's real
+  collection keys (see "Writing a good JSON seed"). Unknown keys are dropped by
+  normalization, so a typo silently seeds nothing.
+- **Do not hand-tune both `.json` and `.sql` for the same name.** Pick one form
+  per seed name; resolution stops at the first that exists.
+- **Do not blow away a sideloaded session by accident.** On a reused
+  `archal clone start` session the loader probes for existing state before
+  re-applying. Use `--keep-state` to keep it or `--fresh-seed` to reset on
+  purpose, rather than fighting the guard.
+
+## Writing a good JSON seed
+
+The seed file must mirror the clone's real state shape. The fastest reliable way
+to get the shape right is to open an existing catalog seed for that clone and
+match its top-level keys and per-entity fields.
+
+A JSON seed is a top-level object: each key is a collection, each value is an
+array of entity objects.
+
+```jsonc
+{
+  "users":  [{ "id": "u1", "login": "octocat", "type": "User" }],
+  "repos":  [{ "id": "r1", "name": "demo", "fullName": "octocat/demo", "private": false }],
+  "issues": [{ "id": "i1", "repoId": "r1", "number": 1, "title": "First issue", "state": "open" }]
+}
+```
+
+Match the clone, not your imagination:
+
+- Use the same collection names the clone uses. `clones/github/seeds/small-project.json`
+  has `users`, `repos`, `issues`, `pullRequests`, `labels`, and more.
+- Give each entity the fields the clone expects, especially `id` and the foreign
+  keys that wire entities together (`repoId`, `issueNumber`, ...). The clone
+  maintains those relationships; broken references produce realistic errors at
+  runtime, not seed-time.
+- Only arrays survive normalization — non-array top-level values are dropped
+  (`normalizeSeedState`). Keep everything in collection arrays.
+
+## When SQL fits
+
+Use a `.sql` seed for relational clones whose state is naturally tables and
+rows — `supabase` is the canonical case, and its seeds on disk are `.sql`. The
+SQL seed is plain `CREATE TABLE` + `INSERT INTO ... VALUES (...)`:
+
+```sql
+CREATE TABLE customers (id serial, email text, name text);
+INSERT INTO customers (email, name) VALUES
+  ('ada@example.com', 'Ada Lovelace'),
+  ('alan@example.com', 'Alan Turing');
+```
+
+The SQL parser is deliberately small (`parseSqlSeed` in
+`packages/seed-state/src/state.ts`): it understands `CREATE TABLE` (including
+`IF NOT EXISTS`), `INSERT INTO ... VALUES`, schema-qualified and quoted
+identifiers, line and block comments, and auto-assigns serial `id`s. It is not a
+full SQL engine — anything other than `CREATE TABLE` / `INSERT` throws an
+"Unsupported SQL seed statement" error. Keep seeds to those two statements.
+
+## Failure taxonomy
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `Could not resolve static seed "<name>"` / `seed_unavailable` | Seed name is misspelled, not in this clone's catalog, or the hosted session was started with a different seed | `archal seed list <clone>` to confirm the name; re-provision the session with the right seed |
+| `clone "<x>" is not part of this scenario` | Clone-prefixed seed names a clone the scenario doesn't declare | Add the clone to `clones:`, or drop the prefix |
+| Seed loads but state looks empty / partial | Wrong collection keys, or non-array top-level values dropped by normalization | Match an existing catalog seed's keys; keep every collection an array |
+| `Failed to parse seed file ...` | Malformed JSON | Validate the JSON; check trailing commas and quoting |
+| `Unsupported SQL seed statement: ...` | SQL beyond `CREATE TABLE` / `INSERT` | Reduce the seed to those two statements |
+| `…does not expose SQL state loading` (HTTP 400) | Sent SQL to a clone that only loads JSON | Send JSON state, or use a clone that supports SQL |
+| `Rollback failed after partial seed load` | A clone errored mid-load and the snapshot restore also failed | The clones may be in a mixed state; restart the clone session and retry |
+| Seed "not re-applied" warning on a reused session | The loader kept existing sideloaded state instead of overwriting it | `--fresh-seed` to reset and re-apply, or `--keep-state` to accept it on purpose |
+
+## What to report back
+
+After authoring or loading a seed, tell the user:
+
+- the clone(s) and the seed shape used (named catalog seed, JSON file, SQL file,
+  or inline `## Seed State`)
+- the seed name or file path, and how a scenario/run selects it (`seed:` or
+  `--seed`)
+- the entity counts loaded per clone (the loader logs e.g. `7 issues, 3 repos`)
+- for a new seed file, that it mirrors an existing catalog seed's shape
+- any blocker: missing seed name, shape mismatch, SQL parse error, or a rollback
+  that fired — with the exact next command
+
+## Docs
+
+- Seeds guide: https://docs.archal.ai/guides/seeds
+- Clones and seeds overview: https://docs.archal.ai/clones/overview
+- Writing scenarios: https://docs.archal.ai/guides/writing-scenarios

package/skills/vitest/SKILL.md

@@ -17,7 +17,8 @@ Claude already knows what Vitest is and how a fetch interceptor works. These are
 - Clones are hosted on **ECS Fargate** in Archal's AWS. First run = ~30s cold start. Subsequent runs within the 30-min idle TTL = ~2s. Tell the user; they'll think it's hung otherwise.
 - Session cache key = `(projectName, services, seeds)` hash. Change any of those and the cache misses.
 - **Seeds = starting state.** Omit to get the clone's default. Named seeds give fixtures (e.g. `small-project` for GitHub, `small-business` for Stripe). Never ask "what seed?" open-ended - the user doesn't know the catalog.
-- Route-mode clone availability is defined by `SHARED_ROUTE_MANIFESTS` in `packages/route-runtime-core/src/manifests.ts`; use `archal clone --json` / `archal seed list` before naming supported services.
+- Route-mode clone availability comes from the packaged route manifest; use
+  `archal clone --json` / `archal seed list` before naming supported services.
 
 ## Discover before you ask
 
@@ -131,4 +132,4 @@ console.log(getInstalledArchalVitestSession()?.resolvedRuntime.resolvedServices)
 ## Docs
 
 - Guide: https://docs.archal.ai/guides/vitest
-- Package reference: `packages/vitest/README.md`
+- Package reference: `archal/vitest` in the `archal` npm package

package/dist/harness.cjs

@@ -1,62 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/harness.ts
-var harness_exports = {};
-__export(harness_exports, {
-  reportAgentMetrics: () => reportAgentMetrics
-});
-module.exports = __toCommonJS(harness_exports);
-var import_promises = require("fs/promises");
-var import_node_path = require("path");
-async function reportAgentMetrics(metrics, options = {}) {
-  assertNonNegativeInteger("inputTokens", metrics.inputTokens);
-  assertNonNegativeInteger("outputTokens", metrics.outputTokens);
-  assertNonNegativeInteger("llmCallCount", metrics.llmCallCount);
-  const metricsFile = options.metricsFile ?? process.env["AGENT_METRICS_FILE"] ?? process.env["ARCHAL_METRICS_FILE"];
-  if (!metricsFile) {
-    return false;
-  }
-  await (0, import_promises.mkdir)((0, import_node_path.dirname)(metricsFile), { recursive: true });
-  await (0, import_promises.writeFile)(
-    metricsFile,
-    JSON.stringify({
-      version: 1,
-      inputTokens: metrics.inputTokens,
-      outputTokens: metrics.outputTokens,
-      llmCallCount: metrics.llmCallCount,
-      ...nonEmptyString(metrics.provider) ? { provider: metrics.provider.trim() } : {},
-      ...nonEmptyString(metrics.model) ? { model: metrics.model.trim() } : {}
-    }),
-    "utf8"
-  );
-  return true;
-}
-function nonEmptyString(value) {
-  return typeof value === "string" && value.trim().length > 0;
-}
-function assertNonNegativeInteger(name, value) {
-  if (!Number.isSafeInteger(value) || value < 0) {
-    throw new TypeError(`${name} must be a non-negative safe integer`);
-  }
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  reportAgentMetrics
-});

package/dist/harness.d.cts

@@ -1,20 +0,0 @@
-interface AgentMetrics {
-    inputTokens: number;
-    outputTokens: number;
-    llmCallCount: number;
-    provider?: string;
-    model?: string;
-}
-interface ReportAgentMetricsOptions {
-    metricsFile?: string;
-}
-/**
- * Write agent-side token usage for `archal run`.
- *
- * Archal sets AGENT_METRICS_FILE when it launches a harness. Calling this
- * helper before the harness exits lets the dashboard show agent input/output
- * token counts without exposing the artifact wire format to user code.
- */
-declare function reportAgentMetrics(metrics: AgentMetrics, options?: ReportAgentMetricsOptions): Promise<boolean>;
-
-export { type AgentMetrics, type ReportAgentMetricsOptions, reportAgentMetrics };