@namzu/sdk 35.0.0 → 36.0.0

package/src/public-runtime.ts

@@ -649,8 +649,9 @@ export {
 	LocalSandboxProvider,
 	missingIsolation,
 	SandboxProviderFactory,
+	walkFilesViaExec,
 } from './sandbox/index.js'
-export type { LocalSandboxProviderOptions } from './sandbox/index.js'
+export type { LocalSandboxProviderOptions, SandboxFileWalkExec } from './sandbox/index.js'
 
 // The classified provider-failure surface: a driver states what went wrong
 // first-hand, and the run boundary reads it to choose between a pause and a

package/src/runtime/query/executor.ts

@@ -1279,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)
 		}
@@ -1376,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)
 			}
@@ -1483,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
@@ -1606,7 +1618,7 @@ export class ToolExecutor {
 
 		if (this.workingStateManager) {
 			extractFromToolResult(this.workingStateManager, toolName, output, effectiveIsError)
-			for (const pin of result.workingState ?? []) {
+			for (const pin of this.config.abortSignal.aborted ? [] : (result.workingState ?? [])) {
 				this.workingStateManager.pin(pin.key, pin.text, toolName)
 			}
 		}
@@ -1623,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'),
 			})
 		}
 
@@ -2369,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) {
@@ -2484,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,

package/src/runtime/query/index.ts

@@ -671,6 +671,13 @@ export interface QueryParams {
 	 * started. See `BaseAgentConfig.inboundMessages` for what it closes.
 	 */
 	inboundMessages?: () => import('../../types/message/index.js').Message[]
+	/**
+	 * Wake a background-task hold when operator input is available, without draining it.
+	 * Resolve immediately if input is already pending. Otherwise wait for its arrival;
+	 * the supplied signal ends the wait and must release any listeners. Messages are
+	 * still consumed only through `inboundMessages` at a provider-valid boundary.
+	 */
+	waitForInbound?: (signal: AbortSignal) => Promise<void>
 
 	/**
 	 * Live project policy for this run. Unlike `inboundMessages`, snapshot
@@ -1963,6 +1970,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		...(params.repeatCallAdvisory === false ? {} : { repeatCalls: new RepeatCallTracker() }),
 		compactionConfig,
 		...(params.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
+		...(params.waitForInbound ? { waitForInbound: params.waitForInbound } : {}),
 		...(params.projectInstructionContext
 			? { projectInstructionContext: params.projectInstructionContext }
 			: {}),

package/src/runtime/query/iteration/index.ts

@@ -1450,9 +1450,9 @@ export class IterationOrchestrator {
 	/**
 	 * Hold the run open for a worker that has not finished, and deliver it.
 	 *
-	 * Returns whether a completion arrived and was put in the transcript — the
-	 * caller continues the loop on `true`, so the model gets a turn in which to
-	 * USE the result. That turn is the entire justification for waiting, which
+	 * Returns whether a completion or operator message entered the transcript —
+	 * the caller continues on `true`, so the model gets a turn to respond.
+	 * That turn is the entire justification for waiting, which
 	 * is why only the exits that can still take one call this.
 	 *
 	 * Bounded by `settleGraceMs` and by `maxIterations`, so a worker that never
@@ -1473,14 +1473,34 @@ export class IterationOrchestrator {
 			[NAMZU.ITERATION]: iterationNum,
 			'namzu.runtime.grace_ms': graceMs,
 		})
-		await this.ctx.completionInbox.waitForArrival(graceMs)
+		// User input releases this wait without cancelling any child. Both waits
+		// share a disposable signal so the losing arrival listener cannot leak.
+		const waiting = new AbortController()
+		const runSignal = this.ctx.abortController.signal
+		const cancelWait = () => waiting.abort(runSignal.reason)
+		runSignal.addEventListener('abort', cancelWait, { once: true })
+		if (runSignal.aborted) cancelWait()
+		try {
+			await Promise.race([
+				this.ctx.completionInbox.waitForArrival(graceMs, waiting.signal),
+				...(this.ctx.waitForInbound ? [this.ctx.waitForInbound(waiting.signal)] : []),
+			])
+		} catch (error) {
+			if (!runSignal.aborted) throw error
+		} finally {
+			waiting.abort()
+			runSignal.removeEventListener('abort', cancelWait)
+		}
+		runSignal.throwIfAborted()
 
 		const arrived = this.ctx.completionInbox.drain()
-		if (arrived.length === 0) return false
-
-		this.ctx.runMgr.pushMessage(
-			createRuntimeContextMessage(formatCompletionNotification(arrived), 'task-completion'),
-		)
+		if (arrived.length > 0) {
+			this.ctx.runMgr.pushMessage(
+				createRuntimeContextMessage(formatCompletionNotification(arrived), 'task-completion'),
+			)
+		}
+		const inbound = this.deliverInbound()
+		if (arrived.length === 0 && inbound === 0) return false
 		await this.ctx.emitEvent({
 			type: 'iteration_completed',
 			runId: this.ctx.runMgr.id,

package/src/runtime/query/iteration/phases/context.ts

@@ -188,6 +188,8 @@ export interface IterationContext {
 	 * after tool results and before the next turn.
 	 */
 	readonly inboundMessages?: () => readonly import('../../../../types/message/index.js').Message[]
+	/** Observes pending input without draining it; abort releases the waiter. */
+	readonly waitForInbound?: (signal: AbortSignal) => Promise<void>
 
 	/** Live project policy; separate from human inbound continuation. */
 	readonly projectInstructionContext?: ProjectInstructionContext

package/src/runtime/query/iteration/stream-turn.ts

@@ -518,11 +518,15 @@ export async function* streamProviderTurn(
 		streamCause = err
 	} finally {
 		if (onAbort) signal?.removeEventListener('abort', onAbort)
-		// Release the underlying connection on every exit (natural end, error,
-		// or abort). `for await` did this implicitly on natural completion; the
-		// manual drive must do it explicitly. `.return()` on an already-finished
-		// provider generator is a no-op.
-		await it.return?.().catch(() => {})
+		// Request cleanup on every exit, but never wait for a blocked provider's
+		// pending next(). An async generator queues return() behind that pull;
+		// awaiting it would undo the cancellation race above. Provider metering
+		// independently records cancellation and any already-issued late receipt.
+		try {
+			void it.return?.().catch(() => {})
+		} catch {
+			// Cleanup cannot replace the original stream outcome.
+		}
 	}
 
 	// Flush any tool buckets the provider failed to close (no toolCallEnd

package/src/runtime/query/prompt.ts

@@ -41,7 +41,8 @@ export interface PromptBuilderConfig {
 	contributions?: PromptContributionRegistry
 }
 
-function buildEnvContext(workingDirectory: string, runtimeContext?: AgentRuntimeContext): string {
+function buildEnvContext(workingDirectory: string, config: PromptBuilderConfig): string {
+	const { runtimeContext, tools, allowedTools } = config
 	const lines = [
 		`<env>
 Working directory: ${workingDirectory}
@@ -69,7 +70,23 @@ Platform: ${process.platform}`,
 
 	lines.push(`</env>
 
-IMPORTANT: Always use absolute paths based on the working directory above. Before reading a file, use the glob tool to discover actual file paths — never guess or hallucinate paths.`)
+Resolve relative paths against the working directory above; use supplied absolute paths as given.`)
+
+	if (hasFilesystemTools(tools, allowedTools)) {
+		lines.push(
+			'When file contents are needed, read known file paths directly. Discover unknown paths with available filesystem tools using targeted directories and patterns.',
+		)
+		const canGlob =
+			tools.has('glob') &&
+			(!allowedTools || allowedTools.includes('glob')) &&
+			tools.getAvailability('glob') === 'active'
+		lines.push(
+			canGlob
+				? "For an immediate directory overview, use glob with pattern '*' or an available directory listing tool. Use '**' only when recursive discovery is needed."
+				: 'For an immediate directory overview, use an available directory listing tool.',
+			"Keep discovery within the task's scope; do not recursively inventory unrelated home directories or cache trees.",
+		)
+	}
 
 	return lines.join('\n')
 }
@@ -224,7 +241,7 @@ export class PromptBuilder {
 				hasFilesystemTools(this.config.tools, this.config.allowedTools) ||
 				Boolean(this.config.runtimeContext)
 			if (shouldIncludeEnv) {
-				parts.push(buildEnvContext(workingDirectory, this.config.runtimeContext))
+				parts.push(buildEnvContext(workingDirectory, this.config))
 			}
 		}
 
@@ -290,7 +307,7 @@ export class PromptBuilder {
 				hasFilesystemTools(this.config.tools, this.config.allowedTools) ||
 				Boolean(this.config.runtimeContext)
 			if (shouldIncludeEnv) {
-				dynamicParts.push(buildEnvContext(workingDirectory, this.config.runtimeContext))
+				dynamicParts.push(buildEnvContext(workingDirectory, this.config))
 			}
 		}
 

package/src/sandbox/file-walk-program.ts

@@ -0,0 +1,93 @@
+/** Stable guest code: host bundlers must never rewrite a function we serialize. */
+export const FILE_WALK_PROGRAM = String.raw`
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const plan = JSON.parse(process.argv[1]);
+const missing = error => ['ENOENT', 'ENOTDIR'].includes(error.code);
+const write = async value => {
+  if (!process.stdout.write(JSON.stringify(value) + '\n')) {
+    await new Promise(resolve => process.stdout.once('drain', resolve));
+  }
+};
+const visit = count => {
+  if (count > plan.maxVisitedEntries) {
+    throw Object.assign(new Error('File search stopped after examining ' + plan.maxVisitedEntries + ' entries; narrow its root or pattern.'), {code:'ERR_FILE_WALK_LIMIT'});
+  }
+};
+const patterns = plan.patterns.map(set => set.map(part =>
+  typeof part === 'object' && part !== null ? new RegExp(part.source, part.flags + 's') : part));
+const canDescend = relative => patterns.some(pattern => {
+  const closure = states => {
+    for (const index of states) if (pattern[index] === null) states.add(index + 1);
+    return states;
+  };
+  let states = closure(new Set([0]));
+  for (const name of relative.split('/')) {
+    const next = new Set();
+    for (const index of states) {
+      const segment = pattern[index];
+      if (segment === null) {
+        if (plan.includeHidden || !name.startsWith('.')) next.add(index);
+      } else if (typeof segment === 'string' ? segment === name : segment?.test(name)) next.add(index + 1);
+    }
+    states = closure(next);
+    if (states.size === 0) return false;
+  }
+  return [...states].some(index => index < pattern.length);
+});
+async function run() {
+  const stack = [];
+  let visited = 0;
+  let emitted = 0;
+  const matchers = plan.expressions.map(({source, flags}) => new RegExp(source, flags + 's'));
+  const maxDepth = plan.maxDepth === null ? Infinity : plan.maxDepth;
+  const open = async (absolute, relative, depth) => {
+    try { stack.push({dir: await fs.opendir(absolute), relative, depth}); }
+    catch (error) { if (!missing(error)) throw error; }
+  };
+  try {
+    if (plan.patterns.length === 0) return;
+    let canonicalRoot;
+    try { canonicalRoot = await fs.realpath(plan.root); }
+    catch (error) { if (missing(error)) return; throw error; }
+    if (canonicalRoot !== path.resolve(plan.root)) throw new Error('File walk root follows a symbolic link; use its authorized real directory');
+    let start = plan.root;
+    for (const part of plan.prefix) {
+      start = path.join(start, part);
+      let info;
+      try { info = await fs.lstat(start); }
+      catch (error) { if (missing(error)) return; throw error; }
+      visit(++visited);
+      if (!info.isDirectory()) return;
+    }
+    if (plan.prefix.length >= maxDepth) return;
+    await open(start, plan.prefix.join('/'), plan.prefix.length);
+    while (stack.length) {
+      const frame = stack[stack.length - 1];
+      const entry = await frame.dir.read();
+      if (!entry) { stack.pop(); await frame.dir.close(); continue; }
+      visit(++visited);
+      const relative = frame.relative ? frame.relative + '/' + entry.name : entry.name;
+      const absolute = path.join(plan.root, relative);
+      const depth = frame.depth + 1;
+      if (entry.isDirectory()) {
+        if (depth < maxDepth && canDescend(relative)) await open(absolute, relative, depth);
+        continue;
+      }
+      if (!entry.isFile() || !matchers.some(matcher => matcher.test(relative))) continue;
+      let info;
+      try { info = await fs.lstat(absolute); }
+      catch (error) { if (missing(error)) continue; throw error; }
+      if (!info.isFile()) continue;
+      await write({type:'entry', path:absolute, size:info.size});
+      if (++emitted >= plan.maxEntries) return;
+    }
+  } finally {
+    for (const {dir} of stack.reverse()) await dir.close();
+  }
+}
+run().then(
+  () => write({type:'done'}),
+  async error => { await write({type:'error', message:error.message, code:error.code}); process.exitCode = 1; },
+);
+`