@archmax-ai/harness 0.9.0 → 1.0.1

package/skills/archmax-harness/references/code-states-and-scripts.md

@@ -0,0 +1,115 @@
+# Code-state scripts and `archmax_run` scripts — contracts
+
+Load this when writing a `workflows/<slug>/scripts/*.js` code-state script or a
+`skills/<cap>/scripts/*.js` source. Worked examples, graders and the sandbox details:
+[`code-state-and-test-scripts.md`](code-state-and-test-scripts.md) Part 1.
+
+## Code-state script contract
+
+A `type: code` state runs its `script: scripts/<file>.js` on entry, with no model
+call. The default export is called once with the state's input and **moves the
+session itself**; its return value is never read. The typed import is optional
+(`import { defineCodeState } from "@archmax-ai/harness/sandbox";`, placed below the
+JSDoc; no other import is allowed).
+
+```js
+/**
+ * Request screen — the request must name a requester the order records know.
+ *
+ * Reads the first user message from the session's history, extracts the first
+ * email address, reads skills/order-data/assets/orders.json (this state enables
+ * `order-data`) and matches the address against every record's `email`,
+ * case-insensitively.
+ *
+ * Advances to identify-case when it matches; otherwise to decline, with a reason
+ * naming what was missing. An unreadable order database throws, so the state
+ * fails through its on_error.
+ */
+import { defineCodeState } from "@archmax-ai/harness/sandbox";
+
+export default defineCodeState(async ({ tools }) => {
+  const { messages } = JSON.parse(await tools.archmax_get_history());
+  const orders = JSON.parse(await tools.read_file({ file_path: "skills/order-data/assets/orders.json" }));
+  const text = messages.find((m) => m.role === "user")?.text ?? "";
+  const email = text.match(/[\w.+-]+@[\w.-]+\.\w{2,}/)?.[0];
+  if (!email) return tools.archmax_advance({ to: "decline", reason: "The request names no email address." });
+  if (!orders.some((o) => o.email?.toLowerCase() === email.toLowerCase())) {
+    return tools.archmax_advance({ to: "decline", reason: `"${email}" is not in the order database.` });
+  }
+  await tools.archmax_advance({ to: "identify-case", reason: `${email} is a known requester.` });
+});
+```
+
+| Input | Meaning |
+| --- | --- |
+| `state` | the code state's own slug |
+| `trigger?` | the turn's trigger id string (its payload is in `variables`) |
+| `variables` | read-only `name → value` map incl. `trigger`; structured values whole; write with `tools.archmax_set_variables` |
+| `tools` | **exactly this state's surface**, async, by own name or camelCase (`tools.read_file`, `tools.readFile`): its grants (the workflow-wide grant included, minus `write_todos`, `archmax_eval`, `archmax_run`), the host's essential tools, and the controls `archmax_advance` (absent when terminal), `archmax_raise`, `archmax_get_variables`, `archmax_set_variables`, `archmax_get_history` — the same set a grader gets. Anything else is `undefined`; a call with no argument passes `{}` |
+
+**The session's history** is read, not passed in:
+`const { messages, trail } = JSON.parse(await tools.archmax_get_history())` — the
+same `SessionHistory` a grader reads, the session as it stood when the state was
+entered, whole and oldest first.
+
+| Field | Meaning |
+| --- | --- |
+| `messages` | the **whole** transcript, `{ role, text, toolCalls?, tool?, id?, note? }`; roles `user`/`assistant`/`tool`/`system`/`runtime` (a runtime note, `note` naming its kind; match `role === "runtime"`, never a `[bracket]`). An `assistant` entry lists the calls it made in `toolCalls` (`{ id?, name, args }`); the `tool` entry whose `id` matches carries the tool's name in `tool` and its result in `text` (`JSON.parse` it when the tool returns JSON) |
+| `trail` | the whole trail, `{ to, kind, reason?, workflow?, status?, ts }`; `kind` is `trigger`/`agent`/`human`/`grader`/`code`/`sub-workflow`/`reset`/`on_error` — count rounds here |
+
+| The script… | Effect |
+| --- | --- |
+| calls `tools.archmax_advance({ to, reason })` and finishes | the session moves; `reason` reaches the next state as a `[code]` runtime note and the trail as a `kind: code` step |
+| calls `tools.archmax_raise({ code, reason })` | the session ends `failed` with that code and reason |
+| finishes without either, in a terminal state | the session completes, held to the trigger's `returns` |
+| finishes without either, in a non-terminal state | **fails**: `code state '<slug>' finished without calling archmax_advance or archmax_raise` → `on_error` |
+| throws, times out (`settings.timeoutMs`), imports a foreign module, or its file is missing | fails → `on_error` (else the session ends rejected); a recorded advance is discarded, a raise still stands |
+
+A refused call **rejects** with governance's reason, and a `try`/`catch` can
+handle it: a blocked tool, an `archmax_advance` to an undeclared target, or one
+made while the state's `requires` are unmet. The first accepted advance or raise is
+the state's decision; a later one is refused. A write with `archmax_set_variables`
+is visible to the script's later calls, so it can set what `requires` names and
+then advance. Each run starts in a fresh REPL; `console.log` lines become
+`code-output` events. A file with no default export runs as a plain script, reading
+the same input from the global `args` and calling the global `tools`.
+
+**Governance is the state's own.** Every `tools.*` call is decided against the code
+state, exactly as the agent's calls are: grant what the script reads or calls in
+*that* state's `skills.allow` / `mounts.allow` / `tools.allow`; its `forbid`,
+`forbid_always` and the safety rules bind it. A code state is never offered
+`write_todos`, `archmax_eval`, `archmax_run`, `archmax_wait`, `archmax_reset` or
+`task`, even when the workflow's `tools.allow_always` lists one (naming one in its
+own `tools.allow` is a `validate` error). Neither script kind can read `workflows/**`.
+
+## `archmax_run` script contract
+
+`skills/<cap>/scripts/<x>.js`: plain script, top-level `await`, `tools.*`,
+`console.log`; the **last expression** is the tool result. Input is the global
+`args`: the arguments the model passed plus `args.variables` (read-only snapshot).
+No control tool and no `task` is on its `tools`. Fan-out shape:
+
+```js
+/** One sub-run per requested order, all in flight at once; returns [{ order_id, ...returns }]. */
+const orders = args.variables?.orders_to_enrich ?? [];
+await Promise.all(orders.map(async (o) => {
+  const answer = await tools.archmaxWorkflowEnrichOrder({ order_id: o.order_id });
+  return { order_id: o.order_id, ...JSON.parse(answer).returns };
+}));
+```
+
+The calling state must allow every tool the script calls (here
+`archmax_workflow_enrich-order`). A script's `tools` holds exactly the calling
+state's tools, re-scoped at every evaluation (so after an advance the same REPL
+holds the next state's); a tool the state does not offer is `undefined`, and a call
+the state's guards refuse rejects with governance's reason. The listing is
+camelCased, but a tool's own name reaches the same function
+(`tools["archmax_workflow_enrich-order"]`, `tools.read_file`).
+
+**Return into a variable.** A script's result reaches the model as one tool
+message and no further — it is not written to the variable store, and a script
+cannot write there itself. Return structured data and name the variable in the
+calling state's `requires:`; the model then records it with
+`archmax_set_variables`, which is what makes it survive the state, guard a
+`tools.allow` glob, and be quotable downstream as `${{name}}` instead of retyped.
+A result worth computing is worth naming.

