norn-cli 2.9.7 → 3.0.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to the "Norn" extension will be documented in this file.
 
+## [3.0.0] - 2026-08-11
+
+### Added
+- **`.nornagent` files — the Agent Workbench** - a new file type that declares AI agents alongside your API tests. An imported `.nornagent` sidecar declares the models and agents; a `.norn` sequence owns execution order and calls them with `var reply = run <Agent> "…"`. Agents can be given MCP-backed tools, `accepts` / `returns` JSON Schema contracts that are validated on every boundary, and other agents they are allowed to call.
+- **Agent graph canvas** - a read-only VS Code canvas for a `.nornagent` file showing who calls whom, the contract on each boundary, and how each hop turned out. Hover for models, timings, usage, prompts, payloads, and contract issues.
+- **Run recording, replay, and stepping** - runs are recorded by default under `.norn-cache/runs/` (last 20 kept). Replay a recording to step it in the existing `norn` debugger, or play it back hop by hop on the canvas — nothing re-executes and no model is called. The graph toolbar labels each run with the `.norn` file it came from, and **This file — current view** returns you to the open file.
+- **`judge` statements — AI evals in a sequence** - `judge <value> with <Agent> expects "…"` scores free text that an assertion cannot. The judge rules on each expectation independently and quotes its evidence; Norn computes the pass or fail, so the verdict never comes from the model. A long checklist lives in a file with `expects file <path>`, where an ordinary Markdown list works as-is. Every ruling carries a reason, and a quote that cannot be found in the judged text is flagged.
+- **Judge results everywhere a run is reported** - verdicts appear in the response panel, on the agent graph, in the CLI summary, and in per-statement JUnit output, and travel with the run's trace and recording. A failed verdict fails the sequence and exits the CLI non-zero.
+- **Request body variable highlighting** - a variable used as a request body is now coloured as a variable rather than as a header group reference.
+
+### Changed
+- **`model` blocks in `.nornagent`** - a model is declared as a block naming every input it needs:
+
+  ```nornagent
+  model Workbench
+      provider openai
+      name gpt-4o
+      apiKey {{$env.OPENAI_API_KEY}}
+  end model
+  ```
+
+  This replaces the earlier one-line `model <Alias>: <provider>/<model-id>` form, which implied both the provider/model split and an undeclared environment-variable name. `apiKey` and `baseUrl` are ordinary Norn templates resolved per run, so the file says exactly which value it needs and the secret itself stays in the environment.
+
 ## [2.9.1] - 2026-06-22
 
 ### Fixed

package/CLAUDE.md

