@namzu/sdk 42.0.2 → 44.0.0

package/src/bridge/sse/mapper.ts

@@ -1,18 +1,17 @@
-import type { StreamEventType } from '../../contracts/index.js'
-import type { RunId } from '../../types/ids/index.js'
-import type { RunEvent } from '../../types/run/events.js'
+import type { SessionStreamEventType } from '../../contracts/session/api.js'
+import type { SessionEvent } from '../../types/session/events.js'
 
 export interface MappedStreamEvent {
-	wire: StreamEventType
+	wire: SessionStreamEventType
 	data: Record<string, unknown>
 	/**
-	 * The cursor a client resubscribes at, as `<runId>:<seq>`.
+	 * The cursor a client resubscribes at, as `<sessionId>:<seq>`.
 	 *
 	 * Not a bare number, and the reason is structural: a parent's stream also
-	 * carries its children's events, each numbered in its OWN run's log, so one
-	 * scalar over a mixed stream would compare positions from two different
-	 * sequences. The run id is what makes the position addressable — a client
-	 * keeps one cursor per run id and sends the right one back.
+	 * carries its children's events, each numbered in its OWN session's log, so
+	 * one scalar over a mixed stream would compare positions from two different
+	 * sequences. The session id is what makes the position addressable — a
+	 * client keeps one cursor per session id and sends the right one back.
 	 *
 	 * This is what an SSE `id:` line should carry, which is why it sits beside
 	 * the payload rather than inside it: a framer writes it without having to
@@ -20,50 +19,52 @@ export interface MappedStreamEvent {
 	 *
 	 * Absent when the event is not recoverable — every ephemeral event, every
 	 * event whose durable write failed, and every delegation-lifecycle event
-	 * that never passed through the run's log at all. A client must not advance
+	 * that never passed through the session's log at all. A client must not advance
 	 * its cursor on one, and the absence is how it knows.
 	 */
 	id?: string
 }
 
-type EventTransform<K extends RunEvent['type']> = {
-	wire: StreamEventType
-	transform: (event: Extract<RunEvent, { type: K }>, runId: RunId) => Record<string, unknown>
+/**
+ * One event's wire name and payload. The payload holds the event's own
+ * fields only: `session_id` and `turn_id` are stamped on every payload by
+ * {@link mapSessionEventToStreamEvent}, from the event itself.
+ */
+type EventTransform<K extends SessionEvent['type']> = {
+	wire: SessionStreamEventType
+	transform: (event: Extract<SessionEvent, { type: K }>) => Record<string, unknown>
 } | null
 
 const MAPPING: {
-	[K in RunEvent['type']]: EventTransform<K>
+	[K in SessionEvent['type']]: EventTransform<K>
 } = {
 	// Internal cumulative admission ledger, not a public UI event.
 	tool_calls_admitted: null,
 	hosted_tool: {
 		wire: 'hosted.tool',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			tool: e.tool,
 		}),
 	},
