@north-light/crouter 0.3.154

package/dist/pi-extensions/canvas-structured-output.d.ts

@@ -0,0 +1,9 @@
+type PiEvents = 'before_agent_start' | 'agent_start';
+interface PiLike {
+    on: (event: PiEvents, handler: (event: any, ctx: any) => void | Promise<void>) => void;
+    registerTool: (definition: Record<string, unknown>) => void;
+    getActiveTools?: () => string[];
+    setActiveTools?: (tools: string[]) => void;
+}
+export declare function registerCanvasStructuredOutput(pi: PiLike): void;
+export default registerCanvasStructuredOutput;

package/dist/pi-extensions/canvas-structured-output.js

@@ -0,0 +1,155 @@
+// canvas-structured-output.ts — dynamic `submit` tool for schema-shaped node results.
+//
+// Loaded into every canvas node. Inert unless nodes/<id>/output-schema.json exists.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { FinalizationError, pushFinal, pushUpdate } from '../core/feed/feed.js';
+import { outputResultPath, readOutputRequest, removeOutputSchema, } from '../core/runtime/structured-output.js';
+function reportBody(resultPath, json) {
+    return `Structured output submitted.\n\nResult path: ${resultPath}\n\n\`\`\`json\n${json}\n\`\`\`\n`;
+}
+function activateTool(pi) {
+    try {
+        const current = pi.getActiveTools?.() ?? [];
+        if (!current.includes('submit'))
+            pi.setActiveTools?.([...current, 'submit']);
+    }
+    catch {
+        /* best-effort; registration refresh normally activates new extension tools */
+    }
+}
+function retireTool(pi) {
+    try {
+        const current = pi.getActiveTools?.() ?? [];
+        pi.setActiveTools?.(current.filter((name) => name !== 'submit'));
+    }
+    catch {
+        /* best-effort; the execute handler is inert when no schema file exists */
+    }
+}
+function toolDescription(request) {
+    if (request.mode === 'terminal') {
+        return 'Submit your final structured result. Calling this ends your run: the result is recorded and a final report is pushed automatically — do NOT call `crtr push final` yourself.';
+    }
+    return 'Submit the requested one-off structured result. Calling this records the result, pushes an update report automatically, frees you from the structured-output gate, and lets you continue working.';
+}
+export function registerCanvasStructuredOutput(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return;
+    let registeredKey = null;
+    let active = false;
+    const ensureSubmitTool = (activate) => {
+        const request = readOutputRequest(nodeId);
+        if (request === null) {
+            if (active) {
+                active = false;
+                retireTool(pi);
+            }
+            return;
+        }
+        const key = JSON.stringify(request);
+        if (registeredKey !== key) {
+            pi.registerTool({
+                name: 'submit',
+                label: 'Submit',
+                description: toolDescription(request),
+                promptSnippet: request.mode === 'terminal'
+                    ? 'Submit the final structured result and end this node'
+                    : 'Submit the requested one-off structured result',
+                promptGuidelines: request.mode === 'terminal'
+                    ? [
+                        'Use submit as your final action when the required structured result is ready.',
+                        'After calling submit, do not call crtr push final yourself and do not emit another assistant response.',
+                    ]
+                    : [
+                        'Use submit to answer the pending one-off structured-output request before stopping or going dormant.',
+                        'After one-off submit succeeds, continue with any remaining work normally.',
+                    ],
+                parameters: request.schema,
+                // pi 0.82 can ask the provider to constrain sampling to the tool's JSON schema.
+                // `prefer` degrades silently on a model without strict tool support (`require`
+                // would fail the whole request); crouter's server-side validation and stop-guard
+                // stay authoritative either way — this only makes a malformed submission rarer.
+                constrainedSampling: { type: 'json_schema', strict: 'prefer' },
+                async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+                    const current = readOutputRequest(nodeId);
+                    if (current === null) {
+                        return {
+                            content: [{ type: 'text', text: 'No structured output is currently requested.' }],
+                            details: { submitted: false, reason: 'no_request' },
+                        };
+                    }
+                    if (JSON.stringify(current) !== key) {
+                        registeredKey = null;
+                        ensureSubmitTool(true);
+                        return {
+                            content: [{ type: 'text', text: 'The structured-output request changed while you were working. Call submit again using the current schema.' }],
+                            details: { submitted: false, reason: 'schema_replaced' },
+                        };
+                    }
+                    const resultPath = outputResultPath(nodeId);
+                    const json = JSON.stringify(params, null, 2);
+                    mkdirSync(dirname(resultPath), { recursive: true });
+                    writeFileSync(resultPath, `${json}\n`, 'utf8');
+                    const body = reportBody(resultPath, json);
+                    if (current.mode === 'terminal') {
+                        try {
+                            await pushFinal(nodeId, body);
+                        }
+                        catch (err) {
+                            if (!(err instanceof FinalizationError && err.code === 'already_finalized'))
+                                throw err;
+                        }
+                        removeOutputSchema(nodeId);
+                        active = false;
+                        retireTool(pi);
+                        try {
+                            ctx?.abort?.();
+                        }
+                        catch { /* ignore */ }
+                        try {
+                            ctx?.shutdown?.();
+                        }
+                        catch { /* ignore */ }
+                        return {
+                            content: [{ type: 'text', text: `Structured output submitted and finalized: ${resultPath}` }],
+                            details: { submitted: true, mode: current.mode, resultPath, result: params },
+                            terminate: true,
+                        };
+                    }
+                    await pushUpdate(nodeId, body);
+                    removeOutputSchema(nodeId);
+                    active = false;
+                    retireTool(pi);
+                    return {
+                        content: [{ type: 'text', text: `Structured output submitted: ${resultPath}` }],
+                        details: { submitted: true, mode: current.mode, resultPath, result: params },
+                    };
+                },
+            });
+            registeredKey = key;
+        }
+        if (activate && !active) {
+            active = true;
+            activateTool(pi);
+        }
+    };
+    try {
+        ensureSubmitTool(false);
+    }
+    catch { /* malformed files are enforced by the stop-guard */ }
+    pi.on('before_agent_start', () => {
+        try {
+            ensureSubmitTool(true);
+        }
+        catch { /* keep the node alive; stop-guard will reprompt */ }
+    });
+    pi.on('agent_start', () => {
+        try {
+            ensureSubmitTool(true);
+        }
+        catch { /* keep the node alive; stop-guard will reprompt */ }
+    });
+}
+export default registerCanvasStructuredOutput;

