@namzu/sdk 30.2.0 → 31.0.0

package/src/types/connector/definition.ts

@@ -18,40 +18,61 @@ export interface ConnectorDefinition<TConfig = unknown> {
 	category?: ConnectorCategory
 	connectionType: ConnectionType
 	/**
-	 * **Not consulted.** A connector declaring this is not checked against
-	 * the auth an instance is actually configured with, so a mismatch
-	 * surfaces as a 401 from the upstream rather than as a refusal here.
-	 *
-	 * Worth wiring where instances are created, not at request time: the
-	 * point of declaring supported schemes is to reject a misconfiguration
-	 * before anything is sent.
+	 * Authentication schemes this connector can consume. When present, the
+	 * manager refuses an unsupported explicit credential before publishing an
+	 * instance and revalidates the effective scheme immediately before connect.
+	 * Omit only when a custom connector intentionally accepts every scheme.
 	 */
-	supportedAuth?: AuthType[]
+	supportedAuth?: readonly AuthType[]
 	configSchema: z.ZodType<TConfig, z.ZodTypeDef, unknown>
 	methods: ConnectorMethod[]
-	/** Declared, not implemented — see {@link ConnectorTrigger}. */
+	/**
+	 * Declared, not implemented — see {@link ConnectorTrigger}.
+	 *
+	 * @deprecated The SDK never reads this field or starts a run from it. Move
+	 * subscription metadata into a host-owned store before the next major.
+	 * It remains readable through `ConnectorRegistry` during this migration
+	 * release so existing host dispatchers do not break without warning.
+	 */
 	triggers?: ConnectorTrigger[]
 }
 
 export interface ConnectorConfig {
-	connectorId: ConnectorId
+	readonly connectorId: ConnectorId
 	name: string
 	auth?: AuthConfig
 	options?: Record<string, unknown>
 }
 
 export interface ConnectorInstance {
-	id: ConnectorInstanceId
-	connectorId: ConnectorId
-	config: ConnectorConfig
+	readonly id: ConnectorInstanceId
+	readonly connectorId: ConnectorId
+	readonly config: ConnectorConfig
 	status: ConnectorStatus
-	createdAt: number
+	readonly createdAt: number
 	connectedAt?: number
 	lastUsedAt?: number
 	error?: string
 }
 
