@namzu/sdk 0.1.1 → 0.1.2

package/src/registry/tool/execute.ts

@@ -1,7 +1,7 @@
-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 { 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,
@@ -9,183 +9,171 @@ import type {
 	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";
+} 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;
+	permissionDenied?: boolean
+	permissionMessage?: string
 }
 
 export class ToolRegistry extends Registry<ToolDefinition> {
-	private log: Logger;
-	private availability: Map<string, ToolAvailability> = new Map();
+	private log: Logger
+	private availability: Map<string, ToolAvailability> = new Map()
 
 	constructor(config?: ToolRegistryConfig) {
-		super();
+		super()
 		this.log = (config?.logger ?? getRootLogger()).child({
-			component: "ToolRegistry",
-		});
+			component: 'ToolRegistry',
+		})
 	}
 
-	override register(id: string, tool: ToolDefinition): void;
-	register(tool: ToolDefinition, initialState?: ToolAvailability): void;
-	register(tools: ToolDefinition[], initialState?: ToolAvailability): void;
-	register(
+	override register(id: string, tool: ToolDefinition): void
+	override register(tool: ToolDefinition, initialState?: ToolAvailability): void
+	override register(tools: ToolDefinition[], initialState?: ToolAvailability): void
+	override register(
 		idOrToolOrTools: string | ToolDefinition | ToolDefinition[],
 		maybeTool?: ToolDefinition | ToolAvailability,
 	): void {
 		if (Array.isArray(idOrToolOrTools)) {
-			const state = (
-				typeof maybeTool === "string" ? maybeTool : "active"
-			) as ToolAvailability;
+			const state = (typeof maybeTool === 'string' ? maybeTool : 'active') as ToolAvailability
 			for (const tool of idOrToolOrTools) {
-				this.registerOne(tool.name, tool, state);
+				this.registerOne(tool.name, tool, state)
 			}
-			return;
+			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";
+		if (typeof idOrToolOrTools === 'string') {
+			if (!maybeTool || typeof maybeTool === 'string') {
+				throw new Error('register(id, tool) requires a ToolDefinition argument')
+			}
+			this.registerOne(idOrToolOrTools, maybeTool, 'active')
+			return
+		}
 
-		this.registerOne(id, tool, state);
+		const tool = idOrToolOrTools
+		const id = tool.name
+		const state: ToolAvailability = typeof maybeTool === 'string' ? maybeTool : 'active'
+
+		this.registerOne(id, tool, state)
 	}
 
-	private registerOne(
-		id: string,
-		tool: ToolDefinition,
-		state: ToolAvailability,
-	): void {
+	private registerOne(id: string, tool: ToolDefinition, state: ToolAvailability): void {
 		if (this.has(id)) {
-			this.log.warn(`Tool "${id}" is already registered, overwriting.`);
+			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})`);
+		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);
+		this.availability.delete(id)
+		return super.unregister(id)
 	}
 
 	override clear(): void {
-		this.availability.clear();
-		super.clear();
+		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}`);
+			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}`);
+			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");
+			if (this.getAvailability(name) === 'active') {
+				this.availability.set(name, 'suspended')
 			}
 		}
-		this.log.info("All active tools suspended");
+		this.log.info('All active tools suspended')
 	}
 
 	hasSuspended(): boolean {
 		for (const state of this.availability.values()) {
-			if (state === "suspended") return true;
+			if (state === 'suspended') return true
 		}
-		return false;
+		return false
 	}
 
 	getAvailability(name: string): ToolAvailability {
-		return this.availability.get(name) ?? "active";
+		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),
-		);
+		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);
+		const tool = this.get(name)
 		if (!tool) {
-			throw new Error(
-				`Tool not found: "${name}". Available tools: ${this.listIds().join(", ")}`,
-			);
+			throw new Error(`Tool not found: "${name}". Available tools: ${this.listIds().join(', ')}`)
 		}
-		return tool;
+		return tool
 	}
 
 	listNames(): string[] {
-		return this.listIds();
+		return this.listIds()
 	}
 
 	toPromptSection(toolNames?: string[]): string {
-		const active = this.getByAvailability(["active"], toolNames);
-		const deferred = this.getByAvailability(["deferred"], toolNames);
+		const active = this.getByAvailability(['active'], toolNames)
+		const deferred = this.getByAvailability(['deferred'], toolNames)
 
-		const parts: string[] = [];
+		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>`);
+			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");
+			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");
+		if (parts.length === 0) return ''
+		return parts.join('\n\n')
 	}
 
 	toLLMTools(toolNames?: string[]): LLMToolSchema[] {
-		const toolsToConvert = this.getByAvailability(
-			["active", "suspended"],
-			toolNames,
-		);
+		const toolsToConvert = this.getByAvailability(['active', 'suspended'], toolNames)
 
 		return toolsToConvert.map((tool) => ({
-			type: "function" as const,
+			type: 'function' as const,
 			function: {
 				name: tool.name,
 				description: tool.description,
 				parameters: zodToJsonSchema(tool.inputSchema, {
-					target: "jsonSchema7",
-					$refStrategy: "none",
+					target: 'jsonSchema7',
+					$refStrategy: 'none',
 				}) as Record<string, unknown>,
 			},
-		}));
+		}))
 	}
 
 	getCallableTools(toolNames?: string[]): ToolDefinition[] {
-		return this.getByAvailability(["active"], toolNames);
+		return this.getByAvailability(['active'], toolNames)
 	}
 
 	async execute(
@@ -193,131 +181,122 @@ export class ToolRegistry extends Registry<ToolDefinition> {
 		rawInput: unknown,
 		context: ToolContext,
 	): Promise<ToolExecutionResult> {
-		const tracer = getTracer();
+		const tracer = getTracer()
 
 		return tracer.startActiveSpan(toolSpanName(toolName), async (span) => {
 			span.setAttributes({
 				[GENAI.TOOL_NAME]: toolName,
-				[GENAI.TOOL_TYPE]: "function",
-			});
+				[GENAI.TOOL_TYPE]: 'function',
+			})
 
-			const tool = this.getOrThrow(toolName);
+			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);
+			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();
+				})
+				span.setStatus({ code: SpanStatusCode.ERROR, message: msg })
+				span.end()
 				return {
 					success: false,
-					output: "",
+					output: '',
 					error: msg,
-				};
+				}
 			}
 
