@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/personas/loader.js

@@ -42,17 +42,13 @@ function builtinPersonasRoot() {
         return srcPath;
     return distPath;
 }
-// ---------------------------------------------------------------------------
-// Scope roots for personas
-// ---------------------------------------------------------------------------
-/** Returns the ordered list of roots to search, highest precedence first. */
 function personaSearchRoots() {
     const roots = [];
     const projectRoot = findProjectScopeRoot();
     if (projectRoot)
-        roots.push(join(projectRoot, 'personas'));
-    roots.push(join(userScopeRoot(), 'personas'));
-    roots.push(builtinPersonasRoot());
+        roots.push({ scope: 'project', root: join(projectRoot, 'personas') });
+    roots.push({ scope: 'user', root: join(userScopeRoot(), 'personas') });
+    roots.push({ scope: 'builtin', root: builtinPersonasRoot() });
     return roots;
 }
 // ---------------------------------------------------------------------------
@@ -72,21 +68,17 @@ function scalarToString(v) {
         return String(v);
     return null;
 }
-// ---------------------------------------------------------------------------
-// File resolution helpers
-// ---------------------------------------------------------------------------
-/**
- * Find the first existing file across the scope roots.
- * `relativePath` is relative to each root (e.g. 'general/PERSONA.md').
- */
-function resolveFile(relativePath) {
-    for (const root of personaSearchRoots()) {
+function resolveFileMeta(relativePath) {
+    for (const { scope, root } of personaSearchRoots()) {
         const candidate = join(root, relativePath);
         if (existsSync(candidate))
-            return candidate;
+            return { path: candidate, scope };
     }
     return null;
 }
+function resolveFile(relativePath) {
+    return resolveFileMeta(relativePath)?.path ?? null;
+}
 // ---------------------------------------------------------------------------
 // @include inlining
 // ---------------------------------------------------------------------------
@@ -110,6 +102,14 @@ function inlineIncludes(body) {
         return kernelBody.trim();
     });
 }