package/skills/archmax-harness/references/diagnostics.md

@@ -16,12 +16,19 @@ message alone. Migrations for removed keys in full:
 | Workflow slug / state key not kebab-case, or empty | Rename the directory or key; update every `to`, `on_error`, `reachedState` |
 | transitions to / on_error routes to undefined state | Fix the slug or add the state |
 | no start state / multiple states declare trigger | Exactly one state per trigger id declares it under `triggers:` |
-| hook must be a `{ script }` or `{ rubric }` entry / single-key tagged object | One kind per hook; the only sidecar is `max_iterations`; `specification:` and `subagent:` do not exist |
-| hook script must be inside `hooks/` / not found | `before: { script: hooks/<x>.js }`, file at `workflows/<slug>/hooks/<x>.js` |
-| `before` declares `max_iterations` | Remove it; before hooks are ok/veto |
-| Human state must declare instructions / transitions / description; self-edge; hook can never run; two transitions of one type | Add them; route out of the state; drop the hook; one target per labelled type |
+| `Unrecognized key: "before"` / `"after"` (on a state) or `"extensions"` (at the root) | Hooks are removed — rewrite each as a state: a `before` check → a **code state in front** of the state (the trigger's entry, or the target of the edge into it); an `after` check → a **code state behind** it (the state's transition points at it, and it advances onward or back with the reason); a `rubric:` → a **grader state** behind it with an edge back. `max_iterations` has no successor: count rounds from the trail. Move `workflows/<slug>/hooks/*.js` to `scripts/` and rewrite them to the code-state contract. Delete `extensions` |
+| `Unrecognized key: "budget"` (at the root) | The root turn budget (`budget.maxModelCalls`) is removed: delete the key. A turn is bounded by LangGraph's `recursionLimit` (400 unless the host's invoke config sets one); bound a state with its own `budget.maxTurns` |
+| Code state declares no `script` | Add `script: scripts/<x>.js`, file at `workflows/<slug>/scripts/<x>.js` |
+| state declares `script`, which only a code state runs | Declare `type: code`, or drop the key |
+| `script` must be a workflow-relative path inside `scripts/` ending in .js or .mjs | `scripts/<x>.js` — no `hooks/`, no `skills/…` path, no `..` |
+| Code state `<s>` script not found / imports from `<x>` | Create the file under the workflow's `scripts/`; import only from `@archmax-ai/harness/*` |
+| Code state declares `instructions` / `model` / `budget` / `evidence` / `approvers` | Drop them: a code state makes no model call and cannot park. Say what the script does in its JSDoc and `summary`; `settings.timeoutMs` bounds it |
+| Grader state must declare `instructions` / at least one transition | Write the criteria in `instructions`; give it an edge onward and, to send work back, one to the graded state |
+| Grader state declares `evidence` / `approvers` / `budget.maxParks` | Drop them: a grader presents nothing to a person and cannot park |
+| `<type>` state is never offered `write_todos` / `archmax_eval` / `archmax_run` / `archmax_wait` / `archmax_reset` | Drop the entry from the state's `tools.allow`: a script calls tools directly, and an automated state cannot park or reset. The same tools in the workflow's `allow_always` are simply not offered there |
+| Human state must declare instructions / transitions / description; self-edge; two transitions of one type | Add them; route out of the state; one target per labelled type |
 | `'*'` is not a tool name a grant may use | Move the wildcard to `forbid`/`forbid_always` |
