@namzu/sdk 0.4.4 → 0.5.0

package/src/bridge/sse/mapper.test.ts

@@ -67,39 +67,43 @@ describe('mapRunToStreamEvent — mapped variants', () => {
 		expect(b).toEqual({ wire: 'iteration.completed', data: { run_id: RID, iteration: 2 } })
 	})
 
-	it('llm_response → message.delta with content + has_tool_calls', () => {
-		const r = mapRunToStreamEvent(
-			{ type: 'llm_response', runId: RID, content: 'hi', hasToolCalls: false },
-			RID,
-		)
-		expect(r).toEqual({
-			wire: 'message.delta',
-			data: { run_id: RID, content: 'hi', has_tool_calls: false },
-		})
-	})
-
-	it('llm_response with null content → content: null', () => {
-		const r = mapRunToStreamEvent(
-			{ type: 'llm_response', runId: RID, content: null, hasToolCalls: true },
-			RID,
-		)
-		expect(r?.data).toMatchObject({ content: null, has_tool_calls: true })
-	})
-
-	it('tool_executing / tool_completed carry tool_name + input/result', () => {
+	it('tool_executing / tool_completed carry tool_use_id, tool_name, input/result, is_error', () => {
+		const TUID = 'toolu_x'
 		const exec = mapRunToStreamEvent(
-			{ type: 'tool_executing', runId: RID, toolName: 'read_file', input: { path: '/a' } },
+			{
+				type: 'tool_executing',
+				runId: RID,
+				toolUseId: TUID,
+				toolName: 'read_file',
+				input: { path: '/a' },
+			},
 			RID,
 		)
 		expect(exec?.wire).toBe('tool.executing')
-		expect(exec?.data).toMatchObject({ tool_name: 'read_file', input: { path: '/a' } })
+		expect(exec?.data).toMatchObject({
+			tool_use_id: TUID,
+			tool_name: 'read_file',
+			input: { path: '/a' },
+		})
 
 		const done = mapRunToStreamEvent(
-			{ type: 'tool_completed', runId: RID, toolName: 'read_file', result: 'ok' },
+			{
+				type: 'tool_completed',
+				runId: RID,
+				toolUseId: TUID,
+				toolName: 'read_file',
+				result: 'ok',
+				isError: false,
+			},
 			RID,
 		)
 		expect(done?.wire).toBe('tool.completed')
-		expect(done?.data).toMatchObject({ tool_name: 'read_file', result: 'ok' })
+		expect(done?.data).toMatchObject({
+			tool_use_id: TUID,
+			tool_name: 'read_file',
+			result: 'ok',
+			is_error: false,
+		})
 	})
 
 	it('tool_review_requested / tool_review_completed carry review fields', () => {
@@ -410,6 +414,130 @@ describe('mapRunToStreamEvent — explicit null set', () => {
 	})
 })
 
+describe('mapRunToStreamEvent — v3 message and tool-input lifecycle', () => {
+	const MID = 'msg_1' as `msg_${string}`
+	const TUID = 'toolu_a'
+
+	it('message_started → message.created', () => {
+		const r = mapRunToStreamEvent(
+			{ type: 'message_started', runId: RID, iteration: 0, messageId: MID },
+			RID,
+		)
+		expect(r?.wire).toBe('message.created')
+		expect(r?.data).toMatchObject({ run_id: RID, iteration: 0, message_id: MID })
+	})
+
+	it('text_delta → message.delta carries raw text fragment', () => {
+		const r = mapRunToStreamEvent(
+			{
+				type: 'text_delta',
+				runId: RID,
+				iteration: 0,
+				messageId: MID,
+				text: 'hel',
+			},
+			RID,
+		)
+		expect(r?.wire).toBe('message.delta')
+		expect(r?.data).toMatchObject({ message_id: MID, text: 'hel' })
+	})
+
+	it('message_completed → message.completed carries stop reason and usage', () => {
+		const usage = {
+			promptTokens: 10,
+			completionTokens: 5,
+			totalTokens: 15,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		}
+		const r = mapRunToStreamEvent(
+			{
+				type: 'message_completed',
+				runId: RID,
+				iteration: 0,
+				messageId: MID,
+				stopReason: 'end_turn',
+				usage,
+			},
+			RID,
+		)
+		expect(r?.wire).toBe('message.completed')
+		expect(r?.data).toMatchObject({
+			message_id: MID,
+			stop_reason: 'end_turn',
+			usage,
+		})
+	})
+
+	it('message_completed without usage → usage: null (defensive against dropped message_stop)', () => {
+		const r = mapRunToStreamEvent(
+			{
+				type: 'message_completed',
+				runId: RID,
+				iteration: 0,
+				messageId: MID,
+				stopReason: 'tool_use',
+			},
+			RID,
+		)
+		expect(r?.data).toMatchObject({ usage: null })
+	})
+
+	it('tool_input_started → tool.input_started carries toolUseId + toolName', () => {
+		const r = mapRunToStreamEvent(
+			{
+				type: 'tool_input_started',
+				runId: RID,
+				iteration: 0,
+				messageId: MID,
+				toolUseId: TUID,
+				toolName: 'Read',
+			},
+			RID,
+		)
+		expect(r?.wire).toBe('tool.input_started')
+		expect(r?.data).toMatchObject({
+			tool_use_id: TUID,
+			tool_name: 'Read',
+			message_id: MID,
+		})
+	})
+
+	it('tool_input_delta → tool.input_delta carries raw partial JSON fragment', () => {
+		const r = mapRunToStreamEvent(
+			{
+				type: 'tool_input_delta',
+				runId: RID,
+				toolUseId: TUID,
+				partialJson: '{"file_path":"',
+			},
+			RID,
+		)
+		expect(r?.wire).toBe('tool.input_delta')
+		expect(r?.data).toMatchObject({
+			tool_use_id: TUID,
+			partial_json: '{"file_path":"',
+		})
+	})
+
+	it('tool_input_completed → tool.input_completed carries parsed input object', () => {
+		const r = mapRunToStreamEvent(
+			{
+				type: 'tool_input_completed',
+				runId: RID,
+				toolUseId: TUID,
+				input: { file_path: '/etc/passwd' },
+			},
+			RID,
+		)
+		expect(r?.wire).toBe('tool.input_completed')
+		expect(r?.data).toMatchObject({
+			tool_use_id: TUID,
+			input: { file_path: '/etc/passwd' },
+		})
+	})
+})
+
 describe('mapSessionToStreamEvent (deprecated alias)', () => {
 	it('is the same function reference as mapRunToStreamEvent', () => {
 		// Identity check is deterministic. toEqual on paired calls

package/src/bridge/sse/mapper.ts

@@ -33,19 +33,11 @@ const MAPPING: {
 		transform: (e, runId) => ({ run_id: runId, iteration: e.iteration }),
 	},
 
-	llm_response: {
-		wire: 'message.delta',
-		transform: (e, runId) => ({
-			run_id: runId,
-			content: e.content ?? null,
-			has_tool_calls: !!e.hasToolCalls,
-		}),
-	},
-
 	tool_executing: {
 		wire: 'tool.executing',
 		transform: (e, runId) => ({
 			run_id: runId,
+			tool_use_id: e.toolUseId,
 			tool_name: e.toolName,
 			input: e.input,
 		}),
@@ -55,8 +47,10 @@ const MAPPING: {
 		wire: 'tool.completed',
 		transform: (e, runId) => ({
 			run_id: runId,
+			tool_use_id: e.toolUseId,
 			tool_name: e.toolName,
 			result: e.result,
+			is_error: e.isError,
 		}),
 	},
 
@@ -279,6 +273,69 @@ const MAPPING: {
 	subsession_spawned: null,
 	subsession_messaged: null,
 	subsession_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
+	// migration switches the orchestrator over and removes `llm_response`
+	// from this map.
+	message_started: {
+		wire: 'message.created',
+		transform: (e, runId) => ({
+			run_id: runId,
+			iteration: e.iteration,
+			message_id: e.messageId,
+		}),
+	},
+
+	text_delta: {
+		wire: 'message.delta',
+		transform: (e, runId) => ({
+			run_id: runId,
+			iteration: e.iteration,
+			message_id: e.messageId,
+			text: e.text,
+		}),
+	},
+
+	message_completed: {
+		wire: 'message.completed',
+		transform: (e, runId) => ({
+			run_id: runId,
+			iteration: e.iteration,
+			message_id: e.messageId,
+			stop_reason: e.stopReason,
+			usage: e.usage ?? null,
+		}),
+	},
+
+	tool_input_started: {
+		wire: 'tool.input_started',
+		transform: (e, runId) => ({
+			run_id: runId,
+			iteration: e.iteration,
+			message_id: e.messageId,
+			tool_use_id: e.toolUseId,
+			tool_name: e.toolName,
+		}),
+	},
+
+	tool_input_delta: {
+		wire: 'tool.input_delta',
+		transform: (e, runId) => ({
+			run_id: runId,
+			tool_use_id: e.toolUseId,
+			partial_json: e.partialJson,
+		}),
+	},
+
+	tool_input_completed: {
+		wire: 'tool.input_completed',
+		transform: (e, runId) => ({
+			run_id: runId,
+			tool_use_id: e.toolUseId,
+			input: e.input,
+		}),
+	},
 }
 
 export function mapRunToStreamEvent(event: RunEvent, runId: RunId): MappedStreamEvent | null {

package/src/compaction/verifier.ts

@@ -1,4 +1,5 @@
 import type { CompactionConfig } from '../config/runtime.js'
+import { collect } from '../provider/collect.js'
 import type { Message } from '../types/message/index.js'
 import type { LLMProvider } from '../types/provider/interface.js'
 import type { WorkingStateManager } from './manager.js'
@@ -74,12 +75,14 @@ export async function buildVerifiedSummary(
 		},
 	]
 
-	const response = await provider.chat({
-		model: '',
-		messages: verificationMessages,
-		maxTokens: config.llmVerificationMaxTokens,
-		temperature: 0,
-	})
+	const response = await collect(
+		provider.chatStream({
+			model: '',
+			messages: verificationMessages,
+			maxTokens: config.llmVerificationMaxTokens,
+			temperature: 0,
+		}),
+	)
 
 	const responseText = response.message.content?.trim() ?? ''
 

package/src/config/runtime.ts

@@ -63,7 +63,7 @@ export type PluginRuntimeConfig = z.infer<typeof PluginRuntimeConfigSchema>
 export const RuntimeConfigSchema = z.object({
 	model: z.string().default('qwen/qwen3.6-plus:free'),
 	temperature: z.number().min(0).max(2).default(0.3),
-	tokenBudget: z.number().positive().default(100_000),
+	tokenBudget: z.number().nonnegative().default(100_000),
 	maxResponseTokens: z.number().positive().default(8192),
 	timeoutMs: z.number().positive().default(600_000),
 	maxIterations: z.number().positive().default(200),

package/src/contracts/api.ts

@@ -145,6 +145,13 @@ export type StreamEventType =
 	| 'tool.executing'
 	| 'tool.completed'
 	| 'tool.error'
+	// v3 tool input lifecycle (ses_001-tool-stream-events). Additive; phase 4
+	// of the migration removes `tool.error` and folds the boolean into
+	// `tool.completed`. Until then both surfaces are wire-supported so
+	// adapters can roll forward independently.
+	| 'tool.input_started'
+	| 'tool.input_delta'
+	| 'tool.input_completed'
 	| 'token.usage'
 	| 'message.created'
 	| 'message.delta'

package/src/contracts/schemas.ts

@@ -8,7 +8,7 @@ export const RunConfigSchema = z
 	.object({
 		model: z.string().min(1).optional(),
 		temperature: z.number().min(0).max(2).optional(),
-		tokenBudget: z.number().int().positive().optional(),
+		tokenBudget: z.number().int().nonnegative().optional(),
 		maxResponseTokens: z.number().int().positive().optional(),
 		timeoutMs: z.number().int().positive().max(3_600_000).optional(),
 		permissionMode: z.enum(['plan', 'auto']).optional(),

package/src/gateway/local.ts

@@ -14,7 +14,7 @@ export class LocalTaskGateway implements TaskGateway {
 	private listener: RunEventListener | undefined
 	private trackedTaskIds: Set<TaskId> = new Set()
 
-	private parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides'>
+	private parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides' | 'runtimeContext'>
 
 	private completionListeners: Set<(handle: TaskHandle) => void> = new Set()
 
@@ -22,7 +22,7 @@ export class LocalTaskGateway implements TaskGateway {
 		agentManager: AgentManagerContract,
 		taskContext: AgentTaskContext,
 		listener?: RunEventListener,
-		parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides'>,
+		parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides' | 'runtimeContext'>,
 	) {
 		this.agentManager = agentManager
 		this.taskContext = taskContext
@@ -39,6 +39,7 @@ export class LocalTaskGateway implements TaskGateway {
 					workingDirectory: options.workingDirectory,
 					taskStore: this.parentInput?.taskStore,
 					runtimeToolOverrides: this.parentInput?.runtimeToolOverrides,
+					runtimeContext: options.runtimeContext ?? this.parentInput?.runtimeContext,
 				},
 				// Phase 6: spawn scope propagates from the gateway's task context.
 				// The caller built it at SupervisorAgent boundary (§12.1).

package/src/manager/agent/__tests__/lifecycle.test.ts

@@ -258,14 +258,14 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 			expect(spawned.lineage.parentSessionId).toBe(harness.parentSession.id)
 			expect(spawned.lineage.rootSessionId).toBe(harness.parentSession.id)
 			expect(spawned.lineage.depth).toBe(1)
-			expect(spawned.schemaVersion).toBe(2)
+			expect(spawned.schemaVersion).toBe(3)
 		}
 
 		const idled = events.find((e) => e.type === 'subsession_idled')
 		expect(idled).toBeDefined()
 		if (idled && 'lineage' in idled) {
 			expect(idled.lineage.depth).toBe(1)
-			expect(idled.schemaVersion).toBe(2)
+			expect(idled.schemaVersion).toBe(3)
 		}
 	})
 

package/src/provider/collect.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Behavioural contract for `collect()` (ses_001-tool-stream-events phase 1A):
+ *
+ * - Drains a `StreamChunk` async iterable into a single
+ *   `ChatCompletionResponse` matching the legacy `provider.chat()` shape.
+ * - Concatenates `delta.content` in arrival order; null when no text
+ *   chunks ever arrive.
+ * - Buckets tool-call argument fragments by `index`; emits `toolCalls`
+ *   sorted by index. `id` and `function.name` come from the first chunk
+ *   that supplies them; `function.arguments` is the concatenation of all
+ *   `arguments` fragments for that index.
+ * - Latest-wins for `finishReason` and `usage`; defaults
+ *   `finishReason: 'stop'` and zero usage if the provider omits them
+ *   (defensive — see anthropics/anthropic-sdk-typescript#842).
+ * - Throws if any chunk surfaces a `chunk.error`.
+ *
+ * Phase 2 swaps every internal `provider.chat()` call site for
+ * `collect(provider.chatStream())`; the response shape parity guarded
+ * here is what makes that swap safe.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { StreamChunk } from '../types/provider/stream.js'
+
+import { collect } from './collect.js'
+
+async function* fromArray(chunks: StreamChunk[]): AsyncIterable<StreamChunk> {
+	for (const chunk of chunks) yield chunk
+}
+
+describe('collect()', () => {
+	it('aggregates text-only stream into single content string', async () => {
+		const result = await collect(
+			fromArray([
+				{ id: 'm1', delta: { content: 'hel' } },
+				{ id: 'm1', delta: { content: 'lo' } },
+				{ id: 'm1', delta: { content: ' world' } },
+				{ id: 'm1', delta: {}, finishReason: 'stop' },
+			]),
+		)
+		expect(result.message.content).toBe('hello world')
+		expect(result.message.toolCalls).toBeUndefined()
+		expect(result.finishReason).toBe('stop')
+		expect(result.id).toBe('m1')
+	})
+
+	it('returns content: null when no text chunks arrive', async () => {
+		const result = await collect(fromArray([{ id: 'm', delta: {}, finishReason: 'stop' }]))
+		expect(result.message.content).toBeNull()
+	})
+
+	it('buckets parallel tool calls by index, preserves order', async () => {
+		const result = await collect(
+			fromArray([
+				{
+					id: 'm',
+					delta: {
+						toolCalls: [
+							{ index: 0, id: 'toolu_a', function: { name: 'Read' } },
+							{ index: 1, id: 'toolu_b', function: { name: 'WebSearch' } },
+						],
+					},
+				},
+				{
+					id: 'm',
+					delta: {
+						toolCalls: [{ index: 1, function: { arguments: '{"query":"x"}' } }],
+					},
+				},
+				{
+					id: 'm',
+					delta: {
+						toolCalls: [
+							{ index: 0, function: { arguments: '{"file_path":' } },
+							{ index: 0, function: { arguments: '"/a"}' } },
+						],
+					},
+				},
+				{ id: 'm', delta: {}, finishReason: 'tool_calls' },
+			]),
+		)
+		expect(result.message.toolCalls).toEqual([
+			{
+				id: 'toolu_a',
+				type: 'function',
+				function: { name: 'Read', arguments: '{"file_path":"/a"}' },
+			},
+			{
+				id: 'toolu_b',
+				type: 'function',
+				function: { name: 'WebSearch', arguments: '{"query":"x"}' },
+			},
+		])
+		expect(result.finishReason).toBe('tool_calls')
+	})
+
+	it('latest finishReason and usage win', async () => {
+		const result = await collect(
+			fromArray([
+				{ id: 'm', delta: {}, finishReason: 'stop' },
+				{
+					id: 'm',
+					delta: {},
+					finishReason: 'length',
+					usage: {
+						promptTokens: 100,
+						completionTokens: 50,
+						totalTokens: 150,
+						cachedTokens: 0,
+						cacheWriteTokens: 0,
+					},
+				},
+			]),
+		)
+		expect(result.finishReason).toBe('length')
+		expect(result.usage.totalTokens).toBe(150)
+	})
+
+	it('defaults finishReason to stop and usage to zero when provider omits them', async () => {
+		const result = await collect(fromArray([{ id: 'm', delta: { content: 'hi' } }]))
+		expect(result.finishReason).toBe('stop')
+		expect(result.usage).toEqual({
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		})
+	})
+
+	it('throws on chunk.error', async () => {
+		await expect(
+			collect(
+				fromArray([
+					{ id: 'm', delta: { content: 'hi' } },
+					{ id: 'm', delta: {}, error: 'rate limited' },
+				]),
+			),
+		).rejects.toThrow('rate limited')
+	})
+})

package/src/provider/collect.ts

@@ -0,0 +1,85 @@
+import type { ChatCompletionResponse } from '../types/provider/chat.js'
+import type { StreamChunk } from '../types/provider/stream.js'
+
+/**
+ * Drains a {@link StreamChunk} async iterable into the equivalent
+ * non-streaming {@link ChatCompletionResponse}.
+ *
+ * Phase 2 of ses_001-tool-stream-events removes `LLMProvider.chat()`; the
+ * four internal callers that genuinely need the aggregated view (advisory
+ * executor, RouterAgent's deterministic routing decision, compaction's
+ * verifier, the instrumentation wrapper) replace `provider.chat(p)` with
+ * `collect(provider.chatStream(p))`.
+ *
+ * Behaviour matches the pre-removal `chat()` contract:
+ * - text content is concatenated in delta order;
+ * - tool calls are bucketed by `index` into the existing
+ *   `Array<{ id, function: { name, arguments } }>` shape;
+ * - usage and finishReason fall back to safe defaults when the provider
+ *   omits them (defensive — see anthropics/anthropic-sdk-typescript#842
+ *   where `message_stop` is occasionally dropped on connection close).
+ *
+ * The orchestrator does NOT call this helper — it consumes the stream
+ * directly so it can emit per-delta `RunEvent`s.
+ */
+export async function collect(stream: AsyncIterable<StreamChunk>): Promise<ChatCompletionResponse> {
+	let id = ''
+	const model = ''
+	let content = ''
+	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 }>()
+
+	for await (const chunk of stream) {
+		if (chunk.error) {
+			throw new Error(chunk.error)
+		}
+		if (!id && chunk.id) id = chunk.id
+
+		if (chunk.delta.content) {
+			content += chunk.delta.content
+		}
+
+		for (const tc of chunk.delta.toolCalls ?? []) {
+			const bucket = toolBuckets.get(tc.index) ?? {
+				id: '',
+				name: '',
+				argsBuf: '',
+			}
+			if (tc.id) bucket.id = tc.id
+			if (tc.function?.name) bucket.name = tc.function.name
+			if (tc.function?.arguments) bucket.argsBuf += tc.function.arguments
+			toolBuckets.set(tc.index, bucket)
+		}
+
+		if (chunk.finishReason) finishReason = chunk.finishReason
+		if (chunk.usage) usage = chunk.usage
+	}
+
+	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 },
+		}))
+
+	return {
+		id,
+		model,
+		message: {
+			role: 'assistant',
+			content: content.length > 0 ? content : null,
+			toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+		},
+		finishReason,
+		usage,
+	}
+}