@namzu/sdk 46.0.0 → 48.1.0

package/src/types/message/index.ts

@@ -1,4 +1,4 @@
-import type { GoalId } from '../ids/index.js'
+import type { GoalId, MessageId } from '../ids/index.js'
 
 export type MessageRole = 'system' | 'user' | 'assistant' | 'tool'
 
@@ -105,7 +105,7 @@ export interface Citation {
  * An attachment whose bytes are held by a store, not by the message.
  *
  * Structural rather than an import from `store/attachment`, so this types
- * module keeps depending on nothing — the same reasoning `ToolRegistryRef`
+ * module keeps depending on nothing — the same reasoning `ToolsView`
  * gives. `store/attachment` owns the resolution and its refusals; this is
  * the shape a message may carry.
  *
@@ -144,18 +144,106 @@ export interface ToolCall {
 	 * JSON payload, while provider/runtime recovery state lives here.
 	 */
 	metadata?: {
+		/**
+		 * The streamed arguments could not be read, and `function.arguments`
+		 * was normalized to `"{}"`. Set for every unreadable call, cut off or
+		 * malformed alike: the name predates that distinction, and
+		 * {@link inputError} is what says which it was.
+		 */
 		inputTruncated?: boolean
 		/**
-		 * The partial argument buffer as it arrived, when the stream cut off
-		 * mid-JSON. `function.arguments` is normalized to `"{}"` in that
-		 * case so tool args stay clean, which leaves this as the only record
-		 * of what the model was actually saying — and a `repairToolCall`
-		 * hook has nothing to repair without it.
+		 * The argument buffer as it arrived, when it could not be read.
+		 * `function.arguments` is normalized to `"{}"` in that case so tool
+		 * args stay clean, which leaves this as the only record of what the
+		 * model was actually saying — and a `repairToolCall` hook has nothing
+		 * to repair without it.
 		 */
 		partialArguments?: string
+		/**
+		 * Why the arguments could not be read. Present with
+		 * {@link inputTruncated} on every call the runtime marked; absent on a
+		 * call marked by an older runtime, which recorded only the flag.
+		 */
+		inputError?: ToolInputError
 	}
 }
 
+/**
+ * Why a streamed tool call's arguments could not be read. See
+ * {@link ToolInputError}.
+ */
+export type ToolInputErrorReason = 'truncated' | 'malformed'
+
+/**
+ * A tool call whose streamed arguments did not parse as JSON, and why.
+ *
+ * An output limit, a content filter or a dropped stream stops a response
+ * wherever it is, so only the call the response was streaming at that moment
+ * can have been cut off: the last one, with nothing the model streamed after
+ * it. For that call the finish reason decides, never the text:
+ *
+ * - `truncated` — the response stopped before the model closed the
+ *   arguments. It reached its output limit (`finishReason: 'length'`), a
+ *   content filter stopped it (`'content_filter'`), or the stream ended
+ *   without reporting a finish reason at all.
+ * - `malformed` — the response finished normally (`'stop'` or
+ *   `'tool_calls'`) and the arguments still were not valid JSON.
+ *
+ * Every other unreadable call is `malformed`, whatever the finish reason:
+ * the model moved on to more text, reasoning or another call, so it had
+ * finished writing this one.
+ */
+export interface ToolInputError {
+	readonly reason: ToolInputErrorReason
+	/** How the response ended, as the provider reported it. Absent when the stream reported nothing. */
+	readonly finishReason?: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+	/**
+	 * `'context_window'` when a `'length'` finish was the model's context
+	 * window rather than its output token limit (`StreamChunk.finishDetail`).
+	 */
+	readonly finishDetail?: 'context_window'
+	/** The JSON parser's own message. */
+	readonly parseError: string
+	/**
+	 * Zero-based character offset in the arguments where parsing failed: the
+	 * first character that cannot continue valid JSON, or their length when
+	 * the text simply ended. Found by scanning the arguments, so it is there
+	 * when {@link parseError} names no position, as for a bare `True` or
+	 * `None`.
+	 */
+	readonly offset?: number
+	/** How many characters of arguments arrived. */
+	readonly length: number
+	/**
+	 * How many characters the response streamed before this call began: its
+	 * text, its visible reasoning and the arguments of earlier tool calls.
+	 * Text a driver adds of its own is not counted. For a `truncated` call,
+	 * which nothing followed, this plus {@link length} is everything the
+	 * response streamed as text. It is not everything the response spent:
+	 * reasoning a provider does not stream (encrypted, summarised, or only
+	 * counted) uses the output limit too, and {@link outputTokens} and
+	 * {@link reasoningTokens} are what show it.
+	 */
+	readonly precedingLength: number
+	/**
+	 * The output tokens the whole response used, reasoning included, as the
+	 * provider reported them when it ended. Present on a `truncated` call when
+	 * the provider reported any.
+	 *
+	 * After an output limit it says whether the visible text accounts for the
+	 * limit: when most of the output went to reasoning, or to anything else
+	 * the stream did not carry, the call is not what filled the response, and
+	 * the model is told so rather than told to shrink the call.
+	 */
+	readonly outputTokens?: number
+	/**
+	 * Of {@link outputTokens}, the tokens the provider says went to reasoning.
+	 * Present only when the provider reports that split; absent means unknown,
+	 * not zero.
+	 */
+	readonly reasoningTokens?: number
+}
+
 export interface BaseMessage {
 	/**
 	 * Widened from `string | null` so `ToolMessage` can carry content
@@ -167,6 +255,22 @@ export interface BaseMessage {
 	content: string | null | readonly ToolResultBlock[]
 	timestamp?: number
 	cacheHint?: CacheHint
+	/**
+	 * The id of the durable `message` record this message was written as, or
+	 * a `message_replaced` record's `targetMessageId` when a guardrail,
+	 * review or structured-output override replaced its content in place.
+	 * Absent means the kernel has not recorded this exact message: a host
+	 * just constructed it, or it is a compaction's own summary (a bulk
+	 * spilled or inline array, which carries no per-message id — see
+	 * `docs/sdk/session-log.md`).
+	 *
+	 * Set by the kernel alone, never by a caller: `query()` stamps every
+	 * message it folds from the session log or records fresh, on `Turn.messages`,
+	 * on the messages `onConversationMessages` reports, and on a checkpoint's
+	 * restored messages. A caller that mints its own id here gets `conflict`
+	 * on the next turn — this log never recorded it under that name.
+	 */
+	readonly id?: MessageId
 	/**
 	 * Exempt this message from compaction and from tool-result clearing.
 	 *
@@ -248,6 +352,8 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'auto-continuation',
 	'job-exit',
 	'limit-finalization',
+	'peer-message',
+	'peer-notice',
 	'repeat-call',
 	'steering',
 	'step-context',
@@ -445,6 +551,13 @@ export type ToolResultBlock =
  */
 export type ToolResultContent = string | readonly ToolResultBlock[]
 
+/** A schema reveal bound to the source that contributed that exact tool. */
+export interface ToolRevealReceipt {
+	readonly name: string
+	readonly sourceId: string
+	readonly sourceKind: import('../toolset/index.js').ToolSourceKind
+}
+
 export interface ToolMessage extends BaseMessage {
 	role: 'tool'
 	content: ToolResultContent
@@ -460,6 +573,19 @@ export interface ToolMessage extends BaseMessage {
 	 * fired and namzu relied on prose formatting to convey failure.
 	 */
 	isError?: boolean
+	/**
+	 * Source-bound receipts for deferred schemas loaded by a successful
+	 * {@link ToolResult.reveals} (`types/tool/index.ts`). The executor writes
+	 * these onto the message it built from that result.
+	 *
+	 * This is what `ToolManager.availability` (`toolsets/manager.ts`) scans
+	 * the post-compaction history for, instead of a mutable activation map:
+	 * a deferred tool is active once a matching receipt appears after the
+	 * last compaction summary and the host still reports it ready. Persisted
+	 * like any other message field — a session log or checkpoint already
+	 * carries this too, with nothing extra to serialize.
+	 */
+	revealedTools?: readonly ToolRevealReceipt[]
 }
 
 export type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage
@@ -539,12 +665,14 @@ export function createToolMessage(
 	content: ToolResultContent,
 	toolCallId: string,
 	isError?: boolean,
+	revealedTools?: readonly ToolRevealReceipt[],
 ): ToolMessage {
 	return {
 		role: 'tool',
 		content,
 		toolCallId,
 		...(isError !== undefined ? { isError } : {}),
+		...(revealedTools && revealedTools.length > 0 ? { revealedTools } : {}),
 		timestamp: Date.now(),
 	}
 }

package/src/types/plugin/index.ts

@@ -326,26 +326,41 @@ export function assertPluginHookResult(result: PluginHookResult): asserts result
 	}
 }
 
-export interface PluginHookDefinition {
-	readonly event: PluginHookEvent
-	readonly handler: (context: PluginHookContext) => Promise<PluginHookResult>
-	/**
-	 * Lower runs first. Default 100.
-	 *
-	 * Order was install order, which is neither declared nor stable — it
-	 * depends on when each plugin happened to be installed. That is fine
-	 * for hooks that only observe, and wrong for the ones that decide:
-	 * `executeHooks` SHORT-CIRCUITS on `skip` and `error`, so a hook that
-	 * denies a dangerous command only gets to deny it if it runs before
-	 * whatever else stops the chain. A guard that fires depending on
-	 * installation history is not a guard.
-	 *
-	 * Ties keep registration order, so plugins that never set a priority
-	 * behave exactly as before. Convention: guards below 100, observers
-	 * above.
-	 */
-	readonly priority?: number
-}
+/** Actions the query can interpret for a particular hook event. */
+export type PluginHookResultFor<E extends PluginHookEvent> = E extends 'user_prompt_submit'
+	? Extract<PluginHookResult, { action: 'continue' | 'annotate' | 'skip' | 'error' }>
+	: E extends 'pre_tool_use'
+		? Extract<PluginHookResult, { action: 'continue' | 'skip' | 'modify' | 'error' }>
+		: E extends 'post_tool_use'
+			? Extract<PluginHookResult, { action: 'continue' | 'replace' | 'retry' | 'error' }>
+			: E extends 'turn_interrupt' | 'session_start' | 'session_end'
+				? Extract<PluginHookResult, { action: 'continue' }>
+				: Extract<PluginHookResult, { action: 'continue' | 'error' }>
+
+/** The event and its handler verdict stay correlated, including in hook arrays. */
+export type PluginHookDefinition<E extends PluginHookEvent = PluginHookEvent> =
+	E extends PluginHookEvent
+		? {
+				readonly event: E
+				readonly handler: (context: PluginHookContext) => Promise<PluginHookResultFor<E>>
+				/**
+				 * Lower runs first. Default 100.
+				 *
+				 * Order was install order, which is neither declared nor stable — it
+				 * depends on when each plugin happened to be installed. That is fine
+				 * for hooks that only observe, and wrong for the ones that decide:
+				 * `executeHooks` SHORT-CIRCUITS on `skip` and `error`, so a hook that
+				 * denies a dangerous command only gets to deny it if it runs before
+				 * whatever else stops the chain. A guard that fires depending on
+				 * installation history is not a guard.
+				 *
+				 * Ties keep registration order, so plugins that never set a priority
+				 * behave exactly as before. Convention: guards below 100, observers
+				 * above.
+				 */
+				readonly priority?: number
+			}
+		: never
 
 // ---------------------------------------------------------------------------
 // Plugin MCP server config
@@ -367,6 +382,8 @@ export interface PluginManifest {
 	readonly version: string
 	readonly description: string
 	readonly author?: string
+	/** Plugin-authored request context, present only while this plugin is enabled. */
+	readonly instructions?: string
 	readonly tools?: readonly string[]
 	readonly skills?: readonly string[]
 	readonly hooks?: readonly string[]
@@ -391,6 +408,7 @@ export const PluginManifestSchema = z.object({
 	version: z.string().min(1),
 	description: z.string().min(1),
 	author: z.string().optional(),
+	instructions: z.string().min(1).optional(),
 	tools: z.array(z.string()).max(MAX_TOOLS_PER_PLUGIN).optional(),
 	skills: z.array(z.string()).max(MAX_SKILLS_PER_PLUGIN).optional(),
 	hooks: z.array(z.string()).max(MAX_HOOKS_PER_PLUGIN).optional(),
@@ -419,7 +437,12 @@ export interface PluginDefinition {
 // ---------------------------------------------------------------------------
 
 export type PluginLifecycleEvent =
-	| { type: 'plugin_installed'; pluginId: PluginId; name: string; scope: PluginScope }
+	| {
+			type: 'plugin_installed'
+			pluginId: PluginId
+			name: string
+			scope: PluginScope
+	  }
 	| { type: 'plugin_enabled'; pluginId: PluginId; name: string }
 	| { type: 'plugin_disabled'; pluginId: PluginId; name: string }
 	| { type: 'plugin_uninstalled'; pluginId: PluginId; name: string }

package/src/types/provider/chat.ts

@@ -193,5 +193,10 @@ export interface ChatCompletionResponse {
 		citations?: readonly import('../message/index.js').Citation[]
 	}
 	finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+	/**
+	 * `'context_window'` when a `'length'` finish was the model's context
+	 * window rather than the output token limit; see `StreamChunk.finishDetail`.
+	 */
+	finishDetail?: 'context_window'
 	usage: TokenUsage
 }

package/src/types/provider/config.ts

@@ -38,9 +38,14 @@ export interface MockToolCall {
 	/** Fragment size for the argument JSON; smaller exercises more buffering. */
 	argChunkSize?: number
 	/**
-	 * Omit the block-close signal and stop mid-JSON, reproducing the
-	 * provider cutting a tool call off at `max_tokens`. The consumer should
-	 * mark the call `inputTruncated` rather than crashing on a parse.
+	 * Send only the first half of the arguments, omit the block-close signal
+	 * and finish with `'length'` (unless the turn sets `finishReason`),
+	 * reproducing the provider cutting a tool call off at `max_tokens`. The
+	 * response ends at this call, as an output limit ends it: later calls in
+	 * the turn's `toolCalls` are not streamed. The consumer should mark the
+	 * call `inputTruncated` with a `truncated` `inputError` rather than
+	 * crashing on a parse; under a scripted `finishReason` of `'stop'` or
+	 * `'tool_calls'` it is `malformed` instead.
 	 */
 	truncateArguments?: boolean
 	/**

package/src/types/provider/stream.ts

@@ -29,8 +29,28 @@ export interface StreamChunk {
 		}
 
 		content?: string
+		/**
+		 * Who wrote {@link content}. Absent means the model. `'driver'` marks
+		 * text a driver adds of its own after the model's output, such as a
+		 * list of the sources a hosted search used. It is shown and kept in
+		 * the message like any other text, but it is not output the model
+		 * produced: the turn loop does not read it as the model moving on from
+		 * its last tool call, which would turn a call the output limit cut
+		 * off into a malformed one.
+		 */
+		contentOrigin?: 'driver'
 		/** Identity and phase of this content fragment, when the provider supplies them. */
 		textPart?: Omit<import('../message/index.js').AssistantTextPart, 'text'>
+		/**
+		 * Fragments of tool calls. `index` is what groups them: every fragment
+		 * of one call carries the same index, and no other call in the
+		 * response uses it. The call's `id` and `function.name` may arrive on
+		 * any of its fragments, including after arguments; arguments that
+		 * arrive first are kept for the call at their index. The turn loop gives
+		 * a call whose id never arrives, here or on `toolCallEnd`, an id of its
+		 * own. A second id on an index another call holds is refused, by the
+		 * turn loop and by `collectChatCompletion`.
+		 */
 		toolCalls?: Array<{
 			index: number
 			id?: string
@@ -52,6 +72,12 @@ export interface StreamChunk {
 		 * leave this undefined; the orchestrator infers from
 		 * end-of-stream instead.
 		 *
+		 * `id` fills in the call's id when no fragment carried one. The
+		 * completion always carries the id the call was announced with, and
+		 * follows the announcement: a close with an empty `id` for a call no
+		 * fragment named, or for a call whose name has not arrived, is
+		 * settled when the stream ends instead.
+		 *
 		 * Added 2026-05-01 (ses_001-tool-stream-events A9).
 		 */
 		toolCallEnd?: {
@@ -93,6 +119,19 @@ export interface StreamChunk {
 		citation?: import('../message/index.js').Citation
 	}
 	finishReason?: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+	/**
+	 * Which limit a `'length'` finish reached, when it was not the output
+	 * token limit: `'context_window'` when the response filled the model's
+	 * context window (a stop reason such as `model_context_window_exceeded`
+	 * or `model_length`).
+	 *
+	 * Both stop the output where it stands, so both are `'length'`, and a
+	 * tool call either one cut off is truncated. They differ in what can
+	 * follow: after the output limit the turn loop asks the model to continue
+	 * a reply it cut off mid-text, and after the context window there is no
+	 * room to continue into. Set only with `finishReason: 'length'`.
+	 */
+	finishDetail?: 'context_window'
 	usage?: TokenUsage
 	error?: string
 

package/src/types/sandbox/index.ts

@@ -466,7 +466,7 @@ export interface SandboxDestroyOptions {
  *  - `azureFileShare` — mount an Azure Files SMB share into the
  *    container. Used by managed Azure Container Instances (incl.
  *    Standby Pool) which have no host filesystem to bind from; the
- *    Vandal-side host provisions a per-task share before claim and
+ *    host provisions a per-task share before claim and
  *    the ACI backend translates this variant to ACI's `volume +
  *    azureFile` shape.
  */

package/src/types/session/events.ts

@@ -1096,11 +1096,22 @@ type CoreSessionEvent =
 			toolUseId: ToolUseId
 			input: unknown
 			/**
-			 * True when the provider stream ended before the tool JSON
-			 * arguments closed. `input` stays a sanitized object so public
-			 * consumers never receive internal recovery sentinels.
+			 * True when the streamed arguments could not be read, whether the
+			 * response stopped before they closed or they were not valid JSON;
+			 * {@link inputError} says which. `input` is then `{}`, a sanitized
+			 * object, so public consumers never receive internal recovery
+			 * sentinels.
 			 */
 			inputTruncated?: boolean
+			/** Why the arguments could not be read. Present exactly when `inputTruncated` is. */
+			inputError?: import('../message/index.js').ToolInputError
+			/**
+			 * The arguments as they arrived, when they could not be read: at most
+			 * the first 16 384 characters, with `inputError.length` saying how many
+			 * there were. The whole text stays on the assistant message, as
+			 * `ToolCall.metadata.partialArguments`.
+			 */
+			partialArguments?: string
 	  }
 
 /**

package/src/types/session/sub-session.ts

@@ -100,6 +100,8 @@ export interface SubSession {
 	failureMode: FailureMode
 	completionMode: CompletionMode
 	workspaceId: WorkspaceId | null
+	/** Keep this delegated workspace when the child ends or its session is archived. */
+	workspaceRetention?: 'retain'
 	/**
 	 * For interventions, the immutable artifact being addressed. Chains form
 	 * a strict acyclic DAG — see session-hierarchy.md §4.5.