@archmax-ai/harness 0.7.1 → 0.9.0

package/skills/archmax-harness/references/workflow-schema.md

@@ -80,8 +80,8 @@ instructions?: string         # the workflow's STANDING instructions — free-fo
                               # simply ignored; use `instructions:`, rereading the
                               # text as direction, not narration.
                               # A test case's `description` is UNAFFECTED. A
-                              # TRANSITION's `description` is now REQUIRED and
-                              # non-empty (see `transitions` below).
+                              # TRANSITION's `description` is what the agent routes
+                              # on (see `transitions` below).
 
 disabled?: boolean            # `true` = this machine STARTS NO NEW TURNS. Bounds
                               # STARTING, not finishing.
@@ -115,6 +115,17 @@ runtime?:
   engine?: string             # "archmax-harness"
   version?: string | number   # target contract — use "2"
 
+budget?:
+  maxModelCalls?: number      # default 50 — model calls ONE TURN may make across EVERY
+                              # state (a turn = one message, decision, reply or delivery;
+                              # each counts from zero). A state's maxTurns restarts on
+                              # every entry, so only this ends an agent cycling between
+                              # states. Exhaustion routes once through the current
+                              # state's on_error, else the turn ends rejected; the agent
+                              # is warned once a fifth is left. The step limit follows
+                              # it. RAISE it for turns that legitimately run long (a long
+                              # state chain, a self-driven review cycle).
+
 settings?:
   model?: string              # MODEL ID ONLY — the id every state of this workflow runs
                               # on, over the endpoint/credentials the assembly already
@@ -146,7 +157,13 @@ tests?:                       # cases suite config (declarative data;
                               #      factory's `judge` role; other keys are errors
 
 tools?:
-  allow_always?: AllowEntry[] # grants added to every state's allowlist
+  allow_always?: AllowEntry[] # the WORKFLOW-WIDE GRANT, in every state. ABSENT = the
+                              #      default tools (ls, read_file, write_file, edit_file,
+                              #      glob, grep, copy_file, move_file, remove_file,
+                              #      write_todos, archmax_eval, archmax_run). DECLARED
+                              #      ([] included) = exactly what it lists: it REPLACES
+                              #      the default tools, so list each one you want. A
+                              #      new workflow lists all twelve.
   forbid_always?: ForbidEntry[]
                               # DENIED in EVERY state, and absolute: nothing reaches
                               #      past it — no state grant, allow_always entry,
@@ -259,6 +276,18 @@ states:
                                # reference GUARANTEED rather than dependent on agent
                                # behavior. Name here anything a downstream guard
                                # reads.
+    locks?: [string]           # RUN VARIABLES this state OWNS: only it may write them,
+                               # on any visit, before or after they are set; a write
+                               # from another state is refused naming the owner. To
+                               # change one (the person meant another order), the
+                               # session goes BACK to the owner, whose rules apply
+                               # again, and later guards re-read it — so give the
+                               # owner an edge back from the states that use it. Any
+                               # variable, guarded or not. One owner per variable;
+                               # never `trigger`/`title`; not on a human state.
+                               # `lock: true` is refused for an owned variable, and a
+                               # host-supplied value with the same name stays final.
+                               # Pair with `requires` to make the owner set it.
     title?: string             # HUMAN-READABLE label. Presentational only: carried
                                # in a human state's pending-decision record and shown
                                # in host surfaces. REACHES NO MODEL CALL. Never a
@@ -312,8 +341,9 @@ states:
                                # NO PART OF THE PROMPT — the model never reads it,
                                # so it is free, and it can NOT carry routing logic.
                                # The routing text the agent reads is the SOURCE
-                               # state's transition `description`s; nothing about a
-                               # target state is disclosed at all.
+                               # state's transition `description`s, or a target's
+                               # `instructions` where an edge is undescribed; a
+                               # target's summary is never disclosed.
 
     instructions?: string      # behavior guidance.
                                #   agent node: surfaced to the LLM while active.
@@ -328,13 +358,14 @@ states:
                                #   for a terminal state)
 
     tools?:
