byterover-cli 1.8.0 → 2.1.0

package/dist/agent/infra/storage/message-storage-service.js

@@ -88,23 +88,23 @@ export class MessageStorageService {
         if (!session) {
             return false;
         }
-        // Delete all messages and their parts
+        const ops = [];
+        // Collect all message keys and their part keys
         const messageKeys = await this.keyStorage.list(this.messagePrefix(sessionId));
         for (const messageKey of messageKeys) {
             const messageId = messageKey[2];
-            // Delete all parts for this message
             // eslint-disable-next-line no-await-in-loop
             const partKeys = await this.keyStorage.list(this.partPrefix(messageId));
             for (const partKey of partKeys) {
-                // eslint-disable-next-line no-await-in-loop
-                await this.keyStorage.delete(partKey);
+                ops.push({ key: partKey, type: 'delete' });
             }
-            // Delete the message
-            // eslint-disable-next-line no-await-in-loop
-            await this.keyStorage.delete(messageKey);
+            ops.push({ key: messageKey, type: 'delete' });
         }
         // Delete the session record
-        return this.keyStorage.delete(this.sessionKey(sessionId));
+        ops.push({ key: this.sessionKey(sessionId), type: 'delete' });
+        // Atomic delete of everything
+        await this.keyStorage.batch(ops);
+        return true;
     }
     /**
      * Get the session record, if it exists.
@@ -196,29 +196,53 @@ export class MessageStorageService {
             return { hitCompactionBoundary: false, messages: [] };
         }
         const stopAtCompaction = options?.stopAtCompaction ?? true;
-        const messages = [];
+        // Bulk-load all messages for this session in one query
+        const allMessageEntries = await this.keyStorage.listWithValues(this.messagePrefix(sessionId));
+        const messageMap = new Map();
+        for (const entry of allMessageEntries) {
+            messageMap.set(entry.value.id, entry.value);
+        }
+        // Traverse linked list in-memory from newest to oldest
+        const orderedMessages = [];
         let hitCompactionBoundary = false;
-        // Traverse from newest to oldest
         let currentMessageId = session.newestMessageId;
         while (currentMessageId) {
-            // eslint-disable-next-line no-await-in-loop
-            const storedMsg = await this.keyStorage.get(this.messageKey(sessionId, currentMessageId));
+            const storedMsg = messageMap.get(currentMessageId);
             if (!storedMsg)
                 break;
-            // Load parts for this message
-            // eslint-disable-next-line no-await-in-loop
-            const parts = await this.loadParts(storedMsg);
-            const messageWithParts = { ...storedMsg, parts };
             // Check for compaction boundary
             if (stopAtCompaction && storedMsg.compactionBoundary) {
-                // Include the compaction boundary message itself
-                messages.unshift(messageWithParts);
+                orderedMessages.unshift(storedMsg);
                 hitCompactionBoundary = true;
                 break;
             }
-            messages.unshift(messageWithParts);
+            orderedMessages.unshift(storedMsg);
             currentMessageId = storedMsg.prevMessageId;
         }
+        // Bulk-load parts per message (one query per message instead of one per part)
+        const messages = [];
+        for (const msg of orderedMessages) {
+            if (msg.partIds.length === 0) {
+                messages.push({ ...msg, parts: [] });
+                continue;
+            }
+            // One query for all parts of this message
+            // eslint-disable-next-line no-await-in-loop
+            const partEntries = await this.keyStorage.listWithValues(this.partPrefix(msg.id));
+            const partMap = new Map();
+            for (const entry of partEntries) {
+                partMap.set(entry.value.id, entry.value);
+            }
+            // Maintain order from partIds
+            const parts = [];
+            for (const partId of msg.partIds) {
+                const part = partMap.get(partId);
+                if (part) {
+                    parts.push(part);
+                }
+            }
+            messages.push({ ...msg, parts });
+        }
         return { hitCompactionBoundary, messages };
     }
     /**
@@ -371,12 +395,100 @@ export class MessageStorageService {
      * More efficient than calling saveMessage multiple times.
      */
     async saveMessages(sessionId, messages) {
+        if (messages.length === 0)
+            return [];
+        // For single messages, delegate to saveMessage (avoids double-read overhead)
+        if (messages.length === 1) {
+            return [await this.saveMessage(sessionId, messages[0])];
+        }
+        const now = Date.now();
+        const ops = [];
         const results = [];
+        // Get or create session (1 read)
+        let session = await this.getSession(sessionId);
+        if (!session) {
+            session = {
+                createdAt: now,
+                messageCount: 0,
+                sessionId,
+                updatedAt: now,
+            };
+        }
+        // Read previous newest message to update its nextMessageId (1 read)
+        const originalPrevId = session.newestMessageId;
+        if (originalPrevId) {
+            const prevMsg = await this.keyStorage.get(this.messageKey(sessionId, originalPrevId));
+            if (prevMsg) {
+                ops.push({
+                    key: this.messageKey(sessionId, originalPrevId),
+                    type: 'set',
+                    value: { ...prevMsg, nextMessageId: undefined, updatedAt: now },
+                });
+            }
+        }
+        // Build all stored messages and parts in memory
+        let prevId = originalPrevId;
         for (const message of messages) {
-            // eslint-disable-next-line no-await-in-loop
-            const stored = await this.saveMessage(sessionId, message);
-            results.push(stored);
+            const messageId = randomUUID();
+            const { content, parts } = this.extractParts(message, messageId, now);
+            const storedMessage = {
+                content,
+                createdAt: now,
+                id: messageId,
+                name: message.name,
+                partIds: parts.map((p) => p.id),
+                prevMessageId: prevId,
+                reasoning: message.reasoning,
+                role: message.role,
+                sessionId,
+                thought: message.thought,
+                thoughtSummary: message.thoughtSummary,
+                toolCallId: message.toolCallId,
+                toolCalls: message.toolCalls,
+                updatedAt: now,
+            };
+            // Add part ops
+            for (const part of parts) {
+                ops.push({
+                    key: this.partKey(messageId, part.id),
+                    type: 'set',
+                    value: part,
+                });
+            }
+            results.push(storedMessage);
+            prevId = messageId;
+        }
+        // Chain messages: set nextMessageId pointers between consecutive messages
+        for (let i = 0; i < results.length - 1; i++) {
+            results[i].nextMessageId = results[i + 1].id;
+        }
+        // Patch the previous newest message to point to the first new message
+        if (originalPrevId && ops.length > 0 && ops[0].type === 'set') {
+            ;
+            ops[0].value.nextMessageId = results[0].id;
+        }
+        // Add all message ops
+        for (const storedMessage of results) {
+            ops.push({
+                key: this.messageKey(sessionId, storedMessage.id),
+                type: 'set',
+                value: storedMessage,
+            });
+        }
+        // Update session record
+        session.newestMessageId = results.at(-1).id;
+        if (!session.oldestMessageId) {
+            session.oldestMessageId = results[0].id;
         }
+        session.messageCount += messages.length;
+        session.updatedAt = now;
+        ops.push({
+            key: this.sessionKey(sessionId),
+            type: 'set',
+            value: session,
+        });
+        // Execute all ops atomically (1 batch)
+        await this.keyStorage.batch(ops);
         return results;
     }
     /**

package/dist/agent/infra/system-prompt/contributors/context-tree-structure-contributor.d.ts

@@ -63,5 +63,9 @@ export declare class ContextTreeStructureContributor implements SystemPromptCont
      * @returns Instructions for using search_knowledge tool
      */
     private buildSearchKnowledgeInstructions;