-			const mode = context.permissionContext?.mode ?? "auto";
-			if (mode === "plan") {
-				const isReadOnly = tool.isReadOnly ? tool.isReadOnly(rawInput) : false;
+			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`;
+					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();
+					})
+					span.setStatus({ code: SpanStatusCode.ERROR, message: msg })
+					span.end()
 					return {
 						success: false,
-						output: "",
+						output: '',
 						error: msg,
 						permissionDenied: true,
 						permissionMessage: msg,
-					};
+					}
 				}
 			}
 
-			const parseResult = tool.inputSchema.safeParse(rawInput);
+			const parseResult = tool.inputSchema.safeParse(rawInput)
 			if (!parseResult.success) {
 				const errorMessage = parseResult.error.issues
-					.map((i) => `${i.path.join(".")}: ${i.message}`)
-					.join("; ");
+					.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();
+				})
+				span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage })
+				span.end()
 
 				return {
 					success: false,
-					output: "",
+					output: '',
 					error: `Invalid input for tool "${toolName}": ${errorMessage}`,
-				};
+				}
 			}
 
-			const finalInput = parseResult.data;
+			const finalInput = parseResult.data
 
 			try {
-				this.log.debug(`Executing tool: ${toolName}`);
-				const result = await tool.execute(finalInput, context);
+				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);
+				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 });
+					span.setAttribute(NAMZU.TOOL_ERROR, result.error)
+					span.setStatus({ code: SpanStatusCode.ERROR, message: result.error })
 				} else {
-					span.setStatus({ code: SpanStatusCode.OK });
+					span.setStatus({ code: SpanStatusCode.OK })
 				}
 
-				return result;
+				return result
 			} catch (err) {
-				const errorMessage = toErrorMessage(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),
-				);
+				})
+				span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage })
+				span.recordException(err instanceof Error ? err : new Error(errorMessage))
 
 				return {
 					success: false,
-					output: "",
+					output: '',
 					error: `Tool "${toolName}" execution failed: ${errorMessage}`,
-				};
+				}
 			} finally {
-				span.end();
+				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)),
-		);
+	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

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