@@ -0,0 +1,68 @@
+# Norn Extension — Claude Code instructions
+
+## Read these first
+
+1. **[`NOW.md`](NOW.md)** — the tool-agnostic active-work board shared by every agent and by
+   Peter. Whatever sits under **Active now** is the current priority. This board, not any
+   assistant's memory, is the source of truth for what we are working on.
+2. **[`AGENTS.md`](AGENTS.md)** — the full repo instructions (CLI parity requirement, how to
+   run the local CLI, code style, testing). Everything in that file applies here.
+
+## Skills: consult `.github/skills/` — always
+
+This repo keeps its accumulated implementation knowledge in **[`.github/skills/`](.github/skills/)**,
+maintained by every agent that works here. Treat it as required reading, not an optional
+reference.
+
+**Before touching any area of the codebase, check `.github/skills/` for a skill covering it
+and read that skill.** Do this even for changes that look small — the skills exist precisely
+because these areas have non-obvious rules that are easy to break.
+
+Current skills and what they cover:
+
+| Skill | Read it when working on |
+|-------|------------------------|
+| `norn-syntax-highlighting` | TextMate grammars in `syntaxes/`, token scopes, highlighting bugs |
+| `norn-agent-workbench` | `.nornagent` sidecars, agent `run` steps, providers, contracts, record/replay, agent graph |
+| `norn-intellisense-preferences` | Completion providers, IntelliSense behaviour |
+| `norn-value-resolution` | Variables, interpolation, `.nornenv`, value precedence |
+| `add-norn-keyword` | Adding a keyword to the `.norn` language |
+| `add-assertion-operator` | Adding an assertion operator |
+| `add-sequence-step-type` | Adding a new sequence step type |
+| `add-imported-sidecar-language` | Adding a new imported sidecar file type |
+| `norn-cli-integration` | `src/cli.ts` and CLI parity |
+| `norn-debugger-integration` | DAP / debugger work |
+| `norn-response-panel` | The response webview panel |
+| `norn-test-explorer` | VS Code Test Explorer integration |
+| `norn-sequence-tags` | Sequence tags and filtering |
+| `norn-api-coverage` | `.nornapi` coverage features |
+| `norn-mcp-tools` | MCP client and tool wiring |
+| `norn-k8s` | Kubernetes features |
+| `norn-terminal` | Norn Terminal / PTY work |
+| `norn-env-templates` | `.nornenv` templates |
+| `norn-publishing` | Packaging and publishing the extension |
+| `norn-starter-catalog` | Starter templates catalog |
+| `norn-title-cards` | Title cards |
+| `demo-task-helper` | Building demos |
+| `readme-sync` | Keeping README/docs in sync with features |
+
+The table can go stale — list the directory when the work doesn't obviously map to a row.
+
+### Maintaining skills
+
+Per `AGENTS.md`, skills are living documents:
+
+- If a skill is **wrong or outdated**, fix it as part of the change.
+- If a skill is **missing** for an area you just learned, write one in Agent Skills format.
+- After creating or editing any skill, run `npm run validate:skills`.
+
+Capture the lesson that was hard to learn, not a restatement of the code.
+
+## Verification
+
+Never use `npx norn` — that runs the published package, not local changes:
+
+```bash
+npm run compile
+node ./dist/cli.js tests/file.norn --env prelive
+```

package/NOW.md

