@namzu/sdk 48.3.1 → 50.0.0

package/src/types/tool/index.ts

@@ -7,6 +7,7 @@ import type { CodeNavigationProvider } from '../code-navigation/index.js'
 import type { ToolResultGuardrailSpec } from '../guardrail/index.js'
 import type { SessionId, TurnId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
+import type { BackgroundJobOutputWaitOptions, BackgroundJobOutputWaitResult } from '../job/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { Sandbox } from '../sandbox/index.js'
 import type { ToolPresentation } from './presentation.js'
@@ -117,7 +118,13 @@ export interface BackgroundJobRegistryRef {
 		id: string
 		status: string
 	}
-	get(id: string): { id: string; status: string; exitCode?: number }
+	get(id: string): { id: string; status: string; exitCode?: number; error?: string }
+	/**
+	 * Resolves once the process exists or failed to start (`error` says why).
+	 * Optional: a host that cannot tell may omit it, and `bash` then replies
+	 * without waiting.
+	 */
+	awaitStarted?(id: string): Promise<{ readonly error?: string }>
 	read(
 		id: string,
 		opts?: { fromOffset?: number },
@@ -127,6 +134,7 @@ export interface BackgroundJobRegistryRef {
 		droppedBytes: number
 		status: string
 		exitCode?: number
+		error?: string
 	}
 	kill(id: string): Promise<{ id: string; status: string }>
 	list(): readonly { id: string; command: string; status: string }[]
@@ -144,12 +152,19 @@ export interface BackgroundJobRegistryRef {
 		id: string
 		status: string
 		exitCode?: number
+		error?: string
 	}>
+	/** Observe a bounded literal output condition. Does not express exit-wait intent. */
+	waitForOutput?(
+		id: string,
+		opts: BackgroundJobOutputWaitOptions,
+	): Promise<BackgroundJobOutputWaitResult>
 	/**
 	 * Say that the model is waiting on this job, so the turn stays open for it
 	 * when the model stops calling tools.
 	 *
-	 * Called by `wait_for_job` and nothing else. The kernel holds a finishing
+	 * Called only by the exit mode of `wait_for_job`. Output readiness does not
+	 * mark a job here. The kernel holds a finishing
 	 * run open — bounded, and for no model tokens — only for a job marked
 	 * here; a job nobody marked never delays a turn, which is what a dev server
 	 * or a watcher needs. Optional for the reason `waitForExit` is: a host
@@ -758,6 +773,14 @@ export interface ToolResult {
 	 * the child's turn fails with {@link ToolHandoff.reason} instead.
 	 */
 	handoff?: ToolHandoff
+	/**
+	 * What this call did, as typed fields for the PERSON's view: the exit code
+	 * and the two streams of a command, the path and size of a read, whether a
+	 * write created the file. `output` stays the model's text and is not
+	 * derived from these; a host that headlines a row reads these and never
+	 * the prose. A host-side override of the output (a redaction) drops them.
+	 */
+	facts?: import('./presentation.js').ToolFacts
 }
 
 /**
@@ -776,8 +799,10 @@ export interface ToolHandoff {
  * `bash` reads it as bash does. `sh` reads it for a shell that may be bash or
  * a POSIX shell such as `dash`: every construct the two read differently
  * makes the line opaque, so a line that is not opaque means the same in both.
+ * `cmd` identifies native Windows CMD; its commands are conservatively opaque
+ * until a matching parser is available. It is never read as POSIX shell text.
  */
-export type ShellDialect = 'bash' | 'sh'
+export type ShellDialect = 'bash' | 'sh' | 'cmd'
 
 export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInput> {
 	name: string
@@ -901,7 +926,8 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * may be bash or a POSIX shell, and every construct the two read
 	 * differently makes the line opaque, so no allow rule approves it. The
 	 * shipped `bash` tool answers `bash` when it will spawn bash on the host
-	 * and `sh` inside a sandbox, whose guest may not have bash.
+	 * and `sh` inside a sandbox, whose guest may not have bash. Native Windows
+	 * CMD reports `cmd`, whose command-specific permission reading is opaque.
 	 */
 	commandDialect?: (context: { readonly sandboxed: boolean }) => ShellDialect
 	/**
@@ -1167,12 +1193,20 @@ export interface PreparedToolExecution {
 /** 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 }
+	| {
+			readonly success: false
+			readonly result: ToolExecutionResult
+			/** Zod rejected the input; other preparation failures leave this absent. */
+			readonly inputFailure?: 'schema_validation'
+	  }
 
 export * from './repair.js'
 
 export type {
 	ToolCallView,
+	ToolFacts,
+	ToolFailureReason,
 	ToolPresentation,
 	ToolResultView,
+	ToolTextWindow,
 } from './presentation.js'

package/src/types/tool/presentation.ts

@@ -33,6 +33,20 @@ export type ToolCallView =
 			 * what did not happen ("Cancelled — nothing was saved").
 			 */
 			readonly outcome?: 'cancelled'
+			/**
+			 * For a result: a person answered No to this call at review, so it
+			 * never ran. `label` names what it was about (the file, the command)
+			 * and `note` is what the person said, in their own words and capped
+			 * at 4,000 characters. Set only from the review answer, never read
+			 * out of text; a refusal by policy does not carry it.
+			 */
+			readonly declined?: { readonly note?: string }
+			/**
+			 * For a call: what the call is about, as fields. A host headlines the
+			 * row ("Read a.ts", "Searched for export") from these and never from
+			 * the text of `label`.
+			 */
+			readonly facts?: ToolFacts
 	  }
 	/**
 	 * A change to a document. `path` is optional because not every diff is
@@ -50,6 +64,113 @@ export type ToolCallView =
 	/** A command and what it printed. */
 	| { readonly kind: 'terminal'; readonly command?: string; readonly output: string }
 
