@namzu/sdk 51.1.0 → 52.0.0

package/src/public-types.ts

@@ -204,6 +204,7 @@ export type {
 	Disposable,
 	RunAgentOptions,
 	RunAgentResult,
+	SupervisorResumeTarget,
 } from './agents/index.js'
 
 export type {
@@ -457,7 +458,10 @@ export type {
 
 export type {
 	GuardedFetchConfig,
+	WebContentExtractor,
+	WebExtractRequest,
 	WebFetchProvider,
+	WebFetchRedirectPolicy,
 	WebFetchRefusalReason,
 	WebFetchRequest,
 	WebFetchResult,

package/src/runtime/jobs/registry.ts

@@ -99,6 +99,21 @@ export interface StartJobParams {
 	 * expect stdin.
 	 */
 	readonly spawn?: () => JobProcess
+	/**
+	 * Output the process already wrote before the registry took it over, in
+	 * the order it was written. Used when a foreground command is moved to the
+	 * background, so a later `read` starts with what the model was shown.
+	 */
+	readonly initialOutput?: readonly {
+		readonly stream: 'stdout' | 'stderr'
+		readonly text: string
+	}[]
+	/**
+	 * `spawn` returned a process on THIS host that the host shell started (a
+	 * foreground command being moved to the background), so its bytes are
+	 * decoded the way a foreground command's are, not as a Linux guest's.
+	 */
+	readonly hostOutput?: boolean
 }
 
 export interface BackgroundJobRegistryConfig {
@@ -333,8 +348,12 @@ export class BackgroundJobRegistry {
 		// Raw bytes, decoded here: a Windows console writes its OEM code page.
 		// A process a sandbox started runs a Linux guest, so it is UTF-8.
 		const decoders = {
-			stdout: createHostOutputDecoder(params.spawn ? { platform: 'linux' } : {}),
-			stderr: createHostOutputDecoder(params.spawn ? { platform: 'linux' } : {}),
+			stdout: createHostOutputDecoder(
+				params.spawn && !params.hostOutput ? { platform: 'linux' } : {},
+			),
+			stderr: createHostOutputDecoder(
+				params.spawn && !params.hostOutput ? { platform: 'linux' } : {},
+			),
 		}
 		let startError: string | undefined
 		let settleStarted!: () => void
@@ -473,6 +492,7 @@ export class BackgroundJobRegistry {
 			const text = typeof data === 'string' ? data : decoders[stream].write(data)
 			if (text) append(text, stream)
 		}
+		for (const seed of params.initialOutput ?? []) append(seed.text, seed.stream)
 		child.stdout?.on('data', onData('stdout'))
 		child.stderr?.on('data', onData('stderr'))
 
@@ -855,6 +875,23 @@ export function bindOwner(
 					: {}),
 			})
 		},
+		// A foreground command that ran out of time, kept instead of killed.
+		// The same owner and cap as `start`; the process is the one already
+		// running, with what it has written so far.
+		adopt: (params: {
+			command: string
+			child: ReturnType<typeof spawn>
+			workingDirectory?: string
+			initialOutput?: StartJobParams['initialOutput']
+		}) =>
+			registry.start({
+				owner,
+				command: params.command,
+				workingDirectory: params.workingDirectory ?? defaults.workingDirectory ?? process.cwd(),
+				spawn: () => ({ child: params.child }),
+				hostOutput: true,
+				...(params.initialOutput ? { initialOutput: params.initialOutput } : {}),
+			}),
 		get: (id: string) => mine(id),
 		awaitStarted: (id: string) => {
 			mine(id)

package/src/runtime/query/executor/tool-call-admission.ts

@@ -2,7 +2,7 @@ import { GENAI, NAMZU } from '../../../constants/telemetry/index.js'
 import { callableToolNames, formatToolNames } from '../../../registry/tool/callable.js'
 import { renderToolSchema } from '../../../registry/tool/schema.js'
 import type { ToolCall, ToolInputError } from '../../../types/message/index.js'
-import type { PluginHookResult } from '../../../types/plugin/index.js'
+import type { PluginHookPermission, PluginHookResult } from '../../../types/plugin/index.js'
 import type { ToolDefinition } from '../../../types/tool/index.js'
 import type { ToolCallRepair, ToolCallRepairReason } from '../../../types/tool/repair.js'
 import { awaitWithAbort } from '../../../utils/await-with-abort.js'
@@ -10,6 +10,7 @@ import { toErrorMessage } from '../../../utils/error.js'
 import type { Logger } from '../../../utils/logger.js'
 import type {
 	EmitEvent,
+	PreToolHookNotes,
 	PreToolHookOutcome,
 	PreparedDirectCall,
 	ToolExecutorConfig,
@@ -49,6 +50,11 @@ export interface ToolAdmissionHost {
 	 * step, which is the answer that sent a model round in a circle.
 	 */
 	readonly allowedTools: readonly string[] | undefined
+	/**
+	 * A hook asked for the turn to stop after the current step. Optional so a
+	 * host that builds an admission by hand (a test) need not say anything.
+	 */
+	readonly requestHalt?: (reason: string) => void
 }
 
 /**
@@ -89,7 +95,7 @@ export async function runPreToolHook(
 		signal,
 	)
 	signal.throwIfAborted()
-	return interpretPreToolResults(toolName, input, results)
+	return interpretPreToolResults(toolName, input, results, host.requestHalt)
 }
 
 export async function prepareDirectCall(
@@ -169,6 +175,7 @@ export async function prepareDirectCall(
 				...(providerInput && !truncationRepair && !preOutcome.modified && resolved.inputFailure
 					? { inputFailure: resolved.inputFailure }
 					: {}),
+				...hookNotesOf(preOutcome),
 			}
 		}
 		return {
@@ -321,6 +328,20 @@ export async function prepareDirectCall(
 		toolName,
 		input: preparation.prepared.input,
 		prepared: preparation.prepared,
+		...hookNotesOf(preOutcome),
+	}
+}
+
+/** The hook answers a ready or legacy call carries forward, or nothing. */
+function hookNotesOf(outcome: Extract<PreToolHookOutcome, { kind: 'continue' }>): {
+	hook?: PreToolHookNotes
+} {
+	if (outcome.permission === undefined && outcome.context === undefined) return {}
+	return {
+		hook: {
+			...(outcome.permission ? { permission: outcome.permission } : {}),
+			...(outcome.context !== undefined ? { context: outcome.context } : {}),
+		},
 	}
 }
 
@@ -328,29 +349,49 @@ function interpretPreToolResults(
 	toolName: string,
 	initialInput: unknown,
 	results: readonly PluginHookResult[],
+	requestHalt?: (reason: string) => void,
 ): PreToolHookOutcome {
 	let currentInput = initialInput
 	let modified = false
+	let permission: PluginHookPermission | undefined
+	const contexts: string[] = []
+	/** `ask` outranks `allow`: the stricter answer is the one that stands. */
+	const takePermission = (next: PluginHookPermission | undefined) => {
+		if (next === undefined) return
+		if (permission === undefined || (permission.decision === 'allow' && next.decision === 'ask')) {
+			permission = next
+		}
+	}
+	const withContext = (text: string): string =>
+		contexts.length === 0 ? text : `${text}\n\n${hookNote(contexts)}`
+	// The hooks ran side by side on the original input, and their answers are
+	// combined here. The first refusal (or failure) in registration order is the
+	// answer, whatever the others said; of several rewrites the last wins;
+	// `ask` outranks `allow`; every context is kept; every request to stop is
+	// passed on.
+	let refusal: { kind: 'skip' | 'error'; text: string } | undefined
 	for (const result of results) {
 		switch (result.action) {
 			case 'continue':
+				takePermission(result.permission)
+				if (result.context) contexts.push(result.context)
+				if (result.halt) requestHalt?.(result.halt.reason)
 				continue
 			case 'modify':
 				currentInput = result.input
 				modified = true
+				takePermission(result.permission)
+				if (result.context) contexts.push(result.context)
+				if (result.halt) requestHalt?.(result.halt.reason)
 				continue
 			case 'skip':
-				return {
-					kind: 'skip',
-					input: currentInput,
-					output: skippedToolResultText(toolName, result.reason),
-				}
+				if (result.context) contexts.push(result.context)
+				if (result.halt) requestHalt?.(result.halt.reason)
+				refusal ??= { kind: 'skip', text: skippedToolResultText(toolName, result.reason) }
+				continue
 			case 'error':
-				return {
-					kind: 'error',
-					input: currentInput,
-					output: `Error: ${result.message}`,
-				}
+				refusal ??= { kind: 'error', text: `Error: ${result.message}` }
+				continue
 			case 'retry':
 			case 'annotate':
 			// There is no result to replace yet. Rejecting loudly beats
@@ -367,9 +408,34 @@ function interpretPreToolResults(
 			}
 		}
 	}
-	return { kind: 'continue', input: currentInput, modified }
+	if (refusal) {
+		return {
+			kind: refusal.kind,
+			input: currentInput,
+			output: refusal.kind === 'skip' ? withContext(refusal.text) : refusal.text,
+		}
+	}
+	return {
+		kind: 'continue',
+		input: currentInput,
+		modified,
+		...(permission ? { permission } : {}),
+		...(contexts.length > 0 ? { context: contexts.join('\n') } : {}),
+	}
+}
+
+/**
+ * Hook text, framed so the model reads it as what a configured hook said and
+ * not as something the tool returned.
+ */
+export function hookNote(texts: readonly string[]): string {
+	const joined = texts.join('\n')
+	return `[Hook note]\n${joined.length > MAX_HOOK_NOTE_CHARS ? `${joined.slice(0, MAX_HOOK_NOTE_CHARS)}\n[truncated]` : joined}`
 }
 
+/** A hook's text is one more thing for the model to read; it gets a bound. */
+const MAX_HOOK_NOTE_CHARS = 8_000
+
 /**
  * Turn the call the model issued into a name and a parsed input, giving
  * a configured repairer one chance to fix it first.