norn-cli 3.3.0 → 4.0.1

package/demos/agent-workbench/README.md

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

package/demos/agent-workbench/agents.nornagent

@@ -1,87 +0,0 @@
-# Agent Workbench Slice 2 demo
-#
-# Swap this block to compare the same graph on another model. Nothing is implied:
-# the provider, the model, and the variable holding the key are all named here.
-# apiKey points at a .nornenv variable — run with --env to select the environment.
-model Workbench
-    provider openai
-    name gpt-4o
-    apiKey {{$env.OPENAI_API}}
-end model
-
-agent TicketReader
-    model Workbench
-    accepts "contracts/ticket.schema.json"
-    returns "contracts/ticket.schema.json"
-    system "
-    Normalize the supplied ticket into the required JSON structure.
-    Preserve the ticket's meaning and every acceptance criterion.
-    Return JSON only.
-    "
-end agent
-
-agent CriteriaComparer
-    model Workbench
-    accepts contracts/ticket.schema.json
-    returns contracts/verdict.schema.json
-    system "
-    Compare implementationNotes with acceptanceCriteria.
-    Return drifted=false with no findings when every criterion is covered.
-    Otherwise return drifted=true and one finding per uncovered criterion.
-    Use only low, medium, or high for finding severity.
-
-    For the explicit contract-failure fixture, whose implementationNotes begin
-    with DEMO_INVALID_OUTPUT, set summary exactly to deliberately invalid.
-    This instruction exists only to demonstrate Norn's full post-generation
-    contract check: the generation adapter intentionally cannot enforce the
-    schema's pattern keyword.
-    "
-end agent
-
-agent Responder
-    model Workbench
-    accepts contracts/verdict.schema.json
-    system "
-    Turn the verdict into a short neutral message for the developer.
-    Use no preamble and do not invent findings.
-    "
-end agent
-
-agent FrontendExpert
-    model Workbench
-    describe "
-    Call when a ticket may affect browser or client-facing behaviour. Give it
-    the complete ticket and one specific frontend question.
-    "
-    accepts contracts/domain-question.schema.json
-    returns contracts/domain-answer.schema.json
-    system "
-    You own the frontend domain. Answer only the supplied question. Identify
-    concrete checks without inventing requirements.
-    "
-end agent
-
-agent BackendExpert
-    model Workbench
-    describe "
-    Call when a ticket may affect APIs, services, persistence, or server-side
-    behaviour. Give it the complete ticket and one specific backend question.
-    "
-    accepts contracts/domain-question.schema.json
-    returns contracts/domain-answer.schema.json
-    system "
-    You own the backend domain. Answer only the supplied question. Identify
-    concrete checks without inventing requirements.
-    "
-end agent
-
-agent TicketRouter
-    model Workbench
-    accepts "contracts/ticket.schema.json"
-    returns "contracts/router-verdict.schema.json"
-    agents FrontendExpert, BackendExpert
-    # The longest prompt in this graph lives in its own Markdown file. The path is
-    # relative to this sidecar, and the file's text is the prompt verbatim — quotes
-    # need no escaping at all, which is why this one is easier to read there.
-    system file prompts/ticket-router.md
-end agent

package/demos/agent-workbench/contracts/domain-answer.schema.json

@@ -1,28 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Domain consultation answer",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "domain",
-    "affected",
-    "checks",
-    "rationale"
-  ],
-  "properties": {
-    "domain": {
-      "type": "string",
-      "enum": ["frontend", "backend"]
-    },
-    "affected": {
-      "type": "boolean"
-    },
-    "checks": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "rationale": {
-      "type": "string"
-    }
-  }
-}

package/demos/agent-workbench/contracts/domain-question.schema.json

@@ -1,34 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Domain consultation question",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "ticket",
-    "question"
-  ],
-  "properties": {
-    "ticket": {
-      "type": "object",
-      "required": [
-        "id",
-        "title",
-        "acceptanceCriteria",
-        "implementationNotes"
-      ],
-      "properties": {
-        "id": { "type": "string" },
-        "title": { "type": "string" },
-        "acceptanceCriteria": {
-          "type": "array",
-          "items": { "type": "string" }
-        },
-        "implementationNotes": { "type": "string" }
-      }
-    },
-    "question": {
-      "type": "string",
-      "pattern": "^DOMAIN QUESTION: .+"
-    }
-  }
-}

package/demos/agent-workbench/contracts/router-verdict.schema.json

@@ -1,43 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Domain routing verdict",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "domains",
-    "consultations",
-    "summary"
-  ],
-  "properties": {
-    "domains": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["frontend", "backend"]
-      }
-    },
-    "consultations": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["domain", "affected", "checks", "rationale"],
-        "properties": {
-          "domain": {
-            "type": "string",
-            "enum": ["frontend", "backend"]
-          },
-          "affected": { "type": "boolean" },
-          "checks": {
-            "type": "array",
-            "items": { "type": "string" }
-          },
-          "rationale": { "type": "string" }
-        }
-      }
-    },
-    "summary": {
-      "type": "string"
-    }
-  }
-}

