@namzu/sdk 51.1.0 → 52.1.0

package/dist/runtime/query/executor.js

@@ -20,13 +20,24 @@ import { generateToolCallId } from '../../utils/id.js';
 import { compressShellOutput } from '../../utils/shell-compress.js';
 import { parseStructuredResultJson } from '../../utils/structured-result-json.js';
 import { bindOwner } from '../jobs/registry.js';
-import { formatFailedToolOutput, isUnregistered, prepareDirectCall, runPreToolHook, unknownToolMessage, } from './executor/tool-call-admission.js';
+import { formatFailedToolOutput, hookNote, isUnregistered, prepareDirectCall, runPreToolHook, unknownToolMessage, } from './executor/tool-call-admission.js';
 import { describeVisibleFileEvidence } from './file-evidence-context.js';
 import { seedObservationLedger } from './file-evidence-seed.js';
 import { DEFAULT_TOOL_RESULT_GUARDRAILS } from './guardrail-presets.js';
+import { declaredWriteEscalation, shellEscalations } from './path-escalation.js';
 import { savedPresentation } from './saved-presentation.js';
 import { ToolCallBudget, assertMaxToolCalls } from './tool-call-budget.js';
-import { DEFAULT_MAX_TOOL_OUTPUT_CHARS, applyToolOutputBudget, describeDroppedContent, measureContentBytes, } from './tool-output-budget.js';
+import { DEFAULT_MAX_TOOL_OUTPUT_CHARS, DEFAULT_MAX_TOOL_OUTPUT_CHARS_PER_MESSAGE, applyToolOutputBudget, describeDroppedContent, fitResultsToMessageBudget, measureContentBytes, } from './tool-output-budget.js';
+/**
+ * A nested call cannot open a review from inside the tool that issued it, so
+ * a hook that asked for a person to approve it can only be answered with a
+ * refusal. Silence would run the call the hook wanted a person to see.
+ */
+function askedNestedMessage(toolName, outcome) {
+    if (outcome.kind !== 'continue' || outcome.permission?.decision !== 'ask')
+        return undefined;
+    return `Blocked: a hook asked that a person approve "${toolName}", and an approval cannot be requested from inside another tool. Call it directly.`;
+}
 function assertUniqueToolCallIds(toolCalls) {
     const seen = new Set();
     for (const [index, toolCall] of toolCalls.entries()) {
@@ -226,6 +237,7 @@ export class ToolExecutor {
     /** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
     stepAllowedTools;
     fileReadTracker;
+    sandboxGate;
     /** A ledger is rebuilt from history at most once; a second pass would re-append its chains. */
     fileObservationsSeeded = false;
     constructor(config, activityStore, emitEvent, log, probes = defaultProbeRegistry) {
@@ -245,6 +257,22 @@ export class ToolExecutor {
     }
     setSandbox(sandbox) {
         this.config = { ...this.config, sandbox };
+        this.sandboxGate = undefined;
+    }
+    /**
+     * Hold tool admission until a sandbox that is still being acquired exists.
+     * The gate rejects when none will, and the turn settles that rejection. It
+     * is cleared by {@link setSandbox}, so a turn pays the check once.
+     */
+    setSandboxGate(gate) {
+        this.sandboxGate = gate;
+    }
+    async awaitSandbox() {
+        await this.sandboxGate?.();
+    }
+    /** True once the turn has a sandbox, or is certain to get one before a tool runs. */
+    get sandboxed() {
+        return this.config.sandbox !== undefined || this.sandboxGate !== undefined;
     }
     /** Classify only the exact successful result executed by this executor. */
     recordedObservationKey(call, message) {
@@ -318,7 +346,7 @@ export class ToolExecutor {
     }
     /** Request-only evidence from the same ledger used by mutation admission. No filesystem I/O. */
     describeFileEvidence(messages) {
-        return describeVisibleFileEvidence(messages, this.fileReadTracker, this.config.workingDirectory, this.config.sandbox !== undefined);
+        return describeVisibleFileEvidence(messages, this.fileReadTracker, this.config.workingDirectory, this.sandboxed);
     }
     /**
      * Span that this executor's tool spans should hang off — the current
@@ -480,7 +508,7 @@ export class ToolExecutor {
     commandDialect(toolName) {
         const tool = this.config.tools.get(toolName);
         return (tool?.commandDialect?.({
-            sandboxed: this.config.sandbox !== undefined,
+            sandboxed: this.sandboxed,
         }) ?? 'sh');
     }
     /**
@@ -500,6 +528,8 @@ export class ToolExecutor {
      */
     async prepareBatchForReview(response, hostModifiedCallIds) {
         assertUniqueToolCallIds(response.message.toolCalls ?? []);
+        if ((response.message.toolCalls ?? []).length > 0)
+            await this.awaitSandbox();
         const calls = new Map();
         const escalations = new Map();
         for (const toolCall of response.message.toolCalls ?? []) {
@@ -531,7 +561,7 @@ export class ToolExecutor {
         if (!tool || call.input === null || typeof call.input !== 'object')
             return undefined;
         const input = call.input;
-        const sandboxed = this.config.sandbox !== undefined;
+        const sandboxed = this.sandboxed;
         let outsidePaths;
         if (this.config.outsideRootAccess === 'review' &&
             !sandboxed &&
@@ -548,12 +578,67 @@ export class ToolExecutor {
             tool.sandboxEscapeArgument !== undefined &&
             input[tool.sandboxEscapeArgument] === true;
         const unknownProgram = this.unknownProgramOf(tool, input, sandboxed);
-        if (!outsidePaths && !sandboxEscape && unknownProgram === undefined)
+        const reaches = await this.pathEscalationsOf(tool, input, sandboxed);
+        if (reaches.outsidePaths.length > 0) {
+            outsidePaths = [...new Set([...(outsidePaths ?? []), ...reaches.outsidePaths])];
+        }
+        const protectedPaths = reaches.protectedPaths;
+        const removal = reaches.dangerousRemoval;
+        if (!outsidePaths &&
+            !sandboxEscape &&
+            unknownProgram === undefined &&
+            protectedPaths.length === 0 &&
+            removal === undefined) {
             return undefined;
+        }
         return {
             ...(outsidePaths ? { outsidePaths } : {}),
             ...(sandboxEscape ? { sandboxEscape: true } : {}),
             ...(unknownProgram !== undefined ? { unknownProgram } : {}),
+            ...(protectedPaths.length > 0 ? { protectedPaths } : {}),
+            ...(removal !== undefined ? { dangerousRemoval: removal } : {}),
+        };
+    }
+    /**
+     * What the call's own arguments write or remove that no mode may approve in
+     * advance, and, for a shell line, the paths outside the roots it names.
+     *
+     * The protected-path and removal floors hold whether or not the turn reviews
+     * outside paths and whether or not it is sandboxed: they are about what the
+     * write plants and what the removal destroys, not about where the turn is
+     * allowed to look. The outside-path half follows `outsideRootAccess`, as the
+     * file tools' own does.
+     */
+    async pathEscalationsOf(tool, input, sandboxed) {
+        const roots = toolRoots(this.config);
+        const protectedPaths = [];
+        let outsidePaths = [];
+        let removal;
+        if (tool.pathArgument !== undefined && tool.isReadOnly?.(input) !== true) {
+            const value = input[tool.pathArgument];
+            if (typeof value === 'string') {
+                const hit = await declaredWriteEscalation(roots, value);
+                if (hit !== undefined)
+                    protectedPaths.push(hit);
+            }
+        }
+        if (tool.commandArgument !== undefined) {
+            const line = input[tool.commandArgument];
+            if (typeof line === 'string') {
+                const dialect = tool.commandDialect?.({ sandboxed }) ?? 'sh';
+                const found = await shellEscalations(line, dialect, {
+                    roots,
+                    reviewOutside: this.config.outsideRootAccess === 'review' && !sandboxed,
+                });
+                protectedPaths.push(...found.protectedPaths);
+                outsidePaths = found.outsidePaths;
+                removal = found.dangerousRemoval;
+            }
+        }
+        return {
+            outsidePaths,
+            protectedPaths: [...new Set(protectedPaths)],
+            ...(removal !== undefined ? { dangerousRemoval: removal } : {}),
         };
     }
     /**
@@ -602,11 +687,13 @@ export class ToolExecutor {
             .filter((call) => call.kind !== 'synthetic')
             .map((call) => {
             const escalation = escalations.get(call.toolCall.id);
+            const hookPermission = call.hook?.permission;
             return {
                 id: call.toolCall.id,
                 name: call.toolName,
                 input: call.input,
                 ...(escalation ? { escalation } : {}),
+                ...(hookPermission ? { hookPermission } : {}),
             };
         });
         const batch = Object.freeze({
@@ -623,6 +710,8 @@ export class ToolExecutor {
             return { messages: [], results: [], observations: [] };
         }
         assertUniqueToolCallIds(toolCalls);
+        if (toolCalls.length > 0)
+            await this.awaitSandbox();
         // Sampled here, once, and held for every call below. See the note on
         // `permissionMode` in the config type.
         this.batchMode = this.resolvePermissionMode();
@@ -832,6 +921,7 @@ export class ToolExecutor {
                 isError: true,
             });
         }
+        this.fitBatchToMessageBudget(results);
         // isError and rich content were computed and then discarded here: the
         // tuple narrowed to {toolCallId, output} BEFORE the message was built,
         // so the failure signal and any image block were structurally lost at
@@ -839,6 +929,46 @@ export class ToolExecutor {
         const messages = results.map((r) => createToolMessage(r.content ?? r.output, r.toolCallId, r.isError, r.revealedTools));
         return { messages, results, observations };
     }
+    /**
+     * Hold the batch's combined result text under the per-message cap.
+     *
+     * Runs once, on the settled batch and before the results become history
+     * messages, so what it writes is what every later request replays.
+     */
+    fitBatchToMessageBudget(results) {
+        const maxChars = this.config.maxToolOutputCharsPerMessage ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS_PER_MESSAGE;
+        const replacements = fitResultsToMessageBudget(results.map((r) => ({
+            toolCallId: r.toolCallId,
+            toolName: r.toolName,
+            output: r.output,
+            // A result carrying rich content or a structured-output copy is
+            // not text the model reads alone, and a self-limiting tool has
+            // already decided its own size.
+            replaceable: r.content === undefined &&
+                r.structuredResultJson === undefined &&
+                this.config.tools.get(r.toolName)?.selfLimitingOutput !== true,
+        })), {
+            maxChars,
+            spillDir: this.outputDirectory(),
+            onError: (message) => this.log.warn('Failed to retain a tool output replaced for the message budget', {
+                [NAMZU.TURN_ID]: this.config.turnId,
+                'exception.message': message,
+            }),
+        });
+        if (replacements.size === 0)
+            return;
+        for (const [i, r] of results.entries()) {
+            const replacement = replacements.get(r.toolCallId);
+            if (replacement === undefined)
+                continue;
+            results[i] = { ...r, output: replacement.output };
+        }
+        this.log.warn("Tool results exceeded the message's combined budget", {
+            [NAMZU.TURN_ID]: this.config.turnId,
+            'namzu.runtime.replaced_count': replacements.size,
+            'namzu.runtime.message_budget_chars': maxChars,
+        });
+    }
     /**
      * Run a tool on behalf of another tool, and put it on the record.
      *
@@ -1236,7 +1366,9 @@ export class ToolExecutor {
         let input;
         let prepared;
         let inputFailure;
+        let preparedHookContext;
         if (preparedCall?.kind === 'ready' || preparedCall?.kind === 'legacy') {
+            preparedHookContext = preparedCall.hook?.context;
             input = preparedCall.input;
             prepared = preparedCall.kind === 'ready' ? preparedCall.prepared : undefined;
             if (preparedCall.kind === 'legacy')
@@ -1262,6 +1394,7 @@ export class ToolExecutor {
                 return this.recordSyntheticPreparation(admitted);
             toolName = admitted.toolName;
             input = admitted.input;
+            preparedHookContext = admitted.hook?.context;
             prepared = admitted.kind === 'ready' ? admitted.prepared : undefined;
             if (admitted.kind === 'legacy')
                 inputFailure = admitted.inputFailure;
@@ -1460,7 +1593,10 @@ export class ToolExecutor {
                 ];
             }
         }
-        const maxToolOutputChars = this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS;
+        // A tool that bounds its own output is exempt from the DEFAULT per-result
+        // cap only; a host that set the cap explicitly still gets it.
+        const maxToolOutputChars = this.config.maxToolOutputChars ??
+            (executedDefinition?.selfLimitingOutput === true ? 0 : DEFAULT_MAX_TOOL_OUTPUT_CHARS);
         const sourceOutput = output;
         // This owner-bound channel follows the selected receipt after both result
         // screening and post-tool replacement. ToolResult.data and raw input can
@@ -1511,12 +1647,25 @@ export class ToolExecutor {
             });
         }
         output = budgeted.output;
-        const modelContent = selectedContent === undefined
+        let modelContent = selectedContent === undefined
             ? undefined
             : this.budgetContent(selectedContent, toolName, toolCall.id, {
                 sourceOutput,
                 budgeted,
             });
+        // What hooks said about this call rides with its result, in the model's
+        // receipt and the host's alike, framed as a hook's words. Added after
+        // the output budget so a bounded result is never trimmed to make room
+        // for it; the note has its own bound (`hookNote`).
+        const hookTexts = [preparedHookContext, post.context].filter((text) => text !== undefined && text.length > 0);
+        if (hookTexts.length > 0) {
+            const note = hookNote(hookTexts);
+            output = `${output}\n\n${note}`;
+            if (typeof modelContent === 'string')
+                modelContent = `${modelContent}\n\n${note}`;
+            else if (modelContent)
+                modelContent = [...modelContent, { type: 'text', text: note }];
+        }
         // A failed call, or an override that says the call failed. A `replace`
         // says the opposite, and reading it as a failure is what made redaction
         // unusable: the model was told a successful call had gone wrong, and
@@ -1820,8 +1969,21 @@ export class ToolExecutor {
             emitEvent: this.emitEvent,
             log: this.log,
             allowedTools: this.effectiveAllowedTools(),
+            requestHalt: (reason) => this.requestHalt(reason),
         };
     }
+    /** Why a hook asked for the turn to stop, until the iteration loop reads it. */
+    haltReason;
+    /** The first request wins: a later hook does not rewrite why the turn stopped. */
+    requestHalt(reason) {
+        this.haltReason ??= reason;
+    }
+    /** Read and clear a hook's request to stop the turn. */
+    takeHalt() {
+        const reason = this.haltReason;
+        this.haltReason = undefined;
+        return reason;
+    }
     async prepareNestedCall(toolName, input, signal) {
         signal.throwIfAborted();
         const prepare = this.config.tools.prepareExecutionAsync ?? this.config.tools.prepareExecution;
@@ -1845,6 +2007,14 @@ export class ToolExecutor {
                     ...(preOutcome.kind === 'skip' ? { skipped: true } : {}),
                 };
             }
+            const nestedAsk = askedNestedMessage(toolName, preOutcome);
+            if (nestedAsk)
+                return {
+                    kind: 'synthetic',
+                    input: preOutcome.input,
+                    message: nestedAsk,
+                    isError: true,
+                };
             return { kind: 'legacy', input: preOutcome.input };
         }
         let preparation;
@@ -1885,6 +2055,15 @@ export class ToolExecutor {
                 ...(preOutcome.kind === 'skip' ? { skipped: true } : {}),
             };
         }
+        const nestedAsk = askedNestedMessage(toolName, preOutcome);
+        if (nestedAsk) {
+            return {
+                kind: 'synthetic',
+                input: preOutcome.input,
+                message: nestedAsk,
+                isError: true,
+            };
+        }
         if (!preOutcome.modified) {
             return {
                 kind: 'ready',
@@ -1937,6 +2116,7 @@ export class ToolExecutor {
     /**
      * @returns `override` — text replacing the tool's output, or `null`.
      *   `retry` — the hook asked for the tool to run again.
+     *   `context` — what the hooks want the model to read beside the result.
      */
     async runPostToolHook(toolName, input, toolResult) {
         if (!this.config.pluginManager)
@@ -1951,6 +2131,22 @@ export class ToolExecutor {
                 toolResult,
                 signal: this.config.abortSignal,
             }, this.emitEvent);
+            // A failed call is announced a second time, by name, so a hook that
+            // only cares about failures need not read every result. After
+            // `post_tool_use`, so the existing hooks see exactly what they saw.
+            if (!toolResult.success) {
+                results = [
+                    ...results,
+                    ...(await this.config.pluginManager.executeHooks('post_tool_use_failure', {
+                        sessionId: this.config.sessionId,
+                        turnId: this.config.turnId,
+                        toolName,
+                        toolInput: input,
+                        toolResult,
+                        signal: this.config.abortSignal,
+                    }, this.emitEvent)),
+                ];
+            }
         }
         catch (error) {
             if (!this.config.abortSignal.aborted)
@@ -1969,9 +2165,14 @@ export class ToolExecutor {
         }
         let override = null;
         let retry = false;
+        const contexts = [];
         for (const result of results) {
             switch (result.action) {
                 case 'continue':
+                    if (result.context)
+                        contexts.push(result.context);
+                    if (result.halt)
+                        this.requestHalt(result.halt.reason);
                     continue;
                 case 'error':
                     override = { output: `Error: ${result.message}`, isError: true };
@@ -2005,7 +2206,11 @@ export class ToolExecutor {
                 }
             }
         }
-        return { override, retry };
+        return {
+            override,
+            retry,
+            ...(contexts.length > 0 ? { context: contexts.join('\n') } : {}),
+        };
     }
     /**
      * Answer a tool call that policy or a human refused, without executing