-| allows `task` — not grantable | Delete the entry; declare a `rubric:` hook instead |
+| allows `task` — not grantable | Delete the entry; grade with a grader state, delegate with `archmax_workflow_<slug>` |
 | allows `archmax_run` on `skills/<x>/…` which the state does not enable | Add `x` to the state's `skills.allow` (or `allow_always`), or drop the entry |
 | `forbid_always` denies `archmax_advance` | Remove it |
 | not a skill slug (path/glob given) | Use the bundle directory name; narrow paths with a `tools.allow` entry |
@@ -34,10 +41,12 @@ message alone. Migrations for removed keys in full:
 | state has several transitions but no `instructions` (warning) | Add routing guidance so the agent classifies the request before it advances |
 | `transitions.<i>.description` must be a non-empty string here: '<target>' declares none (error) | The edge is undescribed and its target has no `instructions` to route on. Add the condition under which the edge is taken (say *when*, not *where*), or give the target instructions |
 | `transitions.<i>.description` must be a non-empty string on a human state's transition (error) | It is the decision's button label: say what choosing it means |
+| `transitions.<i>.description` must be a non-empty string here: '<target>' is a grader / is a code state (error) | An edge into an automated state cannot route on its target: a grader's instructions are its criteria, never shown to the work it judges, and a code state has none. Say when the work is ready for the check (`The reply is drafted`). A code state's own edges may stay undescribed |
 | `transitions.<i>.description` must be a string (error) | Quote it, or omit it to route on the target's instructions |
 | trigger declares unknown key (warning) | Keys read: `session`, `message`, `connection`, `requires`, `returns`; others are preserved |
 | `maxConcurrency` above 1 | Set to 1 or remove |
 | `WORKFLOW.md` has frontmatter | Strip it; the machine is `workflow.yaml` |
