@crouton-kit/crouter 0.3.42 → 0.3.44

package/dist/core/runtime/stop-guard.js

@@ -17,8 +17,21 @@
 //   • otherwise      → a TERMINAL node with nothing live to wait for and no
 //                      final pushed. Re-prompt it to finish or escalate.
 import { hasActiveLiveSubscription, hasPendingSelfTrigger, getNode } from '../canvas/index.js';
+import { hasPendingStructuredOutput, readOutputRequest } from './structured-output.js';
 export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
     'Run `crtr push final "<result>"` if the work is done, or `crtr human ask` if you are blocked or need the user.';
+function structuredOutputReprompt(nodeId) {
+    let schema = '{}';
+    try {
+        const request = readOutputRequest(nodeId);
+        if (request !== null)
+            schema = JSON.stringify(request.schema, null, 2);
+    }
+    catch {
+        /* keep a deterministic reprompt even if the schema file was corrupted */
+    }
+    return `You must call the \`submit\` tool with a result matching the required schema before you can stop. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n\`\`\`json\n${schema}\n\`\`\``;
+}
 /** Decide what to do when a node stops. Pure given the canvas + this turn's
  *  signals — the stophook supplies the signals and enacts the action. */
 export function evaluateStop(nodeId, signals) {
@@ -32,6 +45,12 @@ export function evaluateStop(nodeId, signals) {
     if (node !== null && (node.status === 'done' || node.status === 'dead' || node.status === 'canceled')) {
         return { action: 'allow', reason: 'finished' };
     }
+    // A pending structured-output request overrides every normal dormancy path:
+    // terminal mode must finish through submit, and one-off mode must answer the
+    // outstanding request before the node is freed to stop normally again.
+    if (hasPendingStructuredOutput(nodeId)) {
+        return { action: 'reprompt', reason: 'stalled', message: structuredOutputReprompt(nodeId) };
+    }
     // A RESIDENT node is interactable / human-driven and is never forced to submit
     // a final: stopping to go dormant is always legitimate (the inbox or the human
     // wakes it). Keyed on lifecycle, not parent — whether it has a parent doesn't

package/dist/core/runtime/structured-output.d.ts

@@ -0,0 +1,12 @@
+export type StructuredOutputMode = 'terminal' | 'oneoff';
+export interface StructuredOutputRequest {
+    mode: StructuredOutputMode;
+    schema: Record<string, unknown>;
+}
+export declare function outputSchemaPath(nodeId: string): string;
+export declare function outputResultPath(nodeId: string): string;
+export declare function parseOutputSchemaValue(value: string | undefined): Record<string, unknown> | null;
+export declare function writeOutputSchema(nodeId: string, mode: StructuredOutputMode, schema: Record<string, unknown>): string;
+export declare function readOutputRequest(nodeId: string): StructuredOutputRequest | null;
+export declare function removeOutputSchema(nodeId: string): void;
+export declare function hasPendingStructuredOutput(nodeId: string): boolean;

package/dist/core/runtime/structured-output.js

@@ -0,0 +1,90 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { nodeDir, contextDir } from '../canvas/paths.js';
+import { InputError } from '../io.js';
+export function outputSchemaPath(nodeId) {
+    return `${nodeDir(nodeId)}/output-schema.json`;
+}
+export function outputResultPath(nodeId) {
+    return `${contextDir(nodeId)}/result.json`;
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function parseOutputSchemaValue(value) {
+    const raw = value?.trim();
+    if (raw === undefined || raw === '')
+        return null;
+    let text;
+    let source;
+    if (raw.startsWith('{')) {
+        text = raw;
+        source = 'inline JSON';
+    }
+    else {
+        const path = resolve(raw);
+        source = path;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch (err) {
+            throw new InputError({
+                error: 'bad_output_schema',
+                message: `could not read output schema from ${path}: ${err.message}`,
+                field: 'output-schema',
+                next: 'Pass a readable JSON Schema file path, or inline JSON beginning with `{`.',
+            });
+        }
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new InputError({
+            error: 'bad_output_schema',
+            message: `output schema from ${source} is not valid JSON: ${err.message}`,
+            field: 'output-schema',
+            next: 'Pass valid JSON whose top-level value is an object.',
+        });
+    }
+    if (!isObject(parsed)) {
+        throw new InputError({
+            error: 'bad_output_schema',
+            message: `output schema from ${source} must be a JSON object`,
+            field: 'output-schema',
+            next: 'Pass a JSON Schema object, not an array, string, number, boolean, or null.',
+        });
+    }
+    return parsed;
+}
+export function writeOutputSchema(nodeId, mode, schema) {
+    const path = outputSchemaPath(nodeId);
+    mkdirSync(dirname(path), { recursive: true });
+    const request = { mode, schema };
+    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`, 'utf8');
+    return path;
+}
+export function readOutputRequest(nodeId) {
+    const path = outputSchemaPath(nodeId);
+    if (!existsSync(path))
+        return null;
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!isObject(parsed))
+        return null;
+    const mode = parsed['mode'];
+    const schema = parsed['schema'];
+    if ((mode !== 'terminal' && mode !== 'oneoff') || !isObject(schema))
+        return null;
+    return { mode, schema };
+}
+export function removeOutputSchema(nodeId) {
+    const path = outputSchemaPath(nodeId);
+    try {
+        unlinkSync(path);
+    }
+    catch { /* already gone */ }
+}
+export function hasPendingStructuredOutput(nodeId) {
+    return existsSync(outputSchemaPath(nodeId));
+}

package/dist/core/substrate/schema.d.ts

@@ -58,6 +58,21 @@ export interface SubstrateSchema {
      *  than the node subject. Absent ⇒ no frontmatter trigger. Frontmatter key
      *  `read-when`. */
     readWhen?: GatePredicate;
+    /** Opt-in: this doc is invocable as a pi slash command (`/<name>`, `/` in a
+     *  nested name rendered as `:`). Default `false` — most docs are consulted,
+     *  not invoked. Frontmatter key `slash`. */
+    slash: boolean;
+    /** The gap this doc exists to close — the observed agent failure that
+     *  prompted it (CTO ruling 2026-07-03, `taste/document-substrate` §"Rationale
+     *  is a frontmatter field, never delivered"). MAINTAINER-FACING ONLY: excluded
+     *  from every delivered surface by construction — it is frontmatter, never
+     *  body, so it never reaches a boot render, on-read injection, or `memory
+     *  read` content output; only the raw file at `path` (or `memory read
+     *  --frontmatter`) shows it. It is NOT read-routing (`whenAndWhyToRead` owns
+     *  that) and NOT a content summary (`shortForm` owns that) — it answers
+     *  "what observed failure made this doc exist," never "why obey it." Absent
+     *  when the doc carries none. Frontmatter key `rationale`. */
+    rationale?: string;
 }
 /** A fully-resolved substrate document: the parsed schema PLUS the resolver's
  *  path-derived identity and body. This single object flows through the whole

package/dist/core/substrate/schema.js

@@ -94,6 +94,8 @@ export function parseSubstrateFrontmatter(fm) {
         gate: parseGate(fm.gate),
         appliesTo: parseAppliesTo(fm['applies-to']),
         readWhen: parseGate(fm['read-when']),
+        slash: fm.slash === true,
+        rationale: parseRationale(fm['rationale']),
     };
 }
 /** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the
@@ -121,6 +123,13 @@ export function previewLine(doc) {
 function strField(v) {
     return typeof v === 'string' ? v : '';
 }
+/** Resolve an optional `rationale` field: a non-empty string is carried as-is
+ *  (multi-line YAML block scalars parse to a plain string, so no special
+ *  handling is needed); anything else (absent, blank, non-string) yields
+ *  `undefined` — the doc simply carries no rationale. */
+function parseRationale(v) {
+    return typeof v === 'string' && v.trim() !== '' ? v : undefined;
+}
 /** Resolve a visibility field to a ladder rung, falling back to the neutral
  *  floor when absent/invalid. */
 function parseRung(v, fallback) {

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,150 @@
+// 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 { getNode } from '../core/canvas/index.js';
+import { 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,
+                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) {
+                            const status = getNode(nodeId)?.status;
+                            const alreadyFinalized = status === 'done' || status === 'dead' || status === 'canceled' ||
+                                (err instanceof Error && err.message.startsWith("illegal lifecycle transition: 'finalize' from status='"));
+                            if (!alreadyFinalized)
+                                throw err;
+                        }
+                        removeOutputSchema(nodeId);
+                        active = false;
+                        retireTool(pi);
+                        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.js

@@ -1,3 +1,17 @@
+/**
+ * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.42",
+  "version": "0.3.44",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",