@namzu/sdk 34.2.0 → 36.0.0

package/src/runtime/query/executor.ts

@@ -1,3 +1,4 @@
+import { join } from 'node:path'
 import type { Span } from '@opentelemetry/api'
 import type { AuthorizationGate } from '../../authorization/gate.js'
 import { extractFromToolCall, extractFromToolResult } from '../../compaction/extractor.js'
@@ -47,10 +48,11 @@ import { toErrorMessage } from '../../utils/error.js'
 import { generateToolCallId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
-import { type BackgroundJobRegistry, bindOwner } from '../jobs/registry.js'
+import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/registry.js'
 import type { ToolResultObservation } from './project-instructions.js'
 import {
 	DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+	type ToolOutputBudgetResult,
 	applyToolOutputBudget,
 	describeDroppedContent,
 	measureContentBytes,
@@ -290,6 +292,8 @@ export interface ToolExecutorConfig {
 	tools: ToolRegistryContract
 	runId: RunId
 	workingDirectory: string
+	/** See `ToolContext.additionalDirectories`. */
+	additionalDirectories?: readonly string[]
 	/**
 	 * Read LIVE, not frozen at run start.
 	 *
@@ -319,6 +323,13 @@ export interface ToolExecutorConfig {
 	 * that fallback is a lie rather than a lesser version.
 	 */
 	backgroundJobs?: BackgroundJobRegistry
+	/**
+	 * Which owner the run's jobs are bound to. The run id by default, which
+	 * scopes them to the run; a host that wants jobs to outlive a turn (a
+	 * dev server started in one, read in the next) binds them to its
+	 * session and stops them itself when the session ends.
+	 */
+	backgroundJobOwner?: string
 
 	/**
 	 * Where the `skill` tool reads from.
@@ -1175,6 +1186,9 @@ export class ToolExecutor {
 		const context: ToolContext = {
 			runId: this.config.runId,
 			workingDirectory: this.config.workingDirectory,
+			...(this.config.additionalDirectories?.length
+				? { additionalDirectories: this.config.additionalDirectories }
+				: {}),
 			abortSignal: this.config.abortSignal,
 			env: this.config.env,
 			log: (level, message) => this.log[level](message),
@@ -1219,12 +1233,38 @@ export class ToolExecutor {
 			// that its foreground work would use. A sandbox-aware persistent
 			// process capability needs its own execution seam; until one exists,
 			// the safe composition is to withhold this host capability entirely.
-			...(this.config.backgroundJobs && !this.config.sandbox
+			//
+			// That seam now exists: a sandbox that can `spawnDetached` starts
+			// the job inside its boundary, and the registry only keeps it. A
+			// sandbox without it still withholds the capability.
+			...(this.config.backgroundJobs &&
+			(!this.config.sandbox || this.config.sandbox.spawnDetached !== undefined)
 				? {
-						backgroundJobs: bindOwner(this.config.backgroundJobs, this.config.runId, {
-							workingDirectory: this.config.workingDirectory,
-							env: this.config.env,
-						}),
+						backgroundJobs: bindOwner(
+							this.config.backgroundJobs,
+							this.config.backgroundJobOwner ?? this.config.runId,
+							{
+								workingDirectory: this.config.workingDirectory,
+								env: this.config.env,
+								...(this.config.sandbox?.spawnDetached
+									? {
+											spawn: (job: {
+												readonly command: string
+												readonly workingDirectory: string
+												readonly env?: Record<string, string>
+											}): JobProcess =>
+												(this.config.sandbox as Sandbox).spawnDetached?.(
+													'/bin/sh',
+													['-c', job.command],
+													{
+														cwd: job.workingDirectory,
+														...(job.env ? { env: job.env } : {}),
+													},
+												) as JobProcess,
+										}
+									: {}),
+							},
+						),
 					}
 				: {}),
 			...(this.parentSpan ? { parentSpan: this.parentSpan } : {}),
@@ -1239,6 +1279,9 @@ export class ToolExecutor {
 		settleProgress: () => Promise<void>,
 		preparedCall?: PreparedDirectCall,
 	): Promise<ToolCallOutcome> {
+		if (this.config.abortSignal.aborted) {
+			return this.recordCancelledBeforeExecution(toolCall.id, toolCall.function.name, {})
+		}
 		if (preparedCall?.kind === 'synthetic') {
 			return this.recordSyntheticPreparation(preparedCall)
 		}
@@ -1336,7 +1379,15 @@ export class ToolExecutor {
 
 			input = resolved.input
 
-			const preOutcome = await this.runPreToolHook(toolName, input)
+			let preOutcome: PreToolHookOutcome
+			try {
+				preOutcome = await this.runPreToolHook(toolName, input)
+			} catch (error) {
+				if (!this.config.abortSignal.aborted) throw error
+				// A later call's interrupted preparation must not reject the batch
+				// that already holds an earlier call's settled side-effect receipt.
+				return this.recordCancelledBeforeExecution(toolCall.id, toolName, input)
+			}
 			if (preOutcome.kind === 'skip' || preOutcome.kind === 'error') {
 				return this.recordSyntheticHookOutcome(toolCall.id, toolName, preOutcome.input, preOutcome)
 			}
@@ -1443,6 +1494,7 @@ export class ToolExecutor {
 			...this.config.toolRetryBackoff,
 		}
 		for (let attempt = 1; ; attempt++) {
+			if (this.config.abortSignal.aborted) break
 			// A missing file will not appear on the second attempt; burning
 			// the budget on it only delays the error the model needs to see.
 			const toolWants = !result.success && result.retryable === true
@@ -1510,23 +1562,23 @@ export class ToolExecutor {
 		const postOverride = post.override
 		let output =
 			postOverride?.output ?? (result.success ? this.maybeCompress(toolName, rawOutput) : rawOutput)
-		const selectedContent = postOverride?.isError
+		let selectedContent = postOverride?.isError
 			? undefined
 			: (postOverride?.content ?? result.content)
-		const maxToolOutputChars = this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS
-
-		// If the text preview forces rich content out, say so inside the SAME
-		// budget. Appending this after truncation made the diagnostic itself a
-		// cap bypass; selecting a post-hook override after truncation was a
-		// larger bypass that could replace a bounded result with anything.
-		if (
-			maxToolOutputChars > 0 &&
-			output.length > maxToolOutputChars &&
-			selectedContent !== undefined
-		) {
-			const dropped = describeDroppedContent(selectedContent)
-			if (dropped) output = `${output}\n\n${dropped}`
+		if (postOverride && !postOverride.isError && postOverride.content === undefined) {
+			// A text redaction must reach both text channels. Only the image or
+			// document blocks survive implicitly; explicit replacement content
+			// remains the hook's complete model-visible decision.
+			if (typeof selectedContent === 'string') selectedContent = postOverride.output
+			else if (selectedContent) {
+				selectedContent = [
+					{ type: 'text', text: postOverride.output },
+					...selectedContent.filter((block) => block.type !== 'text'),
+				]
+			}
 		}
+		const maxToolOutputChars = this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS
+		const sourceOutput = output
 
 		// Compression is opportunistic and shell-only; the budget is the
 		// hard bound that applies to every final tool result, including a
@@ -1553,6 +1605,10 @@ export class ToolExecutor {
 			})
 		}
 		output = budgeted.output
+		const modelContent =
+			selectedContent === undefined
+				? undefined
+				: this.budgetContent(selectedContent, toolName, toolCall.id, { sourceOutput, budgeted })
 
 		// 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
@@ -1562,6 +1618,9 @@ export class ToolExecutor {
 
 		if (this.workingStateManager) {
 			extractFromToolResult(this.workingStateManager, toolName, output, effectiveIsError)
+			for (const pin of this.config.abortSignal.aborted ? [] : (result.workingState ?? [])) {
+				this.workingStateManager.pin(pin.key, pin.text, toolName)
+			}
 		}
 
 		if (result.success) {
@@ -1576,7 +1635,7 @@ export class ToolExecutor {
 				[NAMZU.RUN_ID]: this.config.runId,
 				[GENAI.TOOL_NAME]: toolName,
 				'namzu.duration_ms': durationMs,
-				'exception.message': result.error ?? 'unknown',
+				'exception.message': postOverride ? output : (result.error ?? 'unknown'),
 			})
 		}
 
@@ -1615,11 +1674,6 @@ export class ToolExecutor {
 			result,
 		})
 
-		const resolveContent = (): { content?: ToolResultContent } => {
-			if (budgeted.truncated || selectedContent === undefined) return {}
-			return { content: this.budgetContent(selectedContent, toolName) }
-		}
-
 		return {
 			toolCallId: toolCall.id,
 			toolName,
@@ -1629,13 +1683,12 @@ export class ToolExecutor {
 			//
 			// An ERROR override drops it: the payload is no longer the tool's,
 			// and shipping an image beside a failure message describes something
-			// the model was just told did not happen. A spilled preview drops it
-			// for the same reason.
+			// the model was just told did not happen.
 			//
 			// A REPLACE keeps it, because the common case is redacting text from
 			// a result whose image is unaffected — and a hook that needs it gone
 			// says so with `content`, which wins over both.
-			...resolveContent(),
+			...(modelContent !== undefined ? { content: modelContent } : {}),
 		}
 	}
 
@@ -2108,6 +2161,7 @@ export class ToolExecutor {
 						output: `Error: ${result.message}`,
 					}
 				case 'retry':
+				case 'annotate':
 				// There is no result to replace yet. Rejecting loudly beats
 				// silently ignoring it: a hook author who returned this here
 				// meant to redact something and would otherwise watch the secret
@@ -2327,17 +2381,33 @@ export class ToolExecutor {
 		toolResult: ToolResult,
 	): Promise<{ override: PostToolOverride | null; retry: boolean }> {
 		if (!this.config.pluginManager) return { override: null, retry: false }
-		const results = await this.config.pluginManager.executeHooks(
-			'post_tool_use',
-			{
-				runId: this.config.runId,
-				toolName,
-				toolInput: input,
-				toolResult,
-				signal: this.config.abortSignal,
-			},
-			this.emitEvent,
-		)
+		let results: PluginHookResult[]
+		try {
+			results = await this.config.pluginManager.executeHooks(
+				'post_tool_use',
+				{
+					runId: this.config.runId,
+					toolName,
+					toolInput: input,
+					toolResult,
+					signal: this.config.abortSignal,
+				},
+				this.emitEvent,
+			)
+		} catch (error) {
+			if (!this.config.abortSignal.aborted) throw error
+			// The tool has already returned. Cancellation of a later redaction
+			// cannot erase that execution or turn it into a safe-to-repeat call.
+			// Withhold both channels until their post-tool policy has completed.
+			const outcome = toolResult.success
+				? 'reported success before cancellation. The call already executed.'
+				: 'reported failure while cancellation was in progress. Side effects are possible.'
+			const output = `Tool "${toolName}" ${outcome} Output withheld because post-tool review was interrupted. Inspect external state before any retry.`
+			return {
+				override: { output, content: output, isError: !toolResult.success },
+				retry: false,
+			}
+		}
 		let override: PostToolOverride | null = null
 		let retry = false
 		for (const result of results) {
@@ -2368,6 +2438,7 @@ export class ToolExecutor {
 					continue
 				case 'skip':
 				case 'modify':
+				case 'annotate':
 					throw new Error(
 						`Plugin hook post_tool_use returned unsupported action '${result.action}' for tool ${toolName}`,
 					)
@@ -2441,6 +2512,18 @@ export class ToolExecutor {
 		return { toolCallId: toolCall.id, toolName, output, isError: true }
 	}
 
+	private recordCancelledBeforeExecution(
+		toolCallId: string,
+		toolName: string,
+		input: unknown,
+	): Promise<ToolCallOutcome> {
+		const reason = abortReasonText(this.config.abortSignal.reason)
+		return this.recordSyntheticHookOutcome(toolCallId, toolName, input, {
+			kind: 'error',
+			output: `Tool "${toolName}" was not started because the run was cancelled${reason ? `: ${reason}` : '.'}`,
+		})
+	}
+
 	private async recordSyntheticHookOutcome(
 		toolCallId: string,
 		toolName: string,
@@ -2493,42 +2576,69 @@ export class ToolExecutor {
 	}
 
 	/**
-	 * Bound the rich channel, or leave it alone when no cap is configured.
-	 *
-	 * Refused whole rather than trimmed: half a base64 payload is not a
-	 * smaller image, it is a corrupt one, and a driver handed it would
-	 * either fail the request or show the model noise. The text half stays
-	 * untouched, so the result still says what happened — and the
-	 * replacement names what was withheld and how big it was, which is what
-	 * lets the agent ask for a smaller region instead of retrying the same
-	 * call.
+	 * The host preview and model text may differ; each gets its own text
+	 * budget. Rich bytes are measured separately and withheld whole when
+	 * over their cap, with a notice inside the model text's same hard bound.
 	 */
 	private budgetContent(
-		content: import('../../types/message/index.js').ToolResultContent,
+		content: ToolResultContent,
 		toolName: string,
-	): import('../../types/message/index.js').ToolResultContent {
+		toolUseId: string,
+		host: { sourceOutput: string; budgeted: ToolOutputBudgetResult },
+	): ToolResultContent {
 		const cap = this.config.maxToolContentBytes ?? 0
-		if (cap <= 0) return content
-
 		const size = measureContentBytes(content)
-		if (size <= cap) return content
-
-		this.log.warn('Tool result content exceeded the rich-content budget', {
-			[NAMZU.RUN_ID]: this.config.runId,
-			[GENAI.TOOL_NAME]: toolName,
-			'namzu.runtime.content_bytes': size,
-			'namzu.runtime.cap': cap,
-		})
-
-		const described = describeDroppedContent(content)
+		const richWithheld = cap > 0 && size > cap
+		const text =
+			typeof content === 'string'
+				? content
+				: content.flatMap((block) => (block.type === 'text' ? [block.text] : [])).join('\n')
+		const notice = richWithheld
+			? `[rich content withheld: ${size} base64 chars exceeds this run's ${cap} cap] ${describeDroppedContent(content) ?? ''}`
+			: undefined
+		if (richWithheld) {
+			this.log.warn('Tool result content exceeded the rich-content budget', {
+				[NAMZU.RUN_ID]: this.config.runId,
+				[GENAI.TOOL_NAME]: toolName,
+				'namzu.runtime.content_bytes': size,
+				'namzu.runtime.cap': cap,
+			})
+		}
+		const budgeted =
+			text === host.sourceOutput && !notice
+				? host.budgeted
+				: applyToolOutputBudget({
+						toolName,
+						toolUseId,
+						output: text,
+						maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+						...(notice ? { notice } : {}),
+						// A tool may return different host and model text. They must
+						// never compete for the same exclusive spill filename.
+						spillDir: this.config.toolOutputDir
+							? join(this.config.toolOutputDir, 'content')
+							: undefined,
+						onError: (message) =>
+							this.log.warn('Failed to spill oversized model tool content', {
+								[NAMZU.RUN_ID]: this.config.runId,
+								[GENAI.TOOL_NAME]: toolName,
+								'exception.message': message,
+							}),
+					})
+		if (budgeted.truncated && budgeted !== host.budgeted) {
+			this.log.warn('Model tool text exceeded the model-visible budget', {
+				[NAMZU.RUN_ID]: this.config.runId,
+				[GENAI.TOOL_NAME]: toolName,
+				'namzu.runtime.original_length': budgeted.originalLength,
+				'namzu.runtime.spill_path': budgeted.spillPath,
+			})
+		}
+		if (!budgeted.truncated && !richWithheld) return content
+		if (typeof content === 'string') return budgeted.output
 		return [
-			{
-				type: 'text',
-				text: `[rich content withheld: ${size} base64 chars exceeds this run's ${cap} cap${
-					described ? ` — ${described}` : ''
-				}]`,
-			},
-		] as import('../../types/message/index.js').ToolResultContent
+			...(budgeted.output ? [{ type: 'text' as const, text: budgeted.output }] : []),
+			...(richWithheld ? [] : content.filter((block) => block.type !== 'text')),
+		]
 	}
 
 	private maybeCompress(toolName: string, output: string): string {

package/src/runtime/query/guard.ts

@@ -110,6 +110,14 @@ export class GuardCoordinator {
 		}
 
 		const limitResult = checkLimitsDetailed(this.limitConfig, limitState)
+		if (!abortSignal.aborted && runMgr.budget && runMgr.budget.remaining <= 0) {
+			return {
+				shouldStop: true,
+				forceFinalize: false,
+				stopReason: 'token_budget',
+				isCancelled: false,
+			}
+		}
 
 		if (limitResult.type === 'hard_stop') {
 			return {