@namzu/sdk 49.0.0 → 50.1.0

package/src/toolsets/manager.ts

@@ -8,6 +8,7 @@ import { ToolResultHalted, screenToolResult } from '../registry/tool/screen.js'
 import { GENAI, NAMZU, toolSpanName } from '../telemetry/attributes.js'
 import { recordToolCall } from '../telemetry/metrics.js'
 import { getTracer } from '../telemetry/runtime-accessors.js'
+import { failureFactsFromError } from '../tools/failure-facts.js'
 import { isTrustedReadOnly } from '../tools/trusted-read-only.js'
 import { wrapUntrusted } from '../tools/untrusted-envelope.js'
 import type { ToolResultGuardrailSpec } from '../types/guardrail/index.js'
@@ -25,6 +26,8 @@ import type {
 	ToolTierConfig,
 	ToolsView,
 } from '../types/tool/index.js'
+import type { ToolFacts } from '../types/tool/presentation.js'
+import { awaitWithAbort } from '../utils/await-with-abort.js'
 import { toErrorMessage } from '../utils/error.js'
 import { cloneJsonValue as clonePreparedInput } from '../utils/json-snapshot.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
@@ -670,10 +673,55 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 	prepareExecution(toolName: string, rawInput: unknown): ToolPreparationResult {
 		const tool = this.getOrThrow(toolName)
 		const parseResult = tool.inputSchema.safeParse(rawInput)
+		return this.finalizePreparation(tool, rawInput, parseResult)
+	}
+
+	/**
+	 * Decode an input once, including asynchronous schema refinements and transforms.
+	 * JSON-compatible raw values are detached synchronously before validation can
+	 * yield. Non-JSON host values retain the schema's input semantics; callers must
+	 * not mutate them while preparation is pending. The prepared output must still
+	 * be immutable JSON, as with `prepareExecution`.
+	 * Cancellation stops waiting and prevents publication, but cannot stop schema
+	 * work that does not cooperate with cancellation.
+	 */
+	async prepareExecutionAsync(
+		toolName: string,
+		rawInput: unknown,
+		signal?: AbortSignal,
+	): Promise<ToolPreparationResult> {
+		signal?.throwIfAborted()
+		const tool = this.getOrThrow(toolName)
+		let validationInput = rawInput
+		try {
+			validationInput = clonePreparedInput(rawInput, false, '$', true)
+		} catch {
+			// A schema may normalize a Date or another host value into JSON.
+			// Raw input safety must not narrow that existing normalization domain.
+		}
+		signal?.throwIfAborted()
+		const asyncParse = tool.inputSchema.safeParseAsync
+		const operation =
+			typeof asyncParse === 'function'
+				? asyncParse.call(tool.inputSchema, validationInput)
+				: Promise.resolve(tool.inputSchema.safeParse(validationInput))
+		const parseResult = await awaitWithAbort(operation, signal)
+		signal?.throwIfAborted()
+		return this.finalizePreparation(tool, validationInput, parseResult, signal)
+	}
+
+	private finalizePreparation(
+		tool: ToolDefinition,
+		rawInput: unknown,
+		parseResult: ReturnType<ToolDefinition['inputSchema']['safeParse']>,
+		signal?: AbortSignal,
+	): ToolPreparationResult {
+		const toolName = tool.name
 		if (!parseResult.success) {
 			return {
 				success: false,
 				result: this.validationFailure(tool, rawInput, parseResult.error),
+				inputFailure: 'schema_validation',
 			}
 		}
 
@@ -683,6 +731,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 			retainedInput = clonePreparedInput(parseResult.data, false)
 			reviewInput = clonePreparedInput(retainedInput, true)
 		} catch (err) {
+			signal?.throwIfAborted()
 			const message = `Tool "${toolName}" produced an input that cannot be safely prepared for review and execution: ${toErrorMessage(err)}`
 			this.log.error('Prepared tool input could not be detached for review and execution', {
 				'namzu.tool.name': toolName,
@@ -694,6 +743,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 			}
 		}
 
+		signal?.throwIfAborted()
 		const prepared = Object.freeze({ toolName, input: reviewInput })
 		this.preparations.set(prepared, { tool, input: retainedInput })
 		return { success: true, prepared }
@@ -728,7 +778,8 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 	): Promise<ToolExecutionResult> {
 		let preparation: ToolPreparationResult
 		try {
-			preparation = this.prepareExecution(toolName, rawInput)
+			preparation = await this.prepareExecutionAsync(toolName, rawInput, context.abortSignal)
+			context.abortSignal?.throwIfAborted()
 		} catch (err) {
 			return this.rejectPreparationWithClosedSpan(toolName, context, err)
 		}
@@ -921,6 +972,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						success: false,
 						output: '',
 						error: `Tool "${toolName}" execution failed: ${errorMessage}`,
+						...failureFactsField(err),
 					}
 				}
 			} finally {
@@ -1067,3 +1119,8 @@ function describeRequiredInput(schema: { _def?: unknown }): string {
 		return 'Could not introspect required parameters.'
 	}
 }
