@archmax-ai/harness 0.1.0 → 0.2.1

package/dist/workflow/workflow-tools.js

@@ -1,8 +1,8 @@
 /**
  * Delegation tools: one per sibling workflow a machine is permitted to call. A
- * workflow's declared signature is its call signature: the `sub-workflow`
- * trigger's `requires:` becomes the tool's parameters and `returns:` the shape
- * of the result, so delegating is an ordinary governed tool call.
+ * workflow's declared signature is its call signature: the `manual` trigger's
+ * `requires:` becomes the tool's typed parameters and `returns:` the shape of
+ * the result, so delegating is an ordinary governed tool call.
  *
  * Unlike the other `archmax_*` tools, the body is real: a delegation tool is the
  * only runtime tool a script may call through the PTC gateway (which runs the
@@ -10,39 +10,52 @@
  * is parallel tool calls or a script's `Promise.all`, bounded by the dispatcher.
  */
 import { tool } from "langchain";
+import { signatureJsonSchema } from "../machine/signature.js";
 import { workflowToolName } from "../machine/tool-names.js";
 import { callingStateFrom } from "../sessions/scope.js";
 /**
  * The model-facing description, built from the target's own spec: what the
- * runtime enforces and no more. The target's `instructions` are absent — that is
- * the child's brief, and the caller's agent must not act on it.
+ * runtime enforces and no more, led by what the target says calling it does.
+ * The target's `instructions` are absent — that is the child's brief, and the
+ * caller's agent must not act on it.
  */
 export function delegationToolDescription(target) {
     const parts = [];
+    const description = target.description?.trim();
+    if (description)
+        parts.push(/[.!?]$/.test(description) ? description : `${description}.`);
     const label = target.title?.trim();
+    const requires = (target.requires ?? []).map((entry) => entry.name);
+    const returns = (target.returns ?? []).map((entry) => entry.name);
     parts.push(`Run the '${target.workflow}' workflow${label ? ` (${label})` : ""} to completion and ` +
         `return its result. It runs as its own governed machine with its own states and tools; ` +
         `your run stays where it is and continues when the call answers.`);
-    if (target.requires?.length) {
-        parts.push(`It requires ${quoteList(target.requires)}, which the call must supply.`);
+    if (requires.length) {
+        parts.push(`It requires ${quoteList(requires)}, which the call must supply.`);
     }
-    parts.push(target.returns?.length
-        ? `The result carries ${quoteList(target.returns)} under 'returns', alongside the ` +
+    parts.push(returns.length
+        ? `The result carries ${quoteList(returns)} under 'returns', alongside the ` +
             `workflow's closing message under 'message'.`
         : `The result is the workflow's closing message.`);
     parts.push(`One call runs it once; call it again (in the same turn) to run several at once.`);
     return parts.join(" ");
 }
-/** The JSON Schema for a call: the target's `requires`, and nothing else named. */
+/**
+ * The JSON Schema for a call: the target's `requires`, and nothing else named —
+ * built by the one signature mapping, so each parameter carries the type the
+ * dispatch enforces, and described as the locked variable it is seeded as.
+ */
 export function delegationToolSchema(target) {
-    const required = target.requires ?? [];
+    const requires = target.requires ?? [];
+    const schema = signatureJsonSchema(requires);
+    for (const entry of requires) {
+        const declared = entry.description?.trim();
+        schema.properties[entry.name].description = declared
+            ? `${/[.!?]$/.test(declared) ? declared : `${declared}.`} Seeded as a locked run variable.`
+            : `Required input '${entry.name}', seeded as a locked run variable.`;
+    }
     return {
-        type: "object",
-        properties: Object.fromEntries(required.map((name) => [
-            name,
-            { description: `Required input '${name}', seeded as a locked run variable.` },
-        ])),
-        required: [...required],
+        ...schema,
         // Open: `requires` states only what is mandatory, and nothing declares the full accepted set.
         additionalProperties: true,
     };

package/dist/workflow/workflow-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-tools.js","sourceRoot":"","sources":["../../src/workflow/workflow-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflow-tools.js","sourceRoot":"","sources":["../../src/workflow/workflow-tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archmax-ai/harness",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Agents can't reliably follow a process. archmax harness makes them: a governed layer over LangChain Deep Agents that enforces a declarative workflow state machine on every step.",
   "keywords": [
@@ -64,6 +64,7 @@
   },
   "files": [
     "dist",
+    "skills/archmax-harness",
     "README.md",
     "LICENSE"
   ],

package/skills/archmax-harness/README.md

@@ -0,0 +1,82 @@
+# @archmax-ai/harness skill
+
+An [Agent Skill](https://skills.sh) that teaches a coding agent (Claude Code,
+Cursor, Codex, …) how to **build with** the
+[`@archmax-ai/harness`](https://www.npmjs.com/package/@archmax-ai/harness) runtime:
+
+1. **Author a workflow** — a `workflow.yaml` state machine plus its skills,
+   grading rubrics, scripts, lifecycle hooks, tool governance, and cases.
+2. **Wire the runtime into a backend** — assemble an agent with
+   `createAgent`, run a workflow, resume human-in-the-loop states, and
+   stream lifecycle events / run artifacts so a frontend can visualize run state.
+
+## Install
+
+**Via the skills CLI (primary)** — from the public GitHub repository:
+
+```bash
+npx skills add archmax-ai/harness
+```
+
+Add `-g` to install globally, or `-a <agent>` to target a specific coding agent.
+
+**From the installed `@archmax-ai/harness` package** — the skill ships inside the
+npm package, so this copy always matches the installed SDK version. After
+`npm install`:
+
+```bash
+npx skills add ./node_modules/@archmax-ai/harness
+```
+
+`npx skills experimental_sync` picks it up too, along with any other skill in
+`node_modules`. The package ships this directory as `skills/archmax-harness/`
+(for installers) and as `dist/authoring-skill/archmax-harness/` (for
+`BUNDLED_AUTHORING_SKILL_DIR`).
+
+```ts
+import { BUNDLED_AUTHORING_SKILL_DIR } from "@archmax-ai/harness";
+// <BUNDLED_AUTHORING_SKILL_DIR>/archmax-harness/SKILL.md (+ references/) — the
+// constant is the dist/authoring-skill directory, for skills middleware.
+```
+
+**From a checkout of this repository**: `npx skills add ./skills/archmax-harness`.
+
+Skills appear on skills.sh automatically via install telemetry — there is no
+separate submission step.
+
+## What's inside
+
+| File | Purpose |
+| --- | --- |
+| `SKILL.md` | The entry point, loaded when the skill triggers: procedure, workspace layout, CLI, and a table saying which short reference to load for which task |
+| `references/workflow-yaml.md` | Short: every `workflow.yaml` key as an annotated skeleton, machine rules, governance |
+| `references/hooks-and-scripts.md` | Short: the hook-script and `archmax_run` contracts |
+| `references/cases.md` | Short: the case grammar (keys, actions, assertions, mocking rule) |
+| `references/diagnostics.md` | Short: every `validate` diagnostic → its fix; removed keys |
+| `references/wiring.md` | Short: `createAgent`, human states, events, artifacts |
+| `references/workflow-schema.md` | Exhaustive `workflow.yaml` field reference + annotated example |
+| `references/hook-and-test-scripts.md` | Full lifecycle hook-script + cases contracts with worked code examples |
+| `references/backend-integration.md` | Full `createAgent` / events / run-artifact integration reference |
+
+The skill is **self-contained** — no external docs are required to use it. It
+targets **runtime contract version `"2"`**.
+
+## Naming note
+
+This **authoring skill** is distinct from a workspace's **skill bundles** —
+`skills/<slug>/` directories holding a `SKILL.md`, the capability's `assets/`
+and its `archmax_run` `scripts/`, enabled per workflow and per state by slug.
+They share the Agent Skills file format and nothing else: this skill is a
+playbook for *building* such workspaces and wiring the runtime, which is why
+it ships under `dist/authoring-skill/` rather than beside any workspace's
+`skills/`.
+
+## Safety
+
+Instruction-only: this skill bundles **no executable scripts**. It directs the
+agent to run the runtime's own `archmax validate` / `archmax test` CLI commands to
+verify authored workflows.
+
+## License
+
+MIT (same as the `@archmax-ai/harness` package).

package/skills/archmax-harness/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: archmax-harness
+description: >-
+  Build with the @archmax-ai/harness runtime for LangChain Deep Agents. Use this
+  whenever you are designing, editing or fixing a workflow state machine (a
+  workflow.yaml with states, transitions, lifecycle hooks, tool and skill
+  governance, grading rubrics, scripts, cases, or skill bundles), OR wiring the
+  @archmax-ai/harness npm package into a backend service — assembling an agent with
+  createAgent, running a workflow, resuming human-in-the-loop states, or
+  streaming lifecycle events / session artifacts so a frontend can visualize a
+  run. Trigger this skill for phrases like "design a workflow", "author a
+  workflow.yaml", "add a state/transition/hook", "archmax validate fails", "run
+  an agent workflow from my worker", or "integrate @archmax-ai/harness" even when the
+  runtime is not named explicitly.
+---
+
+# Building with @archmax-ai/harness
+
+The archmax harness is a thin, governed runtime over
+[LangChain Deep Agents](https://docs.langchain.com/oss/javascript/deepagents/overview):
+one Deep Agent per workflow, moved by a declarative state machine
+(`workflow.yaml`). It holds no use-case logic — a **workspace** supplies it.
+Runtime contract: `runtime: { engine: archmax-harness, version: "2" }` in every spec.
+
+**Read by task, not by curiosity.** This file holds the procedure, the
+workspace layout and the commands. Load exactly the short reference your next
+file needs, once, and nothing else:
+
+| You are about to… | Load |
+| --- | --- |
+| write or edit `workflow.yaml` | [`references/workflow-yaml.md`](references/workflow-yaml.md) — every key, machine rules, governance |
+| write a script — a skill's `scripts/*.js` (`archmax_run`) or a `hooks/*.js` gate | [`references/hooks-and-scripts.md`](references/hooks-and-scripts.md); sequence the skill case with the *Script playbook* below |
+| write or fix a case (`tests/*.test.yaml`) | [`references/cases.md`](references/cases.md) |
+| fix what `archmax validate` / `archmax test` reported | [`references/diagnostics.md`](references/diagnostics.md) |
+| embed the package in a service | [`references/wiring.md`](references/wiring.md) |
+
+The long references — `workflow-schema.md`, `hook-and-test-scripts.md`,
+`backend-integration.md` — are exhaustive; open a **section** of one only when
+the short reference says so or a field's exact semantics are in doubt. Do
+**not** read the SDK source, do not `ls`/`glob` a workspace to discover its
+layout (it is fixed, below), and do not re-read a file already in context.
+Naming note: this authoring skill is not a workspace's `skills/<slug>/` bundle;
+they share a file format and nothing else.
+
+---
+
+## Authoring
+
+### Procedure
+
+**Build a workflow.** Design the whole file set first, write each file once,
+then verify. Do not write a file, validate, and discover the next file.
+
+1. **Sketch the graph**: states (kebab-case slugs), the start state carrying
+   `triggers: { manual: }` (plus any host trigger ids that enter there),
+   terminal states (no `transitions`), the edges between them — and for each
+   edge, the *condition* under which it is taken. That condition is the edge's
+   required `description`, and it is the only thing the agent will know about
+   where the edge leads. If something outside the session calls the workflow
+   (another workflow, a host's MCP tool or form), give its trigger a
+   `description` for the caller and a `requires`/`returns` signature, typing an
+   entry (`{ name, type, description }`; `string` `integer` `number` `boolean`
+   `date` `date-time` `object` `array`) where the caller must build or read the
+   value. The runtime holds typed entries at start, at `archmax_set_variables`
+   and at completion ([`references/workflow-schema.md`](references/workflow-schema.md)).
+2. **Decide the file set** from the sketch: `workflow.yaml` always; one
+   `hooks/<check>.js` per *deterministic* gate; one inline `rubric:` per
+   *judgment* gate (tone, completeness); cases — one happy path per branch,
+   one per hook veto path, one `decide:` per human state; a
+   `skills/<capability>/` bundle only for data, an `archmax_run` script, or
+   guidance two or more states share identically; `AGENTS.md` only for a
+   workspace-wide persona.
+3. **Write `workflow.yaml`** from the skeleton in [`references/workflow-yaml.md`](references/workflow-yaml.md). Each state's behaviour
+   goes inline in its `instructions`; run-wide rules once in the top-level
+   `instructions`; nothing about the machine itself (the platform prompt and
+   the disclosed edges already say it, and prose is billed on every call), and
+   nothing about the date: every model call opens with the current date and time
+   in UTC (rounded down to ten minutes, with the host's zone named), so date
+   arithmetic ("due in 30 days") needs no authored `today`.
+   Never describe another state in a state's `instructions` or in an edge's
+   `description`: the agent is shown the active state's edges and nothing else
+   of the graph, so a routing condition parked in the *target's* `summary` or
+   `instructions` is invisible to the state that has to route on it. Name
+   a model (`settings.model`, or `model:` on one state) only where the work
+   differs in kind — a small model on mechanical states, the default on
+   drafting, judgement and heavy-routing ones.
+4. **Write hooks, rubrics, cases** — description first (a hook's JSDoc, a
+   case's `title` + `description`), then the body, and never leave the two
+   disagreeing. Before writing a case, settle what to mock ([`references/cases.md`](references/cases.md)).
+5. **Verify**: `archmax validate <slug>` → fix every error (and every warning
+   you can) → `archmax test <slug>`. Never call a workflow done without a clean
+   `validate`.
+
+**Fix a workflow.** Diagnose from the tool, not by reading everything.
+
+1. Run `archmax validate <slug>` (offline, instant). Every diagnostic names
+   the file, the field path and the fix; map it with the
+   [`references/diagnostics.md`](references/diagnostics.md).
+2. Read **only** the files the diagnostics name. Edit once. Re-validate.
+3. When clean, `archmax test <slug> [filter]`. Read the failing case's verdict
+   line: a **structural** miss (`reachedState`, `parked`, `succeeded`,
+   `trail`) is a routing or governance defect — fix the routing state's
+   `instructions`, the transition `description`s, or the `tools`/`skills`
+   grants; a **content** miss (`reply`, `calledTool`, `grade`) is an
+   `instructions` defect in the state that answered; a veto reason quoted in
+   the reply is the hook or rubric speaking — fix what it names. Change the
+   case only when it asserts something the spec never promised.
+4. A `grade` miss is the one non-deterministic assertion: re-run that case
+   once before calling it a regression. Re-run with `--verbose` for raw
+   events only when the verdict line is not enough.
+
+Budget: one validate, one edit pass, one validate, one test. If you are on
+your fourth read of a file, you are guessing — reread the relevant reference
+instead.
+
+**Shapes come from tools, not from research.** Before naming any field of a
+tool's result or a trigger's payload — in `instructions`, a `${{…}}` guard, a
+hook — ask the host: a platform embedding this runtime typically exposes
+describe-style tools (a tool's input and output schema, a trigger's payload
+schema and sample) and a way to sample or invoke once with a narrow input. Call
+those first; fall back to a recorded session's variables (`archmax sessions <id>`)
+only when no such tool exists. Reading more files never reveals what a live
+system returns.
+
+### Script playbook (a skill's `scripts/<x>.js`)
+
+Deterministic work the model triggers with `archmax_run`. In order:
+
+1. **Shapes first.** Trigger payload and tool I/O from the host's describe/sample
+   tools; the variables a run actually carries from `archmax sessions <id>`.
+   Guessing a field name here costs a whole run (above).
+2. **Write it.** `skills/<cap>/scripts/<x>.js`: JSDoc, then the body. Input is the
+   global `args` — `args.<param>` from the model plus `args.variables`, a read-only
+   snapshot — and the **last expression** is the result. Contract:
+   [`references/hooks-and-scripts.md`](references/hooks-and-scripts.md).
+3. **Land the result in a variable.** Return structured data, and name the variable
+   in the calling state's `requires:`. A script may not call
+   `archmax_set_variables`, so `requires` is what makes the model record the return;
+   unrecorded, the result lives in one tool message and is gone.
+4. **Announce it in the skill.** The `SKILL.md` `description` says *when* to run it;
+   the body says the script's path, its arguments, and the variable its result
+   lands in. A script nothing points at is never reached.
+5. **Grant it.** The calling state allows `{ tool: archmax_run, paths:
+   ["skills/<cap>/scripts/**"] }` plus every tool the script itself calls. Then
+   `archmax validate`.
+
+### Reference a variable, never retype it
+
+`${{name}}` / `${{a.b.-1.c}}` resolves against the run's variables in a
+`tools.allow` glob **and inside any text argument the model writes** — mid-string,
+repeatable, matched literally. The transcript keeps the reference and only the tool
+sees the value, so a stored value costs its tokens once instead of on every later
+model call. Step 3 is what puts a value there to reference.
+
+A state that must emit something already stored is told to interpolate it:
+
+```yaml
+instructions: >-
+  Send the reply with gmail__send. Quote the customer's message by writing
+  ${{inbound.text}} in the body rather than retyping it.
+```
+
+Exact — a retyped copy truncates and drifts, a reference cannot — and it agrees by
+construction with a guard on the same variable. Not available in scripts, which
+read `args.variables`. To write the characters literally: `$${{name}}`.
+
+### Workspace layout (complete — nothing else exists)
+
+```
+<workspace root>/
+  AGENTS.md                          # optional persona; prompt layer 1
+  workflows/<slug>/                  # AUTHORING PLANE — runtime reads it, the agent CANNOT
+    workflow.yaml                    #   the machine (required, canonical)
+    WORKFLOW.md                      #   optional plain-markdown addendum, NO frontmatter
+    hooks/<check>.js                 #   lifecycle hook scripts, run by the runtime
+    tests/<case>.test.yaml           #   one case per file; fixtures beside them (`from:`)
+  skills/<capability>/               # AGENT PLANE — mounted read-only, enabled per state by slug
+    SKILL.md                         #   frontmatter (name = directory slug, description) + body
+    scripts/<script>.js              #   archmax_run sources, run by the agent
+    assets/<file>                    #   read-only inputs
+    references/<topic>.md            #   optional deeper material
+  .env                               # ARCHMAX_* model config (never mounted)
+  sessions/<sessionId>/              # the run; the agent's workspace ROOT (never authored)
+    scratchpad/                      #   agent-visible `scratchpad/…`: the session's always-writable
+                                     #   area (a host-wired writable mount is another place to write)
+    large_tool_results/ conversation_history/   # runtime offload, agent reads only
+    checkpoints/ artifacts/          #   runtime-internal
+```
+
+Rules that follow:
+
+- **The agent cannot read `workflows/**`** — its spec, hooks, rubrics and
+  cases have no route in its workspace. Never point `instructions`,
+  `evidence` or a case `workspace:` at one (`validate` errors). Text the agent
+  needs goes in a skill bundle.
+- **Placement**: a hook is the guard, a runtime script is the tool; they
+  never share a file or a directory.
+
+  | Script | Runs on | Lives at | Wired as |
+  | --- | --- | --- | --- |
+  | Hook | runtime authority, at `before`/`after` | `workflows/<slug>/hooks/<x>.js` | `before: { script: hooks/<x>.js }` (workflow-relative, confined to `hooks/`) |
+  | Runtime script | the model's authority, via `archmax_run` | `skills/<cap>/scripts/<x>.js` | enabling the skill; narrow with `{ tool: archmax_run, paths: ["skills/<cap>/scripts/**"] }` |
+
+  `archmax_run` is confined to skill bundles by a non-overridable rule
+  (`script.skill-only`): a script in `scratchpad/` or `hooks/` is unrunnable.
+- **Paths have no leading slash** (`skills/order-data/assets/orders.json`,
+  `scratchpad/refund.json`); never author a `run/` prefix. `scratchpad/` is
+  writable in every state regardless of `tools.allow`, so an allow entry
+  inside it narrows nothing (warning); to govern *where* a result lands, name
+  a non-reserved run path (`reports/*.json`) and allow it.
+- **Guidance has three homes, one per rule**: every workflow → `AGENTS.md`;
+  the whole run → top-level `instructions` (`|-` literal block, since `>-`
+  folds paragraphs together); one state's turn → that state's `instructions`
+  (`>-` is fine). Pasting a paragraph into a second state means hoist it.
+  Never one `skills/<state>/` per state.
+- **Every `.js` you author opens with a JSDoc block**: title line, blank
+  line, then what it reads, the sequence of checks, and the condition for each
+  verdict (hook) or what it computes and returns (script). Admin UIs show this
+  instead of the code. No `@specification` tag, no sidecar key.
+
+### Verify (CLI)
+
+```bash
+archmax validate [workflow] [--json]            # offline; run after every structural edit
+archmax test [workflow] [filter] [--json]       # cases; filter = case-id substring
+archmax run <workflow> "<prompt>" [--session <id>] [--trigger <id>] [--variables '<json>']
+archmax sessions [session] [--json]             # list, or one session's variables (value + locked)
+archmax decide <session> --to <state> [--comment "…"]   # resume a human state
+archmax reply <session> "<message>"             # message a parked run; it stays parked
+archmax deliver <session> --trigger <id> [--variables '<json>']   # resume an archmax_wait
+```
+
+`<workflow>` may be omitted when the workspace has one. Global `--root <dir>`
+(cwd default; `.env` loads from it), `--verbose` for raw events. Results on
+stdout, narration on stderr. Exit 0 done/parked, 1 failure, 2 usage. Dev from
+the SDK checkout: `npm run dev -- <command…>`.
+
+---
+
+
+---
+
+## Done when
+
+- Authoring: `archmax validate` clean, `archmax test` passing, every `.js`
+  opens with its JSDoc, every case has `title` + `description`.
+- Wiring: the snippet compiles against the installed package's exports.