@kinqs/brainrouter-cli 0.3.4

package/dist/memory/briefing.js

@@ -0,0 +1,152 @@
+import { redactText } from '../state/sessionStore.js';
+import { callMcpTool } from '../runtime/mcpUtils.js';
+/**
+ * Run pre-turn memory queries in parallel and assemble a compact briefing block.
+ * This is the System-1 entry point: every turn pays a small fixed cost to ask
+ * the BrainRouter brain "what do I already know that matters here?" so the LLM
+ * does not redo work the agent has done before in this workspace.
+ */
+export async function buildMemoryBriefing(inputs) {
+    const { mcpClient, mcpTools, sessionKey, workspaceRoot, query, activeSkill } = inputs;
+    const maxChars = inputs.maxCharsPerSource ?? 4000;
+    const toolNames = new Set(mcpTools.map((t) => t.name));
+    const tasks = [];
+    if (toolNames.has('memory_recall')) {
+        tasks.push(callSafe('memory_recall', { sessionKey, query, activeSkill }, mcpClient, maxChars, extractRecords));
+    }
+    if (toolNames.has('memory_working_context')) {
+        tasks.push(callSafe('memory_working_context', { sessionKey, workspacePath: workspaceRoot }, mcpClient, maxChars));
+    }
+    if (toolNames.has('memory_task_state')) {
+        tasks.push(callSafe('memory_task_state', { query }, mcpClient, maxChars));
+    }
+    const results = await Promise.all(tasks);
+    const sections = [];
+    const sourcesQueried = [];
+    const recalledRecords = [];
+    for (const r of results) {
+        if (!r.text)
+            continue;
+        sourcesQueried.push(r.source);
+        if (r.records && r.records.length > 0) {
+            // Render structured cards instead of dumping the raw JSON. The previous
+            // form emitted ~2-4KB of `recallExplanation`/`sparkedNodes`/etc. per
+            // turn — high signal-to-noise loss AND a 4000-char hard slice that
+            // routinely chopped the payload mid-string. Cards are ~120 chars each.
+            const cards = r.records.slice(0, 8).map((rec) => {
+                const idTag = `[${rec.recordId}]`;
+                const typeTag = rec.type ? ` (${rec.type})` : '';
+                const content = (rec.content ?? '').replace(/\s+/g, ' ').trim();
+                const preview = content.length > 240 ? content.slice(0, 239) + '…' : content;
+                return `- ${idTag}${typeTag} ${preview}`;
+            });
+            sections.push(`### ${prettyLabel(r.source)}\n${cards.join('\n')}`);
+            recalledRecords.push(...r.records);
+        }
+        else {
+            // No structured records to render. Treat the JSON dump as opaque and
+            // only include it when it carries actual signal (skip the
+            // `keyword-empty` / zero-hits responses that the MCP returns when
+            // recall genuinely had nothing to surface).
+            const trimmed = r.text.trim();
+            if (!trimmed ||
+                /"recallStrategy"\s*:\s*"(keyword|hybrid)-empty"/.test(trimmed) ||
+                /^[\s\S]{0,40}"ftsHits"\s*:\s*0\s*,\s*"vecHits"\s*:\s*0/.test(trimmed)) {
+                continue;
+            }
+            sections.push(`### ${prettyLabel(r.source)}\n${redactText(trimmed.slice(0, 1500))}`);
+        }
+    }
+    if (sections.length === 0) {
+        return { block: '', recalledRecordIds: [], recalledRecords: [], sourcesQueried };
+    }
+    const block = [
+        '## BrainRouter Memory Briefing',
+        `Session: ${sessionKey}`,
+        `Workspace: ${workspaceRoot}`,
+        '',
+        'The following context was recalled before this turn. Cite the IDs of records you actually used in your reasoning.',
+        '',
+        ...sections,
+    ].join('\n');
+    const recalledRecordIds = dedupe(recalledRecords.map((r) => r.recordId));
+    return { block, recalledRecordIds, recalledRecords, sourcesQueried };
+}
+/**
+ * Heuristic for which recalled records actually informed the assistant's
+ * final answer. We mark a record as "cited" when:
+ *  - its recordId literally appears in the answer text, OR
+ *  - a distinctive snippet (≥ 24 chars of non-trivial content) from its
+ *    content appears verbatim in the answer.
+ * Conservative on purpose — false positives hurt memory quality more than
+ * false negatives, since uncited records get demoted next time around.
+ */
+export function selectCitedRecordIds(records, finalAnswer) {
+    if (!finalAnswer || records.length === 0)
+        return [];
+    const haystack = finalAnswer.toLowerCase();
+    const cited = [];
+    for (const record of records) {
+        if (!record.recordId)
+            continue;
+        if (haystack.includes(record.recordId.toLowerCase())) {
+            cited.push(record.recordId);
+            continue;
+        }
+        const snippet = extractDistinctiveSnippet(record.content);
+        if (snippet && haystack.includes(snippet.toLowerCase())) {
+            cited.push(record.recordId);
+        }
+    }
+    return dedupe(cited);
+}
+function extractDistinctiveSnippet(content) {
+    if (!content)
+        return undefined;
+    const trimmed = content.trim();
+    if (trimmed.length < 24)
+        return undefined;
+    // Use the longest line that looks like substantive content; skip headings / bullets.
+    const lines = trimmed.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    const ranked = lines
+        .filter((l) => !/^[#>\-*]/.test(l) && l.length >= 24)
+        .sort((a, b) => b.length - a.length);
+    const candidate = ranked[0] ?? trimmed;
+    return candidate.slice(0, Math.min(60, candidate.length));
+}
+async function callSafe(toolName, args, mcpClient, maxChars, extractRecordsFn) {
+    const res = await callMcpTool(mcpClient, toolName, args);
+    if (res.isError || !res.text.trim())
+        return { source: toolName, text: null };
+    const records = extractRecordsFn && res.parsed ? extractRecordsFn(res.parsed) : undefined;
+    return { source: toolName, text: res.text.slice(0, maxChars), records };
+}
+function extractRecords(parsed) {
+    if (!parsed)
+        return [];
+    const records = parsed.recalledCognitiveMemories ??
+        parsed.recalledCognitiveRecords ??
+        parsed.records ??
+        [];
+    if (!Array.isArray(records))
+        return [];
+    return records
+        .filter((r) => r && (typeof r.recordId === 'string' || typeof r.recordId === 'number'))
+        .map((r) => ({
+        recordId: String(r.recordId),
+        content: typeof r.content === 'string' ? r.content : undefined,
+        type: typeof r.type === 'string' ? r.type : undefined,
+        priority: typeof r.priority === 'number' ? r.priority : undefined,
+    }));
+}
+function prettyLabel(toolName) {
+    switch (toolName) {
+        case 'memory_recall': return 'Recalled cognitive memories';
+        case 'memory_working_context': return 'Working memory canvas';
+        case 'memory_task_state': return 'Open task / handover state';
+        default: return toolName;
+    }
+}
+function dedupe(items) {
+    return Array.from(new Set(items));
+}

package/dist/memory/consolidation.d.ts

@@ -0,0 +1,60 @@
+import type { McpClientWrapper } from '../runtime/mcpClient.js';
+/**
+ * Filesystem memory consolidation — the human-readable companion to the
+ * cognitive memory database.
+ *
+ * Brainrouter's MCP already stores recall records in the cognitive memory DB.
+ * This module writes filesystem artifacts so users get a human-readable view
+ * of what was learned across sessions:
+ *
+ *   ~/.brainrouter/workspaces/<encoded>/memories/
+ *     MEMORY.md              - one-line index of all consolidated entries
+ *     raw_memories.md        - merged "raw" memories in stable order
+ *     user.md                - profile facts about the user
+ *     feedback.md            - "do this / don't do this" guidance
+ *     project.md             - in-flight project context
+ *     reference.md           - pointers to external systems
+ *     rollout_summaries/     - one .md per recent session summary
+ *
+ * The CLI populates these from `memory_search`/`memory_recall` results at the
+ * end of a session or when the user runs `/memories consolidate`. This file is
+ * pure — it never calls the LLM; the records were already extracted by the
+ * agent loop and stored via memory_capture_turn.
+ */
+export declare function memoriesDir(workspaceRoot: string): string;
+export declare function ensureMemoriesDir(workspaceRoot: string): string;
+export type MemoryType = 'user' | 'feedback' | 'project' | 'reference';
+export interface MemoryRecord {
+    recordId: string;
+    type: MemoryType | string;
+    content: string;
+    scene?: string;
+    capturedAt?: string;
+}
+interface ConsolidationResult {
+    totalRecords: number;
+    perType: Record<string, number>;
+    files: string[];
+}
+/**
+ * Pull every memory record we can see from MCP and write the per-type
+ * markdown files. Records without a known type land in `raw_memories.md` so
+ * nothing is lost.
+ */
+export declare function consolidateMemories(mcpClient: McpClientWrapper, workspaceRoot: string, options?: {
+    sessionKey?: string;
+    query?: string;
+}): Promise<ConsolidationResult>;
+/**
+ * Write a per-session rollout summary file. Used by /handover or auto-capture
+ * at session end. Each summary lives alongside the others so users can scan
+ * across sessions without trawling transcripts.
+ */
+export declare function writeRolloutSummary(workspaceRoot: string, sessionKey: string, summary: {
+    firstPrompt?: string;
+    lastPrompt?: string;
+    turnCount: number;
+    totalTokens: number;
+    body: string;
+}): string;
+export {};

package/dist/memory/consolidation.js

@@ -0,0 +1,208 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { callMcpTool } from '../runtime/mcpUtils.js';
+import { getWorkspaceStateRoot } from '../state/cliState.js';
+/**
+ * Filesystem memory consolidation — the human-readable companion to the
+ * cognitive memory database.
+ *
+ * Brainrouter's MCP already stores recall records in the cognitive memory DB.
+ * This module writes filesystem artifacts so users get a human-readable view
+ * of what was learned across sessions:
+ *
+ *   ~/.brainrouter/workspaces/<encoded>/memories/
+ *     MEMORY.md              - one-line index of all consolidated entries
+ *     raw_memories.md        - merged "raw" memories in stable order
+ *     user.md                - profile facts about the user
+ *     feedback.md            - "do this / don't do this" guidance
+ *     project.md             - in-flight project context
+ *     reference.md           - pointers to external systems
+ *     rollout_summaries/     - one .md per recent session summary
+ *
+ * The CLI populates these from `memory_search`/`memory_recall` results at the
+ * end of a session or when the user runs `/memories consolidate`. This file is
+ * pure — it never calls the LLM; the records were already extracted by the
+ * agent loop and stored via memory_capture_turn.
+ */
+export function memoriesDir(workspaceRoot) {
+    return path.join(getWorkspaceStateRoot(workspaceRoot), 'memories');
+}
+export function ensureMemoriesDir(workspaceRoot) {
+    const dir = memoriesDir(workspaceRoot);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    const summaries = path.join(dir, 'rollout_summaries');
+    if (!fs.existsSync(summaries))
+        fs.mkdirSync(summaries, { recursive: true });
+    return dir;
+}
+/**
+ * Pull every memory record we can see from MCP and write the per-type
+ * markdown files. Records without a known type land in `raw_memories.md` so
+ * nothing is lost.
+ */
+export async function consolidateMemories(mcpClient, workspaceRoot, options = {}) {
+    const dir = ensureMemoriesDir(workspaceRoot);
+    const query = options.query ?? '*';
+    const recall = await callMcpTool(mcpClient, 'memory_search', { query, sessionKey: options.sessionKey });
+    if (recall.isError) {
+        throw new Error(`memory_search failed: ${recall.text || '(no message)'}`);
+    }
+    const records = extractRecordsFromMcp(recall.parsed);
+    const buckets = {
+        user: [], feedback: [], project: [], reference: [], raw: [],
+    };
+    for (const rec of records) {
+        const t = String(rec.type ?? '').toLowerCase();
+        if (t === 'user' || t === 'feedback' || t === 'project' || t === 'reference') {
+            buckets[t].push(rec);
+        }
+        else {
+            buckets.raw.push(rec);
+        }
+    }
+    const filesWritten = [];
+    for (const t of ['user', 'feedback', 'project', 'reference', 'raw']) {
+        const file = path.join(dir, t === 'raw' ? 'raw_memories.md' : `${t}.md`);
+        fs.writeFileSync(file, renderMemoryFile(t, buckets[t]), 'utf8');
+        filesWritten.push(file);
+    }
+    const index = renderIndex(records, buckets);
+    const indexFile = path.join(dir, 'MEMORY.md');
+    fs.writeFileSync(indexFile, index, 'utf8');
+    filesWritten.push(indexFile);
+    return {
+        totalRecords: records.length,
+        perType: {
+            user: buckets.user.length,
+            feedback: buckets.feedback.length,
+            project: buckets.project.length,
+            reference: buckets.reference.length,
+            raw: buckets.raw.length,
+        },
+        files: filesWritten.map((p) => path.relative(workspaceRoot, p)),
+    };
+}
+function extractRecordsFromMcp(parsed) {
+    if (!parsed)
+        return [];
+    const candidates = [
+        parsed?.records,
+        parsed?.results,
+        parsed?.items,
+        Array.isArray(parsed) ? parsed : undefined,
+    ].filter((x) => Array.isArray(x));
+    for (const list of candidates) {
+        const out = [];
+        for (const r of list) {
+            if (!r)
+                continue;
+            const recordId = String(r.recordId ?? r.id ?? r.record_id ?? '');
+            if (!recordId)
+                continue;
+            out.push({
+                recordId,
+                type: String(r.type ?? r.memoryType ?? 'raw'),
+                content: String(r.content ?? r.text ?? r.body ?? r.summary ?? ''),
+                scene: r.scene ?? r.focusScene,
+                capturedAt: r.capturedAt ?? r.createdAt ?? r.timestamp,
+            });
+        }
+        if (out.length > 0)
+            return out;
+    }
+    return [];
+}
+function renderMemoryFile(type, records) {
+    const heading = type === 'raw' ? 'Raw memories' : `${capitalize(type)} memory`;
+    const intro = type === 'raw'
+        ? 'Memories whose type the agent did not classify into user/feedback/project/reference.'
+        : descriptionFor(type);
+    const body = records.length === 0
+        ? '_(empty — no records of this type yet)_'
+        : records.sort(stableSort).map(renderRecord).join('\n\n');
+    return [`# ${heading}`, '', intro, '', body, ''].join('\n');
+}
+function descriptionFor(type) {
+    switch (type) {
+        case 'user': return 'Profile facts about the user — role, expertise, goals.';
+        case 'feedback': return 'Validated guidance from the user about how to approach work (do/avoid).';
+        case 'project': return 'In-flight project context: deadlines, stakeholders, motivation.';
+        case 'reference': return 'Pointers to external systems (Linear, Grafana, GitHub) where authoritative info lives.';
+        default: return '';
+    }
+}
+function renderRecord(rec) {
+    const lines = [];
+    lines.push(`## ${rec.recordId}`);
+    if (rec.scene)
+        lines.push(`*Scene: ${rec.scene}*`);
+    if (rec.capturedAt)
+        lines.push(`*Captured: ${rec.capturedAt}*`);
+    lines.push('');
+    lines.push(rec.content.trim());
+    return lines.join('\n');
+}
+function renderIndex(records, buckets) {
+    const lines = [];
+    lines.push('# Memory index');
+    lines.push('');
+    lines.push(`_${records.length} consolidated memory records across ${Object.keys(buckets).length} files._`);
+    lines.push('');
+    for (const t of ['user', 'feedback', 'project', 'reference', 'raw']) {
+        const list = buckets[t];
+        if (list.length === 0)
+            continue;
+        const file = t === 'raw' ? 'raw_memories.md' : `${t}.md`;
+        lines.push(`## ${capitalize(t)} (${list.length})`);
+        lines.push(`File: [${file}](${file})`);
+        lines.push('');
+        for (const r of list.slice(0, 12).sort(stableSort)) {
+            const oneLine = r.content.split('\n')[0].slice(0, 140);
+            lines.push(`- \`${r.recordId}\` — ${oneLine}`);
+        }
+        if (list.length > 12)
+            lines.push(`- _…and ${list.length - 12} more in ${file}_`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function stableSort(a, b) {
+    return a.recordId.localeCompare(b.recordId);
+}
+function capitalize(s) {
+    if (!s)
+        return s;
+    return s[0].toUpperCase() + s.slice(1);
+}
+/**
+ * Write a per-session rollout summary file. Used by /handover or auto-capture
+ * at session end. Each summary lives alongside the others so users can scan
+ * across sessions without trawling transcripts.
+ */
+export function writeRolloutSummary(workspaceRoot, sessionKey, summary) {
+    ensureMemoriesDir(workspaceRoot);
+    const safe = sessionKey.replace(/[^A-Za-z0-9._-]+/g, '-');
+    const file = path.join(memoriesDir(workspaceRoot), 'rollout_summaries', `${safe}.md`);
+    const lines = [];
+    lines.push(`# Session: ${sessionKey}`);
+    lines.push('');
+    lines.push(`- Turns: ${summary.turnCount}`);
+    lines.push(`- Total tokens: ${summary.totalTokens}`);
+    if (summary.firstPrompt)
+        lines.push(`- First prompt: ${truncate(summary.firstPrompt, 200)}`);
+    if (summary.lastPrompt)
+        lines.push(`- Last prompt: ${truncate(summary.lastPrompt, 200)}`);
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(summary.body.trim());
+    lines.push('');
+    fs.writeFileSync(file, lines.join('\n'), 'utf8');
+    return path.relative(workspaceRoot, file);
+}
+function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return `${s.slice(0, n)}…`;
+}

package/dist/memory/formatters.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Compact renderers for BrainRouter memory tool results.
+ *
+ * The raw `memory_recall` / `memory_search` payload can be 70k+ chars of
+ * mixed JSON + Mermaid graph context + persona blocks. Dumping it to stdout
+ * gave the user a "JSON sea" and gave the LLM 70k tokens of noise to
+ * hallucinate from. These helpers parse the result and render a small,
+ * card-style list keyed by recordId so the human reader (and any downstream
+ * LLM citation) only sees the facts that are actually present.
+ */
+export interface FlatMemory {
+    recordId: string;
+    type: string;
+    content: string;
+    sceneName?: string;
+    skillTag?: string;
+    priority?: number;
+    confidence?: number;
+}
+/**
+ * Extract the flat memory list from whatever shape memory_recall /
+ * memory_search returned. The MCP wraps payloads in `<relevant-memories>`
+ * XML inside `prependContext`, and ALSO returns parsed arrays at the top
+ * level depending on the variant. We tolerate both.
+ */
+export declare function extractMemories(parsed: any): FlatMemory[];
+/**
+ * Render a compact ANSI-colored block: heading + N cards, each with the
+ * recordId, type tag, scene tag, and a one-line content preview. Returns
+ * the formatted string (no console.log here so callers can choose target).
+ */
+export declare function renderMemoryCards(memories: FlatMemory[], heading: string, limit?: number): string;
+/**
+ * Bound a raw payload to a maximum size so the agent's context doesn't get
+ * blown out by a 70k-char working_context dump. Used by the briefing / slash
+ * command rendering paths.
+ */
+export declare function clampPayload(text: string, maxChars?: number): string;

package/dist/memory/formatters.js

@@ -0,0 +1,102 @@
+/**
+ * Compact renderers for BrainRouter memory tool results.
+ *
+ * The raw `memory_recall` / `memory_search` payload can be 70k+ chars of
+ * mixed JSON + Mermaid graph context + persona blocks. Dumping it to stdout
+ * gave the user a "JSON sea" and gave the LLM 70k tokens of noise to
+ * hallucinate from. These helpers parse the result and render a small,
+ * card-style list keyed by recordId so the human reader (and any downstream
+ * LLM citation) only sees the facts that are actually present.
+ */
+import chalk from 'chalk';
+/**
+ * Extract the flat memory list from whatever shape memory_recall /
+ * memory_search returned. The MCP wraps payloads in `<relevant-memories>`
+ * XML inside `prependContext`, and ALSO returns parsed arrays at the top
+ * level depending on the variant. We tolerate both.
+ */
+export function extractMemories(parsed) {
+    const out = [];
+    const push = (m) => {
+        if (!m || typeof m !== 'object')
+            return;
+        const recordId = (m.recordId ?? m.record_id ?? m.id ?? '').toString();
+        if (!recordId)
+            return;
+        out.push({
+            recordId,
+            type: (m.type ?? 'memory').toString(),
+            content: (m.content ?? m.text ?? '').toString().replace(/\s+/g, ' ').trim(),
+            sceneName: m.sceneName ?? m.scene_name,
+            skillTag: m.skillTag ?? m.skill_tag,
+            priority: typeof m.priority === 'number' ? m.priority : undefined,
+            confidence: typeof m.confidence === 'number' ? m.confidence : undefined,
+        });
+    };
+    // Direct arrays first. The canonical MCP key is `recalledCognitiveMemories`;
+    // the others are tolerated for older payloads / shimmed responses.
+    for (const key of [
+        'recalledCognitiveMemories',
+        'recalledCognitiveRecords',
+        'records',
+        'memories',
+        'recalledMemories',
+    ]) {
+        if (Array.isArray(parsed?.[key]))
+            parsed[key].forEach(push);
+    }
+    // Parse the XML-style prependContext if present and we still have nothing.
+    if (out.length === 0 && typeof parsed?.prependContext === 'string') {
+        const text = parsed.prependContext;
+        // Match `  - [type|scene] content (skill: xxx)` lines. The MCP doesn't
+        // include the recordId in this text-only block, so we synthesize one for
+        // display purposes only — recall callers that need real ids should hit
+        // the JSON path above.
+        const re = /-\s+\[([^\]|]+)\|([^\]]+)\]\s+([^\n]+)/g;
+        let match;
+        let i = 0;
+        while ((match = re.exec(text)) !== null) {
+            out.push({
+                recordId: `inline-${i++}`,
+                type: match[1].trim(),
+                content: match[3].replace(/\(skill:.*$/, '').trim(),
+                sceneName: match[2].trim(),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Render a compact ANSI-colored block: heading + N cards, each with the
+ * recordId, type tag, scene tag, and a one-line content preview. Returns
+ * the formatted string (no console.log here so callers can choose target).
+ */
+export function renderMemoryCards(memories, heading, limit = 10) {
+    if (memories.length === 0) {
+        return `${chalk.bold(heading)}\n  ${chalk.yellow('(no records returned)')}\n`;
+    }
+    const lines = [chalk.bold(heading)];
+    for (const m of memories.slice(0, limit)) {
+        const id = chalk.gray(m.recordId.length > 40 ? m.recordId.slice(0, 37) + '…' : m.recordId);
+        const type = chalk.cyan(`[${m.type}]`);
+        const scene = m.sceneName ? chalk.gray(` · ${m.sceneName}`) : '';
+        const preview = m.content.length > 200 ? m.content.slice(0, 197) + '…' : m.content;
+        lines.push(`  ${type}${scene}`);
+        lines.push(`    ${id}`);
+        lines.push(`    ${preview}`);
+    }
+    if (memories.length > limit) {
+        lines.push(chalk.gray(`  …and ${memories.length - limit} more (use /memory <query> to filter further)`));
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Bound a raw payload to a maximum size so the agent's context doesn't get
+ * blown out by a 70k-char working_context dump. Used by the briefing / slash
+ * command rendering paths.
+ */
+export function clampPayload(text, maxChars = 6000) {
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, maxChars) + `\n…[${text.length - maxChars} chars truncated]`;
+}

package/dist/memory/mentions.d.ts

@@ -0,0 +1,10 @@
+export interface MentionExpansion {
+    expanded: string;
+    mentions: Array<{
+        token: string;
+        resolvedPath: string;
+        bytes: number;
+        truncated: boolean;
+    }>;
+}
+export declare function expandMentions(prompt: string, workspaceRoot: string, maxBytes?: number): MentionExpansion;

package/dist/memory/mentions.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPathInside } from '../state/cliState.js';
+/**
+ * Expand `@path/to/file` mentions in a user prompt by appending the referenced
+ * file contents as a fenced block.
+ *
+ * Rules:
+ *   - Token shape: `@` followed by a workspace-relative path. The path can
+ *     contain letters, digits, `._-/~`, but stops at whitespace or punctuation
+ *     that wouldn't appear in a filename.
+ *   - File must exist and resolve INSIDE the workspace (no `..` escapes).
+ *   - Each file is appended only once even if mentioned multiple times.
+ *   - Mention text in the prompt is left intact so the human-written sentence
+ *     still makes sense; the contents are added below as a context block.
+ *   - Files larger than `maxBytes` are truncated with a marker.
+ *
+ * Returns `{ expanded, mentions }`. `mentions` is the resolved set of files
+ * actually attached, useful for status display.
+ */
+const MAX_BYTES_DEFAULT = 24_000;
+const MENTION_RE = /(^|\s)@([\w./~-][\w./~-]*[\w/])/g;
+export function expandMentions(prompt, workspaceRoot, maxBytes = MAX_BYTES_DEFAULT) {
+    // Resolve each mention to {resolvedPath, body (possibly truncated), truncated}
+    // in a single pass. Re-reading inside the rendering loop with a different
+    // limit would silently undo the truncation we just computed.
+    const mentioned = new Map();
+    let match;
+    MENTION_RE.lastIndex = 0;
+    while ((match = MENTION_RE.exec(prompt)) !== null) {
+        const token = match[2];
+        if (!token || mentioned.has(token))
+            continue;
+        let resolved;
+        try {
+            resolved = path.resolve(workspaceRoot, token);
+        }
+        catch {
+            continue;
+        }
+        if (!isPathInside(workspaceRoot, resolved))
+            continue;
+        if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile())
+            continue;
+        let content = fs.readFileSync(resolved, 'utf8');
+        let truncated = false;
+        if (content.length > maxBytes) {
+            content = content.slice(0, maxBytes) + `\n…[truncated at ${maxBytes} chars]`;
+            truncated = true;
+        }
+        mentioned.set(token, { resolvedPath: resolved, body: content, truncated });
+    }
+    if (mentioned.size === 0)
+        return { expanded: prompt, mentions: [] };
+    const blocks = ['', '---', 'Attached files (from @-mentions):', ''];
+    for (const [token, info] of mentioned.entries()) {
+        const rel = path.relative(workspaceRoot, info.resolvedPath);
+        const ext = path.extname(rel).replace(/^\./, '');
+        blocks.push(`### ${rel} (referenced via @${token}${info.truncated ? ', truncated' : ''})`);
+        blocks.push('```' + (ext || ''));
+        blocks.push(info.body);
+        blocks.push('```');
+        blocks.push('');
+    }
+    const mentions = Array.from(mentioned.entries()).map(([token, info]) => ({
+        token,
+        resolvedPath: info.resolvedPath,
+        bytes: info.body.length,
+        truncated: info.truncated,
+    }));
+    return { expanded: prompt + blocks.join('\n'), mentions };
+}

package/dist/orchestration/orchestrator.d.ts

@@ -0,0 +1,36 @@
+import { type AccessMode } from './roles.js';
+export type ChildStatus = 'pending' | 'running' | 'completed' | 'failed' | 'stale' | 'closed';
+export interface ChildSessionRecord {
+    id: string;
+    label?: string;
+    role: string;
+    access: AccessMode;
+    parentSessionKey: string;
+    prompt: string;
+    status: ChildStatus;
+    startedAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    pid: number;
+    finalOutput?: string;
+    error?: string;
+    /** LLM usage attributable to this child (filled when the child completes). */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        calls: number;
+        turns: number;
+    };
+}
+export declare function listSessions(workspaceRoot: string): ChildSessionRecord[];
+export declare function getSession(workspaceRoot: string, id: string): ChildSessionRecord | undefined;
+export declare function createSession(workspaceRoot: string, input: {
+    role: string;
+    prompt: string;
+    parentSessionKey: string;
+    access?: AccessMode;
+    label?: string;
+}): ChildSessionRecord;
+export declare function updateSession(workspaceRoot: string, id: string, patch: Partial<ChildSessionRecord>): ChildSessionRecord;
+export declare function reconcileStale(workspaceRoot: string): number;
+export declare function formatSessionSummary(s: ChildSessionRecord): string;