@@ -0,0 +1,157 @@
+# NOW — Active Work Board
+
+> **The single source of truth for what we are working on _right now_** — for Peter and
+> for every AI agent (Claude, Codex, Copilot, Cursor, any). Deliberately tool-agnostic:
+> it lives here in the repo, **not** in any one assistant's memory or private notes.
+>
+> We have a lot of planning docs; this board exists so nobody (human or AI) has to guess
+> what's current. If it's on this board, it's the work. If it's not, it isn't — yet.
+
+## How this board works
+
+- **Empty by default.** Nothing is "current" unless it has been explicitly **Accepted**
+  onto this board by Peter. An empty "Active now" means: no directed work in flight —
+  don't start big work off a backlog/plan doc without Peter accepting it here first.
+- **Accepting work:** Peter says "Accept X" (or moves it here). That's the signal it
+  becomes current. Until then, ideas live in the plan/backlog docs, not here.
+- **This board is an _index_, not the detail.** Each item is one or two lines + a link to
+  its real plan doc. Keep the detail in the linked doc; keep this page short and scannable.
+- **Finishing work:** when an item is done, move it to "Recently done" (keep the last
+  handful), then prune. Don't let this page grow.
+- **Agents:** treat items under "Active now" as the current priority order. Do these
+  before picking up anything from the wider `Docs/` set.
+
+---
+
+## Active now
+
+### 🧪 Agent Workbench — Slice 5: AI evals
+The last of the four things nothing else does in one place: let an **AI judge score what a
+contract cannot**, with thresholds useful in CI rather than noisy. An umbrella, not a buildable
+slice — it breaks into six items (authoring, rubric/scoring, judge execution, thresholds,
+reporting, fixtures/docs), specced and built one at a time.
+→ Spec: [`Docs/to-be-built/agent-workbench-slice-5.md`](Docs/to-be-built/agent-workbench-slice-5.md)
+
+**Next step:** **5f — fixtures, docs, positioning**, the last item of slice 5. The feature is
+complete and reported across every surface; what is missing is a demo anyone else can run and an
+explanation of what it is for. 5f has no spec yet.
+
+**5b and 5d are closed.** 5b was made unnecessary by the checklist scoring model. 5d's content
+was decided in conversation — a failed judge stops the sequence, the CLI already exits `1`, and
+per-expectation strictness plus the replay-drift check are future work Peter deferred
+2026-08-10.
+→ 5a spec (built): [`Docs/to-be-built/agent-workbench-slice-5a.md`](Docs/to-be-built/agent-workbench-slice-5a.md)
+→ 5c spec (built): [`Docs/to-be-built/agent-workbench-slice-5c.md`](Docs/to-be-built/agent-workbench-slice-5c.md)
+→ 5e spec (built): [`Docs/to-be-built/agent-workbench-slice-5e.md`](Docs/to-be-built/agent-workbench-slice-5e.md)
+
+---
+
+## Backlog / accepted-but-not-started
+
+_(empty)_
+
+## Parked
+
+### Contract & Drift + Voiden-playbook marketing
+The previous direction, parked 2026-08-07 — untested, not failed. Stages 1+2 are built and
+shipped in 2.9.8; the QA dogfood and the "why Norn, now" hook never happened. Full
+narrative and how to resume:
+[`Docs/random/parked_contract_drift_and_marketing.md`](Docs/random/parked_contract_drift_and_marketing.md)
+
+## Recently done
+
+- **Agent Workbench Slice 5e — reporting** (2026-08-10) — **done.**
+  A verdict is now visible in the response panel, the canvas, the debugger, and JUnit, derived
+  once through `agentHopPresentation` so the surfaces cannot disagree. The load-bearing move was
+  putting the verdict on `AgentHopResult` rather than the step: a recording persists the trace
+  and never step results, so a step-only verdict vanished the moment a past run was reopened —
+  the round-trip is now a test. Two bugs the build surfaced: a judged hop has `success === true`
+  even when the verdict failed, so the canvas drew a **green node for a failed run** until the
+  verdict was counted explicitly; and the runner emits its `completed` event before the verdict
+  exists, so the deep-cloned event log needed patching or replay playback showed no verdict.
+  Also: judge statements now draw a sequence handoff edge from whatever produced the value they
+  judge, live progress is emitted as `stepType: 'judge'`, and JUnit gets one testcase per
+  statement with `ExpectationsUnmet` and `JudgeError` kept distinct. 13 new focused tests; 159
+  pass across every runnable suite, plus type-check, lint, bundles, regression, skill validation,
+  and a real CLI run producing JUnit.
+  → [`Docs/to-be-built/agent-workbench-slice-5e.md`](Docs/to-be-built/agent-workbench-slice-5e.md)
+- **Agent Workbench Slice 5c — judge execution and the result contract** (2026-08-10) — **done,
+  one deliverable deferred.** A `judge` statement now runs its judge and produces a verdict.
+  The design that carries it: **the model is never asked for an overall result** — it rules on
+  each expectation and quotes evidence, and Norn computes `passed`, checks one ruling per
+  expectation with indexes in range, and verifies each quote occurs in the judged text. A judge
+  is an ordinary agent invocation; everything judge-specific lives in a derived definition, so
+  there is no judge runtime and no `if (isJudge)` in the runner. `builtInContracts` generalises
+  "a contract that lives in code" and rides the existing generation/validation path.
+  A provider or contract failure sets an error and no verdict, so "the judge said no" never
+  reads like "the judge never answered". **A failed judge stops the sequence**, the same as a
+  failed `assert` — it is the concluding check on an orchestration, so later steps must not run
+  on a disproved premise; the run is still recorded and replayable. A malformed reply *shape* is
+  corrected up to `contract_retries` via the opt-in `retryReturnsContract` (off for `run
+  <Agent>`); the verdict itself is never re-rolled. Evidence that cannot be found in the judged
+  text is flagged and still passes — strictness is intended to become per-expectation, not
+  global. **Deferred:** the automatic replay drift check —
+  `expectationsHash` is recorded and diffable, but pure replay never re-reads the `.norn`, so
+  the comparison needs `runLineNumber` plumbing and lands with 5d, which owns the policy.
+  Fixed along the way: judge hops reported false prompt drift on every replay. 18 new focused
+  tests; 141 pass across every runnable suite, plus type-check, lint, bundles, regression, skill
+  validation, and a real CLI run against a deterministic judge server.
+  → [`Docs/to-be-built/agent-workbench-slice-5c.md`](Docs/to-be-built/agent-workbench-slice-5c.md)
+- **Agent Workbench Slice 5a — eval authoring** (2026-08-10) — **done.**
+  `judge <subject> with <Agent> expects "…"` in `.norn` sequences — **one line, like `assert`**,
+  with `expects file <path>` for a list. Built as a `judge … end judge` block first and reworked
+  on Peter's correction: the sequence is the orchestrator, so it stays a flat list of steps
+  rather than nesting a mini-language. Expectations are ordinary Norn strings, file lists resolve
+  at parse time with per-expectation origins, plus eleven `judge-*` diagnostics, grammar,
+  completions, hover, and CLI/JSON step output. Driven by Peter's answer that the first eval is a
+  checklist — all expectations must be met, exceeding them is not a failure. Reuse held:
+  expectation strings go through `agentPromptBlock.ts`'s existing escaping rather than a second
+  stack, one shared module serves runner/diagnostics/completions/hover, and statements validate
+  in the existing agent preflight so a malformed eval cannot spend a model call. A judge step
+  reports as explicitly *not judged* until 5c rather than silently passing. 15 new focused tests;
+  123 pass across every runnable suite, plus type-check, lint, bundles, regression, and skill
+  validation.
+  → [`Docs/to-be-built/agent-workbench-slice-5a.md`](Docs/to-be-built/agent-workbench-slice-5a.md)
+- **Agent Workbench Slice 4** (2026-08-09) — **done and reviewed.**
+  Default-on, secret-safe recordings under `.norn-cache/runs`; fixed 20-run retention;
+  byte-identical offline replay with zero provider/MCP side effects; strict CLI replay with JSON,
+  environment restoration, graph-drift failure, and live `--from`; agent frames/scopes,
+  breakpoints, stepping, and contract-failure navigation in the existing DAP; paused-hop canvas
+  highlighting and validated node-to-invocation navigation. Review: replay is a clean
+  `AgentProviderAdapter` with no runtime special-casing; the debugger is the existing DAP session
+  extended, not a second one; secrets are stable placeholders re-substituted from `.nornenv` at
+  replay time behind a preflight that fails naming the missing variables; and the debugger became
+  the third surface consuming the shared `agentHopPresentation` helper. 55 focused tests pass
+  across all agent suites, plus type-check, lint, and bundle build.
+  → [`Docs/to-be-built/agent-workbench-slice-4.md`](Docs/to-be-built/agent-workbench-slice-4.md)
+- **Agent Workbench Slice 3** (2026-08-09) — **done and reviewed.**
+  Read-only VS Code agent canvas with parser-first static graphs, redacted live/completed trace
+  overlays, deterministic cycle-safe layout, first-class contract states, hover/copy payloads,
+  source navigation, command and CodeLens entry points, and shared response-panel presentation.
+  Recovery resolves successful correction invocations rather than trusting a flag. Review: the
+  shared `agentHopPresentation` helper is consumed by both the canvas and the response panel so
+  they cannot drift; the trace is redacted before anything reads it; CSP is `default-src 'none'`
+  with nonce'd scripts and no external hosts; no graph library was added; the panel never writes.
+  43 focused tests pass across all agent suites, plus type-check, lint, and bundle build.
+  → [`Docs/to-be-built/agent-workbench-slice-3.md`](Docs/to-be-built/agent-workbench-slice-3.md)
+- **Agent Workbench Slice 2** (2026-08-08) — **done and reviewed.**
+  Model-directed agent-as-tool delegation, two-way boundary correction, subtree conversations,
+  configurable spend guards, recursive CLI/JSON/response-panel traces, language tooling, docs,
+  and a deterministic violate → correct → pass demo. Review: sub-agents go through the same tool
+  path as MCP tools, config precedence is agent → provider → global → built-in, parallel tool use
+  is disabled on both adapters, and the runner was extracted to `src/agents/agentRunner.ts` rather
+  than growing `sequenceRunner`. 32 focused tests pass; the language suite needs the VS Code host.
+  `max_tokens` default stays 16000 — a real OpenAI model rejected 32000 and reported a 16384
+  cap, so the generous default was walked back; raise it per-provider where a model allows it.
+  → [`Docs/to-be-built/agent-workbench-slice-2.md`](Docs/to-be-built/agent-workbench-slice-2.md)
+- **Agent Workbench Slice 1** (2026-08-08) — **done and verified running by Peter.**
+  `.nornagent` definitions, linear agent `run` handoffs, OpenAI/local/Anthropic/Google adapters,
+  MCP tools, automatic boundary contracts, live CLI + JSON traces, language tooling, focused
+  tests, and a runnable demo. Reviewed: reuse held (contracts go through `matchesSchema` and the
+  existing Contract View path), provider interface held (Google landed later as a pure new file).
+  → [`Docs/to-be-built/agent-workbench-slice-1.md`](Docs/to-be-built/agent-workbench-slice-1.md)
+- **Website k8s de-promotion** (2026-08-07) — promo surfaces stripped and deployed; docs
+  and functionality untouched. Was Phase 0 of the marketing plan.
+
+---
+_Last updated: 2026-08-10_

