@namzu/sdk 0.1.1

package/src/registry/tool/execute.ts

@@ -0,0 +1,323 @@
+import { SpanStatusCode } from "@opentelemetry/api";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { getTracer } from "../../provider/telemetry/setup.js";
+import { GENAI, NAMZU, toolSpanName } from "../../telemetry/attributes.js";
+import type {
+	LLMToolSchema,
+	ToolAvailability,
+	ToolContext,
+	ToolDefinition,
+	ToolRegistryConfig,
+	ToolResult,
+} from "../../types/tool/index.js";
+import { toErrorMessage } from "../../utils/error.js";
+import { type Logger, getRootLogger } from "../../utils/logger.js";
+import { Registry } from "../Registry.js";
+
+export interface ToolExecutionResult extends ToolResult {
+	permissionDenied?: boolean;
+	permissionMessage?: string;
+}
+
+export class ToolRegistry extends Registry<ToolDefinition> {
+	private log: Logger;
+	private availability: Map<string, ToolAvailability> = new Map();
+
+	constructor(config?: ToolRegistryConfig) {
+		super();
+		this.log = (config?.logger ?? getRootLogger()).child({
+			component: "ToolRegistry",
+		});
+	}
+
+	override register(id: string, tool: ToolDefinition): void;
+	register(tool: ToolDefinition, initialState?: ToolAvailability): void;
+	register(tools: ToolDefinition[], initialState?: ToolAvailability): void;
+	register(
+		idOrToolOrTools: string | ToolDefinition | ToolDefinition[],
+		maybeTool?: ToolDefinition | ToolAvailability,
+	): void {
+		if (Array.isArray(idOrToolOrTools)) {
+			const state = (
+				typeof maybeTool === "string" ? maybeTool : "active"
+			) as ToolAvailability;
+			for (const tool of idOrToolOrTools) {
+				this.registerOne(tool.name, tool, state);
+			}
+			return;
+		}
+
+		const tool =
+			typeof idOrToolOrTools === "string"
+				? (maybeTool as ToolDefinition)!
+				: idOrToolOrTools;
+		const id =
+			typeof idOrToolOrTools === "string" ? idOrToolOrTools : tool.name;
+		const state: ToolAvailability =
+			typeof maybeTool === "string" ? maybeTool : "active";
+
+		this.registerOne(id, tool, state);
+	}
+
+	private registerOne(
+		id: string,
+		tool: ToolDefinition,
+		state: ToolAvailability,
+	): void {
+		if (this.has(id)) {
+			this.log.warn(`Tool "${id}" is already registered, overwriting.`);
+		}
+		super.register(id, tool);
+		this.availability.set(id, state);
+		this.log.info(`Tool registered: ${id} (${state})`);
+	}
+
+	override unregister(id: string): boolean {
+		this.availability.delete(id);
+		return super.unregister(id);
+	}
+
+	override clear(): void {
+		this.availability.clear();
+		super.clear();
+	}
+
+	activate(names: string[]): void {
+		for (const name of names) {
+			this.getOrThrow(name);
+			this.availability.set(name, "active");
+			this.log.debug(`Tool activated: ${name}`);
+		}
+	}
+
+	defer(names: string[]): void {
+		for (const name of names) {
+			this.getOrThrow(name);
+			this.availability.set(name, "deferred");
+			this.log.debug(`Tool deferred: ${name}`);
+		}
+	}
+
+	suspendAll(): void {
+		for (const name of this.listIds()) {
+			if (this.getAvailability(name) === "active") {
+				this.availability.set(name, "suspended");
+			}
+		}
+		this.log.info("All active tools suspended");
+	}
+
+	hasSuspended(): boolean {
+		for (const state of this.availability.values()) {
+			if (state === "suspended") return true;
+		}
+		return false;
+	}
+
+	getAvailability(name: string): ToolAvailability {
+		return this.availability.get(name) ?? "active";
+	}
+
+	searchDeferred(query: string): ToolDefinition[] {
+		const q = query.toLowerCase();
+		return this.getByAvailability(["deferred"]).filter(
+			(t) =>
+				t.name.toLowerCase().includes(q) ||
+				t.description.toLowerCase().includes(q),
+		);
+	}
+
+	getOrThrow(name: string): ToolDefinition {
+		const tool = this.get(name);
+		if (!tool) {
+			throw new Error(
+				`Tool not found: "${name}". Available tools: ${this.listIds().join(", ")}`,
+			);
+		}
+		return tool;
+	}
+
+	listNames(): string[] {
+		return this.listIds();
+	}
+
+	toPromptSection(toolNames?: string[]): string {
+		const active = this.getByAvailability(["active"], toolNames);
+		const deferred = this.getByAvailability(["deferred"], toolNames);
+
+		const parts: string[] = [];
+
+		if (active.length > 0) {
+			const entries = active
+				.map((t) => `- ${t.name}: ${t.description}`)
+				.join("\n");
+			parts.push(`<available_tools>\n${entries}\n</available_tools>`);
+		}
+
+		if (deferred.length > 0) {
+			const entries = deferred.map((t) => `- ${t.name}`).join("\n");
+			parts.push(
+				`<deferred_tools>\nUse search_tools to load these before use:\n${entries}\n</deferred_tools>`,
+			);
+		}
+
+		if (parts.length === 0) return "";
+		return parts.join("\n\n");
+	}
+
+	toLLMTools(toolNames?: string[]): LLMToolSchema[] {
+		const toolsToConvert = this.getByAvailability(
+			["active", "suspended"],
+			toolNames,
+		);
+
+		return toolsToConvert.map((tool) => ({
+			type: "function" as const,
+			function: {
+				name: tool.name,
+				description: tool.description,
+				parameters: zodToJsonSchema(tool.inputSchema, {
+					target: "jsonSchema7",
+					$refStrategy: "none",
+				}) as Record<string, unknown>,
+			},
+		}));
+	}
+
+	getCallableTools(toolNames?: string[]): ToolDefinition[] {
+		return this.getByAvailability(["active"], toolNames);
+	}
+
+	async execute(
+		toolName: string,
+		rawInput: unknown,
+		context: ToolContext,
+	): Promise<ToolExecutionResult> {
+		const tracer = getTracer();
+
+		return tracer.startActiveSpan(toolSpanName(toolName), async (span) => {
+			span.setAttributes({
+				[GENAI.TOOL_NAME]: toolName,
+				[GENAI.TOOL_TYPE]: "function",
+			});
+
+			const tool = this.getOrThrow(toolName);
+
+			const availability = this.getAvailability(toolName);
+			if (availability !== "active") {
+				const msg = `Tool "${toolName}" is ${availability} and cannot be executed`;
+				this.log.warn(msg);
+				span.setAttributes({
+					[NAMZU.TOOL_SUCCESS]: false,
+					[NAMZU.TOOL_ERROR]: msg,
+				});
+				span.setStatus({ code: SpanStatusCode.ERROR, message: msg });
+				span.end();
+				return {
+					success: false,
+					output: "",
+					error: msg,
+				};
+			}
+
+			const mode = context.permissionContext?.mode ?? "auto";
+			if (mode === "plan") {
+				const isReadOnly = tool.isReadOnly ? tool.isReadOnly(rawInput) : false;
+				if (!isReadOnly) {
+					const msg = `plan mode: non-read-only tool "${toolName}" blocked`;
+					span.setAttributes({
+						[NAMZU.TOOL_SUCCESS]: false,
+						[NAMZU.TOOL_ERROR]: msg,
+					});
+					span.setStatus({ code: SpanStatusCode.ERROR, message: msg });
+					span.end();
+					return {
+						success: false,
+						output: "",
+						error: msg,
+						permissionDenied: true,
+						permissionMessage: msg,
+					};
+				}
+			}
+
+			const parseResult = tool.inputSchema.safeParse(rawInput);
+			if (!parseResult.success) {
+				const errorMessage = parseResult.error.issues
+					.map((i) => `${i.path.join(".")}: ${i.message}`)
+					.join("; ");
+
+				this.log.error(`Tool input validation failed: ${toolName}`, {
+					errors: errorMessage,
+				});
+
+				span.setAttributes({
+					[NAMZU.TOOL_SUCCESS]: false,
+					[NAMZU.TOOL_ERROR]: `Validation: ${errorMessage}`,
+				});
+				span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage });
+				span.end();
+
+				return {
+					success: false,
+					output: "",
+					error: `Invalid input for tool "${toolName}": ${errorMessage}`,
+				};
+			}
+
+			const finalInput = parseResult.data;
+
+			try {
+				this.log.debug(`Executing tool: ${toolName}`);
+				const result = await tool.execute(finalInput, context);
+				this.log.debug(`Tool completed: ${toolName}`, {
+					success: result.success,
+				});
+
+				span.setAttribute(NAMZU.TOOL_SUCCESS, result.success);
+				if (!result.success && result.error) {
+					span.setAttribute(NAMZU.TOOL_ERROR, result.error);
+					span.setStatus({ code: SpanStatusCode.ERROR, message: result.error });
+				} else {
+					span.setStatus({ code: SpanStatusCode.OK });
+				}
+
+				return result;
+			} catch (err) {
+				const errorMessage = toErrorMessage(err);
+				this.log.error(`Tool execution error: ${toolName}`, {
+					error: errorMessage,
+				});
+
+				span.setAttributes({
+					[NAMZU.TOOL_SUCCESS]: false,
+					[NAMZU.TOOL_ERROR]: errorMessage,
+				});
+				span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage });
+				span.recordException(
+					err instanceof Error ? err : new Error(errorMessage),
+				);
+
+				return {
+					success: false,
+					output: "",
+					error: `Tool "${toolName}" execution failed: ${errorMessage}`,
+				};
+			} finally {
+				span.end();
+			}
+		});
+	}
+
+	private getByAvailability(
+		states: ToolAvailability[],
+		filter?: string[],
+	): ToolDefinition[] {
+		const candidates = filter
+			? filter.map((n) => this.getOrThrow(n))
+			: this.getAll();
+		return candidates.filter((t) =>
+			states.includes(this.getAvailability(t.name)),
+		);
+	}
+}

