@archmax-ai/harness 0.0.0

package/dist/assembly/plain.js

@@ -0,0 +1,41 @@
+/**
+ * The no-workflow composition: a plain, skills-driven Deep Agent over the same
+ * workspace, with no machine, no control tools and no per-state gating.
+ */
+import { createDeepAgent } from "deepagents";
+import { asCompiledAgentGraph } from "../core/deepagents.js";
+import { TOOL_MOCK_MIDDLEWARE_NAME } from "../core/tool-mocks.js";
+import { frameworkPassthrough, rubricParams, todoMiddleware } from "./compose.js";
+/**
+ * A skill source as upstream's middleware wants it: a leading-slash,
+ * trailing-slash POSIX path. The assembly's own sources are workspace-relative
+ * (`skills/`); only the plain composition hands them to upstream, so the
+ * conversion lives at that one boundary.
+ */
+function asSkillSource(source) {
+    return `/${source.replace(/^\/+/, "").replace(/\/+$/, "")}/`;
+}
+/** Compose the plain agent: its graph, and whether the host's tool-mock middleware is among its middleware. */
+export function composePlain(ctx, systemPrompt) {
+    // The host's middleware rides after the runtime's own, as on the governed path.
+    const middleware = [todoMiddleware(), ...(ctx.params.middleware ?? [])];
+    const deepAgent = createDeepAgent({
+        model: ctx.model,
+        backend: ctx.backend,
+        // No machine, so there are no states to vary disclosure by: upstream's
+        // skills middleware discloses every skill of the declared sources, which is
+        // exactly right here and exactly wrong under a workflow.
+        skills: ctx.skillSources.map(asSkillSource),
+        tools: ctx.params.tools ?? [],
+        ...rubricParams(ctx),
+        middleware,
+        systemPrompt: { prefix: systemPrompt, base: null },
+        checkpointer: ctx.checkpointer,
+        ...frameworkPassthrough(ctx.params),
+    });
+    return {
+        graph: asCompiledAgentGraph(deepAgent.graph),
+        toolMocks: middleware.some((m) => m.name === TOOL_MOCK_MIDDLEWARE_NAME),
+    };
+}
+//# sourceMappingURL=plain.js.map

package/dist/assembly/plain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plain.js","sourceRoot":"","sources":["../../src/assembly/plain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAA2B,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,cAAc,EAAwB,MAAM,cAAc,CAAC;AAExG;;;;;GAKG;AACH,SAAS,aAAa,CAAC,MAAc;IACnC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC;AAC/D,CAAC;AAED,+GAA+G;AAC/G,MAAM,UAAU,YAAY,CAC1B,GAAoB,EACpB,YAAoB;IAEpB,gFAAgF;IAChF,MAAM,UAAU,GAAG,CAAC,cAAc,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,CAAC;IACxE,MAAM,SAAS,GAAG,eAAe,CAAC;QAChC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,uEAAuE;QACvE,4EAA4E;QAC5E,yDAAyD;QACzD,MAAM,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC;QAC3C,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;QAC7B,GAAG,YAAY,CAAC,GAAG,CAAC;QACpB,UAAU;QACV,YAAY,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE;QAClD,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,GAAG,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC;KACpC,CAAC,CAAC;IACH,OAAO;QACL,KAAK,EAAE,oBAAoB,CAAC,SAAS,CAAC,KAAK,CAAC;QAC5C,SAAS,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,yBAAyB,CAAC;KACxE,CAAC;AACJ,CAAC"}

package/dist/authoring-skill/archmax-harness/README.md

@@ -0,0 +1,76 @@
+# @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
+
+**From the installed `@archmax-ai/harness` package (primary for runtime consumers)** —
+the skill ships inside the npm package, so it always matches the installed SDK
+version instead of a synced copy:
+
+```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 holding archmax-harness/. Point an install CLI at
+// the skill itself:
+// npx skills add ./node_modules/@archmax-ai/harness/dist/authoring-skill/archmax-harness
+// (`BUNDLED_SKILLS_DIR` is a deprecated alias with the same value, kept one
+// release.)
+```
+
+**Via the skills CLI from a checkout (coding-agent / development use)**:
+
+```bash
+npx skills add <owner>/<repo>            # once this repo is public, from its root
+# or point at the subfolder directly:
+npx skills add ./skills/archmax-harness
+```
+
+Replace `<owner>/<repo>` with this repository's GitHub slug. 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/dist/authoring-skill/archmax-harness/SKILL.md

@@ -0,0 +1,241 @@
+---
+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.
+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.