@namzu/sdk 0.4.2 → 0.4.3

package/src/bridge/mcp/connector/adapter.test.ts

@@ -0,0 +1,230 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 2):
+ *
+ *   - `MCPConnectorBridge` wraps a `ConnectorManager` and exposes
+ *     connector methods as MCP tools with a name pattern
+ *     `<prefix>_<connectorId>_<methodName>`; prefix defaults to 'namzu'.
+ *   - `listTools()` with no instanceId iterates
+ *     `manager.listConnectedInstances()`; `listTools(instanceId)` uses
+ *     `manager.getInstance(instanceId)` and filters Boolean (missing
+ *     instance → empty output).
+ *   - `listTools()` rebuilds `mappings` from scratch on each call.
+ *   - Schema conversion via `zodToJsonSchema` is best-effort; on
+ *     conversion failure the schema falls back to `{type: 'object'}`.
+ *   - `getMappings()` returns a COPY (mutation of the returned array
+ *     does not affect internal state).
+ *   - `callTool(name, args)`:
+ *     - Returns `{content: [text], isError: true}` for unknown tools.
+ *     - On manager success, returns `{content: [text], isError: false}`
+ *       with the output stringified if non-string.
+ *     - On manager failure, returns `{content: [text with error],
+ *       isError: true}`; falls back to 'Unknown error' when the
+ *       manager error is undefined.
+ *   - Method descriptions include the connector DEFINITION name
+ *     bracketed (not the instance name): `[<def.name>] <method.description>`.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+
+import type { ConnectorManager } from '../../../manager/connector/lifecycle.js'
+import type { ConnectorRegistry } from '../../../registry/connector/definitions.js'
+import type {
+	ConnectorDefinition,
+	ConnectorExecuteResult,
+	ConnectorInstance,
+} from '../../../types/connector/index.js'
+import type { ConnectorId, ConnectorInstanceId } from '../../../types/ids/index.js'
+
+import { MCPConnectorBridge } from './adapter.js'
+
+const CID = 'conn_http' as ConnectorId
+const IID = 'ci_abc' as ConnectorInstanceId
+
+function makeDefinition(overrides: Partial<ConnectorDefinition> = {}): ConnectorDefinition {
+	return {
+		id: CID,
+		name: 'HTTP',
+		description: 'HTTP connector',
+		connectionType: 'http',
+		configSchema: z.object({}),
+		methods: [
+			{
+				name: 'request',
+				description: 'make http request',
+				inputSchema: z.object({ url: z.string() }),
+			},
+		],
+		...overrides,
+	}
+}
+
+function makeInstance(): ConnectorInstance {
+	return {
+		id: IID,
+		connectorId: CID,
+		config: { connectorId: CID, name: 'svc' },
+		status: 'connected',
+		createdAt: Date.now(),
+	}
+}
+
+function makeManager(overrides: Partial<ConnectorManager> = {}): ConnectorManager {
+	const def = makeDefinition()
+	const registry = {
+		get: vi.fn(() => def),
+	} as unknown as ConnectorRegistry
+	const instance = makeInstance()
+	return {
+		getInstance: vi.fn(() => instance),
+		getRegistry: vi.fn(() => registry),
+		listConnectedInstances: vi.fn(() => [instance]),
+		execute: vi.fn<() => Promise<ConnectorExecuteResult>>(),
+		...overrides,
+	} as unknown as ConnectorManager
+}
+
+describe('MCPConnectorBridge.listTools', () => {
+	it('builds one MCP tool per method per connected instance with default prefix namzu', () => {
+		const bridge = new MCPConnectorBridge({ manager: makeManager() })
+		const tools = bridge.listTools()
+		expect(tools).toHaveLength(1)
+		expect(tools[0]?.name).toBe(`namzu_${CID}_request`)
+		expect(tools[0]?.description).toBe('[HTTP] make http request')
+	})
+
+	it('honors a custom prefix', () => {
+		const bridge = new MCPConnectorBridge({ manager: makeManager(), prefix: 'acme' })
+		expect(bridge.listTools()[0]?.name).toBe(`acme_${CID}_request`)
+	})
+
+	it('single-instance lookup via listTools(instanceId) uses getInstance; missing instance → empty', () => {
+		const manager = makeManager({
+			getInstance: vi.fn(() => undefined),
+		} as unknown as Partial<ConnectorManager>)
+		const bridge = new MCPConnectorBridge({ manager })
+		expect(bridge.listTools(IID)).toEqual([])
+	})
+
+	it('mappings are rebuilt on every listTools() call (not appended)', () => {
+		const bridge = new MCPConnectorBridge({ manager: makeManager() })
+		bridge.listTools()
+		bridge.listTools()
+		expect(bridge.getMappings()).toHaveLength(1)
+	})
+
+	it('skips instances whose connectorId is missing in the registry', () => {
+		const manager = makeManager({
+			getRegistry: vi.fn(() => ({ get: vi.fn(() => undefined) }) as unknown as ConnectorRegistry),
+		} as unknown as Partial<ConnectorManager>)
+		const bridge = new MCPConnectorBridge({ manager })
+		expect(bridge.listTools()).toEqual([])
+	})
+
+	it('getMappings returns a copy — external mutation does not leak', () => {
+		const bridge = new MCPConnectorBridge({ manager: makeManager() })
+		bridge.listTools()
+		const copy = bridge.getMappings()
+		copy.length = 0
+		expect(bridge.getMappings()).toHaveLength(1)
+	})
+
+	it('schema conversion falls back to {type: object} when zodToJsonSchema throws', () => {
+		const bad = makeDefinition({
+			methods: [
+				{
+					name: 'broken',
+					description: 'd',
+					// Not a real zod type — intentionally misleads zodToJsonSchema.
+					inputSchema: null as unknown as z.ZodType,
+				},
+			],
+		})
+		const manager = makeManager({
+			getRegistry: vi.fn(() => ({ get: vi.fn(() => bad) }) as unknown as ConnectorRegistry),
+		} as unknown as Partial<ConnectorManager>)
+		const bridge = new MCPConnectorBridge({ manager })
+		const tools = bridge.listTools()
+		expect(tools[0]?.inputSchema).toEqual({ type: 'object' })
+	})
+})
+
+describe('MCPConnectorBridge.callTool', () => {
+	it('unknown tool → isError true + explanatory text', async () => {
+		const bridge = new MCPConnectorBridge({ manager: makeManager() })
+		const result = await bridge.callTool('nope')
+		expect(result.isError).toBe(true)
+		expect(result.content[0]).toMatchObject({ type: 'text', text: expect.stringContaining('nope') })
+	})
+
+	it('happy path — string output passes through as text', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: true,
+			output: 'hello',
+			durationMs: 5,
+		})
+		const bridge = new MCPConnectorBridge({ manager })
+		bridge.listTools()
+		const result = await bridge.callTool(`namzu_${CID}_request`, { url: 'x' })
+		expect(result.isError).toBe(false)
+		expect(result.content[0]).toEqual({ type: 'text', text: 'hello' })
+	})
+
+	it('non-string success output is JSON-stringified', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: true,
+			output: { status: 200 },
+			durationMs: 1,
+		})
+		const bridge = new MCPConnectorBridge({ manager })
+		bridge.listTools()
+		const result = await bridge.callTool(`namzu_${CID}_request`)
+		expect(result.content[0]).toEqual({
+			type: 'text',
+			text: JSON.stringify({ status: 200 }, null, 2),
+		})
+	})
+
+	it('manager failure → isError true with error text; falls back to "Unknown error" when error is undefined', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: false,
+			output: undefined,
+			durationMs: 1,
+		})
+		const bridge = new MCPConnectorBridge({ manager })
+		bridge.listTools()
+		const result = await bridge.callTool(`namzu_${CID}_request`)
+		expect(result.isError).toBe(true)
+		expect(result.content[0]).toEqual({ type: 'text', text: 'Unknown error' })
+	})
+
+	it('carries the explicit error message when manager provides one', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: false,
+			output: undefined,
+			durationMs: 1,
+			error: 'timeout',
+		})
+		const bridge = new MCPConnectorBridge({ manager })
+		bridge.listTools()
+		const result = await bridge.callTool(`namzu_${CID}_request`)
+		expect(result.content[0]).toEqual({ type: 'text', text: 'timeout' })
+	})
+
+	it('passes empty args through as {} when invoked without a second arg', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: true,
+			output: 'ok',
+			durationMs: 1,
+		})
+		const bridge = new MCPConnectorBridge({ manager })
+		bridge.listTools()
+		await bridge.callTool(`namzu_${CID}_request`)
+		expect(manager.execute).toHaveBeenCalledWith(expect.objectContaining({ input: {} }))
+	})
+})

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

