@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/personas/resolve.js

@@ -1,134 +1,376 @@
 /**
  * Persona resolver — composes base + orchestrator personas into a
  * ResolvedPersona ready for use when spawning a canvas node.
- *
- * Composition rules:
- *   mode==='base'
- *     → load <kind>/PERSONA.md; if missing fall back to general defaults.
- *
- *   mode==='orchestrator'
- *     → prefer <kind>/orchestrator.md (which must embed the kernel via
- *       @include orchestration-kernel.md — inlined by the loader).
- *       If no orchestrator.md exists for this kind, compose:
- *         <kind>/PERSONA.md body  +  '\n\n'  +  kernel body
- *       If even the PERSONA.md is missing, fall back to general defaults + kernel.
- *
- * Frontmatter from whichever file is the primary source (orchestrator.md >
- * PERSONA.md) supplies model/skills/extensions/tools. Lifecycle and spine position
- * are INPUTS (the caller decides them — root/child, terminal/resident), not
- * derived here; they select the lifecycle/spine protocol fragments spliced
- * ahead of the persona body.
  */
-import { loadPersona, loadKernel, loadRuntimeBase, loadSpineFragment, loadLifecycleFragment, loadWaitingFragment, subPersonasFor } from './loader.js';
+import { getNode } from '../canvas/index.js';
+import { renderKnowledgeBlock, renderPreferencesSection } from '../substrate/render.js';
+import { loadPersona, loadPersonaSource, loadKernelSource, loadRuntimeBaseSource, loadSpineFragmentSource, loadLifecycleFragmentSource, loadWaitingFragmentSource, loadScopedText, subPersonasFor, } from './loader.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 function toStringArray(v) {
     if (!Array.isArray(v))
         return [];
-    // yaml.parse coerces scalars to native types; the persona prompt needs strings,
-    // so coerce each scalar element (dropping nested objects/arrays/null) — this
-    // mirrors the prior hand-rolled parser, which returned every scalar as a string.
     return v.filter((x) => x != null && typeof x !== 'object').map((x) => String(x));
 }
 function toOptionalString(v) {
     if (typeof v === 'string')
         return v;
-    // Preserve the legacy parser's string-typed contract for native scalars
-    // (e.g. `model: 4` must compose as "4", not be dropped as a non-string).
     if (typeof v === 'number' || typeof v === 'boolean')
         return String(v);
     return undefined;
 }
-/** The bare-minimum system prompt used when no persona file is found at all. */
 function fallbackBasePrompt(kind) {
     return `You are a ${kind} agent. Complete the task you have been given.`;
 }
