@namzu/sdk 58.1.1 → 60.0.0

package/src/runtime/jobs/registry.ts

@@ -1,7 +1,7 @@
 import type { spawn } from 'node:child_process'
 
 import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
-import { killTree } from '../../process/kill-tree.js'
+import { isSignalablePid, killTree } from '../../process/kill-tree.js'
 import { describeSpawnFailure, spawnHostShell } from '../../tools/command-shell.js'
 import { scrubInheritedEnv } from '../../tools/env-scrub.js'
 import { createHostOutputDecoder } from '../../tools/host-output.js'
@@ -12,6 +12,7 @@ import type {
 import type { MonitorWebSocketTarget } from '../../types/tool/index.js'
 import { subscribeToAbort } from '../../utils/abort.js'
 import { oneMetadataLine } from '../system-events.js'
+import { stopAtHostExit } from './host-exit-finalizer.js'
 import { createBackgroundJobId } from './job-id.js'
 import {
 	MONITOR_TIMEOUT_CAP_MS,
@@ -53,6 +54,10 @@ export interface BackgroundJob {
 	readonly command: string
 	readonly status: BackgroundJobStatus
 	readonly startedAt: number
+	/** When the job last wrote output (epoch ms). Absent until it has written anything. */
+	readonly lastOutputAt?: number
+	/** The last non-empty output line, flattened and clipped to {@link LAST_OUTPUT_LINE_MAX}. */
+	readonly lastOutputLine?: string
 	readonly exitedAt?: number
 	readonly exitCode?: number
 	readonly signal?: string
@@ -347,7 +352,7 @@ interface MonitorState {
 
 /** Whether any process of the group led by `pid` is still alive. */
 function groupAlive(pid: number | undefined): boolean {
-	if (pid === undefined || process.platform === 'win32') return false
+	if (!isSignalablePid(pid) || process.platform === 'win32') return false
 	try {
 		process.kill(-pid, 0)
 		return true
@@ -356,8 +361,67 @@ function groupAlive(pid: number | undefined): boolean {
 	}
 }
 
+/**
+ * The same probe for a status read: a group that exists but is not ours to
+ * signal (EPERM) is there. The close handler keeps {@link groupAlive}, which
+ * must not wait on a group it can never see end.
+ *
+ * Not proof the group is still the job's: between the group ending and the
+ * record closing, a recycled pid that leads a new group would read as alive.
+ * The close handler polls every {@link GROUP_POLL_MS}, so the window is
+ * that small.
+ */
+function groupPresent(pid: number): boolean {
+	if (!isSignalablePid(pid)) return false
+	try {
+		process.kill(-pid, 0)
+		return true
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === 'EPERM'
+	}
+}
+
 const GROUP_POLL_MS = 250
 
+/** Longest `lastOutputLine` kept on a job record. */
+export const LAST_OUTPUT_LINE_MAX = 160
+
+/**
+ * Drop terminal control sequences and control characters, keeping one space
+ * where a control character stood. Done by code point so no pattern has to
+ * spell a control character.
+ */
+function plainLine(raw: string): string {
+	let out = ''
+	let i = 0
+	while (i < raw.length) {
+		const code = raw.charCodeAt(i)
+		if (code === 0x1b && raw[i + 1] === '[') {
+			// CSI: parameters and intermediates, then one final byte in @..~.
+			i += 2
+			while (i < raw.length && raw.charCodeAt(i) >= 0x20 && raw.charCodeAt(i) <= 0x3f) i += 1
+			i += 1
+			continue
+		}
+		out += code < 0x20 || code === 0x7f ? ' ' : (raw[i] ?? '')
+		i += 1
+	}
+	return out.replace(/ {2,}/g, ' ').trim()
+}
+
+/** The last non-empty line of `text`, flattened and clipped; `undefined` when it has none. */
+function lastLineOf(text: string): string | undefined {
+	const lines = text.split('\n')
+	for (let index = lines.length - 1; index >= 0; index -= 1) {
+		const flat = plainLine(lines[index] ?? '')
+		if (flat.length > 0)
+			return flat.length <= LAST_OUTPUT_LINE_MAX
+				? flat
+				: `${flat.slice(0, LAST_OUTPUT_LINE_MAX - 1)}…`
+	}
+	return undefined
+}
+
 /**
  * Why a command that was running in the foreground moved to the background:
  * the person asked (`user`), or the person sent a message that has to reach
@@ -708,6 +772,7 @@ export class BackgroundJobRegistry {
 				const finalize = (code: number | null, signal: NodeJS.Signals | null): void => {
 					if (finalized) return
 					finalized = true
+					untrackAtHostExit()
 					entry.record = {
 						...entry.record,
 						// A job killed by this registry says `killed`, not
@@ -788,11 +853,26 @@ export class BackgroundJobRegistry {
 			}),
 		}
 		entry.finalize = finalizeEntry
+		// A job that is not stopped before the host exits is an orphan: nothing
+		// owns its id any more. A remote job confirms its own termination and is
+		// not signalled from an exit listener.
+		const untrackAtHostExit = entry.terminateProcess
+			? () => {}
+			: stopAtHostExit({
+					child,
+					...(entry.killProcess ? { kill: entry.killProcess } : {}),
+				})
 
 		const append = (text: string, stream: 'stdout' | 'stderr'): void => {
 			const chunk: OutputChunk = { stream, offset: entry.produced, bytes: Buffer.from(text) }
 			if (chunk.bytes.length === 0) return
 			entry.produced += chunk.bytes.length
+			const line = lastLineOf(text)
+			entry.record = {
+				...entry.record,
+				lastOutputAt: Date.now(),
+				...(line !== undefined ? { lastOutputLine: line } : {}),
+			}
 			entry.buffer += text
 			entry.buffer = outputTail(entry.buffer, this.maxBytes).text
 			entry.outputChunks.push(chunk)
@@ -898,6 +978,20 @@ export class BackgroundJobRegistry {
 		return entry.record
 	}
 
+	/**
+	 * Whether the job's process group is still there, asked of the system rather
+	 * than inferred from the record. A job with no process of its own to probe
+	 * (a sandboxed or WebSocket source, or a platform without process groups)
+	 * is alive exactly when the registry says it is running.
+	 */
+	isAlive(id: string): boolean {
+		const entry = this.jobs.get(id)
+		if (!entry || entry.record.status !== 'running') return false
+		const pid = entry.child.pid
+		if (pid === undefined || process.platform === 'win32') return true
+		return groupPresent(pid)
+	}
+
 	/**
 	 * Await one job's exit — the public counterpart to `onExit`, for a
 	 * caller that wants a single result rather than a standing
@@ -1253,6 +1347,12 @@ export function bindOwner(
 		 * than present and silently doing nothing.
 		 */
 		readonly onAwaited?: (id: string) => void
+		/**
+		 * Be told that a tool result has handed the model this job's exit, so the
+		 * notice announcing the same exit can be withdrawn. Like `onAwaited` it
+		 * belongs to the turn; absent, `markCollected` is absent from the ref.
+		 */
+		readonly onCollected?: (id: string) => void
 		/**
 		 * The longest a monitor started through this binding may live. A host
 		 * may lower it (a single-shot run has no tomorrow to watch for); the
@@ -1387,11 +1487,23 @@ export function bindOwner(
 					},
 				}
 			: {}),
+		...(defaults.onCollected
+			? {
+					markCollected: (id: string) => {
+						mine(id)
+						defaults.onCollected?.(id)
+					},
+				}
+			: {}),
 		kill: async (id: string) => {
 			mine(id)
 			return await registry.kill(id)
 		},
 		list: () => registry.list(owner),
+		isAlive: (id: string) => {
+			mine(id)
+			return registry.isAlive(id)
+		},
 	}
 }
 

package/src/runtime/jobs/wake-budget.ts

@@ -0,0 +1,55 @@
+/**
+ * A bound on how many times in a row a session wakes the model on its own.
+ *
+ * A finished background job wakes an idle session, and the turn that wakes may
+ * start another job whose exit wakes it again, with nobody reading. For an
+ * owner that nobody is watching, that chain never has to end. The budget caps
+ * it: after `max` wakes in a row no further exit wakes the model, and the
+ * exits stay pending so the next message from a person carries them.
+ *
+ * **Off unless asked.** An interactive session has a person to stop it, and a
+ * cap there would only get in the way. `max` of `undefined` (or anything that
+ * is not a positive integer) never limits.
+ *
+ * **Only a person resets it.** A wake, a job notice or a tool result is not
+ * evidence anyone is looking; a human message is.
+ */
+export class WakeBudget {
+	private woken = 0
+	private readonly max: number | undefined
+
+	constructor(max?: number) {
+		this.max = max !== undefined && Number.isInteger(max) && max > 0 ? max : undefined
+	}
+
+	/** Whether another automatic wake is allowed. */
+	get canWake(): boolean {
+		return this.max === undefined || this.woken < this.max
+	}
+
+	/** Count one automatic wake. Call when a wake begins a turn. */
+	recordWake(): void {
+		this.woken++
+	}
+
+	/** A person wrote: the chain is attended again. */
+	reset(): void {
+		this.woken = 0
+	}
+
+	/** Wakes since the last human message. */
+	get consecutiveWakes(): number {
+		return this.woken
+	}
+}
+
+/**
+ * The budget a host asked for through `NAMZU_MAX_CONSECUTIVE_WAKES`, or an
+ * unlimited one. Anything but a positive integer means no limit.
+ */
+export function wakeBudgetFromEnv(
+	env: Record<string, string | undefined> = process.env,
+): WakeBudget {
+	const raw = env.NAMZU_MAX_CONSECUTIVE_WAKES?.trim()
+	return new WakeBudget(raw && /^\d+$/.test(raw) ? Number(raw) : undefined)
+}

package/src/runtime/query/detached-calls.ts

@@ -0,0 +1,135 @@
+import { frameNotice } from '../../types/message/notice-frame.js'
+import type { ToolCallOutcome } from './executor.js'
+
+/**
+ * Tool calls that were still running when the operator wrote.
+ *
+ * A model cannot answer while a `tool_use` block has no `tool_result`, and a
+ * long call used to hold the operator's question until it finished: the person
+ * asked how things stand and heard nothing for as long as the call took. When
+ * the operator writes while a call has been running for a while, the batch
+ * answers the unfinished calls with a placeholder result, the model reads the
+ * message at once, and the call carries on untouched. Its real result reaches
+ * the model later as a message of its own that names the call.
+ *
+ * This holds the bookkeeping for one turn: which calls were handed back this
+ * way, and the outcomes that have arrived since.
+ */
+
+/** How long a call must have been running before an operator message detaches it. */
+export const DETACH_AFTER_MS = 2_000
+
+/**
+ * What a model reads as the result of a call that is still running.
+ *
+ * It says the call goes on, what not to do about it, and what to tell the
+ * person; the model never sees these words as anything the tool printed.
+ */
+export function stillRunningResult(toolName: string, started = true): string {
+	if (!started) {
+		return [
+			`[Waiting to start] The ${toolName} call has not started: it is queued behind an earlier call in this batch. The operator wrote a message while the batch ran, and that message follows so you can answer it now.`,
+			'The call will start by itself when the earlier one ends, and its result will arrive in a later message that names this call id.',
+			'Repeating the call would run the work twice, and waiting or polling for it would delay your answer, so do neither. If they ask, say it has not started yet.',
+		].join('\n')
+	}
+	return [
+		`[Still running] The ${toolName} call has not finished. The operator wrote a message while it ran, and that message follows so you can answer it now.`,
+		'The call was not interrupted. Its result will arrive on its own, in a later message that names this call id.',
+		'Repeating the call would run the work twice, and waiting or polling for it would delay your answer, so do neither.',
+		'You cannot stop it from here, so do not say you cancelled or dropped it. On the operator’s screen it still shows as in progress; if they ask, say it is still running.',
+	].join('\n')
+}
+
+/** What a model reads when a call it was told was still running has finished. */
+export function formatLateResults(outcomes: readonly ToolCallOutcome[]): string {
+	const parts = outcomes.map(
+		(outcome) =>
+			`The ${outcome.toolName} call with id ${outcome.toolCallId}, which you were told was still running, has finished${outcome.isError ? ' with an error' : ''}. This is what it returned:\n${outcome.output}`,
+	)
+	return frameNotice('job', '[Tool call finished]', parts.join('\n\n'))
+}
+
+export class DetachedCalls {
+	private readonly open = new Map<string, string>()
+	private arrived: ToolCallOutcome[] = []
+	private readonly waiters = new Set<() => void>()
+
+	/**
+	 * `waitForOperator` resolves when the operator wrote and at no other wake: a
+	 * child's notice or a peer's mail must not hand a call back, because the
+	 * model would then get a turn with no question to answer.
+	 */
+	constructor(readonly waitForOperator?: (signal: AbortSignal) => Promise<void>) {}
+
+	/** A call was answered with the placeholder and is still running. */
+	begin(toolCallId: string, toolName: string): void {
+		this.open.set(toolCallId, toolName)
+	}
+
+	/** The real outcome of a detached call. Ignored for a call that was never detached. */
+	settle(outcome: ToolCallOutcome): void {
+		if (!this.open.delete(outcome.toolCallId)) return
+		this.arrived.push(outcome)
+		this.wake()
+	}
+
+	/** True while a call is still running or its outcome has not been read. */
+	get hasWork(): boolean {
+		return this.open.size > 0 || this.arrived.length > 0
+	}
+
+	/** Calls still running. */
+	get running(): number {
+		return this.open.size
+	}
+
+	/** The outcomes that have arrived since the last read, in arrival order. */
+	take(): readonly ToolCallOutcome[] {
+		const taken = this.arrived
+		this.arrived = []
+		return taken
+	}
+
+	/**
+	 * Resolves when an outcome is waiting, when nothing is running, after
+	 * `graceMs`, or rejects when `signal` aborts. Resolving early is never
+	 * delivery: the caller reads with {@link take}.
+	 */
+	waitForArrival(graceMs: number, signal: AbortSignal): Promise<void> {
+		if (this.arrived.length > 0 || this.open.size === 0) return Promise.resolve()
+		if (signal.aborted) return Promise.reject(signal.reason)
+		return new Promise<void>((resolve, reject) => {
+			const done = (): void => {
+				clearTimeout(timer)
+				this.waiters.delete(wake)
+				signal.removeEventListener('abort', abort)
+			}
+			const wake = (): void => {
+				done()
+				resolve()
+			}
+			const abort = (): void => {
+				done()
+				reject(signal.reason)
+			}
+			const timer = setTimeout(wake, Math.max(0, graceMs))
+			this.waiters.add(wake)
+			signal.addEventListener('abort', abort, { once: true })
+		})
+	}
+
+	private wake(): void {
+		for (const wake of [...this.waiters]) wake()
+	}
+}
+
+/**
+ * What one batch needs to hand its unfinished calls back. `requested` settles
+ * once the operator has written and the batch has run for {@link DETACH_AFTER_MS};
+ * `calls` receives each call that was handed back and, later, its outcome.
+ */
+export interface BatchDetach {
+	readonly requested: Promise<void>
+	readonly calls: DetachedCalls
+}

package/src/runtime/query/executor.ts

@@ -13,6 +13,7 @@ import { buildProbeContext } from '../../probe/context.js'
 import { ProbeVetoError } from '../../probe/errors.js'
 import { probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ProbeEnforcement } from '../../probe/registry.js'
+import { ToolResultHalted } from '../../registry/tool/screen.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import {
 	effectiveBashWorkingDirectory,
@@ -70,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,
@@ -411,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
 	/**
@@ -1428,6 +1432,7 @@ export class ToolExecutor {
 		preparedBatch?: PreparedToolBatch,
 		declines?: ToolCallDeclines,
 		review?: ReviewedExecution,
+		detach?: BatchDetach,
 	): Promise<ToolExecutionBatch> {
 		const toolCalls = response.message.toolCalls
 		if (!toolCalls) {
@@ -1454,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.
@@ -1471,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,
@@ -1506,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
@@ -1622,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()
 				}
@@ -1663,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
@@ -2204,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 }
 				: {}),
@@ -2299,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 }
 									: {}),
@@ -3131,11 +3214,16 @@ export class ToolExecutor {
 	}
 
 	/**
-	 * One execution attempt, with a throw materialized as an error result.
+	 * One execution attempt, with a throw materialized as an error result —
+	 * except `ToolResultHalted`, which this deliberately lets through.
 	 *
 	 * an unhandled throw from `tools.execute(...)` used to
 	 * propagate up to `result.ts` as `turn_failed` without emitting a
-	 * terminal `tool_completed`, leaving UI cards stuck in `executing`.
+	 * terminal `tool_completed`, leaving UI cards stuck in `executing`. That
+	 * is still right for a tool that merely broke. It is wrong for a screen
+	 * that said `halt`: `screen.ts` throws `ToolResultHalted` instead of
+	 * returning it so a catch this generic cannot flatten it into a failed
+	 * `ToolResult` the model reads and works around.
 	 *
 	 * The return is the full `ToolResult`, not a narrowed literal: the
 	 * narrow version silently DROPPED `content`, so a tool returning an
@@ -3151,6 +3239,8 @@ export class ToolExecutor {
 		try {
 			return await this.executeWithDeadline(toolName, input, toolContext, prepared)
 		} catch (err) {
+			if (err instanceof ToolResultHalted) throw err
+
 			const message = toErrorMessage(err)
 			this.log.warn('Tool execution threw', {
 				[NAMZU.TURN_ID]: this.config.turnId,