+/**
+ * A bounded window onto a block of text: the first lines, the last lines, and
+ * how much lay between. Small enough to travel in an event, and enough for a
+ * host to show "head, tail, Show more" without holding the whole output.
+ */
+export interface ToolTextWindow {
+	/** The first lines, or the whole text when it fit. */
+	readonly head: string
+	/** The last lines, present only when lines were left out between `head` and it. */
+	readonly tail?: string
+	/** Lines left out between `head` and `tail`. */
+	readonly omittedLines?: number
+	/** Lines in the whole text. */
+	readonly totalLines: number
+	/** Bytes in the whole text. */
+	readonly totalBytes: number
+}
+
+/** Why a call did not do what it was asked, as a kind a host can phrase for a person. */
+export type ToolFailureReason =
+	| 'not_found'
+	| 'permission_denied'
+	| 'not_a_file'
+	| 'already_exists'
+	| 'blocked'
+	| 'needs_administrator'
+	| 'unknown_tool'
+	| 'timed_out'
+	| 'invalid_input'
+
+/**
+ * What a call was about and what came of it, as typed fields.
+ *
+ * `output` is written for the model and its wording is the model's interface.
+ * A person is shown a different thing, and reading their screen out of the
+ * model's prose is how "STDOUT:" and "1 replacement(s)" reached it. These are
+ * the same facts the tool already knew, stated once, so a host never has to
+ * read text to learn an exit code, a file name or whether a file was created.
+ *
+ * Every field but `kind` is optional: the same shape describes a call that is
+ * still running (what it was asked) and one that finished (what it did).
+ * Paths are as the tool resolved them; a host shortens them for display.
+ */
+export type ToolFacts =
+	| {
+			readonly kind: 'command'
+			/** The command line, on the call. */
+			readonly command?: string
+			readonly exitCode?: number
+			readonly timedOut?: boolean
+			/** The signal that ended it, when one did. */
+			readonly signal?: string
+			readonly stdout?: ToolTextWindow
+			readonly stderr?: ToolTextWindow
+			/** The output was not text; nothing of it is in `stdout`/`stderr`. */
+			readonly binary?: { readonly bytes: number }
+			/** The command was handed to a background job instead of being waited on. */
+			readonly background?: true
+	  }
+	| {
+			readonly kind: 'read'
+			readonly path: string
+			/** The file is not text; the person is told so instead of being shown its bytes. */
+			readonly binary?: boolean
+			readonly bytes?: number
+			readonly totalLines?: number
+			readonly returnedLines?: number
+			/** Only a window of the file was returned. */
+			readonly partial?: boolean
+	  }
+	| {
+			readonly kind: 'search'
+			readonly pattern: string
+			readonly path?: string
+			readonly matches?: number
+			readonly filesMatched?: number
+			readonly filesSearched?: number
+			readonly truncated?: boolean
+	  }
+	| {
+			readonly kind: 'list'
+			readonly pattern: string
+			readonly path?: string
+			readonly count?: number
+			readonly truncated?: boolean
+	  }
+	| {
+			readonly kind: 'edit'
+			readonly path?: string
+			readonly replacements?: number
+	  }
+	| {
+			readonly kind: 'write'
+			readonly path: string
+			/** `wrote` when the file's earlier state could not be established. */
+			readonly operation: 'created' | 'updated' | 'unchanged' | 'wrote'
+			readonly bytes?: number
+			readonly added?: number
+			readonly removed?: number
+	  }
+	| {
+			readonly kind: 'failure'
+			readonly reason: ToolFailureReason
+			/** What it was about: a path, or the tool's name for `unknown_tool`. */
+			readonly subject?: string
+	  }
+
 /** The same shapes, for what a call produced. */
 export type ToolResultView = ToolCallView
 