+| `Unsupported runtime contract 'archmax-harness@1'` (or `@2`). Supported: `archmax-harness@3` | Contracts 1 and 2 (the hook contract) are retired: rewrite any hooks as states (above), then set `runtime: { engine: archmax-harness, version: "3" }` or drop the block (omitted resolves to `3`) |
 | case: missing/over-long `title`/`description`; unknown key; assertion before action; `expect:` block; malformed regex; unknown trigger; `from:` missing | Fix the field named; assertions are steps; regexes are `"/p/f"` strings |
 | `agent cannot read workflows/**` (instructions/evidence/workspace path) | Move the text to a skill bundle or the path to `scratchpad/` |
 
@@ -48,6 +57,30 @@ root `skills.allow`→`skills.allow_always`; state `type: wait`→`archmax_wait`
 `type: trigger`→`triggers:` on the entered state; `type: workflow`,
 `workflow:`, `params:`, `for_each:`, `result:`→an agent state allowing
 `archmax_workflow_<slug>` + `requires`; `parallel:`/`join:`→sequenced states;
-transition `on:`→nothing (the resumed state picks its edge); `subagent:` hook
-→`rubric:`; `max_corrections`→`max_iterations`; single-file `WORKFLOW.md` with
+transition `on:`→nothing (the resumed state picks its edge); state
+`before:`/`after:` (with `{ script }`, `{ rubric }`, `subagent:`, custom kinds,
+`max_iterations`/`max_corrections`)→code and grader states; root
+`extensions:`→nothing; root `budget: { maxModelCalls }`→nothing (the
+`recursionLimit` bounds a turn); single-file `WORKFLOW.md` with
 frontmatter→`workflow.yaml` + prose.
+
+## Reading a failed run
+
+`archmax test` and `archmax run` report an automated state's run in the state
+flow (stderr): `› code scripts/<x>.js` with each `console.log` line beneath it,
+`› grader grading`, and `✖ code failed <reason>` / `✖ grader failed <reason>` when
+the run failed. The raw events (`--verbose`, or `onEvent` in a host) are
+`code-start { state, script }`, `code-output { state, line }`,
+`code-result { state, status, durationMs, reason? }`, `grader-start { state }` and
+`grader-result { state, status, durationMs, reason? }`; a failure then shows as
+`state-error-routed` (its `on_error`) or a rejected session.
+
+| Reason says | Fix |
+| --- | --- |
+| `code state '<s>' finished without calling archmax_advance or archmax_raise` | Every path through a non-terminal state's script must advance or raise; returning a value does nothing |
+| `grader state '<s>' finished without calling …` | The grader answered in text: say in its `instructions` exactly when to take each transition and when to raise |
+| `grader state '<s>' exhausted its turn budget (maxTurns: N)` / `exceeded its time budget` | Raise `budget.maxTurns`/`timeoutMs` (reading the history and deciding is two calls), or narrow what it must read |
+| `archmax_advance rejected: cannot advance from '<s>' to '<t>'` / `cannot leave '<s>' yet: '<v>' is not set` | The script's `to` is not one of its state's transitions, or its `requires` are unmet — fix the target, or set the variable first |
+| `archmax_advance rejected: this state has decided` | A script or grader decided twice; only the first advance or raise counts |
+| a tool refused, or `tools.<x>` is `undefined`, inside a code state | Grant it on the **code state itself** (`tools.allow`, `skills.allow`, `mounts.allow`); another state's grant does not reach it |
+| `GraphRecursionError` / the session `failed` with `recursion-limit` | The turn hit LangGraph's `recursionLimit` (400 unless the host sets one): states cycle within one turn — automated states advancing to each other, or an agent looping between states. Add an edge out, or count rounds from the trail and give up; where one state loops on its own, bound it with `budget.maxTurns` + `on_error` |

package/skills/archmax-harness/references/wiring.md

