@north-light/crouter 0.3.170 → 0.3.172

package/dist/core/runtime/tool-group-summary.d.ts

@@ -0,0 +1,19 @@
+import { type ToolGroupSummary } from '../../shared/tool-groups.js';
+export type ToolGroupPiece = {
+    type: 'tool';
+    name: string;
+    args: unknown;
+} | {
+    type: 'result';
+    name: string;
+    result: unknown;
+    isError: boolean;
+} | {
+    type: 'text';
+    text: string;
+};
+/** Serialize only the causal material around one group, with fixed per-piece
+ * and total budgets so a verbose tool result cannot dominate the light-model call. */
+export declare function serializeToolGroup(previousBoundaryProse: string, pieces: readonly ToolGroupPiece[]): string;
+/** Generate a structured summary object, or null on every failure. */
+export declare function headlessToolGroupSummary(segment: string): Promise<ToolGroupSummary | null>;

package/dist/core/runtime/tool-group-summary.js

@@ -0,0 +1,88 @@
+// Broker-side, best-effort tool-group summarization. The only successful output
+// path is the constrained submit_summary tool; failures deliberately yield no
+// substitute object so callers leave the normal folded calls visible.
+import { Type } from '@earendil-works/pi-ai';
+import { headlessToolCall } from './headless-pi.js';
+import { defaultProvider, modelLadders } from './model-selection.js';
+import { lightModel } from './naming.js';
+import { normalizeToolGroupSummary } from '../../shared/tool-groups.js';
+const BOUNDARY_CAP = 600;
+const TOOL_ARGS_CAP = 300;
+const RESULT_CAP = 400;
+const TEXT_CAP = 1_000;
+const SEGMENT_CAP = 10_000;
+const SUMMARY_TIMEOUT_MS = 45_000;
+function capped(value, cap) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    return normalized.length <= cap ? normalized : `${normalized.slice(0, Math.max(0, cap - 1)).trimEnd()}…`;
+}
+function printable(value, cap) {
+    try {
+        return capped(typeof value === 'string' ? value : JSON.stringify(value), cap);
+    }
+    catch {
+        return capped(String(value), cap);
+    }
+}
+/** Serialize only the causal material around one group, with fixed per-piece
+ * and total budgets so a verbose tool result cannot dominate the light-model call. */
+export function serializeToolGroup(previousBoundaryProse, pieces) {
+    const lines = [`Previous visible message: ${capped(previousBoundaryProse, BOUNDARY_CAP) || '(none)'}`, 'Between-message activity:'];
+    for (const piece of pieces) {
+        if (piece.type === 'tool')
+            lines.push(`- tool ${piece.name}(${printable(piece.args, TOOL_ARGS_CAP)})`);
+        else if (piece.type === 'result')
+            lines.push(`- ${piece.isError ? 'error' : 'result'} ${piece.name}: ${printable(piece.result, RESULT_CAP)}`);
+        else
+            lines.push(`- context: ${capped(piece.text, TEXT_CAP)}`);
+    }
+    return capped(lines.join('\n'), SEGMENT_CAP);
+}
+// Tool mechanics, identifiers, and inbox bookkeeping produce a machine log rather
+// than the glanceable human recap this surface needs, so the prompt asks only for
+// very short outcomes while the structured fields retain the underlying stats.
+const SUMMARY_SYSTEM_PROMPT = 'Create a structured recap of this coding-agent tool activity. ' +
+    'Prefer 1–3 bullets and use at most 5 only for distinct meaningful outcomes. ' +
+    'Each bullet must be an extremely readable plain-English outcome of 3–10 words, without markdown markers. ' +
+    'Describe what changed or was accomplished, not the tools, commands, or investigation steps; for code work, say what capability was added to a one- or two-phrase plain-English part of the system, such as "Added scheduling controls to the worker service." ' +
+    'Never include IDs, hashes, paths, filenames, command names, tool names, raw values, or report text. ' +
+    'Omit inbox receipt, delivery, and queueing; node-response and report bookkeeping; help lookups; status checks; and summary-generation activity. ' +
+    'A node response may support a substantive outcome, but its arrival or resummarization is never itself an outcome. ' +
+    'If no meaningful outcome remains after those omissions, submit the single bullet "No meaningful changes." ' +
+    'Count nodes created and distinct files created, modified, or deleted only when evidenced by the supplied tool arguments or results; otherwise use zero, even when the corresponding mechanics are omitted from bullets. ' +
+    'Do not invent success when a result shows failure. ' +
+    'Call submit_summary exactly once with bullets, nodesSpawned, and filesEdited, then stop.';
+const SUBMIT_SUMMARY_SCHEMA = Type.Object({
+    bullets: Type.Array(Type.String({
+        minLength: 1,
+        maxLength: 120,
+        description: 'A very short, plain-English outcome without bullet markers, identifiers, or operational bookkeeping.',
+    }), { minItems: 1, maxItems: 5 }),
+    nodesSpawned: Type.Integer({
+        minimum: 0,
+        description: 'Count of nodes created during the supplied segment, or zero when none are evidenced.',
+    }),
+    filesEdited: Type.Integer({
+        minimum: 0,
+        description: 'Count of distinct files created, modified, or deleted during the supplied segment, or zero when none are evidenced.',
+    }),
+}, { additionalProperties: false });
+/** Generate a structured summary object, or null on every failure. */
+export async function headlessToolGroupSummary(segment) {
+    const ladders = modelLadders();
+    const modelIntent = `${defaultProvider(ladders)}/light`;
+    return normalizeToolGroupSummary(await headlessToolCall({
+        systemPrompt: SUMMARY_SYSTEM_PROMPT,
+        userPrompt: `<tool-group>\n${segment}\n</tool-group>\n\nSummarize the activity above.`,
+        modelSpec: lightModel(),
+        modelIntent,
+        timeoutMs: SUMMARY_TIMEOUT_MS,
+        tool: {
+            name: 'submit_summary',
+            label: 'Submit summary',
+            description: 'Submit the structured tool-group activity recap exactly once, then stop.',
+            parameters: SUBMIT_SUMMARY_SCHEMA,
+            constrainedSampling: false,
+        },
+    }));
+}