package/dist/prompts/review.d.ts

@@ -0,0 +1,2 @@
+export declare function specReviewPrompt(specPath: string): string;
+export declare function planReviewPrompt(planPath: string, specPath: string | null): string;

package/dist/prompts/review.js

@@ -0,0 +1,130 @@
+/**
+ * Builds the guidance delivered to spec/plan reviewer agents.
+ *
+ * Why this exists (CTO, 2026-07-03): reviewer agents without calibration
+ * drift to rubber-stamping or nitpicking, so the decision tables force a
+ * real verdict — but the deeper point is that this reviews AGENT-written
+ * work, not generic review. Agents have a specific failure profile: a check
+ * earns a place here only when it targets a mistake agents actually make
+ * (unrequested features, placeholder sections, noise comments), and a check
+ * for something agents reliably get right (e.g. arithmetic/logic
+ * correctness) is pure noise. Maintain the checklists empirically: add a
+ * check when we observe agents failing at something, cut one that never
+ * catches anything.
+ */
+const SUBMIT_INSTRUCTIONS = `## Delivering your review
+
+When your review is complete, deliver your verdict as instructed by
+__CRTR_SUBMIT_INSTRUCTION__
+
+The pane will close automatically once your review is delivered. Do NOT
+summarize or chat after submission — the submit call IS the response.
+
+If you cannot complete the review (file missing, totally malformed, etc.),
+still submit with a brief explanation of why.`;
+export function specReviewPrompt(specPath) {
+    return `You are reviewing a spec document. Verify it is complete and ready for
+planning.
+
+**Spec to review:** ${specPath}
+
+Read the spec end-to-end first.
+
+## What to check
+
+| Category | What to look for |
+|----------|------------------|
+| Completeness | TODOs, placeholders, "TBD", incomplete sections |
+| Consistency | Internal contradictions, conflicting requirements |
+| Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
+| Scope | Focused enough for a single plan |
+| YAGNI | Unrequested features, over-engineering |
+
+For specs with non-trivial component interaction, also walk the primary
+flow from trigger to final state and check whether preconditions, state
+transitions, failure handling, and handoffs between components are
+actually specified. This is the highest-signal check when there are
+seams to fall between — skip it for self-contained specs.
+
+For larger specs touching established patterns, optionally spawn a Task
+agent (\`general-purpose\`, \`sonnet\`) to cross-check the spec's design
+against \`CLAUDE.md\` / \`.claude/rules/*.md\` and the files it references,
+looking for contradictions with project conventions. Skip for small specs.
+
+## Calibration
+
+Approve unless an implementer or planner would be led astray. Real issues:
+missing requirements, contradictory design, unspecified failure modes on
+critical paths, requirements ambiguous enough to be built two ways. Not
+issues: wording preferences, "I'd have organized this differently",
+sections less detailed than others.
+
+## Output
+
+## Spec Review
+
+**Status:** Approved | Issues Found
+
+**Issues (if any):**
+- [Section]: [specific issue] — [why it matters for planning]
+
+**Recommendations (advisory, do not block approval):**
+- [suggestions]
+
+${SUBMIT_INSTRUCTIONS}`;
+}
+export function planReviewPrompt(planPath, specPath) {
+    const inputs = specPath === null
+        ? `**Plan to review:** ${planPath}
+
+No spec was provided for cross-reference — evaluate the plan on its own
+merits (internal completeness, task decomposition, buildability). Skip the
+"Spec Alignment" check.`
+        : `**Plan to review:** ${planPath}
+**Spec for reference:** ${specPath}
+
+Read the plan first, then the spec, then evaluate alignment and the other
+criteria below.`;
+    return `You are reviewing a plan document. Verify it is complete and ready for
+implementation.
+
+${inputs}
+
+## What to check
+
+| Category | What to look for |
+|----------|------------------|
+| Completeness | TODOs, placeholders, incomplete tasks, missing steps |
+${specPath === null ? '' : '| Spec alignment | Plan covers spec requirements, no major scope creep, no unjustified divergence from the spec\'s design |\n'}| Resolved decisions | No "if X then Y" branches, no "investigate whether…", no deferred choices |
+| Buildability | Could an engineer follow this without getting stuck or re-deciding things? |
+| Quality smells | Timelines, "for now" shortcuts, magic values, fallbacks, missing type definitions where the plan creates a new contract |
+
+For medium+ plans that claim parallelizable tasks, also check that tasks
+own disjoint files (or call out unavoidable overlap) and that shared
+types/APIs between tasks have their contracts specified.
+
+For large plans${specPath === null ? '' : ', or when spec coverage feels uncertain'}, you may
+optionally spawn one Task agent (\`general-purpose\`, \`sonnet\`) to
+cross-check ${specPath === null ? 'coverage of the plan\'s own stated phases against its task list' : `spec requirements at \`${specPath}\` against plan tasks`}.
+Skip for small plans.
+
+## Calibration
+
+Approve unless an implementer would build the wrong thing, get stuck, or
+ship something that violates the plan's quality bar. Minor wording,
+stylistic preferences, and "nice to have" reorganizations are NOT issues.
+
+## Output
+
+## Plan Review
+
+**Status:** Approved | Issues Found
+
+**Issues (if any):**
+- [Task / Section]: [specific issue] — [why it matters for implementation]
+
+**Recommendations (advisory, do not block approval):**
+- [suggestions]
+
+${SUBMIT_INSTRUCTIONS}`;
+}

package/dist/prompts/view.d.ts

@@ -0,0 +1,7 @@
+export interface ViewScaffoldVars {
+    id: string;
+    title: string;
+    description: string;
+}
+/** Build every file of a freshly scaffolded dual-target view, keyed by filename. */
+export declare function viewScaffold(v: ViewScaffoldVars): Record<string, string>;

package/dist/prompts/view.js

@@ -0,0 +1,172 @@
+// Scaffold stubs for surface-view authoring. Returns the four files of a dual-target
+// view directory — a portable `core.mjs` plus the TUI / web / text presenters —
+// that runs as-is via the surface view host (TUI/static snapshot) and the surface
+// web server (browser).
+//
+// Authoring guidance lives INSIDE each stub (the comment block at the top of the
+// generated file), so a view author reads the contract right where they edit.
+/** Escape a value for embedding inside a single-quoted JS string literal. */
+function jsStr(s) {
+    return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+/** The portable core: manifest · init · sources · intents. Runs in BOTH Node
+ *  (the TUI host) and the browser (the web bundle) — imports NOTHING. */
+function coreStub(v) {
+    const id = jsStr(v.id);
+    const title = jsStr(v.title);
+    const description = jsStr(v.description);
+    return `// ${v.title} — portable core (manifest · init · sources · intents).
+//
+// Runs in BOTH Node (the TUI host) and the browser (the web bundle), so it
+// imports NOTHING — no \`node:*\`, no crtr. ALL state + behavior live here;
+// presenters (tui.mjs / web.jsx) are pure reads that dispatch named intents.
+//
+//   Run it through the surface view host for TUI/static snapshots, or through
+//   the surface web server for the React + Tailwind browser page.
+//
+// THE CONTRACT:
+//   manifest          { id, title, description, refreshMs? } — id MUST equal
+//                     this view's directory name.
+//   init(opts)        cheap, SYNCHRONOUS initial state — NO fetch, NO screen.
+//                     CLI flags arrive in \`opts\` (for example port/target options).
+//   sources           { request, parse } READ descriptors. The host's transport
+//                     runs request() (exec/file/http) and hands parse() the bytes
+//                     — your parse is pure, runs in Node AND the browser.
+//   intents           semantic actions both targets dispatch. State updates are
+//                     IMMUTABLE via ctx.set; async effects (ctx.resolve a source)
+//                     live in the same handler. ctx.signal raises chrome signals.
+
+/** A READ source: a transport-agnostic request + a pure parse. */
+export const clockSource = {
+  id: 'clock',
+  request: () => ({ kind: 'exec', bin: 'date', args: [] }),
+  parse: (raw) =>
+    raw.ok && raw.exitCode === 0
+      ? { ok: true, data: raw.stdout.trim() }
+      : { ok: false, error: { kind: 'clock-failed', display: {
+          headline: 'Could not read the clock',
+          explanation: raw.stderr || 'the date command failed',
+          nextStep: 'Check the \`date\` binary is on PATH.',
+          level: 'error', blocking: true } } },
+};
+
+/** @type {import('@north-light/crouter/dist/core/view/contract.js').ViewCore} */
+const core = {
+  manifest: {
+    id: '${id}',
+    title: '${title}',
+    description: '${description}',
+    // refreshMs: 30000,   // uncomment to auto-poll; omit ⇒ on-demand (g) only
+  },
+
+  // Cheap, synchronous setup. Stash CLI flags off \`opts\` here.
+  init: (opts) => ({ count: 0, clock: null, port: opts.port ?? null }),
+
+  sources: { clockSource },
+
+  intents: {
+    // Async intent: ctx.set updates state immutably; ctx.resolve runs a source
+    // through the host transport. The host runs 'refresh' on launch, every
+    // manifest.refreshMs (if set), and on the \`g\` key (see tui.mjs).
+    async refresh(ctx) {
+      ctx.signal.setStatus('Reading clock…');
+      const r = await ctx.resolve(clockSource);
+      if (!r.ok) { ctx.signal.setBanner(r.error.display.headline, r.error.display.level); ctx.signal.setStatus(null); return; }
+      ctx.set((s) => ({ ...s, count: s.count + 1, clock: r.data }));
+      ctx.signal.clearBanner();
+      ctx.signal.setStatus(\`refreshed \${ctx.state.count}×\`);
+    },
+    quit: (ctx) => ctx.signal.quit(),
+  },
+};
+
+export default core;
+`;
+}
+/** The TUI presenter: render(state, draw, content) + keymap. Node only. */
+function tuiStub(v) {
+    const title = jsStr(v.title);
+    return `// ${v.title} — TUI presenter: render(state, draw, content) + keymap.
+//
+// A pure read of state — paint via draw.*; NEVER write ANSI. Keys map to the
+// core's intents (no logic here; the keymap names an intent, the host dispatches).
+//
+// draw API (all absolute cells inside \`content\`):
+//   draw.text(row,col,text,style?)            · draw.spans(row,col,spans,maxWidth?)
+//   draw.hline(row,fromCol?,toCol?)           · draw.box(rect,title?)
+//   draw.columns(rect,[1,2]) -> Rect[]        · draw.list(rect,items,cursor,scroll)
+//   style: { fg, bg, bold, dim, reverse }     (fg/bg honored only when color is on)
+
+export const keymap = [
+  { keys: ['g'], intent: 'refresh', hint: { keys: 'g', label: 'refresh' } },
+  { keys: ['q'], intent: 'quit', hint: { keys: 'q', label: 'quit' } },
+];
+
+export function render(state, draw, content) {
+  draw.text(content.row, content.col, '${title}', { bold: true });
+  draw.text(content.row + 2, content.col, \`clock: \${state.clock ?? '(loading…)'}\`);
+  draw.text(content.row + 3, content.col, \`refreshed \${state.count} time(s)\`, { dim: true });
+  draw.text(content.row + 4, content.col, \`port option: \${state.port ?? '(none)'}\`, { dim: true });
+  draw.text(content.row + 6, content.col, 'Edit core.mjs + tui.mjs to build your view — g refreshes, q quits.', { dim: true });
+}
+`;
+}
+/** The web presenter: a React + Tailwind component. Browser only (Vite owns the
+ *  JSX + Tailwind transpile; this file is NEVER Node-imported). */
+function webStub(v) {
+    const title = jsStr(v.title);
+    return `// ${v.title} — web presenter: a React + Tailwind component.
+//
+// A pure function of \`state\`; DOM events call \`dispatch(intent)\`. Consumed ONLY
+// by the surface web host (Vite owns JSX + Tailwind) — never Node-imported. The
+// SAME state + intents the TUI reads; zero shared render code (an intentional fork).
+
+export default function View({ state, dispatch }) {
+  return (
+    <div
+      className="font-mono text-sm p-4 outline-none"
+      tabIndex={0}
+      onKeyDown={(e) => { if (e.key === 'g') dispatch('refresh'); }}
+    >
+      <h1 className="text-lg font-bold">${title}</h1>
+      <p className="mt-2">clock: {state.clock ?? '(loading…)'}</p>
+      <p className="text-gray-500">refreshed {state.count} time(s)</p>
+      <button
+        className="mt-3 rounded bg-blue-600 px-2 py-1 text-white hover:bg-blue-500"
+        onClick={() => dispatch('refresh')}
+      >
+        Refresh
+      </button>
+    </div>
+  );
+}
+`;
+}
+/** The text presenter: the piped / non-TTY snapshot. Node only. Optional — omit
+ *  it and the host synthesizes a generic one-line dump. */
+function textStub(v) {
+    const title = jsStr(v.title);
+    return `// ${v.title} — text presenter: the piped / non-TTY snapshot (exits 0).
+//
+// A pure read of current state. Omit this file and the host synthesizes a
+// one-line dump (\`<title> — <n> items\`).
+
+export function dump(state) {
+  return [
+    '${title}',
+    '',
+    \`clock: \${state.clock ?? '(none)'}\`,
+    \`refreshed \${state.count} time(s)\`,
+  ].join('\\n');
+}
+`;
+}
+/** Build every file of a freshly scaffolded dual-target view, keyed by filename. */
+export function viewScaffold(v) {
+    return {
+        'core.mjs': coreStub(v),
+        'tui.mjs': tuiStub(v),
+        'web.jsx': webStub(v),
+        'text.mjs': textStub(v),
+    };
+}

package/dist/suppress-experimental-warnings.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/suppress-experimental-warnings.js

@@ -0,0 +1,15 @@
+const originalEmit = process.emit;
+process.emit = function (name, ...args) {
+    const [data] = args;
+    if (name === 'warning' &&
+        data instanceof Error &&
+        data.name === 'ExperimentalWarning' &&
+        data.message.includes('SQLite')) {
+        return false;
+    }
+    return originalEmit.apply(this, [
+        name,
+        ...args,
+    ]);
+};
+export {};