-	run_started: {
-		wire: 'run.started',
-		transform: (e, runId) => ({
-			run_id: runId,
+	turn_started: {
+		wire: 'turn.started',
+		transform: (e) => ({
 			system_prompt: e.systemPrompt ?? null,
 		}),
 	},
 
 	iteration_started: {
 		wire: 'iteration.started',
-		transform: (e, runId) => ({ run_id: runId, iteration: e.iteration }),
+		transform: (e) => ({ iteration: e.iteration }),
 	},
 
 	// Named policies only, never the handler: the wire cannot carry a
-	// function, and the names are what an operator watching a live run
+	// function, and the names are what an operator watching a live turn
 	// needs in order to see supervision loosen.
 	approval_policy_changed: {
 		wire: 'approval_policy.changed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			from: e.from,
 			to: e.to,
 			reason: e.reason,
@@ -72,13 +73,12 @@ const MAPPING: {
 
 	iteration_completed: {
 		wire: 'iteration.completed',
-		transform: (e, runId) => ({ run_id: runId, iteration: e.iteration }),
+		transform: (e) => ({ iteration: e.iteration }),
 	},
 
 	reasoning_started: {
 		wire: 'reasoning.started',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			message_id: e.messageId,
 			block_index: e.blockIndex,
@@ -88,8 +88,7 @@ const MAPPING: {
 
 	reasoning_delta: {
 		wire: 'reasoning.delta',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			message_id: e.messageId,
 			block_index: e.blockIndex,
 			text: e.text,
@@ -98,8 +97,7 @@ const MAPPING: {
 
 	reasoning_completed: {
 		wire: 'reasoning.completed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			message_id: e.messageId,
 			block_index: e.blockIndex,
@@ -110,8 +108,7 @@ const MAPPING: {
 
 	guardrail_triggered: {
 		wire: 'guardrail.triggered',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			stage: e.stage,
 			action: e.action,
 			guardrail: e.guardrail,
@@ -125,8 +122,7 @@ const MAPPING: {
 	compaction_shed: null,
 	compaction_completed: {
 		wire: 'compaction.completed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			messages_before: e.messagesBefore,
 			messages_after: e.messagesAfter,
@@ -140,7 +136,7 @@ const MAPPING: {
 
 	// Carried for the same reason its sibling is: a host that can show a user
 	// context was dropped must also be able to show them it was not, because a
-	// run continuing at full context is the state that ends in an opaque
+	// turn continuing at full context is the state that ends in an opaque
 	// provider rejection later.
 	// Declined: it duplicates content already on the wire — the prompt a
 	// consumer can read from the transcript — and a system prompt plus a
@@ -150,8 +146,7 @@ const MAPPING: {
 
 	background_job_exited: {
 		wire: 'background_job.exited',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			job_id: e.jobId,
 			command: e.command,
 			status: e.status,
@@ -161,8 +156,7 @@ const MAPPING: {
 	},
 	memory_consolidated: {
 		wire: 'memory.consolidated',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			memory_id: e.memoryId,
 			title: e.title,
 			decisions: e.decisions,
@@ -172,8 +166,7 @@ const MAPPING: {
 	},
 	compaction_tool_results_cleared: {
 		wire: 'compaction.tool_results_cleared',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			cleared_count: e.clearedCount,
 			chars_reclaimed: e.charsReclaimed,
@@ -184,8 +177,7 @@ const MAPPING: {
 
 	compaction_failed: {
 		wire: 'compaction.failed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			cause: e.cause,
 			messages: e.messages,
@@ -195,8 +187,7 @@ const MAPPING: {
 
 	tool_executing: {
 		wire: 'tool.executing',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			tool_use_id: e.toolUseId,
 			tool_name: e.toolName,
 			input: e.input,
@@ -204,11 +195,10 @@ const MAPPING: {
 	},
 
 	// Ephemeral, like text_delta: a live view wants it, the durable record
-	// does not, and a chatty tool must not be able to bloat transcript.jsonl.
+	// does not, and a chatty tool must not be able to bloat the session log.
 	tool_progress: {
 		wire: 'tool.progress',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			tool_use_id: e.toolUseId,
 			tool_name: e.toolName,
 			message: e.message,
@@ -216,13 +206,12 @@ const MAPPING: {
 		}),
 	},
 
-	// Same reason as `tool_progress`, for the other half of a run's wall
+	// Same reason as `tool_progress`, for the other half of a turn's wall
 	// clock: a backoff can run for the better part of a minute, and without
 	// this the client gets no event and no keepalive for its duration.
 	provider_retry: {
 		wire: 'provider.retry',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			attempt: e.attempt,
 			max_retries: e.maxRetries,
@@ -235,8 +224,7 @@ const MAPPING: {
 
 	provider_fallback: {
 		wire: 'provider.fallback',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			from_index: e.fromIndex,
 			from_provider_id: e.fromProviderId,
@@ -252,8 +240,7 @@ const MAPPING: {
 
 	user_question_asked: {
 		wire: 'question.asked',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			checkpoint_id: e.checkpointId,
 			question_id: e.questionId,
 			question: e.question,
@@ -262,8 +249,7 @@ const MAPPING: {
 
 	user_question_answered: {
 		wire: 'question.answered',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			checkpoint_id: e.checkpointId,
 			question_id: e.questionId ?? null,
 			answered: e.answered,
@@ -272,8 +258,7 @@ const MAPPING: {
 
 	tool_completed: {
 		wire: 'tool.completed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			tool_use_id: e.toolUseId,
 			tool_name: e.toolName,
 			result: e.result,
@@ -283,8 +268,7 @@ const MAPPING: {
 
 	tool_review_requested: {
 		wire: 'review.requested',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			tool_calls: e.toolCalls,
 			iteration: e.iteration,
 		}),
@@ -292,25 +276,22 @@ const MAPPING: {
 
 	tool_review_completed: {
 		wire: 'review.completed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			decision: e.decision,
 		}),
 	},
 
 	checkpoint_created: {
 		wire: 'checkpoint.created',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			checkpoint_id: e.checkpointId,
 			iteration: e.iteration,
 		}),
 	},
 
-	run_paused: {
-		wire: 'run.paused',
-		transform: (e, runId) => ({
-			run_id: runId,
+	turn_paused: {
+		wire: 'turn.paused',
+		transform: (e) => ({
 			checkpoint_id: e.checkpointId,
 			reason: e.reason,
 			...(e.failure ? { failure: e.failure } : {}),
@@ -319,18 +300,16 @@ const MAPPING: {
 		}),
 	},
 
-	run_resuming: {
-		wire: 'run.resuming',
-		transform: (e, runId) => ({
-			run_id: runId,
+	turn_resuming: {
+		wire: 'turn.resuming',
+		transform: (e) => ({
 			from_checkpoint_id: e.fromCheckpointId,
 		}),
 	},
 
 	token_usage_updated: {
 		wire: 'token.usage',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			usage: e.usage,
 			cost: e.cost,
 			// Carried, and named apart from `usage` on the wire as well as in
@@ -348,8 +327,7 @@ const MAPPING: {
 
 	activity_created: {
 		wire: 'activity.created',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			activity_id: e.activityId,
 			activity_type: e.activityType,
 			description: e.description,
@@ -358,8 +336,7 @@ const MAPPING: {
 
 	activity_updated: {
 		wire: 'activity.updated',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			activity_id: e.activityId,
 			status: e.status,
 			output: e.output,
@@ -369,8 +346,7 @@ const MAPPING: {
 
 	plan_ready: {
 		wire: 'plan.ready',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			plan_id: e.planId,
 			title: e.title,
 			steps: e.steps,
@@ -380,13 +356,12 @@ const MAPPING: {
 
 	plan_approved: {
 		wire: 'plan.approved',
-		transform: (e, runId) => ({ run_id: runId, plan_id: e.planId }),
+		transform: (e) => ({ plan_id: e.planId }),
 	},
 
 	plan_rejected: {
 		wire: 'plan.rejected',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			plan_id: e.planId,
 			reason: e.reason,
 		}),
@@ -394,13 +369,12 @@ const MAPPING: {
 
 	plan_completed: {
 		wire: 'plan.completed',
-		transform: (e, runId) => ({ run_id: runId, plan_id: e.planId }),
+		transform: (e) => ({ plan_id: e.planId }),
 	},
 
 	plan_failed: {
 		wire: 'plan.failed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			plan_id: e.planId,
 			reason: e.reason,
 		}),
@@ -408,29 +382,31 @@ const MAPPING: {
 
 	plan_step_updated: {
 		wire: 'plan.step_updated',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			plan_id: e.planId,
 			step_id: e.stepId,
 			status: e.status,
 		}),
 	},
 
-	run_completed: null,
-	run_failed: null,
+	// The host that serves the stream writes `turn.completed`, `turn.failed`
+	// and `turn.cancelled` from the settled turn, with the wire status and
+	// usage it reports for it. Mapping the events too would put two terminal
+	// frames on one stream.
+	turn_completed: null,
+	turn_failed: null,
 
 	// Not mapped to a wire event yet — hosts consume `capability_warning`
-	// from the RunEvent stream directly; promoting it to the SSE contract
-	// needs a StreamEventType addition first.
+	// from the SessionEvent stream directly; promoting it to the SSE contract
+	// needs a SessionStreamEventType addition first.
 	capability_warning: null,
-	// Counts describing a local storage repair are likewise a RunEvent host
+	// Counts describing a local storage repair are likewise a SessionEvent host
 	// diagnostic, not yet part of the public SSE wire vocabulary.
 	message_history_repaired: null,
 
 	agent_pending: {
 		wire: 'agent.pending',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			task_id: e.taskId,
 			parent_agent_id: e.parentAgentId,
 			child_agent_id: e.childAgentId,
@@ -453,8 +429,7 @@ const MAPPING: {
 
 	agent_completed: {
 		wire: 'agent.completed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			task_id: e.taskId,
 			result: e.result?.result,
 		}),
@@ -462,8 +437,7 @@ const MAPPING: {
 
 	agent_failed: {
 		wire: 'agent.failed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			task_id: e.taskId,
 			error: e.error,
 		}),
@@ -471,16 +445,14 @@ const MAPPING: {
 
 	agent_canceled: {
 		wire: 'agent.canceled',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			task_id: e.taskId,
 		}),
 	},
 
 	task_created: {
 		wire: 'task.created',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			task_id: e.taskId,
 			subject: e.subject,
 			status: e.status,
@@ -489,8 +461,7 @@ const MAPPING: {
 
 	task_updated: {
 		wire: 'task.updated',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			task_id: e.taskId,
 			subject: e.subject,
 			status: e.status,
@@ -500,8 +471,7 @@ const MAPPING: {
 
 	plugin_hook_executing: {
 		wire: 'plugin.hook_executing',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			plugin_id: e.pluginId,
 			hook_event: e.hookEvent,
 		}),
@@ -509,8 +479,7 @@ const MAPPING: {
 
 	plugin_hook_completed: {
 		wire: 'plugin.hook_completed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			plugin_id: e.pluginId,
 			hook_event: e.hookEvent,
 			result_action: e.result.action,
@@ -519,8 +488,7 @@ const MAPPING: {
 
 	sandbox_created: {
 		wire: 'sandbox.created',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			sandbox_id: e.sandboxId,
 			environment: e.environment,
 		}),
@@ -528,8 +496,7 @@ const MAPPING: {
 
 	sandbox_exec: {
 		wire: 'sandbox.exec',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			sandbox_id: e.sandboxId,
 			command: e.command,
 			exit_code: e.exitCode,
@@ -539,15 +506,15 @@ const MAPPING: {
 
 	sandbox_destroyed: {
 		wire: 'sandbox.destroyed',
-		transform: (e, runId) => ({ run_id: runId, sandbox_id: e.sandboxId }),
+		transform: (e) => ({ sandbox_id: e.sandboxId }),
 	},
 
-	// Sub-session lifecycle events (session-hierarchy.md §10.4). These are
-	// in-flight signals carried on the kernel bus; the SSE wire surface does
-	// not emit them today.
-	subsession_spawned: null,
-	subsession_messaged: null,
-	subsession_idled: null,
+	// Child-session lifecycle events. The parent's log records them, and a
+	// client learns about delegated work from `agent.pending` and its siblings;
+	// the SSE wire surface does not emit these today.
+	child_session_spawned: null,
+	child_session_messaged: null,
+	child_session_idled: null,
 
 	// v3 message + tool-input lifecycle (ses_001-tool-stream-events). Additive
 	// today; the orchestrator does not yet emit these. Phase 4 of the
@@ -555,8 +522,7 @@ const MAPPING: {
 	// from this map.
 	message_started: {
 		wire: 'message.created',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			message_id: e.messageId,
 		}),
@@ -564,8 +530,7 @@ const MAPPING: {
 
 	text_delta: {
 		wire: 'message.delta',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			message_id: e.messageId,
 			text: e.text,
@@ -574,8 +539,7 @@ const MAPPING: {
 
 	message_completed: {
 		wire: 'message.completed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			message_id: e.messageId,
 			stop_reason: e.stopReason,
@@ -585,8 +549,7 @@ const MAPPING: {
 
 	tool_input_started: {
 		wire: 'tool.input_started',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			iteration: e.iteration,
 			message_id: e.messageId,
 			tool_use_id: e.toolUseId,
@@ -596,8 +559,7 @@ const MAPPING: {
 
 	tool_input_delta: {
 		wire: 'tool.input_delta',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			tool_use_id: e.toolUseId,
 			partial_json: e.partialJson,
 		}),
@@ -605,22 +567,31 @@ const MAPPING: {
 
 	tool_input_completed: {
 		wire: 'tool.input_completed',
-		transform: (e, runId) => ({
-			run_id: runId,
+		transform: (e) => ({
 			tool_use_id: e.toolUseId,
 			input: e.input,
 		}),
 	},
 }
 
-export function mapRunToStreamEvent(event: RunEvent, runId: RunId): MappedStreamEvent | null {
+/**
+ * One session event as an SSE frame, or `null` for an event the wire does not
+ * carry.
+ *
+ * Every payload names the session the event belongs to (`session_id`) and,
+ * when it happened inside a turn, the turn (`turn_id`). Both come from the
+ * event itself, so a child session's event relayed on its parent's stream
+ * names the child, which is the session whose log numbers it.
+ */
+export function mapSessionEventToStreamEvent(event: SessionEvent): MappedStreamEvent | null {
 	const mapping = MAPPING[event.type]
 	if (!mapping) return null
 
-	const data = (mapping.transform as (event: RunEvent, runId: RunId) => Record<string, unknown>)(
-		event,
-		runId,
-	)
+	const data: Record<string, unknown> = {
+		session_id: event.sessionId,
+		...(event.turnId !== undefined ? { turn_id: event.turnId } : {}),
+		...(mapping.transform as (event: SessionEvent) => Record<string, unknown>)(event),
+	}
 
 	const annotated = event as unknown as Record<string, unknown>
 	if ('sourceAgentId' in annotated && annotated.sourceAgentId) {
@@ -630,16 +601,16 @@ export function mapRunToStreamEvent(event: RunEvent, runId: RunId): MappedStream
 		data.parent_task_id = annotated.parentTaskId
 	}
 
-	// Keyed on the event's OWN run id, not the stream's. A child's event
-	// arriving on a parent's stream is numbered in the child's log, so stamping
-	// the enclosing run here would produce a cursor that addresses the wrong
+	// Keyed on the event's OWN session, not the stream's. A child's event
+	// arriving on a parent's stream is numbered in the child's log, so the
+	// parent's id here would produce a cursor that addresses the wrong
 	// sequence — and it would look right.
 	return {
 		wire: mapping.wire,
 		data,
-		...(event.seq !== undefined ? { id: `${event.runId}:${event.seq}` } : {}),
+		...(event.seq !== undefined ? { id: `${event.sessionId}:${event.seq}` } : {}),
 	}
 }
 
-/** @deprecated Use mapRunToStreamEvent */
-export const mapSessionToStreamEvent = mapRunToStreamEvent
+/** @deprecated Use mapSessionEventToStreamEvent */
+export const mapSessionToStreamEvent = mapSessionEventToStreamEvent