@namzu/sdk 31.1.0 → 32.0.0

package/src/types/message/index.ts

@@ -4,6 +4,21 @@ 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'
+}
+
+/** 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'
+	)
+}
+
 /**
  * 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 +37,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 +229,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 +302,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 +413,7 @@ export type ToolResultBlock =
 			readonly type: 'image'
 			readonly data: string
 			readonly mediaType: string
+			readonly modelOmission?: ModelContentOmission
 	  }
 	| DocumentAttachment
 
@@ -401,6 +466,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/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/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/tool/index.ts

@@ -68,7 +68,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 +161,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 +278,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 +297,10 @@ 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
 
 	/**
 	 * Run another tool through the same dispatch this call came through.
@@ -275,7 +318,11 @@ export interface ToolContext {
 	 * dispatch, so a tool calling through here reaches exactly what a
 	 * `tool_use` block would have.
 	 */
-	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 +334,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 +390,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.
 	 */
@@ -626,4 +687,8 @@ export interface ToolRegistryContract {
 
 export * from './repair.js'
 
-export type { ToolCallView, ToolPresentation, ToolResultView } from './presentation.js'
+export type {
+	ToolCallView,
+	ToolPresentation,
+	ToolResultView,
+} from './presentation.js'