+    /**
+     * Count .stub.md files inside an _archived/ directory (recursive).
+     */
+    private countArchivedEntries;
     private traverseContextTree;
 }

package/dist/agent/infra/system-prompt/contributors/context-tree-structure-contributor.js

@@ -92,7 +92,7 @@ export class ContextTreeStructureContributor {
         if (truncatedCount.value > 0) {
             parts.push('', `[${truncatedCount.value} additional entries not shown]`);
         }
-        parts.push('', '## Structure Guide', '- Each top-level folder is a **domain** (dynamically created based on content)', '- Inside domains are **topics** as `.md` files or subfolders with `context.md`', '- `context.md` files contain the curated knowledge content', '', '## Dynamic Domains', '- Domains are created dynamically based on the semantics of curated content', '- Domain names should be descriptive, use snake_case (e.g., `authentication`, `api_design`)', '- Before creating a new domain, check if existing domains could accommodate the content', '', '## Usage', '- **Query commands**: Search ONLY within this context tree structure', '- **Curate commands**: Check existing domains/topics before creating new ones', '</context-tree-structure>');
+        parts.push('', '## Structure Guide', '- Each top-level folder is a **domain** (dynamically created based on content)', '- Inside domains are **topics** as `.md` files or subfolders with `context.md`', '- `context.md` files contain the curated knowledge content', '- `_index.md` files are auto-generated summaries at each directory level', '- `_archived/` contains archived low-importance entries (use `expand_knowledge` to drill into them)', '', '## Dynamic Domains', '- Domains are created dynamically based on the semantics of curated content', '- Domain names should be descriptive, use snake_case (e.g., `architecture`, `market_trends`, `risk_analysis`)', '- Before creating a new domain, check if existing domains could accommodate the content', '', '## Usage', '- **Query commands**: Search ONLY within this context tree structure', '- **Curate commands**: Check existing domains/topics before creating new ones', '</context-tree-structure>');
         return parts.join('\n');
     }
     /**
@@ -106,8 +106,8 @@ export class ContextTreeStructureContributor {
             'The context tree at `.brv/context-tree/` exists but contains no curated content yet.',
             '',
             '**For curate commands**: Create new domains and topics dynamically based on content.',
-            '- Choose semantically meaningful domain names (e.g., `authentication`, `api_design`, `data_models`)',
-            '- Use snake_case format for domain names',
+            '- Choose semantically meaningful domain names that represent broad knowledge categories',
+            '- Use snake_case format for domain names (e.g., `data_models`, `trading_strategies`, `personal_notes`)',
             '**For query commands**: No context is available to search.',
             '</context-tree-structure>',
         ].join('\n');
@@ -168,6 +168,18 @@ export class ContextTreeStructureContributor {
             '</context-tree-structure>',
         ].join('\n');
     }
+    /**
+     * Count .stub.md files inside an _archived/ directory (recursive).
+     */
+    async countArchivedEntries(archivedDir) {
+        try {
+            const entries = await fs.readdir(archivedDir, { recursive: true });
+            return entries.filter((e) => String(e).endsWith('.stub.md')).length;
+        }
+        catch {
+            return 0;
+        }
+    }
     async traverseContextTree(options) {
         const { currentDepth, dir, entriesCount, lines, maxDepth, maxEntries, relativePath, truncatedCount } = options;
         if (currentDepth >= maxDepth) {
@@ -198,21 +210,37 @@ export class ContextTreeStructureContributor {
             entriesCount.value++;
             const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
             if (entry.isDirectory()) {
-                lines.push(`${indent}${entry.name}/`);
-                // eslint-disable-next-line no-await-in-loop -- Sequential traversal required for ordered output
-                await this.traverseContextTree({
-                    currentDepth: currentDepth + 1,
-                    dir: path.join(dir, entry.name),
-                    entriesCount,
-                    lines,
-                    maxDepth,
-                    maxEntries,
-                    relativePath: entryRelativePath,
-                    truncatedCount,
-                });
+                // For _archived/ directories, show entry count instead of recursing
+                if (entry.name === '_archived') {
+                    // eslint-disable-next-line no-await-in-loop -- Sequential traversal required for ordered output
+                    const archivedCount = await this.countArchivedEntries(path.join(dir, entry.name));
+                    if (archivedCount > 0) {
+                        lines.push(`${indent}_archived/ (${archivedCount} archived entries)`);
+                    }
+                }
+                else {
+                    lines.push(`${indent}${entry.name}/`);
+                    // eslint-disable-next-line no-await-in-loop -- Sequential traversal required for ordered output
+                    await this.traverseContextTree({
+                        currentDepth: currentDepth + 1,
+                        dir: path.join(dir, entry.name),
+                        entriesCount,
+                        lines,
+                        maxDepth,
+                        maxEntries,
+                        relativePath: entryRelativePath,
+                        truncatedCount,
+                    });
+                }
             }
             else {
-                const annotation = entry.name === 'context.md' ? ' (knowledge content)' : '';
+                let annotation = '';
+                if (entry.name === 'context.md') {
+                    annotation = ' (knowledge content)';
+                }
+                else if (entry.name === '_index.md') {
+                    annotation = ' (summary)';
+                }
                 lines.push(`${indent}${entry.name}${annotation}`);
             }
         }

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

@@ -24,6 +24,14 @@ const CodeExecInputSchema = z
         .enum(['javascript', 'typescript'])
         .optional()
         .describe('Language: "javascript" or "typescript" (default: auto-detect)'),
+    /**
+     * If true, stdout is suppressed from the result (stderr still returned).
+     * Use for variable assignments or mutations where output is not needed.
+     */
+    silent: z
+        .boolean()
+        .optional()
+        .describe('If true, stdout is suppressed from the result. Use for variable assignments where output is not needed.'),
     /**
      * Timeout in milliseconds (max: 300000, default: 30000 = 30 seconds).
      */
@@ -54,7 +62,7 @@ export function createCodeExecTool(sandboxService) {
     return {
         description: 'Execute JavaScript or TypeScript code in a sandboxed REPL environment.',
         async execute(input, context) {
-            const { code, context: contextPayload, language, timeout } = input;
+            const { code, context: contextPayload, language, silent, timeout } = input;
             // Get sessionId from execution context (automatic - no user input needed)
             const sessionId = context?.sessionId ?? 'default';
             // Stream initial status via metadata callback if available
@@ -65,11 +73,43 @@ export function createCodeExecTool(sandboxService) {
                     progress: 0,
                 });
             }
+            // Cap stdout per command type to prevent context overflow
+            // curate: 5K (heavy processing, context in variables), query: 8K (results in variables)
+            const maxStdoutChars = context?.commandType === 'curate' ? 5000
+                : context?.commandType === 'query' ? 8000
+                    : undefined;
             const result = await sandboxService.executeCode(code, sessionId, {
+                commandType: context?.commandType,
                 contextPayload,
                 language,
+                maxStdoutChars,
                 timeout,
             });
+            // Auto-redirect large outputs to sandbox variable for RLM commands.
+            // This prevents large tool results from bloating conversation history.
+            const AUTO_REDIRECT_THRESHOLD = 2000;
+            if (!silent
+                && result.stdout.length > AUTO_REDIRECT_THRESHOLD
+                && (context?.commandType === 'curate' || context?.commandType === 'query')) {
+                const overflowVar = `__stdout_${Date.now()}`;
+                sandboxService.setSandboxVariable(sessionId, overflowVar, result.stdout);
+                // Stream completion via metadata callback if available
+                if (context?.metadata) {
+                    context.metadata({
+                        description: result.stderr ? 'Execution completed with errors' : 'Execution completed (output stored in variable)',
+                        output: `[Output stored in ${overflowVar}]` + (result.stderr ? `\n[stderr]\n${result.stderr}` : ''),
+                        progress: 100,
+                    });
+                }
+                return {
+                    executionTime: result.executionTime,
+                    finalResult: result.finalResult,
+                    locals: result.locals,
+                    returnValue: result.returnValue,
+                    stderr: result.stderr,
+                    stdout: `[Output (${result.stdout.length} chars) stored in variable: ${overflowVar}. Access via code_exec.]`,
+                };
+            }
             // Stream completion via metadata callback if available
             if (context?.metadata) {
                 context.metadata({
@@ -79,11 +119,13 @@ export function createCodeExecTool(sandboxService) {
                 });
             }
             return {
+                ...(result.curateResults ? { curateResults: result.curateResults } : {}),
                 executionTime: result.executionTime,
+                finalResult: result.finalResult,
                 locals: result.locals,
                 returnValue: result.returnValue,
                 stderr: result.stderr,
-                stdout: result.stdout,
+                stdout: silent ? '' : result.stdout,
             };
         },
         id: ToolName.CODE_EXEC,