@namzu/sdk 0.1.1

package/src/bridge/sse/mapper.ts

@@ -0,0 +1,261 @@
+import type { StreamEventType } from "../../contracts/index.js";
+import type { RunId } from "../../types/ids/index.js";
+import type { RunEvent } from "../../types/run/events.js";
+
+export interface MappedStreamEvent {
+	wire: StreamEventType;
+	data: Record<string, unknown>;
+}
+
+type EventTransform<K extends RunEvent["type"]> = {
+	wire: StreamEventType;
+	transform: (
+		event: Extract<RunEvent, { type: K }>,
+		runId: RunId,
+	) => Record<string, unknown>;
+} | null;
+
+const MAPPING: {
+	[K in RunEvent["type"]]: EventTransform<K>;
+} = {
+	run_started: {
+		wire: "run.started",
+		transform: (e, runId) => ({
+			run_id: runId,
+			system_prompt: e.systemPrompt ?? null,
+		}),
+	},
+
+	iteration_started: {
+		wire: "iteration.started",
+		transform: (e, runId) => ({ run_id: runId, iteration: e.iteration }),
+	},
+
+	iteration_completed: {
+		wire: "iteration.completed",
+		transform: (e, runId) => ({ run_id: runId, iteration: e.iteration }),
+	},
+
+	llm_response: {
+		wire: "message.delta",
+		transform: (e, runId) => ({
+			run_id: runId,
+			content: e.content ?? null,
+			has_tool_calls: !!e.hasToolCalls,
+		}),
+	},
+
+	tool_executing: {
+		wire: "tool.executing",
+		transform: (e, runId) => ({
+			run_id: runId,
+			tool_name: e.toolName,
+			input: e.input,
+		}),
+	},
+
+	tool_completed: {
+		wire: "tool.completed",
+		transform: (e, runId) => ({
+			run_id: runId,
+			tool_name: e.toolName,
+			result: e.result,
+		}),
+	},
+
+	tool_review_requested: {
+		wire: "review.requested",
+		transform: (e, runId) => ({
+			run_id: runId,
+			tool_calls: e.toolCalls,
+			iteration: e.iteration,
+		}),
+	},
+
+	tool_review_completed: {
+		wire: "review.completed",
+		transform: (e, runId) => ({
+			run_id: runId,
+			decision: e.decision,
+		}),
+	},
+
+	checkpoint_created: {
+		wire: "checkpoint.created",
+		transform: (e, runId) => ({
+			run_id: runId,
+			checkpoint_id: e.checkpointId,
+			iteration: e.iteration,
+		}),
+	},
+
+	run_paused: {
+		wire: "run.paused",
+		transform: (e, runId) => ({
+			run_id: runId,
+			checkpoint_id: e.checkpointId,
+			reason: e.reason,
+		}),
+	},
+
+	run_resuming: {
+		wire: "run.resuming",
+		transform: (e, runId) => ({
+			run_id: runId,
+			from_checkpoint_id: e.fromCheckpointId,
+		}),
+	},
+
+	token_usage_updated: {
+		wire: "token.usage",
+		transform: (e, runId) => ({
+			run_id: runId,
+			usage: e.usage,
+			cost: e.cost,
+		}),
+	},
+
+	activity_created: {
+		wire: "activity.created",
+		transform: (e, runId) => ({
+			run_id: runId,
+			activity_id: e.activityId,
+			activity_type: e.activityType,
+			description: e.description,
+		}),
+	},
+
+	activity_updated: {
+		wire: "activity.updated",
+		transform: (e, runId) => ({
+			run_id: runId,
+			activity_id: e.activityId,
+			status: e.status,
+			output: e.output,
+			error: e.error,
+		}),
+	},
+
+	plan_ready: {
+		wire: "plan.ready",
+		transform: (e, runId) => ({
+			run_id: runId,
+			plan_id: e.planId,
+			title: e.title,
+			steps: e.steps,
+			summary: e.summary,
+		}),
+	},
+
+	plan_approved: {
+		wire: "plan.approved",
+		transform: (e, runId) => ({ run_id: runId, plan_id: e.planId }),
+	},
+
+	plan_rejected: {
+		wire: "plan.rejected",
+		transform: (e, runId) => ({
+			run_id: runId,
+			plan_id: e.planId,
+			reason: e.reason,
+		}),
+	},
+
+	plan_step_updated: {
+		wire: "plan.step_updated",
+		transform: (e, runId) => ({
+			run_id: runId,
+			plan_id: e.planId,
+			step_id: e.stepId,
+			status: e.status,
+		}),
+	},
+
+	run_completed: null,
+	run_failed: null,
+
+	agent_pending: {
+		wire: "agent.pending",
+		transform: (e, runId) => ({
+			run_id: runId,
+			task_id: e.taskId,
+			parent_agent_id: e.parentAgentId,
+			child_agent_id: e.childAgentId,
+			depth: e.depth,
+		}),
+	},
+
+	agent_completed: {
+		wire: "agent.completed",
+		transform: (e, runId) => ({
+			run_id: runId,
+			task_id: e.taskId,
+			result: e.result?.result,
+		}),
+	},
+
+	agent_failed: {
+		wire: "agent.failed",
+		transform: (e, runId) => ({
+			run_id: runId,
+			task_id: e.taskId,
+			error: e.error,
+		}),
+	},
+
+	agent_canceled: {
+		wire: "agent.canceled",
+		transform: (e, runId) => ({
+			run_id: runId,
+			task_id: e.taskId,
+		}),
+	},
+
+	task_created: {
+		wire: "task.created",
+		transform: (e, runId) => ({
+			run_id: runId,
+			task_id: e.taskId,
+			subject: e.subject,
+			status: e.status,
+		}),
+	},
+
+	task_updated: {
+		wire: "task.updated",
+		transform: (e, runId) => ({
+			run_id: runId,
+			task_id: e.taskId,
+			subject: e.subject,
+			status: e.status,
+			owner: e.owner ?? null,
+		}),
+	},
+};
+
+export function mapRunToStreamEvent(
+	event: RunEvent,
+	runId: RunId,
+): MappedStreamEvent | null {
+	const mapping = MAPPING[event.type];
+	if (!mapping) return null;
+
+	const data = (
+		mapping.transform as (
+			event: RunEvent,
+			runId: RunId,
+		) => Record<string, unknown>
+	)(event, runId);
+
+	const annotated = event as Record<string, unknown>;
+	if ("sourceAgentId" in annotated && annotated.sourceAgentId) {
+		data.source_agent_id = annotated.sourceAgentId;
+	}
+	if ("parentTaskId" in annotated && annotated.parentTaskId) {
+		data.parent_task_id = annotated.parentTaskId;
+	}
+
+	return { wire: mapping.wire, data };
+}
+
+export const mapSessionToStreamEvent = mapRunToStreamEvent;

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