package/src/run/LimitChecker.ts

@@ -0,0 +1,86 @@
+import type { StopReason, LimitCheckerConfig } from '../types/run/index.js'
+
+export interface LimitCheckerState {
+  aborted: boolean
+  totalTokens: number
+  totalCost: number
+  currentIteration: number
+  startTime: number
+}
+
+export type LimitCheckResult =
+  | { type: 'ok' }
+  | { type: 'warning'; reason: StopReason }
+  | { type: 'hard_stop'; reason: StopReason }
+
+export function checkLimits(
+  config: LimitCheckerConfig,
+  state: LimitCheckerState,
+): StopReason | null {
+  const result = checkLimitsDetailed(config, state)
+  if (result.type === 'ok') return null
+  return result.reason
+}
+
+export function checkLimitsDetailed(
+  config: LimitCheckerConfig,
+  state: LimitCheckerState,
+): LimitCheckResult {
+  if (state.aborted) {
+    return { type: 'hard_stop', reason: 'cancelled' }
+  }
+
+  if (Date.now() - state.startTime > config.timeoutMs) {
+    return { type: 'hard_stop', reason: 'timeout' }
+  }
+
+  if (config.tokenBudget > 0 && state.totalTokens >= config.tokenBudget) {
+    return { type: 'hard_stop', reason: 'token_budget' }
+  }
+
+  if (config.costLimitUsd && config.costLimitUsd > 0 && state.totalCost >= config.costLimitUsd) {
+    return { type: 'hard_stop', reason: 'cost_limit' }
+  }
+
+  if (state.currentIteration >= config.maxIterations) {
+    return { type: 'hard_stop', reason: 'max_iterations' }
+  }
+
+  if (config.tokenBudget > 0) {
+    const usageRatio = state.totalTokens / config.tokenBudget
+    if (usageRatio >= config.budgetWarningThreshold) {
+      return { type: 'warning', reason: 'token_budget' }
+    }
+  }
+
+  if (config.costLimitUsd && config.costLimitUsd > 0) {
+    const costRatio = state.totalCost / config.costLimitUsd
+    if (costRatio >= config.budgetWarningThreshold) {
+      return { type: 'warning', reason: 'cost_limit' }
+    }
+  }
+
+  const timeElapsed = Date.now() - state.startTime
+  const timeRatio = timeElapsed / config.timeoutMs
+  if (timeRatio >= config.budgetWarningThreshold) {
+    return { type: 'warning', reason: 'timeout' }
+  }
+
+  return { type: 'ok' }
+}
+
+export function buildLimitConfig(
+  tokenBudget: number,
+  timeoutMs: number,
+  costLimitUsd?: number,
+  maxIterations?: number,
+  budgetWarningThreshold?: number,
+): LimitCheckerConfig {
+  return {
+    tokenBudget,
+    timeoutMs,
+    costLimitUsd,
+    maxIterations: maxIterations ?? 200,
+    budgetWarningThreshold: budgetWarningThreshold ?? 0.9,
+  }
+}

