byterover-cli 2.0.0 → 2.1.0

package/dist/agent/infra/system-prompt/contributors/map-selection-contributor.d.ts

@@ -0,0 +1,16 @@
+import type { ContributorContext, SystemPromptContributor } from '../../../core/domain/system-prompt/types.js';
+/**
+ * System prompt contributor that injects tool selection guidance for
+ * parallel map tools (llm_map, agentic_map).
+ *
+ * Only active for 'curate' and 'curate-folder' commands, and only when
+ * the map tools are available in the current tool set.
+ *
+ * Based on VoltCode's subagent-rules.txt and symbolic-recursion.txt.
+ */
+export declare class MapSelectionContributor implements SystemPromptContributor {
+    readonly id: string;
+    readonly priority: number;
+    constructor(id: string, priority: number);
+    getContent(context: ContributorContext): Promise<string>;
+}

package/dist/agent/infra/system-prompt/contributors/map-selection-contributor.js

@@ -0,0 +1,47 @@
+import { ToolName } from '../../../core/domain/tools/constants.js';
+/**
+ * System prompt contributor that injects tool selection guidance for
+ * parallel map tools (llm_map, agentic_map).
+ *
+ * Only active for 'curate' and 'curate-folder' commands, and only when
+ * the map tools are available in the current tool set.
+ *
+ * Based on VoltCode's subagent-rules.txt and symbolic-recursion.txt.
+ */
+export class MapSelectionContributor {
+    id;
+    priority;
+    constructor(id, priority) {
+        this.id = id;
+        this.priority = priority;
+    }
+    async getContent(context) {
+        // Only inject for curate commands
+        if (context.commandType !== 'curate') {
+            return '';
+        }
+        const tools = context.availableTools ?? [];
+        const hasLlmMap = tools.includes(ToolName.LLM_MAP);
+        const hasAgenticMap = tools.includes(ToolName.AGENTIC_MAP);
+        // Only inject if at least one map tool is available
+        if (!hasLlmMap && !hasAgenticMap) {
+            return '';
+        }
+        const lines = [
+            '<parallel-processing-guidance>',
+            'When processing multiple items during curation, choose the right approach:',
+            '',
+            '| Scenario | Tool | Why |',
+            '|----------|------|-----|',
+            '| 1-5 items, context-dependent decisions | Direct curate tool | Cross-item awareness needed |',
+        ];
+        if (hasLlmMap) {
+            lines.push('| 5+ items, independent extraction/classification | llm_map | Parallel stateless LLM calls, fast |');
+        }
+        if (hasAgenticMap) {
+            lines.push('| 5+ items, need file reads or tool access | agentic_map | Parallel sub-agents with tools |');
+        }
+        lines.push('| Cross-item dedup/merge decisions | Always direct curate | Needs full context tree visibility |', '', 'Key rules:', '- Map tools process items in COMPLETE ISOLATION — each item cannot see others.', '- Use map tools for the extraction/classification PHASE, then curate tool for final decisions.', '- Two-phase pattern for folder curation: (1) llm_map to extract knowledge from each file, (2) curate to deduplicate and organize.', '- Input/output for map tools: JSONL files (one JSON object per line).', '', 'Map tool output behavior:', '- Map tools may return a `summaryHandle` field — bounded continuation context summarizing processed items.', '- `summaryHandle` is optional helper context; its absence is non-fatal (fail-open design).', '- The JSONL output file is always the source of truth for per-item results.', '- Cross-item deduplication must happen in the curate phase, not during map processing.', '</parallel-processing-guidance>');
+        return lines.join('\n');
+    }
+}

package/dist/agent/infra/tools/core-tool-scheduler.js