package/README.md

@@ -1,6 +1,6 @@
 # Norn
 
-Norn keeps API tests, database checks, and Kubernetes runbooks in repeatable, version-controlled files your whole team can trust. Author, inspect, and debug them in VS Code, then run the same files from the CLI and CI.
+Norn keeps API tests and database checks in repeatable, version-controlled files your whole team can trust. Author, inspect, and debug them in VS Code, then run the same files from the CLI and CI.
 
 ### Simple API Requests
 
@@ -27,7 +27,7 @@ That means you can:
 - `.nornenv` files for environments and secrets
 - `.nornapi` files for reusable endpoint definitions
 - `.nornsql` files for database queries and commands
-- `.nornk8s` files for Kubernetes commands and runbooks
+- `.nornagent` files for contract-checked AI agents and model-directed delegation
 - syntax highlighting, IntelliSense, and diagnostics
 - response inspection, JSON diffing, and click-to-generate assertions
 - tagged and parameterized test execution in VS Code and the CLI
@@ -64,7 +64,6 @@ Use Norn to:
 - run a whole sequence from the editor
 - debug a sequence with breakpoints
 - run test sequences from the Testing view
-- inspect live Kubernetes pods and logs from `.nornk8s` files
 
 ## In The CLI
 
@@ -73,35 +72,8 @@ The CLI uses the same execution model as the extension, so local runs and CI run
 ```bash
 npm install -g norn-cli
 norn ./tests/smoke.norn -e dev
-norn ./runbooks/triage.nornk8s --context prelive
 ```
 
