@namzu/sdk 31.1.0 → 33.0.0

package/src/types/computer-use/index.ts

@@ -109,6 +109,25 @@ export type ComputerUseResult =
 	| { readonly type: 'cursor_position'; readonly point: Point }
 	| { readonly type: 'ok' }
 
+/**
+ * A state-changing desktop action started, but its subprocess did not report
+ * a clean completion. The desktop may already have changed, so treating this
+ * as an ordinary failure and automatically replaying the action is unsafe.
+ *
+ * Host packages throw an error carrying this shape. The SDK recognises it
+ * structurally so separately installed host and SDK versions do not need to
+ * share an error constructor identity.
+ */
+export interface ComputerUseOutcomeUnknown {
+	readonly code: 'computer_use_outcome_unknown'
+	readonly action: ComputerUseAction['type']
+	readonly outcome: 'unknown'
+	readonly retrySafety: 'unsafe'
+	readonly timedOut: boolean
+	readonly exitCode: number
+	readonly message: string
+}
+
 // ---------------------------------------------------------------------------
 // Host interface — the core abstraction. Mirrors Sandbox/SandboxProvider shape.
 // Implementations live outside @namzu/sdk (e.g. @namzu/computer-use).

package/src/types/connector/execution-context.ts

@@ -13,6 +13,7 @@ export type {
 export type {
 	CommandOptions,
 	CommandResult,
+	CommandTermination,
 	CommandExecutor,
 	RemoteCommandHandler,
 } from '../execution/index.js'
@@ -33,6 +34,8 @@ export interface LocalExecutionContextConfig extends ExecutionContextBase {
 	fsAccess: boolean
 	envVars?: Record<string, string>
 	shell?: string
+	/** Retained bytes per stdout/stderr stream. Defaults to 4 MiB; maximum 64 MiB. */
+	maxOutputBytes?: number
 }
 
 export interface RemoteExecutionContextConfig extends ExecutionContextBase {

package/src/types/execution/index.ts

@@ -5,22 +5,67 @@ export type ExecutionCapability = 'filesystem' | 'process' | 'network' | 'shell'
 export interface CommandOptions {
 	cwd?: string
 	env?: Record<string, string>
+	/**
+	 * Caller-owned cancellation for this command.
+	 *
+	 * A compliant executor may accept this only when it can prove that command
+	 * admission never happened or that admitted work reached quiescence before
+	 * settling. `LocalExecutionContext` owns that guarantee for its process
+	 * group. `RemoteExecutionContext` refuses this option because its generic
+	 * executor seam has no reservation and terminal-acknowledgement protocol;
+	 * use the `Sandbox.exec()` contract for cancellable remote execution.
+	 */
+	signal?: AbortSignal
+	/**
+	 * Command deadline in milliseconds; `0` disables the deadline.
+	 *
+	 * `LocalExecutionContext` owns its spawned process group through stdio
+	 * close, first requesting termination and then forcing it after a bounded
+	 * grace period. Remote handlers define how this option is enforced at their
+	 * own execution boundary.
+	 */
 	timeoutMs?: number
 	shell?: string | boolean
 }
 
+export type CommandTermination =
+	| {
+			/** Caller cancellation was already present, so no process was admitted. */
+			origin: 'caller'
+			admitted: false
+	  }
+	| {
+			/** The first Namzu-owned cause that requested termination. */
+			origin: 'caller' | 'timeout' | 'teardown'
+			admitted: true
+			/** The direct child's actual close signal, when Node reported one. */
+			signal?: string
+	  }
+
 export interface CommandResult {
-	exitCode: number
+	/** Numeric process exit, or `null` when no numeric exit exists. */
+	exitCode: number | null
 	stdout: string
 	stderr: string
+	/** Whether the executor retained only part of stdout. Absent means unknown. */
+	stdoutTruncated?: boolean
+	/** Whether the executor retained only part of stderr. Absent means unknown. */
+	stderrTruncated?: boolean
 	durationMs: number
+	/** Present only when Namzu requested termination or refused pre-aborted admission. */
+	termination?: CommandTermination
 }
 
 export interface CommandExecutor {
 	executeCommand(command: string, args?: string[], options?: CommandOptions): Promise<CommandResult>
 }
 
+/**
+ * @deprecated Use `CommandExecutor` so command arguments retain their
+ * boundaries at the remote execution seam.
+ */
 export interface RemoteCommandHandler {
+	/** @deprecated Use `CommandExecutor.executeCommand()`. */
 	executeRemote(command: string, options?: CommandOptions): Promise<CommandResult>
 }
 

package/src/types/hitl/index.ts

@@ -71,6 +71,17 @@ export interface ToolCallSummary {
 	name: string
 	input: unknown
 	isDestructive: boolean
+	/**
+	 * Operator-policy verdict attached to the exact input shown for review.
+	 *
+	 * Persisted with a durable review so a later process cannot treat a call
+	 * the gate denied as approved merely because the human approved a mixed
+	 * batch. Absent only on checkpoints written before this field existed.
+	 */
+	authorization?: {
+		decision: 'allow' | 'deny' | 'review'
+		reason?: string
+	}
 }
 
 export interface ToolModification {

package/src/types/message/index.ts

@@ -4,6 +4,22 @@ export type MessageRole = 'system' | 'user' | 'assistant' | 'tool'
 
 export type CacheHint = 'cache' | 'ephemeral' | 'none'
 
+/** Why durable rich content must not be sent to a model again. */
+export interface ModelContentOmission {
+	readonly reason: 'provider-rejected' | 'invalid-image'
+}
+
+/** Runtime validation for persisted model-delivery metadata. */
+export function isModelContentOmission(value: unknown): value is ModelContentOmission {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		!Array.isArray(value) &&
+		((value as { readonly reason?: unknown }).reason === 'provider-rejected' ||
+			(value as { readonly reason?: unknown }).reason === 'invalid-image')
+	)
+}
+
 /**
  * An image attached to a user message (vision input). Drivers that declare
  * vision support emit it alongside the text. A shipped driver that cannot
@@ -22,6 +38,8 @@ export interface ImageAttachment {
 	readonly data: string
 	/** IANA media type, e.g. `image/png`, `image/jpeg`, `image/webp`. */
 	readonly mediaType: string
+	/** Durable delivery state; the original image bytes remain in history. */
+	readonly modelOmission?: ModelContentOmission
 }
 
 /**
@@ -212,7 +230,38 @@ export interface ProjectInstructionMessageSource {
 	readonly files: readonly string[]
 }
 
-export type UserMessageSource = GoalRoundMessageSource | ProjectInstructionMessageSource
+/**
+ * Why the runtime, rather than the operator, inserted one user-role message.
+ *
+ * Providers require several pieces of host context to occupy the `user` role:
+ * a continuation after an output ceiling, reviewer feedback, task completion
+ * notices, and similar prompts. Role alone therefore cannot answer who wrote a
+ * durable message. Keeping that provenance on the message prevents a resumed
+ * transcript, export, or previous-prompt editor from presenting kernel context
+ * as something the operator typed.
+ */
+export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
+	'advisory',
+	'answer-review',
+	'auto-continuation',
+	'limit-finalization',
+	'steering',
+	'structured-output',
+	'task-completion',
+] as const
+
+export type RuntimeContextMessageKind = (typeof RUNTIME_CONTEXT_MESSAGE_KINDS)[number]
+
+/** Host-generated context carried in the provider's required user role. */
+export interface RuntimeContextMessageSource {
+	readonly type: 'runtime-context'
+	readonly kind: RuntimeContextMessageKind
+}
+
+export type UserMessageSource =
+	| GoalRoundMessageSource
+	| ProjectInstructionMessageSource
+	| RuntimeContextMessageSource
 
 /** A bounded source list keeps untrusted persisted metadata cheap to validate. */
 export const MAX_PROJECT_INSTRUCTION_SOURCE_FILES = 256
