@namzu/sdk 0.4.4 → 0.5.0

package/src/session/__tests__/integration/event-stream-ordering.test.ts

@@ -2,7 +2,7 @@
  * Integration — event stream ordering + lineage + schemaVersion envelope.
  *
  * Covers roadmap §5 invariants:
- *   - §10.1 schemaVersion: 2 on every sub-session RunEvent
+ *   - §10.1 schemaVersion: 3 on every sub-session RunEvent
  *   - §10.3 tree-scoped monotonic ordering by (rootSessionId, eventId)
  *   - §10.3 depth filter ('self' vs 'tree') at subscribe time
  *   - §10.4 lineage stamped on every sub-session event with parent + root + depth
@@ -32,7 +32,7 @@ import {
 } from './_fixtures.js'
 
 describe('Integration — event stream ordering + lineage + schemaVersion', () => {
-	it('every sub-session RunEvent carries schemaVersion: 2', async () => {
+	it('every sub-session RunEvent carries schemaVersion: 3', async () => {
 		const harness = buildHarness()
 		const { project, thread, session, actor } = await seedActiveParent(harness)
 		harness.registry.register(buildDefinition(buildAgent('worker')))
@@ -59,7 +59,7 @@ describe('Integration — event stream ordering + lineage + schemaVersion', () =
 		)
 		await harness.manager.waitForCompletion(task.taskId)
 
-		// Every sub-session lifecycle event is stamped with schemaVersion: 2.
+		// Every sub-session lifecycle event is stamped with schemaVersion: 3.
 		const subSessionEvents = captured.filter(
 			(e) =>
 				e.type === 'subsession_spawned' ||
@@ -68,7 +68,7 @@ describe('Integration — event stream ordering + lineage + schemaVersion', () =
 		)
 		expect(subSessionEvents.length).toBeGreaterThan(0)
 		for (const ev of subSessionEvents) {
-			expect(ev.schemaVersion).toBe(2)
+			expect(ev.schemaVersion).toBe(3)
 		}
 	})
 
@@ -348,9 +348,9 @@ describe('Integration — event stream ordering + lineage + schemaVersion', () =
 		expect(outerDepths.every((d) => d === 1)).toBe(true)
 	})
 
-	it('run_started and other core RunEvents also carry schemaVersion: 2 when stamped by the child listener wrapper', async () => {
+	it('run_started and other core RunEvents also carry schemaVersion: 3 when stamped by the child listener wrapper', async () => {
 		// The listener wrapper in `manager/agent/lifecycle.ts#wrapChildListener`
-		// stamps `schemaVersion: 2` + `lineage` on EVERY event emitted inside
+		// stamps `schemaVersion: 3` + `lineage` on EVERY event emitted inside
 		// the child's run. Core events that pass through the wrapped listener
 		// therefore inherit the envelope even though they have no lineage in
 		// their own type definition.
@@ -404,7 +404,7 @@ describe('Integration — event stream ordering + lineage + schemaVersion', () =
 		const runStarted = captured.find((e) => e.type === 'run_started')
 		expect(runStarted).toBeDefined()
 		if (runStarted && 'schemaVersion' in runStarted) {
-			expect(runStarted.schemaVersion).toBe(2)
+			expect(runStarted.schemaVersion).toBe(3)
 		}
 	})
 })

package/src/streaming/coalesce.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Behavioural contract for `coalesce()` (ses_001-tool-stream-events phase 1A):
+ *
+ * - `text_delta` events for the same `messageId` within the configured
+ *   `windowMs` are merged into a single event whose `text` is the
+ *   concatenation in arrival order.
+ * - `tool_input_delta` events for the same `toolUseId` within the window
+ *   are merged the same way on `partialJson`.
+ * - Any other event flushes pending buffers first, preserving overall
+ *   stream ordering.
+ * - End-of-stream flushes any remaining buffers.
+ * - Different `messageId`s and `toolUseId`s never merge with each other.
+ *
+ * The coalescer is opt-in for slow downstream consumers (SSE adapters);
+ * the orchestrator emits raw deltas. A 16ms default roughly aligns with
+ * one 60fps animation frame.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { MessageId, RunId, ToolUseId } from '../types/ids/index.js'
+import type { RunEvent } from '../types/run/events.js'
+
+import { coalesce } from './coalesce.js'
+
+const RID = 'run_1' as RunId
+const MID = 'msg_1' as MessageId
+const MID2 = 'msg_2' as MessageId
+const TUID: ToolUseId = 'toolu_a'
+const TUID2: ToolUseId = 'toolu_b'
+
+async function* fromArray(events: RunEvent[]): AsyncIterable<RunEvent> {
+	for (const e of events) yield e
+}
+
+async function drain(stream: AsyncIterable<RunEvent>): Promise<RunEvent[]> {
+	const out: RunEvent[] = []
+	for await (const e of stream) out.push(e)
+	return out
+}
+
+describe('coalesce()', () => {
+	it('merges consecutive text_delta events with same messageId within window', async () => {
+		const events: RunEvent[] = [
+			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'hel' },
+			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'lo' },
+			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: ' world' },
+		]
+		const result = await drain(coalesce(fromArray(events), { windowMs: 1000 }))
+		expect(result).toHaveLength(1)
+		expect(result[0]).toMatchObject({
+			type: 'text_delta',
+			text: 'hello world',
+			messageId: MID,
+		})
+	})
+
+	it('merges consecutive tool_input_delta events with same toolUseId', async () => {
+		const events: RunEvent[] = [
+			{ type: 'tool_input_delta', runId: RID, toolUseId: TUID, partialJson: '{"file":' },
+			{ type: 'tool_input_delta', runId: RID, toolUseId: TUID, partialJson: '"/a"' },
+			{ type: 'tool_input_delta', runId: RID, toolUseId: TUID, partialJson: '}' },
+		]
+		const result = await drain(coalesce(fromArray(events), { windowMs: 1000 }))
+		expect(result).toHaveLength(1)
+		expect(result[0]).toMatchObject({
+			type: 'tool_input_delta',
+			toolUseId: TUID,
+			partialJson: '{"file":"/a"}',
+		})
+	})
+
+	it('does not merge across different messageIds', async () => {
+		const events: RunEvent[] = [
+			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'a' },
+			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID2, text: 'b' },
+		]
+		const result = await drain(coalesce(fromArray(events), { windowMs: 1000 }))
+		expect(result).toHaveLength(2)
+	})
+
+	it('does not merge across different toolUseIds', async () => {
+		const events: RunEvent[] = [
+			{ type: 'tool_input_delta', runId: RID, toolUseId: TUID, partialJson: 'x' },
+			{ type: 'tool_input_delta', runId: RID, toolUseId: TUID2, partialJson: 'y' },
+		]
+		const result = await drain(coalesce(fromArray(events), { windowMs: 1000 }))
+		expect(result).toHaveLength(2)
+	})
+
+	it('flushes pending buffers when a non-coalescable event arrives', async () => {
+		const events: RunEvent[] = [
+			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'a' },
+			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'b' },
+			{
+				type: 'tool_input_started',
+				runId: RID,
+				iteration: 0,
+				messageId: MID,
+				toolUseId: TUID,
+				toolName: 'Read',
+			},
+			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'c' },
+		]
+		const result = await drain(coalesce(fromArray(events), { windowMs: 1000 }))
+		expect(result.map((e) => e.type)).toEqual(['text_delta', 'tool_input_started', 'text_delta'])
+		expect((result[0] as { text: string }).text).toBe('ab')
+		expect((result[2] as { text: string }).text).toBe('c')
+	})
+
+	it('flushes residual buffers at end of stream', async () => {
+		const events: RunEvent[] = [
+			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'tail' },
+		]
+		const result = await drain(coalesce(fromArray(events), { windowMs: 1000 }))
+		expect(result).toHaveLength(1)
+	})
+
+	it('emits new event after window expires', async () => {
+		const events: RunEvent[] = [
+			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'a' },
+			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'b' },
+		]
+		const stream: AsyncIterable<RunEvent> = (async function* () {
+			yield events[0]!
+			await new Promise((r) => setTimeout(r, 30))
+			yield events[1]!
+		})()
+		const result = await drain(coalesce(stream, { windowMs: 16 }))
+		expect(result).toHaveLength(2)
+	})
+})

