@namzu/sdk 0.4.1 → 0.4.3

package/src/bridge/a2a/agent-card.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 2):
+ *
+ *   - `buildAgentCard(info, config, skills?)`:
+ *     - `name`, `description`, `version` are passed through from info.
+ *     - `protocolVersion` is pinned to `A2A_PROTOCOL_VERSION` (0.3.0).
+ *     - `provider.organization` defaults to 'Namzu' when
+ *       `config.providerOrganization` is absent.
+ *     - `capabilities.streaming` mirrors
+ *       `info.capabilities?.supportsStreaming` with false default;
+ *       `pushNotifications` + `extendedAgentCard` are always false.
+ *     - Each tool in `info.tools` becomes a skill with
+ *       `{id: 'tool-<name>', name: '<name>', tags: ['tool']}`.
+ *     - Each entry in the optional `skills` param becomes a skill with
+ *       `tags: ['procedure']` and id = name = skill.metadata.name.
+ *     - Tool skills come first, procedural skills after, in insertion
+ *       order.
+ *     - `supportedInterfaces[0].url` = `${config.baseUrl}/a2a/${info.id}`.
+ *     - `securitySchemes` always includes `bearer` + `securityRequirements`
+ *       is `[{bearer: []}]`.
+ *     - `defaultInputModes` and `defaultOutputModes` are `['text']`.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { AgentInfo } from '../../contracts/index.js'
+import type { A2AServerConfig } from '../../types/a2a/index.js'
+import type { Skill } from '../../types/skills/index.js'
+
+import { buildAgentCard } from './agent-card.js'
+
+const baseInfo: AgentInfo = {
+	id: 'coder',
+	name: 'Coder',
+	version: '1.0.0',
+	category: 'coding',
+	description: 'Writes code',
+	tools: ['read_file', 'write_file'],
+	defaults: { model: 'claude-opus-4-7', tokenBudget: 100_000 },
+}
+
+const baseConfig: A2AServerConfig = {
+	baseUrl: 'https://example.com',
+	transport: 'jsonrpc',
+}
+
+describe('buildAgentCard', () => {
+	it('passes name / description / version through', () => {
+		const card = buildAgentCard(baseInfo, baseConfig)
+		expect(card.name).toBe('Coder')
+		expect(card.description).toBe('Writes code')
+		expect(card.version).toBe('1.0.0')
+	})
+
+	it('pins protocolVersion to A2A_PROTOCOL_VERSION', () => {
+		const card = buildAgentCard(baseInfo, baseConfig)
+		expect(card.protocolVersion).toBe('0.3.0')
+	})
+
+	it('defaults provider.organization to Namzu when config omits it', () => {
+		const card = buildAgentCard(baseInfo, baseConfig)
+		expect(card.provider?.organization).toBe('Namzu')
+		expect(card.provider?.url).toBeUndefined()
+	})
+
+	it('uses config-supplied providerOrganization + providerUrl when given', () => {
+		const card = buildAgentCard(baseInfo, {
+			...baseConfig,
+			providerOrganization: 'ACME',
+			providerUrl: 'https://acme.io',
+		})
+		expect(card.provider?.organization).toBe('ACME')
+		expect(card.provider?.url).toBe('https://acme.io')
+	})
+
+	it('streaming capability mirrors info.capabilities?.supportsStreaming (default false)', () => {
+		const noCaps = buildAgentCard(baseInfo, baseConfig)
+		expect(noCaps.capabilities.streaming).toBe(false)
+
+		const withStreaming = buildAgentCard(
+			{
+				...baseInfo,
+				capabilities: {
+					supportsTools: true,
+					supportsStreaming: true,
+					supportsConcurrency: false,
+					supportsSubAgents: false,
+				},
+			},
+			baseConfig,
+		)
+		expect(withStreaming.capabilities.streaming).toBe(true)
+	})
+
+	it('pushNotifications + extendedAgentCard are always false', () => {
+		const card = buildAgentCard(baseInfo, baseConfig)
+		expect(card.capabilities.pushNotifications).toBe(false)
+		expect(card.capabilities.extendedAgentCard).toBe(false)
+	})
+
+	it('each tool becomes a skill with id = tool-<name> + tags = [tool]', () => {
+		const card = buildAgentCard(baseInfo, baseConfig)
+		const toolSkills = card.skills.filter((s) => s.tags?.includes('tool'))
+		expect(toolSkills.map((s) => s.id)).toEqual(['tool-read_file', 'tool-write_file'])
+		expect(toolSkills.map((s) => s.name)).toEqual(['read_file', 'write_file'])
+	})
+
+	it('procedural skills come after tool skills with tags = [procedure]', () => {
+		const skills: Skill[] = [
+			{
+				metadata: { name: 'commit', description: 'Drafts commits' },
+				dirPath: '/skills/commit',
+			},
+		]
+		const card = buildAgentCard(baseInfo, baseConfig, skills)
+		expect(card.skills).toHaveLength(3)
+		const last = card.skills[2]
+		expect(last?.id).toBe('commit')
+		expect(last?.name).toBe('commit')
+		expect(last?.tags).toEqual(['procedure'])
+	})
+
+	it('supportedInterfaces[0].url = <baseUrl>/a2a/<id>', () => {
+		const card = buildAgentCard(baseInfo, baseConfig)
+		expect(card.supportedInterfaces[0]?.url).toBe('https://example.com/a2a/coder')
+		expect(card.supportedInterfaces[0]?.transport).toBe('jsonrpc')
+	})
+
+	it('carries bearer security scheme + requirement by default', () => {
+		const card = buildAgentCard(baseInfo, baseConfig)
+		expect(card.securitySchemes?.bearer).toMatchObject({ type: 'http', scheme: 'bearer' })
+		expect(card.securityRequirements).toEqual([{ bearer: [] }])
+	})
+
+	it('default input / output modes are text-only', () => {
+		const card = buildAgentCard(baseInfo, baseConfig)
+		expect(card.defaultInputModes).toEqual(['text'])
+		expect(card.defaultOutputModes).toEqual(['text'])
+	})
+})

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))
+	})
+})