@archmax-ai/harness 0.0.0

package/dist/authoring-skill/archmax-harness/references/workflow-yaml.md

@@ -0,0 +1,241 @@
+# `workflow.yaml` — keys, machine rules, governance
+
+Load this when writing or editing a `workflow.yaml`. Field-level detail and
+precedence edge cases: [`workflow-schema.md`](workflow-schema.md).
+
+## Every key
+
+The schema is strict: an unknown key anywhere is a load error naming it. This
+skeleton is the complete vocabulary; omit what you do not need.
+
+```yaml
+title: Triage example            # label only; identity is the directory slug
+instructions: |-                 # standing direction for the whole run (warning if absent)
+  Records live in skills/order-data/assets/orders.json; write artifacts under scratchpad/.
+
+  Answer only from records you have read; never fabricate.
+runtime: { engine: archmax-harness, version: "2" }
+disabled: false                  # true = out of service: no new turns; parked runs still drain
+settings:                        # sandbox limits: timeoutMs, memoryLimitBytes, maxPtcCalls,
+  timeoutMs: 15000               #   maxResultChars, prompt_cache: { enabled, ttl }
+  model: gpt-5-mini              # MODEL ID ONLY — every state runs on it; overrides ARCHMAX_MODEL
+tests:                           # case suite config (no tests.config.js exists)
+  maxConcurrency: 1              # only 1 accepted
+  caseTimeoutMs: 120000          # per-case wall clock, distinct from settings.timeoutMs
+  judge: {}                      # required for grade:; {} = env default model, or { model, modelOptions }
+metadata: { canvas: {} }         # host data, never read; accepted at root, state, rubric — leave as found
+extensions: { hooks: [] }        # host-registered hook kinds; rarely authored
+
+tools:                           # tool governance, workflow level
+  allow_always: []               #   granted in EVERY state; a state's allow adds to it
+  forbid_always: [archmax_reset]  #   denied in EVERY state; beats every grant; "*" = every tool
+skills:                          # skill governance, workflow level — SLUGS, never paths
+  allow_always: [order-data]     #   enabled in every state; [] = every capability is state-specific
+  forbid_always: []              #   out of reach everywhere
+
+states:
+  triage:                        # key = slug = identity (^[a-z0-9]+(-[a-z0-9]+)*$)
+    type: agent                  # agent (default) | human
+    title: Triage request        # label for people/hosts; reaches no model call
+    summary: Record the refund decision for review.   # ditto: an authoring/host label, NOT in the prompt
+    triggers:                    # a trigger is declared on the state it ENTERS; key = id
+      manual:                    #   CLI / caller / host entry; the prompt is its input
+      email_reply:               #   any other id = host event; the payload arrives as locked variables
+        session: conversation_id #   dotted path over variables: which conversation a firing joins
+        message: false           #   or a dotted path to the message text; false = firings carry none
+        connection: mail         #   host access connection; other keys preserved with a warning
+        requires: [order_id]     #   variables a firing must supply (a caller's required params)
+        returns: [result_file]   #   variables the run guarantees on completion (a caller's result)
+    instructions: >-
+      Record the decision in scratchpad/refund.json, then archmax_advance to
+      review; never close the case yourself.
+    before:                      # gates entry: ok/veto only; a veto here rejects the run
+      - script: hooks/check-requester.js
+    after:                       # gates the archmax_advance out (or completion, when terminal)
+      - script: hooks/check-policy.js
+        max_iterations: 2        #   how many `correct`s before a hard veto (per hook; default 0)
+      - rubric:                  #   LLM grader, inline; the agent never sees it
+          instructions: |-       #   the only required key: criteria + verdict (ok/correct/veto + reason)
+            Judge the tone of the last assistant message …
+          max_iterations: 1
+          model: gpt-4.1-mini    #   optional override
+    tools:
+      allow:                     # adds to allow_always; entry = name | { tool, args: {<arg>: [globs]} } | { tool, paths }
+        - lookup_customer
+        - { tool: archmax_run, paths: ["skills/refund-policy/scripts/**"] }   # narrows an always-on tool, within an enabled skill
+        - { tool: write_file, args: { file_path: ["reports/${{case_id}}/*.json"] } }  # variable-bound guard
+        - archmax_workflow_enrich-order                                     # runs a sibling workflow
+      forbid: [archmax_wait]      # denies here; beats every grant incl. the always-on surface
+    skills:
+      allow: [refund-policy]     # adds to allow_always (bundle readable + scripts runnable, no path entries)
+      forbid: [order-data]       # subtracts, even from allow_always ([] never denies)
+    requires: [case_id]          # variables that must be set before this state may be left
+    model: claude-opus-5         # MODEL ID ONLY — this state's turns; beats settings.model
+    budget: { maxTurns: 12, timeoutMs: 60000, maxParks: 5 }   # bounds the state's segment
+    on_error: closed             # where a terminal failure of this segment routes
+    metadata: { x: 40, y: 180 }
+    transitions:                 # none => terminal state
+      - to: review               # slug; must exist
+        description: The decision is recorded and needs a person's approval.   # REQUIRED, non-empty:
+                                 #   the ONLY thing the agent knows about this edge (on a human
+                                 #   state, also the button label). Say WHEN, never where.
+        type: none               # approve | reject | refine | none — semantic on human states
+
+  review:                        # human state: parks with a decision record; a PERSON picks the edge
+    type: human
+    title: Review refund
+    summary: A person approves the recorded decision or sends it back.   # label only
+    instructions: >-             # required on human states: the decision to present
+      Confirm scratchpad/refund.json matches policy.
+    approvers: [finance@acme.com]
+    evidence: [scratchpad/refund.json]   # plus whatever archmax_advance attached via `evidence:`
+    transitions:                 # required; no self-edge; one target per labeled type
+      - { to: closed, type: approve, description: Approve and close. }
+      - { to: triage, type: refine, description: Send back with a comment. }
+
+  closed:                        # bare key = terminal state with no declarations
+```
+
+## Machine rules
+
+- **Movement.** The agent moves only by `archmax_advance({ to, reason, evidence? })`
+  — one per message, edge validated, then the leaving state's `after` hooks,
+  the target's `before` hooks, then the target's tools unlock. A state with no
+  transitions is terminal; the run ends when the agent finishes there. Human
+  decisions and `on_error` are the other two movers. `archmax_reset({ reason })`
+  returns to the entry state (forbid it via `forbid_always` when a run must
+  never restart). No fan-out: sequence states; concurrency lives in
+  sub-workflow calls.
+- **Entry.** At least one state declares `triggers`; one state per trigger id;
+  `manual` is the entry the CLI, a host firing and a caller all use. A
+  re-invoked finished session is a **new turn in the state it ended in**, not
+  at the entry — give a state re-entry transitions if a conversation must move
+  on, or park instead of finishing.
+- **Variables.** One flat checkpointed `name → value` store, never declared.
+  Host seeds (`--variables`, `createAgent({ variables })`, a delivery) are
+  **locked**; the agent uses `archmax_get_variables`/`archmax_set_variables`
+  (`lock: true` to freeze). Reserved: `trigger` (current trigger id, always
+  locked) and `title` (the run's one-line task label, agent-owned). A
+  `${{name}}` / `${{a.b.-1.c}}` reference works in `tools.allow` globs
+  (guard) and inside any text tool argument the model writes (exact
+  substitution, no retyping) — but not in scripts, which read
+  `args.variables`. Name a guarded variable in an earlier state's `requires`
+  or seed it; an unresolvable guard reference fails the run, an unresolvable
+  argument reference is refused and retried. An `archmax_set_variables` typo
+  creates a new variable; `requires` is what surfaces it.
+- **Models.** `settings.model` names the id every state runs on and a state's
+  `model` names its own — an **id only**, over the endpoint the assembly is
+  already configured with (a block with `temperature` is a load error;
+  sampling is env/host configuration). Precedence: state → workflow →
+  `ARCHMAX_MODEL`. Author it where the work differs in kind: small models for
+  classification, extraction and other mechanical states; leave drafting,
+  judgement and any state with a big tool surface or several transitions on
+  the default, since a small model that routes badly costs more in retries
+  than it saves. Repeating the workflow's id on a state is a validate warning.
+  A rubric keeps its own `model`, a sub-workflow uses its own spec's, and a
+  host that passes an explicit `model` instance to `createAgent` outranks
+  every declared id (it must pass `modelFactory` to honour them).
+- **Parking.** A state that needs an event or a time calls
+  `archmax_wait({ reason, until? })` (`until`: `30m`/`2h`/`1d` or ISO instant →
+  `resumeAt` for the host's scheduler; the runtime holds no timer). Any
+  delivered trigger resumes **that same state** with the payload as locked
+  variables and an `[event]` runtime note; the state then picks its own edge.
+  Bound a polling loop with `budget.maxParks` + `on_error`. `archmax_wait` is
+  in every state, terminal ones included. Use a **human state** when a person
+  picks the edge, `archmax_wait` when an event or time resumes the work.
+- **Human states** park with a record built from `instructions`, `evidence`
+  and transition `type`s. The handoff spends one reply-only model call so the
+  park carries a message — do **not** instruct the agent to announce the
+  handoff (two messages). While parked, `archmax reply` is answered on a
+  tool-free turn and re-parks unchanged; only `decide` moves the run. A
+  `refine` edge delivers the reviewer's comment as correction.
+- **Hooks.** `before`: ok/veto (veto rejects entry; on a start state, the
+  run; routed through `on_error` if declared). `after`: ok/correct/veto on
+  the outgoing advance or on completion of a terminal state; `correct` sends
+  the agent back with the reason, bounded per hook by `max_iterations`
+  (default 0 → a correct is a hard veto). A list runs in order and stops at
+  the first non-ok. Errors and missing files veto (fail-closed). Hooks run
+  on runtime authority: the state's `allow`/`forbid`/`skills` do not bind
+  them; `forbid_always` and safety rules do. Human states may not declare
+  hooks.
+- **Budgets and `on_error`.** `budget.maxTurns`/`timeoutMs`/`maxParks` bound
+  a state's segment. A terminal failure (hook execution error, exhausted
+  corrections, exhausted budget, exhausted parks) routes to `on_error`
+  instead of failing the run; recoverable rejections (invalid edge, veto,
+  in-budget correct) keep the agent in place. Declare `on_error` on states
+  with strict `after` hooks or bounded loops.
+- **Sub-workflows are tools.** Allow `archmax_workflow_<slug>` (slug verbatim)
+  and the sibling `workflows/<slug>/` is callable: its `manual` trigger's
+  `requires` are the parameters, its `returns` the result
+  (`{ message, returns }`). Nothing captures the result — the caller records
+  what it needs with `archmax_set_variables`, made mandatory by `requires`.
+  The child is a separate session with a fresh transcript, sees only its
+  arguments (as locked variables), and shares no prose. One call = one
+  sub-run; fan out with parallel tool calls or `Promise.all` in a script
+  (bounds: depth 3, 4 concurrent). A child's human state parks the child;
+  a script's delegation cannot park and fails closed.
+- **Choosing a mechanism.** Deterministic work with no model → an `archmax_run`
+  script. Delegated work that is itself a process or reused across workflows
+  → a sub-workflow. Judging work already done → a rubric hook (never
+  callable by the agent; `task` is disclosed nowhere and not grantable).
+- **Prompt economy.** The static prompt + tool schemas are re-sent every
+  model call. The static part carries the workflow's `title` + `instructions`
+  and **no state of the graph**; a state's `instructions` and its **own**
+  outgoing edges are sent only while it is active. So: workflow-wide
+  conventions go in the root `instructions` (paid once, cached); everything
+  else goes in the state that needs it, and splitting a broad state into
+  several narrow ones costs nothing in the prefix. `title` and `summary` are
+  free — neither reaches a model call. `WORKFLOW.md` carries only what the spec
+  cannot say; reader diagrams go inside an HTML comment (stripped from the
+  prompt).
+
+## What the agent sees of the graph
+
+Only the state it is in. Every model call is handed that state's outgoing edges
+and nothing else of the machine — no other state's slug, `title`, `summary`,
+hooks or transitions, and no count of the states:
+
+```
+Transitions — choose one with `archmax_advance` when this state's work is done:
+- to `review` (human decision node) — The decision is recorded and needs a person's approval.
+- to `closed` (terminal) — Nothing to refund; the case is answered.
+```
+
+Two rules follow, and they are the ones authors get wrong:
+
+1. **Write the `description` for the source state, not the target.** The agent
+   reading it knows nothing about where it is going. Say *when* the edge applies:
+   `The refund is over $50, or the customer has asked twice.` Not `Go to
+   refund-review.` — that tells a reader who already knows the graph something
+   they cannot use, and tells this reader nothing.
+2. **Routing conditions cannot live downstream.** A target's `summary` or
+   `instructions` is never disclosed to the state routing into it. If the
+   condition is "when the order is over 30 days old", it belongs on the edge.
+
+A missing or blank `description` is a **load error**. There is no fallback, and
+no way to see more of the graph.
+
+## Governance
+
+Closed by default; **deny beats allow, and no narrower level widens a denial.**
+
+- **Always on, never declared**: `ls`, `read_file`, `write_file`,
+  `edit_file`, `glob`, `grep`, `write_todos`, `archmax_eval`, `archmax_run`,
+  and the controls `archmax_advance`, `archmax_reset`, `archmax_wait`,
+  `archmax_get_variables`, `archmax_set_variables`. Any other tool needs an
+  `allow`/`allow_always` entry. An entry naming an always-on tool **narrows**
+  it. `task` is ungrantable (error).
+- **Entries**: bare name; `{ tool, args: { <arg>: ["glob", …] } }` (matches
+  if any glob matches; `${{var}}` allowed); `{ tool, paths: [...] }`
+  (shorthand for `args.file_path`). `"*"` as the tool is legal only in a
+  forbid list. Globs match dot-segments (`secrets/**` covers `secrets/.env`).
+- **Skills** are governed by **slug**, never path. Enabling a bundle makes
+  `skills/<slug>/**` readable and its scripts runnable with no `tools.allow`
+  entry; a disabled bundle is unreachable **and invisible** (not listed, not
+  in the prompt). `allow` adds, `forbid` subtracts, `allow: []` denies
+  nothing. A `tools.allow` entry may still narrow *within* an enabled bundle.
+  A state enabling no skill can run no script at all.
+- **Scripts' `tools.*` calls** are governed per call: an `archmax_run` script
+  is bound like the model (grant every tool it calls); a hook is exempt from
+  the state's lists. Neither may read `workflows/**` or write a mount. A
+  refused call throws inside the script.

package/dist/behaviour/support.d.ts

@@ -0,0 +1,232 @@
+import type { BaseMessage } from "@langchain/core/messages";
+import { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import type { BaseChatModelCallOptions } from "@langchain/core/language_models/chat_models";
+import type { ChatResult } from "@langchain/core/outputs";
+import { type Agent, type CreateAgentParams, type GovernedAgent, type SessionStore, type WorkflowLifecycleEvent } from "../index.js";
+/** Token usage a scripted reply may report, so `model-usage` events are testable. */
+export interface ScriptedUsage {
+    input: number;
+    output: number;
+}
+/**
+ * The model id a scripted response echoes back in `response_metadata`. Omitted,
+ * the response names no model — which is the ordinary case behind an
+ * OpenAI-compatible proxy, and the one that used to cost a call its price.
+ */
+export type ScriptedModelName = string;
+/** One scripted model turn. */
+export type ScriptedTurn = 
+/** A single tool call. */
+{
+    tool: string;
+    args: Record<string, unknown>;
+    usage?: ScriptedUsage;
+    reports?: ScriptedModelName;
+}
+/** Several tool calls issued in one assistant message (a tool batch). */
+ | {
+    batch: Array<{
+        tool: string;
+        args: Record<string, unknown>;
+    }>;
+    usage?: ScriptedUsage;
+    reports?: ScriptedModelName;
+}
+/** A final text reply, ending the turn. */
+ | {
+    reply: string;
+    usage?: ScriptedUsage;
+    reports?: ScriptedModelName;
+};
+/** A tool call the scripted model issued, as recorded. */
+export interface IssuedCall {
+    name: string;
+    args: Record<string, unknown>;
+}
+/** One model invocation as the fake observed it. */
+export interface ModelCall {
+    /** Tool names bound for this call (from the most recent `bindTools`). */
+    tools: string[];
+    /** The system prompt text, when one was present. */
+    systemPrompt: string;
+    /** Kinds of the messages the model was shown (`system`, `human`, `ai`, `tool`). */
+    messageTypes: string[];
+}
+/**
+ * A model that replays a fixed script of turns. `bindTools` returns the same
+ * instance so the cursor is shared across every binding the agent performs —
+ * the script is the run's plan, not one binding's. When the script runs out the
+ * model replies with a final `done`, so every turn terminates.
+ */
+export declare class ScriptedModel extends BaseChatModel<BaseChatModelCallOptions> {
+    private readonly turns;
+    private cursor;
+    private lastBound;
+    private seq;
+    /** Tool calls the script actually issued, in order. */
+    readonly issued: IssuedCall[];
+    /** Every model invocation, in order. */
+    readonly calls: ModelCall[];
+    /** What to say when the script is exhausted. */
+    readonly fallbackReply: string;
+    /**
+     * The id this model was configured to run, as a real client exposes it — what
+     * `modelIdOf` reads and what the runtime prices against when a response names
+     * no model. Left undefined by default so an existing case is unchanged.
+     */
+    readonly model?: string;
+    constructor(turns: ScriptedTurn[], opts?: {
+        fallbackReply?: string;
+        name?: string;
+        model?: string;
+    });
+    _llmType(): string;
+    /** How many scripted turns are still unplayed. */
+    get remaining(): number;
+    /** Append turns to the script — for a later conversational turn on the same agent. */
+    enqueue(...turns: ScriptedTurn[]): void;
+    bindTools(tools: unknown[]): BaseChatModel;
+    _generate(messages: BaseMessage[]): Promise<ChatResult>;
+}
+/**
+ * Write an authored workspace into a fresh temp directory. Values are file
+ * contents; a non-string value is serialized as YAML (handy for `workflow.yaml`
+ * declared as an object). Returns the root path.
+ */
+export declare function makeWorkspace(files: Record<string, string | object>): string;
+/** Remove every workspace {@link makeWorkspace} created. Call from `afterEach`. */
+export declare function cleanupWorkspaces(): void;
+/** A `SKILL.md` body with the frontmatter the skill loader requires. */
+export declare function skillMarkdown(name: string, description?: string): string;
+/**
+ * One inline rubric, as the value of a `{ rubric: … }` hook. A rubric is
+ * declared on the hook that applies it, so a fixture builds the declaration and
+ * drops it straight into a state's `before`/`after`.
+ */
+export declare function rubricDeclaration(opts?: {
+    maxIterations?: number;
+    model?: string;
+    instructions?: string;
+    metadata?: unknown;
+}): Record<string, unknown>;
+/** The default persona file every workspace here carries. */
+export declare const AGENTS_MD = "# Agent\n\nDo what the workflow says.\n";
+export interface AssembleOptions {
+    /** Workflow slug; defaults to `w`. */
+    workflow?: string;
+    /** The agent model's script. Ignored when `model` is supplied. */
+    turns?: ScriptedTurn[];
+    /** A prebuilt model (e.g. to share across two assemblies). */
+    model?: ScriptedModel;
+    /** A second scripted model for the `rubric` role (grading rubrics). */
+    rubricModel?: ScriptedModel | JudgeModel;
+    /**
+     * Supplies the model per role and requested id, for a workflow that declares
+     * models. Supplied, it replaces the explicit `model` — which would outrank
+     * every declared id — so the ids the spec names actually resolve.
+     */
+    modelFactory?: CreateAgentParams["modelFactory"];
+    /** The session store; defaults to a fresh memory store. */
+    store?: SessionStore;
+    /** Extra `createAgent` parameters merged in last. */
+    params?: Partial<CreateAgentParams>;
+}
+export interface Assembled {
+    agent: GovernedAgent;
+    model: ScriptedModel;
+    events: WorkflowLifecycleEvent[];
+    store: SessionStore;
+    root: string;
+}
+/** Assemble a governed agent over `root` with an event sink and memory storage. */
+export declare function assemble(root: string, opts?: AssembleOptions): Promise<Assembled>;
+export interface TurnOutcome {
+    /** The settled turn result's message list. */
+    messages: unknown[];
+    /** The last assistant message carrying text, as a person would read it. */
+    reply: string;
+}
+/** Drive one conversational turn on `sessionId`. */
+export declare function turn(agent: Agent, sessionId: string, text: string, opts?: {
+    trigger?: {
+        id: string;
+    };
+}): Promise<TurnOutcome>;
+/** The final assistant message carrying text, skipping tool results. */
+export declare function lastAgentText(messages: unknown[]): string;
+/** The type of a message (`ai`, `human`, `tool`, `system`), read across shapes. */
+export declare function messageType(message: unknown): string;
+/** Tool results in a transcript: `{ name, content, status }`. */
+export declare function toolResults(messages: unknown[]): Array<{
+    name: string;
+    content: string;
+    status?: string;
+}>;
+/** Events of one type, narrowed. */
+export declare function eventsOf<T extends WorkflowLifecycleEvent["type"]>(events: WorkflowLifecycleEvent[], type: T): Array<Extract<WorkflowLifecycleEvent, {
+    type: T;
+}>>;
+/** The states entered, in order. */
+export declare function statesEntered(events: WorkflowLifecycleEvent[]): string[];
+/** The agent-driven transitions (`from -> to`), in order — the opening arrival excluded. */
+export declare function advances(events: WorkflowLifecycleEvent[]): Array<{
+    from: string;
+    to: string;
+    reason?: string;
+}>;
+/** Names of the tools governance refused, in order. */
+export declare function blockedTools(events: WorkflowLifecycleEvent[]): string[];
+/** Events emitted for one session only. */
+export declare function forSession(events: WorkflowLifecycleEvent[], sessionId: string): WorkflowLifecycleEvent[];
+/**
+ * A two-state linear machine: `start` (manual) → `done` (terminal), with the
+ * runtime contract pinned. Extra keys are merged into the spec root.
+ */
+export declare function linearSpec(extra?: Record<string, unknown>): Record<string, unknown>;
+/** The scripted turn that advances `to` with a reason. */
+export declare function advanceTo(to: string, reason?: string): ScriptedTurn;
+/** A workspace with a persona and one workflow spec under `workflows/w/`. */
+export declare function workspaceWith(spec: Record<string, unknown>, extraFiles?: Record<string, string | object>): string;
+/** A lifecycle judge's answer. */
+export interface JudgeVerdict {
+    verdict: "ok" | "correct" | "veto";
+    reason: string;
+}
+/**
+ * A fake model for the `rubric` role that answers each dispatch with the next
+ * scripted verdict. When the framework binds a structured-output tool
+ * (`extract-*`) it is called with the verdict; otherwise the verdict is the reply
+ * text as JSON — both reach the lifecycle runner as a parseable verdict.
+ */
+export declare class JudgeModel extends BaseChatModel<BaseChatModelCallOptions> {
+    private readonly verdicts;
+    private readonly fallback;
+    /**
+     * Fail every dispatch instead of answering — how an unusable `model` id
+     * surfaces, since a bad id is refused at invocation, not construction.
+     */
+    private readonly failWith?;
+    private cursor;
+    private lastBound;
+    private seq;
+    /** How many times the judge was asked. */
+    get dispatches(): number;
+    private calls;
+    constructor(verdicts: JudgeVerdict[], fallback?: JudgeVerdict, 
+    /**
+     * Fail every dispatch instead of answering — how an unusable `model` id
+     * surfaces, since a bad id is refused at invocation, not construction.
+     */
+    failWith?: string | undefined);
+    _llmType(): string;
+    bindTools(tools: unknown[]): BaseChatModel;
+    _generate(): Promise<ChatResult>;
+}
+/** Read one file from a session store by store-relative path, or `undefined`. */
+export declare function storeFile(store: SessionStore, path: string): Promise<string | undefined>;
+/**
+ * A session id no other test in this process has used. Sandbox REPL sessions
+ * and other per-session resources are keyed by session id for the life of the
+ * process, so tests that run hooks or scripts must not share one.
+ */
+export declare function freshSessionId(prefix?: string): string;