@namzu/sdk 0.4.1 → 0.4.3

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

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

@@ -0,0 +1,224 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 2):
+ *
+ *   - `connectorMethodToTool(connectorId, instanceId, method, manager)`
+ *     produces a `ToolDefinition` with:
+ *     - `name: '<connectorId>_<methodName>'`
+ *     - `description: '[<connectorId>] <method.description>'`
+ *     - `category: 'network'`, `permissions: ['network_access']`,
+ *       all read/destructive/concurrency flags set (readOnly:false,
+ *       destructive:false, concurrencySafe:true) — current behavior,
+ *       regardless of what the underlying method actually does.
+ *     - `execute(input, ctx)` calls `manager.execute` and wraps the
+ *       result; output is JSON-stringified on success, empty string
+ *       on failure; `_context` is ignored (§2.7).
+ *   - `connectorInstanceToTools(instanceId, manager)` throws when the
+ *     instance is missing; returns one tool per method otherwise.
+ *   - `allConnectorTools(manager)` enumerates
+ *     `manager.listConnectedInstances()` and flattens per-instance tool
+ *     lists.
+ *   - `createConnectorRouterTool(manager)` returns a single
+ *     `connector_execute` tool that routes by
+ *     `{connectorId, instanceId, method, input}`; returns
+ *     `{success: false}` results (not thrown errors) for missing
+ *     instance or connectorId mismatch. The description enumerates
+ *     currently connected instances.
+ */
+
+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 type { ToolContext } from '../../../types/tool/index.js'
+
+import {
+	allConnectorTools,
+	connectorInstanceToTools,
+	connectorMethodToTool,
+	createConnectorRouterTool,
+} from './adapter.js'
+
+const CID = 'conn_http' as ConnectorId
+const IID1 = 'ci_abc123' as ConnectorInstanceId
+const IID2 = 'ci_def456' as ConnectorInstanceId
+
+function makeMethod(name: string, description = `${name} description`) {
+	return { name, description, inputSchema: z.object({}) }
+}
+
+function makeManager(overrides: Partial<ConnectorManager> = {}): ConnectorManager {
+	const execute = vi.fn<() => Promise<ConnectorExecuteResult>>()
+	const def: ConnectorDefinition = {
+		id: CID,
+		name: 'HTTP',
+		description: 'HTTP connector',
+		connectionType: 'http',
+		configSchema: z.object({}),
+		methods: [makeMethod('request'), makeMethod('send')],
+	}
+	const registry = {
+		getOrThrow: vi.fn(() => def),
+		get: vi.fn(() => def),
+	} as unknown as ConnectorRegistry
+	const instance: ConnectorInstance = {
+		id: IID1,
+		connectorId: CID,
+		config: { connectorId: CID, name: 'default' },
+		status: 'connected',
+		createdAt: Date.now(),
+	}
+	return {
+		getInstance: vi.fn(() => instance),
+		getRegistry: vi.fn(() => registry),
+		listConnectedInstances: vi.fn(() => [instance]),
+		listInstances: vi.fn(() => [instance]),
+		execute,
+		...overrides,
+	} as unknown as ConnectorManager
+}
+
+const ctx: ToolContext = {} as ToolContext
+
+describe('connectorMethodToTool', () => {
+	it('produces the expected name + description + flags', () => {
+		const manager = makeManager()
+		const tool = connectorMethodToTool(CID, IID1, makeMethod('request'), manager)
+		expect(tool.name).toBe(`${CID}_request`)
+		expect(tool.description).toBe(`[${CID}] request description`)
+		expect(tool.category).toBe('network')
+		expect(tool.permissions).toEqual(['network_access'])
+		expect(tool.isReadOnly?.({})).toBe(false)
+		expect(tool.isDestructive?.({})).toBe(false)
+		expect(tool.isConcurrencySafe?.({})).toBe(true)
+	})
+
+	it('execute wraps manager.execute success into a ToolResult with stringified output', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: true,
+			output: { answer: 42 },
+			durationMs: 10,
+		})
+		const tool = connectorMethodToTool(CID, IID1, makeMethod('request'), manager)
+		const result = await tool.execute({}, ctx)
+		expect(result.success).toBe(true)
+		expect(result.output).toBe(JSON.stringify({ answer: 42 }, null, 2))
+		expect(result.data).toEqual({ answer: 42 })
+	})
+
+	it('execute carries through failure, leaves output as empty string', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: false,
+			output: undefined,
+			durationMs: 5,
+			error: 'boom',
+		})
+		const tool = connectorMethodToTool(CID, IID1, makeMethod('request'), manager)
+		const result = await tool.execute({}, ctx)
+		expect(result.success).toBe(false)
+		expect(result.output).toBe('')
+		expect(result.error).toBe('boom')
+	})
+})
+
+describe('connectorInstanceToTools', () => {
+	it('returns one tool per method on the definition', () => {
+		const manager = makeManager()
+		const tools = connectorInstanceToTools(IID1, manager)
+		expect(tools.map((t) => t.name)).toEqual([`${CID}_request`, `${CID}_send`])
+	})
+
+	it('throws when the instance is not found', () => {
+		const manager = makeManager({
+			getInstance: vi.fn(() => undefined),
+		} as unknown as Partial<ConnectorManager>)
+		expect(() => connectorInstanceToTools(IID2, manager)).toThrow(/not found/)
+	})
+})
+
+describe('allConnectorTools', () => {
+	it('enumerates every connected instance', () => {
+		const manager = makeManager()
+		const tools = allConnectorTools(manager)
+		expect(tools).toHaveLength(2)
+		expect(manager.listConnectedInstances).toHaveBeenCalled()
+	})
+
+	it('returns empty array when no connected instances', () => {
+		const manager = makeManager({
+			listConnectedInstances: vi.fn(() => []),
+		} as unknown as Partial<ConnectorManager>)
+		expect(allConnectorTools(manager)).toEqual([])
+	})
+})
+
+describe('createConnectorRouterTool', () => {
+	it('returns a single connector_execute tool', () => {
+		const tool = createConnectorRouterTool(makeManager())
+		expect(tool.name).toBe('connector_execute')
+		expect(tool.category).toBe('network')
+	})
+
+	it('description enumerates currently connected instances', () => {
+		const tool = createConnectorRouterTool(makeManager())
+		expect(tool.description).toContain(CID)
+		expect(tool.description).toContain(IID1)
+		expect(tool.description).toContain('request')
+	})
+
+	it('description notes "No connectors are currently connected" when empty', () => {
+		const manager = makeManager({
+			listConnectedInstances: vi.fn(() => []),
+		} as unknown as Partial<ConnectorManager>)
+		const tool = createConnectorRouterTool(manager)
+		expect(tool.description).toContain('No connectors are currently connected')
+	})
+
+	it('execute returns {success: false} when instance is missing', async () => {
+		const manager = makeManager({
+			getInstance: vi.fn(() => undefined),
+		} as unknown as Partial<ConnectorManager>)
+		const tool = createConnectorRouterTool(manager)
+		const result = await tool.execute(
+			{ connectorId: CID, instanceId: IID2, method: 'request', input: {} },
+			ctx,
+		)
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/not found/)
+	})
+
+	it('execute returns {success: false} when connectorId mismatches the instance', async () => {
+		const manager = makeManager()
+		const tool = createConnectorRouterTool(manager)
+		const result = await tool.execute(
+			{ connectorId: 'conn_other' as ConnectorId, instanceId: IID1, method: 'request', input: {} },
+			ctx,
+		)
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/belongs to connector/)
+	})
+
+	it('execute delegates to manager.execute on happy path', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: true,
+			output: 'hello',
+			durationMs: 1,
+		})
+		const tool = createConnectorRouterTool(manager)
+		const result = await tool.execute(
+			{ connectorId: CID, instanceId: IID1, method: 'request', input: { k: 'v' } },
+			ctx,
+		)
+		expect(result.success).toBe(true)
+		expect(result.data).toBe('hello')
+	})
+})