@namzu/sdk 0.4.2 → 0.4.3

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

@@ -0,0 +1,293 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 2):
+ *
+ *   - `mapRunToA2AEvent(event, contextId?)` is a one-way mapper: RunEvent →
+ *     A2AStreamEvent | null. There is no reverse mapper (§2.7).
+ *   - For events in MAPPING, the returned object is either a
+ *     TaskStatusUpdateEvent (with a `status` field) or a
+ *     TaskArtifactUpdateEvent (with an `artifact` field).
+ *   - For events explicitly mapped to null (iteration_completed,
+ *     tool_executing, sub-session lifecycle, etc.), the mapper returns
+ *     null — this is NOT a bug, it is the "bridge does not surface this"
+ *     contract. Asserting the null-set here pins the contract.
+ *   - `run_started` / `run_completed` / `run_failed` / `iteration_started`
+ *     / `run_paused` produce TaskStatusUpdateEvent with stable states:
+ *     running / completed / failed / running / input-required.
+ *   - `run_completed.final` is true; every non-terminal status event has
+ *     `final: false`.
+ *   - `llm_response` with null/empty `content` returns null; with content
+ *     returns a running status event.
+ *   - `tool_completed` produces an artifact event with `artifactId`
+ *     containing a timestamp and `metadata.toolName`.
+ *   - `tool_review_requested` and `plan_ready` attach data parts with
+ *     domain-specific mime types: `application/x-namzu-review-request`
+ *     and `application/x-namzu-plan`.
+ *   - `contextId` threads through into the returned event when provided.
+ *   - `mapSessionToA2AEvent` is a deprecated alias — identical behavior.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { CheckpointId, PlanId, RunId, TaskId } from '../../types/ids/index.js'
+import type { RunEvent } from '../../types/run/events.js'
+
+import { mapRunToA2AEvent, mapSessionToA2AEvent } from './mapper.js'
+
+const RID = 'run_1' as RunId
+
+function isStatusEvent(
+	e: ReturnType<typeof mapRunToA2AEvent>,
+): e is Extract<NonNullable<ReturnType<typeof mapRunToA2AEvent>>, { status: unknown }> {
+	return !!e && 'status' in e
+}
+
+function isArtifactEvent(
+	e: ReturnType<typeof mapRunToA2AEvent>,
+): e is Extract<NonNullable<ReturnType<typeof mapRunToA2AEvent>>, { artifact: unknown }> {
+	return !!e && 'artifact' in e
+}
+
+describe('mapRunToA2AEvent — mapped variants', () => {
+	it('run_started → running / not final / contextId threaded', () => {
+		const event: RunEvent = { type: 'run_started', runId: RID }
+		const a2a = mapRunToA2AEvent(event, 'ctx_42')
+		expect(isStatusEvent(a2a)).toBe(true)
+		if (isStatusEvent(a2a)) {
+			expect(a2a.status.state).toBe('running')
+			expect(a2a.final).toBe(false)
+			expect(a2a.contextId).toBe('ctx_42')
+			expect(a2a.taskId).toBe(RID)
+		}
+	})
+
+	it('run_completed → completed / final / message carries the result', () => {
+		const event: RunEvent = { type: 'run_completed', runId: RID, result: 'done' }
+		const a2a = mapRunToA2AEvent(event)
+		expect(isStatusEvent(a2a)).toBe(true)
+		if (isStatusEvent(a2a)) {
+			expect(a2a.status.state).toBe('completed')
+			expect(a2a.final).toBe(true)
+			expect(a2a.status.message?.parts).toEqual([{ kind: 'text', text: 'done' }])
+		}
+	})
+
+	it('run_failed → failed / final / message carries the error', () => {
+		const event: RunEvent = { type: 'run_failed', runId: RID, error: 'boom' }
+		const a2a = mapRunToA2AEvent(event)
+		expect(isStatusEvent(a2a)).toBe(true)
+		if (isStatusEvent(a2a)) {
+			expect(a2a.status.state).toBe('failed')
+			expect(a2a.final).toBe(true)
+			expect(a2a.status.message?.parts).toEqual([{ kind: 'text', text: 'boom' }])
+		}
+	})
+
+	it('iteration_started → running / not final / message names the iteration', () => {
+		const event: RunEvent = { type: 'iteration_started', runId: RID, iteration: 3 }
+		const a2a = mapRunToA2AEvent(event)
+		expect(isStatusEvent(a2a)).toBe(true)
+		if (isStatusEvent(a2a)) {
+			expect(a2a.status.state).toBe('running')
+			expect(a2a.final).toBe(false)
+			expect(a2a.status.message?.parts[0]).toMatchObject({
+				kind: 'text',
+				text: expect.stringContaining('Iteration 3'),
+			})
+		}
+	})
+
+	it('llm_response with content → running + text part', () => {
+		const event: RunEvent = { type: 'llm_response', runId: RID, content: 'hi', hasToolCalls: false }
+		const a2a = mapRunToA2AEvent(event)
+		expect(isStatusEvent(a2a)).toBe(true)
+		if (isStatusEvent(a2a)) {
+			expect(a2a.status.state).toBe('running')
+			expect(a2a.status.message?.parts).toEqual([{ kind: 'text', text: 'hi' }])
+		}
+	})
+
+	it('llm_response with null content → null', () => {
+		const event: RunEvent = { type: 'llm_response', runId: RID, content: null, hasToolCalls: true }
+		expect(mapRunToA2AEvent(event)).toBeNull()
+	})
+
+	it('llm_response with empty-string content → null (falsy)', () => {
+		const event: RunEvent = { type: 'llm_response', runId: RID, content: '', hasToolCalls: false }
+		expect(mapRunToA2AEvent(event)).toBeNull()
+	})
+
+	it('tool_completed → artifact with toolName metadata + timestamped id', () => {
+		const event: RunEvent = {
+			type: 'tool_completed',
+			runId: RID,
+			toolName: 'read_file',
+			result: 'ok',
+		}
+		const a2a = mapRunToA2AEvent(event)
+		expect(isArtifactEvent(a2a)).toBe(true)
+		if (isArtifactEvent(a2a)) {
+			expect(a2a.artifact.artifactId).toMatch(/^tool-read_file-\d+$/)
+			expect(a2a.artifact.name).toBe('read_file result')
+			expect(a2a.artifact.parts).toEqual([{ kind: 'text', text: 'ok' }])
+			expect(a2a.artifact.metadata).toEqual({ toolName: 'read_file' })
+		}
+	})
+
+	it('tool_review_requested → input-required + data part with review mime type', () => {
+		const event: RunEvent = {
+			type: 'tool_review_requested',
+			runId: RID,
+			iteration: 2,
+			toolCalls: [{ id: 'tc1', name: 'write_file', input: {}, isDestructive: true }],
+		}
+		const a2a = mapRunToA2AEvent(event)
+		expect(isStatusEvent(a2a)).toBe(true)
+		if (isStatusEvent(a2a)) {
+			expect(a2a.status.state).toBe('input-required')
+			const dataPart = a2a.status.message?.parts.find((p) => p.kind === 'data')
+			expect(dataPart).toBeDefined()
+			if (dataPart && dataPart.kind === 'data') {
+				expect(dataPart.mimeType).toBe('application/x-namzu-review-request')
+				expect(dataPart.data).toEqual({
+					toolCalls: [{ id: 'tc1', name: 'write_file', isDestructive: true }],
+				})
+			}
+		}
+	})
+
+	it('plan_ready → input-required + data part with plan mime type', () => {
+		const event: RunEvent = {
+			type: 'plan_ready',
+			runId: RID,
+			planId: 'plan_1' as PlanId,
+			title: 'Migrate tables',
+			summary: 'Three steps',
+			steps: [
+				{
+					id: 's1',
+					description: 'create schema',
+					toolName: 'bash',
+					dependsOn: [],
+					order: 0,
+					status: 'pending',
+				},
+			],
+		}
+		const a2a = mapRunToA2AEvent(event)
+		expect(isStatusEvent(a2a)).toBe(true)
+		if (isStatusEvent(a2a)) {
+			expect(a2a.status.state).toBe('input-required')
+			const dataPart = a2a.status.message?.parts.find((p) => p.kind === 'data')
+			expect(dataPart).toBeDefined()
+			if (dataPart && dataPart.kind === 'data') {
+				expect(dataPart.mimeType).toBe('application/x-namzu-plan')
+				expect(dataPart.data).toMatchObject({
+					planId: 'plan_1',
+					title: 'Migrate tables',
+					summary: 'Three steps',
+				})
+			}
+		}
+	})
+
+	it('run_paused → input-required + reason in text part', () => {
+		const event: RunEvent = {
+			type: 'run_paused',
+			runId: RID,
+			checkpointId: 'ckpt_1' as CheckpointId,
+			reason: 'waiting for review',
+		}
+		const a2a = mapRunToA2AEvent(event)
+		expect(isStatusEvent(a2a)).toBe(true)
+		if (isStatusEvent(a2a)) {
+			expect(a2a.status.state).toBe('input-required')
+			expect(a2a.status.message?.parts[0]).toMatchObject({
+				kind: 'text',
+				text: expect.stringContaining('waiting for review'),
+			})
+		}
+	})
+})
+
+describe('mapRunToA2AEvent — explicit null set', () => {
+	const nullEvents: RunEvent[] = [
+		{ type: 'iteration_completed', runId: RID, iteration: 1, hasToolCalls: false },
+		{ type: 'tool_executing', runId: RID, toolName: 'x', input: {} },
+		{ type: 'tool_review_completed', runId: RID, decision: 'approved' },
+		{
+			type: 'checkpoint_created',
+			runId: RID,
+			checkpointId: 'ckpt_1' as CheckpointId,
+			iteration: 1,
+		},
+		{ type: 'run_resuming', runId: RID, fromCheckpointId: 'ckpt_1' as CheckpointId },
+		{
+			type: 'token_usage_updated',
+			runId: RID,
+			usage: {
+				promptTokens: 0,
+				completionTokens: 0,
+				totalTokens: 0,
+				cachedTokens: 0,
+				cacheWriteTokens: 0,
+			},
+			cost: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 },
+		},
+		{ type: 'plan_approved', runId: RID, planId: 'plan_1' as PlanId },
+		{ type: 'plan_rejected', runId: RID, planId: 'plan_1' as PlanId },
+		{
+			type: 'agent_pending',
+			runId: RID,
+			taskId: 'task_1' as TaskId,
+			parentAgentId: 'a',
+			childAgentId: 'b',
+			depth: 1,
+		},
+		{
+			type: 'agent_completed',
+			runId: RID,
+			taskId: 'task_1' as TaskId,
+			result: {
+				runId: RID,
+				status: 'completed',
+				iterations: 1,
+				durationMs: 1,
+				messages: [],
+				usage: {
+					promptTokens: 0,
+					completionTokens: 0,
+					totalTokens: 0,
+					cachedTokens: 0,
+					cacheWriteTokens: 0,
+				},
+				cost: {
+					inputCostPer1M: 0,
+					outputCostPer1M: 0,
+					totalCost: 0,
+					cacheDiscount: 0,
+				},
+			},
+		},
+		{ type: 'agent_failed', runId: RID, taskId: 'task_1' as TaskId, error: 'e' },
+		{ type: 'agent_canceled', runId: RID, taskId: 'task_1' as TaskId },
+	]
+
+	it.each(nullEvents.map((e) => [e.type, e] as const))(
+		'%s returns null (bridge does not surface)',
+		(_name, event) => {
+			expect(mapRunToA2AEvent(event)).toBeNull()
+		},
+	)
+})
+
+describe('mapSessionToA2AEvent (deprecated alias)', () => {
+	it('is the same function reference as mapRunToA2AEvent', () => {
+		// toEqual against paired invocations races the ISO timestamp
+		// inside `statusEvent()` across a millisecond boundary; CI
+		// flaked once with 1 ms drift (see PR #11 Build & Test (22)
+		// 2026-04-22T11:13). Identity check is deterministic and
+		// asserts the deprecation shim strictly — not just a "similar
+		// output" check.
+		expect(mapSessionToA2AEvent).toBe(mapRunToA2AEvent)
+	})
+})

