@namzu/sdk 43.0.0 → 44.0.0

package/src/runtime/query/iteration/stream-turn.ts

@@ -27,8 +27,8 @@ import type {
 	LLMProvider,
 	StreamChunk,
 } from '../../../types/provider/index.js'
-import type { RunEvent } from '../../../types/run/index.js'
-import type { MessageStopReason } from '../../../types/run/stop-reason.js'
+import type { SessionEvent } from '../../../types/session/index.js'
+import type { MessageStopReason } from '../../../types/session/stop-reason.js'
 import { generateMessageId } from '../../../utils/id.js'
 import type { Logger } from '../../../utils/logger.js'
 import type { EmitEvent } from '../events.js'
@@ -65,7 +65,7 @@ export interface StreamingTurnResult {
 }
 
 /**
- * Consume a provider's streaming response and emit the v3 RunEvent
+ * Consume a provider's streaming response and emit the v3 SessionEvent
  * lifecycle natively (message_started → text_delta* + tool_input_*
  * → message_completed). Returns the aggregated `ChatCompletionResponse`
  * for downstream code that still expects the legacy shape (assistant
@@ -103,7 +103,7 @@ export interface StreamingTurnResult {
  */
 async function settleCancelledTurn(args: {
 	emitEvent: EmitEvent
-	runId: import('../../../types/ids/index.js').RunId
+	turnId: import('../../../types/ids/index.js').TurnId
 	iteration: number
 	messageId: import('../../../types/ids/index.js').MessageId
 	usage: ChatCompletionResponse['usage']
@@ -127,7 +127,7 @@ async function settleCancelledTurn(args: {
 
 		await args.emitEvent({
 			type: 'message_completed',
-			runId: args.runId,
+			turnId: args.turnId,
 			iteration: args.iteration,
 			messageId: args.messageId,
 			stopReason: 'cancelled',
@@ -144,8 +144,8 @@ export async function* streamProviderTurn(
 	provider: LLMProvider,
 	params: import('../../../types/provider/index.js').ChatCompletionParams,
 	emitEvent: EmitEvent,
-	drainPending: () => Generator<RunEvent>,
-	runId: import('../../../types/ids/index.js').RunId,
+	drainPending: () => Generator<SessionEvent>,
+	turnId: import('../../../types/ids/index.js').TurnId,
 	iteration: number,
 	forceFinalize: boolean,
 	log: Logger,
@@ -167,7 +167,9 @@ export async function* streamProviderTurn(
 		readonly onAccepted: (identity: RequestImageIdentity) => Promise<void>
 	},
 	captureRequest = false,
-): AsyncGenerator<RunEvent, StreamingTurnResult> {
+	/** The session the turn belongs to, named on the chat span as `gen_ai.conversation.id`. */
+	sessionId?: import('../../../types/ids/index.js').SessionId,
+): AsyncGenerator<SessionEvent, StreamingTurnResult> {
 	assertNativeStructuredOutputSupported(provider, params)
 	assertHostedWebSearchSupported(provider, params)
 	// The `chat {model}` span the GenAI conventions require. There was none:
@@ -180,6 +182,8 @@ export async function* streamProviderTurn(
 	chatSpan.setAttributes({
 		[GENAI.OPERATION_NAME]: 'chat',
 		[GENAI.REQUEST_MODEL]: params.model,
+		...(sessionId !== undefined ? { [GENAI.CONVERSATION_ID]: sessionId } : {}),
+		[NAMZU.TURN_ID]: turnId,
 		...(params.temperature !== undefined
 			? { [GENAI.REQUEST_TEMPERATURE]: params.temperature }
 			: {}),
@@ -187,7 +191,7 @@ export async function* streamProviderTurn(
 	})
 
 	const messageId = announceAs ?? generateMessageId()
-	await emitEvent({ type: 'message_started', runId, iteration, messageId })
+	await emitEvent({ type: 'message_started', turnId, iteration, messageId })
 	yield* drainPending()
 
 	let id = ''
@@ -268,11 +272,11 @@ export async function* streamProviderTurn(
 			: provider.chatStream(streamParams)
 	) as AsyncIterable<StreamChunk>
 
-	// Drive the stream manually so each `.next()` can be RACED against the run
+	// Drive the stream manually so each `.next()` can be RACED against the turn
 	// abort: a Stop tears the in-flight model request down (the provider got
 	// `params.signal`), and we ALSO stop pulling within a tick even if a
 	// transport buffers or ignores the signal. The abort rejection propagates
-	// out of this generator so the run loop settles the turn as cancelled.
+	// out of this generator so the turn loop settles the turn as cancelled.
 	// `{ once: true }` keeps a multi-iteration run from leaking a listener/turn.
 	const it = stream[Symbol.asyncIterator]()
 	const signal = params.signal
@@ -306,7 +310,7 @@ export async function* streamProviderTurn(
 			if (chunk.retry) {
 				await emitEvent({
 					type: 'provider_retry',
-					runId,
+					turnId,
 					iteration,
 					attempt: chunk.retry.attempt,
 					maxRetries: chunk.retry.maxRetries,
@@ -327,7 +331,7 @@ export async function* streamProviderTurn(
 			if (chunk.fallback) {
 				await emitEvent({
 					type: 'provider_fallback',
-					runId,
+					turnId,
 					iteration,
 					fromIndex: chunk.fallback.fromIndex,
 					fromProviderId: chunk.fallback.fromProviderId,
@@ -371,7 +375,7 @@ export async function* streamProviderTurn(
 			if (chunk.delta.hostedTool) {
 				await emitEvent({
 					type: 'hosted_tool',
-					runId,
+					turnId,
 					iteration,
 					tool: chunk.delta.hostedTool,
 				})
@@ -387,7 +391,7 @@ export async function* streamProviderTurn(
 					reasoningBuckets.set(reasoning.index, bucket)
 					await emitEvent({
 						type: 'reasoning_started',
-						runId,
+						turnId,
 						iteration,
 						messageId,
 						blockIndex: reasoning.index,
@@ -402,7 +406,7 @@ export async function* streamProviderTurn(
 					bucket.text += reasoning.text
 					await emitEvent({
 						type: 'reasoning_delta',
-						runId,
+						turnId,
 						iteration,
 						messageId,
 						blockIndex: reasoning.index,
@@ -413,7 +417,7 @@ export async function* streamProviderTurn(
 				if (reasoning.done) {
 					await emitEvent({
 						type: 'reasoning_completed',
-						runId,
+						turnId,
 						iteration,
 						messageId,
 						blockIndex: reasoning.index,
@@ -427,7 +431,7 @@ export async function* streamProviderTurn(
 			if (chunk.delta.content) {
 				await emitEvent({
 					type: 'text_delta',
-					runId,
+					turnId,
 					iteration,
 					messageId,
 					text: chunk.delta.content,
@@ -457,7 +461,7 @@ export async function* streamProviderTurn(
 					bucket.started = true
 					await emitEvent({
 						type: 'tool_input_started',
-						runId,
+						turnId,
 						iteration,
 						messageId,
 						toolUseId: bucket.id as ToolUseId,
@@ -470,7 +474,7 @@ export async function* streamProviderTurn(
 				if (fragment) {
 					if (!bucket.id) {
 						log.warn('tool_input_delta arrived before tool id was known; dropping fragment', {
-							[NAMZU.RUN_ID]: runId,
+							[NAMZU.TURN_ID]: turnId,
 							'namzu.runtime.index': tc.index,
 							'namzu.runtime.length': fragment.length,
 						})
@@ -478,7 +482,7 @@ export async function* streamProviderTurn(
 						bucket.argsBuf += fragment
 						await emitEvent({
 							type: 'tool_input_delta',
-							runId,
+							turnId,
 							toolUseId: bucket.id as ToolUseId,
 							partialJson: fragment,
 						})
@@ -498,7 +502,7 @@ export async function* streamProviderTurn(
 					} catch (err) {
 						bucket.inputTruncated = true
 						log.warn('tool input JSON parse failed at content_block_stop', {
-							[NAMZU.RUN_ID]: runId,
+							[NAMZU.TURN_ID]: turnId,
 							'namzu.runtime.tool_use_id': endId,
 							'exception.message': err instanceof Error ? err.message : String(err),
 						})
@@ -506,7 +510,7 @@ export async function* streamProviderTurn(
 					bucket.parsed = parsed
 					await emitEvent({
 						type: 'tool_input_completed',
-						runId,
+						turnId,
 						toolUseId: endId as ToolUseId,
 						input: parsed,
 						...(bucket.inputTruncated ? { inputTruncated: true } : {}),
@@ -522,7 +526,7 @@ export async function* streamProviderTurn(
 			if (chunk.usage) usage = mergeTokenUsage(usage, chunk.usage)
 		}
 	} catch (err) {
-		// An abort tears the turn down: propagate it so the run loop settles the
+		// An abort tears the turn down: propagate it so the turn loop settles the
 		// run as cancelled rather than recording a normal (errored) turn. Any
 		// other stream error is captured into the synthesized response as before.
 		if (signal?.aborted) {
@@ -538,7 +542,7 @@ export async function* streamProviderTurn(
 			// opposite of what its frequency deserves.
 			await settleCancelledTurn({
 				emitEvent,
-				runId,
+				turnId,
 				iteration,
 				messageId,
 				usage,
@@ -615,7 +619,7 @@ export async function* streamProviderTurn(
 			bucket.inputTruncated = truncated
 			if (truncated) {
 				log.warn('tool input truncated by upstream cutoff (no toolCallEnd, argsBuf unparsable)', {
-					[NAMZU.RUN_ID]: runId,
+					[NAMZU.TURN_ID]: turnId,
 					'namzu.runtime.tool_use_id': bucket.id,
 					[GENAI.TOOL_NAME]: bucket.name,
 					'namzu.runtime.buffer_length': bucket.argsBuf.length,
@@ -623,7 +627,7 @@ export async function* streamProviderTurn(
 			}
 			await emitEvent({
 				type: 'tool_input_completed',
-				runId,
+				turnId,
 				toolUseId: bucket.id as ToolUseId,
 				input: parsed,
 				...(truncated ? { inputTruncated: true } : {}),
@@ -666,7 +670,7 @@ export async function* streamProviderTurn(
 
 	if (recoveredToolInputFromStreamError) {
 		log.warn('provider stream failed after tool input; surfacing tool call to executor', {
-			[NAMZU.RUN_ID]: runId,
+			[NAMZU.TURN_ID]: turnId,
 			[NAMZU.ITERATION]: iteration,
 			'exception.message': streamError,
 			'namzu.runtime.tool_call_count': toolCalls.length,
@@ -681,7 +685,7 @@ export async function* streamProviderTurn(
 
 	await emitEvent({
 		type: 'message_completed',
-		runId,
+		turnId,
 		iteration,
 		messageId,
 		stopReason,
@@ -708,7 +712,7 @@ export async function* streamProviderTurn(
 		// identical faults settled oppositely depending on whether compaction
 		// happened to run that iteration.
 		if (streamCause instanceof ProviderError) throw streamCause
-		// The newer classified shape carries the same guarantee, and the run
+		// The newer classified shape carries the same guarantee, and the turn
 		// boundary reads it to decide between a pause and a failure.
 		if (isProviderRequestError(streamCause)) throw streamCause
 
@@ -752,8 +756,8 @@ export async function* streamProviderTurn(
 	}
 
 	// The same numbers as a MEASUREMENT, not only as a span attribute.
-	// A span answers "what happened in this run"; a metric answers "what is
-	// this costing across every run", and no amount of span attributes adds
+	// A span answers "what happened in this turn"; a metric answers "what is
+	// this costing across every turn", and no amount of span attributes adds
 	// up to the second question without a trace backend willing to
 	// aggregate them.
 	recordTokenUsage(params.model, usage)

package/src/runtime/query/plugin-hooks.ts

@@ -28,7 +28,7 @@ export function applyLifecycleHookResults(
 				continue
 			case 'skip':
 				// The one lifecycle event with a verdict: a hook may refuse the
-				// prompt before the model sees it, and the run ends there.
+				// prompt before the model sees it, and the turn ends there.
 				if (event === 'user_prompt_submit') {
 					throw new NamzuError({
 						code: 'plugin_error',