@namzu/sdk 0.4.4 → 0.5.0

package/src/runtime/query/executor.ts

@@ -126,10 +126,27 @@ export class ToolExecutor {
 		try {
 			input = JSON.parse(toolCall.function.arguments)
 		} catch {
-			return {
-				toolCallId: toolCall.id,
-				output: `Error: Invalid JSON in tool arguments for "${toolName}"`,
-			}
+			// Codex M2: malformed JSON args used to return without ever
+			// emitting tool_executing or tool_completed, leaving UI cards
+			// orphaned in `streaming_input`. Emit the executing→completed
+			// terminal pair so the card lifecycle closes.
+			const message = `Error: Invalid JSON in tool arguments for "${toolName}"`
+			await this.emitEvent({
+				type: 'tool_executing',
+				runId: this.config.runId,
+				toolUseId: toolCall.id,
+				toolName,
+				input: {},
+			})
+			await this.emitEvent({
+				type: 'tool_completed',
+				runId: this.config.runId,
+				toolUseId: toolCall.id,
+				toolName,
+				result: message,
+				isError: true,
+			})
+			return { toolCallId: toolCall.id, output: message }
 		}
 
 		const preOutcome = await this.runPreToolHook(toolName, input)
@@ -152,6 +169,7 @@ export class ToolExecutor {
 		await this.emitEvent({
 			type: 'tool_executing',
 			runId: this.config.runId,
+			toolUseId: toolCall.id,
 			toolName,
 			input,
 		})
@@ -160,6 +178,7 @@ export class ToolExecutor {
 			{
 				type: 'tool_executing',
 				runId: this.config.runId,
+				toolUseId: toolCall.id,
 				toolName,
 				input,
 			},
@@ -178,6 +197,16 @@ export class ToolExecutor {
 			if (activity) {
 				this.activityStore.fail(activity.id, veto.message)
 			}
+			// Codex M1: probe veto used to skip tool_completed entirely.
+			// Emit the terminal event with isError so UI cards finalize.
+			await this.emitEvent({
+				type: 'tool_completed',
+				runId: this.config.runId,
+				toolUseId: toolCall.id,
+				toolName,
+				result: `Error: ${veto.message}`,
+				isError: true,
+			})
 			return {
 				toolCallId: toolCall.id,
 				output: `Error: ${veto.message}`,
@@ -189,7 +218,22 @@ export class ToolExecutor {
 		}
 
 		const startMs = Date.now()
-		const result = await this.config.tools.execute(toolName, input, toolContext)
+		// Codex M4: an unhandled throw from `tools.execute(...)` used to
+		// propagate up to `result.ts` as `run_failed` without emitting a
+		// terminal `tool_completed`, leaving UI cards stuck in `executing`.
+		// Wrap so any throw materialises as an error result.
+		let result: { success: boolean; output: string; error?: string }
+		try {
+			result = await this.config.tools.execute(toolName, input, toolContext)
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err)
+			this.log.warn('Tool execution threw', {
+				runId: this.config.runId,
+				tool: toolName,
+				error: message,
+			})
+			result = { success: false, output: '', error: message }
+		}
 		const durationMs = Date.now() - startMs
 
 		const rawOutput = result.success
@@ -236,8 +280,10 @@ export class ToolExecutor {
 		await this.emitEvent({
 			type: 'tool_completed',
 			runId: this.config.runId,
+			toolUseId: toolCall.id,
 			toolName,
 			result: output,
+			isError: effectiveIsError,
 		})
 
 		return { toolCallId: toolCall.id, output }
@@ -351,14 +397,17 @@ export class ToolExecutor {
 		await this.emitEvent({
 			type: 'tool_executing',
 			runId: this.config.runId,
+			toolUseId: toolCallId,
 			toolName,
 			input,
 		})
 		await this.emitEvent({
 			type: 'tool_completed',
 			runId: this.config.runId,
+			toolUseId: toolCallId,
 			toolName,
 			result: outcome.output,
+			isError: outcome.kind === 'error',
 		})
 		return { toolCallId, output: outcome.output }
 	}

package/src/runtime/query/index.ts

@@ -14,7 +14,7 @@ import { buildAdvisoryTools } from '../../tools/advisory/index.js'
 import { SearchToolsTool } from '../../tools/builtins/search-tools.js'
 import { buildTaskTools } from '../../tools/task/index.js'
 import type { AdvisoryConfig } from '../../types/advisory/index.js'
-import type { RuntimeToolOverrides } from '../../types/agent/base.js'
+import type { AgentRuntimeContext, RuntimeToolOverrides } from '../../types/agent/base.js'
 import type { AgentContextLevel } from '../../types/agent/factory.js'
 import {
 	type CheckpointId,
@@ -108,6 +108,8 @@ export interface QueryParams {
 
 	runtimeToolOverrides?: RuntimeToolOverrides
 
+	runtimeContext?: AgentRuntimeContext
+
 	taskGateway?: import('../../types/agent/gateway.js').TaskGateway
 
 	launchedTasks?: Map<
@@ -251,6 +253,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		basePrompt: params.basePrompt,
 		tools: params.tools,
 		allowedTools: params.allowedTools,
+		runtimeContext: params.runtimeContext,
 	})
 
 	const guard = new GuardCoordinator({
@@ -368,6 +371,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				basePrompt: contextLevel === 'full' ? params.basePrompt : undefined,
 				tools: params.tools,
 				allowedTools: params.allowedTools,
+				runtimeContext: params.runtimeContext,
 			}
 
 			const segments: PromptSegments = params.contextCache

package/src/runtime/query/iteration/index.ts

@@ -5,15 +5,23 @@ import type { WorkingStateManager } from '../../../compaction/manager.js'
 import type { CompactionConfig } from '../../../config/runtime.js'
 import type { PlanManager } from '../../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../../manager/run/persistence.js'
+import { collect } from '../../../provider/collect.js'
 import type { ActivityStore } from '../../../store/activity/memory.js'
 import { GENAI, NAMZU, agentIterationSpanName } from '../../../telemetry/attributes.js'
 import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import type { ResumeHandler } from '../../../types/hitl/index.js'
+import type { ToolUseId } from '../../../types/ids/index.js'
 import { createAssistantMessage, createUserMessage } from '../../../types/message/index.js'
-import type { LLMProvider } from '../../../types/provider/index.js'
+import type {
+	ChatCompletionResponse,
+	LLMProvider,
+	StreamChunk,
+} from '../../../types/provider/index.js'
 import type { AgentRunConfig, RunEvent, StopReason } from '../../../types/run/index.js'
+import type { MessageStopReason } from '../../../types/run/stop-reason.js'
 import type { ToolRegistryContract } from '../../../types/tool/index.js'
 import { toErrorMessage } from '../../../utils/error.js'
+import { generateMessageId } from '../../../utils/id.js'
 import type { Logger } from '../../../utils/logger.js'
 import type { CheckpointManager } from '../checkpoint.js'
 import type { EmitEvent } from '../events.js'
@@ -50,6 +58,251 @@ export interface IterationConfig {
 	pluginManager?: import('../../../plugin/lifecycle.js').PluginLifecycleManager
 }
 
+/**
+ * Map a provider's coarse `finishReason` plus the orchestrator's
+ * `forceFinalize` flag onto the per-message {@link MessageStopReason}
+ * union the v3 `message_completed` event surfaces.
+ */
+function synthesizeMessageStopReason(
+	finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter',
+	forceFinalize: boolean,
+): MessageStopReason {
+	if (forceFinalize) return 'forced_finalize'
+	switch (finishReason) {
+		case 'tool_calls':
+			return 'tool_use'
+		case 'length':
+			return 'max_tokens'
+		case 'content_filter':
+			return 'refusal'
+		default:
+			return 'end_turn'
+	}
+}
+
+interface StreamingTurnResult {
+	response: ChatCompletionResponse
+	messageId: import('../../../types/ids/index.js').MessageId
+}
+
+/**
+ * Consume a provider's streaming response and emit the v3 RunEvent
+ * lifecycle natively (message_started → text_delta* + tool_input_*
+ * → message_completed). Returns the aggregated `ChatCompletionResponse`
+ * for downstream code that still expects the legacy shape (assistant
+ * message construction, working-state extraction, telemetry attribute
+ * stamping).
+ *
+ * Per-delta `emitEvent` calls are followed by a `drainPending()`
+ * yield so SSE consumers see live progress instead of a burst at
+ * end-of-message. The bus's ephemeral filter (D1) ensures these
+ * deltas never hit transcript.jsonl.
+ *
+ * Edge cases (codex A3, A4, A5):
+ * - Stream ends without `finishReason` (anthropic-sdk-typescript#842
+ *   dropped message_stop): we still emit `message_completed` from a
+ *   finally-style fall-through path with `stopReason: 'refusal'`.
+ * - `tool_input_delta` with no `toolUseId` registered yet: we drop
+ *   the fragment and log a warning (proxies seen to misorder events).
+ * - `chunk.error`: we surface as a thrown error after emitting the
+ *   message_completed terminator so consumer cards still close.
+ */
+async function* streamProviderTurn(
+	provider: LLMProvider,
+	params: import('../../../types/provider/index.js').ChatCompletionParams,
+	emitEvent: EmitEvent,
+	drainPending: () => Generator<RunEvent>,
+	runId: import('../../../types/ids/index.js').RunId,
+	iteration: number,
+	forceFinalize: boolean,
+	log: Logger,
+): AsyncGenerator<RunEvent, StreamingTurnResult> {
+	const messageId = generateMessageId()
+	await emitEvent({ type: 'message_started', runId, iteration, messageId })
+	yield* drainPending()
+
+	let id = ''
+	const model = ''
+	let textBuf = ''
+	let finishReason: ChatCompletionResponse['finishReason'] = 'stop'
+	let usage: ChatCompletionResponse['usage'] = {
+		promptTokens: 0,
+		completionTokens: 0,
+		totalTokens: 0,
+		cachedTokens: 0,
+		cacheWriteTokens: 0,
+	}
+	const toolBuckets = new Map<
+		number,
+		{ id: string; name: string; argsBuf: string; started: boolean; completed: boolean }
+	>()
+	let streamError: string | undefined
+
+	const stream = provider.chatStream({ ...params, stream: true }) as AsyncIterable<StreamChunk>
+
+	try {
+		for await (const chunk of stream) {
+			if (chunk.error) {
+				streamError = chunk.error
+				break
+			}
+			if (!id && chunk.id) id = chunk.id
+
+			if (chunk.delta.content) {
+				textBuf += chunk.delta.content
+				await emitEvent({
+					type: 'text_delta',
+					runId,
+					iteration,
+					messageId,
+					text: chunk.delta.content,
+				})
+				yield* drainPending()
+			}
+
+			for (const tc of chunk.delta.toolCalls ?? []) {
+				let bucket = toolBuckets.get(tc.index)
+				if (!bucket) {
+					bucket = {
+						id: tc.id ?? '',
+						name: tc.function?.name ?? '',
+						argsBuf: '',
+						started: false,
+						completed: false,
+					}
+					toolBuckets.set(tc.index, bucket)
+				}
+				if (tc.id && !bucket.id) bucket.id = tc.id
+				if (tc.function?.name && !bucket.name) bucket.name = tc.function.name
+
+				if (!bucket.started && bucket.id && bucket.name) {
+					bucket.started = true
+					await emitEvent({
+						type: 'tool_input_started',
+						runId,
+						iteration,
+						messageId,
+						toolUseId: bucket.id as ToolUseId,
+						toolName: bucket.name,
+					})
+					yield* drainPending()
+				}
+
+				const fragment = tc.function?.arguments
+				if (fragment) {
+					if (!bucket.id) {
+						log.warn('tool_input_delta arrived before tool id was known; dropping fragment', {
+							runId,
+							index: tc.index,
+							length: fragment.length,
+						})
+					} else {
+						bucket.argsBuf += fragment
+						await emitEvent({
+							type: 'tool_input_delta',
+							runId,
+							toolUseId: bucket.id as ToolUseId,
+							partialJson: fragment,
+						})
+						yield* drainPending()
+					}
+				}
+			}
+
+			if (chunk.delta.toolCallEnd) {
+				const { index, id: endId } = chunk.delta.toolCallEnd
+				const bucket = toolBuckets.get(index)
+				if (bucket && !bucket.completed) {
+					bucket.completed = true
+					let parsed: unknown = {}
+					try {
+						parsed = bucket.argsBuf ? JSON.parse(bucket.argsBuf) : {}
+					} catch (err) {
+						log.warn('tool input JSON parse failed at content_block_stop', {
+							runId,
+							toolUseId: endId,
+							error: err instanceof Error ? err.message : String(err),
+						})
+					}
+					await emitEvent({
+						type: 'tool_input_completed',
+						runId,
+						toolUseId: endId as ToolUseId,
+						input: parsed,
+					})
+					yield* drainPending()
+				}
+			}
+
+			if (chunk.finishReason) finishReason = chunk.finishReason
+			if (chunk.usage) usage = chunk.usage
+		}
+	} catch (err) {
+		streamError = err instanceof Error ? err.message : String(err)
+	}
+
+	// Flush any tool buckets the provider failed to close (no toolCallEnd
+	// arrived — defensive against providers that don't yet emit it).
+	for (const bucket of toolBuckets.values()) {
+		if (bucket.started && !bucket.completed) {
+			bucket.completed = true
+			let parsed: unknown = {}
+			try {
+				parsed = bucket.argsBuf ? JSON.parse(bucket.argsBuf) : {}
+			} catch {
+				// leave parsed = {}
+			}
+			await emitEvent({
+				type: 'tool_input_completed',
+				runId,
+				toolUseId: bucket.id as ToolUseId,
+				input: parsed,
+			})
+			yield* drainPending()
+		}
+	}
+
+	const stopReason: MessageStopReason = streamError
+		? 'refusal'
+		: synthesizeMessageStopReason(finishReason, forceFinalize)
+
+	await emitEvent({
+		type: 'message_completed',
+		runId,
+		iteration,
+		messageId,
+		stopReason,
+		usage,
+		content: textBuf || undefined,
+	})
+	yield* drainPending()
+
+	if (streamError) {
+		throw new Error(`Provider stream error: ${streamError}`)
+	}
+
+	const toolCalls = [...toolBuckets.entries()]
+		.sort(([a], [b]) => a - b)
+		.map(([, b]) => ({
+			id: b.id,
+			type: 'function' as const,
+			function: { name: b.name, arguments: b.argsBuf },
+		}))
+
+	const response: ChatCompletionResponse = {
+		id: id || messageId,
+		model: model || params.model,
+		message: {
+			role: 'assistant',
+			content: textBuf.length > 0 ? textBuf : null,
+			toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+		},
+		finishReason,
+		usage,
+	}
+	return { response, messageId }
+}
+
 export class IterationOrchestrator {
 	private ctx: IterationContext
 
@@ -214,14 +467,31 @@ export class IterationOrchestrator {
 						yield* this.ctx.drainPending()
 					}
 
-					const response = await this.ctx.provider.chat({
-						model,
-						messages,
-						tools: openAITools && openAITools.length > 0 ? openAITools : undefined,
-						temperature: runConfig.temperature,
-						maxTokens: runConfig.maxResponseTokens,
-						cacheControl: { type: 'auto' },
-					})
+					// Phase 4 (ses_001-tool-stream-events): consume the
+					// streaming response natively, emitting message and
+					// tool-input lifecycle events as deltas arrive. The
+					// helper yields RunEvents through drainPending() so SSE
+					// consumers see live progress; its return value is the
+					// aggregated `ChatCompletionResponse` for the legacy
+					// downstream paths (assistantMsg construction, working
+					// state extraction, telemetry attribute stamping).
+					const { response } = yield* streamProviderTurn(
+						this.ctx.provider,
+						{
+							model,
+							messages,
+							tools: openAITools && openAITools.length > 0 ? openAITools : undefined,
+							temperature: runConfig.temperature,
+							maxTokens: runConfig.maxResponseTokens,
+							cacheControl: { type: 'auto' },
+						},
+						this.ctx.emitEvent,
+						this.ctx.drainPending,
+						runMgr.id,
+						iterationNum,
+						forceFinalize,
+						this.ctx.log,
+					)
 
 					runMgr.accumulateUsage(response.usage)
 
@@ -268,13 +538,6 @@ export class IterationOrchestrator {
 						)
 					}
 
-					await this.ctx.emitEvent({
-						type: 'llm_response',
-						runId: runMgr.id,
-						content: response.message.content,
-						hasToolCalls: forceFinalize ? false : !!response.message.toolCalls?.length,
-					})
-
 					yield* this.ctx.drainPending()
 
 					iterSpan.setAttributes({
@@ -490,24 +753,36 @@ export class IterationOrchestrator {
 				),
 			]
 
-			const response = await this.ctx.provider.chat({
-				model,
-				messages: finalMessages,
-				temperature: this.ctx.runConfig.temperature,
-				maxTokens: this.ctx.runConfig.maxResponseTokens,
-				cacheControl: { type: 'auto' },
-			})
+			const response = await collect(
+				this.ctx.provider.chatStream({
+					model,
+					messages: finalMessages,
+					temperature: this.ctx.runConfig.temperature,
+					maxTokens: this.ctx.runConfig.maxResponseTokens,
+					cacheControl: { type: 'auto' },
+				}),
+			)
 
 			this.ctx.runMgr.accumulateUsage(response.usage)
 
 			const assistantMsg = createAssistantMessage(response.message.content)
 			this.ctx.runMgr.pushMessage(assistantMsg)
 
+			const finalMessageId = generateMessageId()
+			await this.ctx.emitEvent({
+				type: 'message_started',
+				runId: this.ctx.runMgr.id,
+				iteration: this.ctx.runMgr.currentIteration,
+				messageId: finalMessageId,
+			})
 			await this.ctx.emitEvent({
-				type: 'llm_response',
+				type: 'message_completed',
 				runId: this.ctx.runMgr.id,
-				content: response.message.content,
-				hasToolCalls: false,
+				iteration: this.ctx.runMgr.currentIteration,
+				messageId: finalMessageId,
+				stopReason: 'forced_finalize',
+				usage: response.usage,
+				content: response.message.content ?? undefined,
 			})
 		} catch (err) {
 			this.ctx.log.error('Failed to get final response', {

package/src/runtime/query/iteration/phases/compaction.ts

@@ -32,6 +32,8 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 
 	const estimatedTokens = estimateTokens(ctx)
 	const budget = ctx.runConfig.tokenBudget
+	if (budget <= 0) return
+
 	const usage = estimatedTokens / budget
 
 	if (usage < config.triggerThreshold) return

package/src/runtime/query/prompt.ts

@@ -1,5 +1,6 @@
 import { FILESYSTEM_TOOLS } from '../../constants/tools/index.js'
 import { assembleSystemPrompt } from '../../persona/assembler.js'
+import type { AgentRuntimeContext } from '../../types/agent/base.js'
 import type { AgentContextLevel } from '../../types/agent/factory.js'
 import type { AgentPersona } from '../../types/persona/index.js'
 import type { Skill } from '../../types/skills/index.js'
@@ -23,15 +24,40 @@ export interface PromptBuilderConfig {
 
 	tools: ToolRegistryContract
 	allowedTools?: string[]
+	runtimeContext?: AgentRuntimeContext
 }
 
-function buildEnvContext(workingDirectory: string): string {
-	return `<env>
+function buildEnvContext(workingDirectory: string, runtimeContext?: AgentRuntimeContext): string {
+	const lines = [
+		`<env>
 Working directory: ${workingDirectory}
-Platform: ${process.platform}
-</env>
+Platform: ${process.platform}`,
+	]
 
-IMPORTANT: Always use absolute paths based on the working directory above. Before reading a file, use the glob tool to discover actual file paths — never guess or hallucinate paths.`
+	if (runtimeContext?.label) {
+		lines.push(`Runtime: ${runtimeContext.label}`)
+	}
+
+	if (runtimeContext?.outputDirectory) {
+		lines.push(`Output directory: ${runtimeContext.outputDirectory}`)
+	}
+
+	if (runtimeContext?.outputFileMarker) {
+		lines.push(`Output file marker: ${runtimeContext.outputFileMarker}`)
+	}
+
+	if (runtimeContext?.notes?.length) {
+		lines.push('Runtime notes:')
+		for (const note of runtimeContext.notes) {
+			lines.push(`- ${note}`)
+		}
+	}
+
+	lines.push(`</env>
+
+IMPORTANT: Always use absolute paths based on the working directory above. Before reading a file, use the glob tool to discover actual file paths — never guess or hallucinate paths.`)
+
+	return lines.join('\n')
 }
 
 function hasFilesystemTools(tools: ToolRegistryContract, allowedTools?: string[]): boolean {
@@ -71,12 +97,13 @@ export class PromptBuilder {
 			}
 		}
 
-		if (
-			contextLevel !== 'minimal' &&
-			workingDirectory &&
-			hasFilesystemTools(this.config.tools, this.config.allowedTools)
-		) {
-			parts.push(buildEnvContext(workingDirectory))
+		if (contextLevel !== 'minimal' && workingDirectory) {
+			const shouldIncludeEnv =
+				hasFilesystemTools(this.config.tools, this.config.allowedTools) ||
+				Boolean(this.config.runtimeContext)
+			if (shouldIncludeEnv) {
+				parts.push(buildEnvContext(workingDirectory, this.config.runtimeContext))
+			}
 		}
 
 		return parts.join('\n\n---\n\n')
@@ -120,12 +147,13 @@ export class PromptBuilder {
 			}
 		}
 
-		if (
-			contextLevel !== 'minimal' &&
-			workingDirectory &&
-			hasFilesystemTools(this.config.tools, this.config.allowedTools)
-		) {
-			dynamicParts.push(buildEnvContext(workingDirectory))
+		if (contextLevel !== 'minimal' && workingDirectory) {
+			const shouldIncludeEnv =
+				hasFilesystemTools(this.config.tools, this.config.allowedTools) ||
+				Boolean(this.config.runtimeContext)
+			if (shouldIncludeEnv) {
+				dynamicParts.push(buildEnvContext(workingDirectory, this.config.runtimeContext))
+			}
 		}
 
 		return {

package/src/session/__tests__/integration/e2e-spawn.test.ts

@@ -182,12 +182,12 @@ describe('E2E — SubSession spawn → kernel summary → parent drill', () => {
 			expect(spawned.lineage.parentSessionId).toBe(parentSession.id)
 			expect(spawned.lineage.rootSessionId).toBe(parentSession.id)
 			expect(spawned.lineage.depth).toBe(1)
-			expect(spawned.schemaVersion).toBe(2)
+			expect(spawned.schemaVersion).toBe(3)
 		}
 		if (idled && 'lineage' in idled && 'schemaVersion' in idled) {
 			expect(idled.lineage.rootSessionId).toBe(parentSession.id)
 			expect(idled.lineage.depth).toBe(1)
-			expect(idled.schemaVersion).toBe(2)
+			expect(idled.schemaVersion).toBe(3)
 		}
 
 		// --- Summary materialized by kernel ---