-/** Compose the runtime protocol that precedes every persona body: the
- *  lifecycle-neutral base (identity/delegate/ask/promote), then the spine
- *  fragment (report-up vs. silent, keyed on whether the node has a manager),
- *  then the lifecycle fragment (finish-with-`push final` vs. dormant/wake). The
- *  kind×mode persona body follows after a rule. Empty fragments drop out. */
-/** Render the "sub-personas you may spawn" menu for a kind that has any
- *  available to it. Returns '' when none are. Data-driven: one line per
- *  sub-persona, its spawn string + its `whenToUse`. A sub-persona surfaces here
- *  for a kind when its `availableTo` includes that kind (default: its own
- *  top-level ancestor) or is the wildcard. */
+function approxTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function makeLayer(part) {
+    return {
+        ...part,
+        chars: part.text.length,
+        tokens: approxTokens(part.text),
+    };
+}
+function trimBlock(text) {
+    return text.trim();
+}
+function includeTargets(rawBody) {
+    const targets = [];
+    const re = /^@include\s+(\S+)\s*$/gm;
+    for (const match of rawBody.matchAll(re)) {
+        targets.push(match[1]);
+    }
+    return targets;
+}
+function addSource(list, seen, source) {
+    if (source === null)
+        return;
+    const key = `${source.scope}:${source.path}`;
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    list.push(source);
+}
+function resolveSourceRef(path, label) {
+    const loaded = loadScopedText(path);
+    if (!loaded)
+        return null;
+    return { id: label, label, path: loaded.sourcePath, scope: loaded.scope };
+}
+function collectPersonaSources(primary, fallbackLabel) {
+    const sources = [];
+    const seen = new Set();
+    if (primary !== null) {
+        addSource(sources, seen, {
+            id: fallbackLabel,
+            label: fallbackLabel,
+            path: primary.sourcePath,
+            scope: primary.scope,
+        });
+        for (const target of includeTargets(primary.rawBody)) {
+            addSource(sources, seen, resolveSourceRef(target, `included: ${target}`));
+        }
+    }
+    return sources;
+}
+function basePersonaLayer(kind, mode) {
+    const source = loadPersonaSource(kind, mode);
+    if (source !== null) {
+        const label = mode === 'base' ? 'Persona body' : 'Orchestrator body';
+        return {
+            layer: makeLayer({
+                id: 'persona-body',
+                label,
+                group: 'persona',
+                source: source.source,
+                sourcePath: source.sourcePath,
+                scope: source.scope,
+                included: true,
+                condition: null,
+                text: source.body || fallbackBasePrompt(kind),
+            }),
+            sources: collectPersonaSources(source, label),
+        };
+    }
+    if (mode === 'orchestrator') {
+        const base = loadPersonaSource(kind, 'base');
+        const kernel = loadKernelSource();
+        const body = `${base?.body || fallbackBasePrompt(kind)}${kernel ? `\n\n${kernel.text}` : ''}`;
+        const layer = makeLayer({
+            id: 'persona-body',
+            label: 'Orchestrator body',
+            group: 'persona',
+            source: base?.sourcePath !== undefined ? base.source : 'generated: base persona + kernel',
+            sourcePath: base?.sourcePath ?? null,
+            scope: base?.scope ?? 'generated',
+            included: true,
+            condition: null,
+            text: body,
+        });
+        const sources = [];
+        const seen = new Set();
+        if (base !== null) {
+            addSource(sources, seen, { id: 'persona-body', label: 'Persona body', path: base.sourcePath, scope: base.scope });
+            for (const target of includeTargets(base.rawBody)) {
+                addSource(sources, seen, resolveSourceRef(target, `included: ${target}`));
+            }
+        }
+        if (kernel !== null) {
+            addSource(sources, seen, { id: 'kernel', label: 'Kernel', path: kernel.sourcePath, scope: kernel.scope });
+        }
+        return { layer, sources };
+    }
+    const layer = makeLayer({
+        id: 'persona-body',
+        label: 'Persona body',
+        group: 'persona',
+        source: 'generated: fallback persona',
+        sourcePath: null,
+        scope: 'generated',
+        included: true,
+        condition: null,
+        text: fallbackBasePrompt(kind),
+    });
+    return { layer, sources: [] };
+}
+function protocolLayers(lifecycle, hasManager) {
+    const runtime = loadRuntimeBaseSource();
+    const wait = loadWaitingFragmentSource();
+    const spineHas = loadSpineFragmentSource(true);
+    const spineNo = loadSpineFragmentSource(false);
+    const lifecycleTerminal = loadLifecycleFragmentSource('terminal');
+    const lifecycleResident = loadLifecycleFragmentSource('resident');
+    return [
+        makeLayer({
+            id: 'runtime-base',
+            label: 'Runtime base',
+            group: 'protocol',
+            source: 'personas/runtime-base.md',
+            sourcePath: runtime?.sourcePath ?? null,
+            scope: runtime?.scope ?? 'generated',
+            included: true,
+            condition: null,
+            text: trimBlock(runtime?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'spine-has-manager',
+            label: 'Has manager',
+            group: 'protocol',
+            source: 'personas/spine/has-manager.md',
+            sourcePath: spineHas?.sourcePath ?? null,
+            scope: spineHas?.scope ?? 'generated',
+            included: hasManager,
+            condition: hasManager ? null : 'hasManager == false',
+            text: trimBlock(spineHas?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'spine-no-manager',
+            label: 'No manager',
+            group: 'protocol',
+            source: 'personas/spine/no-manager.md',
+            sourcePath: spineNo?.sourcePath ?? null,
+            scope: spineNo?.scope ?? 'generated',
+            included: !hasManager,
+            condition: hasManager ? 'hasManager == true' : null,
+            text: trimBlock(spineNo?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'lifecycle-terminal',
+            label: 'Terminal lifecycle',
+            group: 'protocol',
+            source: 'personas/lifecycle/terminal.md',
+            sourcePath: lifecycleTerminal?.sourcePath ?? null,
+            scope: lifecycleTerminal?.scope ?? 'generated',
+            included: lifecycle === 'terminal',
+            condition: lifecycle === 'terminal' ? null : 'lifecycle == resident',
+            text: trimBlock(lifecycleTerminal?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'lifecycle-resident',
+            label: 'Resident lifecycle',
+            group: 'protocol',
+            source: 'personas/lifecycle/resident.md',
+            sourcePath: lifecycleResident?.sourcePath ?? null,
+            scope: lifecycleResident?.scope ?? 'generated',
+            included: lifecycle === 'resident',
+            condition: lifecycle === 'resident' ? null : 'lifecycle == terminal',
+            text: trimBlock(lifecycleResident?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'waiting',
+            label: 'Waiting',
+            group: 'protocol',
+            source: 'personas/waiting.md',
+            sourcePath: wait?.sourcePath ?? null,
+            scope: wait?.scope ?? 'generated',
+            included: true,
+            condition: null,
+            text: trimBlock(wait?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'separator',
+            label: 'Separator',
+            group: 'protocol',
+            source: 'generated: separator',
+            sourcePath: null,
+            scope: 'generated',
+            included: true,
+            condition: null,
+            text: '---',
+        }),
+    ];
+}
 function renderSubPersonaMenu(kind) {
     const subs = subPersonasFor(kind);
     if (subs.length === 0)
-        return '';
-    const lines = subs.map((s) => `- \`${s.kind}\` — ${s.whenToUse}`);
-    return [
+        return { layer: null, sources: [] };
+    const lines = [
         '## Sub-personas you may spawn',
         '',
-        `These specialist sub-personas are available to the ${kind} kind. Spawn one with \`crtr node new --kind <sub> "<scope>"\`, giving it only its scope, never your suspicions: a reviewer handed a hint anchors on it instead of finding problems independently.`,
+        `These specialist sub-personas are available to the ${kind} kind. Spawn one with \`crtr node new --kind <sub> "<scope>"\`, and treat it as its own scope instead of dragging unrelated context into it.`,
         '',
-        ...lines,
-    ].join('\n');
+    ];
+    const sources = [];
+    const seen = new Set();
+    for (const sub of subs) {
+        const src = loadPersonaSource(sub.kind, 'base');
+        if (src !== null) {
+            addSource(sources, seen, { id: sub.kind, label: sub.kind, path: src.sourcePath, scope: src.scope });
+            lines.push(`- \`${sub.kind}\` — ${sub.whenToUse} (${src.sourcePath})`);
+        }
+        else {
+            lines.push(`- \`${sub.kind}\` — ${sub.whenToUse}`);
+        }
+    }
+    return {
+        layer: makeLayer({
+            id: 'subpersona-menu',
+            label: 'Sub-persona menu',
+            group: 'generated',
+            source: 'generated: sub-persona menu',
+            sourcePath: null,
+            scope: 'generated',
+            included: true,
+            condition: null,
+            text: lines.join('\n'),
+        }),
+        sources,
+    };
 }
-function composeProtocol(personaPrompt, kind, lifecycle, hasManager) {
+function coreLayers(kind, mode, opts) {
+    const protocol = protocolLayers(opts.lifecycle, opts.hasManager);
+    const body = basePersonaLayer(kind, mode);
     const menu = renderSubPersonaMenu(kind);
-    const body = menu ? `${personaPrompt}\n\n${menu}` : personaPrompt;
-    const protocol = [
-        loadRuntimeBase(),
-        loadSpineFragment(hasManager),
-        loadLifecycleFragment(lifecycle),
-        loadWaitingFragment(),
-    ]
-        .filter((s) => s.length > 0)
-        .join('\n\n');
-    return protocol ? `${protocol}\n\n---\n\n${body}` : body;
+    const layers = [...protocol, body.layer];
+    if (menu.layer !== null)
+        layers.push(menu.layer);
+    const sources = [];
+    const seen = new Set();
+    for (const layer of protocol) {
+        if (layer.sourcePath === null)
+            continue;
+        addSource(sources, seen, { id: layer.id, label: layer.label, path: layer.sourcePath, scope: layer.scope });
+    }
+    for (const source of body.sources)
+        addSource(sources, seen, source);
+    for (const source of menu.sources)
+        addSource(sources, seen, source);
+    return { layers, sources };
 }
-export function resolve(kind, mode, opts) {
-    if (mode === 'base') {
-        const persona = loadPersona(kind, 'base');
-        if (!persona) {
-            // No persona file for this kind — use minimal defaults.
-            return {
-                systemPrompt: composeProtocol(fallbackBasePrompt(kind), kind, opts.lifecycle, opts.hasManager),
-                extensions: [],
-                skills: [],
-                lifecycle: opts.lifecycle,
-            };
-        }
-        const fm = persona.frontmatter ?? {};
-        return {
-            systemPrompt: composeProtocol(persona.body || fallbackBasePrompt(kind), kind, opts.lifecycle, opts.hasManager),
-            extensions: toStringArray(fm['extensions']),
-            skills: toStringArray(fm['skills']),
-            model: toOptionalString(fm['model']),
-            lifecycle: opts.lifecycle,
-            tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
-        };
+function joinIncluded(layers) {
+    return layers.filter((layer) => layer.included && layer.text.length > 0).map((layer) => layer.text).join('\n\n');
+}
+function spliceRuntimeSubstrate(systemPrompt, nodeId) {
+    const pref = renderPreferencesSection(nodeId).trim();
+    const blocks = [];
+    const layers = [];
+    if (pref !== '') {
+        const text = pref;
+        blocks.push(text);
+        layers.push(makeLayer({
+            id: 'memory-preference',
+            label: 'Memory — usage guidance + preferences',
+            group: 'substrate',
+            source: 'runtime-spliced',
+            sourcePath: null,
+            scope: 'runtime',
+            included: true,
+            condition: null,
+            text,
+        }));
     }
-    // mode === 'orchestrator'
-    const orchestratorPersona = loadPersona(kind, 'orchestrator');
-    if (orchestratorPersona) {
-        // Orchestrator file exists; @include was already inlined by the loader.
-        const fm = orchestratorPersona.frontmatter ?? {};
-        return {
-            systemPrompt: composeProtocol(orchestratorPersona.body || fallbackBasePrompt(kind), kind, opts.lifecycle, opts.hasManager),
-            extensions: toStringArray(fm['extensions']),
-            skills: toStringArray(fm['skills']),
-            model: toOptionalString(fm['model']),
-            lifecycle: opts.lifecycle,
-            tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
-        };
+    const knowledge = renderKnowledgeBlock(nodeId).trim();
+    if (knowledge !== '') {
+        layers.push(makeLayer({
+            id: 'memory-knowledge',
+            label: 'Memory (knowledge) — context message, not system prompt',
+            group: 'substrate',
+            source: 'runtime-spliced',
+            sourcePath: null,
+            scope: 'runtime',
+            included: false,
+            condition: 'session_start context message, not the system prompt',
+            text: knowledge,
+        }));
     }
-    // No orchestrator.md for this kind — compose base + bare kernel.
-    const kernel = loadKernel();
-    const basePersona = loadPersona(kind, 'base');
-    const baseBody = basePersona?.body || fallbackBasePrompt(kind);
-    const fm = basePersona?.frontmatter ?? {};
-    // Append the kernel to the base body (with separator if kernel is non-empty).
-    const systemPrompt = kernel ? `${baseBody}\n\n${kernel}` : baseBody;
+    if (blocks.length === 0)
+        return { prompt: systemPrompt, layers };
+    const insert = blocks.join('\n\n');
+    const anchor = '\n\nGuidelines:';
+    const idx = systemPrompt.indexOf(anchor);
+    if (idx === -1)
+        return { prompt: `${systemPrompt}\n\n${insert}`, layers };
+    return { prompt: `${systemPrompt.slice(0, idx)}\n\n${insert}${systemPrompt.slice(idx)}`, layers };
+}
+function collectLayers(kind, mode, opts, nodeId) {
+    const core = coreLayers(kind, mode, opts);
+    const assembledCore = joinIncluded(core.layers);
+    const node = nodeId !== undefined ? getNode(nodeId) : null;
+    const config = {
+        kind,
+        mode,
+        lifecycle: opts.lifecycle,
+        hasManager: opts.hasManager,
+        node: node !== null ? node.node_id : null,
+    };
+    const substrate = node !== null ? spliceRuntimeSubstrate(assembledCore, node.node_id) : { prompt: assembledCore, layers: [] };
+    const layers = [...core.layers, ...substrate.layers];
+    const sources = [];
+    const seen = new Set();
+    for (const source of core.sources)
+        addSource(sources, seen, source);
+    const included = layers.filter((layer) => layer.included).reduce((acc, layer) => ({ tokens: acc.tokens + layer.tokens, chars: acc.chars + layer.chars }), { tokens: 0, chars: 0 });
+    return {
+        config,
+        layers,
+        assembled: substrate.prompt,
+        total: included,
+        sources,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a fully composed persona for the given `kind` and `mode`.
+ */
+export function resolve(kind, mode, opts) {
+    const persona = mode === 'base' ? loadPersona(kind, 'base') : loadPersona(kind, 'orchestrator') ?? loadPersona(kind, 'base');
+    const fm = persona?.frontmatter ?? {};
+    const systemPrompt = joinIncluded(coreLayers(kind, mode, opts).layers);
     return {
-        systemPrompt: composeProtocol(systemPrompt, kind, opts.lifecycle, opts.hasManager),
+        systemPrompt,
         extensions: toStringArray(fm['extensions']),
-        skills: toStringArray(fm['skills']),
         model: toOptionalString(fm['model']),
         lifecycle: opts.lifecycle,
         tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
     };
 }
+export function resolveLayers(kind, mode, opts) {
+    return coreLayers(kind, mode, opts).layers;
+}
+export function resolvePromptReview(kind, mode, opts, nodeId) {
+    return collectLayers(kind, mode, opts, nodeId);
+}

package/dist/core/preview-registry.d.ts

@@ -0,0 +1,25 @@
+export declare const SUPPRESS_OUTPUT_LEAVES: ReadonlySet<string>;
+/** True when the leaf at this full help-name path (e.g. "canvas snapshot")
+ *  declares `preview.suppressOutput: true`. */
+export declare function suppressOutputForLeaf(helpName: string): boolean;
+/** Same lookup from argv tokens (e.g. ['node', 'inspect', 'snapshot', 'abc'])
+ *  instead of a pre-joined help name. Matches a registered leaf name against
+ *  a *prefix* of the tokens, not the whole joined tail, so a leaf's own
+ *  positional arguments (e.g. the snapshot id in `node inspect snapshot
+ *  abc`) don't prevent the match. */
+export declare function suppressOutputForPath(tokens: readonly string[]): boolean;
+export declare const HELP_ICON: string;
+/** Resolve the Nerd Font glyph for a command's argv tokens: the longest
+ *  matching LEAF_ICON_CP prefix, else the tokens[0] family glyph, else the
+ *  generic ◆ fallback for an unmapped family. */
+export declare function iconForPath(tokens: readonly string[]): string;
+export type SummaryTone = 'plain' | 'success' | 'error' | 'warning' | 'muted' | 'accent';
+export interface SummaryLine {
+    text: string;
+    tone?: SummaryTone;
+}
+/** Dispatch a command's argv tokens + its raw result text to the summarizer
+ *  that owns that leaf path (longest-registered-prefix match, same shape as
+ *  suppressOutputForPath), or null when no command owns a summary — the
+ *  caller falls through to generic truncation in that case. */
+export declare function summarizePath(tokens: readonly string[], rawText: string): SummaryLine[] | null;