@@ -0,0 +1,143 @@
+import { z } from 'zod'
+import type { ToolDefinition, ToolContext, ToolResult } from '../../../types/tool/index.js'
+import type { ConnectorInstanceId } from '../../../types/ids/index.js'
+import type { ConnectorManager } from '../../../manager/connector/lifecycle.js'
+import type { ConnectorMethod } from '../../../types/connector/index.js'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+import { parseConnectorInstanceId } from '../../../utils/id.js'
+
+export function connectorMethodToTool(
+  connectorId: string,
+  instanceId: ConnectorInstanceId,
+  method: ConnectorMethod,
+  manager: ConnectorManager,
+): ToolDefinition {
+  const toolName = `${connectorId}_${method.name}`
+
+  return {
+    name: toolName,
+    description: `[${connectorId}] ${method.description}`,
+    inputSchema: method.inputSchema,
+    category: 'network',
+    permissions: ['network_access'],
+    isReadOnly: () => false,
+    isDestructive: () => false,
+    isConcurrencySafe: () => true,
+
+    async execute(input: unknown, _context: ToolContext): Promise<ToolResult> {
+      const result = await manager.execute({
+        instanceId,
+        method: method.name,
+        input,
+      })
+
+      return {
+        success: result.success,
+        output: result.success
+          ? JSON.stringify(result.output, null, 2)
+          : '',
+        data: result.output,
+        error: result.error,
+      }
+    },
+  }
+}
+
+export function connectorInstanceToTools(
+  instanceId: ConnectorInstanceId,
+  manager: ConnectorManager,
+): ToolDefinition[] {
+  const instance = manager.getInstance(instanceId)
+  if (!instance) {
+    throw new Error(`Connector instance not found: "${instanceId}"`)
+  }
+
+  const definition = manager.getRegistry().getOrThrow(instance.connectorId)
+  return definition.methods.map((method) =>
+    connectorMethodToTool(instance.connectorId, instanceId, method, manager),
+  )
+}
+
+export function allConnectorTools(manager: ConnectorManager): ToolDefinition[] {
+  const tools: ToolDefinition[] = []
+  for (const instance of manager.listConnectedInstances()) {
+    tools.push(...connectorInstanceToTools(instance.id, manager))
+  }
+  return tools
+}
+
+const ConnectorRouterInputSchema = z.object({
+  connectorId: z.string().describe('The connector definition ID (e.g., "http", "webhook")'),
+  instanceId: z.string().describe('The connector instance ID (e.g., "ci_abc123")'),
+  method: z.string().describe('The method to execute on the connector'),
+  input: z.record(z.unknown()).describe('The input data for the method'),
+})
+
+export type ConnectorRouterInput = z.infer<typeof ConnectorRouterInputSchema>
+
+export function createConnectorRouterTool(
+  manager: ConnectorManager,
+): ToolDefinition<ConnectorRouterInput> {
+  return {
+    name: 'connector_execute',
+    description: buildRouterDescription(manager),
+    inputSchema: ConnectorRouterInputSchema,
+    category: 'network',
+    permissions: ['network_access'],
+    isReadOnly: () => false,
+    isDestructive: () => false,
+    isConcurrencySafe: () => true,
+
+    async execute(input: ConnectorRouterInput, _context: ToolContext): Promise<ToolResult> {
+      const instanceId = parseConnectorInstanceId(String(input.instanceId))
+      const instance = manager.getInstance(instanceId)
+      if (!instance) {
+        return {
+          success: false,
+          output: '',
+          error: `Connector instance not found: "${input.instanceId}"`,
+        }
+      }
+
+      if (instance.connectorId !== input.connectorId) {
+        return {
+          success: false,
+          output: '',
+          error: `Instance "${input.instanceId}" belongs to connector "${instance.connectorId}", not "${input.connectorId}"`,
+        }
+      }
+
+      const result = await manager.execute({
+        instanceId,
+        method: input.method,
+        input: input.input,
+      })
+
+      return {
+        success: result.success,
+        output: result.success
+          ? JSON.stringify(result.output, null, 2)
+          : '',
+        data: result.output,
+        error: result.error,
+      }
+    },
+  }
+}
+
+function buildRouterDescription(manager: ConnectorManager): string {
+  const instances = manager.listConnectedInstances()
+  if (instances.length === 0) {
+    return 'Execute a method on a connected connector instance. No connectors are currently connected.'
+  }
+
+  const parts = ['Execute a method on a connected connector instance. Available:']
+  for (const inst of instances) {
+    const def = manager.getRegistry().get(inst.connectorId)
+    if (def) {
+      const methods = def.methods.map((m) => m.name).join(', ')
+      parts.push(`- ${inst.connectorId} (${inst.id}): ${methods}`)
+    }
+  }
+  return parts.join('\n')
+}

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