@@ -0,0 +1,422 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 2):
+ *
+ *   - `mapRunToStreamEvent(event, runId)` returns `{wire, data}` or null.
+ *   - Wire names match a fixed mapping (one per RunEvent.type):
+ *     run.started, iteration.started, iteration.completed, message.delta,
+ *     tool.executing, tool.completed, review.requested, review.completed,
+ *     checkpoint.created, run.paused, run.resuming, token.usage,
+ *     activity.created, activity.updated, plan.ready, plan.approved,
+ *     plan.rejected, plan.step_updated, agent.pending, agent.completed,
+ *     agent.failed, agent.canceled, task.created, task.updated,
+ *     plugin.hook_executing, plugin.hook_completed, sandbox.created,
+ *     sandbox.exec, sandbox.destroyed.
+ *   - `run_completed` and `run_failed` produce null (final state is
+ *     delivered by the task.* path, not the SSE delta).
+ *   - Sub-session lifecycle events (spawned / messaged / idled) produce
+ *     null — the SSE wire surface does not carry them today.
+ *   - `data.run_id` is always set from the second arg.
+ *   - `llm_response` data: `content` falls back to null when empty;
+ *     `has_tool_calls` is a boolean.
+ *   - If the event carries `sourceAgentId` or `parentTaskId` fields,
+ *     they are mirrored onto `data.source_agent_id` / `data.parent_task_id`
+ *     (snake-cased).
+ *   - `mapSessionToStreamEvent` is a deprecated alias.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type {
+	ActivityId,
+	CheckpointId,
+	PlanId,
+	PluginId,
+	RunId,
+	SandboxId,
+	TaskId,
+} from '../../types/ids/index.js'
+import type { RunEvent } from '../../types/run/events.js'
+
+import { mapRunToStreamEvent, mapSessionToStreamEvent } from './mapper.js'
+
+const RID = 'run_1' as RunId
+
+describe('mapRunToStreamEvent — mapped variants', () => {
+	it('run_started → run.started', () => {
+		const r = mapRunToStreamEvent(
+			{ type: 'run_started', runId: RID, systemPrompt: 'be terse' },
+			RID,
+		)
+		expect(r?.wire).toBe('run.started')
+		expect(r?.data).toMatchObject({ run_id: RID, system_prompt: 'be terse' })
+	})
+
+	it('run_started with no systemPrompt → system_prompt: null', () => {
+		const r = mapRunToStreamEvent({ type: 'run_started', runId: RID }, RID)
+		expect(r?.data).toMatchObject({ system_prompt: null })
+	})
+
+	it('iteration_started / iteration_completed carry iteration number', () => {
+		const a = mapRunToStreamEvent({ type: 'iteration_started', runId: RID, iteration: 2 }, RID)
+		expect(a).toEqual({ wire: 'iteration.started', data: { run_id: RID, iteration: 2 } })
+
+		const b = mapRunToStreamEvent(
+			{ type: 'iteration_completed', runId: RID, iteration: 2, hasToolCalls: false },
+			RID,
+		)
+		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', () => {
+		const exec = mapRunToStreamEvent(
+			{ type: 'tool_executing', runId: RID, toolName: 'read_file', input: { path: '/a' } },
+			RID,
+		)
+		expect(exec?.wire).toBe('tool.executing')
+		expect(exec?.data).toMatchObject({ tool_name: 'read_file', input: { path: '/a' } })
+
+		const done = mapRunToStreamEvent(
+			{ type: 'tool_completed', runId: RID, toolName: 'read_file', result: 'ok' },
+			RID,
+		)
+		expect(done?.wire).toBe('tool.completed')
+		expect(done?.data).toMatchObject({ tool_name: 'read_file', result: 'ok' })
+	})
+
+	it('tool_review_requested / tool_review_completed carry review fields', () => {
+		const a = mapRunToStreamEvent(
+			{
+				type: 'tool_review_requested',
+				runId: RID,
+				iteration: 1,
+				toolCalls: [{ id: 'tc1', name: 'write_file', input: {}, isDestructive: true }],
+			},
+			RID,
+		)
+		expect(a?.wire).toBe('review.requested')
+		expect(a?.data.iteration).toBe(1)
+
+		const b = mapRunToStreamEvent(
+			{ type: 'tool_review_completed', runId: RID, decision: 'modified' },
+			RID,
+		)
+		expect(b).toEqual({ wire: 'review.completed', data: { run_id: RID, decision: 'modified' } })
+	})
+
+	it('checkpoint_created → checkpoint.created', () => {
+		const r = mapRunToStreamEvent(
+			{
+				type: 'checkpoint_created',
+				runId: RID,
+				checkpointId: 'ckpt_1' as CheckpointId,
+				iteration: 1,
+			},
+			RID,
+		)
+		expect(r?.wire).toBe('checkpoint.created')
+		expect(r?.data).toMatchObject({ checkpoint_id: 'ckpt_1', iteration: 1 })
+	})
+
+	it('run_paused / run_resuming carry checkpoint fields', () => {
+		const p = mapRunToStreamEvent(
+			{
+				type: 'run_paused',
+				runId: RID,
+				checkpointId: 'ckpt_2' as CheckpointId,
+				reason: 'input required',
+			},
+			RID,
+		)
+		expect(p?.wire).toBe('run.paused')
+		expect(p?.data).toMatchObject({ checkpoint_id: 'ckpt_2', reason: 'input required' })
+
+		const r = mapRunToStreamEvent(
+			{ type: 'run_resuming', runId: RID, fromCheckpointId: 'ckpt_2' as CheckpointId },
+			RID,
+		)
+		expect(r).toEqual({
+			wire: 'run.resuming',
+			data: { run_id: RID, from_checkpoint_id: 'ckpt_2' },
+		})
+	})
+
+	it('plan_* events carry plan_id', () => {
+		const ready = mapRunToStreamEvent(
+			{
+				type: 'plan_ready',
+				runId: RID,
+				planId: 'plan_1' as PlanId,
+				title: 't',
+				summary: 's',
+				steps: [],
+			},
+			RID,
+		)
+		expect(ready?.wire).toBe('plan.ready')
+
+		expect(
+			mapRunToStreamEvent({ type: 'plan_approved', runId: RID, planId: 'plan_1' as PlanId }, RID)
+				?.wire,
+		).toBe('plan.approved')
+
+		expect(
+			mapRunToStreamEvent(
+				{ type: 'plan_rejected', runId: RID, planId: 'plan_1' as PlanId, reason: 'nope' },
+				RID,
+			)?.wire,
+		).toBe('plan.rejected')
+
+		expect(
+			mapRunToStreamEvent(
+				{
+					type: 'plan_step_updated',
+					runId: RID,
+					planId: 'plan_1' as PlanId,
+					stepId: 's1',
+					status: 'completed',
+				},
+				RID,
+			)?.wire,
+		).toBe('plan.step_updated')
+	})
+
+	it('agent_* events carry task_id', () => {
+		const pending = mapRunToStreamEvent(
+			{
+				type: 'agent_pending',
+				runId: RID,
+				taskId: 'task_1' as TaskId,
+				parentAgentId: 'a',
+				childAgentId: 'b',
+				depth: 1,
+			},
+			RID,
+		)
+		expect(pending?.wire).toBe('agent.pending')
+		expect(pending?.data).toMatchObject({ task_id: 'task_1', depth: 1 })
+
+		expect(
+			mapRunToStreamEvent(
+				{
+					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,
+						},
+					},
+				},
+				RID,
+			)?.wire,
+		).toBe('agent.completed')
+
+		expect(
+			mapRunToStreamEvent(
+				{ type: 'agent_failed', runId: RID, taskId: 'task_1' as TaskId, error: 'e' },
+				RID,
+			)?.wire,
+		).toBe('agent.failed')
+
+		expect(
+			mapRunToStreamEvent({ type: 'agent_canceled', runId: RID, taskId: 'task_1' as TaskId }, RID)
+				?.wire,
+		).toBe('agent.canceled')
+	})
+
+	it('task_created / task_updated map cleanly', () => {
+		const a = mapRunToStreamEvent(
+			{
+				type: 'task_created',
+				runId: RID,
+				taskId: 'task_1' as TaskId,
+				subject: 's',
+				status: 'pending',
+			},
+			RID,
+		)
+		expect(a?.wire).toBe('task.created')
+
+		const b = mapRunToStreamEvent(
+			{
+				type: 'task_updated',
+				runId: RID,
+				taskId: 'task_1' as TaskId,
+				subject: 's',
+				status: 'completed',
+			},
+			RID,
+		)
+		expect(b?.wire).toBe('task.updated')
+		expect(b?.data.owner).toBe(null) // undefined owner → null
+	})
+
+	it('plugin_hook_* + sandbox_* + activity_* events map cleanly', () => {
+		expect(
+			mapRunToStreamEvent(
+				{
+					type: 'plugin_hook_executing',
+					runId: RID,
+					pluginId: 'plugin_x' as PluginId,
+					hookEvent: 'pre_tool_use',
+				},
+				RID,
+			)?.wire,
+		).toBe('plugin.hook_executing')
+
+		expect(
+			mapRunToStreamEvent(
+				{
+					type: 'plugin_hook_completed',
+					runId: RID,
+					pluginId: 'plugin_x' as PluginId,
+					hookEvent: 'pre_tool_use',
+					result: { action: 'continue' },
+				},
+				RID,
+			)?.wire,
+		).toBe('plugin.hook_completed')
+
+		expect(
+			mapRunToStreamEvent(
+				{
+					type: 'sandbox_created',
+					runId: RID,
+					sandboxId: 'sbx_1' as SandboxId,
+					environment: 'basic',
+				},
+				RID,
+			)?.wire,
+		).toBe('sandbox.created')
+
+		expect(
+			mapRunToStreamEvent(
+				{
+					type: 'sandbox_exec',
+					runId: RID,
+					sandboxId: 'sbx_1' as SandboxId,
+					command: 'ls',
+					exitCode: 0,
+					durationMs: 10,
+				},
+				RID,
+			)?.wire,
+		).toBe('sandbox.exec')
+
+		expect(
+			mapRunToStreamEvent(
+				{ type: 'sandbox_destroyed', runId: RID, sandboxId: 'sbx_1' as SandboxId },
+				RID,
+			)?.wire,
+		).toBe('sandbox.destroyed')
+
+		expect(
+			mapRunToStreamEvent(
+				{
+					type: 'activity_created',
+					runId: RID,
+					activityId: 'act_1' as ActivityId,
+					activityType: 'tool_call',
+					description: 'd',
+				},
+				RID,
+			)?.wire,
+		).toBe('activity.created')
+
+		expect(
+			mapRunToStreamEvent(
+				{
+					type: 'activity_updated',
+					runId: RID,
+					activityId: 'act_1' as ActivityId,
+					status: 'completed',
+				},
+				RID,
+			)?.wire,
+		).toBe('activity.updated')
+	})
+
+	it('token_usage_updated → token.usage with usage + cost passed through', () => {
+		const usage = {
+			promptTokens: 10,
+			completionTokens: 20,
+			totalTokens: 30,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		}
+		const cost = {
+			inputCostPer1M: 1,
+			outputCostPer1M: 2,
+			totalCost: 0.01,
+			cacheDiscount: 0,
+		}
+		const r = mapRunToStreamEvent({ type: 'token_usage_updated', runId: RID, usage, cost }, RID)
+		expect(r?.wire).toBe('token.usage')
+		expect(r?.data).toMatchObject({ usage, cost })
+	})
+
+	it('source_agent_id + parent_task_id are mirrored when present on the event', () => {
+		const event = {
+			type: 'run_started',
+			runId: RID,
+			sourceAgentId: 'sub_agent_1',
+			parentTaskId: 'task_42',
+		} as unknown as RunEvent
+		const r = mapRunToStreamEvent(event, RID)
+		expect(r?.data).toMatchObject({ source_agent_id: 'sub_agent_1', parent_task_id: 'task_42' })
+	})
+})
+
+describe('mapRunToStreamEvent — explicit null set', () => {
+	it.each([
+		[{ type: 'run_completed' as const, runId: RID, result: 'ok' }],
+		[{ type: 'run_failed' as const, runId: RID, error: 'boom' }],
+	])('%o returns null', (event) => {
+		expect(mapRunToStreamEvent(event, RID)).toBeNull()
+	})
+})
+
+describe('mapSessionToStreamEvent (deprecated alias)', () => {
+	it('is the same function reference as mapRunToStreamEvent', () => {
+		// Identity check is deterministic. toEqual on paired calls
+		// would work here (SSE mapper doesn't touch the clock), but
+		// we mirror the a2a mapper test pattern for consistency —
+		// the deprecation shim is literal assignment, so identity is
+		// the strictest possible assertion.
+		expect(mapSessionToStreamEvent).toBe(mapRunToStreamEvent)
+	})
+})