-      allow?: AllowEntry[]     # grants beyond the always-on tools (plus
-                               # allow_always grants and the always-allowed
-                               # archmax_advance); an entry naming
-                               # an always-on tool NARROWS it.
+      allow?: AllowEntry[]     # grants beyond the workflow-wide grant (plus the
+                               # always-allowed archmax_advance); an entry naming
+                               # a tool that grant includes NARROWS it, and one
+                               # naming a default tool a declared allow_always
+                               # leaves out GRANTS it here.
       forbid?: ForbidEntry[]   # what this state DENIES while active — beating the
-                               # workflow's allow_always, this state's own allow,
-                               # and the always-on surface alike. Deny beats allow.
+                               # workflow-wide grant, this state's own allow,
+                               # and a host's essentialTools alike. Deny beats allow.
                                # Not inherited by a sub-workflow; a lifecycle hook
                                # is exempt from it (runtime authority).
 
@@ -421,25 +452,35 @@ states:
                                #
                                # Transition = {
                                #   to: string          # a declared state's SLUG
-                               #   description: string # REQUIRED, non-empty
+                               #   description?: string # what the agent routes on
                                #   type?: "approve" | "reject" | "refine" | "none"
                                # }
                                #
                                # THE AGENT SEES THIS STATE'S EDGES AND NOTHING
                                # ELSE OF THE GRAPH — no other state's slug, title,
                                # summary, hooks or transitions, and no count of
-                               # the states. So `description` is the whole of what
-                               # it knows about where an edge leads, and a missing
-                               # or blank one is a LOAD ERROR naming
-                               # states.<slug>.transitions.<i>.description.
+                               # the states. So `description` is what it knows
+                               # about where an edge leads. An UNDESCRIBED edge
+                               # (absent/empty/blank) routes on the TARGET's
+                               # `instructions` instead: the edge's line carries
+                               # them, quoted, and nothing else of the target.
+                               # LOAD ERRORS (states.<slug>.transitions.<i>.description):
+                               # an undescribed edge whose target has no
+                               # instructions; an undescribed transition of a
+                               # HUMAN state (it is the button label); a
+                               # non-string. An undescribed edge INTO a human
+                               # state discloses that state's reviewer-facing
+                               # instructions to the agent — describe it to keep
+                               # them private.
                                #
                                # Write it for a reader standing in THIS state,
                                # which knows nothing about the target:
                                #   GOOD: "The refund is over $50."   (when)
                                #   BAD:  "Go to refund-review."      (where)
                                # A routing condition CANNOT live in the target's
-                               # summary/instructions — those are never disclosed
-                               # to the state routing into it.
+                               # summary, which is never disclosed; it lives in the
+                               # target's instructions only when the edge is left
+                               # undescribed.
                                #
                                # The rendered line marks a target that is a human
                                # decision node or terminal (each changes the call
@@ -666,11 +707,12 @@ an entry naming an unprefixed variant governs a tool that does not exist,
 silently granting nothing. A host tool may never claim the prefix. Deep Agents' built-ins
 (`read_file`, `task`, …) keep their own names.
 