@@ -0,0 +1,143 @@
+import { z } from 'zod'
+import { defineTool } from '../../../tools/defineTool.js'
+import type { ToolDefinition } from '../../../types/tool/index.js'
+import type { ConnectorInstanceId } from '../../../types/ids/index.js'
+import type { ConnectorManager } from '../../../manager/connector/lifecycle.js'
+import { parseConnectorInstanceId } from '../../../utils/id.js'
+
+export interface ConnectorToolConfig {
+  manager: ConnectorManager
+}
+
+const connectorExecuteInputSchema = z.object({
+  instance_id: z
+    .string()
+    .describe('The connector instance ID to execute against'),
+  method: z
+    .string()
+    .describe('The connector method to invoke (e.g. "request", "send")'),
+  input: z
+    .record(z.unknown())
+    .describe('Input parameters for the connector method'),
+})
+
+const connectorListInputSchema = z.object({})
+
+export function createConnectorExecuteTool(
+  config: ConnectorToolConfig,
+): ToolDefinition {
+  return defineTool({
+    name: 'connector_execute',
+    description:
+      'Execute a method on a connected external service. Use this to make HTTP requests, send webhooks, or interact with any configured connector.',
+    inputSchema: connectorExecuteInputSchema,
+    category: 'network',
+    permissions: ['network_access'],
+    readOnly: false,
+    destructive: false,
+    concurrencySafe: true,
+
+    async execute(input) {
+      const instanceId = parseConnectorInstanceId(String(input.instance_id))
+      const instance = config.manager.getInstance(instanceId)
+
+      if (!instance) {
+        return {
+          success: false,
+          output: '',
+          error: `Connector instance not found: "${instanceId}"`,
+        }
+      }
+
+      if (instance.status !== 'connected') {
+        return {
+          success: false,
+          output: '',
+          error: `Connector "${instanceId}" is not connected (status: ${instance.status})`,
+        }
+      }
+
+      const result = await config.manager.execute({
+        instanceId,
+        method: input.method,
+        input: input.input,
+      })
+
+      if (!result.success) {
+        return {
+          success: false,
+          output: '',
+          error: result.error ?? 'Connector execution failed',
+        }
+      }
+
+      const outputStr =
+        typeof result.output === 'string'
+          ? result.output
+          : JSON.stringify(result.output, null, 2)
+
+      return {
+        success: true,
+        output: outputStr,
+        data: {
+          durationMs: result.durationMs,
+          metadata: result.metadata,
+        },
+      }
+    },
+  })
+}
+
+export function createConnectorListTool(
+  config: ConnectorToolConfig,
+): ToolDefinition {
+  return defineTool({
+    name: 'connector_list',
+    description:
+      'List all available connector instances and their connection status.',
+    inputSchema: connectorListInputSchema,
+    category: 'network',
+    permissions: [],
+    readOnly: true,
+    destructive: false,
+    concurrencySafe: true,
+
+    async execute() {
+      const instances = config.manager.listInstances()
+
+      if (instances.length === 0) {
+        return {
+          success: true,
+          output: 'No connector instances configured.',
+        }
+      }
+
+      const lines = instances.map(
+        (i) =>
+          `- ${i.id} (${i.connectorId}): ${i.config.name} [${i.status}]`,
+      )
+
+      return {
+        success: true,
+        output: lines.join('\n'),
+        data: {
+          instances: instances.map((i) => ({
+            id: i.id,
+            connectorId: i.connectorId,
+            name: i.config.name,
+            status: i.status,
+          })),
+        },
+      }
+    },
+  })
+}
+
+export function createConnectorTools(
+  config: ConnectorToolConfig,
+): ToolDefinition[] {
+  return [
+    createConnectorExecuteTool(config),
+    createConnectorListTool(config),
+  ]
+}