-## Kubernetes Runbooks
-
-`.nornk8s` files turn common kubectl triage commands into reusable runbooks. Standalone
-`get pods`, `describe pod`, and `logs` commands open styled VS Code views with live pod
-and log updates. Helper sequences run explicitly, while `runbook sequence` blocks are
-automatic CLI entry points.
-
-```nornk8s
-namespace {{ordersNs}}
-
-get pods
-logs orders-api-7d9f --tail 500
-
-sequence RestartOrders
-    restart deployment/orders-api
-end sequence
-
-runbook sequence ClusterCheck
-    get pods
-    get pods -n kube-system
-end sequence
-```
-
-Select a Kubernetes context from the VS Code context lens or pass `--context` to the
-CLI. Restart commands require a VS Code confirmation or CLI `--yes`.
-
 ## `.nornenv` Templates And Extends
 
 Use `[template:name]` sections for reusable environment building blocks, then compose selectable `[env:name]` sections with `extends`. Only templates can be extended. Templates are not selectable from the VS Code environment picker or CLI; only `[env:...]` names can be used with `-e`.
@@ -180,13 +152,163 @@ Behavior:
 - Tool `structuredContent` is validated against the MCP tool's advertised `outputSchema` when present.
 - Sessions are closed automatically when the outermost sequence finishes or fails.
 
