@namzu/sdk 0.1.1

package/src/agents/RouterAgent.ts

@@ -0,0 +1,236 @@
+import type { RunEventListener } from '../types/run/index.js'
+import type {
+  RouterAgentConfig,
+  RouterAgentResult,
+  RoutingDecision,
+  AgentInput,
+  AgentMetadata,
+} from '../types/agent/index.js'
+import { AbstractAgent } from './AbstractAgent.js'
+import { EMPTY_TOKEN_USAGE } from '../types/common/index.js'
+import { ZERO_COST } from '../utils/cost.js'
+import {
+  createSystemMessage,
+  createUserMessage,
+} from '../types/message/index.js'
+import { DecisionParser } from '../runtime/decision/parser.js'
+import { FallbackResolver } from '../runtime/decision/fallback.js'
+import type { FallbackStrategy } from '../types/decision/index.js'
+import { getRootLogger } from '../utils/logger.js'
+
+export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentResult> {
+  readonly type = 'router' as const
+
+  constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>) {
+    super({
+      ...metadata,
+      type: 'router',
+      capabilities: {
+        supportsTools: false,
+        supportsStreaming: true,
+        supportsConcurrency: false,
+        supportsSubAgents: true,
+      },
+    })
+  }
+
+  async run(
+    input: AgentInput,
+    config: RouterAgentConfig,
+    listener?: RunEventListener,
+  ): Promise<RouterAgentResult> {
+    const startTime = Date.now()
+    const runId = this.createRunId()
+
+    await this.emitEvent({ type: 'run_started', runId }, listener)
+
+    const decision = await this.route(input, config)
+
+    let targetRoute = config.routes.find((r) => r.agentId === decision.agentId)
+
+    if (!targetRoute) {
+      const fallback = config.fallbackAgentId
+        ? config.routes.find((r) => r.agentId === config.fallbackAgentId)
+        : undefined
+
+      if (!fallback) {
+        const errorMsg = `No route found for "${decision.agentId}"`
+
+        await this.emitEvent(
+          { type: 'run_failed', runId, error: errorMsg },
+          listener,
+        )
+
+        return {
+          runId,
+          status: 'failed',
+          stopReason: 'error',
+          usage: { ...EMPTY_TOKEN_USAGE },
+          cost: { ...ZERO_COST },
+          iterations: 1,
+          durationMs: Date.now() - startTime,
+          messages: input.messages,
+          lastError: errorMsg,
+          selectedRoute: decision.agentId,
+          routingDecision: decision,
+          delegateResult: {
+            runId,
+            status: 'failed',
+            usage: { ...EMPTY_TOKEN_USAGE },
+            cost: { ...ZERO_COST },
+            iterations: 0,
+            durationMs: 0,
+            messages: [],
+          },
+        }
+      }
+
+      decision.agentId = fallback.agentId
+      targetRoute = fallback
+    }
+
+    const delegateResult = await targetRoute.agent.run(input, config, listener)
+
+    await this.emitEvent(
+      {
+        type: 'run_completed',
+        runId,
+        result: delegateResult.result ?? '',
+      },
+      listener,
+    )
+
+    return {
+      runId,
+      status: delegateResult.status,
+      stopReason: delegateResult.stopReason,
+      usage: delegateResult.usage,
+      cost: delegateResult.cost,
+      iterations: delegateResult.iterations + 1,
+      durationMs: Date.now() - startTime,
+      messages: delegateResult.messages,
+      result: delegateResult.result,
+      lastError: delegateResult.lastError,
+      selectedRoute: decision.agentId,
+      routingDecision: decision,
+      delegateResult,
+    }
+  }
+
+  private async route(
+    input: AgentInput,
+    config: RouterAgentConfig,
+  ): Promise<RoutingDecision> {
+    const log = getRootLogger().child({ component: 'RouterAgent', agent: this.metadata.name })
+
+    const validAgentIds = config.routes.map((r) => r.agentId)
+    const fallbackAgentId = config.fallbackAgentId ?? config.routes[0]?.agentId ?? ''
+    const minConfidence = config.minConfidence ?? 0
+    const maxRetries = config.maxRoutingRetries ?? 1
+
+    const parser = new DecisionParser(
+      {
+        validAgentIds,
+        minConfidence,
+        maxRetries,
+        fallbackAgentId,
+      },
+      log,
+    )
+
+    const fallbackStrategies: FallbackStrategy[] = []
+
+    const patternMap = new Map<string, string[]>()
+    for (const route of config.routes) {
+      if (route.matchPatterns && route.matchPatterns.length > 0) {
+        patternMap.set(route.agentId, route.matchPatterns)
+      }
+    }
+    if (patternMap.size > 0) {
+      fallbackStrategies.push({ type: 'pattern_match', patterns: patternMap })
+    }
+
+    if (config.fallbackAgentId) {
+      fallbackStrategies.push({ type: 'fixed', agentId: config.fallbackAgentId })
+    }
+
+    fallbackStrategies.push({ type: 'first_route' })
+
+    const fallbackResolver = new FallbackResolver(fallbackStrategies, log)
+
+    const routeDescriptions = config.routes
+      .map((r) => `- ${r.agentId}: ${r.description}`)
+      .join('\n')
+
+    const prompt = config.routingPrompt ??
+      `Given the user's request, select the most appropriate agent.\n\nAvailable agents:\n${routeDescriptions}\n\nRespond with JSON only: { "agentId": "<id>", "confidence": <0-1>, "reasoning": "<why>" }`
+
+    const userContent = input.messages
+      .filter((m) => m.role === 'user')
+      .map((m) => m.content)
+      .filter((c): c is string => c !== null)
+      .join('\n')
+
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        const response = await config.provider.chat({
+          model: config.model,
+          messages: [
+            createSystemMessage(prompt),
+            createUserMessage(userContent),
+          ],
+          temperature: 0,
+          maxTokens: 200,
+        })
+
+        const parseResult = parser.parse(response.message.content)
+
+        if (parseResult.ok && parseResult.source === 'parsed') {
+          return {
+            agentId: parseResult.decision.agentId,
+            confidence: parseResult.decision.confidence,
+            reasoning: parseResult.decision.reasoning,
+            routingSource: 'provider',
+          }
+        }
+
+        if (parseResult.ok && parseResult.source === 'fallback') {
+          log.warn(`Routing attempt ${attempt + 1} fell back`, {
+            reason: parseResult.reason,
+            decision: parseResult.decision,
+          })
+
+          if (attempt === maxRetries - 1) {
+            return {
+              agentId: parseResult.decision.agentId,
+              confidence: parseResult.decision.confidence,
+              reasoning: parseResult.decision.reasoning,
+              routingSource: 'fallback',
+            }
+          }
+
+          continue
+        }
+
+        if (!parseResult.ok) {
+          log.warn(`Routing attempt ${attempt + 1} failed to parse`, {
+            error: parseResult.error,
+          })
+          if (attempt === maxRetries - 1) {
+            break
+          }
+          continue
+        }
+      } catch (err) {
+        log.warn(`Routing LLM call failed on attempt ${attempt + 1}`, {
+          error: String(err),
+        })
+        if (attempt === maxRetries - 1) {
+          break
+        }
+      }
+    }
+
+    return fallbackResolver.resolve(userContent, validAgentIds)
+  }
+}