+
+function failureFactsField(err: unknown): { facts?: ToolFacts } {
+	const facts = failureFactsFromError(err)
+	return facts ? { facts } : {}
+}

package/src/types/acp/index.ts

@@ -1,5 +1,10 @@
+import type { ReviewMode } from '../../runtime/query/review-policy.js'
 import type { SerializableHostCommand } from '../command/index.js'
-import type { ToolCallView } from '../tool/presentation.js'
+import type { AssistantTextPart, DocumentAttachment, ImageAttachment } from '../message/index.js'
+import type { ReasoningEffort } from '../provider/chat.js'
+import type { MessageStopReason } from '../session/stop-reason.js'
+import type { TaskStatus } from '../task/index.js'
+import type { ToolCallView, ToolFacts } from '../tool/presentation.js'
 
 /**
  * The wire shapes an editor or an orchestrator sees.
@@ -34,6 +39,12 @@ export interface AcpInitializeParams extends AcpClientCapabilities {
 }
 
 export interface AcpInitializeResult {
+	/** True only when the host gateway opts into inline user attachment delivery. */
+	readonly promptAttachments?: boolean
+	/** True only when this host applies captured effort and review settings per prompt. */
+	readonly promptOptions?: boolean
+	/** Optional, explicitly installed Namzu host methods; core ACP peers can ignore them. */
+	readonly extensions?: readonly string[]
 	readonly protocolVersion: number
 	readonly agentInfo: { readonly name: string; readonly version: string }
 	/**
@@ -71,6 +82,25 @@ export interface AcpSessionLoadParams {
 	readonly cwd?: string
 }
 
+/**
+ * The file change a pending `edit` or `write` call would make, computed by the
+ * agent with the tool's own apply code against the file as it is now.
+ *
+ * Optional on the wire: an older client ignores it, and an agent that cannot
+ * establish it (a binary or oversized file, a path outside the turn's roots, a
+ * call the tool would refuse) simply omits it.
+ */
+export interface AcpFileChangePreview {
+	/** The absolute path the tool resolves the call's `path` to. */
+	readonly path: string
+	/** The current body, or `null` when the call would create the file. */
+	readonly before: string | null
+	/** The body after the call. */
+	readonly after: string
+	/** True when `before` and `after` were cut to a bounded size. */
+	readonly truncated?: boolean
+}
+
 /** What the agent asks the client before running a tool batch. */
 export interface AcpRequestPermissionParams {
 	readonly sessionId: string
@@ -79,6 +109,8 @@ export interface AcpRequestPermissionParams {
 		readonly name: string
 		readonly input: unknown
 		readonly isDestructive: boolean
+		/** For `edit` and `write` calls, when the agent could compute it. */
+		readonly preview?: AcpFileChangePreview
 	}[]
 }
 