package/demos/agent-workbench/contracts/ticket.schema.json

@@ -1,29 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Demo ticket",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "id",
-    "title",
-    "acceptanceCriteria",
-    "implementationNotes"
-  ],
-  "properties": {
-    "id": {
-      "type": "string"
-    },
-    "title": {
-      "type": "string"
-    },
-    "acceptanceCriteria": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "implementationNotes": {
-      "type": "string"
-    }
-  }
-}

package/demos/agent-workbench/contracts/verdict.schema.json

@@ -1,48 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Acceptance criteria verdict",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "drifted",
-    "findings",
-    "summary"
-  ],
-  "properties": {
-    "drifted": {
-      "type": "boolean"
-    },
-    "findings": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": [
-          "criterion",
-          "severity",
-          "message"
-        ],
-        "properties": {
-          "criterion": {
-            "type": "string"
-          },
-          "severity": {
-            "type": "string",
-            "enum": [
-              "low",
-              "medium",
-              "high"
-            ]
-          },
-          "message": {
-            "type": "string"
-          }
-        }
-      }
-    },
-    "summary": {
-      "type": "string",
-      "pattern": "^(aligned|drift found)$"
-    }
-  }
-}

package/demos/agent-workbench/fake-openai-server.js

@@ -1,128 +0,0 @@
-const http = require('http');
-
-const port = Number(process.env.NORN_AGENT_DEMO_PORT || 18766);
-
-function completion(model, message, finishReason) {
-    return {
-        id: `chatcmpl-demo-${Date.now()}`,
-        object: 'chat.completion',
-        created: Math.floor(Date.now() / 1000),
-        model,
-        choices: [{ index: 0, message, finish_reason: finishReason }],
-        usage: { prompt_tokens: 24, completion_tokens: 8, total_tokens: 32 }
-    };
-}
-
-function toolCall(model, name, id, args) {
-    return completion(model, {
-        role: 'assistant',
-        content: null,
-        tool_calls: [{
-            id,
-            type: 'function',
-            function: { name, arguments: JSON.stringify(args) }
-        }]
-    }, 'tool_calls');
-}
-
-function parseJson(value, fallback = {}) {
-    try {
-        return JSON.parse(value);
-    } catch {
-        return fallback;
-    }
-}
-
-function expertAnswer(domain) {
-    return {
-        domain,
-        affected: true,
-        checks: domain === 'frontend'
-            ? ['Render each retry-attempt event without refreshing checkout']
-            : ['Emit retry-attempt events and preserve the final safe error mapping'],
-        rationale: `The ticket explicitly changes ${domain} behaviour.`
-    };
-}
-
-function handleDemoRequest(body) {
-    const schemaName = body.response_format?.json_schema?.name;
-    if (schemaName === 'FrontendExpert_return') {
-        return completion(body.model, {
-            role: 'assistant',
-            content: JSON.stringify(expertAnswer('frontend'))
-        }, 'stop');
-    }
-    if (schemaName === 'BackendExpert_return') {
-        return completion(body.model, {
-            role: 'assistant',
-            content: JSON.stringify(expertAnswer('backend'))
-        }, 'stop');
-    }
-
-    const messages = body.messages || [];
-    const tools = body.tools || [];
-    const frontendTool = tools.find(tool => tool.function?.name?.includes('FrontendExpert'))?.function?.name;
-    const backendTool = tools.find(tool => tool.function?.name?.includes('BackendExpert'))?.function?.name;
-    if (!frontendTool || !backendTool) {
-        return completion(body.model, { role: 'assistant', content: 'missing demo tools' }, 'stop');
-    }
-
-    const userMessage = messages.find(message => message.role === 'user');
-    const ticket = parseJson(String(userMessage?.content || '{}'));
-    const toolMessages = messages.filter(message => message.role === 'tool');
-    const lastToolContent = String(toolMessages.at(-1)?.content || '');
-
-    if (toolMessages.length === 0) {
-        return toolCall(body.model, frontendTool, 'demo-frontend', {
-            ticket,
-            question: 'DOMAIN QUESTION: What must the checkout client verify?'
-        });
-    }
-    if (lastToolContent.includes('"domain":"frontend"')) {
-        return toolCall(body.model, backendTool, 'demo-backend-invalid', {
-            ticket,
-            question: 'Does this affect backend services?'
-        });
-    }
-    if (lastToolContent.includes('"error"')) {
-        return toolCall(body.model, backendTool, 'demo-backend-corrected', {
-            ticket,
-            question: 'DOMAIN QUESTION: What must the payment service verify?'
-        });
-    }
-
-    return completion(body.model, {
-        role: 'assistant',
-        content: JSON.stringify({
-            domains: ['frontend', 'backend'],
-            consultations: [expertAnswer('frontend'), expertAnswer('backend')],
-            summary: 'The ticket crosses the checkout client and payment service boundary.'
-        })
-    }, 'stop');
-}
-
-const server = http.createServer((request, response) => {
-    if (request.method !== 'POST' || !request.url.endsWith('/chat/completions')) {
-        response.writeHead(404).end();
-        return;
-    }
-
-    let raw = '';
-    request.setEncoding('utf8');
-    request.on('data', chunk => { raw += chunk; });
-    request.on('end', () => {
-        try {
-            const result = handleDemoRequest(JSON.parse(raw));
-            response.writeHead(200, { 'content-type': 'application/json' });
-            response.end(JSON.stringify(result));
-        } catch (error) {
-            response.writeHead(500, { 'content-type': 'application/json' });
-            response.end(JSON.stringify({ error: String(error) }));
-        }
-    });
-});
-
-server.listen(port, '127.0.0.1', () => {
-    process.stdout.write(`Deterministic Agent Workbench demo listening on http://127.0.0.1:${port}/v1\n`);
-});
-process.on('SIGTERM', () => server.close(() => process.exit(0)));

