@namzu/sdk 59.0.0 → 60.1.0

package/src/runtime/query/executor.ts

@@ -71,6 +71,7 @@ import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
 import { parseStructuredResultJson } from '../../utils/structured-result-json.js'
 import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/registry.js'
+import { type BatchDetach, stillRunningResult } from './detached-calls.js'
 import {
 	type ToolAdmissionHost,
 	formatFailedToolOutput,
@@ -412,6 +413,8 @@ export interface ToolExecutorConfig {
 	 * recorder gets no hold rather than a marking call that goes nowhere.
 	 */
 	onJobAwaited?: (id: string) => void
+	/** Where a tool result that handed the model a job's exit says so; see `ToolContext.backgroundJobs.markCollected`. */
+	onJobCollected?: (id: string) => void
 	/** The longest a monitor may live in this turn; see `QueryParams.monitorTimeoutCapMs`. */
 	monitorTimeoutCapMs?: number
 	/**
@@ -1429,6 +1432,7 @@ export class ToolExecutor {
 		preparedBatch?: PreparedToolBatch,
 		declines?: ToolCallDeclines,
 		review?: ReviewedExecution,
+		detach?: BatchDetach,
 	): Promise<ToolExecutionBatch> {
 		const toolCalls = response.message.toolCalls
 		if (!toolCalls) {
@@ -1455,9 +1459,9 @@ export class ToolExecutor {
 			if (refusal) {
 				const refused = new Map(denials)
 				for (const call of toolCalls) if (!refused.has(call.id)) refused.set(call.id, refusal)
-				return await this.runBatch(toolCalls, refused, prior, owned, declines, review)
+				return await this.runBatch(toolCalls, refused, prior, owned, declines, review, detach)
 			}
-			return await this.runBatch(toolCalls, denials, prior, owned, declines, review)
+			return await this.runBatch(toolCalls, denials, prior, owned, declines, review, detach)
 		} finally {
 			// Cleared so a later single execution outside a batch resolves
 			// live rather than inheriting the last batch's sample.
@@ -1472,6 +1476,7 @@ export class ToolExecutor {
 		preparedBatch?: OwnedPreparedToolBatch,
 		declines?: ToolCallDeclines,
 		review?: ReviewedExecution,
+		detach?: BatchDetach,
 	): Promise<ToolExecutionBatch> {
 		this.log.debug('Executing tool batch', {
 			[NAMZU.TURN_ID]: this.config.turnId,
@@ -1507,6 +1512,17 @@ export class ToolExecutor {
 		// (which let the last writer clobber the rest). Results are written by
 		// index to preserve the original tool-call order.
 		const results: ToolCallOutcome[] = new Array(toolCalls.length)
+		// Calls handed back to the model as still running (see `detach`), and the
+		// ones among them whose real outcome has been reported.
+		const handedBack = new Set<string>()
+		const reported = new Set<string>()
+		// Calls that have begun; one queued behind a serial or barrier call has not.
+		const started = new Set<string>()
+		const reportLate = (outcome: ToolCallOutcome): void => {
+			if (reported.has(outcome.toolCallId)) return
+			reported.add(outcome.toolCallId)
+			detach?.calls.settle(outcome)
+		}
 		const parallel: Promise<void>[] = []
 		let serial: Promise<void> = Promise.resolve()
 		let barrier: Promise<void> | undefined
@@ -1623,13 +1639,32 @@ export class ToolExecutor {
 			}
 			const run = async () => {
 				try {
-					results[i] = await this.executeSingle(
-						toolCall,
-						ctx,
-						recordObservation,
-						() => progress.close(),
-						preparedCall,
-					)
+					let outcome: ToolCallOutcome
+					started.add(toolCall.id)
+					try {
+						outcome = await this.executeSingle(
+							toolCall,
+							ctx,
+							recordObservation,
+							() => progress.close(),
+							preparedCall,
+						)
+					} catch (error) {
+						// A call already answered with the placeholder has no batch
+						// left to fail; its failure is its outcome.
+						if (!handedBack.has(toolCall.id)) throw error
+						reportLate({
+							toolCallId: toolCall.id,
+							toolName: toolCall.function.name,
+							output: `Error: Tool "${toolCall.function.name}" did not complete — ${
+								error instanceof Error ? error.message : String(error)
+							}`,
+							isError: true,
+						})
+						return
+					}
+					if (handedBack.has(toolCall.id)) reportLate(outcome)
+					else results[i] = outcome
 				} finally {
 					await progress.close()
 				}
@@ -1664,7 +1699,46 @@ export class ToolExecutor {
 			schedule(safe ? gated : run, safe, isBarrier)
 		})
 		if (review) await this.walkReviewed(reviewUnits, results, review)
-		await Promise.all([...parallel, serial])
+		const completion = Promise.all([...parallel, serial])
+		if (detach && !review) {
+			const first = await Promise.race([
+				completion.then(() => 'finished' as const),
+				detach.requested.then(() => 'requested' as const),
+			])
+			if (first === 'requested' && toolCalls.some((_, i) => results[i] === undefined)) {
+				// The operator wrote while calls were still running. Answer each
+				// unfinished call with the placeholder so the model can read the
+				// message now; the calls keep running and report themselves.
+				toolCalls.forEach((toolCall, i) => {
+					if (results[i]) return
+					handedBack.add(toolCall.id)
+					detach.calls.begin(toolCall.id, toolCall.function.name)
+					results[i] = {
+						toolCallId: toolCall.id,
+						toolName: toolCall.function.name,
+						output: stillRunningResult(toolCall.function.name, started.has(toolCall.id)),
+						isError: false,
+					}
+				})
+				const settleRest = (): void => {
+					for (const id of handedBack) {
+						if (reported.has(id)) continue
+						const name = toolCalls.find((call) => call.id === id)?.function.name ?? 'tool'
+						reportLate({
+							toolCallId: id,
+							toolName: name,
+							output: `Error: Tool "${name}" did not complete — the batch failed before it produced a result.`,
+							isError: true,
+						})
+					}
+				}
+				completion.then(settleRest, settleRest)
+			} else {
+				await completion
+			}
+		} else {
+			await completion
+		}
 
 		// Whatever failed above left a hole in `results`; fill every one, so
 		// the invariant holds by construction rather than by everything having
@@ -2205,6 +2279,13 @@ export class ToolExecutor {
 			...(this.config.additionalDirectories?.length
 				? { additionalDirectories: this.config.additionalDirectories }
 				: {}),
+			...(this.config.authorizationGate
+				? {
+						readDenied: (absolutePath: string) =>
+							this.evaluatePreparedAuthorization('read', { path: absolutePath })?.decision ===
+							'deny',
+					}
+				: {}),
 			...(this.outputDirectory()
 				? { retainedOutputDirectory: this.outputDirectory() as string }
 				: {}),
@@ -2300,6 +2381,7 @@ export class ToolExecutor {
 										}
 									: {}),
 								...(this.config.onJobAwaited ? { onAwaited: this.config.onJobAwaited } : {}),
+								...(this.config.onJobCollected ? { onCollected: this.config.onJobCollected } : {}),
 								...(this.config.monitorTimeoutCapMs !== undefined
 									? { monitorTimeoutCapMs: this.config.monitorTimeoutCapMs }
 									: {}),

package/src/runtime/query/index.ts

@@ -113,6 +113,7 @@ import {
 	SandboxAcquisitionStopped,
 	createDeferredSandbox,
 } from './deferred-sandbox.js'
+import { DetachedCalls } from './detached-calls.js'
 import type { EventTranslator } from './events.js'
 import { finalizeTurn } from './finalize-turn.js'
 import { GuardCoordinator } from './guard.js'
@@ -150,6 +151,7 @@ import { acquireSandbox } from './sandbox-lifecycle.js'
 import {
 	SteeringBinding,
 	type SteeringChannel,
+	formatJobExitNotice,
 	formatMonitorEnd,
 	formatMonitorEvent,
 	isOperatorUserMessage,
@@ -375,6 +377,20 @@ export interface QueryParams {
 	 * before; `0` stops at the first cut-off.
 	 */
 	maxOutputContinuations?: number
+	/**
+	 * What the turn does when the model declines to answer (its provider
+	 * finished the reply as a refusal or a safety block).
+	 *
+	 * `'auto'` (the default) re-runs the refused request once on another model
+	 * of the same provider (the one the provider recommends, or the one its
+	 * own fallback order names) and keeps that model for the rest of the turn;
+	 * a `model_refusal` event names the swap so a host can keep it for later
+	 * turns. `'off'` never changes the model: the turn tries once more on the
+	 * same model only when the refused reply had partial output, and otherwise
+	 * settles with stop reason `'refused'`. A refused reply is never added to
+	 * the history sent next.
+	 */
+	refusalFallback?: 'auto' | 'off'
 
 	/**
 	 * Model-visible size cap for a single tool result. Over-budget output is
@@ -808,6 +824,28 @@ export interface QueryParams {
 	 */
 	waitForInbound?: (signal: AbortSignal) => Promise<void>
 
+	/**
+	 * Answer the operator while a long tool call is still running.
+	 *
+	 * Default off. When on, and `waitForOperator` reports the operator wrote while
+	 * a batch had been running for two seconds, each call not yet finished is answered with a "still running"
+	 * placeholder so the model can read the message and reply at once. The
+	 * calls are not interrupted and not repeated: their real results reach the
+	 * model later in a message that names each call, and the turn is held open
+	 * for them like any outstanding work. The host's wake is then also consulted
+	 * during tool batches, not only when the turn would otherwise end. Ignored
+	 * under per-call review, where the batch is waiting on a person.
+	 */
+	answerWhileCallsRun?: boolean
+
+	/**
+	 * Resolve when the operator wrote, and for no other reason. It is what
+	 * `answerWhileCallsRun` listens to: a notice from a child agent or mail from
+	 * a peer also wakes `waitForInbound`, but must not hand a running call back.
+	 * Abort removes the waiter, as for `waitForInbound`.
+	 */
+	waitForOperator?: (signal: AbortSignal) => Promise<void>
+
 	/** Durable host input: normal append, flush and exact acknowledgement before inference. Requires sessionLog. */
 	durableInbound?: DurableInboundSource
 
@@ -1484,6 +1522,21 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				)
 			: undefined
 		awaitedJobs?.attach()
+		// A tool result has handed the model this job's exit: the notice that
+		// would announce the same exit is taken back, and the host is told it was
+		// delivered so the session does not wake the model for it either.
+		const collectJob = (id: string): void => {
+			const withdrawn = jobNotices?.withdraw(id) ?? false
+			awaitedJobs?.collected(id)
+			if (!pendingJobNoticeIds.delete(id) && !withdrawn) return
+			try {
+				params.onJobNoticeDelivered?.([id])
+			} catch (error) {
+				ctx.log.warn('A background job notice observer failed', {
+					'exception.message': error instanceof Error ? error.message : String(error),
+				})
+			}
+		}
 
 		// Turn-scoped, like `toolGrants` below: what a skill loaded in this turn
 		// pre-approves ends with the turn. Shared by the executor, where the
@@ -1513,6 +1566,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				...(params.backgroundJobs ? { backgroundJobs: params.backgroundJobs } : {}),
 				...(params.backgroundJobOwner ? { backgroundJobOwner: params.backgroundJobOwner } : {}),
 				...(awaitedJobs ? { onJobAwaited: (id: string) => awaitedJobs.expect(id) } : {}),
+				...(awaitedJobs ? { onJobCollected: collectJob } : {}),
 				...(awaitedJobs ? { onMonitorStarted: (id: string) => awaitedJobs.expectMonitor(id) } : {}),
 				...(params.monitorTimeoutCapMs !== undefined
 					? { monitorTimeoutCapMs: params.monitorTimeoutCapMs }
@@ -1611,13 +1665,13 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 					.catch(() => {})
 				return
 			}
-			const outcome =
-				job.status === 'killed'
-					? 'was stopped'
-					: `exited with code ${job.exitCode ?? 'unknown'}${job.signal ? ` (${job.signal})` : ''}`
-			jobNotices?.steer(
-				`Background job ${job.id} (${job.command}) ${outcome}. Read its output with the job tool if you need it.`,
-			)
+			let inlineOutput: ReturnType<NonNullable<typeof params.backgroundJobs>['read']> | undefined
+			try {
+				inlineOutput = params.backgroundJobs?.read(job.id)
+			} catch {
+				// The record is gone; the notice still stands without its output.
+			}
+			jobNotices?.steer(formatJobExitNotice(job, inlineOutput), job.id)
 			pendingJobNoticeIds.add(job.id)
 			void eventTranslator
 				.emitEvent({
@@ -1821,6 +1875,9 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			...(monitorNotices ? { monitorNotices } : {}),
 			...(monitorNotices ? { onMonitorNoticeDelivered: acknowledgeMonitorNotices } : {}),
 			...(awaitedJobs ? { awaitedJobs } : {}),
+			...(params.answerWhileCallsRun && params.waitForOperator
+				? { detachedCalls: new DetachedCalls(params.waitForOperator) }
+				: {}),
 			checkpointMgr,
 			planManager: ctx.planManager,
 			taskGateway: taskScheduler,
@@ -1840,6 +1897,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			...(params.maxOutputContinuations !== undefined
 				? { maxOutputContinuations: params.maxOutputContinuations }
 				: {}),
+			...(params.refusalFallback !== undefined ? { refusalFallback: params.refusalFallback } : {}),
 			...(params.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
 			...(params.reminders ? { reminders: params.reminders } : {}),
 			...(params.durableInbound ? { durableInbound: params.durableInbound } : {}),

package/src/runtime/query/iteration/effort-clamp.ts

@@ -0,0 +1,46 @@
+import type { LLMProvider, ReasoningEffort, ThinkingConfig } from '../../../types/provider/index.js'
+
+/** Lowest to highest, the order the effort menus are drawn in. */
+const EFFORT_ORDER: readonly ReasoningEffort[] = [
+	'none',
+	'minimal',
+	'low',
+	'medium',
+	'high',
+	'xhigh',
+	'max',
+	'ultra',
+]
+
+/**
+ * The effort to send to `model` when the turn was configured for another one.
+ *
+ * A level the model does not offer is rejected by some drivers, so a request
+ * moved to a different model (a refusal fallback, a live model pick) carries
+ * the nearest level that model supports: the next one down when there is one,
+ * otherwise the lowest one above. The menu comes from the provider, never from
+ * a copy here. A provider that cannot say what the model offers, or a level
+ * the model already offers, leaves the effort exactly as configured.
+ */
+export function effortForModel(
+	provider: LLMProvider,
+	model: string,
+	effort: ReasoningEffort,
+	thinking?: ThinkingConfig,
+): ReasoningEffort {
+	let menu: readonly ReasoningEffort[] | undefined
+	try {
+		menu = provider.reasoningEffortLevelsFor
+			? provider.reasoningEffortLevelsFor(model, thinking)
+			: provider.effortLevelsFor?.(model, thinking)
+	} catch {
+		return effort
+	}
+	if (!menu || menu.length === 0 || menu.includes(effort)) return effort
+	const rank = (level: ReasoningEffort) => EFFORT_ORDER.indexOf(level)
+	const wanted = rank(effort)
+	if (wanted < 0) return effort
+	const ranked = menu.filter((level) => rank(level) >= 0).sort((a, b) => rank(a) - rank(b))
+	const below = ranked.filter((level) => rank(level) < wanted)
+	return below[below.length - 1] ?? ranked[0] ?? effort
+}