@@ -254,6 +303,22 @@ export function isProjectInstructionMessageSource(
 	return true
 }
 
+/** Runtime validation for durable host-generated user-message provenance. */
+export function isRuntimeContextMessageSource(
+	value: unknown,
+): value is RuntimeContextMessageSource {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+	const candidate = value as {
+		readonly type?: unknown
+		readonly kind?: unknown
+	}
+	return (
+		candidate.type === 'runtime-context' &&
+		typeof candidate.kind === 'string' &&
+		(RUNTIME_CONTEXT_MESSAGE_KINDS as readonly string[]).includes(candidate.kind)
+	)
+}
+
 /**
  * The configured model route that produced or is about to receive a message.
  *
@@ -349,6 +414,7 @@ export type ToolResultBlock =
 			readonly type: 'image'
 			readonly data: string
 			readonly mediaType: string
+			readonly modelOmission?: ModelContentOmission
 	  }
 	| DocumentAttachment
 
@@ -401,6 +467,17 @@ export function createUserMessage(
 	}
 }
 
+/** Build provider-visible context that no operator authored. */
+export function createRuntimeContextMessage(
+	content: string,
+	kind: RuntimeContextMessageKind,
+): UserMessage {
+	return createUserMessage(content, undefined, {
+		type: 'runtime-context',
+		kind,
+	})
+}
+
 /** Build the retained user-context message that carries live project policy. */
 export function createProjectInstructionMessage(
 	content: string,

package/src/types/plugin/index.ts

@@ -10,6 +10,7 @@ import {
 } from '../../constants/plugin/index.js'
 import type { PluginId, RunId } from '../ids/index.js'
 import type { Message, ToolResultContent } from '../message/index.js'
+import type { CancelCause } from '../run/cancel-cause.js'
 import type { ToolResult } from '../tool/index.js'
 
 // ---------------------------------------------------------------------------
@@ -85,6 +86,7 @@ export function assertPluginContributionType(type: PluginContributionType): void
 export type PluginHookEvent =
 	| 'run_start'
 	| 'run_end'
+	| 'run_interrupt'
 	| 'pre_tool_use'
 	| 'post_tool_use'
 	| 'pre_llm_call'
@@ -96,6 +98,7 @@ export function assertPluginHookEvent(event: PluginHookEvent): void {
 	switch (event) {
 		case 'run_start':
 		case 'run_end':
+		case 'run_interrupt':
 		case 'pre_tool_use':
 		case 'post_tool_use':
 		case 'pre_llm_call':
@@ -147,6 +150,15 @@ export interface PluginHookContext {
 	readonly toolInput?: unknown
 	readonly toolResult?: ToolResult
 	readonly iteration?: number
+	/**
+	 * Why the run was stopped, on `run_interrupt`.
+	 *
+	 * That hook is emitted only for a root run carrying the explicit `user`
+	 * cause. Keeping the field typed as the complete cause vocabulary lets a
+	 * host narrow normally and leaves room for a future, deliberate expansion
+	 * without overloading `event` or an error sentence.
+	 */
+	readonly cancelCause?: CancelCause
 
 	/**
 	 * The request about to be sent, on `pre_llm_call`.
@@ -176,6 +188,9 @@ export interface PluginHookContext {
 	readonly response?: Readonly<PluginModelResponse>
 	/**
 	 * Aborts when this hook's run is cancelled or its deadline expires.
+	 * `run_interrupt` is the exception: the run is already cancelled, so its
+	 * handler receives a fresh signal that represents only the bounded cleanup
+	 * deadline. The original verdict is available as `cancelCause`.
 	 *
 	 * The runtime stops waiting on a slow hook either way, but in-process
 	 * JavaScript cannot be forcibly stopped. Without a signal the hook itself

package/src/types/provider/error.ts

@@ -11,11 +11,14 @@ export type ProviderErrorKind =
  * Serializable provider-failure metadata carried by failed runs and events.
  *
  * No response body, URL, or `cause` belongs here. `detail` is the one thing
- * the provider itself said, and it arrives scrubbed — see below.
+ * the provider itself said, and it arrives scrubbed. `providerCode` preserves
+ * a bounded machine identifier independently of wording — see below.
  */
 export interface ProviderErrorInfo {
 	readonly kind: ProviderErrorKind
 	readonly providerId: string
+	/** Provider-defined machine code, preserved only when it is a bounded safe token. */
+	readonly providerCode?: string
 	readonly status?: number
 	readonly retryAfterMs?: number
 	/**

package/src/types/provider/interface.ts

@@ -163,6 +163,24 @@ export interface LLMProvider {
 		thinking?: import('./chat.js').ThinkingConfig,
 	): readonly import('./chat.js').ReasoningEffort[] | undefined
 
+	/**
+	 * The effort a model uses when a request omits an explicit level.
+	 *
+	 * A directional control cannot infer this from the menu: a model may start
+	 * anywhere in its advertised order, so treating "default" as an item before
+	 * the first level can make an increase lower the effective effort. The
+	 * method is optional because many drivers cannot establish a model-owned
+	 * default. A present method returning `undefined` means this particular
+	 * model is unknown.
+	 *
+	 * When both this and {@link LLMProvider.reasoningEffortLevelsFor} return an
+	 * exact value, the default must be a member of that menu.
+	 */
+	reasoningEffortDefaultFor?(
+		model: string,
+		thinking?: import('./chat.js').ThinkingConfig,
+	): import('./chat.js').ReasoningEffort | undefined
+
 	/**
 	 * Legacy effort menu which cannot distinguish an unknown model from a model
 	 * with no effort support.

package/src/types/run/events.ts

@@ -320,7 +320,12 @@ type CoreRunEvent =
 			 * draws eleven siblings where there is one call with eleven
 			 * children.
 			 */
-			via?: { readonly tool: string; readonly toolUseId: ToolUseId }
+			via?: {
+				readonly tool: string
+				readonly toolUseId: ToolUseId
+				/** The code runtime's request id, when that was the dispatch source. */
+				readonly runtimeToolCallId?: string
+			}
 	  }
 	/**
 	 * A tool saying how far along it is.
@@ -334,7 +339,10 @@ type CoreRunEvent =
 	 * duration: the host could show that a tool had started and then nothing
 	 * at all until it either finished or timed out. The model never sees
 	 * these; they answer "is it still working?", which is a question only a
-	 * human asks.
+	 * human asks. It is latest state rather than a lossless log: the executor
+	 * bounds each UTF-8 message and coalesces intermediate updates when the
+	 * live consumer falls behind. Complete output belongs to the terminal
+	 * `tool_completed` result.
 	 */
 	| {
 			type: 'tool_progress'
@@ -412,7 +420,11 @@ type CoreRunEvent =
 			isError: boolean
 			/** See {@link tool_executing}'s `via`. Carried on both, so a
 			 * consumer can pair them without holding the start event. */
-			via?: { readonly tool: string; readonly toolUseId: ToolUseId }
+			via?: {
+				readonly tool: string
+				readonly toolUseId: ToolUseId
+				readonly runtimeToolCallId?: string
+			}
 			/**
 			 * Wall-clock the tool took. Computed since the first version of
 			 * the executor but only ever logged; a host asking "which tool
@@ -603,10 +615,12 @@ type CoreRunEvent =
 	| {
 			type: 'message_history_repaired'
 			runId: RunId
-			source: 'fresh-history' | 'abandoned-checkpoint'
+			source: 'fresh-history' | 'abandoned-checkpoint' | 'provider-rejected-image'
 			duplicateToolResultsRemoved: number
 			orphanedToolResultsRemoved: number
 			syntheticToolResultsInserted: number
+			/** Exact number of durable image occurrences withheld from later requests. */
+			providerRejectedImagesSuppressed?: number
 	  }
 	| {
 			type: 'token_usage_updated'

package/src/types/sandbox/index.ts

@@ -141,22 +141,27 @@ export interface SandboxExecOptions {
 		readonly data: string
 	}) => void
 	/**
-	 * Cancellation for the command. A backend that honours it kills the
-	 * process; one that does not simply ignores it, so this is additive.
+	 * Cancellation for the command. A backend that accepts it must terminate
+	 * the owned process or prove that admission never happened. A backend that
+	 * cannot make that guarantee must refuse before admission; silently
+	 * ignoring the signal is not a compliant implementation.
 	 *
 	 * Without it a Stop (or a per-tool deadline) could only ever abandon
 	 * the *wait* — the sandboxed process kept running after the host
 	 * believed the run had been cancelled.
 	 *
-	 * **Who honours it.** The in-process local sandbox does: the signal is
-	 * merged with the call's own deadline and reaches `spawn`, so the child
-	 * dies. The remote backends do not, and deliberately: their wire has no
-	 * cancel op, so aborting the request would abandon the wait and leave the
-	 * command running — the failure above, wearing the appearance of a fix.
-	 * They will honour it when their protocols carry a cancel.
+	 * **Who honours it.** The in-process local sandbox does: the run owns a
+	 * listener until the process group's shared stdio closes, and terminates
+	 * that group directly. The HTTP-container backends in `@namzu/sandbox` also
+	 * do: a
+	 * current peer reserves an execution before admission and confirms its
+	 * cancellation over a separate control request. Older worker and microVM
+	 * images are refused when this option is present, because aborting only the HTTP
+	 * or framed data request would abandon the wait and leave the command
+	 * running.
 	 *
-	 * Passing it is therefore always safe and never harmful; whether it takes
-	 * effect depends on the backend.
+	 * Every backend shipped by Namzu therefore either enforces the signal or
+	 * returns an explicit unsupported error before running the command.
 	 */
 	readonly signal?: AbortSignal
 }