@archmax-ai/harness 0.1.0 → 0.2.1

package/skills/archmax-harness/references/hooks-and-scripts.md

@@ -0,0 +1,82 @@
+# Hook scripts and `archmax_run` scripts — contracts
+
+Load this when writing a `workflows/<slug>/hooks/*.js` gate or a
+`skills/<cap>/scripts/*.js` source. Worked examples and the sandbox details:
+[`hook-and-test-scripts.md`](hook-and-test-scripts.md) Part 1.
+
+## Hook script contract
+
+Default-export function; its return value is the verdict. Verdict helpers are
+globals (typed import optional: `import { ok, veto, correct } from "@archmax-ai/harness/sandbox";`,
+placed below the JSDoc; no other import is allowed).
+
+```js
+/**
+ * Requester gate — the request must name a requester the order records know.
+ *
+ * Reads the first user message, extracts the first email address, loads
+ * skills/order-data/assets/orders.json through the bridge and matches the
+ * address against every record's `email`, case-insensitively.
+ *
+ * Vetoes when the file cannot be parsed, no address is present, or none
+ * matches — each with the reason. Otherwise ok.
+ */
+export default async function hook({ state, phase, trigger, variables, messages, tools, from, to, reason }) {
+  let orders;
+  try { orders = JSON.parse(await tools.readFile({ file_path: "skills/order-data/assets/orders.json" })); }
+  catch { return veto("Could not load 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 veto("Include your email address so we can look up your account.");
+  if (!orders.some((o) => o.email?.toLowerCase() === email.toLowerCase())) return veto(`"${email}" is not in the order database.`);
+  return ok();
+}
+```
+
+| Input | Meaning |
+| --- | --- |
+| `state`, `phase` | state slug; `"before"` or `"after"` |
+| `trigger` | trigger id string (payload is in `variables`) |
+| `variables` | read-only `name → value` map incl. `trigger`; structured values whole |
+| `messages` | last 24 messages, newest last, `{ role, text, toolCalls? }`; roles `user`/`assistant`/`tool`/`system`/`runtime` (a runtime note; match `role === "runtime"`, never a `[bracket]`) |
+| `from`, `to`, `reason` | `after` only: the attempted transition and the agent's reason |
+| `tools` | async camelCased bridge: `tools.readFile`, `tools.writeFile`, `tools.archmaxWorkflowEnrichOrder(...)`; no variable tools, no `task` |
+
+| Return | Effect |
+| --- | --- |
+| `ok()`, nothing, `true`/number/string | proceed |
+| `veto(reason)` | block; the reason is shown to the agent — make it actionable |
+| `correct(reason)` | `after` only: retry with the reason, within `max_iterations` |
+| `false` | veto ("precondition not met") |
+| any other object, a throw | veto with keys/error named — never silently ok |
+
+`console.log` goes to the trail. A file with no default export uses its
+completion value as the verdict. Parse inputs defensively; turn a failure that
+should not block into an explicit `ok()`.
+
+## `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 `archmax_advance`, `archmax_set_variables` or `task`. 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`).
+
+**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/wiring.md

