@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/agent/subagent.js

@@ -1,3 +1,5 @@
+import { ZRouterStreamBackend } from './backends/zrouter_stream.js';
+import { readRouterCatalog } from '../utils/router_catalog.js';
 /**
  * SubAgent - Isolated agent for context-heavy operations
  *
@@ -9,6 +11,8 @@
  * Only the final summary is returned to the main agent, keeping the main context clean.
  */
 import { randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { getSessionPathForCwd, saveSessionToFile } from '../session.js';
 import { getDefaultModel } from '../utils/models.js';
 import { debugLog } from '../utils/debug_log.js';
 import { createBackendForProvider } from './backends/index.js';
@@ -16,9 +20,16 @@ import { accountBackendOptions, resolveRotation } from './backends/account_pool.
 import { buildAccountRotation, subagentShouldRotate } from './backends/rotation_factory.js';
 import { describeExecutionContext, resolveExecutionSettings } from './runtime/execution_context.js';
 import { createRecoveryGuard } from './runtime/recovery.js';
+import { listCommandJobs, shutdownCommandJobs } from './runtime/command_jobs.js';
+import { awaitManagedCommandProgress, formatManagedCommandObservations } from './runtime/command_wait.js';
 import { scheduleToolBatch, commandStillRunning } from './runtime/tool_scheduler.js';
 import { configStore } from '../config.js';
-import { ToolResponseStore } from './tool_response_store.js';
+import { RequestEncoder, nativeHistoryContextId } from './request_encoder.js';
+import { ToolResponseIntegrityError, ToolResponseStore } from './tool_response_store.js';
+import { formatEvidenceContext } from './runtime/evidence.js';
+import { acquireDelegatedEvidenceWriter, bindDelegatedEvidence, createDelegatedEvidenceHandoff } from './runtime/delegated_evidence.js';
+import { recallToolResponseTool } from './tools/recall_tool_response.js';
+import { sessionEvidenceTool } from './tools/session_evidence.js';
 import { RESEARCH_TOOLS } from '../worker/toolsets.js';
 import { renderPrompt } from '../utils/template.js';
 import { executeToolWithRuntime } from './runtime/tool_runtime.js';
@@ -44,6 +55,18 @@ function isToolUseBlock(block) {
 function getSubAgentModel(provider, preferredModel) {
     if (preferredModel)
         return preferredModel;
+    if (configStore.resolveLLMBackendConfig({ provider }).useProxy) {
+        if (configStore.getProvider() === provider)
+            return configStore.getModel();
+        const catalog = configStore.getRouterCatalog();
+        const rows = catalog?.models.filter(row => row.owned_by === provider && (catalog.version === 0 || row.capabilities?.chat));
+        const selected = rows?.find(row => row.is_default) ?? rows?.[0];
+        if (selected)
+            return selected.id;
+        if (!configStore.getRouterCatalog() || configStore.getRouterCatalog()?.version === 0)
+            return getDefaultModel(provider, 'cheap');
+        throw new Error('Select a Router model for this subagent.');
+    }
     return getDefaultModel(provider, 'cheap');
 }
 /**
@@ -57,6 +80,12 @@ function getSubAgentModel(provider, preferredModel) {
  */
 function createBackend(provider, apiKey) {
     const config = configStore.get();
+    const resolved = configStore.resolveLLMBackendConfig({ provider, apiKeyOverride: apiKey });
+    if (resolved.useProxy) {
+        return new ZRouterStreamBackend({ apiKey: resolved.authToken, proxyUrl: resolved.proxyUrl, provider,
+            workspaceId: configStore.getRouterCatalogConnection()?.workspaceId,
+            catalog: readRouterCatalog({ origin: resolved.proxyUrl, token: resolved.authToken, workspaceId: configStore.getRouterCatalogConnection()?.workspaceId }) });
+    }
     const accountOpts = accountBackendOptions(config, provider);
     const rotationOpts = subagentShouldRotate(resolveRotation(config))
         ? buildAccountRotation(config) ?? {}
@@ -85,23 +114,27 @@ export class SubAgent {
     cwd;
     inputTokens = 0;
     outputTokens = 0;
-    // Per-SubAgent offload store + discovery set. Subagent toolsets (RESEARCH /
-    // WRITE) don't include `tool_search` or `recall_tool_response`, but the
-    // ToolContext shape is required — and keeping these isolated guarantees a
-    // subagent's tool results never leak into the parent's session store.
+    // Exact results remain in the child's owned session, separate from the parent.
     toolResponseStore = new ToolResponseStore();
+    sessionId;
     discoveredTools = new Set();
     hooks;
     approvalRequester;
     constructor(config) {
-        this.config = config;
+        this.config = { ...config, commandPolicy: config.commandPolicy === undefined ? undefined : structuredClone(config.commandPolicy) };
+        this.sessionId = config.resumeSessionId ?? `subagent-${randomUUID()}`;
         this.backend = config.backend ?? createBackend(config.provider, config.apiKey);
         this.model = getSubAgentModel(config.provider, config.model);
-        this.cwd = config.cwd || process.cwd();
+        this.cwd = realpathSync(config.cwd || process.cwd());
         this.hooks = config.hooks;
         this.approvalRequester = config.approvalRequester;
         debug('Created SubAgent with model=%s, cwd=%s, timeout=%dms', this.model, this.cwd, config.timeoutMs || 120000);
     }
+    getSessionId() { return this.sessionId; }
+    getEvidenceSnapshot() { return this.toolResponseStore.evidence.getSnapshot(); }
+    getEvidenceHandoff(summary = '') {
+        return createDelegatedEvidenceHandoff({ sessionId: this.sessionId, parentSessionId: this.config.parentSessionId }, this.getEvidenceSnapshot(), summary);
+    }
     /**
      * Run a task and return a summary.
      *
@@ -109,9 +142,15 @@ export class SubAgent {
      * @param opts  Optional overrides (abort signal, custom system prompt, tools)
      */
     async run(task, opts) {
+        if (this.backend.getModelCapabilities?.(this.model)?.tools === false)
+            throw new Error('Chat-only models cannot run tool-dependent subagents.');
         const signal = opts?.signal;
         const startTime = Date.now();
         const timeoutMs = this.config.timeoutMs || 120000; // 2 minute default
+        const deadlineAt = startTime + timeoutMs;
+        const deadline = new AbortController();
+        const runSignal = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+        const commandSessionId = this.sessionId;
         const maxIterations = this.config.maxIterations || 5;
         let iterations = 0;
         let finalContent = '';
@@ -130,9 +169,18 @@ export class SubAgent {
         // This summary-producing worker does not own the parent checklist or
         // terminal answer lifecycle.
         const tools = (opts?.tools ?? RESEARCH_TOOLS).filter(tool => !tool.finalResponse);
+        // A native host supplies a closed, bounded vocabulary. Adding ambient
+        // helper schemas can reject that otherwise valid request before dispatch.
+        if (!this.backend.preservesNativeHistory || opts?.tools === undefined) {
+            for (const tool of [recallToolResponseTool, sessionEvidenceTool]) {
+                if (!tools.some(existing => existing.definition.name === tool.definition.name))
+                    tools.push(tool);
+            }
+        }
         const messages = [
+            ...structuredClone(opts?.messages ?? []),
             {
-                id: 'task_0',
+                id: `task_${randomUUID()}`,
                 role: 'user',
                 content: task,
                 timestamp: new Date()
@@ -140,36 +188,69 @@ export class SubAgent {
         ];
         // Helper to check timeout
         const checkTimeout = () => {
+            if (signal?.aborted)
+                throw new Error('Sub-agent cancelled');
             const elapsed = Date.now() - startTime;
-            if (elapsed > timeoutMs) {
+            if (elapsed >= timeoutMs || deadline.signal.aborted) {
                 throw new Error(`Sub-agent timed out after ${Math.round(elapsed / 1000)}s (limit: ${Math.round(timeoutMs / 1000)}s)`);
             }
         };
+        const deadlineTimer = setTimeout(() => deadline.abort(), timeoutMs);
+        let releaseWriter;
+        let evidenceBound = false;
+        const publishEvidence = () => {
+            opts?.onEvent?.({ type: 'evidence', sessionId: this.sessionId, snapshot: this.getEvidenceSnapshot() });
+        };
         try {
+            releaseWriter = await acquireDelegatedEvidenceWriter({ sessionId: this.sessionId,
+                parentSessionId: this.config.parentSessionId, cwd: this.cwd });
+            await bindDelegatedEvidence(this.toolResponseStore, this.discoveredTools, { sessionId: this.sessionId, parentSessionId: this.config.parentSessionId, cwd: this.cwd }, this.config.resumeSessionId !== undefined);
+            evidenceBound = true;
+            await this.persistEvidenceCheckpoint();
+            publishEvidence();
             while (iterations < maxIterations) {
-                if (signal?.aborted)
-                    throw new Error('Sub-agent cancelled');
                 checkTimeout();
                 iterations++;
                 debug('Iteration %d/%d', iterations, maxIterations);
+                const evidence = formatEvidenceContext(this.getEvidenceSnapshot());
+                const executionContext = describeExecutionContext({
+                    mode: 'delegated worker', cwd: this.cwd, tools: tools.map(tool => tool.definition.name),
+                    mux: false, configScope: configStore.getConfigScope(), maxTokens: 2048,
+                    outputLimitSource: 'delegated worker budget', settings: resolveExecutionSettings(configStore.get().execution), jobs: listCommandJobs(commandSessionId),
+                });
+                if (this.backend.preservesNativeHistory) {
+                    // Stamp current host observations into a new user row. Earlier rows
+                    // and the signed native system prefix keep their original bytes.
+                    messages.push({ id: `host_context_${randomUUID()}`, role: 'user',
+                        content: [evidence, executionContext].filter(Boolean).join('\n\n'), timestamp: new Date(),
+                        metadata: { synthetic: true, hostContext: true } });
+                }
+                const system = pinnedTaskSystem(systemPrompt, task) + (this.backend.preservesNativeHistory
+                    ? '' : '\n\n' + evidence + '\n\n' + executionContext);
+                const definitions = tools.map(tool => tool.definition);
+                const contextId = nativeHistoryContextId(system, definitions);
                 const request = {
                     model: this.model,
                     maxTokens: 2048,
                     // R7 parity: pin the task in request.system so a long subagent run
                     // can't lose the task framing the same way the main loop could (F9).
-                    system: pinnedTaskSystem(systemPrompt, task) + '\n\n' + describeExecutionContext({
-                        mode: 'delegated worker', cwd: this.cwd, tools: tools.map(tool => tool.definition.name),
-                        mux: false, configScope: configStore.getConfigScope(), maxTokens: 2048,
-                        outputLimitSource: 'delegated worker budget', settings: resolveExecutionSettings(configStore.get().execution), jobs: [],
-                    }),
-                    messages: this.formatMessages(messages),
-                    tools: tools.map(t => t.definition),
+                    system,
+                    messages: this.formatMessages(messages, contextId),
+                    tools: definitions,
                     // The inherited backend is pinned to the parent conversation; this is
                     // what tells it the prefix being sent is this run's instead.
                     agentRunId: this.agentRunId,
-                    signal,
+                    signal: runSignal,
                 };
-                const response = await this.backend.generate(request);
+                const response = await this.backend.generate(request).catch(error => {
+                    opts?.onUsage?.({ inputTokens: 0, outputTokens: 0, totalTokens: 0, estimated: true, unreported: true });
+                    throw error;
+                });
+                if (response.usage)
+                    opts?.onUsage?.(response.usage);
+                else
+                    opts?.onUsage?.({ inputTokens: 0, outputTokens: 0, totalTokens: 0, estimated: true, unreported: true });
+                checkTimeout();
                 // Normalize content to array — some backends/proxies may return a string
                 if (!Array.isArray(response.content)) {
                     const raw = response.content;
@@ -189,8 +270,47 @@ export class SubAgent {
                 if (isIncompleteModelResponse(response.stopReason)) {
                     throw new Error(incompleteModelResponseMessage(response.stopReason, request.maxTokens, response.usage?.outputTokens));
                 }
+                if (response.stopReason === 'refusal')
+                    throw new Error('The model declined this request.');
                 // Check for tool use
-                const toolUseBlocks = response.content.filter(isToolUseBlock);
+                const requestedToolBlocks = response.content.filter(isToolUseBlock);
+                const requestedIds = new Set();
+                for (const block of requestedToolBlocks) {
+                    if (requestedIds.has(block.id)) {
+                        throw new Error(`Provider response contains duplicate tool invocation ID ${block.id}; no call in this batch was executed.`);
+                    }
+                    requestedIds.add(block.id);
+                }
+                // Provider IDs describe this response, rather than retries of an owned
+                // operation. Allocate storage-safe identities before any tool effect,
+                // retaining the delegated source store's narrower 200-byte boundary.
+                const historicalIds = new Set(messages.flatMap(message => message.toolCalls?.map(call => call.id) ?? []));
+                const occupiedIds = new Set([...historicalIds, ...requestedIds]);
+                const toolUseBlocks = [];
+                for (const block of requestedToolBlocks) {
+                    if (/^[A-Za-z0-9_-]{1,200}$/.test(block.id)
+                        && !historicalIds.has(block.id) && !await this.hasStoredToolIdentity(block.id)) {
+                        toolUseBlocks.push(block);
+                        continue;
+                    }
+                    let id;
+                    let identityAttempts = 0;
+                    do {
+                        if (++identityAttempts > 16) {
+                            throw new Error('Unable to allocate a fresh tool invocation identity. Inspect retained source availability before retrying.');
+                        }
+                        id = `tool_${randomUUID()}`;
+                    } while (occupiedIds.has(id) || await this.hasStoredToolIdentity(id));
+                    occupiedIds.add(id);
+                    toolUseBlocks.push({ ...block, id });
+                }
+                if (this.backend.preservesNativeHistory && toolUseBlocks.length > 0) {
+                    // Keep signed/opaque native blocks intact while pairing tool-use IDs
+                    // with the canonical result identities admitted above.
+                    const canonicalIds = new Map(requestedToolBlocks.map((block, index) => [block.id, toolUseBlocks[index].id]));
+                    response.content = response.content.map(block => isToolUseBlock(block)
+                        ? { ...block, id: canonicalIds.get(block.id) } : block);
+                }
                 if (toolUseBlocks.length === 0) {
                     // No tools, extract final response
                     const textBlocks = response.content.filter(isTextBlock);
@@ -202,8 +322,15 @@ export class SubAgent {
                 }
                 debug('Executing %d tool(s): %s', toolUseBlocks.length, toolUseBlocks.map(tb => tb.name).join(', '));
                 // Execute tools and track what was accessed
+                const toolUseMessageId = `assistant_${randomUUID()}`;
                 const toolResults = await scheduleToolBatch(toolUseBlocks, tools, configStore.get().execution ?? {}, async (toolBlock, skipReason) => {
+                    // Leave room for .json and its atomic-write suffix on 255-byte filesystems.
+                    if (!/^[A-Za-z0-9_-]{1,200}$/.test(toolBlock.id))
+                        throw new Error('Invalid delegated tool-call identity');
+                    let retainingSource = false;
                     try {
+                        if (this.toolResponseStore.getMeta(toolBlock.id))
+                            throw new Error('Delegated tool call identity already retained; recall the original source using a fresh call ID.');
                         if (skipReason)
                             throw new Error(skipReason);
                         checkTimeout();
@@ -213,8 +340,12 @@ export class SubAgent {
                             context: {
                                 cwd: this.cwd,
                                 toolCallId: toolBlock.id,
-                                signal,
+                                onUsage: opts?.onUsage,
+                                sessionId: commandSessionId,
+                                managedCommandWaitSliceMs: 0,
+                                signal: runSignal,
                                 temporaryWriteRoot: this.config.temporaryWriteRoot,
+                                commandPolicy: this.config.commandPolicy,
                                 toolResponseStore: this.toolResponseStore,
                                 discoveredTools: this.discoveredTools,
                                 availableTools: tools,
@@ -229,21 +360,40 @@ export class SubAgent {
                         if (!result.isError) {
                             this.trackToolUsage(toolBlock.name, result.effectiveArgs, result.content);
                         }
+                        retainingSource = true;
+                        const source = this.evidenceSource(toolBlock.id, toolBlock.name, result.effectiveArgs, result.managedCommand);
+                        if (result.verificationReceipt) {
+                            source.origin = 'host_receipt';
+                            source.verification = result.verificationReceipt;
+                        }
+                        const rendered = this.toolResponseStore.put(toolBlock.id, toolBlock.name, result.content, Boolean(runSignal.aborted || result.contentTruncated || result.managedCommand?.result.has_more || result.managedCommand?.result.output_truncated), { args: result.effectiveArgs, isError: result.isError, source: { ...source, messageId: toolUseMessageId } }).rendered;
+                        await this.toolResponseStore.flush();
+                        retainingSource = false;
+                        publishEvidence();
                         return {
                             is_error: result.isError,
                             tool_use_id: toolBlock.id,
-                            content: applyRepeatGuard(toolBlock.name, toolBlock.input, result.isError ? `Error: ${result.content}` : result.content),
+                            managedCommand: result.managedCommand,
+                            content: applyRepeatGuard(toolBlock.name, toolBlock.input, result.isError ? `Error: ${rendered}` : rendered, result.isError ? undefined : result.managedCommand),
                         };
                     }
                     catch (err) {
+                        // Source retention failure or reused identity must stop inference;
+                        // neither establishes that an already dispatched effect did not run.
+                        if (retainingSource || this.toolResponseStore.getMeta(toolBlock.id))
+                            throw err;
                         debug('Tool %s failed: %s', toolBlock.name, err.message);
+                        const content = `Error: ${err.message}`;
+                        this.toolResponseStore.put(toolBlock.id, toolBlock.name, content, runSignal.aborted, { args: toolBlock.input, isError: true, source: { ...this.evidenceSource(toolBlock.id, toolBlock.name, toolBlock.input), messageId: toolUseMessageId } });
+                        await this.toolResponseStore.flush();
+                        publishEvidence();
                         return {
                             is_error: true,
                             tool_use_id: toolBlock.id,
-                            content: `Error: ${err.message}`
+                            content,
                         };
                     }
-                }, result => result.is_error || commandStillRunning(result.content), signal);
+                }, result => result.is_error || result.managedCommand?.result.status === 'running' || commandStillRunning(result.content), runSignal);
                 opts?.onIteration?.({
                     iteration: iterations,
                     max: maxIterations,
@@ -255,9 +405,10 @@ export class SubAgent {
                     .map(b => b.text)
                     .join('\n');
                 messages.push({
-                    id: `assistant_${iterations}`,
+                    id: toolUseMessageId,
                     role: 'assistant',
                     content: textContent || '[Using tools...]',
+                    ...(this.backend.preservesNativeHistory ? { nativeContent: structuredClone(response.content), nativeModel: this.model, nativeContextId: contextId } : {}),
                     timestamp: new Date(),
                     toolCalls: toolUseBlocks.map(tb => ({
                         id: tb.id,
@@ -274,19 +425,39 @@ export class SubAgent {
                 messages.push({
                     id: `tool_${iterations}`,
                     role: 'user',
-                    content: JSON.stringify(toolResults),
+                    content: JSON.stringify(toolResults.map(({ managedCommand: _observation, ...result }) => result)),
                     timestamp: new Date()
                 });
+                checkTimeout();
                 const recoveryAction = recovery(toolResults.map((result, index) => ({
                     name: toolUseBlocks[index].name, content: result.content, isError: result.is_error,
+                    managedCommand: result.managedCommand,
                 })));
                 if (recoveryAction === 'stop')
                     throw new Error('Automatic recovery budget exhausted after repeated tool failures.');
                 if (recoveryAction === 'recover')
                     messages.push({ id: `recovery_${iterations}`, role: 'user',
                         content: 'Repeated failures: inspect current capabilities, then try one changed recovery approach. Do not repeat the failing sequence.', timestamp: new Date() });
+                if (iterations < maxIterations && toolResults.every(result => !result.is_error && result.managedCommand !== undefined)) {
+                    const waiting = await awaitManagedCommandProgress(toolResults.map(result => ({
+                        ...result.managedCommand, toolCallId: result.tool_use_id,
+                    })), { signal: runSignal, deadlineAt, emit: opts?.onEvent });
+                    checkTimeout();
+                    if (waiting.waited) {
+                        for (const observation of waiting.observations) {
+                            this.toolResponseStore.put(`wait_${randomUUID()}`, 'read_command', JSON.stringify(observation.result), Boolean(observation.result.has_more || observation.result.output_truncated), { source: { ...this.evidenceSource(observation.toolCallId, 'read_command', {}, observation), originToolCallId: observation.toolCallId } });
+                        }
+                        await this.toolResponseStore.flush();
+                        publishEvidence();
+                    }
+                    if (waiting.waited)
+                        messages.push({ id: `command_observation_${randomUUID()}`, role: 'user',
+                            content: formatManagedCommandObservations(waiting.observations), timestamp: new Date(),
+                            metadata: { synthetic: true, hostContext: true } });
+                }
             }
             const durationMs = Date.now() - startTime;
+            await this.persistEvidenceCheckpoint();
             // Exhausted maxIterations while still requesting tools = did NOT finish.
             const exhausted = !completedCleanly;
             const success = !exhausted;
@@ -308,6 +479,7 @@ export class SubAgent {
                 });
             }
             return {
+                evidence: this.getEvidenceHandoff(finalContent),
                 summary: finalContent || 'Sub-agent completed but produced no summary.',
                 filesRead: Array.from(this.filesRead),
                 commandsRun: this.commandsRun,
@@ -324,7 +496,15 @@ export class SubAgent {
         }
         catch (err) {
             const durationMs = Date.now() - startTime;
-            const errMsg = err.message;
+            let errMsg = err.message;
+            // Reads and inference receive the combined signal. Keep the public worker
+            // outcome specific to its controlling deadline or the user's cancellation.
+            try {
+                checkTimeout();
+            }
+            catch (controlError) {
+                errMsg = controlError.message;
+            }
             debug('Task failed after %dms: %s', durationMs, errMsg);
             if (this.hooks) {
                 await this.hooks.dispatch('SubagentStop', {
@@ -341,6 +521,7 @@ export class SubAgent {
                 });
             }
             return {
+                evidence: this.getEvidenceHandoff(''),
                 summary: '',
                 filesRead: Array.from(this.filesRead),
                 commandsRun: this.commandsRun,
@@ -355,6 +536,54 @@ export class SubAgent {
                 durationMs
             };
         }
+        finally {
+            clearTimeout(deadlineTimer);
+            if (releaseWriter) {
+                try {
+                    if (evidenceBound)
+                        await shutdownCommandJobs(commandSessionId);
+                }
+                finally {
+                    await releaseWriter();
+                }
+            }
+        }
+    }
+    async hasStoredToolIdentity(id) {
+        if (this.toolResponseStore.getMeta(id)
+            || this.toolResponseStore.evidence.getSnapshot().records.some(record => record.source.toolCallId === id))
+            return true;
+        try {
+            // A source can outlive its conversation row or arrive after binding.
+            // Missing indexed bodies and malformed originals still reserve their ID.
+            return await this.toolResponseStore.get(id) !== null;
+        }
+        catch (error) {
+            if (error instanceof ToolResponseIntegrityError)
+                return true;
+            throw error;
+        }
+    }
+    async persistEvidenceCheckpoint() {
+        await this.toolResponseStore.flush();
+        // Delegated instructions originate with the parent model, not the user.
+        // Save a canonical evidence checkpoint without synthesizing user directives
+        // or transferring a child conversation's permissions through task handoff.
+        await saveSessionToFile(getSessionPathForCwd(this.cwd, this.sessionId), this.sessionId, this.cwd, [], this.model, this.config.provider, undefined, undefined, { evidence: this.getEvidenceSnapshot(), mode: 'delegated' });
+    }
+    evidenceSource(toolCallId, toolName, args, managed) {
+        const source = { origin: managed ? 'host_receipt' : 'host_tool', toolCallId, toolName, cwd: this.cwd,
+            ...(typeof args.path === 'string' ? { path: args.path } : {}) };
+        if (managed) {
+            const result = managed.result;
+            source.job = { sessionId: managed.sessionId, jobId: result.job_id, status: result.status, exitCode: result.exit_code ?? null,
+                startedAt: result.started_at, endedAt: result.ended_at, cursor: result.cursor, hasMore: result.has_more, outputTruncated: Boolean(result.output_truncated),
+                ...(result.checked === undefined ? {} : { checked: result.checked }) };
+            source.artifact = { path: result.log_path };
+            if (result.verification)
+                source.verification = result.verification;
+        }
+        return source;
     }
     /**
      * Track what the sub-agent accessed
@@ -378,7 +607,15 @@ export class SubAgent {
     /**
      * Format messages for the API
      */
-    formatMessages(messages) {
+    formatMessages(messages, contextId) {
+        if (this.backend.preservesNativeHistory) {
+            return new RequestEncoder({ preserveNativeHistory: true, model: this.model,
+                nativeContextId: contextId,
+                selectorVerdict: null,
+                currentTurnToolIds: new Set(messages.flatMap(message => message.toolCalls?.map(call => call.id) ?? [])),
+                renderForContext: () => null, loadImageBlock: () => null, loadVideoBlock: () => null,
+            }).encode(messages).messages;
+        }
         return messages
             .filter(m => m.role === 'user' || m.role === 'assistant')
             .map(m => {

package/dist/agent/tool_response_directory.d.ts

@@ -0,0 +1,24 @@
+export declare const TOOL_RESPONSE_DIRECTORY_ENTRY_LIMIT = 1024;
+export declare const TOOL_RESPONSE_DIRECTORY_NAME_BYTE_LIMIT: number;
+export declare const TOOL_RESPONSE_DIRECTORY_BUFFER_SIZE = 16;
+export interface ToolResponseDirectoryAdmission {
+    status: 'not_bound' | 'complete' | 'limited' | 'failed';
+    complete: boolean;
+    directoryComplete: boolean;
+    reasons: Array<'directory_entry_limit' | 'candidate_name_byte_limit' | 'source_retention_limit' | 'directory_error'>;
+    directoryEntriesRead: number;
+    directoryEntryLimit: number;
+    candidateNames: number;
+    candidateNameBytes: number;
+    candidateNameByteLimit: number;
+    bufferSize: number;
+    admittedSources: number;
+    skippedSources: number;
+    errorCode?: string;
+}
+export declare function emptyDirectoryAdmission(): ToolResponseDirectoryAdmission;
+/** Bound discovery independently of unrelated directory size; known index names take priority. */
+export declare function collectResponseFilenames(directory: string, indexedNames: readonly string[]): Promise<{
+    files: string[];
+    admission: ToolResponseDirectoryAdmission;
+}>;

package/dist/agent/tool_response_directory.js

@@ -0,0 +1,61 @@
+import { opendir } from 'node:fs/promises';
+import { EVIDENCE_MAX_RECORDS } from './runtime/evidence.js';
+export const TOOL_RESPONSE_DIRECTORY_ENTRY_LIMIT = 1024;
+export const TOOL_RESPONSE_DIRECTORY_NAME_BYTE_LIMIT = 64 * 1024;
+export const TOOL_RESPONSE_DIRECTORY_BUFFER_SIZE = 16;
+export function emptyDirectoryAdmission() {
+    return { status: 'not_bound', complete: false, directoryComplete: false, reasons: [],
+        directoryEntriesRead: 0, directoryEntryLimit: TOOL_RESPONSE_DIRECTORY_ENTRY_LIMIT,
+        candidateNames: 0, candidateNameBytes: 0, candidateNameByteLimit: TOOL_RESPONSE_DIRECTORY_NAME_BYTE_LIMIT,
+        bufferSize: TOOL_RESPONSE_DIRECTORY_BUFFER_SIZE, admittedSources: 0, skippedSources: 0 };
+}
+/** Bound discovery independently of unrelated directory size; known index names take priority. */
+export async function collectResponseFilenames(directory, indexedNames) {
+    const admission = emptyDirectoryAdmission();
+    if (indexedNames.length > EVIDENCE_MAX_RECORDS * 2)
+        throw new RangeError('Indexed source filenames exceed the bounded evidence capacity');
+    const indexed = new Set(indexedNames);
+    const files = [...indexed].sort();
+    const discovered = new Set();
+    admission.candidateNameBytes = files.reduce((sum, name) => sum + Buffer.byteLength(name), 0);
+    if (admission.candidateNameBytes > admission.candidateNameByteLimit)
+        throw new RangeError('Indexed source filename metadata exceeds its admission byte limit');
+    const handle = await opendir(directory, { bufferSize: TOOL_RESPONSE_DIRECTORY_BUFFER_SIZE });
+    // A boundary failure must close the descriptor even when an iterator rejects its next read.
+    try {
+        for await (const entry of handle) {
+            admission.directoryEntriesRead++;
+            if (admission.directoryEntriesRead > admission.directoryEntryLimit) {
+                admission.reasons.push('directory_entry_limit');
+                break;
+            }
+            const name = entry.name;
+            if (name === '.evidence.json' || !name.endsWith('.json') || indexed.has(name))
+                continue;
+            const size = Buffer.byteLength(name);
+            if (admission.candidateNameBytes + size > admission.candidateNameByteLimit) {
+                admission.reasons.push('candidate_name_byte_limit');
+                break;
+            }
+            if (discovered.has(name))
+                continue;
+            discovered.add(name);
+            admission.candidateNameBytes += size;
+        }
+    }
+    finally {
+        try {
+            await handle.close();
+        }
+        catch (error) {
+            if (error.code !== 'ERR_DIR_CLOSED')
+                throw error;
+        }
+    }
+    files.push(...[...discovered].sort());
+    admission.candidateNames = files.length;
+    admission.directoryComplete = admission.reasons.length === 0;
+    admission.complete = admission.directoryComplete;
+    admission.status = admission.complete ? 'complete' : 'limited';
+    return { files, admission };
+}

package/dist/agent/tool_response_source.d.ts

@@ -0,0 +1,8 @@
+import { type Stats } from 'node:fs';
+/** A source cannot be admitted without its complete, stable, bounded bytes. */
+export declare class SourceAdmissionError extends Error {
+}
+export declare function readBoundedSource(path: string, maximumBytes: number): Promise<{
+    text: string;
+    info: Stats;
+}>;

package/dist/agent/tool_response_source.js

@@ -0,0 +1,49 @@
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { TextDecoder } from 'node:util';
+/** A source cannot be admitted without its complete, stable, bounded bytes. */
+export class SourceAdmissionError extends Error {
+}
+export async function readBoundedSource(path, maximumBytes) {
+    if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 1)
+        throw new RangeError('Invalid source byte admission limit');
+    // Nonblocking/no-follow protects a regular name changed to a FIFO or symlink.
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile())
+            throw new SourceAdmissionError('Source admission requires a regular file');
+        if (!Number.isSafeInteger(before.size) || before.size < 0 || before.size > maximumBytes) {
+            throw new SourceAdmissionError(`Source exceeds byte admission limit (${maximumBytes})`);
+        }
+        // One sentinel byte catches growth even when a filesystem's stat timestamps are coarse.
+        const buffer = Buffer.allocUnsafe(before.size + 1);
+        let count = 0;
+        while (count < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, count, Math.min(65536, buffer.length - count), count);
+            if (bytesRead === 0)
+                break;
+            count += bytesRead;
+        }
+        const after = await handle.stat();
+        const named = await lstat(path);
+        if (count > maximumBytes)
+            throw new SourceAdmissionError(`Source exceeds byte admission limit (${maximumBytes})`);
+        if (count !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs
+            || !named.isFile() || named.dev !== before.dev || named.ino !== before.ino
+            || named.size !== before.size || named.mtimeMs !== before.mtimeMs || named.ctimeMs !== before.ctimeMs) {
+            throw new SourceAdmissionError('Source changed during bounded admission');
+        }
+        let text;
+        try {
+            text = new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, count));
+        }
+        catch {
+            throw new SourceAdmissionError('Source admission requires valid UTF-8 bytes');
+        }
+        return { text, info: before };
+    }
+    finally {
+        await handle.close();
+    }
+}