package/src/agents/SupervisorAgent.ts

@@ -0,0 +1,162 @@
+import type {
+	AgentInput,
+	AgentMetadata,
+	SupervisorAgentConfig,
+	SupervisorAgentResult,
+} from "../types/agent/index.js";
+import type { AgentTaskContext } from "../types/agent/task.js";
+import type { TaskGateway } from "../types/agent/gateway.js";
+import type { TaskId, ThreadId } from "../types/ids/index.js";
+import type { RunEventListener } from "../types/run/index.js";
+import type { LaunchedTaskMeta } from "../runtime/query/iteration/phases/context.js";
+import { EMPTY_TOKEN_USAGE } from "../types/common/index.js";
+import { ZERO_COST } from "../utils/cost.js";
+import { ToolRegistry } from "../registry/tool/execute.js";
+import { LocalTaskGateway } from "../gateway/local.js";
+import { buildCoordinatorTools } from "../tools/coordinator/index.js";
+import { drainQuery } from "../runtime/query/index.js";
+import { AbstractAgent } from "./AbstractAgent.js";
+
+export class SupervisorAgent extends AbstractAgent<
+	SupervisorAgentConfig,
+	SupervisorAgentResult
+> {
+	readonly type = "supervisor" as const;
+
+	constructor(metadata: Omit<AgentMetadata, "type" | "capabilities">) {
+		super({
+			...metadata,
+			type: "supervisor",
+			capabilities: {
+				supportsTools: true,
+				supportsStreaming: true,
+				supportsConcurrency: true,
+				supportsSubAgents: true,
+			},
+		});
+	}
+
+	async run(
+		input: AgentInput,
+		config: SupervisorAgentConfig,
+		listener?: RunEventListener,
+	): Promise<SupervisorAgentResult> {
+		const startTime = Date.now();
+		const runId = this.createRunId();
+
+		if (!config.threadId) {
+			throw new Error("SupervisorAgent requires threadId in config");
+		}
+
+		let gateway: TaskGateway;
+		if (config.gateway) {
+			gateway = config.gateway;
+		} else if (config.agentManager) {
+			const taskContext: AgentTaskContext = {
+				parentRunId: runId,
+				parentAgentId: this.metadata.id,
+				parentAbortController: this.abortController,
+				depth: 0,
+				budgetTracker: {
+					total: config.tokenBudget,
+					remaining: config.tokenBudget,
+				},
+				factoryOptions: config.factoryOptions,
+				threadId: config.threadId as ThreadId,
+			};
+			gateway = new LocalTaskGateway(config.agentManager, taskContext, listener, input);
+		} else {
+			throw new Error(
+				"SupervisorAgentConfig requires either 'gateway' or 'agentManager'",
+			);
+		}
+
+		const launchedTasks = new Map<TaskId, LaunchedTaskMeta>();
+
+		let planManagerRef: import('../manager/plan/lifecycle.js').PlanManager | undefined;
+
+		const coordinatorToolDefs = buildCoordinatorTools({
+			gateway,
+			workingDirectory: input.workingDirectory,
+			allowedAgentIds: config.agentIds,
+			taskStore: input.taskStore,
+			runId,
+			getPlanManager: () => planManagerRef,
+			onTaskLaunched: (agentTaskId, meta) => {
+				launchedTasks.set(agentTaskId, meta);
+			},
+		});
+
+		const tools = new ToolRegistry();
+		for (const tool of coordinatorToolDefs) {
+			tools.register(tool);
+		}
+
+		const session = await drainQuery(
+			{
+				systemPrompt: config.systemPrompt,
+				provider: config.provider,
+				tools,
+				sessionConfig: {
+					model: config.model,
+					tokenBudget: config.tokenBudget,
+					timeoutMs: config.timeoutMs,
+					maxIterations: config.maxIterations,
+					temperature: config.temperature,
+					env: config.env,
+				},
+				agentId: this.metadata.id,
+				agentName: this.metadata.name,
+				workingDirectory: input.workingDirectory,
+				messages: input.messages,
+				signal: input.signal,
+				threadId: config.threadId as ThreadId,
+				runId,
+				parentRunId: config.parentRunId,
+				depth: config.depth,
+				contextLevel: "full",
+				onContextCreated: ({ planManager }) => { planManagerRef = planManager; },
+				taskStore: input.taskStore,
+				runtimeToolOverrides: input.runtimeToolOverrides,
+				taskGateway: gateway,
+				launchedTasks,
+			},
+			listener,
+		);
+
+		const taskHandles = gateway.listTasks();
+		const taskResults = taskHandles.map((handle, index) => ({
+			agentId: handle.agentId,
+			result: handle.result ?? {
+				runId,
+				status: handle.state as "completed" | "failed" | "cancelled",
+				usage: { ...EMPTY_TOKEN_USAGE },
+				cost: { ...ZERO_COST },
+				iterations: 0,
+				durationMs: Date.now() - handle.createdAt,
+				messages: [],
+			},
+			taskIndex: index,
+		}));
+
+		const completedTasks = taskResults.filter(
+			(t) => t.result.status === "completed",
+		).length;
+
+		return {
+			runId: session.id,
+			status: session.status === "completed" ? "completed" : "failed",
+			stopReason: session.stopReason,
+			usage: session.tokenUsage,
+			cost: session.costInfo,
+			iterations: session.currentIteration,
+			durationMs: Date.now() - startTime,
+			messages: session.messages,
+			result: session.result,
+			lastError: session.lastError,
+			taskResults,
+			completedTasks,
+			totalTasks: taskResults.length,
+		};
+	}
+}