-export interface ConnectorExecuteParams {
+/** What the client can establish about a connector side effect. */
+export type ConnectorRemoteOutcome = 'not_started' | 'unknown' | 'response_received'
+
+/** Whether repeating the connector call can be recommended without duplicating a side effect. */
+export type ConnectorRetrySafety = 'safe' | 'unsafe' | 'unknown'
+
+export interface ConnectorOperationOptions {
+	/** The authority for this operation. A pre-aborted signal starts no connector work. */
+	signal?: AbortSignal
+}
+
+export interface ConnectorExecutionMetadata extends Record<string, unknown> {
+	remoteOutcome?: ConnectorRemoteOutcome
+	retrySafety?: ConnectorRetrySafety
+	bodyAvailable?: boolean
+}
+
+export interface ConnectorExecuteParams extends ConnectorOperationOptions {
 	instanceId: ConnectorInstanceId
 	method: string
 	input: unknown
@@ -62,26 +83,39 @@ export interface ConnectorExecuteResult {
 	output: unknown
 	error?: string
 	durationMs: number
-	metadata?: Record<string, unknown>
+	metadata?: ConnectorExecutionMetadata
 }
 
 export interface ConnectorLifecycle<TConfig = unknown> {
 	connect(config: TConfig, auth?: AuthConfig): Promise<void>
 	disconnect(): Promise<void>
-	healthCheck(): Promise<boolean>
-	execute(method: string, input: unknown): Promise<ConnectorExecuteResult>
+	healthCheck(options?: ConnectorOperationOptions): Promise<boolean>
+	execute(
+		method: string,
+		/** ConnectorManager supplies the method schema's parsed canonical value on managed calls. */
+		input: unknown,
+		options?: ConnectorOperationOptions,
+	): Promise<ConnectorExecuteResult>
 }
 
 export type ConnectorLifecycleEvent =
 	| { type: 'connector_registered'; connectorId: ConnectorId }
 	| { type: 'connector_unregistered'; connectorId: ConnectorId }
-	| { type: 'instance_created'; instanceId: ConnectorInstanceId; connectorId: ConnectorId }
+	| {
+			type: 'instance_created'
+			instanceId: ConnectorInstanceId
+			connectorId: ConnectorId
+	  }
 	| { type: 'instance_connecting'; instanceId: ConnectorInstanceId }
 	| { type: 'instance_connected'; instanceId: ConnectorInstanceId }
 	| { type: 'instance_disconnected'; instanceId: ConnectorInstanceId }
 	| { type: 'instance_error'; instanceId: ConnectorInstanceId; error: string }
 	| { type: 'instance_removed'; instanceId: ConnectorInstanceId }
-	| { type: 'action_executing'; instanceId: ConnectorInstanceId; method: string }
+	| {
+			type: 'action_executing'
+			instanceId: ConnectorInstanceId
+			method: string
+	  }
 	| {
 			type: 'action_completed'
 			instanceId: ConnectorInstanceId

package/src/types/connector/http.ts

@@ -1,9 +1,12 @@
+import type { ConnectorRemoteOutcome, ConnectorRetrySafety } from './definition.js'
+
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD'
 
 export interface HttpConnectorConfig {
 	baseUrl: string
 	defaultHeaders?: Record<string, string>
 	timeoutMs?: number
+	maxResponseBytes?: number
 }
 
 export interface HttpRequestInput {
@@ -19,4 +22,8 @@ export interface HttpResponseOutput {
 	statusText: string
 	headers: Record<string, string>
 	body: unknown
+	bodyAvailable?: boolean
+	bodyError?: string
+	remoteOutcome?: ConnectorRemoteOutcome
+	retrySafety?: ConnectorRetrySafety
 }

package/src/types/connector/mcp.ts

@@ -74,10 +74,27 @@ export interface MCPJsonRpcMessage {
 	error?: MCPJsonRpcError
 }
 
+/** Authority for one MCP JSON-RPC request. */
+export interface MCPRequestOptions {
+	/**
+	 * Cancels the local wait and asks the peer to stop the correlated request.
+	 *
+	 * The peer notification is best effort: rejection proves that Namzu stopped
+	 * waiting, not that an already-started remote side effect was rolled back.
+	 */
+	readonly signal?: AbortSignal
+}
+
+/** Authority for one transport write and any response body it consumes. */
+export interface MCPTransportSendOptions {
+	/** A pre-aborted signal starts no transport work. */
+	readonly signal?: AbortSignal
+}
+
 export interface MCPTransport {
 	connect(): Promise<void>
 	close(): Promise<void>
-	send(message: MCPJsonRpcMessage): Promise<void>
+	send(message: MCPJsonRpcMessage, options?: MCPTransportSendOptions): Promise<void>
 	onMessage(handler: (message: MCPJsonRpcMessage) => void): void
 	onClose(handler: () => void): void
 	onError(handler: (error: Error) => void): void
@@ -91,6 +108,12 @@ export interface MCPJsonSchema {
 	[key: string]: unknown
 }
 
+/** A JSON Schema for a value, including non-object tool outputs. */
+export interface MCPValueJsonSchema {
+	type?: string
+	[key: string]: unknown
+}
+
 export interface MCPToolAnnotations {
 	title?: string
 	readOnlyHint?: boolean
@@ -111,7 +134,7 @@ export interface MCPToolDefinition {
 	 * shape never reached the model at all, which was left inferring one
 	 * from prose or from whatever the first call happened to return.
 	 */
-	outputSchema?: MCPJsonSchema
+	outputSchema?: MCPValueJsonSchema
 	annotations?: MCPToolAnnotations
 }
 
@@ -284,10 +307,8 @@ export type MCPEventListener = (event: MCPLifecycleEvent) => void
 
 type ConnectorManager = {
 	getInstance(instanceId: ConnectorInstanceId): ConnectorInstance | undefined
-	getRegistry(): {
-		get(connectorId: ConnectorId): ConnectorDefinition | undefined
-		getOrThrow(connectorId: ConnectorId): ConnectorDefinition
-	}
+	getInstanceConnectorId(instanceId: ConnectorInstanceId): ConnectorId
+	getInstanceDefinition(instanceId: ConnectorInstanceId): ConnectorDefinition
 	listConnectedInstances(): ConnectorInstance[]
 	execute(params: ConnectorExecuteParams): Promise<ConnectorExecuteResult>
 }

package/src/types/connector/tenant.ts

@@ -24,13 +24,13 @@ export interface TenantRateLimitConfig {
 }
 
 export interface CredentialRef {
-	id: CredentialId
-	connectorId: ConnectorId
-	tenantId: TenantId
-	label: string
-	authType: AuthType
-	createdAt: number
-	expiresAt?: number
+	readonly id: CredentialId
+	readonly connectorId: ConnectorId
+	readonly tenantId: TenantId
+	readonly label: string
+	readonly authType: AuthType
+	readonly createdAt: number
+	readonly expiresAt?: number
 }
 
 export interface CredentialVault {
@@ -40,7 +40,21 @@ export interface CredentialVault {
 		label: string,
 		auth: AuthConfig,
 	): Promise<CredentialRef>
+	/** Host-authority lookup. Tenant-facing code must use {@link retrieveForScope}. */
 	retrieve(credentialId: CredentialId): Promise<AuthConfig | undefined>
+	/**
+	 * Resolve only when the credential atomically belongs to both authorities.
+	 * Implementations must not perform an unscoped read followed by a separate
+	 * metadata check: a concurrent rotation must not cross the scope boundary.
+	 */
+	retrieveForScope(
+		tenantId: TenantId,
+		connectorId: ConnectorId,
+		credentialId: CredentialId,
+	): Promise<AuthConfig | undefined>
+	/** Host-authority deletion. Tenant-facing code must use {@link revokeForTenant}. */
 	revoke(credentialId: CredentialId): Promise<boolean>
+	/** Atomically delete only when the credential belongs to `tenantId`. */
+	revokeForTenant(tenantId: TenantId, credentialId: CredentialId): Promise<boolean>
 	list(tenantId: TenantId, connectorId?: ConnectorId): Promise<CredentialRef[]>
 }

package/src/types/connector/webhook.ts

@@ -1,8 +1,11 @@
+import type { ConnectorRemoteOutcome, ConnectorRetrySafety } from './definition.js'
+
 export interface WebhookConnectorConfig {
 	url: string
 	secret?: string
 	defaultHeaders?: Record<string, string>
 	timeoutMs?: number
+	maxResponseBytes?: number
 }
 
 export interface WebhookSendInput {
@@ -15,4 +18,8 @@ export interface WebhookSendOutput {
 	status: number
 	body: unknown
 	deliveredAt: number
+	bodyAvailable?: boolean
+	bodyError?: string
+	remoteOutcome?: ConnectorRemoteOutcome
+	retrySafety?: ConnectorRetrySafety
 }

package/src/types/goal/index.ts

@@ -0,0 +1,50 @@
+import type { GoalId, SessionId, TenantId } from '../ids/index.js'
+
+/** Durable lifecycle of one same-session completion goal. */
+export type GoalPhase = 'active' | 'paused' | 'blocked' | 'complete'
+
+/** Machine-routable and human-readable reason that a goal stopped. */
+export interface GoalBlockReason {
+	/** Stable lower-kebab-case policy code. */
+	readonly code: string
+	/** Non-empty explanation suitable for an operator. */
+	readonly message: string
+}
+
+/** Exact compare-and-set identity of one goal revision. */
+export interface GoalRef {
+	readonly id: GoalId
+	readonly revision: number
+}
+
+/**
+ * The current completion goal owned by one durable Session.
+ *
+ * `objective` is the text to achieve; “goal” is the stateful concept around
+ * it. Keeping those terms apart prevents the old `TopicObjective` shape from
+ * making a piece of text sound like the lifecycle that owns it.
+ */
+export interface SessionGoal extends GoalRef {
+	readonly sessionId: SessionId
+	readonly tenantId: TenantId
+	readonly objective: string
+	readonly phase: GoalPhase
+	/** Finite number of automatic rounds that may be admitted for this goal. */
+	readonly maxGoalRounds: number
+	/** Durable admissions, not a claim that the provider began or completed. */
+	readonly roundsAdmitted: number
+	/** Present exactly while {@link phase} is `blocked`. */
+	readonly blockedReason?: GoalBlockReason
+	readonly createdAt: number
+	readonly updatedAt: number
+}
+
+/** Immutable authority carried by exactly one admitted automatic turn. */
+export interface GoalRoundAuthority extends GoalRef {
+	readonly sessionId: SessionId
+	readonly tenantId: TenantId
+	readonly objective: string
+	/** One-based admitted round number. */
+	readonly round: number
+	readonly maxGoalRounds: number
+}

package/src/types/ids/index.ts

@@ -17,6 +17,8 @@ import { type Id, unsafeId } from './brand.js'
 export type RunId = Id<'run', 'RunId'>
 export type MessageId = Id<'msg', 'MessageId'>
 export type SessionId = Id<'ses', 'SessionId'>
+/** Identifies one durable completion goal across its revisions. */
+export type GoalId = Id<'goal', 'GoalId'>
 export type ToolCallId = Id<'call', 'ToolCallId'>
 /**
  * Provider-issued tool-use identifier surfaced on the streaming event bus.

package/src/types/message/index.ts

@@ -1,3 +1,5 @@
+import type { GoalId } from '../ids/index.js'
+
 export type MessageRole = 'system' | 'user' | 'assistant' | 'tool'
 
 export type CacheHint = 'cache' | 'ephemeral' | 'none'
@@ -156,10 +158,12 @@ export interface BaseMessage {
 	 * one") therefore aged out at the same rate as chatter, and no
 	 * positional rule could express it.
 	 *
-	 * Protection is transitive across a tool pair: pinning a
-	 * `tool_result` also pins the assistant turn that called it, and
-	 * pinning that turn pins every result answering it. Half a pair is not
-	 * a smaller history, it is one the provider rejects.
+	 * Protection is transitive across a provider-valid turn: pinning an
+	 * assistant message also pins the user message that opened its turn;
+	 * pinning a `tool_result` additionally pins the assistant turn that called
+	 * it, and pinning that call pins every result answering it. Half a pair,
+	 * or an assistant-first retained tail, is not a smaller history — it is
+	 * one the provider rejects.
 	 *
 	 * Pinned turns are exempt from the reclaim that keeps a long run
 	 * alive, so this is a budget the setter spends. Nothing caps it: a cap
@@ -179,12 +183,111 @@ export interface UserMessage extends BaseMessage {
 	content: string
 	/** Optional image or document attachments. */
 	attachments?: readonly MessageAttachment[]
+	/** Host provenance for user-role input that was not authored by the operator. */
+	source?: UserMessageSource
+}
+
+/** One automatic continuation prompt admitted against a durable SessionGoal. */
+export interface GoalRoundMessageSource {
+	readonly type: 'goal-round'
+	readonly goalId: GoalId
+	readonly objective: string
+	/** Post-admission goal revision that authorized this prompt. */
+	readonly goalRevision: number
+	readonly round: number
+	readonly maxGoalRounds: number
+}
+
+/**
+ * A host-owned snapshot of the instruction files currently in force.
+ *
+ * Paths are canonical project-relative `AGENTS.md` paths. The text lives on
+ * the user message itself; the paths are provenance used to re-read the
+ * authoritative files after a restart rather than trusting persisted prose as
+ * standing policy.
+ */
+export interface ProjectInstructionMessageSource {
+	readonly type: 'project-instructions'
+	readonly files: readonly string[]
+}
+
+export type UserMessageSource = GoalRoundMessageSource | ProjectInstructionMessageSource
+
+/** A bounded source list keeps untrusted persisted metadata cheap to validate. */
+export const MAX_PROJECT_INSTRUCTION_SOURCE_FILES = 256
+
+/** Runtime validation for persisted or JavaScript-authored instruction provenance. */
+export function isProjectInstructionMessageSource(
+	value: unknown,
+): value is ProjectInstructionMessageSource {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+	const candidate = value as {
+		readonly type?: unknown
+		readonly files?: unknown
+	}
+	if (
+		candidate.type !== 'project-instructions' ||
+		!Array.isArray(candidate.files) ||
+		candidate.files.length === 0 ||
+		candidate.files.length > MAX_PROJECT_INSTRUCTION_SOURCE_FILES
+	) {
+		return false
+	}
+	const seen = new Set<string>()
+	for (const file of candidate.files) {
+		if (typeof file !== 'string' || file.length === 0 || file.length > 1024) return false
+		if (
+			file.includes('\\') ||
+			file.startsWith('/') ||
+			/^[A-Za-z]:/.test(file) ||
+			file.includes('\0') ||
+			(file !== 'AGENTS.md' && !file.endsWith('/AGENTS.md'))
+		) {
+			return false
+		}
+		const parts = file.split('/')
+		if (parts.some((part) => part.length === 0 || part === '.' || part === '..')) return false
+		if (seen.has(file)) return false
+		seen.add(file)
+	}
+	return true
+}
+
+/**
+ * The configured model route that produced or is about to receive a message.
+ *
+ * `chainIndex` is part of the identity on purpose: one chain may contain the
+ * same provider and model more than once with different credentials or base
+ * URLs. Names alone do not prove that provider-native replay state belongs to
+ * the target member.
+ */
+export interface ProviderRoute {
+	readonly providerId: string
+	readonly model: string
+	/** 0 is the primary provider; later values are declared fallbacks. */
+	readonly chainIndex: number
+}
+
+/** Provenance and adapter-private replay state for a model-produced message. */
+export interface AssistantMessageSource extends ProviderRoute {
+	readonly type: 'model'
+	/**
+	 * Lossless-JSON state a provider adapter needs to restore native response
+	 * metadata such as reasoning signatures.
+	 *
+	 * Opaque to the SDK. A target adapter must validate its kind, version,
+	 * route, and correspondence with the durable message before using it.
+	 * Missing or unusable state means provider-neutral history, never inferred
+	 * native replay from matching names alone.
+	 */
+	readonly replayState?: unknown
 }
 
 /**
  * An opaque reasoning block produced by the model.
  *
- * Deliberately opaque: the SDK stores and replays it, never interprets it.
+ * Deliberately opaque: the SDK stores it and leaves native replay to the
+ * adapter that owns the message's {@link AssistantMessageSource} route.
  * A provider whose reasoning blocks are signed requires the preceding
  * assistant turn to be echoed back **verbatim** — thinking blocks and
  * their cryptographic `signature` included — whenever a `tool_result`
@@ -209,10 +312,12 @@ export interface AssistantMessage extends BaseMessage {
 	role: 'assistant'
 	content: string | null
 	toolCalls?: ToolCall[]
+	/** Which configured model route produced this turn. */
+	source?: AssistantMessageSource
 	/**
 	 * Reasoning the model emitted before this turn's content, in order.
-	 * Replayed verbatim and ahead of the text/tool blocks — see
-	 * {@link ReasoningBlock}.
+	 * Stored verbatim; native replay additionally requires validated
+	 * {@link AssistantMessageSource.replayState} owned by the target route.
 	 */
 	reasoning?: readonly ReasoningBlock[]
 	/**
@@ -239,7 +344,11 @@ export interface AssistantMessage extends BaseMessage {
  */
 export type ToolResultBlock =
 	| { readonly type: 'text'; readonly text: string }
-	| { readonly type: 'image'; readonly data: string; readonly mediaType: string }
+	| {
+			readonly type: 'image'
+			readonly data: string
+			readonly mediaType: string
+	  }
 	| DocumentAttachment
 
 /**
@@ -280,13 +389,32 @@ export function createSystemMessage(content: string, cacheHint?: CacheHint): Sys
 export function createUserMessage(
 	content: string,
 	attachments?: readonly MessageAttachment[],
+	source?: UserMessageSource,
 ): UserMessage {
 	return {
 		role: 'user',
 		content,
 		timestamp: Date.now(),
 		...(attachments && attachments.length > 0 ? { attachments } : {}),
+		...(source ? { source } : {}),
+	}
+}
+
+/** Build the retained user-context message that carries live project policy. */
+export function createProjectInstructionMessage(
+	content: string,
+	files: readonly string[],
+): UserMessage {
+	const source: ProjectInstructionMessageSource = {
+		type: 'project-instructions',
+		files,
+	}
+	if (!isProjectInstructionMessageSource(source)) {
+		throw new TypeError(
+			'Project instruction paths must be unique, canonical project-relative paths.',
+		)
 	}
+	return { ...createUserMessage(content, undefined, source), retain: true }
 }
 
 export function createAssistantMessage(
@@ -294,6 +422,7 @@ export function createAssistantMessage(
 	toolCalls?: ToolCall[],
 	reasoning?: readonly ReasoningBlock[],
 	citations?: readonly Citation[],
+	source?: AssistantMessageSource,
 ): AssistantMessage {
 	return {
 		role: 'assistant',
@@ -301,6 +430,7 @@ export function createAssistantMessage(
 		toolCalls,
 		...(reasoning && reasoning.length > 0 ? { reasoning } : {}),
 		...(citations && citations.length > 0 ? { citations } : {}),
+		...(source ? { source } : {}),
 		timestamp: Date.now(),
 	}
 }
@@ -319,4 +449,8 @@ export function createToolMessage(
 	}
 }
 
-export { hasNonTextBlocks, toToolResultBlocks, toolResultToText } from './content.js'
+export {
+	hasNonTextBlocks,
+	toToolResultBlocks,
+	toolResultToText,
+} from './content.js'

package/src/types/plugin/index.ts

@@ -175,12 +175,14 @@ export interface PluginHookContext {
 	 */
 	readonly response?: Readonly<PluginModelResponse>
 	/**
-	 * Aborts when this hook's deadline expires.
+	 * Aborts when this hook's run is cancelled or its deadline expires.
 	 *
-	 * The runtime stops waiting on a slow hook either way, but without a
-	 * signal the hook itself never learns it was abandoned: an HTTP request
-	 * inside it keeps a socket open and its eventual result is written into
-	 * a run that moved on without it. A hook doing I/O should forward this.
+	 * The runtime stops waiting on a slow hook either way, but in-process
+	 * JavaScript cannot be forcibly stopped. Without a signal the hook itself
+	 * never learns it was abandoned: an HTTP request inside it keeps a socket
+	 * open and its eventual side effects can happen after the run moved on. A
+	 * hook doing I/O must forward this signal and stop publishing when it
+	 * aborts.
 	 */
 	readonly signal?: AbortSignal
 }

package/src/types/provider/chat.ts

@@ -1,5 +1,5 @@
 import type { TokenUsage } from '../common/index.js'
-import type { Message, ReasoningBlock, ToolCall } from '../message/index.js'
+import type { Message, ProviderRoute, ReasoningBlock, ToolCall } from '../message/index.js'
 import type { LLMToolSchema } from '../tool/index.js'
 
 export type ToolChoice =
@@ -26,6 +26,14 @@ export interface CacheControl {
 export interface ChatCompletionParams {
 	model: string
 	messages: Message[]
+	/**
+	 * Exact configured member receiving this call.
+	 *
+	 * Set by the query/fallback runtime so provider adapters can decide whether
+	 * historical native replay state belongs to this route. Direct primary
+	 * calls may omit it; a provider then uses its own id, `model`, and index 0.
+	 */
+	providerRoute?: ProviderRoute
 	tools?: LLMToolSchema[]
 	/**
 	 * Provider hint naming tools whose model-facing JSON Schema should be
@@ -73,14 +81,19 @@ export interface ChatCompletionParams {
 	 * default the runtime received blocks it then discarded. Neither half
 	 * was expressible.
 	 *
-	 * Drivers that do not support it ignore the field.
+	 * A driver that has no extended-thinking wire must refuse `enabled` and
+	 * `adaptive` rather than return an ordinary answer that looks honoured.
+	 * `disabled` may be accepted as an explicit no-op by a driver that was
+	 * already going to leave thinking off.
 	 */
 	thinking?: ThinkingConfig
 
 	/**
 	 * How much work to put into the response. See {@link ReasoningEffort}.
 	 *
-	 * Drivers that do not support it ignore the field.
+	 * A driver with no effort concept must refuse the field rather than silently
+	 * use the model default. Drivers whose accepted levels vary by model resolve
+	 * that narrower set according to their documented provider policy.
 	 */
 	effort?: ReasoningEffort
 }
@@ -142,8 +155,24 @@ export interface ThinkingConfig {
  * In adaptive mode it is the primary depth lever — low effort may skip
  * thinking entirely on easy input. In manual mode `budgetTokens` sets depth
  * and effort does not move it.
+ *
+ * This union describes caller intent, not a claim that every provider or model
+ * accepts every level. For example, `minimal` and `none` are distinct levels on
+ * different compatible model generations, `max` is available only on newer
+ * families, and `ultra` can be a host-level value rather than a model wire
+ * capability. A provider must resolve the selected model's actual set before
+ * transport or leave the vendor to refuse an unknown compatible-endpoint
+ * extension explicitly.
  */
-export type ReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+export type ReasoningEffort =
+	| 'none'
+	| 'minimal'
+	| 'low'
+	| 'medium'
+	| 'high'
+	| 'xhigh'
+	| 'max'
+	| 'ultra'
 
 export interface ChatCompletionResponse {
 	id: string
@@ -154,6 +183,8 @@ export interface ChatCompletionResponse {
 		toolCalls?: ToolCall[]
 		/** Reasoning blocks the model emitted, in original block order. */
 		reasoning?: readonly ReasoningBlock[]
+		/** Adapter-private lossless-JSON state for restoring native metadata. */
+		replayState?: unknown
 		/** Passages this turn cites, in the order the model made them. */
 		citations?: readonly import('../message/index.js').Citation[]
 	}