@namzu/sdk 31.0.0 → 32.0.0

package/src/directory/derive.ts

@@ -72,6 +72,11 @@ export function deriveRunOptions(
 					maxRequestRichContentBytes: manifest.config.maxRequestRichContentBytes,
 				}
 			: {}),
+		...(manifest.config.attachmentResolveTimeoutMs !== undefined
+			? {
+					attachmentResolveTimeoutMs: manifest.config.attachmentResolveTimeoutMs,
+				}
+			: {}),
 		...(input.identity ?? {}),
 		...(input.overrides ?? {}),
 	}

package/src/directory/load.ts

@@ -187,6 +187,7 @@ function readConfig(
 	take('timeoutMs', isNumber, 'finite number')
 	take('streamIdleTimeoutMs', isNumber, 'finite number')
 	take('maxRequestRichContentBytes', isNumber, 'finite number')
+	take('attachmentResolveTimeoutMs', isNumber, 'finite number')
 
 	// `metadata` is typed `Record<string, string>` and was admitted on
 	// `typeof === 'object'` alone — which an array also satisfies, and which

package/src/directory/types.ts

@@ -170,6 +170,8 @@ export interface DirectoryConfig {
 	readonly streamIdleTimeoutMs?: number
 	/** Accumulated inline image/document bytes per provider request; `0` disables. */
 	readonly maxRequestRichContentBytes?: number
+	/** Maximum stored-attachment materialization time; `0` disables the bound. */
+	readonly attachmentResolveTimeoutMs?: number
 	/** Names the agent in traces and events when declared. */
 	readonly name?: string
 	/** Free-form labels for an inspector. Never interpreted by this package. */

package/src/execution/code-runtime/types.ts

@@ -42,6 +42,17 @@ export interface HostCallResult {
 	readonly error?: string
 }
 
+/** Authority and provenance for one call from a running program. */
+export interface HostCallContext {
+	/** Unique within this program execution. */
+	readonly runtimeToolCallId: string
+	/**
+	 * Revoked when the caller cancels or the program's own wall clock expires.
+	 * A conforming host threads this into the operation it starts.
+	 */
+	readonly signal: AbortSignal
+}
+
 /**
  * What the host will answer.
  *
@@ -50,7 +61,10 @@ export interface HostCallResult {
  * exactly the point: the program's reach is the run's reach, resolved at
  * the moment of the call rather than frozen when the program started.
  */
-export type HostCallHandler = (request: HostCallRequest) => Promise<HostCallResult>
+export type HostCallHandler = (
+	request: HostCallRequest,
+	context: HostCallContext,
+) => Promise<HostCallResult>
 
 export interface RunCodeOptions {
 	/** The program. Untrusted text, from the model. */

package/src/execution/code-runtime/worker.ts

@@ -105,6 +105,17 @@ export class WorkerCodeRuntime implements CodeRuntime {
 		let output = ''
 		let truncated = false
 
+		// A withdrawn caller owns admission. Do not start an isolate merely to
+		// discover the signal was already aborted after construction.
+		if (options.signal?.aborted) {
+			return {
+				outcome: { status: 'cancelled' },
+				output,
+				outputTruncated: truncated,
+				calls,
+			}
+		}
+
 		const appendOutput = (lines: readonly string[]): void => {
 			for (const line of lines) {
 				if (truncated) return
@@ -143,6 +154,10 @@ export class WorkerCodeRuntime implements CodeRuntime {
 
 		return await new Promise<CodeRunResult>((resolve) => {
 			let settled = false
+			let terminal: CodeRunResult | undefined
+			const inFlight = new Set<Promise<void>>()
+			const operation = new AbortController()
+
 			const finish = (result: CodeRunResult): void => {
 				// The Promise already ignores a second `resolve`, so removing
 				// this guard changes no result — a mutation removing it
@@ -153,18 +168,42 @@ export class WorkerCodeRuntime implements CodeRuntime {
 				// then `exit` is the ordinary sequence, not an edge case.
 				if (settled) return
 				settled = true
+				// Terminating the worker only stops the program. Host work already
+				// admitted through onHostCall lives outside it, so revoke the signal
+				// that was handed to every such call before reporting settlement.
+				if (!operation.signal.aborted) {
+					operation.abort(new Error(`Code runtime settled with status ${result.outcome.status}`))
+				}
 				clearTimeout(deadline)
 				options.signal?.removeEventListener('abort', onAbort)
 				void worker.terminate()
-				resolve(result)
+				// A late, non-cooperative host call must not mutate a result the
+				// caller already received.
+				resolve({ ...result, calls: [...calls] })
+			}
+
+			const finishTerminalWhenHostCallsSettle = (): void => {
+				if (terminal && inFlight.size === 0) finish(terminal)
 			}
 
 			const deadline = setTimeout(() => {
-				finish({ outcome: { status: 'timed-out' }, output, outputTruncated: truncated, calls })
+				operation.abort(new Error(`Code runtime exceeded ${options.timeoutMs}ms`))
+				finish({
+					outcome: { status: 'timed-out' },
+					output,
+					outputTruncated: truncated,
+					calls,
+				})
 			}, options.timeoutMs)
 
 			const onAbort = (): void => {
-				finish({ outcome: { status: 'cancelled' }, output, outputTruncated: truncated, calls })
+				operation.abort(options.signal?.reason)
+				finish({
+					outcome: { status: 'cancelled' },
+					output,
+					outputTruncated: truncated,
+					calls,
+				})
 			}
 			options.signal?.addEventListener('abort', onAbort, { once: true })
 			if (options.signal?.aborted) {
@@ -185,13 +224,23 @@ export class WorkerCodeRuntime implements CodeRuntime {
 							kind: 'call-result',
 							id,
 							ok: false,
-							error: new HostCallDeniedError({ name, allowed: options.allowedCalls }).message,
+							error: new HostCallDeniedError({
+								name,
+								allowed: options.allowedCalls,
+							}).message,
 						})
 						return
 					}
-					void options
-						.onHostCall({ name, input: message.input })
+					const runtimeToolCallId = String(id)
+					const hostCall = Promise.resolve()
+						.then(() =>
+							options.onHostCall(
+								{ name, input: message.input },
+								{ runtimeToolCallId, signal: operation.signal },
+							),
+						)
 						.then((result) => {
+							if (settled) return
 							calls.push({ name, ok: result.ok })
 							worker.postMessage({
 								kind: 'call-result',
@@ -202,6 +251,7 @@ export class WorkerCodeRuntime implements CodeRuntime {
 							})
 						})
 						.catch((err: unknown) => {
+							if (settled) return
 							calls.push({ name, ok: false })
 							worker.postMessage({
 								kind: 'call-result',
@@ -210,6 +260,11 @@ export class WorkerCodeRuntime implements CodeRuntime {
 								error: err instanceof Error ? err.message : String(err),
 							})
 						})
+						.finally(() => {
+							inFlight.delete(hostCall)
+							finishTerminalWhenHostCallsSettle()
+						})
+					inFlight.add(hostCall)
 					return
 				}
 
@@ -219,12 +274,17 @@ export class WorkerCodeRuntime implements CodeRuntime {
 				}
 
 				if (message.kind === 'done') {
-					finish({
+					// A program may start a host call without awaiting it. The worker
+					// declaring its JavaScript body complete is not evidence that the
+					// effect it started is complete, so keep the runtime open until the
+					// already-admitted host calls settle (or the deadline revokes them).
+					terminal = {
 						outcome: { status: 'completed', result: message.result },
 						output,
 						outputTruncated: truncated,
 						calls,
-					})
+					}
+					finishTerminalWhenHostCallsSettle()
 					return
 				}
 
@@ -255,7 +315,10 @@ export class WorkerCodeRuntime implements CodeRuntime {
 				// `error` message — a hard crash, or a program that called
 				// `process.exit` through something we failed to withhold.
 				finish({
-					outcome: { status: 'failed', error: `The program exited with code ${code}.` },
+					outcome: {
+						status: 'failed',
+						error: `The program exited with code ${code}.`,
+					},
 					output,
 					outputTruncated: truncated,
 					calls,

package/src/manager/agent/lifecycle.ts

@@ -396,6 +396,7 @@ export class AgentManager {
 				timeoutMs: options.budgetAllocation?.timeoutMs ?? this.config.childTimeoutMs,
 				streamIdleTimeoutMs: options.configOverrides?.streamIdleTimeoutMs,
 				maxRequestRichContentBytes: options.configOverrides?.maxRequestRichContentBytes,
+				attachmentResolveTimeoutMs: options.configOverrides?.attachmentResolveTimeoutMs,
 				temperature: options.configOverrides?.temperature,
 				parentSpan: options.configOverrides?.parentSpan,
 				maxIterations: options.configOverrides?.maxIterations,

package/src/provider/errors.ts

@@ -57,6 +57,7 @@ const PROVIDER_ERROR_KINDS: readonly ProviderErrorKind[] = [
 export class ProviderRequestError extends Error {
 	public readonly kind: ProviderErrorKind
 	public readonly providerId: string
+	public readonly providerCode?: string
 	public readonly status?: number
 	public readonly retryAfterMs?: number
 	/**
@@ -81,6 +82,8 @@ export class ProviderRequestError extends Error {
 		this.name = 'ProviderRequestError'
 		this.kind = init.kind
 		this.providerId = init.providerId
+		const exactProviderCode = safeProviderCode(init.providerCode)
+		if (exactProviderCode !== undefined) this.providerCode = exactProviderCode
 		if (init.status !== undefined) this.status = init.status
 		if (init.retryAfterMs !== undefined) this.retryAfterMs = init.retryAfterMs
 		if (init.detail !== undefined) this.detail = init.detail
@@ -90,6 +93,32 @@ export class ProviderRequestError extends Error {
 /** Longest detail worth carrying. A provider's complaint is a sentence. */
 const DETAIL_MAX = 400
 
+/** Provider codes are identifiers, not another channel for an arbitrary response body. */
+const PROVIDER_CODE = /^[A-Za-z][A-Za-z0-9._-]{0,79}$/
+
+function safeProviderCode(value: unknown): string | undefined {
+	if (typeof value !== 'string' || !PROVIDER_CODE.test(value)) return undefined
+	return redactSecrets(value) === value ? value : undefined
+}
+
+function providerCode(value: unknown): string | undefined {
+	let decoded = value
+	if (typeof decoded === 'string') {
+		try {
+			decoded = JSON.parse(decoded)
+		} catch {
+			return undefined
+		}
+	}
+	if (typeof decoded !== 'object' || decoded === null) return undefined
+	const record = decoded as Record<string, unknown>
+	const nested =
+		typeof record.error === 'object' && record.error !== null
+			? (record.error as Record<string, unknown>).code
+			: undefined
+	return safeProviderCode(record.code ?? nested)
+}
+
 /**
  * Credential shapes to scrub before a provider's words are kept.
  *
@@ -161,11 +190,15 @@ function pickMessage(value: unknown): string | undefined {
 
 /** Is this a classified provider failure, whichever SDK copy threw it? */
 export function isProviderRequestError(err: unknown): err is ProviderRequestError {
+	const exactProviderCode = (err as { providerCode?: unknown } | null)?.providerCode
 	return (
 		err instanceof Error &&
 		err.name === 'ProviderRequestError' &&
 		typeof (err as { providerId?: unknown }).providerId === 'string' &&
-		PROVIDER_ERROR_KINDS.includes((err as { kind?: ProviderErrorKind }).kind as ProviderErrorKind)
+		PROVIDER_ERROR_KINDS.includes(
+			(err as { kind?: ProviderErrorKind }).kind as ProviderErrorKind,
+		) &&
+		(exactProviderCode === undefined || safeProviderCode(exactProviderCode) === exactProviderCode)
 	)
 }
 
@@ -393,6 +426,7 @@ export function providerVendorError(input: {
 }): ProviderRequestError {
 	const { error } = input
 	const status = vendorErrorStatus(error)
+	const exactProviderCode = providerCode(error)
 	const name = error instanceof Error ? error.name : ''
 	const message = error instanceof Error ? error.message : ''
 
@@ -411,6 +445,8 @@ export function providerVendorError(input: {
 		kind = 'server'
 	} else if (status !== undefined) {
 		kind = classifyProviderHttpStatus(status, message)
+	} else if (exactProviderCode === 'invalid_image') {
+		kind = 'bad_request'
 	} else if (bodySaysContextOverflow(message)) {
 		kind = 'context_overflow'
 	} else {
@@ -428,6 +464,7 @@ export function providerVendorError(input: {
 	return new ProviderRequestError({
 		kind,
 		providerId: input.providerId,
+		...(exactProviderCode !== undefined ? { providerCode: exactProviderCode } : {}),
 		...(status !== undefined ? { status } : {}),
 		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
 		...(detail !== undefined ? { detail } : {}),
@@ -450,9 +487,11 @@ export function providerHttpError(input: {
 	const kind = classifyProviderHttpStatus(input.status, input.body)
 	const retryAfterMs = parseRetryAfterMs(input.retryAfter, input.now ?? Date.now())
 	const detail = vendorDetail(input.body)
+	const exactProviderCode = providerCode(input.body)
 	return new ProviderRequestError({
 		kind,
 		providerId: input.providerId,
+		...(exactProviderCode !== undefined ? { providerCode: exactProviderCode } : {}),
 		status: input.status,
 		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
 		...(detail !== undefined ? { detail } : {}),

package/src/public-runtime.ts

@@ -12,6 +12,12 @@
 
 export { VERSION } from './version.js'
 
+// The opt-in model-authored-code backend. `RunCodeToolOptions.runtime` has
+// always accepted this contract; exporting the implementation and its refusal
+// class makes that signature nameable from the package root.
+export { HostCallDeniedError } from './execution/code-runtime/types.js'
+export { WorkerCodeRuntime } from './execution/code-runtime/worker.js'
+
 export {
 	CompactionConfigSchema,
 	PluginRuntimeConfigSchema,
@@ -995,6 +1001,7 @@ export { assertMemoryStatus } from './types/memory/index.js'
 export {
 	createAssistantMessage,
 	createProjectInstructionMessage,
+	createRuntimeContextMessage,
 	createSystemMessage,
 	createToolMessage,
 	hasNonTextBlocks,
@@ -1002,7 +1009,10 @@ export {
 	toolResultToText,
 	createUserMessage,
 	isProjectInstructionMessageSource,
+	isRuntimeContextMessageSource,
+	isModelContentOmission,
 	MAX_PROJECT_INSTRUCTION_SOURCE_FILES,
+	RUNTIME_CONTEXT_MESSAGE_KINDS,
 } from './types/message/index.js'
 export { isTerminalPlanStatus } from './types/plan/index.js'
 export {
@@ -1198,8 +1208,10 @@ export {
 // Inline base64 lands in the transcript, in every checkpoint, and on the
 // wire once per turn; a reference does not.
 export {
+	DEFAULT_ATTACHMENT_RESOLVE_TIMEOUT_MS,
 	AttachmentMediaTypeMismatchError,
 	AttachmentNotFoundError,
+	AttachmentResolutionTimeoutError,
 	NoAttachmentStoreError,
 	isStoredAttachment,
 	resolveAttachment,
@@ -1254,7 +1266,10 @@ export type {
 	CompactionVerificationOptions,
 	UsageSink,
 } from './compaction/verifier.js'
-export type { PluginDiscoveryOptions, PluginEnablementCapabilities } from './plugin/loader.js'
+export type {
+	PluginDiscoveryOptions,
+	PluginEnablementCapabilities,
+} from './plugin/loader.js'
 export type { ProbeContextInput } from './probe/context.js'
 export type {
 	GoalCommandScope,

package/src/public-types.ts

@@ -19,6 +19,16 @@ export type * from './types/common/index.js'
 export type { CoalesceOptions } from './streaming/coalesce.js'
 export type * from './types/bidi/index.js'
 export type * from './types/tool/index.js'
+export type {
+	CodeRunOutcome,
+	CodeRunResult,
+	CodeRuntime,
+	HostCallContext,
+	HostCallHandler,
+	HostCallRequest,
+	HostCallResult,
+	RunCodeOptions,
+} from './execution/code-runtime/types.js'
 // The directory convention: what a loaded `agent/` directory is, and what the
 // loader reports about the files it could not use.
 export type * from './directory/types.js'
@@ -336,6 +346,7 @@ export type {
 
 export type {
 	AttachmentOperationOptions,
+	AttachmentResolutionOptions,
 	AttachmentStore,
 	StoredAttachment,
 	StoredBytes,

package/src/run/reporter.ts

@@ -344,12 +344,18 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				break
 
 			case 'message_history_repaired':
-				log.warn('Repaired provider-invalid tool history', {
+				log.warn('Repaired provider-invalid conversation history', {
 					[NAMZU.RUN_ID]: event.runId,
 					'namzu.history.source': event.source,
 					'namzu.history.duplicate_tool_results_removed': event.duplicateToolResultsRemoved,
 					'namzu.history.orphaned_tool_results_removed': event.orphanedToolResultsRemoved,
 					'namzu.history.synthetic_tool_results_inserted': event.syntheticToolResultsInserted,
+					...(event.providerRejectedImagesSuppressed !== undefined
+						? {
+								'namzu.history.provider_rejected_images_suppressed':
+									event.providerRejectedImagesSuppressed,
+							}
+						: {}),
 				})
 				break