+## Contract-Checked Agent Graphs
+
+Define agents in an imported `.nornagent` sidecar. An agent can grant another
+agent through `agents`; the callee then appears to the calling model as an
+ordinary tool. Its `accepts` schema constrains and validates the generated tool
+input, and its `returns` schema validates the result before it travels back up
+the graph.
+
+A `model` block declares the provider, the provider's model, and where the API key
+comes from. Nothing is implied by convention: `apiKey` points at a `.nornenv`
+variable, so the file says exactly which value it needs and the secret itself never
+leaves the environment.
+
+```nornagent
+model Workbench
+    provider openai          # openai, anthropic, google, or local
+    name gpt-4o
+    apiKey {{$env.OPENAI_API_KEY}}
+    # baseUrl {{$env.OPENAI_BASE_URL}}   # optional; required for local
+end model
+
+agent DomainExpert
+    model Workbench
+    describe "Call for domain questions and include the ticket context."
+    accepts contracts/domain-question.schema.json
+    returns contracts/domain-answer.schema.json
+    system "Answer only the supplied domain question."
+end agent
+
+agent TicketRouter
+    model Workbench
+    agents DomainExpert
+    system "Consult the domain expert when the ticket needs it."
+end agent
+```
+
+A prompt that outgrows its sidecar can live in its own file instead. `describe`
+and `system` both accept `file <path>`, resolved relative to the `.nornagent`
+file just like an import:
+
+```nornagent
+agent TicketRouter
+    model Workbench
+    agents DomainExpert
+    system file prompts/ticket-router.md
+end agent
+```
+
+The file's text is the prompt verbatim — no escaping, so quotes and backslashes
+stay as written — and `{{...}}` references in it resolve exactly as they do
+inline. A missing or empty prompt file is a parse error on the directive line.
+
+Run the graph from an ordinary sequence; the same nested contract and retry
+trace appears in VS Code and the CLI:
+
+```norn
+import "./agents.nornagent"
+
+test sequence RouteTicket
+    var ticket = run readJson "./ticket.json"
+    var verdict = run TicketRouter ticket
+    assert verdict.text exists
+end sequence
+```
+
+Malformed handoffs are returned to the calling model as field-level tool errors
+so it can correct them. The default guardrails are depth 5, 25 total agent
+invocations, and a two-failed-attempt contract cap. Configure them globally,
+per provider, or on an individual agent (most specific wins):
+
+```json
+{
+    "version": 1,
+    "agents": {
+        "max_tokens": 16000,
+        "max_depth": 5,
+        "max_invocations": 25,
+        "contract_retries": 2,
+        "recording": { "enabled": true },
+        "providers": {
+            "local": { "max_tokens": 4096 }
+        }
+    }
+}
+```
+
+`max_tokens` is an output ceiling, not prepaid usage: raising it does not spend
+tokens by itself. Depth, invocation, and retry limits can permit additional
+model calls, so tighten those three when controlling run cost. See the runnable
+[`demos/agent-workbench`](./demos/agent-workbench) example for delegation and a
+visible contract correction.
+
+Every sequence run that reaches an agent is recorded under
+`.norn-cache/runs/` by default, with a rolling cap of 20 files. Recordings hold
+the resolved provider request, response, tool transcript, contracts,
+conversation state, and ordered hop events. Values declared as secrets in
+`.nornenv` are written as stable named placeholders and restored from the
+selected environment when replay starts; a missing value stops replay before a
+provider or tool can run. Set `agents.recording.enabled` to `false` to disable
+automatic recording.
+
+Replay a recording without model calls, MCP calls, or other sequence side
+effects using the local CLI:
+
+```bash
+node ./dist/cli.js replay .norn-cache/runs/<recording>.json
+node ./dist/cli.js replay .norn-cache/runs/<recording>.json --json
+node ./dist/cli.js replay .norn-cache/runs/<recording>.json --from CriteriaComparer
+```
+
+Pure replay reproduces the stored trace and exits non-zero for failed hops or
+contracts, so a deliberately copied recording can be used as a no-key CI
+fixture. `--from` accepts a unique agent name or canonical path such as
+`TicketRouter[1]/CriteriaComparer[1]`; the prefix stays replayed and that hop
+onward runs live against the current graph.
+
+**Norn: Show Agent Graph**, or the CodeLens on any agent block, draws the graph
+for a `.nornagent` file: who calls whom, the `accepts`/`returns` contract on each
+boundary, and how each one turned out. Hover an agent or a boundary for the full
+detail — models, timings, usage, prompts, payloads, contract issues.
+
+The graph's toolbar also lists the project's recorded runs, each labelled with the
+`.norn` file it came from. Pick one to see how it finished, or press **Play run**
+to watch it unfold hop by hop on the canvas. Playback replays the recording's own
+events, so nothing re-executes and no model is called; press **Stop** to jump to
+the end. A run from a file the open one took no part in is drawn from that
+recording alone — the toolbar says which file it came from, and **This file —
+current view** returns you to the open file, ready for its next live run.
+Recording is on by default and keeps the last 20 runs under `.norn-cache/runs/`.
+
+To step a recording in VS Code, use the existing `norn` debugger and add the
+artifact to a launch configuration:
+
+```json
+{
+    "type": "norn",
+    "request": "launch",
+    "name": "Replay RouteTicket",
+    "file": "${workspaceFolder}/route-ticket.norn",
+    "sequence": "RouteTicket",
+    "recording": "${workspaceFolder}/fixtures/route-ticket-run.json",
+    "stopOnEntry": true
+}
+```
+
+Agent calls appear as nested frames with Request, Response, Contracts, and
+Conversation scopes. Normal step controls navigate the recorded hop timeline;
+**Norn Debug: Run to Next Contract Failure** stops on retry violations as well
+as final contract failures. With Agent Graph open, the paused invocation is
+highlighted and selecting a node moves the replay cursor to that invocation.
+
 ## Good Fit For
 
 - backend teams validating APIs during development
 - QA and automation work that needs readable test flows
 - regression and smoke suites that should run the same way locally and in CI
 - projects that want API requests and API tests to live next to the code
