byterover-cli 1.7.2 → 2.0.0

package/dist/agent/infra/llm/tool-output-processor.js

@@ -21,21 +21,53 @@ export const DEFAULT_TRUNCATION_CONFIG = {
     tailLines: 250,
     threshold: 50_000,
 };
+/**
+ * Percentages used to derive per-command truncation thresholds from the model's context window.
+ * Expressed as a fraction of maxInputTokens. Multiply by charsPerToken (default 4) for char threshold.
+ * Calibrated so values equal the original hardcoded limits on a 200K-token context model:
+ *   default  = 6.25%  → 50,000 chars at 200K  (50K chars / (200K tokens × 4 chars/token) = 6.25%)
+ *   curate   = 1.25%  → 10,000 chars at 200K
+ *   query    = 2.50%  → 20,000 chars at 200K
+ */
+const THRESHOLD_PERCENT_DEFAULT = 0.0625;
+const THRESHOLD_PERCENT_CURATE = 0.0125;
+const THRESHOLD_PERCENT_QUERY = 0.025;
+const DEFAULT_CHARS_PER_TOKEN = 4;
 /**
  * Tool output processor with truncation and file saving capabilities
  */
 export class ToolOutputProcessor {
+    /** Fallback per-command overrides when no maxInputTokens is provided */
+    static DEFAULT_COMMAND_OVERRIDES = {
+        curate: { headLines: 50, tailLines: 20, threshold: 10_000 },
+        query: { headLines: 100, tailLines: 50, threshold: 20_000 },
+    };
+    commandOverrides;
     config;
     /**
      * Create a new tool output processor
      *
-     * @param config - Truncation configuration
+     * @param maxInputTokens - Model context window size. When provided, truncation thresholds
+     *   are derived as a percentage of the context window so they scale across model sizes.
+     * @param config - Optional explicit overrides (take priority over computed defaults)
      */
-    constructor(config) {
-        this.config = {
-            ...DEFAULT_TRUNCATION_CONFIG,
-            ...config,
-        };
+    constructor(maxInputTokens, config) {
+        if (maxInputTokens) {
+            const baseThreshold = Math.floor(maxInputTokens * THRESHOLD_PERCENT_DEFAULT * DEFAULT_CHARS_PER_TOKEN);
+            this.config = {
+                ...DEFAULT_TRUNCATION_CONFIG,
+                threshold: baseThreshold,
+                ...config,
+            };
+            this.commandOverrides = {
+                curate: { headLines: 50, tailLines: 20, threshold: Math.floor(maxInputTokens * THRESHOLD_PERCENT_CURATE * DEFAULT_CHARS_PER_TOKEN) },
+                query: { headLines: 100, tailLines: 50, threshold: Math.floor(maxInputTokens * THRESHOLD_PERCENT_QUERY * DEFAULT_CHARS_PER_TOKEN) },
+            };
+        }
+        else {
+            this.config = { ...DEFAULT_TRUNCATION_CONFIG, ...config };
+            this.commandOverrides = { ...ToolOutputProcessor.DEFAULT_COMMAND_OVERRIDES };
+        }
     }
     // ==================== PUBLIC METHODS ====================
     /**
@@ -48,14 +80,16 @@ export class ToolOutputProcessor {
      *
      * @param toolName - Name of the tool that produced the output
      * @param output - Raw tool output (any type, will be stringified)
+     * @param commandType - Optional command type for per-command truncation overrides
      * @returns Processed output with metadata
      */
-    async processOutput(toolName, output) {
+    async processOutput(toolName, output, commandType) {
+        const config = this.resolveConfig(commandType);
         // Convert output to string
         const contentString = this.stringify(output);
         const originalLength = contentString.length;
         // Check if truncation is needed
-        if (!this.config.enabled || originalLength <= this.config.threshold) {
+        if (!config.enabled || originalLength <= config.threshold) {
             return {
                 content: contentString,
             };
@@ -63,7 +97,7 @@ export class ToolOutputProcessor {
         // Save full output to temp file
         const savedFilePath = await this.saveToTempFile(toolName, contentString);
         // Truncate content
-        const truncatedContent = this.truncateContent(contentString);
+        const truncatedContent = this.truncateContent(contentString, config);
         return {
             content: truncatedContent,
             metadata: {
@@ -83,16 +117,17 @@ export class ToolOutputProcessor {
      *
      * @param toolName - Name of the tool that produced the output
      * @param output - Raw tool output (structured or plain)
+     * @param commandType - Optional command type for per-command truncation overrides
      * @returns Processed output with attachments and title
      */
-    async processStructuredOutput(toolName, output) {
+    async processStructuredOutput(toolName, output, commandType) {
         // Try to detect structured output
         if (this.isStructuredOutput(output)) {
             const structured = output;
             const attachments = this.extractAttachments(structured);
             const textContent = this.extractTextContent(structured);
             // Process the text content with truncation
-            const processed = await this.processOutput(toolName, textContent);
+            const processed = await this.processOutput(toolName, textContent, commandType);
             return {
                 ...processed,
                 attachments: attachments.length > 0 ? attachments : undefined,
@@ -105,14 +140,14 @@ export class ToolOutputProcessor {
             const attachments = this.extractMcpAttachments(contentArray);
             const textContent = this.extractMcpTextContent(contentArray);
             // Process the text content with truncation
-            const processed = await this.processOutput(toolName, textContent);
+            const processed = await this.processOutput(toolName, textContent, commandType);
             return {
                 ...processed,
                 attachments: attachments.length > 0 ? attachments : undefined,
             };
         }
         // Fall back to regular processing
-        return this.processOutput(toolName, output);
+        return this.processOutput(toolName, output, commandType);
     }
     // ==================== PRIVATE METHODS (alphabetical order) ====================
     /**
@@ -264,6 +299,15 @@ export class ToolOutputProcessor {
         // Must have at least one of: content, attachments, or title
         return 'content' in obj || 'attachments' in obj || 'title' in obj;
     }
+    /**
+     * Resolve effective truncation config, applying per-command overrides if applicable.
+     */
+    resolveConfig(commandType) {
+        if (commandType && commandType in this.commandOverrides) {
+            return { ...this.config, ...this.commandOverrides[commandType] };
+        }
+        return this.config;
+    }
     /**
      * Save content to a temporary file
      *
@@ -342,14 +386,15 @@ export class ToolOutputProcessor {
      * [Last N lines]
      *
      * @param content - Content to truncate
+     * @param config - Truncation config to use (may include per-command overrides)
      * @returns Truncated content
      */
-    truncateContent(content) {
+    truncateContent(content, config = this.config) {
         const lines = content.split('\n');
         const totalLines = lines.length;
         // Calculate how many lines to keep
-        const headLines = Math.min(this.config.headLines, totalLines);
-        const tailLines = Math.min(this.config.tailLines, totalLines);
+        const headLines = Math.min(config.headLines, totalLines);
+        const tailLines = Math.min(config.tailLines, totalLines);
         // If content is small enough to fit, return as-is
         if (headLines + tailLines >= totalLines) {
             return content;

package/dist/agent/infra/sandbox/curate-result-collector.d.ts

@@ -0,0 +1,30 @@
+import type { CurateOperation, CurateOptions, CurateResult, DetectDomainsInput, DetectDomainsResult, ICurateService } from '../../core/interfaces/i-curate-service.js';
+/**
+ * Decorator that wraps ICurateService to transparently collect curate() results
+ * per executeCode() call, even when multiple calls run concurrently.
+ *
+ * Uses AsyncLocalStorage so concurrent executeCode() calls each get their own
+ * isolated bucket — curate() calls within a sandbox execution automatically
+ * propagate through the async context chain to the correct bucket.
+ *
+ * Requirement: LocalSandbox must execute in-process (same Node.js thread).
+ * AsyncLocalStorage does NOT propagate across worker thread or child process
+ * boundaries — if the sandbox ever moves off-thread, this silently stops working.
+ *
+ * Usage: const {result, curateResults} = await collector.collect(() => sandbox.execute(...))
+ */
+export declare class CurateResultCollector implements ICurateService {
+    private readonly inner;
+    private readonly storage;
+    constructor(inner: ICurateService);
+    /**
+     * Run fn in an isolated async context and collect all curate() results
+     * triggered within that context. Concurrent collect() calls are fully isolated.
+     */
+    collect<T>(fn: () => Promise<T>): Promise<{
+        curateResults: unknown[];
+        result: T;
+    }>;
+    curate(operations: CurateOperation[], options?: CurateOptions): Promise<CurateResult>;
+    detectDomains(domains: DetectDomainsInput[]): Promise<DetectDomainsResult>;
+}

package/dist/agent/infra/sandbox/curate-result-collector.js

@@ -0,0 +1,39 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Decorator that wraps ICurateService to transparently collect curate() results
+ * per executeCode() call, even when multiple calls run concurrently.
+ *
+ * Uses AsyncLocalStorage so concurrent executeCode() calls each get their own
+ * isolated bucket — curate() calls within a sandbox execution automatically
+ * propagate through the async context chain to the correct bucket.
+ *
+ * Requirement: LocalSandbox must execute in-process (same Node.js thread).
+ * AsyncLocalStorage does NOT propagate across worker thread or child process
+ * boundaries — if the sandbox ever moves off-thread, this silently stops working.
+ *
+ * Usage: const {result, curateResults} = await collector.collect(() => sandbox.execute(...))
+ */
+export class CurateResultCollector {
+    inner;
+    storage = new AsyncLocalStorage();
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /**
+     * Run fn in an isolated async context and collect all curate() results
+     * triggered within that context. Concurrent collect() calls are fully isolated.
+     */
+    async collect(fn) {
+        const bucket = [];
+        const result = await this.storage.run(bucket, fn);
+        return { curateResults: bucket, result };
+    }
+    async curate(operations, options) {
+        const result = await this.inner.curate(operations, options);
+        this.storage.getStore()?.push(result);
+        return result;
+    }
+    detectDomains(domains) {
+        return this.inner.detectDomains(domains);
+    }
+}

package/dist/agent/infra/sandbox/curate-service.d.ts

@@ -8,6 +8,8 @@ import type { CurateOperation, CurateOptions, CurateResult, DetectDomainsInput,
  * Provides curate and domain detection operations for the sandbox.
  */
 export declare class CurateService implements ICurateService {
+    private readonly workingDirectory;
+    constructor(workingDirectory?: string);
     /**
      * Execute curate operations on knowledge topics.
      *
@@ -28,6 +30,7 @@ export declare class CurateService implements ICurateService {
 /**
  * Creates a curate service instance.
  *
+ * @param workingDirectory - Working directory for resolving relative paths
  * @returns CurateService instance
  */
-export declare function createCurateService(): ICurateService;
+export declare function createCurateService(workingDirectory?: string): ICurateService;

package/dist/agent/infra/sandbox/curate-service.js

@@ -2,6 +2,7 @@
  * Curate service implementation for sandbox integration.
  * Wraps the curate-tool logic for use in the sandbox's tools.* SDK.
  */
+import { resolve } from 'node:path';
 import { executeCurate } from '../tools/implementations/curate-tool.js';
 /**
  * Default base path for knowledge storage.
@@ -71,6 +72,10 @@ function validateOperations(operations) {
  * Provides curate and domain detection operations for the sandbox.
  */
 export class CurateService {
+    workingDirectory;
+    constructor(workingDirectory) {
+        this.workingDirectory = workingDirectory ?? process.cwd();
+    }
     /**
      * Execute curate operations on knowledge topics.
      *
@@ -79,7 +84,10 @@ export class CurateService {
      * @returns Curate result with applied operations and summary
      */
     async curate(operations, options) {
-        const basePath = options?.basePath ?? DEFAULT_BASE_PATH;
+        const rawBasePath = options?.basePath ?? DEFAULT_BASE_PATH;
+        // Resolve relative basePath against the working directory to ensure
+        // files are written to the correct project directory, not process.cwd()
+        const basePath = resolve(this.workingDirectory, rawBasePath);
         // Pre-validate operations to catch common mistakes early
         const validationFailures = validateOperations(operations);
         if (validationFailures.length > 0) {
@@ -135,8 +143,9 @@ export class CurateService {
 /**
  * Creates a curate service instance.
  *
+ * @param workingDirectory - Working directory for resolving relative paths
  * @returns CurateService instance
  */
-export function createCurateService() {
-    return new CurateService();
+export function createCurateService(workingDirectory) {
+    return new CurateService(workingDirectory);
 }

package/dist/agent/infra/sandbox/local-sandbox.d.ts

@@ -19,7 +19,15 @@ export interface LocalSandboxOptions {
 export declare class LocalSandbox {
     private context;
     private errorBuffer;
+    /** Value set by setFinalResult() — signals early exit */
+    private finalResult?;
     private outputBuffer;
+    /** Current stdout cap in chars (undefined = unlimited) */
+    private stdoutCap?;
+    /** Running count of chars written to outputBuffer in current execution */
+    private stdoutCharsWritten;
+    /** Whether stdout has been truncated in current execution */
+    private stdoutTruncated;
     constructor(options?: LocalSandboxOptions);
     /**
      * Execute code in the sandbox.
@@ -42,4 +50,9 @@ export declare class LocalSandbox {
      * @param updates - Key-value pairs to add to context
      */
     updateContext(updates: Record<string, unknown>): void;
+    /**
+     * Push a line to stdout, respecting the optional character cap.
+     * When the cap is reached, appends a truncation notice and drops further output.
+     */
+    private pushStdout;
 }

package/dist/agent/infra/sandbox/local-sandbox.js

@@ -84,15 +84,23 @@ function loadAllowedPackages() {
 export class LocalSandbox {
     context;
     errorBuffer = [];
+    /** Value set by setFinalResult() — signals early exit */
+    finalResult;
     outputBuffer = [];
+    /** Current stdout cap in chars (undefined = unlimited) */
+    stdoutCap;
+    /** Running count of chars written to outputBuffer in current execution */
+    stdoutCharsWritten = 0;
+    /** Whether stdout has been truncated in current execution */
+    stdoutTruncated = false;
     constructor(options = {}) {
         const { environmentContext, initialContext = {}, toolsSDK } = options;
-        // Create safe console that captures output
+        // Create safe console that captures output (stdout methods respect cap)
         const safeConsole = {
-            debug: (...args) => this.outputBuffer.push(args.map(String).join(' ')),
+            debug: (...args) => this.pushStdout(args.map(String).join(' ')),
             error: (...args) => this.errorBuffer.push(args.map(String).join(' ')),
-            info: (...args) => this.outputBuffer.push(args.map(String).join(' ')),
-            log: (...args) => this.outputBuffer.push(args.map(String).join(' ')),
+            info: (...args) => this.pushStdout(args.map(String).join(' ')),
+            log: (...args) => this.pushStdout(args.map(String).join(' ')),
             warn: (...args) => this.errorBuffer.push(args.map(String).join(' ')),
         };
         // Load whitelisted packages
@@ -104,6 +112,10 @@ export class LocalSandbox {
             ...packages, // Also spread at top level for convenience: `lodash`, `dateFns`, etc.
             ...initialContext,
         };
+        // Inject setFinalResult for early exit from agentic loop
+        sandbox.setFinalResult = (result) => {
+            this.finalResult = typeof result === 'string' ? result : JSON.stringify(result);
+        };
         // Inject Tools SDK if provided (for file system operations)
         if (toolsSDK) {
             sandbox.tools = toolsSDK;
@@ -139,6 +151,10 @@ export class LocalSandbox {
     async execute(code, config) {
         this.outputBuffer = [];
         this.errorBuffer = [];
+        this.finalResult = undefined;
+        this.stdoutCap = config?.maxStdoutChars;
+        this.stdoutCharsWritten = 0;
+        this.stdoutTruncated = false;
         const timeout = config?.timeout ?? DEFAULT_SANDBOX_TIMEOUT;
         const startTime = performance.now();
         let returnValue;
@@ -202,6 +218,7 @@ export class LocalSandbox {
         }
         return {
             executionTime,
+            finalResult: this.finalResult,
             locals,
             returnValue,
             stderr: this.errorBuffer.join('\n'),
@@ -226,4 +243,24 @@ export class LocalSandbox {
             this.context[key] = value;
         }
     }
+    /**
+     * Push a line to stdout, respecting the optional character cap.
+     * When the cap is reached, appends a truncation notice and drops further output.
+     */
+    pushStdout(line) {
+        if (this.stdoutTruncated) {
+            return;
+        }
+        if (this.stdoutCap !== undefined && this.stdoutCharsWritten + line.length > this.stdoutCap) {
+            const remaining = this.stdoutCap - this.stdoutCharsWritten;
+            if (remaining > 0) {
+                this.outputBuffer.push(line.slice(0, remaining));
+            }
+            this.outputBuffer.push(`\n... [stdout truncated at ${this.stdoutCap} chars]`);
+            this.stdoutTruncated = true;
+            return;
+        }
+        this.stdoutCharsWritten += line.length + 1; // +1 for join newline
+        this.outputBuffer.push(line);
+    }
 }

package/dist/agent/infra/sandbox/sandbox-service.d.ts

@@ -3,24 +3,29 @@ import type { REPLResult, SandboxConfig } from '../../core/domain/sandbox/types.
 import type { ICurateService } from '../../core/interfaces/i-curate-service.js';
 import type { IFileSystem } from '../../core/interfaces/i-file-system.js';
 import type { ISandboxService } from '../../core/interfaces/i-sandbox-service.js';
+import type { SessionManager } from '../session/session-manager.js';
 import type { ISearchKnowledgeService } from './tools-sdk.js';
 /**
  * Sandbox service implementation.
  * Manages sandbox instances tied to agent sessions.
  */
 export declare class SandboxService implements ISandboxService {
+    /** Collector wrapping curateService — captures curate() results per executeCode() call */
+    private collector?;
     /** Curate service for Tools SDK */
     private curateService?;
     /** Environment context for sandbox injection */
     private environmentContext?;
     /** File system service for Tools SDK */
     private fileSystem?;
+    /** Variables buffered before sandbox creation, keyed by sessionId */
+    private pendingVariables;
     /** Map of agent sessionId to LocalSandbox instance */
     private sandboxes;
     /** Search knowledge service for Tools SDK */
     private searchKnowledgeService?;
-    /** Cached Tools SDK instance (created when fileSystem is set) */
-    private toolsSDK?;
+    /** Session manager for sub-agent delegation via tools.agentQuery() */
+    private sessionManager?;
     /**
      * Clean up all resources (called on agent shutdown).
      */
@@ -31,6 +36,14 @@ export declare class SandboxService implements ISandboxService {
      * @param sessionId - Session identifier
      */
     clearSession(sessionId: string): Promise<void>;
+    /**
+     * Delete a variable from a session's sandbox.
+     * If the sandbox doesn't exist yet, cleans up any pending variable with that key.
+     *
+     * @param sessionId - Session identifier
+     * @param key - Variable name to delete
+     */
+    deleteSandboxVariable(sessionId: string, key: string): void;
     /**
      * Execute JavaScript/TypeScript code in a sandbox.
      *
@@ -61,6 +74,16 @@ export declare class SandboxService implements ISandboxService {
      * @param fileSystem - File system service instance
      */
     setFileSystem(fileSystem: IFileSystem): void;
+    /**
+     * Set a variable in a session's sandbox.
+     * If the sandbox doesn't exist yet, the variable is buffered and injected
+     * when the sandbox is created on the first executeCode() call.
+     *
+     * @param sessionId - Session identifier
+     * @param key - Variable name
+     * @param value - Variable value
+     */
+    setSandboxVariable(sessionId: string, key: string, value: unknown): void;
     /**
      * Set the search knowledge service for Tools SDK injection.
      * When set, new sandboxes will have access to knowledge search via `tools.searchKnowledge()`.
@@ -69,8 +92,20 @@ export declare class SandboxService implements ISandboxService {
      */
     setSearchKnowledgeService(searchKnowledgeService: ISearchKnowledgeService): void;
     /**
-     * Rebuild the Tools SDK instance when services change.
-     * Clears existing sandboxes so new ones get the updated SDK.
+     * Set the session manager for sub-agent delegation.
+     * When set, new sandboxes will have access to `tools.agentQuery()`.
+     *
+     * @param sessionManager - Session manager instance
+     */
+    setSessionManager(sessionManager: SessionManager): void;
+    /**
+     * Build a Tools SDK instance for a specific session.
+     * Includes `agentQuery` bound to the session's ID for sub-agent delegation.
+     */
+    private buildToolsSDK;
+    /**
+     * Clear existing sandboxes so new ones get updated services.
+     * Called when file system, curate, or search services change.
      */
-    private rebuildToolsSDK;
+    private invalidateSandboxes;
 }

package/dist/agent/infra/sandbox/sandbox-service.js

@@ -1,3 +1,4 @@
+import { CurateResultCollector } from './curate-result-collector.js';
 import { LocalSandbox } from './local-sandbox.js';
 import { createToolsSDK } from './tools-sdk.js';
 /**
@@ -5,23 +6,28 @@ import { createToolsSDK } from './tools-sdk.js';
  * Manages sandbox instances tied to agent sessions.
  */
 export class SandboxService {
+    /** Collector wrapping curateService — captures curate() results per executeCode() call */
+    collector;
     /** Curate service for Tools SDK */
     curateService;
     /** Environment context for sandbox injection */
     environmentContext;
     /** File system service for Tools SDK */
     fileSystem;
+    /** Variables buffered before sandbox creation, keyed by sessionId */
+    pendingVariables = new Map();
     /** Map of agent sessionId to LocalSandbox instance */
     sandboxes = new Map();
     /** Search knowledge service for Tools SDK */
     searchKnowledgeService;
-    /** Cached Tools SDK instance (created when fileSystem is set) */
-    toolsSDK;
+    /** Session manager for sub-agent delegation via tools.agentQuery() */
+    sessionManager;
     /**
      * Clean up all resources (called on agent shutdown).
      */
     async cleanup() {
         this.sandboxes.clear();
+        this.pendingVariables.clear();
     }
     /**
      * Clear sandbox state for a session.
@@ -30,6 +36,24 @@ export class SandboxService {
      */
     async clearSession(sessionId) {
         this.sandboxes.delete(sessionId);
+        this.pendingVariables.delete(sessionId);
+    }
+    /**
+     * Delete a variable from a session's sandbox.
+     * If the sandbox doesn't exist yet, cleans up any pending variable with that key.
+     *
+     * @param sessionId - Session identifier
+     * @param key - Variable name to delete
+     */
+    deleteSandboxVariable(sessionId, key) {
+        const sandbox = this.sandboxes.get(sessionId);
+        if (sandbox) {
+            sandbox.updateContext({ [key]: undefined });
+        }
+        const pending = this.pendingVariables.get(sessionId);
+        if (pending) {
+            delete pending[key];
+        }
     }
     /**
      * Execute JavaScript/TypeScript code in a sandbox.
@@ -48,10 +72,18 @@ export class SandboxService {
             if (config?.contextPayload) {
                 initialContext.context = config.contextPayload;
             }
+            // Inject any pending variables set before sandbox creation
+            const pending = this.pendingVariables.get(sessionId);
+            if (pending) {
+                Object.assign(initialContext, pending);
+                this.pendingVariables.delete(sessionId);
+            }
+            // Build per-session ToolsSDK (includes agentQuery bound to this sessionId)
+            const sessionToolsSDK = this.buildToolsSDK(sessionId);
             sandbox = new LocalSandbox({
                 environmentContext: this.environmentContext,
                 initialContext,
-                toolsSDK: this.toolsSDK,
+                toolsSDK: sessionToolsSDK,
             });
             this.sandboxes.set(sessionId, sandbox);
         }
@@ -59,6 +91,10 @@ export class SandboxService {
             // Update context if provided
             sandbox.updateContext({ context: config.contextPayload });
         }
+        if (this.collector) {
+            const { curateResults, result } = await this.collector.collect(() => sandbox.execute(code, config));
+            return curateResults.length > 0 ? { ...result, curateResults } : result;
+        }
         return sandbox.execute(code, config);
     }
     /**
@@ -68,8 +104,9 @@ export class SandboxService {
      * @param curateService - Curate service instance
      */
     setCurateService(curateService) {
-        this.curateService = curateService;
-        this.rebuildToolsSDK();
+        this.collector = new CurateResultCollector(curateService);
+        this.curateService = this.collector;
+        this.invalidateSandboxes();
     }
     /**
      * Set the environment context for sandbox injection.
@@ -90,7 +127,31 @@ export class SandboxService {
      */
     setFileSystem(fileSystem) {
         this.fileSystem = fileSystem;
-        this.rebuildToolsSDK();
+        this.invalidateSandboxes();
+    }
+    /**
+     * Set a variable in a session's sandbox.
+     * If the sandbox doesn't exist yet, the variable is buffered and injected
+     * when the sandbox is created on the first executeCode() call.
+     *
+     * @param sessionId - Session identifier
+     * @param key - Variable name
+     * @param value - Variable value
+     */
+    setSandboxVariable(sessionId, key, value) {
+        const sandbox = this.sandboxes.get(sessionId);
+        if (sandbox) {
+            sandbox.updateContext({ [key]: value });
+        }
+        else {
+            // Buffer — will be injected when sandbox is created in executeCode()
+            let pending = this.pendingVariables.get(sessionId);
+            if (!pending) {
+                pending = {};
+                this.pendingVariables.set(sessionId, pending);
+            }
+            pending[key] = value;
+        }
     }
     /**
      * Set the search knowledge service for Tools SDK injection.
@@ -100,18 +161,40 @@ export class SandboxService {
      */
     setSearchKnowledgeService(searchKnowledgeService) {
         this.searchKnowledgeService = searchKnowledgeService;
-        this.rebuildToolsSDK();
+        this.invalidateSandboxes();
+    }
+    /**
+     * Set the session manager for sub-agent delegation.
+     * When set, new sandboxes will have access to `tools.agentQuery()`.
+     *
+     * @param sessionManager - Session manager instance
+     */
+    setSessionManager(sessionManager) {
+        this.sessionManager = sessionManager;
+    }
+    /**
+     * Build a Tools SDK instance for a specific session.
+     * Includes `agentQuery` bound to the session's ID for sub-agent delegation.
+     */
+    buildToolsSDK(sessionId) {
+        if (!this.fileSystem) {
+            return undefined;
+        }
+        return createToolsSDK({
+            curateService: this.curateService,
+            fileSystem: this.fileSystem,
+            parentSessionId: sessionId,
+            sandboxService: this,
+            searchKnowledgeService: this.searchKnowledgeService,
+            sessionManager: this.sessionManager,
+        });
     }
     /**
-     * Rebuild the Tools SDK instance when services change.
-     * Clears existing sandboxes so new ones get the updated SDK.
+     * Clear existing sandboxes so new ones get updated services.
+     * Called when file system, curate, or search services change.
      */
-    rebuildToolsSDK() {
+    invalidateSandboxes() {
         if (this.fileSystem) {
-            this.toolsSDK = createToolsSDK(this.fileSystem, this.searchKnowledgeService, this.curateService);
-            // Clear existing sandboxes so new ones get the updated tools SDK
-            // Note: This means existing sessions lose their state when services are updated
-            // This is acceptable since services are typically set once at startup
             this.sandboxes.clear();
         }
     }