@namzu/sdk 0.4.1 → 0.4.3

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

package/src/bridge/a2a/task.ts

@@ -1,5 +1,5 @@
 import { RUN_STATUS_TO_A2A, TERMINAL_STATES } from '../../constants/a2a/index.js'
-import type { Run, RunConfig, WireRunStatus } from '../../contracts/index.js'
+import type { RunConfig, WireRun, WireRunStatus } from '../../contracts/index.js'
 import type {
 	A2AArtifact,
 	A2AMessage,
@@ -19,7 +19,7 @@ export function runStatusToA2AState(status: WireRunStatus): A2ATaskState {
 	return RUN_STATUS_TO_A2A[status]
 }
 
-function buildTaskStatus(run: Run): A2ATaskStatus {
+function buildTaskStatus(run: WireRun): A2ATaskStatus {
 	const state = runStatusToA2AState(run.status)
 	const timestamp = run.completed_at ?? run.started_at ?? run.created_at
 
@@ -32,7 +32,7 @@ function buildTaskStatus(run: Run): A2ATaskStatus {
 	return { state, message, timestamp }
 }
 
-function buildArtifacts(run: Run): A2AArtifact[] | undefined {
+function buildArtifacts(run: WireRun): A2AArtifact[] | undefined {
 	if (!run.result) return undefined
 
 	return [
@@ -54,7 +54,7 @@ function buildArtifacts(run: Run): A2AArtifact[] | undefined {
 	]
 }
 
-export function runToA2ATask(run: Run, messages?: readonly Message[]): A2ATask {
+export function runToA2ATask(run: WireRun, messages?: readonly Message[]): A2ATask {
 	return {
 		id: run.id,
 		contextId: run.project_id ?? undefined,

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