+export function loadScopedText(relativePath) {
+    const meta = resolveFileMeta(relativePath);
+    if (!meta)
+        return null;
+    const src = readFileSync(meta.path, 'utf8');
+    const { body } = parseFrontmatterGeneric(src);
+    return { text: body.trim(), sourcePath: meta.path, scope: meta.scope };
+}
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -122,16 +122,26 @@ const PERSONA_FILE = 'PERSONA.md';
  * On success, `@include` directives in the body are resolved and inlined.
  */
 export function loadPersona(kind, mode) {
-    // base → PERSONA.md (the role body); orchestrator → its sibling orchestrator.md.
+    const source = loadPersonaSource(kind, mode);
+    if (!source)
+        return null;
+    return { frontmatter: source.frontmatter, body: source.body };
+}
+/** Load a persona file together with its provenance. */
+export function loadPersonaSource(kind, mode) {
     const relativePath = mode === 'orchestrator' ? `${kind}/orchestrator.md` : `${kind}/PERSONA.md`;
-    const filePath = resolveFile(relativePath);
-    if (!filePath)
+    const file = resolveFileMeta(relativePath);
+    if (!file)
         return null;
-    const src = readFileSync(filePath, 'utf8');
+    const src = readFileSync(file.path, 'utf8');
     const { data, body } = parseFrontmatterGeneric(src);
     return {
         frontmatter: data,
+        rawBody: body.trim(),
         body: inlineIncludes(body).trim(),
+        sourcePath: file.path,
+        scope: file.scope,
+        source: `personas/${relativePath}`,
     };
 }
 /**
@@ -139,12 +149,11 @@ export function loadPersona(kind, mode) {
  * Returns an empty string if the kernel file cannot be found.
  */
 export function loadKernel() {
-    const filePath = resolveFile('orchestration-kernel.md');
-    if (!filePath)
-        return '';
-    const src = readFileSync(filePath, 'utf8');
-    const { body } = parseFrontmatterGeneric(src);
-    return body.trim();
+    const file = loadKernelSource();
+    return file?.text ?? '';
+}
+export function loadKernelSource() {
+    return loadScopedText('orchestration-kernel.md');
 }
 /**
  * Load the base runtime prompt — the node operating protocol prepended to
@@ -153,12 +162,10 @@ export function loadKernel() {
  * live in their own fragments, loaded below.
  */
 export function loadRuntimeBase() {
-    const filePath = resolveFile('runtime-base.md');
-    if (!filePath)
-        return '';
-    const src = readFileSync(filePath, 'utf8');
-    const { body } = parseFrontmatterGeneric(src);
-    return body.trim();
+    return loadRuntimeBaseSource()?.text ?? '';
+}
+export function loadRuntimeBaseSource() {
+    return loadScopedText('runtime-base.md');
 }
 /**
  * Load the waiting fragment — the cross-kind "waiting is a way to end a turn"
@@ -167,11 +174,10 @@ export function loadRuntimeBase() {
  * the lifecycle fragment (resolve.ts). Returns '' if the fragment is missing.
  */
 export function loadWaitingFragment() {
-    const filePath = resolveFile('waiting.md');
-    if (!filePath)
-        return '';
-    const { body } = parseFrontmatterGeneric(readFileSync(filePath, 'utf8'));
-    return body.trim();
+    return loadWaitingFragmentSource()?.text ?? '';
+}
+export function loadWaitingFragmentSource() {
+    return loadScopedText('waiting.md');
 }
 /**
  * Load the lifecycle fragment — the "how you end" contract, keyed on the node's
@@ -181,11 +187,10 @@ export function loadWaitingFragment() {
  * Returns '' if the fragment file cannot be found.
  */
 export function loadLifecycleFragment(lifecycle) {
-    const filePath = resolveFile(`lifecycle/${lifecycle}.md`);
-    if (!filePath)
-        return '';
-    const { body } = parseFrontmatterGeneric(readFileSync(filePath, 'utf8'));
-    return body.trim();
+    return loadLifecycleFragmentSource(lifecycle)?.text ?? '';
+}
+export function loadLifecycleFragmentSource(lifecycle) {
+    return loadScopedText(`lifecycle/${lifecycle}.md`);
 }
 /**
  * Load the spine fragment — the "who you report to" contract, keyed on whether
@@ -195,11 +200,10 @@ export function loadLifecycleFragment(lifecycle) {
  * Returns '' if the fragment file cannot be found.
  */
 export function loadSpineFragment(hasManager) {
-    const filePath = resolveFile(`spine/${hasManager ? 'has-manager' : 'no-manager'}.md`);
-    if (!filePath)
-        return '';
-    const { body } = parseFrontmatterGeneric(readFileSync(filePath, 'utf8'));
-    return body.trim();
+    return loadSpineFragmentSource(hasManager)?.text ?? '';
+}
+export function loadSpineFragmentSource(hasManager) {
+    return loadScopedText(`spine/${hasManager ? 'has-manager' : 'no-manager'}.md`);
 }
 /**
  * Enumerate the kinds with at least one persona file (PERSONA.md or
@@ -210,7 +214,7 @@ export function loadSpineFragment(hasManager) {
  */
 export function availableKinds() {
     const kinds = new Set();
-    for (const root of personaSearchRoots()) {
+    for (const { root } of personaSearchRoots()) {
         if (!existsSync(root))
             continue;
         for (const entry of readdirSync(root, { withFileTypes: true })) {
@@ -297,7 +301,7 @@ function parseAvailableTo(data, topKind) {
 export function subPersonasFor(kind) {
     const seen = new Set(); // full kind strings already resolved (higher root won)
     const out = [];
-    for (const root of personaSearchRoots()) {
+    for (const { root } of personaSearchRoots()) {
         if (!existsSync(root))
             continue;
         for (const top of readdirSync(root, { withFileTypes: true })) {

package/dist/core/personas/resolve.d.ts

@@ -1,43 +1,59 @@
 /**
  * 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.
  */
 export interface ResolvedPersona {
     systemPrompt: string;
     extensions: string[];
-    skills: string[];
     model?: string;
     lifecycle: 'terminal' | 'resident';
     tools?: string[];
 }
-/**
- * Resolve a fully composed persona for the given `kind` and `mode`.
- *
- * Never throws for missing files — missing personas produce sensible defaults.
- */
+export type PromptLayerGroup = 'protocol' | 'persona' | 'generated' | 'substrate';
+export type PromptLayerScope = 'project' | 'user' | 'builtin' | 'generated' | 'runtime';
+export interface PromptLayer {
+    id: string;
+    label: string;
+    group: PromptLayerGroup;
+    source: string;
+    sourcePath: string | null;
+    scope: PromptLayerScope;
+    included: boolean;
+    condition: string | null;
+    text: string;
+    tokens: number;
+    chars: number;
+}
+export interface PromptSource {
+    id: string;
+    label: string;
+    path: string;
+    scope: Exclude<PromptLayerScope, 'generated' | 'runtime'>;
+}
+export interface PromptReviewConfig {
+    kind: string;
+    mode: 'base' | 'orchestrator';
+    lifecycle: 'terminal' | 'resident';
+    hasManager: boolean;
+    node: string | null;
+}
+export interface PromptReviewData {
+    config: PromptReviewConfig;
+    layers: PromptLayer[];
+    assembled: string;
+    total: {
+        tokens: number;
+        chars: number;
+    };
+    sources: PromptSource[];
+}
 export interface ResolveOpts {
-    /** The node's lifecycle axis — selects the "how you end" fragment. */
     lifecycle: 'terminal' | 'resident';
-    /** Whether the node reports up to a manager (parent !== null) — selects the
-     *  spine fragment (`has-manager` teaches the push family; `no-manager` omits
-     *  it entirely). */
     hasManager: boolean;
 }
+/**
+ * Resolve a fully composed persona for the given `kind` and `mode`.
+ */
 export declare function resolve(kind: string, mode: 'base' | 'orchestrator', opts: ResolveOpts): ResolvedPersona;
+export declare function resolveLayers(kind: string, mode: 'base' | 'orchestrator', opts: ResolveOpts): PromptLayer[];
+export declare function resolvePromptReview(kind: string, mode: 'base' | 'orchestrator', opts: ResolveOpts, nodeId?: string): PromptReviewData;