package/src/run/index.ts

@@ -0,0 +1,9 @@
+export { RunPersistence, SessionManager } from '../manager/run/persistence.js'
+
+export { RunDiskStore, SessionStore } from '../store/run/disk.js'
+
+export { createRunReporter, createSessionReporter } from './reporter.js'
+export type { RunReporter, SessionReporter } from './reporter.js'
+
+export { checkLimitsDetailed, buildLimitConfig } from './LimitChecker.js'
+export type { LimitCheckerState, LimitCheckResult } from './LimitChecker.js'

package/src/run/reporter.ts

@@ -0,0 +1,191 @@
+import type {
+	AgentRun,
+	RunEvent,
+	RunEventListener,
+} from "../types/run/index.js";
+import { formatCost } from "../utils/cost.js";
+import { type Logger, getRootLogger } from "../utils/logger.js";
+
+function formatDuration(ms: number): string {
+	if (ms < 1000) return `${ms}ms`;
+	const seconds = Math.floor(ms / 1000);
+	if (seconds < 60) return `${(ms / 1000).toFixed(1)}s`;
+	const minutes = Math.floor(seconds / 60);
+	const remainingSeconds = seconds % 60;
+	return `${minutes}m ${remainingSeconds}s`;
+}
+
+export interface RunReporter {
+	listener: RunEventListener;
+	summary(run: AgentRun): void;
+}
+
+export type SessionReporter = RunReporter;
+
+export function createRunReporter(parentLogger?: Logger): RunReporter {
+	const log = (parentLogger ?? getRootLogger()).child({
+		component: "RunReporter",
+	});
+
+	const listener: RunEventListener = (event: RunEvent) => {
+		switch (event.type) {
+			case "run_started":
+				log.info("Run started", {
+					runId: event.runId,
+					hasSystemPrompt: !!event.systemPrompt,
+					systemPromptLength: event.systemPrompt?.length ?? 0,
+				});
+				break;
+
+			case "iteration_started":
+				log.info(`Iteration ${event.iteration} started`, {
+					runId: event.runId,
+					iteration: event.iteration,
+				});
+				break;
+
+			case "iteration_completed":
+				log.info(`Iteration ${event.iteration} completed`, {
+					runId: event.runId,
+					iteration: event.iteration,
+					hasToolCalls: event.hasToolCalls,
+				});
+				break;
+
+			case "tool_executing":
+				log.info(`Tool executing: ${event.toolName}`, {
+					runId: event.runId,
+					tool: event.toolName,
+				});
+				break;
+
+			case "tool_completed":
+				log.info(`Tool completed: ${event.toolName}`, {
+					runId: event.runId,
+					tool: event.toolName,
+				});
+				break;
+
+			case "llm_response":
+				log.info("LLM response received", {
+					runId: event.runId,
+					hasToolCalls: event.hasToolCalls,
+				});
+				break;
+
+			case "token_usage_updated":
+				log.info("Token usage updated", {
+					runId: event.runId,
+					promptTokens: event.usage.promptTokens,
+					completionTokens: event.usage.completionTokens,
+					totalTokens: event.usage.totalTokens,
+					totalCost: event.cost.totalCost,
+				});
+				break;
+
+			case "run_completed":
+				log.info("Run completed", { runId: event.runId });
+				break;
+
+			case "run_failed":
+				log.error("Run failed", {
+					runId: event.runId,
+					error: event.error,
+				});
+				break;
+
+			case "activity_created":
+			case "activity_updated":
+			case "plan_ready":
+			case "plan_approved":
+			case "plan_rejected":
+			case "plan_step_updated":
+			case "tool_review_requested":
+			case "tool_review_completed":
+			case "checkpoint_created":
+			case "run_paused":
+			case "run_resuming":
+				break;
+
+			case "agent_pending":
+				log.info(`Agent task pending: ${event.childAgentId}`, {
+					runId: event.runId,
+					taskId: event.taskId,
+					parentAgentId: event.parentAgentId,
+					childAgentId: event.childAgentId,
+					depth: event.depth,
+				});
+				break;
+
+			case "agent_completed":
+				log.info("Agent task completed", {
+					runId: event.runId,
+					taskId: event.taskId,
+					status: event.result.status,
+					iterations: event.result.iterations,
+				});
+				break;
+
+			case "agent_failed":
+				log.error("Agent task failed", {
+					runId: event.runId,
+					taskId: event.taskId,
+					error: event.error,
+				});
+				break;
+
+			case "agent_canceled":
+				log.info("Agent task canceled", {
+					runId: event.runId,
+					taskId: event.taskId,
+				});
+				break;
+
+			case "task_created":
+				log.info(`Task created: ${event.subject}`, {
+					runId: event.runId,
+					taskId: event.taskId,
+					status: event.status,
+				});
+				break;
+
+			case "task_updated":
+				log.info(`Task updated: ${event.subject}`, {
+					runId: event.runId,
+					taskId: event.taskId,
+					status: event.status,
+					owner: event.owner,
+				});
+				break;
+
+			default: {
+				const _exhaustive: never = event;
+				throw new Error(
+					`Unhandled run event type: ${(_exhaustive as RunEvent).type}`,
+				);
+			}
+		}
+	};
+
+	function summary(run: AgentRun): void {
+		const elapsed = (run.endedAt ?? Date.now()) - run.startedAt;
+		const { tokenUsage, costInfo, currentIteration, stopReason } = run;
+
+		log.info("Run summary", {
+			runId: run.id,
+			agent: run.metadata.agentName,
+			status: run.status,
+			stopReason: stopReason ?? "unknown",
+			iterations: currentIteration,
+			promptTokens: tokenUsage.promptTokens,
+			completionTokens: tokenUsage.completionTokens,
+			totalTokens: tokenUsage.totalTokens,
+			cost: formatCost(costInfo.totalCost),
+			duration: formatDuration(elapsed),
+		});
+	}
+
+	return { listener, summary };
+}
+
+export const createSessionReporter = createRunReporter;