package/src/bridge/tools/connector/index.ts

@@ -0,0 +1,17 @@
+export {
+  createConnectorExecuteTool,
+  createConnectorListTool,
+  createConnectorTools,
+} from './definitions.js'
+export type { ConnectorToolConfig } from './definitions.js'
+
+export {
+  connectorMethodToTool,
+  connectorInstanceToTools,
+  allConnectorTools,
+  createConnectorRouterTool,
+} from './adapter.js'
+export type { ConnectorRouterInput } from './adapter.js'
+
+export { ConnectorToolRouter } from './router.js'
+export type { ConnectorToolStrategy, ConnectorToolRouterConfig } from './router.js'

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

@@ -0,0 +1,71 @@
+import type { ToolDefinition } from '../../../types/tool/index.js'
+import type { ConnectorManager } from '../../../manager/connector/lifecycle.js'
+import type { ToolRegistry } from '../../../registry/tool/execute.js'
+import {
+  connectorInstanceToTools,
+  createConnectorRouterTool,
+} from './adapter.js'
+import { getRootLogger, type Logger } from '../../../utils/logger.js'
+import { toErrorMessage } from '../../../utils/error.js'
+
+export type ConnectorToolStrategy = 'per-method' | 'router'
+
+export interface ConnectorToolRouterConfig {
+  manager: ConnectorManager
+  strategy?: ConnectorToolStrategy
+}
+
+export class ConnectorToolRouter {
+  private manager: ConnectorManager
+  private strategy: ConnectorToolStrategy
+  private log: Logger
+
+  constructor(config: ConnectorToolRouterConfig) {
+    this.manager = config.manager
+    this.strategy = config.strategy ?? 'per-method'
+    this.log = getRootLogger().child({ component: 'ConnectorToolRouter' })
+  }
+
+  getTools(): ToolDefinition[] {
+    if (this.strategy === 'router') {
+      const connected = this.manager.listConnectedInstances()
+      if (connected.length === 0) return []
+      return [createConnectorRouterTool(this.manager)]
+    }
+
+    const tools: ToolDefinition[] = []
+    for (const instance of this.manager.listConnectedInstances()) {
+      try {
+        tools.push(...connectorInstanceToTools(instance.id, this.manager))
+      } catch (err) {
+        this.log.error(`Failed to create tools for instance ${instance.id}`, {
+          error: toErrorMessage(err),
+        })
+      }
+    }
+    return tools
+  }
+
+  registerTools(toolRegistry: ToolRegistry): string[] {
+    const tools = this.getTools()
+    const names: string[] = []
+    for (const tool of tools) {
+      toolRegistry.register(tool)
+      names.push(tool.name)
+    }
+    this.log.info(`Registered ${names.length} connector tools`, { tools: names })
+    return names
+  }
+
+  unregisterTools(toolRegistry: ToolRegistry, toolNames: string[]): void {
+    for (const name of toolNames) {
+      toolRegistry.unregister(name)
+    }
+    this.log.info(`Unregistered ${toolNames.length} connector tools`)
+  }
+
+  refreshTools(toolRegistry: ToolRegistry, previousNames: string[]): string[] {
+    this.unregisterTools(toolRegistry, previousNames)
+    return this.registerTools(toolRegistry)
+  }
+}

package/src/config/runtime.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod'
+
+export const RuntimeConfigSchema = z.object({
+  model: z.string().default('qwen/qwen3.6-plus:free'),
+  temperature: z.number().min(0).max(2).default(0.3),
+  tokenBudget: z.number().positive().default(100_000),
+  maxResponseTokens: z.number().positive().default(8192),
+  timeoutMs: z.number().positive().default(600_000),
+  maxIterations: z.number().positive().default(200),
+})
+
+export type RuntimeConfig = z.infer<typeof RuntimeConfigSchema>
+
+export const RUNTIME_DEFAULTS: Readonly<RuntimeConfig> = RuntimeConfigSchema.parse({})