package/src/bridge/a2a/message.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 2):
+ *
+ *   - `messageToA2A(msg)` role mapping: user → user; assistant / system /
+ *     tool → agent. Any other MessageRole triggers the exhaustive-check
+ *     throw (unreachable via types).
+ *   - Non-empty `content` produces one text part.
+ *   - Assistant with `toolCalls`: one data part per tool call with
+ *     mimeType `application/x-namzu-tool-call` and fields
+ *     `{toolCallId, name, arguments}`.
+ *   - If the message would produce zero parts (null content, no tool
+ *     calls), a fallback empty-text part is added.
+ *   - `extractTextFromA2AMessage(msg)` joins text parts with '\n' and
+ *     ignores non-text parts entirely.
+ *   - `a2aMessageToInput` is a pure alias for `extractTextFromA2AMessage`.
+ *   - Only SDK → A2A direction is covered (design.md §2.7: no reverse
+ *     mapper exists).
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { A2AMessage } from '../../types/a2a/index.js'
+import type {
+	AssistantMessage,
+	SystemMessage,
+	ToolMessage,
+	UserMessage,
+} from '../../types/message/index.js'
+
+import { a2aMessageToInput, extractTextFromA2AMessage, messageToA2A } from './message.js'
+
+describe('messageToA2A', () => {
+	it('maps user role to user', () => {
+		const msg: UserMessage = { role: 'user', content: 'hi' }
+		expect(messageToA2A(msg).role).toBe('user')
+	})
+
+	it.each([['system'], ['assistant'], ['tool']])('maps %s role to agent', (role) => {
+		const msg = { role, content: 'x', ...(role === 'tool' && { toolCallId: 'c' }) } as
+			| SystemMessage
+			| AssistantMessage
+			| ToolMessage
+		expect(messageToA2A(msg).role).toBe('agent')
+	})
+
+	it('emits a single text part for content-only messages', () => {
+		const msg: UserMessage = { role: 'user', content: 'hello' }
+		const a2a = messageToA2A(msg)
+		expect(a2a.parts).toEqual([{ kind: 'text', text: 'hello' }])
+	})
+
+	it('emits text + data parts when the assistant has tool calls', () => {
+		const msg: AssistantMessage = {
+			role: 'assistant',
+			content: 'let me check',
+			toolCalls: [
+				{ id: 'tc1', type: 'function', function: { name: 'read_file', arguments: '{"p":"/a"}' } },
+				{ id: 'tc2', type: 'function', function: { name: 'list_dir', arguments: '{}' } },
+			],
+		}
+		const a2a = messageToA2A(msg)
+		expect(a2a.parts).toEqual([
+			{ kind: 'text', text: 'let me check' },
+			{
+				kind: 'data',
+				data: { toolCallId: 'tc1', name: 'read_file', arguments: '{"p":"/a"}' },
+				mimeType: 'application/x-namzu-tool-call',
+			},
+			{
+				kind: 'data',
+				data: { toolCallId: 'tc2', name: 'list_dir', arguments: '{}' },
+				mimeType: 'application/x-namzu-tool-call',
+			},
+		])
+	})
+
+	it('emits ONLY data parts (no text part) when content is null and tool calls exist', () => {
+		const msg: AssistantMessage = {
+			role: 'assistant',
+			content: null,
+			toolCalls: [{ id: 'tc1', type: 'function', function: { name: 'x', arguments: '{}' } }],
+		}
+		const a2a = messageToA2A(msg)
+		expect(a2a.parts.some((p) => p.kind === 'text')).toBe(false)
+		expect(a2a.parts.some((p) => p.kind === 'data')).toBe(true)
+	})
+
+	it('fallbacks to an empty text part when content is null and no tool calls', () => {
+		const msg: AssistantMessage = { role: 'assistant', content: null }
+		expect(messageToA2A(msg).parts).toEqual([{ kind: 'text', text: '' }])
+	})
+})
+
+describe('extractTextFromA2AMessage', () => {
+	it('joins every text part with a newline', () => {
+		const msg: A2AMessage = {
+			role: 'user',
+			parts: [
+				{ kind: 'text', text: 'line 1' },
+				{ kind: 'text', text: 'line 2' },
+			],
+		}
+		expect(extractTextFromA2AMessage(msg)).toBe('line 1\nline 2')
+	})
+
+	it('ignores non-text parts', () => {
+		const msg: A2AMessage = {
+			role: 'agent',
+			parts: [
+				{ kind: 'text', text: 'hello' },
+				{ kind: 'data', data: { foo: 1 }, mimeType: 'application/json' },
+			],
+		}
+		expect(extractTextFromA2AMessage(msg)).toBe('hello')
+	})
+
+	it('returns empty string when there are no text parts', () => {
+		const msg: A2AMessage = {
+			role: 'agent',
+			parts: [{ kind: 'data', data: {}, mimeType: 'x' }],
+		}
+		expect(extractTextFromA2AMessage(msg)).toBe('')
+	})
+})
+
+describe('a2aMessageToInput', () => {
+	it('behaves identically to extractTextFromA2AMessage', () => {
+		const msg: A2AMessage = {
+			role: 'user',
+			parts: [
+				{ kind: 'text', text: 'a' },
+				{ kind: 'text', text: 'b' },
+				{ kind: 'data', data: {}, mimeType: 'x' },
+			],
+		}
+		expect(a2aMessageToInput(msg)).toBe(extractTextFromA2AMessage(msg))
+	})
+})

