@namzu/sdk 32.0.0 → 33.0.0

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

@@ -6,7 +6,7 @@ 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'
+	readonly reason: 'provider-rejected' | 'invalid-image'
 }
 
 /** Runtime validation for persisted model-delivery metadata. */
@@ -15,7 +15,8 @@ export function isModelContentOmission(value: unknown): value is ModelContentOmi
 		typeof value === 'object' &&
 		value !== null &&
 		!Array.isArray(value) &&
-		(value as { readonly reason?: unknown }).reason === 'provider-rejected'
+		((value as { readonly reason?: unknown }).reason === 'provider-rejected' ||
+			(value as { readonly reason?: unknown }).reason === 'invalid-image')
 	)
 }
 

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/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/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
 }

package/src/types/tool/index.ts

@@ -26,6 +26,32 @@ export interface ToolRegistryRef {
  * filesystem imports into every consumer's type graph.
  */
 export interface SkillRegistryRef {
+	/**
+	 * Enumerate the metadata the model may use to discover a skill.
+	 *
+	 * Optional so an older structural registry that only supports named loads
+	 * remains a valid host. `SkillTool` refuses its list mode when this member is
+	 * absent: `names()` cannot distinguish a model skill from an operator-only
+	 * one, so treating it as a safe catalog would disclose an authority boundary.
+	 */
+	catalog?():
+		| readonly {
+				/** The name the registry accepts, which may be namespaced by its host. */
+				registeredName: string
+				description: string
+				location: string
+				allowedTools?: string
+				invocation?: 'model' | 'operator' | 'both'
+		  }[]
+		| Promise<
+				readonly {
+					registeredName: string
+					description: string
+					location: string
+					allowedTools?: string
+					invocation?: 'model' | 'operator' | 'both'
+				}[]
+		  >
 	/**
 	 * Load a skill's full body, or `undefined` for a name nobody registered.
 	 *
@@ -302,6 +328,16 @@ export interface ToolContext {
 		allowedTools: readonly string[]
 	}) => void
 
+	/**
+	 * Effective model-visible character cap for this tool result.
+	 *
+	 * Present on executor-owned calls so a tool that can paginate does so
+	 * before the generic head+tail fallback loses its middle. `0` means the
+	 * host disabled the cap; absent means a direct host invocation did not
+	 * declare one.
+	 */
+	maxToolOutputChars?: number
+
 	/**
 	 * Run another tool through the same dispatch this call came through.
 	 *
@@ -311,12 +347,17 @@ export interface ToolContext {
 	 * a property of holding a registry reference rather than a capability a
 	 * host wired deliberately.
 	 *
-	 * Available to every tool, which is worth being explicit about rather
-	 * than quietly true. Tools are host-installed code — the model cannot add
-	 * one — so the trust boundary this protects is the MODEL's reach, and
-	 * that is bounded where it has always been: `allowedTools` is enforced at
-	 * dispatch, so a tool calling through here reaches exactly what a
-	 * `tool_use` block would have.
+	 * Available only for this invocation. The executor closes it when the
+	 * visible call settles or is abandoned, aborts calls already started by
+	 * it, and waits for their executor-owned terminal records before reporting
+	 * the parent complete. Retaining the function does not retain authority.
+	 *
+	 * Tools are host-installed code — the model cannot add one — so the trust
+	 * boundary this protects is the MODEL's reach. `allowedTools` is enforced
+	 * again at dispatch. When the run has an operator authorization gate, a
+	 * nested call must be explicitly allowed by that gate; a deny or an
+	 * undecided call fails closed because another durable human review cannot
+	 * be opened from inside the already-executing parent.
 	 */
 	dispatchTool?: (
 		name: string,
@@ -648,6 +689,27 @@ export interface ToolExecutionResult extends ToolResult {
 	permissionMessage?: string
 }
 
+/**
+ * An input decoded exactly once by its owning tool registry.
+ *
+ * `input` is the detached, deeply frozen JSON review projection:
+ * authorization, approval UI, probes and audit all inspect this value. The
+ * registry privately retains a separate detached copy that
+ * {@link ToolRegistryContract.executePrepared} gives the tool. Caller-owned
+ * aliases therefore cannot change either side after preparation. A
+ * preparation is registry-owned and cannot be executed by a different
+ * registry or after that tool registration is replaced.
+ */
+export interface PreparedToolExecution {
+	readonly toolName: string
+	readonly input: unknown
+}
+
+/** Result of decoding a tool input at the execution boundary. */
+export type ToolPreparationResult =
+	| { readonly success: true; readonly prepared: PreparedToolExecution }
+	| { readonly success: false; readonly result: ToolExecutionResult }
+
 /**
  * Full tool registry contract — registration, lookup, execution, prompt generation.
  * Concrete implementation: `ToolRegistry` in `registry/tool/execute.ts`.
@@ -675,6 +737,23 @@ export interface ToolRegistryContract {
 	searchDeferred(query: string): ToolDefinition[]
 	getCallableTools(toolNames?: string[]): ToolDefinition[]
 
+	/**
+	 * Decode/transform an input once, before authorization or human review.
+	 *
+	 * The returned preparation is opaque registry authority. Implementations
+	 * must not run tool code here. They must detach both the executable value
+	 * and `prepared.input` from caller/schema aliases, and make the latter a
+	 * deeply immutable JSON projection of the exact value retained for
+	 * execution. Unsupported mutable/exotic graphs fail closed.
+	 */
+	prepareExecution(toolName: string, rawInput: unknown): ToolPreparationResult
+
+	/** Execute the exact value retained by `prepareExecution`, without parsing again. */
+	executePrepared(
+		prepared: PreparedToolExecution,
+		context: ToolContext,
+	): Promise<ToolExecutionResult>
+
 	execute(toolName: string, rawInput: unknown, context: ToolContext): Promise<ToolExecutionResult>
 
 	size(): number

package/src/types/workspace/ref.ts

@@ -49,6 +49,11 @@ export type WorkspaceBackendMeta = GitWorktreeBackendMeta
  * "which project is this directory" across sessions and process restarts.
  * The two words are close enough that the distinction has been rediscovered
  * more than once; it is written here so it does not have to be again.
+ *
+ * A persisted ref is recovery data for the backend configuration that created
+ * it, not authority for another driver instance to operate on an arbitrary
+ * resource. Reference drivers validate that affiliation before inspection,
+ * branching, or disposal.
  */
 export interface WorkspaceRef {
 	id: WorkspaceId

package/src/utils/abort.ts

@@ -1,3 +1,4 @@
+import { EventEmitter } from 'node:events'
 import { toErrorMessage } from './error.js'
 
 /**
@@ -47,6 +48,23 @@ export function abortReasonText(reason: unknown): string | undefined {
 	return text.length > 0 ? text : undefined
 }
 
+/**
+ * Subscribe to caller cancellation without raising the Node 20.0 runtime floor.
+ *
+ * `addAbortListener` cannot be hidden by another listener calling
+ * `stopImmediatePropagation`. Both branches return an explicit disposer so a
+ * completed operation does not remain attached to a long-lived caller signal.
+ */
+export function subscribeToAbort(signal: AbortSignal, listener: () => void): () => void {
+	if (typeof EventEmitter.addAbortListener === 'function') {
+		const subscription = EventEmitter.addAbortListener(signal, listener)
+		return () => subscription[Symbol.dispose]()
+	}
+
+	signal.addEventListener('abort', listener, { once: true })
+	return () => signal.removeEventListener('abort', listener)
+}
+
 export function createChildAbortController(parent: AbortController): AbortController {
 	const child = new AbortController()