package/src/streaming/coalesce.ts

@@ -0,0 +1,89 @@
+import type { ToolUseId } from '../types/ids/index.js'
+import type { RunEvent } from '../types/run/events.js'
+
+interface CoalesceOptions {
+	windowMs: number
+}
+
+/**
+ * Coalesces high-frequency `text_delta` and `tool_input_delta` events into
+ * fewer, larger events to relieve downstream backpressure (typically a
+ * Server-Sent Events adapter writing to a slow client).
+ *
+ * Within a sliding `windowMs` window, consecutive `text_delta` events for
+ * the same `messageId` are merged by string concatenation; consecutive
+ * `tool_input_delta` events for the same `toolUseId` are likewise merged.
+ * All other event types pass through immediately and flush any buffered
+ * deltas first to preserve ordering.
+ *
+ * The orchestrator does NOT use this — it emits raw deltas. SSE adapters
+ * and other slow consumers opt in. A 16ms window roughly aligns with one
+ * UI animation frame at 60fps, which is the empirically derived default
+ * for cowork's stream route.
+ *
+ * Backpressure semantics: this helper does not drop events. If the
+ * upstream produces faster than the consumer drains, the helper still
+ * yields every coalesced batch; the consumer must apply its own bound or
+ * accept queue growth.
+ */
+export async function* coalesce(
+	stream: AsyncIterable<RunEvent>,
+	options: CoalesceOptions = { windowMs: 16 },
+): AsyncGenerator<RunEvent, void, unknown> {
+	const { windowMs } = options
+	let textBuf: { event: Extract<RunEvent, { type: 'text_delta' }>; deadline: number } | null = null
+	const toolBufs = new Map<
+		ToolUseId,
+		{ event: Extract<RunEvent, { type: 'tool_input_delta' }>; deadline: number }
+	>()
+
+	function* flushAll(): Generator<RunEvent> {
+		if (textBuf) {
+			yield textBuf.event
+			textBuf = null
+		}
+		for (const buf of toolBufs.values()) {
+			yield buf.event
+		}
+		toolBufs.clear()
+	}
+
+	const now = () => Date.now()
+
+	for await (const event of stream) {
+		if (event.type === 'text_delta') {
+			if (textBuf && textBuf.event.messageId === event.messageId && textBuf.deadline > now()) {
+				textBuf.event = {
+					...textBuf.event,
+					text: textBuf.event.text + event.text,
+				}
+			} else {
+				if (textBuf) yield textBuf.event
+				textBuf = { event, deadline: now() + windowMs }
+			}
+			continue
+		}
+
+		if (event.type === 'tool_input_delta') {
+			const existing = toolBufs.get(event.toolUseId)
+			if (existing && existing.deadline > now()) {
+				existing.event = {
+					...existing.event,
+					partialJson: existing.event.partialJson + event.partialJson,
+				}
+			} else {
+				if (existing) yield existing.event
+				toolBufs.set(event.toolUseId, {
+					event,
+					deadline: now() + windowMs,
+				})
+			}
+			continue
+		}
+
+		yield* flushAll()
+		yield event
+	}
+
+	yield* flushAll()
+}