-- teams that want repeatable Kubernetes triage runbooks beside their services
 
 Diff preview test line.
 

package/demos/agent-workbench/README.md

@@ -0,0 +1,156 @@
+# Agent Workbench Slice 2
+
+This demo includes the Slice 1 linear graph and a Slice 2 model-driven graph.
+`TicketRouter` decides which domain experts to invoke as tools, while Norn
+contract-checks both sides of every handoff. It uses no MCP server. The checked-in
+model declaration uses OpenAI, but you can swap it to Google, Anthropic, or an
+OpenAI-compatible local runtime (subject to each model's tool/structured-output
+support).
+
+The checked-in [`norn.config.json`](./norn.config.json) spells out the runtime
+defaults used by the demo: 16,000 output tokens for hosted providers, 4,096 for
+`local`, depth 5, 25 total invocations, and 2 failed contract attempts.
+Agent recording is enabled by default and keeps the latest 20 artifacts under
+`.norn-cache/runs/`.
+
+## Run it
+
+Build the local CLI, export a key, then run the local build:
+
+```bash
+npm run compile
+export OPENAI_API_KEY="your-key"
+node ./dist/cli.js demos/agent-workbench/workbench.norn --sequence HappyPath
+```
+
+The variable name is not a convention Norn assumes — it is written in the model
+block in [agents.nornagent](./agents.nornagent) as `apiKey {{$env.OPENAI_API_KEY}}`,
+so any name works as long as the file and the environment agree.
+
+Alternatively, store `OPENAI_API_KEY` as a secret under `[env:openai]` in a
+local `.nornenv`. Norn gives the selected `.nornenv` values precedence over
+process environment variables; add `--env openai` to the commands in that case.
+
+`HappyPath` runs `TicketReader -> CriteriaComparer -> Responder`. The first two
+agents produce structured output; `accepts` checks each incoming handoff and
+`returns` checks each outgoing handoff. The final result remains available to
+ordinary Norn assertions and interpolation through `verdict.body` and
+`reply.text`.
+
+## Demonstrate model-driven delegation and correction
+
+```bash
+node ./dist/cli.js demos/agent-workbench/workbench.norn --sequence DelegatedRouting
+```
+
+`TicketRouter` consults `FrontendExpert` and `BackendExpert`. Its prompt is the
+longest in the graph, so it lives in
+[`prompts/ticket-router.md`](./prompts/ticket-router.md) and is pulled in with
+`system file prompts/ticket-router.md`. The file's text is the prompt verbatim,
+which is why the quoted instructions there need no escaping. For the checked-in
+`DEMO-201` fixture, its instructions deliberately make the first backend
+question omit the contract-only `DOMAIN QUESTION:` prefix. That `pattern` is
+removed from the provider's generation schema but remains in Norn's untouched
+validation contract, so the calling model receives the exact field-level error,
+retries with conforming input, and completes. The human trace shows the nested
+agents and `retry 1/2 — model corrected the call`; `--json` preserves the same
+graph under each hop's `children` array.
+
+For a deterministic, no-key proof of the exact violate → correct → pass
+trace, start the checked-in OpenAI-compatible demo server in one terminal:
+
+```bash
+node demos/agent-workbench/fake-openai-server.js
+```
+
+Then run the normal demo from another terminal:
+
+```bash
+OPENAI_BASE_URL=http://127.0.0.1:18766/v1 \
+OPENAI_API_KEY=demo \
+node ./dist/cli.js demos/agent-workbench/workbench.norn --sequence DelegatedRouting
+```
+
+The fake server is only a deterministic demo fixture. Normal runs continue to
+use the model declared in `agents.nornagent` and the provider credentials below.
+
+To inspect the machine-readable run artifact:
+
+```bash
+node ./dist/cli.js demos/agent-workbench/workbench.norn --sequence DelegatedRouting --json
+```
+
+After either run, replay its newest `.norn-cache/runs/*.json` artifact without
+the fake server, an API key, or any model/tool side effects:
+
+```bash
+node ./dist/cli.js replay .norn-cache/runs/<recording>.json
+node ./dist/cli.js replay .norn-cache/runs/<recording>.json --from BackendExpert
+```
+
+The first command is fully offline. The second replays everything before the
+selected hop and then switches to the currently configured live provider from
+that hop onward.
+
+## Demonstrate a broken handoff
+
+```bash
+node ./dist/cli.js demos/agent-workbench/workbench.norn --sequence ContractFailure
+```
+
+The failure fixture asks `CriteriaComparer` for the summary `deliberately
+invalid`, while the untouched contract permits only `aligned` or `drift found`.
+The provider-generation schema omits the unsupported `pattern` constraint, but
+Norn then validates the parsed output against the full schema. The run should
+therefore fail at `summary`, retain the raw model text, and exit non-zero.
+
+Model output is nondeterministic. If the model declines the deliberate bad-output
+instruction, rerun the failure sequence or use the injected mock adapter in a
+focused runtime test for deterministic automation.
+
+## Swap the model
+
+Edit the one `model Workbench` block in
+[agents.nornagent](./agents.nornagent). Every agent references the alias, so the
+whole graph moves together:
+
+```nornagent
+model Workbench
+    provider openai
+    name gpt-4o
+    apiKey {{$env.OPENAI_API_KEY}}
+end model
+```
+
+The other providers, with the variable names this demo assumes. `apiKey` and
+`baseUrl` accept any `.nornenv` variable — these are only the conventional names:
+
+```nornagent
+model Workbench
+    provider google              # native Gemini Developer API, never Vertex AI
+    name gemini-3-flash-preview
+    apiKey {{$env.GOOGLE_API_KEY}}
+end model
+
+model Workbench
+    provider anthropic
+    name claude-sonnet-4-6
+    apiKey {{$env.ANTHROPIC_API_KEY}}
+end model
+
+model Workbench
+    provider local               # any OpenAI-compatible runtime
+    name qwen3-coder
+    baseUrl {{$env.LOCAL_BASE_URL}}   # required for local
+    apiKey {{$env.LOCAL_API_KEY}}     # optional
+end model
+```
+
+Omitting `apiKey` falls back to each provider's conventional variable
+(`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY` or `GEMINI_API_KEY`) and
+then to the vendor SDK's own credential chain. Declaring it is preferred — it is
+the difference between a file that documents what it needs and one that fails at
+the provider call. For Google, `baseUrl` is only for a compatible proxy: leave it
+unset for normal use and never paste a full `:generateContent` operation URL.
+
+There is no CLI model override: the authored graph stays the source of truth.