@@ -0,0 +1,101 @@
+# Wiring the runtime into a backend — the short form
+
+Load this when embedding `@archmax-ai/harness` in a service. Every option shape, the
+event catalogue and recipes: [`backend-integration.md`](backend-integration.md).
+
+
+```ts
+import { createAgent, WORKFLOW_STATUSES, createUsageTracker } from "@archmax-ai/harness";
+
+const usage = createUsageTracker();
+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, hookExecutors …
+});
+const sessionId = `run-${runId}`;
+const result = await agent.invoke(
+  { messages: [{ role: "user", content: prompt }] },
+  { configurable: { thread_id: sessionId }, recursionLimit: 50 },
+);
+if (result.status === WORKFLOW_STATUSES.awaitingDecision) {
+  // result.pendingDecision.transitions → show to a person, then:
+  // await agent.workflow.decide(sessionId, { target, comment });
+}
+usage.totals(sessionId);       // tokens (+ costUsd only when pricing is configured)
+agent.dispose(sessionId);
+```
+
+- **Install**: `npm i @archmax-ai/harness`; pre-publish, `npm pack` and install the
+  tarball (a real copy, not a symlink). This skill ships in the package at
+  `BUNDLED_AUTHORING_SKILL_DIR` (`<dir>/archmax-harness/SKILL.md`).
+- **Mounts**: `workspace.mounts` is a route table — key → backend, or
+  `{ backend, readOnly, governed }`. Mark a mount `governed: true` to hand the
+  spec's `mounts` block the decision of which **states** reach it (closed by
+  default, like a skill bundle) and whether each may write there; a mount not so
+  declared is visible in every state, so an existing table behaves unchanged.
+  `readOnly` is a ceiling the spec cannot lift.
+
+  ```ts
+  workspace: {
+    rootDir,
+    mounts: {
+      ...defaultMounts(rootDir),                                  // skills/, .platform/, AGENTS.md
+      "/reference/": { backend: mountSubtree(store, "reference"), governed: true },
+      "/shared/": { backend: mountSubtree(store, "shared"), readOnly: false, governed: true },
+    },
+  },
+  ```
+
+  Then in `workflow.yaml`: `mounts: { allow_always: [reference] }`, a state's
+  `mounts: { allow: [{ mount: shared, access: read }] }`, and
+  `mounts.forbid_always` for what no state (or child session) may reach. Pass the
+  same table to `validateWorkflow({ mounts })` so `archmax validate` checks the
+  spec's names against the wiring.
+- **Storage**: default filesystem store at `<root>/sessions`; else
+  `createFilesystemSessionStore({ dir })`, `createBackendSessionStore({ backend, prefix? })`,
+  `createMemorySessionStore()`. A custom `backend` without `sessionStore`
+  throws `SessionStoreRequiredError`. Delete sessions via `agent.sessions.delete(id)`.
+- **Agent**: Deep Agents' `invoke`/`stream`/`streamEvents` + checkpoint
+  surface; `sessions.list/get/delete`; `emitRunArtifacts`; `dispose`.
+  Governance under `agent.workflow`: `machine`, `resolveTrigger`,
+  `send(sessionId, input)` → one `Outcome` (`decide`/`reply`/`deliver` are
+  conveniences), `resolveSession`.
+- **Multi-turn**: re-invoke the same `thread_id` with only the new message;
+  never concatenate a conversation into one string. A spec edit is adopted,
+  not refused: the next turn runs under the current `workflow.yaml` (the
+  recorded `specHash` says which version each turn ran under), and a state
+  the edit removed reopens at the entry state.
+- **Human-in-the-loop**: `status === "awaiting_decision"` →
+  `pendingDecision.transitions` → `decide`. `reply(sessionId, text)`
+  answers a message without moving the run. An `archmax_wait` park is
+  `awaiting_input` → `deliver(sessionId, { trigger, variables, message? })` — the
+  person's message travels with the firing; a park with `resumeAt` is the host
+  scheduler's cue. A delegated child's park is named on `Outcome.delegation`.
+- **Events**: `onEvent` receives the one typed stream — `state-enter/leave`,
+  `advance`, `hook-verdict`, `parked/decided`, `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.
+  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`,
+  `trajectory.json`, `trail.json`, `variables.json`, `metadata.json` (incl.
+  usage); the agent's files under `scratchpad/`.
+- **Cases against your agent**: `runTests({ workflow, rootDir, createTarget?, sessionIdForCase? })`
+  from `@archmax-ai/harness/testing`; wire `createToolMockMiddleware()` into your
+  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
+  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
+  table works behind a proxy that echoes no model back — the id falls back to the
+  one the runtime was configured to run. Cached tokens are charged once, at the
+  cache rate, not at the input rate as well.
+
+Typical split: worker = `createAgent` + `invoke` + `decide`/`deliver`; API =
+artifacts + event subscription; frontend = graph + trajectory + live stream.