@namzu/sdk 0.4.2 → 0.4.4

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

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

@@ -0,0 +1,183 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 2):
+ *
+ *   - `createConnectorExecuteTool(config)` returns a `defineTool`-wrapped
+ *     tool named `connector_execute` that:
+ *     - Returns `{success: false, error: '... not found'}` when instance
+ *       is missing.
+ *     - Returns `{success: false, error: '... not connected'}` when the
+ *       instance exists but `status !== 'connected'`.
+ *     - Returns `{success: false, error: ...}` when `manager.execute`
+ *       itself reports failure; falls back to 'Connector execution
+ *       failed' when the execute error is undefined.
+ *     - On success, stringifies non-string outputs to JSON; strings pass
+ *       through as-is.
+ *     - Attaches `data: { durationMs, metadata }` on success.
+ *   - `createConnectorListTool(config)` returns a tool named
+ *     `connector_list` that:
+ *     - Emits "No connector instances configured." when none exist.
+ *     - Lists each instance with `- <id> (<connectorId>): <name> [<status>]`.
+ *   - `createConnectorTools(config)` returns the pair of tools above.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import type { ConnectorManager } from '../../../manager/connector/lifecycle.js'
+import type { 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 {
+	createConnectorExecuteTool,
+	createConnectorListTool,
+	createConnectorTools,
+} from './definitions.js'
+
+const CID = 'conn_http' as ConnectorId
+const IID = 'ci_abc123' as ConnectorInstanceId
+
+function makeInstance(overrides: Partial<ConnectorInstance> = {}): ConnectorInstance {
+	return {
+		id: IID,
+		connectorId: CID,
+		config: { connectorId: CID, name: 'default' },
+		status: 'connected',
+		createdAt: Date.now(),
+		...overrides,
+	}
+}
+
+function makeManager(overrides: Partial<ConnectorManager> = {}): ConnectorManager {
+	return {
+		getInstance: vi.fn(() => makeInstance()),
+		listInstances: vi.fn(() => [makeInstance()]),
+		execute: vi.fn<() => Promise<ConnectorExecuteResult>>(),
+		...overrides,
+	} as unknown as ConnectorManager
+}
+
+const ctx: ToolContext = {} as ToolContext
+
+describe('createConnectorExecuteTool', () => {
+	it('is named connector_execute', () => {
+		const tool = createConnectorExecuteTool({ manager: makeManager() })
+		expect(tool.name).toBe('connector_execute')
+	})
+
+	it('returns error when instance is missing', async () => {
+		const manager = makeManager({
+			getInstance: vi.fn(() => undefined),
+		} as unknown as Partial<ConnectorManager>)
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/not found/)
+	})
+
+	it('returns error when instance status is not "connected"', async () => {
+		const manager = makeManager({
+			getInstance: vi.fn(() => makeInstance({ status: 'disconnected' })),
+		} as unknown as Partial<ConnectorManager>)
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/not connected/)
+		expect(result.error).toMatch(/disconnected/)
+	})
+
+	it('wraps manager.execute failure; falls back to "Connector execution failed" on undefined error', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: false,
+			output: undefined,
+			durationMs: 1,
+		})
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.success).toBe(false)
+		expect(result.error).toBe('Connector execution failed')
+	})
+
+	it('carries the explicit error message when provided by manager.execute', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: false,
+			output: undefined,
+			durationMs: 1,
+			error: 'timeout',
+		})
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.error).toBe('timeout')
+	})
+
+	it('passes through string outputs as-is', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: true,
+			output: 'hi there',
+			durationMs: 10,
+		})
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.success).toBe(true)
+		expect(result.output).toBe('hi there')
+	})
+
+	it('stringifies non-string outputs + attaches durationMs + metadata to data', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: true,
+			output: { answer: 42 },
+			durationMs: 15,
+			metadata: { region: 'us-east-1' },
+		})
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.output).toBe(JSON.stringify({ answer: 42 }, null, 2))
+		expect(result.data).toEqual({ durationMs: 15, metadata: { region: 'us-east-1' } })
+	})
+})
+
+describe('createConnectorListTool', () => {
+	it('is named connector_list + read-only', () => {
+		const tool = createConnectorListTool({ manager: makeManager() })
+		expect(tool.name).toBe('connector_list')
+		expect(tool.isReadOnly?.({})).toBe(true)
+	})
+
+	it('emits "No connector instances configured." when none', async () => {
+		const manager = makeManager({
+			listInstances: vi.fn(() => []),
+		} as unknown as Partial<ConnectorManager>)
+		const tool = createConnectorListTool({ manager })
+		const result = await tool.execute({}, ctx)
+		expect(result.success).toBe(true)
+		expect(result.output).toBe('No connector instances configured.')
+	})
+
+	it('lists every instance with id / connectorId / name / status', async () => {
+		const manager = makeManager({
+			listInstances: vi.fn(() => [
+				makeInstance({ id: IID }),
+				makeInstance({
+					id: 'ci_def' as ConnectorInstanceId,
+					status: 'disconnected',
+				}),
+			]),
+		} as unknown as Partial<ConnectorManager>)
+		const tool = createConnectorListTool({ manager })
+		const result = await tool.execute({}, ctx)
+		expect(result.success).toBe(true)
+		expect(result.output).toContain(`- ${IID} (${CID}): default [connected]`)
+		expect(result.output).toContain(`- ci_def (${CID}): default [disconnected]`)
+		expect(result.data).toBeDefined()
+	})
+})
+
+describe('createConnectorTools', () => {
+	it('returns both execute + list tools', () => {
+		const tools = createConnectorTools({ manager: makeManager() })
+		expect(tools.map((t) => t.name)).toEqual(['connector_execute', 'connector_list'])
+	})
+})

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

