@namzu/sdk 31.1.0 → 33.0.0

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.
 	 *
@@ -68,7 +94,10 @@ export interface SkillRegistryRef {
  * outlives, or is billed to, somebody else's run.
  */
 export interface BackgroundJobRegistryRef {
-	start(params: { command: string; workingDirectory: string }): { id: string; status: string }
+	start(params: { command: string; workingDirectory: string }): {
+		id: string
+		status: string
+	}
 	get(id: string): { id: string; status: string; exitCode?: number }
 	read(
 		id: string,
@@ -158,6 +187,39 @@ export type ToolPauseOutcome =
 
 export type RequestToolPause = (request: ToolPauseRequest) => Promise<ToolPauseOutcome>
 
+/**
+ * Where one tool execution entered the runtime from.
+ *
+ * The executor owns this value. A nested caller supplies only its private
+ * operation context to {@link ToolContext.dispatchTool}; the executor derives
+ * the parent id from the context it already issued, so a tool cannot relabel
+ * itself as somebody else's child.
+ */
+export type ToolCallSource =
+	| { readonly kind: 'direct' }
+	| { readonly kind: 'nested'; readonly parentToolUseId: string }
+	| {
+			readonly kind: 'code'
+			readonly parentToolUseId: string
+			/** The code runtime's id, unique within the parent program. */
+			readonly runtimeToolCallId: string
+	  }
+
+/**
+ * Operation authority a trusted tool may narrow when it dispatches another
+ * tool.
+ *
+ * `signal` is fused with the parent call's signal; it can revoke authority
+ * earlier but can never extend the parent's lifetime. `runtimeToolCallId`
+ * identifies one request inside a model-authored program. The executor still
+ * chooses the child's event identity and the parent lineage; durable pause
+ * ownership stays with the model-issued ancestor present in the checkpoint.
+ */
+export interface ToolDispatchOptions {
+	readonly signal?: AbortSignal
+	readonly runtimeToolCallId?: string
+}
+
 export interface ToolContext {
 	runId: RunId
 	workingDirectory: string
@@ -242,7 +304,11 @@ export interface ToolContext {
 			}>
 		}
 		readonly search?: {
-			search(request: { query: string; limit?: number; signal?: AbortSignal }): Promise<{
+			search(request: {
+				query: string
+				limit?: number
+				signal?: AbortSignal
+			}): Promise<{
 				query: string
 				hits: readonly { title: string; url: string; snippet?: string }[]
 			}>
@@ -257,7 +323,20 @@ export interface ToolContext {
 	 * the next batch — a skill loaded alongside other calls must not
 	 * retroactively refuse them.
 	 */
-	adoptSkillScope?: (scope: { skill: string; allowedTools: readonly string[] }) => void
+	adoptSkillScope?: (scope: {
+		skill: string
+		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.
@@ -268,14 +347,23 @@ 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, input: unknown) => Promise<ToolResult>
+	dispatchTool?: (
+		name: string,
+		input: unknown,
+		options?: ToolDispatchOptions,
+	) => Promise<ToolResult>
 
 	/**
 	 * The `tool_use_id` of the assistant block that triggered this
@@ -287,6 +375,14 @@ export interface ToolContext {
 	 */
 	toolUseId?: string
 
+	/**
+	 * How this execution entered the tool registry.
+	 *
+	 * Present on executor-owned calls. Optional because a host may invoke a
+	 * tool directly outside a run and construct its own minimal context.
+	 */
+	source?: ToolCallSource
+
 	/**
 	 * Raise a durable pause and wait for a human to resolve it.
 	 *
@@ -335,10 +431,16 @@ export interface ToolContext {
 	 * timed out.
 	 *
 	 * Fire-and-forget and never throws, so a tool can call it freely
-	 * without wrapping it. The model never sees these: progress answers
-	 * "is it still working?", which is a question only a human asks, and
-	 * putting it in the conversation would spend tokens telling the model
-	 * something it cannot act on.
+	 * without wrapping it. This is latest state, not a log: while a host is
+	 * consuming one update, later calls replace the single pending update.
+	 * Each published message is capped at 8 KiB of UTF-8 with a visible
+	 * omission marker, and every accepted update settles before that call's
+	 * terminal event. Put complete output in `ToolResult`, not here.
+	 *
+	 * The model never sees these: progress answers "is it still working?",
+	 * which is a question only a human asks, and putting it in the
+	 * conversation would spend tokens telling the model something it cannot
+	 * act on.
 	 *
 	 * Absent when the executing surface has no event stream to write to.
 	 */
@@ -587,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`.
@@ -614,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
@@ -626,4 +766,8 @@ export interface ToolRegistryContract {
 
 export * from './repair.js'
 
-export type { ToolCallView, ToolPresentation, ToolResultView } from './presentation.js'
+export type {
+	ToolCallView,
+	ToolPresentation,
+	ToolResultView,
+} from './presentation.js'

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()