package/src/runtime/decision/fallback.ts

@@ -0,0 +1,93 @@
+import type { FallbackStrategy } from '../../types/decision/index.js'
+import type { RoutingDecision } from '../../types/agent/router.js'
+import type { Logger } from '../../utils/logger.js'
+
+export class FallbackResolver {
+  private strategies: FallbackStrategy[]
+  private log: Logger
+
+  constructor(strategies: FallbackStrategy[], log: Logger) {
+    this.strategies = strategies
+    this.log = log
+  }
+
+  resolve(userContent: string, validAgentIds: string[]): RoutingDecision {
+    for (const strategy of this.strategies) {
+      switch (strategy.type) {
+        case 'pattern_match': {
+          const match = this.matchPatterns(userContent, strategy.patterns)
+          if (match && validAgentIds.includes(match)) {
+            this.log.info('Fallback resolved via pattern match', { agentId: match })
+            return {
+              agentId: match,
+              confidence: 0.5,
+              reasoning: `Pattern match fallback: matched "${match}"`,
+              routingSource: 'fallback',
+            }
+          }
+          break
+        }
+        case 'fixed': {
+          if (validAgentIds.includes(strategy.agentId)) {
+            this.log.info('Fallback resolved via fixed strategy', { agentId: strategy.agentId })
+            return {
+              agentId: strategy.agentId,
+              confidence: 0,
+              reasoning: 'Fixed fallback strategy',
+              routingSource: 'fallback',
+            }
+          }
+          break
+        }
+        case 'first_route': {
+          if (validAgentIds.length > 0) {
+            const first = validAgentIds[0]!
+            this.log.info('Fallback resolved via first_route strategy', { agentId: first })
+            return {
+              agentId: first,
+              confidence: 0,
+              reasoning: 'First route fallback strategy',
+              routingSource: 'fallback',
+            }
+          }
+          break
+        }
+        default: {
+          const _exhaustive: never = strategy
+          throw new Error(`Unhandled fallback strategy: ${(_exhaustive as FallbackStrategy).type}`)
+        }
+      }
+    }
+
+    this.log.error('All fallback strategies exhausted')
+    return {
+      agentId: validAgentIds[0] ?? '',
+      confidence: 0,
+      reasoning: 'All fallback strategies exhausted',
+      routingSource: 'hard_fail',
+    }
+  }
+
+  private matchPatterns(
+    userContent: string,
+    patterns: Map<string, string[]>,
+  ): string | null {
+    const lower = userContent.toLowerCase()
+    let bestMatch: { agentId: string; score: number } | null = null
+
+    for (const [agentId, keywords] of patterns) {
+      let score = 0
+      for (const keyword of keywords) {
+        if (lower.includes(keyword.toLowerCase())) {
+          score++
+        }
+      }
+
+      if (score > 0 && (!bestMatch || score > bestMatch.score)) {
+        bestMatch = { agentId, score }
+      }
+    }
+
+    return bestMatch?.agentId ?? null
+  }
+}

package/src/runtime/decision/index.ts

@@ -0,0 +1,2 @@
+export { DecisionParser } from './parser.js'
+export { FallbackResolver } from './fallback.js'