package/src/agents/defineAgent.ts

@@ -0,0 +1,73 @@
+import type { RunEventListener } from '../types/run/index.js'
+import type {
+  AgentType,
+  AgentMetadata,
+  AgentCapabilities,
+  BaseAgentConfig,
+  BaseAgentResult,
+  AgentInput,
+  Agent,
+} from '../types/agent/index.js'
+
+export interface DefineAgentOptions<
+  TConfig extends BaseAgentConfig = BaseAgentConfig,
+  TResult extends BaseAgentResult = BaseAgentResult,
+> {
+  type: AgentType
+  id: string
+  name: string
+  version: string
+  category: string
+  description: string
+  capabilities?: Partial<AgentCapabilities>
+  run(input: AgentInput, config: TConfig, listener?: RunEventListener): Promise<TResult>
+  cancel?(): Promise<void>
+}
+
+const DEFAULT_CAPABILITIES: AgentCapabilities = {
+  supportsTools: false,
+  supportsStreaming: false,
+  supportsConcurrency: false,
+  supportsSubAgents: false,
+}
+
+export function defineAgent<
+  TConfig extends BaseAgentConfig = BaseAgentConfig,
+  TResult extends BaseAgentResult = BaseAgentResult,
+>(options: DefineAgentOptions<TConfig, TResult>): Agent<TConfig, TResult> {
+  const abortController = new AbortController()
+
+  const metadata: AgentMetadata = {
+    type: options.type,
+    id: options.id,
+    name: options.name,
+    version: options.version,
+    category: options.category,
+    description: options.description,
+    capabilities: { ...DEFAULT_CAPABILITIES, ...options.capabilities },
+  }
+
+  return {
+    type: options.type,
+    metadata,
+
+    async run(
+      input: AgentInput,
+      config: TConfig,
+      listener?: RunEventListener,
+    ): Promise<TResult> {
+      return options.run(input, config, listener)
+    },
+
+    async cancel(): Promise<void> {
+      abortController.abort()
+      if (options.cancel) {
+        await options.cancel()
+      }
+    },
+
+    getCapabilities(): AgentCapabilities {
+      return metadata.capabilities
+    },
+  }
+}