package/dist/core/scope.d.ts

@@ -1,5 +1,4 @@
 import type { InstalledPlugin, Scope } from '../types.js';
-export declare function builtinViewsRoot(): string;
 export declare function builtinMemoryRoot(): string;
 export declare function builtinPiPackagesDir(): string;
 export declare function builtinPiPackageDir(name: string): string;
@@ -27,16 +26,12 @@ export declare function pluginsDir(scope: Scope): string | null;
 export declare function marketplacesDir(scope: Scope): string | null;
 /** Where substrate memory documents live per scope. Builtin memory is the
  *  special case — its own package dir (builtinMemoryRoot), since the builtin
- *  scope has no scopeRoot — mirroring viewsDir's builtin handling. User and
- *  project memory live at scopeRoot(scope)/memory. */
+ *  scope has no scopeRoot. User and project memory live at
+ *  scopeRoot(scope)/memory. */
 export declare function scopeMemoryDir(scope: Scope): string | null;
 /** Where a plugin's substrate memory documents live: `<plugin.root>/memory`.
  *  The resolver mounts these under the virtual `<pluginName>/` namespace. */
 export declare function pluginMemoryDir(plugin: InstalledPlugin): string;
-/** Where view definition dirs live per scope. Builtin views sit directly under
- *  builtinViewsRoot() (no `views/` segment — they ARE the builtin views dir),
- *  matching the loader's `<root>/<name>/core.mjs` resolution. */
-export declare function viewsDir(scope: Scope): string | null;
 export declare function resolveScopeArg(scopeArg: string | undefined): Scope | 'all';
 export declare function listScopes(scopeArg: string | undefined): Scope[];
 export declare function resetScopeCache(): void;

package/dist/core/scope.js