-- A state with **no `tools` block** gets the **always-on tools only**
-  (`ls`, `read_file`, `write_file`, `edit_file`, `copy_file`, `move_file`, `remove_file`, `glob`,
-  `grep`, `write_todos`, `archmax_eval`, `archmax_run`, plus the always-allowed `archmax_advance` and `allow_always`
-  grants — minus
-  whatever a `forbid` list denies there, and read-only-zone protection).
+- A state with **no `tools` block** gets the **workflow-wide grant only**: what
+  `tools.allow_always` lists, or the default tools (`ls`, `read_file`, `write_file`,
+  `edit_file`, `copy_file`, `move_file`, `remove_file`, `glob`, `grep`, `write_todos`,
+  `archmax_eval`, `archmax_run`) when the key is absent, plus the always-allowed
+  `archmax_advance` and a host's `essentialTools`, minus whatever a `forbid` list
+  denies there, and read-only-zone protection.
   Governance is closed by default; there is no way to declare a fully open state.
 - `tools.forbid` on a state **denies** while that state is active, beating every
   grant that would otherwise reach it (see [Tool governance](#tool-governance)).
@@ -712,7 +754,8 @@ success.
 ```yaml
 transitions:
   - to: string                 # REQUIRED target state SLUG (must exist); never a title
-    description?: string        # shown to the agent (or human) to pick the edge
+    description?: string        # shown to the agent (or human) to pick the edge; absent =
+                                #   the agent is shown the target's instructions instead
     type?: "approve" | "reject" | "refine" | "none"   # default "none"
 ```
 
@@ -746,22 +789,30 @@ platform-provided tool resolves through when its collection has several) and
 `source` (any string: a host's own label for where the tool came from) — the
 runtime matches governance by `tool` name alone and never reads `source`.
 
-**The model is closed by default, and a denial beats every grant.** Every state always has the
-**always-on tools** (`ls`, `read_file`, `write_file`, `edit_file`, `copy_file`, `move_file`,
-`remove_file`, `glob`, `grep`, `write_todos`, `archmax_eval`, `archmax_run`). One built-in is **never
+**The model is closed by default, and a denial beats every grant.** Every state has the
+**workflow-wide grant**: what `tools.allow_always` lists, or, when the workflow does not
+declare that key, the **default tools** (`ls`, `read_file`, `write_file`, `edit_file`,
+`copy_file`, `move_file`, `remove_file`, `glob`, `grep`, `write_todos`, `archmax_eval`,
+`archmax_run`). A declared list **replaces** the default tools, never adds to them:
+`allow_always: []` grants no tool workflow-wide, and a list without `write_file` leaves
+every state that does not name it unable to write. So a new workflow lists all twelve and
+removes only what it must not have. Every state also has the always-allowed controls and
+any tool the host passes as `essentialTools`, whatever the workflow declares. One built-in is **never
 disclosed** and grantable by nothing: `task`, the runtime's own dispatch for
 grading rubrics — a rubric grades the agent rather than serving it, so naming
 `task` in an allow entry is a `validate` error and the kernel refuses the call.
 The planning scratchpad `write_todos` and the sandbox
-`archmax_eval` are standard equipment — always disclosed, always permitted,
-no setting; only a `forbid` list refuses them. The interpreter is safe as a
+`archmax_eval` are default tools: granted wherever the workflow-wide grant includes
+them (everywhere, in a workflow without `allow_always`). `write_todos`'s prompt
+guidance appears only when some state is granted it, and hooks run in the sandbox
+whether or not the agent is granted `archmax_eval`. The interpreter is safe as a
 default because the `tools.*` calls its code makes are decided against the active
 state by the same kernel: it adds computation over what the state permits, not
-access. `archmax_run` — executing an authored script **file** — is always on on
+access. `archmax_run` — executing an authored script **file** — is a default tool on
 the same terms (the script is a file the state could already read); declare it
 per state to **narrow** which files may run there. The file operations —
 `copy_file({ source, destination, overwrite? })`, `move_file` (same arguments)
-and `remove_file({ file_path })` — are always on on the same terms: every tool
+and `remove_file({ file_path })` — are default tools on the same terms: every tool
 **declares its path arguments** with how the call uses each (`read`, `list`,
 `search`, `write`, `remove`, `execute`), and every path rule reads that
 declaration. `copy_file` reads `source` and writes `destination`; `move_file`
@@ -774,16 +825,19 @@ entry guards every declared path argument: a grant needs all of them to match
 declares its paths (`toolPaths`, or a descriptor's `paths`) is governed the same
 way; an argument may hold a list of paths, each one governed (and each one
 tested by a `paths:` guard), and any other shape is refused
-(`tool.path-argument`). `scratchpad/` is open in every state to the always-on
-tools only — a host tool a state must grant stays refused where it is not
-granted, whatever its paths. Any other tool
+(`tool.path-argument`). `scratchpad/` is open in every state to each default file tool the state
+is granted, whatever the granting entry narrows, and to a host's `essentialTools`.
+A file tool the state is not granted gets nothing from it, and a host tool a state
+must grant stays refused where it is not granted, whatever its paths. Any other tool
 must be declared in the state's `tools.allow` or workflow-level
-`tools.allow_always`. A `tools.allow` entry naming an always-on tool **narrows**
-it for that state.
+`tools.allow_always`. A `tools.allow` entry naming a tool the workflow-wide grant
+includes **narrows** it for that state. A guard on an `allow_always` entry is
+enforced like any other (`{ tool: write_file, paths: [reports/**] }` binds in every
+state that does not name `write_file`).
 Denial is declared beside the grant, in the same two positions and with the same
 entries: `tools.forbid_always` at the root denies in every state,
 `tools.forbid` on a state denies while it is active — subtracting from the
-workflow's grant, the state's own `allow` and the always-on surface alike.
+workflow-wide grant, the state's own `allow` and a host's `essentialTools` alike.
 **Deny beats allow, and no narrower level widens a denial.** A forbid entry may
 name the tool `*` (every tool); `*` in an allow list is a load error. A lifecycle
 hook is exempt from the state's `allow` **and** its `forbid` — runtime authority,
@@ -803,17 +857,18 @@ Precedence (highest first):
    (and regardless of always-allowed): deny beats allow, and no narrower level
    widens a denial.
 2. **Always allowed**: `archmax_advance` (baked in, every state).
-3. **Per-state `tools.allow`** — the listed tools/arg-shapes. An entry for an
-   always-on tool (or one also in `allow_always`) takes precedence
-   (**narrower wins** — the state's arg globs apply, not the broader grant).
-4. **Essential built-ins** — always permitted when no state entry narrows
-   them. Listing one in `allow_always` is inert (`archmax validate` warns).
-5. **Workflow `tools.allow_always`** — grants tools that are not always on in every
-   state.
+3. **Per-state `tools.allow`** — the listed tools/arg-shapes. An entry for a
+   tool the workflow-wide grant includes takes precedence (**narrower wins** —
+   the state's arg globs apply, not the broader grant); an entry for a default
+   tool a declared `allow_always` omits grants it in this state.
+4. **The workflow-wide grant** — the declared `tools.allow_always`, guards
+   included, or the default tools, unconstrained, when the key is absent.
+5. **The host's `essentialTools`** — always permitted when no state entry
+   narrows them, whatever the workflow declares.
 6. **Default**: everything else is blocked.
 
 **Progressive disclosure.** The model is only shown the active state's tool
-surface: always-on tools + `allow_always` + the state's entries + `archmax_advance`
+surface: the workflow-wide grant + a host's `essentialTools` + the state's entries + `archmax_advance`
 (hidden in terminal states), minus every tool denied there by name. Disclosure is
 name-level (arg-constrained tools stay visible; the kernel enforces args at
 call time) and never replaces enforcement. **Skills are disclosed the same way**:
@@ -1265,6 +1320,12 @@ states:
   escalation: { instructions: "Explain the failure and hand off." }  # terminal
 ```
 
+The workflow's root `budget: { maxModelCalls }` (default 50) bounds a whole
+turn across states, beside each state's own `maxTurns`; its exhaustion routes the
+same way. A turn that throws (model failure, cancellation, the step limit) ends
+the session `failed` with exit code `turn-error`, `turn-cancelled` or
+`recursion-limit`; the next message starts a fresh turn.
+
 Two failure classes, routed differently:
 
 - **Recoverable rejections keep the agent in place**: an invalid edge in
@@ -1839,7 +1900,7 @@ them. Its shape:
 - `orders-question` (terminal) answers from `skills/order-data/assets/orders.json`; an
   `after: { rubric: order-reply-tone }` grades the reply at completion.
 - `refund-request` records a decision to `scratchpad/refund.json` (no allow entry
-  narrows it — the working area is open in every state; what holds the agent to a
+  narrows it — the working area is open to `write_file` wherever it is granted; what holds the agent to a
   correct file is the hook), runs `after: check-refund.js`, and pairs
   `budget.maxTurns: 24` with `on_error: escalation` so a terminal failure
   (hook error, exhausted corrections, exhausted budget) routes to escalation

package/skills/archmax-harness/references/workflow-yaml.md

@@ -23,11 +23,24 @@ 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 }
+budget: { maxModelCalls: 50 }    # model calls one turn may make across ALL states (default 50); raise for long turns
 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
+  allow_always:                  #   granted in EVERY state; a state's allow adds to or narrows it.
+    - ls                         #   The DEFAULT TOOLS: declared, this list REPLACES them (absent,
+    - read_file                  #   all twelve are granted), so a new workflow lists all twelve and
+    - write_file                 #   removes only what it must not have. Workflow-wide host tools
+    - edit_file                  #   go below them; state-specific ones under a state's tools.allow.
+    - glob
+    - grep
+    - copy_file
+    - move_file
+    - remove_file
+    - write_todos
+    - archmax_eval
+    - archmax_run
   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
@@ -67,23 +80,25 @@ states:
     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: archmax_run, paths: ["skills/refund-policy/scripts/**"] }   # narrows the workflow-wide grant, 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
+      forbid: [archmax_wait]      # denies here; beats every grant incl. allow_always
     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
+    locks: [case_id]             # variables only this state may write (change = come back here)
     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.
+        description: The decision is recorded and needs a person's approval.   # what the agent routes
+                                 #   on. Say WHEN, never where. Omit it to route on the target's
+                                 #   instructions instead (target must have some); REQUIRED on a
+                                 #   human state's transitions, where it is the button label.
         type: none               # approve | reject | refine | none — semantic on human states
 
   review:                        # human state: parks with a decision record; a PERSON picks the edge
@@ -119,7 +134,10 @@ states:
 - **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
+  (`lock: true` to freeze, until `archmax_reset` releases the agent's locks).
+  A value that must be decided in one place yet stay correctable belongs to a
+  state: `locks: [order_id]` lets only that state write it, so a change routes
+  back there. Reserved: `trigger` (current trigger id, always
   locked) and `title` (the run's one-line task label, agent-owned; a
   sub-workflow child is not asked for one). A
   `${{name}}` / `${{a.b.-1.c}}` reference works in `tools.allow` globs
@@ -174,7 +192,8 @@ states:
   bind them; `forbid_always`, safety rules and the workflow's mount grants
   (any state's) 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
+  a state's segment; the root `budget.maxModelCalls` (default 50) bounds a whole
+  turn across states, so a cycle between states ends there. 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
@@ -252,16 +271,23 @@ no way to see more of the graph.
 
 Closed by default; **deny beats allow, and no narrower level widens a denial.**
 
-- **Always on, never declared**: `ls`, `read_file`, `write_file`,
-  `edit_file`, `copy_file`, `move_file`, `remove_file`, `glob`, `grep`,
-  `write_todos`, `archmax_eval`, `archmax_run`,
-  and the controls `archmax_advance`, `archmax_reset`, `archmax_wait`,
-  `archmax_raise`, `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).
+- **The workflow-wide grant**: `tools.allow_always`, in every state. Absent,
+  it is the **default tools**: `ls`, `read_file`, `write_file`, `edit_file`,
+  `copy_file`, `move_file`, `remove_file`, `glob`, `grep`, `write_todos`,
+  `archmax_eval`, `archmax_run`. Declared (`[]` included), it is exactly what it
+  lists and **replaces** the default tools, so a new workflow lists all twelve
+  (as in the skeleton) and removes only what it must not have. Never declared:
+  the controls `archmax_advance`, `archmax_reset`, `archmax_wait`,
+  `archmax_raise`, `archmax_get_variables`, `archmax_set_variables`, and a host's
+  `essentialTools`. Any other tool needs an `allow`/`allow_always` entry. A
+  state entry naming a granted tool **narrows** it there, and one naming a
+  default tool the list omits grants it there. `task` is ungrantable (error).
 - **Entries**: bare name; `{ tool, args: { <arg>: ["glob", …] } }` (matches
-  if any glob matches; `${{var}}` allowed); `{ tool, paths: [...] }`
+  if any glob matches; `${{var}}` allowed). An argument the tool declares as a
+  path (else `file_path`) is canonicalized first; any other argument (a URL, an
+  address, an email) is matched **as written**, and a denial also catches its
+  path form. `""` matches only an empty value. `*` never crosses `/` (`**` does).
+  `{ tool, paths: [...] }`
   (guards every path argument the tool declares — all must match to grant,
   any matching denies). `"*"` as the tool is legal only in a
   forbid list. Globs match dot-segments (`secrets/**` covers `secrets/.env`).