package/src/agents/index.ts

@@ -0,0 +1,7 @@
+export { AbstractAgent } from './AbstractAgent.js'
+export { ReactiveAgent } from './ReactiveAgent.js'
+export { PipelineAgent } from './PipelineAgent.js'
+export { RouterAgent } from './RouterAgent.js'
+export { SupervisorAgent } from './SupervisorAgent.js'
+export { defineAgent } from './defineAgent.js'
+export type { DefineAgentOptions } from './defineAgent.js'

package/src/bridge/a2a/agent-card.ts

@@ -0,0 +1,77 @@
+import type { AgentInfo } from '../../contracts/index.js'
+import type {
+  A2AAgentCard,
+  A2AAgentSkill,
+  A2AServerConfig,
+} from '../../types/a2a/index.js'
+import type { Skill } from '../../types/skills/index.js'
+
+const A2A_PROTOCOL_VERSION = '0.3.0'
+
+function toolToA2ASkill(toolName: string): A2AAgentSkill {
+  return {
+    id: `tool-${toolName}`,
+    name: toolName,
+    description: `Execute ${toolName} tool`,
+    tags: ['tool'],
+  }
+}
+
+function skillToA2ASkill(skill: Skill): A2AAgentSkill {
+  return {
+    id: skill.metadata.name,
+    name: skill.metadata.name,
+    description: skill.metadata.description,
+    tags: ['procedure'],
+  }
+}
+
+export function buildAgentCard(
+  info: AgentInfo,
+  config: A2AServerConfig,
+  skills?: readonly Skill[],
+): A2AAgentCard {
+  const a2aSkills: A2AAgentSkill[] = []
+
+  for (const toolName of info.tools) {
+    a2aSkills.push(toolToA2ASkill(toolName))
+  }
+
+  if (skills) {
+    for (const skill of skills) {
+      a2aSkills.push(skillToA2ASkill(skill))
+    }
+  }
+
+  return {
+    name: info.name,
+    description: info.description,
+    version: info.version,
+    protocolVersion: A2A_PROTOCOL_VERSION,
+    provider: {
+      organization: config.providerOrganization ?? 'Namzu',
+      url: config.providerUrl,
+    },
+    capabilities: {
+      streaming: info.capabilities?.supportsStreaming ?? false,
+      pushNotifications: false,
+      extendedAgentCard: false,
+    },
+    defaultInputModes: ['text'],
+    defaultOutputModes: ['text'],
+    skills: a2aSkills,
+    supportedInterfaces: [
+      {
+        url: `${config.baseUrl}/a2a/${info.id}`,
+        transport: config.transport,
+      },
+    ],
+    securitySchemes: {
+      bearer: {
+        type: 'http',
+        scheme: 'bearer',
+      },
+    },
+    securityRequirements: [{ bearer: [] }],
+  }
+}

package/src/bridge/a2a/index.ts

@@ -0,0 +1,18 @@
+export { buildAgentCard } from './agent-card.js'
+
+export {
+  runToA2ATask,
+  isTerminalState,
+  runStatusToA2AState,
+  a2aMessageToCreateRun,
+  type CreateRunFromA2A,
+} from './task.js'
+
+export {
+  messageToA2A,
+  threadMessageToA2A,
+  extractTextFromA2AMessage,
+  a2aMessageToInput,
+} from './message.js'
+
+export { mapRunToA2AEvent, mapSessionToA2AEvent } from './mapper.js'