package/src/utils/json-snapshot.ts

@@ -1,5 +1,14 @@
-/** Clone JSON data without invoking getters or silently dropping values. */
-export function cloneJsonValue(value: unknown, freeze: boolean, path = '$'): unknown {
+/**
+ * Clone JSON data without invoking getters or silently dropping values.
+ * Raw schema input may preserve its plain-object prototypes; prepared outputs
+ * keep the default canonical shape used by durable JSON round-trips.
+ */
+export function cloneJsonValue(
+	value: unknown,
+	freeze: boolean,
+	path = '$',
+	preserveObjectPrototype = false,
+): unknown {
 	const active = new WeakSet<object>()
 	const copies = new WeakMap<object, object>()
 
@@ -23,8 +32,16 @@ export function cloneJsonValue(value: unknown, freeze: boolean, path = '$'): unk
 		active.add(candidate)
 		try {
 			if (Array.isArray(candidate)) {
+				if (preserveObjectPrototype && Object.getPrototypeOf(candidate) !== Array.prototype) {
+					throw new TypeError(`${at} must be an ordinary array for raw preparation`)
+				}
 				const extra = Reflect.ownKeys(candidate).filter(
-					(key) => key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key)),
+					(key) =>
+						key !== 'length' &&
+						(typeof key !== 'string' ||
+							!/^(0|[1-9]\d*)$/.test(key) ||
+							(preserveObjectPrototype &&
+								(Number(key) >= candidate.length || Number(key) > 0xffff_fffe))),
 				)
 				if (extra.length > 0) throw new TypeError(`${at} has non-JSON array properties`)
 				const result: unknown[] = new Array(candidate.length)
@@ -45,12 +62,12 @@ export function cloneJsonValue(value: unknown, freeze: boolean, path = '$'): unk
 			if (prototype !== Object.prototype && prototype !== null) {
 				throw new TypeError(`${at} must be a plain JSON object`)
 			}
-			// JSON does not preserve prototypes. Canonicalize both admitted plain
-			// shapes to an ordinary object so a disk checkpoint round-trip compares
-			// equal to a fresh preparation of the same semantic value. Properties
-			// are still defined explicitly, so a literal "__proto__" key remains
-			// data rather than changing this object's prototype.
-			const result: Record<string, unknown> = {}
+			// Raw schema input can depend on its prototype. Prepared output instead
+			// canonicalizes both admitted shapes so a disk checkpoint round-trip
+			// compares equal to a fresh preparation of the same JSON value. Explicit
+			// data properties keep a literal "__proto__" key from changing either.
+			const result: Record<string, unknown> =
+				preserveObjectPrototype && prototype === null ? Object.create(null) : {}
 			copies.set(candidate, result)
 			for (const key of Reflect.ownKeys(candidate)) {
 				if (typeof key !== 'string') throw new TypeError(`${at} has a symbol property`)

package/src/utils/structured-result-json.ts

@@ -0,0 +1,10 @@
+import { cloneJsonValue } from './json-snapshot.js'
+
+/** Maximum UTF-8 JSON body retained by opt-in structured result spills. */
+export const STRUCTURED_RESULT_MAX_BYTES = 16 * 1024 * 1024
+
+/** Decode retained result evidence without coercing non-JSON values or rerunning a schema. */
+export function parseStructuredResultJson(text: unknown): unknown {
+	if (typeof text !== 'string') throw new TypeError('Structured result evidence must be JSON text')
+	return cloneJsonValue(JSON.parse(text), false)
+}