@@ -12,13 +12,14 @@ const agent = await createAgent({
   workflow: "order-lookup",
   workspace: { rootDir, /* mounts?, sessionStore? */ },
   onEvent: (e) => { usage.handler(e); publish(e); },   // omit for the console subscriber
-  // model | modelFactory, tools, systemPrompt, middleware, backend, checkpointer,
-  // trigger, variables, promptCache, pricing, clock, hookExecutors …
+  // model | modelFactory (roles agent, judge, grader), tools, systemPrompt,
+  // middleware, backend, checkpointer, trigger, variables, promptCache, pricing,
+  // clock …
 });
 const sessionId = `run-${runId}`;
 const result = await agent.invoke(
   { messages: [{ role: "user", content: prompt }] },
-  { configurable: { thread_id: sessionId }, recursionLimit: 50 },
+  { configurable: { thread_id: sessionId } },   // recursionLimit: 400 unless you pass one
 );
 if (result.status === WORKFLOW_STATUSES.awaitingDecision) {
   // result.pendingDecision.transitions → show to a person, then:
@@ -81,13 +82,19 @@ agent.dispose(sessionId);
   `SessionSummary.exit` carries the same while the session is `failed`, and a
   later message is an ordinary new turn. `rejected` is governance ending it
   (`Outcome.rejected`, no `exit`). A host that read "not rejected" as success
-  must check `failed` too.
+  must check `failed` too. A turn that throws also ends the session `failed`,
+  with code `turn-error`, `turn-cancelled` or `recursion-limit` — LangGraph's
+  `recursionLimit` (400 unless the invoke config passes one) is the one bound on
+  a whole turn. `Outcome.reply` is every assistant text of the turn, in order.
 - **Events**: `onEvent` receives the one typed stream — `state-enter/leave`,
-  `advance`, `hook-verdict`, `parked/decided`, `raised` (the agent ended the
-  session failed: `state`, `code`, `reason`, `callId`), `tool-called/result/blocked`
-  (every governed call, `archmax_advance` included, grouped by `callId`),
-  `agent-text-delta`/`agent-text` (streaming by default, `messageId` groups
-  chunks), `model-usage` (provider counts per turn), `title-set`, warnings.
+  `advance`, `code-start/output/result` and `grader-start/result` (a code or
+  grader state's run; `status` `ok`/`error`, `reason` on a failure),
+  `parked/decided`, `raised` (the session ended failed: `state`, `code`,
+  `reason`, `callId`), `tool-called/result/blocked` (every governed call,
+  `archmax_advance` included, grouped by `callId`; a code state's carry
+  `origin: "script"`), `agent-text-delta`/`agent-text` (streaming by default,
+  `messageId` groups chunks; a grader's tokens never stream), `model-usage`
+  (provider counts per call, a grader's under its state), `title-set`, warnings.
   There is no run-end event; `invoke` returning is the end. Metrics are a
   fold over this stream; only cost is checkpointed (`sessions.get(id).usage`).
 - **Artifacts** per session under `sessions/<id>/artifacts/`: `graph.json`/`.mmd`,
@@ -98,7 +105,9 @@ agent.dispose(sessionId);
   target or a case with `mocks:` is refused before running.
 - **Model/caching**: `ARCHMAX_API_BASE_URL`, `ARCHMAX_API_KEY`, `ARCHMAX_MODEL`
   (+ `ARCHMAX_TEMPERATURE`, `ARCHMAX_MAX_TOKENS`, `ARCHMAX_STREAMING`) for any
-  OpenAI-compatible endpoint, or pass `model`. Prompt prefix is cache-marked
+  OpenAI-compatible endpoint, or pass `model`. A `modelFactory(role, env, id)`
+  serves each role its own model: `agent`, `judge` (case `grade:`), `grader`
+  (a grader state, asked for the state's `model` id). Prompt prefix is cache-marked
   by default (`promptCache: { enabled, ttl: "5m" | "1h" }`); watch
   `cacheReadTokens`. Pricing via `pricing: { "<model-substring>": { input, output, cacheRead, cacheWrite } }`
   or `ARCHMAX_PRICE_*`; without it report tokens, never a guessed cost. A keyed