package/src/bridge/a2a/task.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 2):
+ *
+ *   - `isTerminalState(state)` returns true iff state ∈ {completed,
+ *     failed, canceled, rejected}.
+ *   - `runStatusToA2AState(status)` is a table lookup:
+ *     queued → pending; running → running; completed → completed;
+ *     failed → failed; cancelled → canceled; cancelling → running;
+ *     expired → failed.
+ *   - `runToA2ATask(run, messages?)`:
+ *     - `id` comes from `run.id`; `contextId` comes from
+ *       `run.project_id ?? undefined`.
+ *     - `status.timestamp` picks the first defined of
+ *       `completed_at`, `started_at`, `created_at` (in that order).
+ *     - `status.message` is agent-text of `run.result` if present,
+ *       else of `run.last_error` if present, else undefined.
+ *     - `artifacts` is present iff `run.result` is present; the single
+ *       artifact carries a subset of usage + timing metadata.
+ *     - `history` is mapped through `messageToA2A` only when `messages`
+ *       is supplied.
+ *     - Top-level `metadata` carries agent_id, agent_name, stop_reason
+ *       (even if undefined).
+ *   - `a2aMessageToCreateRun(agentId, params)` only sets a metadata
+ *     field on `config` when the source value has the expected type
+ *     (string for model/systemPrompt; number for numeric fields;
+ *     'plan' | 'auto' for permissionMode). Everything else is omitted.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { ISOTimestamp, RunConfig, WireRun } from '../../contracts/index.js'
+import type { A2AMessage, A2AMessageSendParams, A2ATaskState } from '../../types/a2a/index.js'
+import type { ProjectId, RunId } from '../../types/ids/index.js'
+
+import {
+	a2aMessageToCreateRun,
+	isTerminalState,
+	runStatusToA2AState,
+	runToA2ATask,
+} from './task.js'
+
+const baseRun: WireRun = {
+	id: 'run_1' as RunId,
+	project_id: null,
+	agent_id: 'coder',
+	status: 'running',
+	created_at: '2026-04-21T12:00:00Z' as ISOTimestamp,
+	config: {} as RunConfig,
+}
+
+describe('isTerminalState', () => {
+	const terminals: A2ATaskState[] = ['completed', 'failed', 'canceled', 'rejected']
+	const nonTerminals: A2ATaskState[] = ['input-required', 'running', 'pending']
+
+	it.each(terminals.map((s) => [s]))('%s is terminal', (state) => {
+		expect(isTerminalState(state)).toBe(true)
+	})
+
+	it.each(nonTerminals.map((s) => [s]))('%s is not terminal', (state) => {
+		expect(isTerminalState(state)).toBe(false)
+	})
+})
+
+describe('runStatusToA2AState', () => {
+	it.each([
+		['queued', 'pending'],
+		['running', 'running'],
+		['completed', 'completed'],
+		['failed', 'failed'],
+		['cancelled', 'canceled'],
+		['cancelling', 'running'],
+		['expired', 'failed'],
+	] as const)('%s → %s', (wire, a2a) => {
+		expect(runStatusToA2AState(wire)).toBe(a2a)
+	})
+})
+
+describe('runToA2ATask', () => {
+	it('sets id + contextId from run.id + run.project_id', () => {
+		const task = runToA2ATask({ ...baseRun, project_id: 'proj_9' as ProjectId })
+		expect(task.id).toBe('run_1')
+		expect(task.contextId).toBe('proj_9')
+	})
+
+	it('contextId is undefined when project_id is null', () => {
+		const task = runToA2ATask(baseRun)
+		expect(task.contextId).toBeUndefined()
+	})
+
+	it('timestamp prefers completed_at > started_at > created_at', () => {
+		const created = '2026-04-21T10:00:00Z' as ISOTimestamp
+		const started = '2026-04-21T10:05:00Z' as ISOTimestamp
+		const completed = '2026-04-21T10:10:00Z' as ISOTimestamp
+
+		expect(
+			runToA2ATask({
+				...baseRun,
+				created_at: created,
+				started_at: started,
+				completed_at: completed,
+			}).status.timestamp,
+		).toBe(completed)
+		expect(
+			runToA2ATask({ ...baseRun, created_at: created, started_at: started }).status.timestamp,
+		).toBe(started)
+		expect(runToA2ATask({ ...baseRun, created_at: created }).status.timestamp).toBe(created)
+	})
+
+	it('status.message is the result text when result is present', () => {
+		const task = runToA2ATask({ ...baseRun, status: 'completed', result: 'all done' })
+		expect(task.status.message?.parts).toEqual([{ kind: 'text', text: 'all done' }])
+		expect(task.status.message?.role).toBe('agent')
+	})
+
+	it('status.message falls back to last_error when result is absent', () => {
+		const task = runToA2ATask({ ...baseRun, status: 'failed', last_error: 'boom' })
+		expect(task.status.message?.parts).toEqual([{ kind: 'text', text: 'boom' }])
+	})
+
+	it('status.message is undefined when neither result nor last_error is set', () => {
+		const task = runToA2ATask(baseRun)
+		expect(task.status.message).toBeUndefined()
+	})
+
+	it('attaches an artifact iff result is present', () => {
+		expect(runToA2ATask(baseRun).artifacts).toBeUndefined()
+
+		const withResult = runToA2ATask({
+			...baseRun,
+			status: 'completed',
+			result: 'done',
+			model: 'claude-opus-4-7',
+			iterations: 3,
+			duration_ms: 1200,
+			usage: { input_tokens: 10, output_tokens: 20, total_tokens: 30, total_cost_usd: 0.05 },
+		})
+		expect(withResult.artifacts).toHaveLength(1)
+		const artifact = withResult.artifacts?.[0]
+		expect(artifact?.artifactId).toBe('run_1-result')
+		expect(artifact?.name).toBe('Agent Response')
+		expect(artifact?.parts).toEqual([{ kind: 'text', text: 'done' }])
+		expect(artifact?.metadata).toMatchObject({
+			model: 'claude-opus-4-7',
+			iterations: 3,
+			duration_ms: 1200,
+			input_tokens: 10,
+			output_tokens: 20,
+			total_cost_usd: 0.05,
+		})
+	})
+
+	it('history is undefined when messages are not supplied', () => {
+		expect(runToA2ATask(baseRun).history).toBeUndefined()
+	})
+
+	it('history maps through messageToA2A for every message', () => {
+		const task = runToA2ATask(baseRun, [
+			{ role: 'user', content: 'hi' },
+			{ role: 'assistant', content: 'ack' },
+		])
+		expect(task.history).toHaveLength(2)
+		expect(task.history?.[0]?.role).toBe('user')
+		expect(task.history?.[1]?.role).toBe('agent')
+	})
+
+	it('top-level metadata carries agent_id + stop_reason', () => {
+		const task = runToA2ATask({ ...baseRun, agent_name: 'Coder', stop_reason: 'end_turn' })
+		expect(task.metadata).toMatchObject({
+			agent_id: 'coder',
+			agent_name: 'Coder',
+			stop_reason: 'end_turn',
+		})
+	})
+})
+
+describe('a2aMessageToCreateRun', () => {
+	const baseMsg: A2AMessage = { role: 'user', parts: [{ kind: 'text', text: 'do a thing' }] }
+
+	it('extracts input text from the message', () => {
+		const params: A2AMessageSendParams = { message: baseMsg }
+		const result = a2aMessageToCreateRun('agent_1', params)
+		expect(result.agentId).toBe('agent_1')
+		expect(result.input).toBe('do a thing')
+		expect(result.config).toEqual({})
+	})
+
+	it('threads contextId from params into projectId', () => {
+		const params: A2AMessageSendParams = { message: baseMsg, contextId: 'proj_2' }
+		expect(a2aMessageToCreateRun('agent_1', params).projectId).toBe('proj_2')
+	})
+
+	it('only includes typed metadata fields in config', () => {
+		const params: A2AMessageSendParams = {
+			message: baseMsg,
+			metadata: {
+				model: 'opus',
+				tokenBudget: 1000,
+				timeoutMs: 5000,
+				temperature: 0.2,
+				maxResponseTokens: 2048,
+				permissionMode: 'plan',
+				systemPrompt: 'be terse',
+			},
+		}
+		const config = a2aMessageToCreateRun('a', params).config
+		expect(config).toEqual({
+			model: 'opus',
+			tokenBudget: 1000,
+			timeoutMs: 5000,
+			temperature: 0.2,
+			maxResponseTokens: 2048,
+			permissionMode: 'plan',
+			systemPrompt: 'be terse',
+		})
+	})
+
+	it('drops metadata fields with wrong types', () => {
+		const params: A2AMessageSendParams = {
+			message: baseMsg,
+			metadata: {
+				model: 123, // wrong type → dropped
+				tokenBudget: 'big', // wrong type → dropped
+				permissionMode: 'invalid', // not 'plan'|'auto' → dropped
+			},
+		}
+		expect(a2aMessageToCreateRun('a', params).config).toEqual({})
+	})
+
+	it('accepts permissionMode only for "plan" or "auto"', () => {
+		for (const mode of ['plan', 'auto'] as const) {
+			const params: A2AMessageSendParams = { message: baseMsg, metadata: { permissionMode: mode } }
+			expect(a2aMessageToCreateRun('a', params).config.permissionMode).toBe(mode)
+		}
+	})
+})