@@ -91,8 +91,10 @@ export class CoreToolScheduler {
         this.updateStatus(execution, 'executing');
         execution.startedAt = new Date();
         try {
-            // Pass full context (including taskId) to toolProvider for subagent billing
+            // Pass full context (including taskId, commandType, metadata) to toolProvider
             const result = await this.toolProvider.executeTool(toolName, args, context.sessionId, {
+                commandType: context.commandType,
+                metadata: context.metadata,
                 sessionId: context.sessionId,
                 taskId: context.taskId,
             });

package/dist/agent/infra/tools/implementations/agentic-map-tool.d.ts

@@ -0,0 +1,35 @@
+import type { Tool } from '../../../core/domain/tools/types.js';
+import type { ICipherAgent } from '../../../core/interfaces/i-cipher-agent.js';
+import type { IContentGenerator } from '../../../core/interfaces/i-content-generator.js';
+import type { ILogger } from '../../../core/interfaces/i-logger.js';
+import type { ITokenizer } from '../../../core/interfaces/i-tokenizer.js';
+import { executeAgenticMap } from '../../map/agentic-map-service.js';
+/**
+ * Create the agentic_map tool.
+ *
+ * Runs a parallel map over a JSONL file. For each item (line), spawns a
+ * sub-agent that receives the prompt plus a standardized metadata block.
+ * The sub-agent must output a JSON value that validates against the provided
+ * output schema.
+ *
+ * Use this instead of llm_map when items need tool access (file reads,
+ * code execution, knowledge search). Use llm_map when items don't need
+ * tools — it's faster and cheaper.
+ *
+ * @param agent - The cipher agent for creating sub-sessions
+ * @param workingDirectory - Project root directory
+ * @param options - Optional dependencies for ContextTreeStore
+ * @param options.executeAgenticMapImpl - Test seam override for executeAgenticMap
+ * @param options.generator - Content generator for context compaction summaries
+ * @param options.logger - Logger for fail-open warnings
+ * @param options.maxContextTokens - Model context window used to size context tree threshold
+ * @param options.tokenizer - Tokenizer used by ContextTreeStore
+ */
+export declare function createAgenticMapTool(agent: ICipherAgent, workingDirectory: string, options?: {
+    /** Test seam: replaces executeAgenticMap for unit tests. Do not set in production. */
+    executeAgenticMapImpl?: typeof executeAgenticMap;
+    generator?: IContentGenerator;
+    logger?: ILogger;
+    maxContextTokens?: number;
+    tokenizer?: ITokenizer;
+}): Tool;

package/dist/agent/infra/tools/implementations/agentic-map-tool.js

@@ -0,0 +1,156 @@
+import { randomUUID } from 'node:crypto';
+import { executeAgenticMap, getNestingRecord, HARD_MAX_DEPTH } from '../../map/agentic-map-service.js';
+import { ContextTreeStore } from '../../map/context-tree-store.js';
+import { AgenticMapParametersSchema } from '../../map/map-shared.js';
+/**
+ * Create the agentic_map tool.
+ *
+ * Runs a parallel map over a JSONL file. For each item (line), spawns a
+ * sub-agent that receives the prompt plus a standardized metadata block.
+ * The sub-agent must output a JSON value that validates against the provided
+ * output schema.
+ *
+ * Use this instead of llm_map when items need tool access (file reads,
+ * code execution, knowledge search). Use llm_map when items don't need
+ * tools — it's faster and cheaper.
+ *
+ * @param agent - The cipher agent for creating sub-sessions
+ * @param workingDirectory - Project root directory
+ * @param options - Optional dependencies for ContextTreeStore
+ * @param options.executeAgenticMapImpl - Test seam override for executeAgenticMap
+ * @param options.generator - Content generator for context compaction summaries
+ * @param options.logger - Logger for fail-open warnings
+ * @param options.maxContextTokens - Model context window used to size context tree threshold
+ * @param options.tokenizer - Tokenizer used by ContextTreeStore
+ */
+export function createAgenticMapTool(agent, workingDirectory, options) {
+    const _executeAgenticMap = options?.executeAgenticMapImpl ?? executeAgenticMap;
+    return {
+        description: [
+            'Run a parallel map over a JSONL file using sub-agent sessions.',
+            'For each item (line), spawn a sub-agent that receives your prompt',
+            'plus a standardized metadata block containing the item.',
+            'The sub-agent must output a JSON value conforming to the output schema.',
+            '',
+            'Each sub-agent has full tool access (read files, search, code execution)',
+            'unless read_only is set to true (which disables write operations).',
+            '',
+            'Use this tool when items need tool access during processing.',
+            'Use llm_map instead if items only need LLM intelligence — it is faster and cheaper.',
+            '',
+            'Concurrency is capped at 4 parallel sub-agents.',
+            'Input: JSONL file (one JSON object per line)',
+            'Output: JSONL file with one result per line, ordered by input line.',
+            '',
+            'Results include an optional summaryHandle — a compact summary of processed items.',
+            'The JSONL output file is always the source of truth for per-item results.',
+        ].join('\n'),
+        async execute(input, context) {
+            const params = AgenticMapParametersSchema.parse(input);
+            // [Guard A] Write-enabled + missing sessionId.
+            // In standard ToolManager execution this is unreachable: ToolManager always injects
+            // sessionId (tool-manager.ts:159). Only reachable via direct tool invocation
+            // that bypasses ToolManager (tests, headless).
+            if (params.read_only === false && !context?.sessionId) {
+                throw new Error('agentic_map: session ID unavailable for write-enabled call. ' +
+                    'Cannot determine nesting depth. This is a bug — please report it.');
+            }
+            const callerRecord = context?.sessionId ? getNestingRecord(context.sessionId) : undefined;
+            // [Guard B] Hard assertion: non-write-enabled call inside a write-enabled sub-session.
+            // Catches both explicit read_only=true and omitted read_only (defaults to true in service).
+            // Decoupled from allowlist — catches read_only recursion even if allowlist changes.
+            if (params.read_only !== false && callerRecord !== undefined && !callerRecord.isRootCaller) {
+                throw new Error('agentic_map: read_only=false is required for recursive (nested) calls. ' +
+                    'Recursive composition requires read_only=false.');
+            }
+            // [Guard C] Universal fail-closed: sessionId present but no registry record.
+            // All legitimate sessions are registered at creation (CipherAgent.createSession/start/
+            // getOrCreateSession/stream). An unregistered session with a known ID is either:
+            //   (a) an orphaned sub-session whose record was cleaned by cleanupMapRun, or
+            //   (b) a session created outside the registered paths (unexpected).
+            // Both cases are rejected regardless of read_only.
+            if (context?.sessionId && callerRecord === undefined) {
+                throw new Error('agentic_map: session has no nesting context. ' +
+                    'Session may be orphaned (post-cleanup timeout race) or created outside ' +
+                    'CipherAgent.createSession()/start(). Aborting to preserve ancestor invariants.');
+            }
+            // [Guard D] Prevent write escalation from query context.
+            // Sub-session commandType is derived from params.read_only, not from caller commandType.
+            // Without this guard, a query session could pass read_only=false and spawn curate
+            // children regardless of whether agentic_map is in the query allowlist.
+            if (params.read_only === false && context?.commandType === 'query') {
+                throw new Error('agentic_map: read_only=false is not permitted from a query context. ' +
+                    'Query sessions are restricted to read-only operations.');
+            }
+            // Three-way nesting branch
+            let nestingDepth;
+            let effectiveMaxDepth;
+            let mapRunId;
+            let ancestorInputPaths;
+            if (callerRecord !== undefined && !callerRecord.isRootCaller) {
+                // ── Sub-session path ──────────────────────────────────────────────
+                // callerRecord was set by processItem in a write-enabled parent run.
+                // LLM cannot override inherited depth limit.
+                nestingDepth = callerRecord.nestingDepth;
+                effectiveMaxDepth = callerRecord.absoluteMaxDepth;
+                mapRunId = callerRecord.mapRunId;
+                ancestorInputPaths = callerRecord.ancestorInputPaths;
+            }
+            else {
+                // ── Root path ─────────────────────────────────────────────────────
+                // callerRecord.isRootCaller === true (pre-registered by CipherAgent.start/createSession)
+                // OR no sessionId (read_only=true direct invocation — structurally unreachable via ToolManager)
+                nestingDepth = 0;
+                effectiveMaxDepth = Math.min(params.max_depth ?? 1, HARD_MAX_DEPTH);
+                mapRunId = randomUUID();
+                ancestorInputPaths = new Set();
+            }
+            // ContextTreeStore construction — UNCHANGED from today
+            const contextTreeStore = options?.generator && options?.tokenizer
+                ? new ContextTreeStore({
+                    generator: options.generator,
+                    tauHard: Math.floor((options.maxContextTokens ?? 100_000) * 0.5),
+                    tokenizer: options.tokenizer,
+                })
+                : undefined;
+            const result = await _executeAgenticMap({
+                abortSignal: context?.signal,
+                agent,
+                ancestorInputPaths,
+                contextTreeStore,
+                effectiveMaxDepth,
+                logger: options?.logger,
+                mapRunId,
+                nestingDepth,
+                onProgress: context?.metadata
+                    ? (progress) => {
+                        context.metadata({
+                            description: `Processing items: ${progress.succeeded + progress.failed}/${progress.total}`,
+                            progress: Math.round(((progress.succeeded + progress.failed) / Math.max(progress.total, 1)) * 100),
+                        });
+                    }
+                    : undefined,
+                params,
+                taskId: context?.taskId,
+                workingDirectory,
+            });
+            return {
+                failed: result.failed,
+                mapId: result.mapId,
+                outputPath: params.output_path,
+                succeeded: result.succeeded,
+                ...(result.summaryHandle && { summaryHandle: result.summaryHandle }),
+                total: result.total,
+            };
+        },
+        getMetadata(args) {
+            return {
+                affectedLocations: [args.output_path],
+                category: 'execute',
+                riskLevel: 'medium',
+            };
+        },
+        id: 'agentic_map',
+        inputSchema: AgenticMapParametersSchema,
+    };
+}

package/dist/agent/infra/tools/implementations/code-exec-tool.js

@@ -79,6 +79,7 @@ export function createCodeExecTool(sandboxService) {
                 : context?.commandType === 'query' ? 8000
                     : undefined;
             const result = await sandboxService.executeCode(code, sessionId, {
+                commandType: context?.commandType,
                 contextPayload,
                 language,
                 maxStdoutChars,

package/dist/agent/infra/tools/implementations/curate-tool.d.ts

@@ -124,13 +124,13 @@ export declare const CurateInputSchema: z.ZodObject<{
         }, "strip", z.ZodTypeAny, {
             tags: string[];
             keywords: string[];
-            relations?: string[] | undefined;
             facts?: {
                 statement: string;
                 value?: string | undefined;
                 subject?: string | undefined;
                 category?: "environment" | "convention" | "other" | "personal" | "preference" | "project" | "team" | undefined;
             }[] | undefined;
+            relations?: string[] | undefined;
             narrative?: {
                 structure?: string | undefined;
                 dependencies?: string | undefined;
@@ -159,14 +159,14 @@ export declare const CurateInputSchema: z.ZodObject<{
             snippets?: string[] | undefined;
         }, {
             tags?: string[] | undefined;
-            keywords?: string[] | undefined;
-            relations?: string[] | undefined;
             facts?: {
                 statement: string;
                 value?: string | undefined;
                 subject?: string | undefined;
                 category?: "environment" | "convention" | "other" | "personal" | "preference" | "project" | "team" | undefined;
             }[] | undefined;
+            keywords?: string[] | undefined;
+            relations?: string[] | undefined;
             narrative?: {
                 structure?: string | undefined;
                 dependencies?: string | undefined;
@@ -262,13 +262,13 @@ export declare const CurateInputSchema: z.ZodObject<{
         content?: {
             tags: string[];
             keywords: string[];
-            relations?: string[] | undefined;
             facts?: {
                 statement: string;
                 value?: string | undefined;
                 subject?: string | undefined;
                 category?: "environment" | "convention" | "other" | "personal" | "preference" | "project" | "team" | undefined;
             }[] | undefined;
+            relations?: string[] | undefined;
             narrative?: {
                 structure?: string | undefined;
                 dependencies?: string | undefined;
@@ -323,14 +323,14 @@ export declare const CurateInputSchema: z.ZodObject<{
         title?: string | undefined;
         content?: {
             tags?: string[] | undefined;
-            keywords?: string[] | undefined;
-            relations?: string[] | undefined;
             facts?: {
                 statement: string;
                 value?: string | undefined;
                 subject?: string | undefined;
                 category?: "environment" | "convention" | "other" | "personal" | "preference" | "project" | "team" | undefined;
             }[] | undefined;
+            keywords?: string[] | undefined;
+            relations?: string[] | undefined;
             narrative?: {
                 structure?: string | undefined;
                 dependencies?: string | undefined;
@@ -389,13 +389,13 @@ export declare const CurateInputSchema: z.ZodObject<{
         content?: {
             tags: string[];
             keywords: string[];
-            relations?: string[] | undefined;
             facts?: {
                 statement: string;
                 value?: string | undefined;
                 subject?: string | undefined;
                 category?: "environment" | "convention" | "other" | "personal" | "preference" | "project" | "team" | undefined;
             }[] | undefined;
+            relations?: string[] | undefined;
             narrative?: {
                 structure?: string | undefined;
                 dependencies?: string | undefined;
@@ -452,14 +452,14 @@ export declare const CurateInputSchema: z.ZodObject<{
         title?: string | undefined;
         content?: {
             tags?: string[] | undefined;
-            keywords?: string[] | undefined;
-            relations?: string[] | undefined;
             facts?: {
                 statement: string;
                 value?: string | undefined;
                 subject?: string | undefined;
                 category?: "environment" | "convention" | "other" | "personal" | "preference" | "project" | "team" | undefined;
             }[] | undefined;
+            keywords?: string[] | undefined;
+            relations?: string[] | undefined;
             narrative?: {
                 structure?: string | undefined;
                 dependencies?: string | undefined;

package/dist/agent/infra/tools/implementations/expand-knowledge-tool.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from '../../../core/domain/tools/types.js';
+/**
+ * Configuration for expand knowledge tool.
+ */
+export interface ExpandKnowledgeToolConfig {
+    baseDirectory?: string;
+}
+/**
+ * Creates the expand knowledge tool.
+ *
+ * Retrieves full content from archived knowledge entries by reading the
+ * lossless .full.md file that the stub points to. No LLM call needed —
+ * purely file-based lookup.
+ *
+ * @param config - Optional configuration
+ * @returns Configured expand knowledge tool
+ */
+export declare function createExpandKnowledgeTool(config?: ExpandKnowledgeToolConfig): Tool;

package/dist/agent/infra/tools/implementations/expand-knowledge-tool.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { FileContextTreeArchiveService } from '../../../../server/infra/context-tree/file-context-tree-archive-service.js';
+import { ToolName } from '../../../core/domain/tools/constants.js';
+/**
+ * Input schema for expand knowledge tool.
+ */
+const ExpandKnowledgeInputSchema = z
+    .object({
+    stubPath: z
+        .string()
+        .min(1)
+        .describe('Path to the .stub.md file in _archived/. ' +
+        'This is the `path` field from search results where symbolKind === "archive_stub".'),
+})
+    .strict();
+/**
+ * Creates the expand knowledge tool.
+ *
+ * Retrieves full content from archived knowledge entries by reading the
+ * lossless .full.md file that the stub points to. No LLM call needed —
+ * purely file-based lookup.
+ *
+ * @param config - Optional configuration
+ * @returns Configured expand knowledge tool
+ */
+export function createExpandKnowledgeTool(config = {}) {
+    const archiveService = new FileContextTreeArchiveService();
+    return {
+        description: 'Retrieve full content from archived knowledge entries. ' +
+            'Use when search results include an archive_stub that you need to drill into.',
+        async execute(input, _context) {
+            const parsed = ExpandKnowledgeInputSchema.parse(input);
+            const result = await archiveService.drillDown(parsed.stubPath, config.baseDirectory);
+            return {
+                fullContent: result.fullContent,
+                originalPath: result.originalPath,
+                tokenCount: result.tokenCount,
+            };
+        },
+        id: ToolName.EXPAND_KNOWLEDGE,
+        inputSchema: ExpandKnowledgeInputSchema,
+    };
+}

package/dist/agent/infra/tools/implementations/llm-map-tool.d.ts

@@ -0,0 +1,24 @@
+import type { Tool } from '../../../core/domain/tools/types.js';
+import type { IContentGenerator } from '../../../core/interfaces/i-content-generator.js';
+import type { ILogger } from '../../../core/interfaces/i-logger.js';
+import type { ITokenizer } from '../../../core/interfaces/i-tokenizer.js';
+/**
+ * Create the llm_map tool.
+ *
+ * Runs a parallel, non-agentic map over a JSONL file. For each item (line),
+ * makes a single LLM API call (no tools, no file I/O, no code execution)
+ * that must return one JSON value conforming to the provided output schema.
+ *
+ * Best for high-throughput, side-effect-free tasks (classification, scoring,
+ * extraction, summarization) where the full context can be included in the
+ * prompt and item JSON.
+ *
+ * @param generator - IContentGenerator for LLM calls
+ * @param workingDirectory - Project root directory
+ * @param options - Optional dependencies for ContextTreeStore
+ */
+export declare function createLlmMapTool(generator: IContentGenerator, workingDirectory: string, options?: {
+    logger?: ILogger;
+    maxContextTokens?: number;
+    tokenizer?: ITokenizer;
+}): Tool;

package/dist/agent/infra/tools/implementations/llm-map-tool.js

@@ -0,0 +1,87 @@
+import { ContextTreeStore } from '../../map/context-tree-store.js';
+import { executeLlmMap } from '../../map/llm-map-service.js';
+import { LlmMapParametersSchema } from '../../map/map-shared.js';
+/**
+ * Create the llm_map tool.
+ *
+ * Runs a parallel, non-agentic map over a JSONL file. For each item (line),
+ * makes a single LLM API call (no tools, no file I/O, no code execution)
+ * that must return one JSON value conforming to the provided output schema.
+ *
+ * Best for high-throughput, side-effect-free tasks (classification, scoring,
+ * extraction, summarization) where the full context can be included in the
+ * prompt and item JSON.
+ *
+ * @param generator - IContentGenerator for LLM calls
+ * @param workingDirectory - Project root directory
+ * @param options - Optional dependencies for ContextTreeStore
+ */
+export function createLlmMapTool(generator, workingDirectory, options) {
+    return {
+        description: [
+            'Run a parallel, non-agentic map over a JSONL file.',
+            'For each item (line), make a single LLM API call (no tools, no file I/O)',
+            'that must return one JSON value conforming to the provided output schema.',
+            '',
+            'Best for high-throughput, side-effect-free tasks:',
+            '- Classification and scoring',
+            '- Data extraction and transformation',
+            '- Summarization',
+            '- Content analysis',
+            '',
+            'Each item is processed in complete isolation — the LLM cannot see other items.',
+            'If per-item processing requires file reads or tool access, use agentic_map instead.',
+            '',
+            'Input: JSONL file (one JSON object per line)',
+            'Output: JSONL file with one result per line, ordered by input line.',
+            '',
+            'Results include an optional summaryHandle — a compact summary of processed items.',
+            'The JSONL output file is always the source of truth for per-item results.',
+        ].join('\n'),
+        async execute(input, context) {
+            const params = LlmMapParametersSchema.parse(input);
+            // Construct ContextTreeStore if tokenizer available
+            const contextTreeStore = options?.tokenizer
+                ? new ContextTreeStore({
+                    generator,
+                    tauHard: Math.floor((options.maxContextTokens ?? 100_000) * 0.5),
+                    tokenizer: options.tokenizer,
+                })
+                : undefined;
+            const result = await executeLlmMap({
+                abortSignal: context?.signal,
+                contextTreeStore,
+                generator,
+                logger: options?.logger,
+                onProgress: context?.metadata
+                    ? (progress) => {
+                        context.metadata({
+                            description: `Processing items: ${progress.succeeded + progress.failed}/${progress.total} (${progress.succeeded} ok, ${progress.failed} failed)`,
+                            progress: Math.round(((progress.succeeded + progress.failed) / Math.max(progress.total, 1)) * 100),
+                        });
+                    }
+                    : undefined,
+                params,
+                taskId: context?.taskId,
+                workingDirectory,
+            });
+            return {
+                failed: result.failed,
+                mapId: result.mapId,
+                outputPath: params.output_path,
+                succeeded: result.succeeded,
+                ...(result.summaryHandle && { summaryHandle: result.summaryHandle }),
+                total: result.total,
+            };
+        },
+        getMetadata(args) {
+            return {
+                affectedLocations: [args.output_path],
+                category: 'execute',
+                riskLevel: 'low',
+            };
+        },
+        id: 'llm_map',
+        inputSchema: LlmMapParametersSchema,
+    };
+}

package/dist/agent/infra/tools/implementations/memory-symbol-tree.d.ts

@@ -7,8 +7,16 @@ export declare enum MemorySymbolKind {
     Context = 4,
     Domain = 1,
     Subtopic = 3,
+    Summary = 5,
     Topic = 2
 }
+/**
+ * Summary metadata attached to folder nodes that have an _index.md file.
+ */
+export interface SummaryInfo {
+    condensationOrder: number;
+    tokenCount: number;
+}
 /**
  * A node in the memory symbol tree.
  * Represents a domain, topic, subtopic, or individual context entry.
@@ -21,6 +29,8 @@ export interface MemorySymbol {
     parent: MemorySymbol | undefined;
     /** Relative path within context-tree, e.g. "auth/jwt-tokens/refresh.md" */
     path: string;
+    /** Present when this folder has an _index.md summary */
+    summaryInfo?: SummaryInfo;
 }
 export interface SymbolMetadata {
     importance: number;
@@ -28,6 +38,16 @@ export interface SymbolMetadata {
     maturity: string;
     tags: string[];
 }
+/**
+ * Minimal summary document shape for attaching summary info to folder nodes.
+ * Built from _index.md files during search indexing.
+ */
+export interface SummaryDocLike {
+    condensationOrder: number;
+    /** Path to the _index.md file, e.g. "domain/topic/_index.md" */
+    path: string;
+    tokenCount: number;
+}
 /**
  * The complete memory symbol tree, built from the context-tree filesystem.
  */
@@ -42,11 +62,15 @@ export interface MemorySymbolTree {
  */
 export interface OverviewEntry {
     childCount: number;
+    /** Present for folder nodes with _index.md summaries */
+    condensationOrder?: number;
     importance: number;
     kind: string;
     maturity: string;
     name: string;
     path: string;
+    /** Present for folder nodes with _index.md summaries */
+    tokenCount?: number;
 }
 /**
  * Bidirectional reference index built from @relation annotations.
@@ -74,8 +98,11 @@ interface DocumentLike {
  *
  * context.md files are absorbed into their parent folder node (enriching its metadata)
  * rather than being treated as leaf Context nodes.
+ *
+ * @param documentMap - Indexed documents (excludes _index.md, includes stubs)
+ * @param summaryMap - Optional map of _index.md summary documents for folder annotation
  */
-export declare function buildSymbolTree(documentMap: Map<string, DocumentLike>): MemorySymbolTree;
+export declare function buildSymbolTree(documentMap: Map<string, DocumentLike>, summaryMap?: Map<string, SummaryDocLike>): MemorySymbolTree;
 /**
  * Get a structural overview of the symbol tree at configurable depth.
  *