@@ -1,8 +1,8 @@
 import { homedir } from 'node:os';
 import { existsSync, statSync, realpathSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { CRTR_DIR_NAME } from '../types.js';
+import { assetRoot } from './asset-root.js';
 import { usage } from './errors.js';
 import { loadProfileManifest } from './profiles/manifest.js';
 // Cache of resolved project-scope-root STACKS, keyed by (resolved cwd, profile
@@ -17,30 +17,13 @@ const scopeRootsCache = new Map();
 function scopeRootsCacheKey(resolvedStartDir, profileId) {
     return `${resolvedStartDir}\u0000${profileId ?? ''}`;
 }
-export function builtinViewsRoot() {
-    // Resolved relative to this file: dist/core/scope.js → dist/builtin-views/
-    // (src/ at dev time).
-    const thisFile = fileURLToPath(import.meta.url);
-    const coreDir = dirname(thisFile);
-    const pkgDir = dirname(coreDir); // src/ or dist/
-    return join(pkgDir, 'builtin-views');
-}
 export function builtinMemoryRoot() {
-    // The substrate's shipped built-in documents live in their OWN package dir,
-    // resolved relative to this file: dist/core/scope.js → dist/builtin-memory/
-    // (src/ at dev time). This is a HARD special case (design verdict m2): builtin
-    // memory is the only content the builtin scope carries — the scope has no
-    // scopeRoot (scopeRoot('builtin') is null).
-    const thisFile = fileURLToPath(import.meta.url);
-    const coreDir = dirname(thisFile);
-    const pkgDir = dirname(coreDir); // src/ or dist/
-    return join(pkgDir, 'builtin-memory');
+    // Builtin memory is the only content the builtin scope carries — the scope
+    // has no scopeRoot (scopeRoot('builtin') is null).
+    return join(assetRoot(), 'builtin-memory');
 }
 export function builtinPiPackagesDir() {
-    const thisFile = fileURLToPath(import.meta.url);
-    const coreDir = dirname(thisFile);
-    const pkgDir = dirname(coreDir); // src/ or dist/
-    return join(pkgDir, 'builtin-pi-packages');
+    return join(assetRoot(), 'builtin-pi-packages');
 }
 export function builtinPiPackageDir(name) {
     return join(builtinPiPackagesDir(), name);
@@ -158,8 +141,8 @@ export function projectScopeRoots(startDir, profileId) {
     return findProjectScopeRoots(startDir, profileId);
 }
 export function scopeRoot(scope) {
-    // The builtin scope has no scope-root dir: its only content is memory
-    // (builtinMemoryRoot) and views (builtinViewsRoot), both hard special cases.
+    // The builtin scope has no scope-root dir; its content lives in dedicated
+    // package directories such as builtinMemoryRoot().
     if (scope === 'builtin')
         return null;
     return scope === 'user' ? userScopeRoot() : projectScopeRoot();
@@ -197,8 +180,8 @@ export function marketplacesDir(scope) {
 }
 /** Where substrate memory documents live per scope. Builtin memory is the
  *  special case — its own package dir (builtinMemoryRoot), since the builtin
- *  scope has no scopeRoot — mirroring viewsDir's builtin handling. User and
- *  project memory live at scopeRoot(scope)/memory. */
+ *  scope has no scopeRoot. User and project memory live at
+ *  scopeRoot(scope)/memory. */
 export function scopeMemoryDir(scope) {
     if (scope === 'builtin')
         return builtinMemoryRoot();
@@ -210,15 +193,6 @@ export function scopeMemoryDir(scope) {
 export function pluginMemoryDir(plugin) {
     return join(plugin.root, 'memory');
 }
-/** Where view definition dirs live per scope. Builtin views sit directly under
- *  builtinViewsRoot() (no `views/` segment — they ARE the builtin views dir),
- *  matching the loader's `<root>/<name>/core.mjs` resolution. */
-export function viewsDir(scope) {
-    if (scope === 'builtin')
-        return builtinViewsRoot();
-    const root = scope === 'user' ? userScopeRoot() : projectScopeRoot();
-    return root ? join(root, 'views') : null;
-}
 export function resolveScopeArg(scopeArg) {
     if (scopeArg === undefined)
         return 'all';

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

@@ -70,7 +70,7 @@ export interface SubstrateSchema {
      *  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
+     *  prompted it (CTO ruling 2026-07-03, `insights/agent-memory/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
@@ -86,7 +86,7 @@ export interface SubstrateSchema {
  *  path-derived fallback) and body. This single object flows through the whole
  *  pipeline (gate eval → boot/on-read render), so a renderer never re-parses. */
 export interface SubstrateDoc extends SubstrateSchema {
-    /** Resolver-supplied identity, e.g. `taste/document-substrate` or an explicit
+    /** Resolver-supplied identity, e.g. `insights/agent-memory/document-substrate` or an explicit
      *  frontmatter name when one is present. */
     name: string;
     /** The scope this doc resolved from. */

package/dist/core/termrender/code-doc.d.ts

@@ -0,0 +1,12 @@
+import { type RenderedDoc } from './termrender.js';
+export declare function isMarkdownFile(file: string): boolean;
+/** Fence info string for a source file — `text` when the extension is unknown,
+ *  which every highlighter degrades to plain text on. */
+export declare function fenceLanguageFor(file: string): string;
+/** Wrap source text as a fenced block. The fence is grown past the longest
+ *  backtick run in the content, so a file that itself contains ``` can't close
+ *  its own block. */
+export declare function codeFenceDocument(content: string, language: string): string;
+/** Render a source file as a syntax-highlighted code panel whose spans are
+ *  source lines — the code-file counterpart of `renderReviewDoc`. */
+export declare function codeRenderedDoc(content: string, language: string, width: number): RenderedDoc;

package/dist/core/termrender/code-doc.js

@@ -0,0 +1,92 @@
+import { extname } from 'node:path';
+import { documentLines } from '../document-lines.js';
+import { renderMarkdownWithMap } from './termrender.js';
+// ── Source files as review documents ─────────────────────────────────────────
+//
+// A review ticket may point at a .ts/.py/.sql source file, not just a .md
+// artifact. Every surface still wants ONE rendering story, so a source file is
+// presented as a single fenced code block: termrender (Pygments) and the
+// browser (highlight.js) then syntax-highlight it for free, and the fence's
+// language comes from the file extension.
+//
+// The one cost is a line shift: the fence's opening line makes source line N
+// land on line N+1 of the wrapped document. `codeRenderedDoc` folds that back
+// out so every span/anchor the surfaces expose is a real SOURCE line number.
+/** Extension → fence info string. Names are the ones Pygments (termrender) and
+ *  highlight.js (browser) both accept, so one map serves every surface. */
+const FENCE_BY_EXT = {
+    '.ts': 'typescript', '.mts': 'typescript', '.cts': 'typescript', '.tsx': 'tsx',
+    '.js': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript', '.jsx': 'jsx',
+    '.py': 'python', '.rb': 'ruby', '.go': 'go', '.rs': 'rust', '.java': 'java',
+    '.c': 'c', '.h': 'c', '.cc': 'cpp', '.cpp': 'cpp', '.hpp': 'cpp', '.cs': 'csharp',
+    '.swift': 'swift', '.kt': 'kotlin', '.php': 'php', '.lua': 'lua', '.pl': 'perl',
+    '.sh': 'bash', '.bash': 'bash', '.zsh': 'bash', '.fish': 'fish',
+    '.sql': 'sql', '.json': 'json', '.jsonc': 'json', '.yaml': 'yaml', '.yml': 'yaml',
+    '.toml': 'toml', '.ini': 'ini', '.xml': 'xml', '.html': 'html', '.htm': 'html',
+    '.css': 'css', '.scss': 'scss', '.less': 'less', '.vim': 'vim', '.el': 'lisp',
+    '.ex': 'elixir', '.exs': 'elixir', '.erl': 'erlang', '.hs': 'haskell',
+    '.scala': 'scala', '.dart': 'dart', '.r': 'r', '.jl': 'julia', '.zig': 'zig',
+    '.tf': 'terraform', '.proto': 'protobuf', '.graphql': 'graphql', '.gql': 'graphql',
+    '.dockerfile': 'dockerfile', '.diff': 'diff', '.patch': 'diff', '.csv': 'text',
+    '.txt': 'text', '.log': 'text', '.env': 'bash', '.mk': 'makefile',
+};
+/** Markdown extensions render as a DOCUMENT (headings, tables, Mermaid); every
+ *  other text file renders as code. */
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown', '.mdown', '.mkd']);
+export function isMarkdownFile(file) {
+    return MARKDOWN_EXTENSIONS.has(extname(file).toLowerCase());
+}
+/** Fence info string for a source file — `text` when the extension is unknown,
+ *  which every highlighter degrades to plain text on. */
+export function fenceLanguageFor(file) {
+    const ext = extname(file).toLowerCase();
+    if (ext === '') {
+        // Extensionless but conventionally-named files still have obvious types.
+        const base = file.slice(file.lastIndexOf('/') + 1).toLowerCase();
+        if (base === 'dockerfile')
+            return 'dockerfile';
+        if (base === 'makefile')
+            return 'makefile';
+        return 'text';
+    }
+    return FENCE_BY_EXT[ext] ?? 'text';
+}
+/** Wrap source text as a fenced block. The fence is grown past the longest
+ *  backtick run in the content, so a file that itself contains ``` can't close
+ *  its own block. */
+export function codeFenceDocument(content, language) {
+    let longest = 0;
+    for (const run of content.matchAll(/`+/g))
+        longest = Math.max(longest, run[0].length);
+    const fence = '`'.repeat(Math.max(3, longest + 1));
+    const body = content.endsWith('\n') ? content.slice(0, -1) : content;
+    return `${fence}${language}\n${body}\n${fence}\n`;
+}
+/** Shift a rendered wrapped-document map back onto SOURCE line numbers: the
+ *  opening fence occupies line 1, so document line N is source line N-1.
+ *
+ *  Rows that touch a fence line are the panel's border/title chrome, not
+ *  source: they lose BOTH their span and their block row so nothing anchors to
+ *  them — otherwise the top border would be a step in j/k that selects the
+ *  whole file. */
+function foldFenceOffset(doc, sourceLineCount) {
+    const closingFenceLine = sourceLineCount + 2;
+    const clamp = (line) => Math.max(1, Math.min(line - 1, sourceLineCount));
+    const chrome = doc.spans.map((span) => span !== null && (span[0] <= 1 || span[1] >= closingFenceLine));
+    return {
+        lines: doc.lines,
+        rows: doc.rows.map((row, index) => (chrome[index] === true ? null : row)),
+        spans: doc.spans.map((span, index) => {
+            if (span === null || chrome[index] === true)
+                return null;
+            return [clamp(span[0]), clamp(span[1])];
+        }),
+        blocks: doc.blocks.map((block) => ({ type: block.type, start: clamp(block.start), end: clamp(block.end) })),
+    };
+}
+/** Render a source file as a syntax-highlighted code panel whose spans are
+ *  source lines — the code-file counterpart of `renderReviewDoc`. */
+export function codeRenderedDoc(content, language, width) {
+    const sourceLineCount = documentLines(content).length;
+    return foldFenceOffset(renderMarkdownWithMap(codeFenceDocument(content, language), width), sourceLineCount);
+}

package/dist/core/termrender/display.d.ts

@@ -0,0 +1,12 @@
+/** Options for `display()` — the live-watch tmux pane surface. The pane always
+ *  watches the file and live-updates on edits; there is no non-watched mode. */
+export interface DisplayOpts {
+    /** `'auto'` (default) splits until the pane budget, then opens a new window. */
+    window?: 'auto' | 'split' | 'new';
+    /** Pane budget per window before `'auto'` opens a new window. Default 3. */
+    maxPanes?: number;
+}
+export declare function countPanesInCurrentWindow(): number;
+export declare function display(path: string, opts?: DisplayOpts): {
+    paneId?: string;
+};

package/dist/core/termrender/display.js

@@ -0,0 +1,19 @@
+import { spawnSync } from 'node:child_process';
+import { displayInPane } from './termrender.js';
+export function countPanesInCurrentWindow() {
+    // -t '' targets the current window of the current session.
+    const result = spawnSync('tmux', ['list-panes', '-F', '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return 0;
+    return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
+}
+export function display(path, opts) {
+    const window = (opts?.window === 'split' || opts?.window === 'new') ? opts.window : 'auto';
+    const maxPanes = (opts?.maxPanes !== undefined && opts.maxPanes > 0) ? opts.maxPanes : 3;
+    const newWindow = window === 'new' ||
+        (window === 'auto' && countPanesInCurrentWindow() >= maxPanes);
+    // The pane always watches the file — displayed docs are live by definition.
+    return displayInPane(path, { newWindow });
+}

package/dist/core/termrender/termrender.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Memoized, self-healing. Guarantees at most one authoritative renderer
+ * lifecycle per process: trust a valid stamp outright (zero subprocess spawns),
+ * else run ONE provision/verify/publish transition under the exclusive lock.
+ * There is no permanent legacy-verifier fallback — the spawn-based verify
+ * (`binaryOk` + `installedVersion`) is a step INSIDE that single transition,
+ * always followed by publishing the stamp, never a lasting alternate path.
+ *
+ * Single degradation path: `uv` absent → one stderr remediation line + plaintext.
+ * win32 → plaintext (no renderer).
+ *
+ * Invoked at postinstall AND lazily on the first render/check/display call,
+ * so `npm ci --ignore-scripts` consumers still self-heal on first use.
+ */
+export declare function ensureRenderer(): void;
+/** Cheap predicate — true when the pinned managed binary is verified ready. Does not install or spawn. */
+export declare function isRendererReady(): boolean;
+/** Render markdown to terminal lines via the pinned binary; plaintext fallback. */
+export declare function renderMarkdown(md: string, width: number): string[];
+export interface RenderedDoc {
+    /** Rendered ANSI rows — byte-identical to the plain `doc render` output. */
+    lines: string[];
+    /** Per-row index into `blocks`; null for the blank separator rows between blocks. */
+    rows: (number | null)[];
+    /** Per-row finest 1-indexed inclusive source-line range the renderer knows
+     *  (a bullet, a table row, a code line…); null for separator rows and rows
+     *  of unmapped blocks. Same length as `lines`. */
+    spans: ([number, number] | null)[];
+    /** Per top-level block: its termrender block type plus 1-indexed inclusive
+     *  source-line bounds. Never empty. */
+    blocks: {
+        type: string;
+        start: number;
+        end: number;
+    }[];
+}
+/** Render markdown with a row→source-line map via the pinned binary
+ *  (`doc render --line-map`); plaintext paragraph-block fallback. */
+export declare function renderMarkdownWithMap(md: string, width: number): RenderedDoc;
+/**
+ * The shared block-aware mapped render: prose blocks keep the readability cap
+ * (`proseWidth`), while diagram blocks are re-rendered at the pane's full
+ * `paneWidth` and spliced back in by block index. Both surfaces (terminal
+ * review and the ask deck) go through this, so "which blocks may be wide" is
+ * decided once, from the renderer's own block types, never by heuristics on
+ * the emitted rows.
+ *
+ * Row order, block list and source spans are the narrow render's; only the
+ * rows OF a wide block are replaced, so anchoring stays source-based and
+ * unchanged.
+ */
+export declare function renderMarkdownBlockAware(md: string, proseWidth: number, paneWidth: number): RenderedDoc;
+/** Block-aware render as plain rows, for surfaces that do not anchor. */
+export declare function renderMarkdownBlockAwareLines(md: string, proseWidth: number, paneWidth: number): string[];
+/** Validate markdown via `termrender doc check`. */
+export declare function checkMarkdown(md: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export interface DisplayInPaneOpts {
+    /** Open in a new tmux window instead of splitting the current one. */
+    newWindow?: boolean;
+}
+/**
+ * Spawn termrender into a live tmux pane. The pane-budget policy (whether to
+ * split vs open a new window) is decided by the caller (`src/surfaces/
+ * display.ts`); this is the thin managed-binary spawn it delegates to.
+ */
+export declare function displayInPane(path: string, opts?: DisplayInPaneOpts): {
+    paneId?: string;
+};