package/demos/agent-workbench/fixtures/aligned-ticket.json

@@ -1,10 +0,0 @@
-{
-  "id": "DEMO-101",
-  "title": "Retry transient payment failures",
-  "acceptanceCriteria": [
-    "Retry HTTP 429 and 5xx responses up to three times",
-    "Wait 500 milliseconds between attempts",
-    "Do not retry HTTP 4xx responses other than 429"
-  ],
-  "implementationNotes": "The client retries 429 and 5xx responses up to three times with a fixed 500 millisecond delay. Other 4xx responses are returned immediately."
-}

package/demos/agent-workbench/fixtures/cross-domain-ticket.json

@@ -1,10 +0,0 @@
-{
-  "id": "DEMO-201",
-  "title": "Show live payment retry state in checkout",
-  "acceptanceCriteria": [
-    "The API retries transient payment failures up to three times",
-    "Checkout shows the current retry attempt without a page refresh",
-    "The final failure message is consistent in the API and browser"
-  ],
-  "implementationNotes": "The payment service now emits retry-attempt events and the checkout client subscribes to them to update its status panel. The final API error is mapped to the same customer-safe message displayed by the client."
-}

package/demos/agent-workbench/fixtures/invalid-output-ticket.json

@@ -1,8 +0,0 @@
-{
-  "id": "DEMO-102",
-  "title": "Show a contract-checked agent boundary",
-  "acceptanceCriteria": [
-    "The comparer output must satisfy the verdict contract"
-  ],
-  "implementationNotes": "DEMO_INVALID_OUTPUT: return the deliberately invalid summary requested by the system prompt so post-generation validation reports the exact field mismatch."
-}

package/demos/agent-workbench/norn.config.json

@@ -1,15 +0,0 @@
-{
-  "version": 1,
-  "agents": {
-    "max_tokens": 16000,
-    "max_depth": 5,
-    "max_invocations": 25,
-    "max_turns": 100,
-    "contract_retries": 2,
-    "providers": {
-      "local": {
-        "max_tokens": 4096
-      }
-    }
-  }
-}

package/demos/agent-workbench/prompts/ticket-router.md

@@ -1,11 +0,0 @@
-Decide which domains the ticket touches. Consult only relevant domain
-agents, one at a time, and combine their answers into the required verdict.
-
-Every valid consultation question starts with "DOMAIN QUESTION: ". For
-ticket DEMO-201, call FrontendExpert with that prefix. On the first
-BackendExpert call, deliberately send the question "Does this affect
-backend services?" without the prefix. The provider generation schema does
-not include the contract-only pattern, so Norn will return the exact
-validation error as the tool result. Retry BackendExpert with the prefix,
-then use the successful answer. This one deliberate mistake demonstrates a
-typed, model-initiated handoff correcting itself.

package/demos/agent-workbench/workbench.norn

@@ -1,32 +0,0 @@
-import "./agents.nornagent"
-
-test sequence HappyPath
-    var fixture = run readJson "./fixtures/aligned-ticket.json"
-
-
-    var ticket = run TicketReader fixture
-    var verdict = run CriteriaComparer ticket
-    var reply = run Responder verdict
-
-    assert verdict.body.drifted == false
-    print "Reply" | "{{reply.text}}"
-end sequence
-
-test sequence ContractFailure
-    var fixture = run readJson "./fixtures/invalid-output-ticket.json"
-
-    var ticket = run TicketReader fixture
-    var verdict = run CriteriaComparer ticket
-
-    print "Raw comparer output" | "{{verdict.text}}"
-end sequence
-
-test sequence DelegatedRouting
-    var fixture = run readJson "./fixtures/cross-domain-ticket.json"
-
-    var verdict = run TicketRouter fixture
-
-    assert verdict.body.domains contains "frontend"
-    assert verdict.body.domains contains "backend"
-    print "Routing verdict" | "{{verdict.text}}"
-end sequence