@@ -0,0 +1,159 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 2):
+ *
+ *   - `new ConnectorToolRouter({ manager })` defaults strategy to
+ *     `'per-method'`.
+ *   - `getTools()` with strategy `'router'`:
+ *     - Returns `[]` when there are no connected instances.
+ *     - Returns a single `connector_execute` routing tool otherwise.
+ *   - `getTools()` with strategy `'per-method'`:
+ *     - Emits one tool per method per connected instance.
+ *     - Catches errors per-instance (logs + skips) — a broken instance
+ *       does not poison the entire tool list.
+ *   - `registerTools(registry)` delegates to `registry.register` for
+ *     every tool and returns the list of names.
+ *   - `unregisterTools(registry, names)` calls `registry.unregister`
+ *     for each name.
+ *   - `refreshTools(registry, previous)` is unregister-then-register in
+ *     one call; returns the new names list.
+ */
+
+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, ConnectorInstance } from '../../../types/connector/index.js'
+import type { ConnectorId, ConnectorInstanceId } from '../../../types/ids/index.js'
+import type { ToolRegistryContract } from '../../../types/tool/index.js'
+
+import { ConnectorToolRouter } from './router.js'
+
+const CID = 'conn_http' as ConnectorId
+const IID1 = 'ci_a' as ConnectorInstanceId
+const IID2 = 'ci_b' as ConnectorInstanceId
+
+function makeDefinition(): ConnectorDefinition {
+	return {
+		id: CID,
+		name: 'HTTP',
+		description: 'x',
+		connectionType: 'http',
+		configSchema: z.object({}),
+		methods: [
+			{ name: 'request', description: 'd', inputSchema: z.object({}) },
+			{ name: 'send', description: 'd', inputSchema: z.object({}) },
+		],
+	}
+}
+
+function makeInstance(id: ConnectorInstanceId): ConnectorInstance {
+	return {
+		id,
+		connectorId: CID,
+		config: { connectorId: CID, name: 'x' },
+		status: 'connected',
+		createdAt: Date.now(),
+	}
+}
+
+function makeManager(instances: ConnectorInstance[]): ConnectorManager {
+	const def = makeDefinition()
+	const registry = {
+		getOrThrow: vi.fn(() => def),
+		get: vi.fn(() => def),
+	} as unknown as ConnectorRegistry
+	return {
+		getInstance: vi.fn((id) => instances.find((i) => i.id === id)),
+		getRegistry: vi.fn(() => registry),
+		listConnectedInstances: vi.fn(() => instances),
+		listInstances: vi.fn(() => instances),
+		execute: vi.fn(),
+	} as unknown as ConnectorManager
+}
+
+function makeToolRegistry(): ToolRegistryContract {
+	return {
+		register: vi.fn(),
+		unregister: vi.fn(() => true),
+		clear: vi.fn(),
+	} as unknown as ToolRegistryContract
+}
+
+describe('ConnectorToolRouter', () => {
+	it('defaults strategy to per-method', () => {
+		const router = new ConnectorToolRouter({ manager: makeManager([makeInstance(IID1)]) })
+		const tools = router.getTools()
+		expect(tools.map((t) => t.name)).toEqual([`${CID}_request`, `${CID}_send`])
+	})
+
+	it('router strategy with connected instances emits one connector_execute tool', () => {
+		const router = new ConnectorToolRouter({
+			manager: makeManager([makeInstance(IID1)]),
+			strategy: 'router',
+		})
+		const tools = router.getTools()
+		expect(tools).toHaveLength(1)
+		expect(tools[0]?.name).toBe('connector_execute')
+	})
+
+	it('router strategy with no connected instances returns empty array', () => {
+		const router = new ConnectorToolRouter({
+			manager: makeManager([]),
+			strategy: 'router',
+		})
+		expect(router.getTools()).toEqual([])
+	})
+
+	it('per-method strategy with multiple instances emits methods per-instance', () => {
+		const router = new ConnectorToolRouter({
+			manager: makeManager([makeInstance(IID1), makeInstance(IID2)]),
+		})
+		const tools = router.getTools()
+		expect(tools).toHaveLength(4) // 2 methods * 2 instances
+	})
+
+	it('per-method strategy skips a broken instance + continues with others', () => {
+		const good = makeInstance(IID1)
+		const bad = makeInstance(IID2)
+		const manager = makeManager([good, bad])
+		// make instance IID2 "not found" by overriding getInstance
+		vi.mocked(manager.getInstance).mockImplementation((id) => (id === IID1 ? good : undefined))
+		const router = new ConnectorToolRouter({ manager })
+		const tools = router.getTools()
+		// 2 from IID1; IID2 threw + got caught
+		expect(tools.map((t) => t.name)).toEqual([`${CID}_request`, `${CID}_send`])
+	})
+})
+
+describe('ConnectorToolRouter.registerTools', () => {
+	it('registers every tool and returns the names', () => {
+		const router = new ConnectorToolRouter({ manager: makeManager([makeInstance(IID1)]) })
+		const reg = makeToolRegistry()
+		const names = router.registerTools(reg)
+		expect(names).toEqual([`${CID}_request`, `${CID}_send`])
+		expect(reg.register).toHaveBeenCalledTimes(2)
+	})
+})
+
+describe('ConnectorToolRouter.unregisterTools', () => {
+	it('unregisters each named tool', () => {
+		const router = new ConnectorToolRouter({ manager: makeManager([]) })
+		const reg = makeToolRegistry()
+		router.unregisterTools(reg, ['a', 'b'])
+		expect(reg.unregister).toHaveBeenCalledWith('a')
+		expect(reg.unregister).toHaveBeenCalledWith('b')
+		expect(reg.unregister).toHaveBeenCalledTimes(2)
+	})
+})
+
+describe('ConnectorToolRouter.refreshTools', () => {
+	it('unregisters previous names then registers new ones', () => {
+		const router = new ConnectorToolRouter({ manager: makeManager([makeInstance(IID1)]) })
+		const reg = makeToolRegistry()
+		const newNames = router.refreshTools(reg, [`${CID}_old_method`])
+		expect(reg.unregister).toHaveBeenCalledWith(`${CID}_old_method`)
+		expect(newNames).toEqual([`${CID}_request`, `${CID}_send`])
+		expect(reg.register).toHaveBeenCalledTimes(2)
+	})
+})