@@ -93,6 +125,14 @@ export interface AcpRequestPermissionResult {
 	readonly outcome: 'approve' | 'approve_all' | 'reject'
 	/** Why, for a rejection. Reaches the MODEL, so it is worth writing. */
 	readonly feedback?: string
+	/**
+	 * For a rejection: set by a client that is reporting a person's No, so
+	 * the session record can say the call was declined by them rather than
+	 * refused by policy. `note` is what they said, without any wrapper the
+	 * client put around it in `feedback`, which is for the model. A bare
+	 * `reject` without this is recorded as it always was.
+	 */
+	readonly declined?: { readonly note?: string }
 }
 
 export interface AcpFsReadParams {
@@ -110,10 +150,17 @@ export interface AcpFsWriteParams {
 	readonly content: string
 }
 
+export interface AcpPromptOptions {
+	readonly effort?: ReasoningEffort
+	readonly permissionMode?: ReviewMode
+}
 export interface AcpSessionPromptParams {
 	readonly sessionId: string
 	/** The operator's message, already plain text. */
 	readonly prompt: string
+	/** Inline user-owned bytes; store references are not admitted across this boundary. */
+	readonly attachments?: readonly (ImageAttachment | DocumentAttachment)[]
+	readonly options?: AcpPromptOptions
 }
 
 /** Why a prompt stopped, in the peer's vocabulary. */
@@ -121,6 +168,8 @@ export type AcpStopReason = 'end_turn' | 'cancelled' | 'refused' | 'error' | 'ma
 
 export interface AcpSessionPromptResult {
 	readonly stopReason: AcpStopReason
+	/** Exact runtime reason, when available; a cancelled preparation also names cancellation. */
+	readonly reason?: string
 }
 
 export interface AcpSessionCancelParams {
@@ -136,9 +185,45 @@ export interface AcpSessionCancelParams {
  */
 export type AcpSessionUpdate =
 	/** A fragment of the assistant's answer. */
-	| { readonly kind: 'agent_message_chunk'; readonly text: string }
+	| {
+			readonly kind: 'agent_message_chunk'
+			readonly text: string
+			readonly messageId?: string
+			readonly turnId?: string
+			readonly iteration?: number
+			/** Public provider phase only; absent means the provider did not name one. */
+			readonly phase?: AssistantTextPart['phase']
+			readonly textPart?: Omit<AssistantTextPart, 'text'>
+	  }
+	/** A completed message; content selects the provider's explicit final-answer parts. */
+	| {
+			readonly kind: 'agent_message'
+			readonly status: 'completed'
+			readonly messageId?: string
+			readonly turnId?: string
+			readonly iteration?: number
+			readonly content?: string
+			readonly textParts?: readonly AssistantTextPart[]
+			readonly stopReason: MessageStopReason
+	  }
 	/** A fragment of the assistant's reasoning, when the model emits any. */
-	| { readonly kind: 'agent_thought_chunk'; readonly text: string }
+	| {
+			readonly kind: 'agent_thought_chunk'
+			readonly text: string
+			readonly messageId?: string
+			readonly turnId?: string
+			readonly iteration?: number
+			readonly blockId?: string
+	  }
+	/** Reasoning boundaries also represent redacted blocks, without exposing their payload. */
+	| {
+			readonly kind: 'agent_thought'
+			readonly status: 'pending' | 'completed'
+			readonly messageId?: string
+			readonly turnId?: string
+			readonly iteration?: number
+			readonly blockId?: string
+	  }
 	/**
 	 * A tool call, rendered by the TOOL rather than by this bridge.
 	 *
@@ -153,11 +238,72 @@ export type AcpSessionUpdate =
 			readonly title: string
 			readonly status: 'pending' | 'completed' | 'failed'
 			readonly view: ToolCallView
+			/**
+			 * What a finished call did, as typed fields (`ToolResult.facts`): the
+			 * exit code and streams of a command, the path of a read. A host builds
+			 * the person's view from these and not from the text in `view`.
+			 */
+			readonly facts?: ToolFacts
+			/** Runtime-measured execution duration, present on completed calls when known. */
+			readonly durationMs?: number
+			/** Live progress for this call; preserve its prior presentation while updating. */
+			readonly progress?: {
+				readonly message: string
+				readonly fraction?: number
+			}
+	  }
+	/**
+	 * A model call failed transiently and will be tried again after `delayMs`.
+	 * Lets a client say "waiting, retrying in N seconds" instead of a silent spinner.
+	 * Carries no provider body, header or credential.
+	 */
+	| {
+			readonly kind: 'provider_retry'
+			/** 1-based attempt that just failed. */
+			readonly attempt: number
+			readonly maxRetries: number
+			readonly delayMs: number
+			/** The HTTP status of the failed attempt, when there was one. */
+			readonly status?: number
+			/** The provider asked for this delay itself (for example `Retry-After`). */
+			readonly serverDirected: boolean
+			readonly turnId?: string
 	  }
 	/** The turn is over. Carries the same reason the prompt result will. */
-	| { readonly kind: 'turn_ended'; readonly stopReason: AcpStopReason }
+	| {
+			readonly kind: 'turn_ended'
+			readonly stopReason: AcpStopReason
+			readonly error?: string
+			readonly turnId?: string
+			/** The settled answer's actual message identity, when the runtime recorded one. */
+			readonly messageId?: string
+			/** Exact runtime reason; for example, paused remains distinct from cancelled. */
+			readonly reason?: string
+			/** Authoritative settled answer. An empty string deliberately clears rejected output. */
+			readonly result?: string
+	  }
 
 export interface AcpSessionUpdateNotification {
 	readonly sessionId: string
 	readonly update: AcpSessionUpdate
 }
+
+/** A full replacement row from the existing session planning-task store. */
+export interface AcpTask {
+	readonly taskId: string
+	readonly subject: string
+	readonly status: TaskStatus
+	/** An explicit empty list clears prior dependencies. */
+	readonly blockedBy: readonly string[]
+	/** Absence clears any previously displayed owner. */
+	readonly owner?: string
+	/** What the task reads as while it is being worked on, such as "Running the tests". */
+	readonly activeForm?: string
+}
+
+/** Optional Namzu planning notification; distinct from delegated worker state. */
+export interface AcpTaskUpdate {
+	readonly sessionId: string
+	readonly task: AcpTask
+	readonly deleted?: true
+}

package/src/types/agent/base.ts

@@ -8,6 +8,7 @@ import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { ResumeHandler } from '../hitl/index.js'
 import type { SessionId, TenantId, TurnId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
+import type { DurableInboundSource } from '../message/inbound-delivery.js'
 import type { Message } from '../message/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { ProjectId, TopicId } from '../session/ids.js'
@@ -111,6 +112,8 @@ export interface BaseAgentConfig {
 	 * until the turn ended.
 	 */
 	inboundMessages?: () => import('../message/index.js').Message[]
+	/** Requires an explicit sessionLog; acknowledgement precedes inference. */
+	durableInbound?: DurableInboundSource
 
 	/** Live project policy, flushed independently of human continuation text. */
 	projectInstructionContext?: ProjectInstructionContext

package/src/types/agent/manager.ts

@@ -25,33 +25,18 @@ export interface AgentManagerContract {
 	cancelAll(parentSessionId: SessionId, cause?: CancelCause): void
 
 	/**
-	 * Queue a message for a running task.
+	 * Queue guidance for a nonterminal task. Acceptance is not delivery.
 	 *
-	 * **The runtime does not deliver it.** These three methods maintain a
-	 * per-task queue that nothing in the iteration loop reads: the consumer
-	 * that once drained it was removed, and the mid-run delivery handshake
-	 * that would replace it is a host concern, not a kernel one. A caller
-	 * who assumes `continueTask` reaches the agent is queuing into a buffer
-	 * only {@link drainMessages} empties.
-	 *
-	 * Kept, and documented rather than deleted, because `drainMessages` is
-	 * the only way a host can pick these up at all — removing it would take
-	 * away the escape hatch and leave the trap.
-	 *
-	 * **For mid-run guidance, use `SteeringChannel` instead.** That is the
-	 * delivery handshake this queue was missing: text queued on it is
-	 * appended to the running batch's last `tool_result`, which is the only
-	 * slot a provider accepts mid-batch, and the loop drains it. Pass one as
-	 * `steering` on `drainQuery` params or on `SupervisorAgentConfig`.
-	 *
-	 * Two other routes also work: reject/modify feedback rides inside a tool
-	 * result, and `prepareStep`'s `system` string is appended to the next
-	 * model call from a hook that sees live history.
+	 * The manager supplies `AgentConfig.inboundMessages`, which query-backed
+	 * agents drain at provider-valid request boundaries, including completion.
+	 * It does not interrupt an in-flight tool or model request. Custom agents
+	 * must consume that callback; an agent that ignores it will not receive mail.
+	 * Terminal tasks reject new input and cannot be restarted by this operation.
 	 */
 	continueTask(taskId: TaskId, message: string): Promise<void>
-	/** See {@link continueTask} — queued, not delivered. */
+	/** Queue a structured message under the same acceptance contract. */
 	queueMessage(taskId: TaskId, message: Message): void
-	/** Empty the queue {@link continueTask} fills. The host must call this. */
+	/** Destructive drain used by the manager's injected inbound callback. */
 	drainMessages(taskId: TaskId): Message[]
 
 	waitForCompletion(taskId: TaskId): Promise<void>

package/src/types/agent/scheduler.ts

@@ -1,5 +1,5 @@
 import type { SessionTokenBudget } from '../../store/budget/index.js'
-import type { TaskId } from '../ids/index.js'
+import type { SessionId, TaskId } from '../ids/index.js'
 import type { AgentPersona } from '../persona/index.js'
 import type { CancelCause } from '../session/cancel-cause.js'
 import type { ChildSessionLifecycleEvent, SessionEventListener } from '../session/events.js'
@@ -14,6 +14,8 @@ export interface TaskHandle {
 	readonly result?: BaseAgentResult
 	readonly createdAt: number
 	readonly completedAt?: number
+	/** Authoritative conversation id, available once the child is admitted. */
+	readonly childSessionId?: SessionId
 	/** The workspace assigned to an explicitly isolated child, when admitted. */
 	readonly workspace?: WorkspaceRef
 }
@@ -32,6 +34,13 @@ export interface TaskHandle {
 export type SiblingFailurePolicy = 'continue' | 'cancel-siblings'
 
 export interface CreateTaskOptions {
+	/**
+	 * Continue a child conversation under a NEW task, with this invocation's
+	 * parent authority, budget and configuration. Local managers accept only
+	 * their own retained, settled shared-workspace children of the same parent
+	 * and unchanged agent definition. A saved log alone grants no authority.
+	 */
+	readonly resumeSessionId?: SessionId
 	/** Per-task filesystem choice, forwarded to the local manager at admission. */
 	readonly workspace?: ChildWorkspaceRequest
 	/**

package/src/types/agent/task.ts

@@ -219,6 +219,8 @@ export interface AgentTask {
 	pendingMessages: Message[]
 	createdAt: number
 	completedAt?: number
+	/** Populated at admission; never inferred from a custom agent's result. */
+	readonly childSessionId?: SessionId
 	/** Populated after an explicitly isolated spawn is admitted. */
 	workspace?: WorkspaceRef
 
@@ -234,6 +236,8 @@ export interface AgentTask {
  * WorkspaceRef triple atomically on every spawn.
  */
 export interface SendMessageOptions {
+	/** See {@link import('./scheduler.js').CreateTaskOptions.resumeSessionId}. */
+	readonly resumeSessionId?: SessionId
 	/** Explicit child filesystem policy; omitted preserves legacy backend behavior. */
 	readonly workspace?: ChildWorkspaceRequest
 	/**

package/src/types/connector/mcp.ts

@@ -457,6 +457,13 @@ export interface MCPClientConfig {
 	id?: MCPClientId
 	serverName: string
 	transport: MCPTransportUnion
+	/**
+	 * Construct a host-owned transport instead of spawning/fetching from `transport`.
+	 * The config still supplies protocol/cache metadata; no built-in transport work
+	 * is started. The factory runs once per client; its transport owns reconnects.
+	 * Custom clients get an isolated era cache unless `eraCache` is supplied.
+	 */
+	transportFactory?: () => MCPTransport
 	capabilities?: MCPClientCapabilities
 	clientInfo?: { name: string; version: string }
 	/**

package/src/types/errors/catalog.ts

@@ -144,8 +144,10 @@ export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
 		// separates them when the provider sent it.
 		id: 'provider.permission',
 		when: (facts) => facts.status === 403,
-		message: 'The credentials are valid but not permitted to use this model.',
-		hint: 'The key authenticated, so this is an entitlement rather than a secret problem: check the model name and whether the account has access to it.',
+		// A 403 says the request was refused, not that a key was accepted: some providers answer
+		// a request that carried no key at all (a keyless free tier) with the same status.
+		message: 'The provider refused this request.',
+		hint: 'Check the model name and whether the account behind your key has access to it. If no key was sent, add one or choose another provider.',
 	},
 	{
 		id: 'provider.auth',

package/src/types/harness/schema.ts

@@ -0,0 +1,203 @@
+import { z } from 'zod'
+import { isEntityId } from '../../utils/id.js'
+import type { MessageId, TurnId } from '../ids/index.js'
+import type { HarnessEvent, HarnessJson } from './session.js'
+
+const opaque = z
+	.string()
+	.min(1)
+	.max(4096)
+	.refine((v) => !Array.from(v).some((c) => c.charCodeAt(0) < 32))
+const text = z.string().max(1024 * 1024)
+const digest = z.string().regex(/^[a-f0-9]{64}$/)
+const turnId = z.custom<TurnId>((v) => isEntityId(v, 'turn'))
+const messageId = z.custom<MessageId>((v) => isEntityId(v, 'message'))
+
+function validJson(value: unknown, depth = 0, budget = { nodes: 0 }): boolean {
+	if (depth > 32 || ++budget.nodes > 50000) return false
+	if (value === null || typeof value === 'boolean') return true
+	if (typeof value === 'number') return Number.isFinite(value)
+	if (typeof value === 'string') return value.length <= 1024 * 1024
+	if (Array.isArray(value)) return value.every((v) => validJson(v, depth + 1, budget))
+	if (typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) return false
+	return Object.entries(value).every(
+		([k, v]) => k.length <= 4096 && validJson(v, depth + 1, budget),
+	)
+}
+const json = z
+	.custom<HarnessJson>((v) => validJson(v))
+	.refine((v) => JSON.stringify(v).length <= 1024 * 1024)
+
+export const HarnessBindingSchema = z
+	.object({
+		v: z.literal(1),
+		engineId: opaque,
+		profileRef: opaque,
+		nativeSessionId: opaque,
+		cwd: opaque,
+		initialModel: opaque,
+	})
+	.strict()
+const nativeTurn = {
+	nativeSessionId: opaque,
+	nativeTurnId: opaque,
+	turnIdSource: z.enum(['engine', 'operation']).optional(),
+}
+const nativeItem = { ...nativeTurn, nativeItemId: opaque }
+export const HarnessNativeTurnSchema = z.object(nativeTurn).strict()
+export const HarnessReviewRequestSchema = z
+	.object({
+		...nativeTurn,
+		requestId: opaque,
+		nativeItemId: opaque.optional(),
+		kind: z.enum(['command', 'file-change', 'tool']),
+		title: opaque,
+		input: json,
+		decisions: z
+			.array(z.enum(['approve-once', 'reject', 'cancel']))
+			.min(1)
+			.max(3),
+	})
+	.strict()
+export const HarnessDecisionSchema = z.discriminatedUnion('kind', [
+	z.object({ kind: z.literal('approve-once'), updatedInput: json.optional() }).strict(),
+	z.object({ kind: z.literal('reject'), feedback: text.optional() }).strict(),
+	z.object({ kind: z.literal('cancel') }).strict(),
+])
+const part = z
+	.object({ id: opaque, text, phase: z.enum(['commentary', 'final_answer']).optional() })
+	.strict()
+export const HarnessEventSchema: z.ZodType<HarnessEvent> = z.discriminatedUnion('kind', [
+	z.object({ kind: z.literal('turn-started'), ...nativeTurn, model: opaque.optional() }).strict(),
+	z.object({ kind: z.literal('message-started'), ...nativeItem }).strict(),
+	z
+		.object({
+			kind: z.literal('text-delta'),
+			...nativeItem,
+			text,
+			part: part.omit({ text: true }).optional(),
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('message-completed'),
+			...nativeItem,
+			content: text,
+			parts: z.array(part).max(10000).optional(),
+			stopReason: z.enum([
+				'end_turn',
+				'tool_use',
+				'max_tokens',
+				'stop_sequence',
+				'pause_turn',
+				'refusal',
+				'forced_finalize',
+				'cancelled',
+			]),
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('reasoning'),
+			...nativeItem,
+			blockId: opaque,
+			status: z.enum(['pending', 'completed']),
+			text: text.optional(),
+		})
+		.strict(),
+	z.object({ kind: z.literal('tool-started'), ...nativeItem, name: opaque, input: json }).strict(),
+	z.object({ kind: z.literal('tool-output'), ...nativeItem, text }).strict(),
+	z
+		.object({
+			kind: z.literal('tool-completed'),
+			...nativeItem,
+			name: opaque,
+			result: text,
+			status: z.enum(['completed', 'failed', 'declined', 'cancelled']),
+			durationMs: z.number().int().nonnegative().safe().optional(),
+		})
+		.strict(),
+	z.object({ kind: z.literal('review-requested'), request: HarnessReviewRequestSchema }).strict(),
+	z.object({ kind: z.literal('review-resolved'), ...nativeTurn, requestId: opaque }).strict(),
+	z
+		.object({
+			kind: z.literal('turn-completed'),
+			...nativeTurn,
+			status: z.enum(['completed', 'failed', 'cancelled']),
+			finalItemId: opaque.optional(),
+			result: text.optional(),
+			error: z.object({ code: opaque, message: text }).strict().optional(),
+		})
+		.strict(),
+	z
+		.object({ kind: z.literal('connection-lost'), code: opaque, mayBeRunning: z.boolean() })
+		.strict(),
+])
+
+export const HarnessJournalTransitionSchema = z.discriminatedUnion('kind', [
+	z
+		.object({
+			kind: z.literal('dispatch-prepared'),
+			model: opaque.optional(),
+			effort: z
+				.enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'])
+				.optional(),
+			permissionMode: z.enum(['prompt', 'auto', 'accept-edits', 'plan', 'strict']).optional(),
+			operationId: opaque,
+			turnId,
+			promptId: messageId,
+			digest,
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('dispatch-accepted'),
+			operationId: opaque,
+			turnId,
+			nativeTurn: HarnessNativeTurnSchema,
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('item-bound'),
+			turnId,
+			nativeItem: z.object(nativeItem).strict(),
+			messageId: messageId.optional(),
+			toolUseId: opaque.optional(),
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('review-requested'),
+			turnId,
+			request: HarnessReviewRequestSchema,
+			digest,
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('review-decided'),
+			turnId,
+			requestId: opaque,
+			requestDigest: digest,
+			decisionDigest: digest,
+			decision: HarnessDecisionSchema,
+		})
+		.strict(),
+	z.object({ kind: z.literal('review-resolved'), turnId, requestId: opaque }).strict(),
+	z
+		.object({ kind: z.literal('connection-lost'), turnId: turnId.optional(), code: opaque })
+		.strict(),
+])
+
+/** Clone at ingress, before any host callback can suspend, and freeze every nested value. */
+export function harnessSnapshot<T>(value: T): T {
+	const copy = structuredClone(value)
+	const freeze = (v: unknown): void => {
+		if (!v || typeof v !== 'object') return
+		for (const entry of Object.values(v)) freeze(entry)
+		Object.freeze(v)
+	}
+	freeze(copy)
+	return copy
+}