package/src/tools/coordinator/index.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import type { PlanManager } from '../../manager/plan/lifecycle.js'
+import type { AgentRuntimeContext } from '../../types/agent/base.js'
 import type { TaskGateway } from '../../types/agent/gateway.js'
 import type { RunId, TaskId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
@@ -18,6 +19,7 @@ export type TaskLaunchedCallback = (
 export interface CoordinatorToolsOptions {
 	gateway: TaskGateway
 	workingDirectory: string
+	runtimeContext?: AgentRuntimeContext
 	allowedAgentIds: string[]
 
 	taskStore?: TaskStore
@@ -88,6 +90,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				agentId: agent_id,
 				prompt,
 				workingDirectory: cwd,
+				runtimeContext: opts.runtimeContext,
 			})
 
 			if (onTaskLaunched) {

package/src/types/agent/base.ts

@@ -62,6 +62,13 @@ export interface BaseAgentConfig {
 
 export type RuntimeToolOverrides = Record<string, ToolAvailability | 'disabled'>
 
+export interface AgentRuntimeContext {
+	label?: string
+	outputDirectory?: string
+	outputFileMarker?: string
+	notes?: readonly string[]
+}
+
 export interface AgentInput {
 	messages: Message[]
 	workingDirectory: string
@@ -70,6 +77,8 @@ export interface AgentInput {
 	taskStore?: TaskStore
 
 	runtimeToolOverrides?: RuntimeToolOverrides
+
+	runtimeContext?: AgentRuntimeContext
 }
 
 export interface BaseAgentResult {

package/src/types/agent/gateway.ts

@@ -1,5 +1,5 @@
 import type { TaskId } from '../ids/index.js'
-import type { BaseAgentResult } from './base.js'
+import type { AgentRuntimeContext, BaseAgentResult } from './base.js'
 import type { AgentTaskState } from './task.js'
 
 export interface TaskHandle {
@@ -18,6 +18,8 @@ export interface CreateTaskOptions {
 
 	workingDirectory: string
 
+	runtimeContext?: AgentRuntimeContext
+
 	configOverrides?: Record<string, unknown>
 }
 

package/src/types/ids/index.ts

@@ -2,6 +2,16 @@ export type RunId = `run_${string}`
 export type MessageId = `msg_${string}`
 export type SessionId = `ses_${string}`
 export type ToolCallId = `call_${string}`
+/**
+ * Provider-issued tool-use identifier surfaced on the streaming event bus.
+ * Providers emit different prefixes (Anthropic: `toolu_*`, OpenAI: `call_*`,
+ * others vary), so this type intentionally stays unbranded — we accept the
+ * provider's verbatim string and use it solely as a correlation key across
+ * `tool_input_*`, `tool_executing`, and `tool_completed` events. Distinct
+ * from {@link ToolCallId} which is the OpenAI-format identifier carried in
+ * persisted assistant messages and replay records.
+ */
+export type ToolUseId = string
 export type ActivityId = `act_${string}`
 export type TaskId = `task_${string}`
 export type PlanId = `plan_${string}`

package/src/types/provider/interface.ts

@@ -1,4 +1,6 @@
-import type { ChatCompletionParams, ChatCompletionResponse } from './chat.js'
+import type { DoctorCheckResult } from '../doctor/index.js'
+
+import type { ChatCompletionParams } from './chat.js'
 import type { ModelInfo } from './model.js'
 import type { StreamChunk } from './stream.js'
 
@@ -6,11 +8,34 @@ export interface LLMProvider {
 	readonly id: string
 	readonly name: string
 
-	chat(params: ChatCompletionParams): Promise<ChatCompletionResponse>
-
+	/**
+	 * The single LLM entry point. Returns an async iterable of
+	 * {@link StreamChunk} carrying text deltas, tool-call argument
+	 * fragments, and per-tool-block boundary signals (`toolCallEnd`).
+	 *
+	 * Consumers that need an aggregated response (legacy
+	 * `ChatCompletionResponse` shape) call
+	 * `collect(provider.chatStream(params))` from
+	 * `@namzu/sdk/provider/collect`. The kernel's iteration
+	 * orchestrator consumes the stream directly so it can emit
+	 * per-delta `RunEvent`s.
+	 *
+	 * Phase 2 of ses_001-tool-stream-events removed the previous
+	 * non-streaming `chat()` method from this interface.
+	 */
 	chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk>
 
 	listModels?(): Promise<ModelInfo[]>
 
 	healthCheck?(): Promise<boolean>
+
+	/**
+	 * Optional structured health probe used by `runDoctor()`.
+	 *
+	 * Returns a `DoctorCheckResult` with provider-specific detail
+	 * (latency, model availability, auth status, …). Providers that
+	 * cannot be cheaply probed should return `{ status: 'inconclusive' }`
+	 * so the doctor doesn't mark them as failing — see ses_007 Q6.4.
+	 */
+	doctorCheck?(): Promise<DoctorCheckResult>
 }

package/src/types/provider/stream.ts

@@ -13,6 +13,24 @@ export interface StreamChunk {
 				arguments?: string
 			}
 		}>
+		/**
+		 * Provider signal that a tool-use content block has finished
+		 * streaming arguments. Translates from Anthropic's
+		 * `content_block_stop` (for tool_use blocks) and from the
+		 * equivalent end-of-tool-arguments boundary on other providers.
+		 *
+		 * The orchestrator uses this to emit `tool_input_completed` per
+		 * tool as soon as its block closes, rather than waiting for
+		 * `message_stop`. Providers that cannot emit a per-tool boundary
+		 * leave this undefined; the orchestrator infers from
+		 * end-of-stream instead.
+		 *
+		 * Added 2026-05-01 (ses_001-tool-stream-events A9).
+		 */
+		toolCallEnd?: {
+			index: number
+			id: string
+		}
 	}
 	finishReason?: 'stop' | 'tool_calls' | 'length' | 'content_filter'
 	usage?: TokenUsage

package/src/types/run/events.ts

@@ -2,18 +2,28 @@ import type { ActivityStatus, ActivityType } from '../activity/index.js'
 import type { BaseAgentResult } from '../agent/base.js'
 import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { CheckpointId, ToolCallSummary } from '../hitl/index.js'
-import type { ActivityId, PlanId, PluginId, RunId, SandboxId, TaskId } from '../ids/index.js'
+import type {
+	ActivityId,
+	MessageId,
+	PlanId,
+	PluginId,
+	RunId,
+	SandboxId,
+	TaskId,
+	ToolUseId,
+} from '../ids/index.js'
 import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
 import type { TaskStatus } from '../task/index.js'
 import type { Lineage } from './lineage.js'
+import type { MessageStopReason } from './stop-reason.js'
 import type {
 	SubsessionIdledEvent,
 	SubsessionMessagedEvent,
 	SubsessionSpawnedEvent,
 } from './subsession-events.js'
 
-export type { StopReason } from './stop-reason.js'
+export type { MessageStopReason, StopReason } from './stop-reason.js'
 
 /**
  * Additive envelope fields present on every {@link RunEvent} variant.
@@ -25,7 +35,13 @@ export type { StopReason } from './stop-reason.js'
  * absent on root-session events.
  */
 interface RunEventEnvelope {
-	schemaVersion?: 2
+	/**
+	 * v3 envelope (ses_001-tool-stream-events, 2026-05-01). Removes
+	 * `llm_response`; adds message + tool-input lifecycle variants;
+	 * tightens `tool_executing` / `tool_completed` payloads. Emitters
+	 * stamp this from {@link RUN_EVENT_SCHEMA_VERSION}.
+	 */
+	schemaVersion?: 3
 	lineage?: Lineage
 }
 
@@ -38,23 +54,20 @@ type CoreRunEvent =
 			iteration: number
 			hasToolCalls: boolean
 	  }
-	| {
-			type: 'llm_response'
-			runId: RunId
-			content: string | null
-			hasToolCalls: boolean
-	  }
 	| {
 			type: 'tool_executing'
 			runId: RunId
+			toolUseId: ToolUseId
 			toolName: string
 			input: unknown
 	  }
 	| {
 			type: 'tool_completed'
 			runId: RunId
+			toolUseId: ToolUseId
 			toolName: string
 			result: string
+			isError: boolean
 	  }
 	| {
 			type: 'tool_review_requested'
@@ -193,6 +206,64 @@ type CoreRunEvent =
 			durationMs: number
 	  }
 	| { type: 'sandbox_destroyed'; runId: RunId; sandboxId: SandboxId }
+	// ─────────────────────────────────────────────────────────────────────
+	// v3 message + tool-input lifecycle (additive 2026-05; see
+	// ses_001-tool-stream-events). These are not yet emitted by the
+	// iteration orchestrator — phase 4 of the migration switches the
+	// orchestrator to streaming consumption and removes `llm_response`.
+	// Until then these variants exist so consumers can be wired ahead of
+	// the producer-side cutover.
+	// ─────────────────────────────────────────────────────────────────────
+	| {
+			type: 'message_started'
+			runId: RunId
+			iteration: number
+			messageId: MessageId
+	  }
+	| {
+			type: 'text_delta'
+			runId: RunId
+			iteration: number
+			messageId: MessageId
+			text: string
+	  }
+	| {
+			type: 'message_completed'
+			runId: RunId
+			iteration: number
+			messageId: MessageId
+			stopReason: MessageStopReason
+			usage?: TokenUsage
+			/**
+			 * Aggregated assistant text accumulated from `text_delta`
+			 * events for this message. Optional so consumers that
+			 * already concatenate deltas themselves don't have to pay
+			 * the duplication; consumers that only care about the
+			 * completed message (telemetry, A2A bridge, postmortem
+			 * tooling) can read this field directly.
+			 */
+			content?: string
+	  }
+	| {
+			type: 'tool_input_started'
+			runId: RunId
+			iteration: number
+			messageId: MessageId
+			toolUseId: ToolUseId
+			toolName: string
+	  }
+	| {
+			type: 'tool_input_delta'
+			runId: RunId
+			toolUseId: ToolUseId
+			partialJson: string
+	  }
+	| {
+			type: 'tool_input_completed'
+			runId: RunId
+			toolUseId: ToolUseId
+			input: unknown
+	  }
 
 /**
  * Discriminated union of all run-scoped events emitted by the kernel.
@@ -210,3 +281,28 @@ export type RunEvent =
 	| SubsessionIdledEvent
 
 export type RunEventListener = (event: RunEvent) => void | Promise<void>
+
+/**
+ * Event types whose volume makes durable persistence wasteful.
+ *
+ * `text_delta` and `tool_input_delta` arrive at provider cadence (often
+ * 50–100 events per second), carry no information not derivable from the
+ * surrounding message/tool lifecycle events, and are not consulted by
+ * replay (`runtime/query/replay/prepare.ts` reads checkpoints, not the
+ * transcript). The kernel still dispatches them on the in-memory bus so
+ * SSE consumers can render live progress, but the disk store
+ * (`store/run/disk.ts:appendEvent`) skips them via this predicate.
+ *
+ * Keeping the predicate centralised — rather than threading an
+ * `ephemeral: true` field through every emit site — means new ephemeral
+ * variants are added by editing one Set and consumers don't have to
+ * inspect event shape to decide what to persist.
+ */
+const EPHEMERAL_EVENT_TYPES: ReadonlySet<RunEvent['type']> = new Set<RunEvent['type']>([
+	'text_delta',
+	'tool_input_delta',
+])
+
+export function isEphemeralEvent(event: RunEvent): boolean {
+	return EPHEMERAL_EVENT_TYPES.has(event.type)
+}

package/src/types/run/schema-version.ts

@@ -4,10 +4,16 @@
  * - v1: pre-0.2.0 (implicit; untagged events are treated as v1 by consumers).
  * - v2: 0.2.0+ — adds `schemaVersion`, `lineage`, and sub-session lifecycle
  *   events.
+ * - v3: 2026-05-01 — removes `llm_response`; adds message + tool-input
+ *   lifecycle variants (`message_started`, `text_delta`,
+ *   `message_completed`, `tool_input_started`, `tool_input_delta`,
+ *   `tool_input_completed`); `tool_executing`/`tool_completed` carry
+ *   required `toolUseId`; `tool_completed` carries required `isError`.
+ *   See ses_001-tool-stream-events.
  *
  * See session-hierarchy.md §10.1 (Event-schema evolution contract) and
  * §13.3.2 (`schemaVersion` back-compat).
  */
-export const RUN_EVENT_SCHEMA_VERSION = 2 as const
+export const RUN_EVENT_SCHEMA_VERSION = 3 as const
 
 export type RunEventSchemaVersion = typeof RUN_EVENT_SCHEMA_VERSION

package/src/types/run/stop-reason.ts

@@ -8,3 +8,20 @@ export type StopReason =
 	| 'plan_rejected'
 	| 'paused'
 	| 'error'
+
+/**
+ * Per-LLM-message stop reason — distinct from the run-level {@link StopReason}.
+ *
+ * Mirrors the union of Anthropic and OpenAI finish reasons normalised into a
+ * provider-agnostic vocabulary. `forced_finalize` is a Namzu-specific value
+ * emitted by the orchestrator when iteration limits force a final response
+ * without a model-issued stop reason.
+ */
+export type MessageStopReason =
+	| 'end_turn'
+	| 'tool_use'
+	| 'max_tokens'
+	| 'stop_sequence'
+	| 'pause_turn'
+	| 'refusal'
+	| 'forced_finalize'