@namzu/sdk 0.1.1

package/src/index.ts

@@ -0,0 +1,218 @@
+export { VERSION } from "./version.js";
+export { RuntimeConfigSchema, RUNTIME_DEFAULTS } from "./config/runtime.js";
+export type { RuntimeConfig } from "./config/runtime.js";
+
+export * from "./contracts/index.js";
+
+export * from "./types/ids/index.js";
+export * from "./types/message/index.js";
+export * from "./types/common/index.js";
+export * from "./types/tool/index.js";
+export * from "./types/permission/index.js";
+export * from "./types/run/index.js";
+export * from "./types/provider/index.js";
+export * from "./types/agent/index.js";
+export * from "./types/decision/index.js";
+export * from "./types/persona/index.js";
+export * from "./types/activity/index.js";
+export * from "./types/task/index.js";
+export * from "./types/plan/index.js";
+export * from "./types/hitl/index.js";
+export * from "./types/rag/index.js";
+export * from "./types/telemetry/index.js";
+export * from "./types/execution/index.js";
+export * from "./types/connector/index.js";
+export * from "./types/skills/index.js";
+export * from "./types/a2a/index.js";
+export * from "./types/conversation/index.js";
+
+export {
+	assembleSystemPrompt,
+	mergePersonas,
+	withSessionContext,
+} from "./persona/index.js";
+export {
+	SkillRegistry,
+	resolveSkillChain,
+	loadSkill,
+	discoverSkills,
+} from "./skills/index.js";
+
+export * from "./utils/id.js";
+export * from "./utils/cost.js";
+export * from "./utils/error.js";
+export * from "./utils/logger.js";
+export { hashToolResult, buildToolResultHashes } from "./utils/hash.js";
+export { createChildAbortController } from "./utils/abort.js";
+export { memoizeAsync } from "./utils/memoize.js";
+export { extractFinalResponse } from "./utils/conversation.js";
+
+export { query, drainQuery } from "./runtime/query/index.js";
+export type { QueryParams } from "./runtime/query/index.js";
+export { ContextCache } from "./runtime/query/context-cache.js";
+export type { ContextCacheConfig, PromptCacheInput } from "./runtime/query/context-cache.js";
+export { CheckpointManager } from "./runtime/query/checkpoint.js";
+export { DecisionParser } from "./runtime/decision/parser.js";
+export { FallbackResolver } from "./runtime/decision/fallback.js";
+export { createRunReporter, createSessionReporter } from "./run/reporter.js";
+export type { RunReporter, SessionReporter } from "./run/reporter.js";
+
+export {
+	AbstractAgent,
+	ReactiveAgent,
+	PipelineAgent,
+	RouterAgent,
+	SupervisorAgent,
+	defineAgent,
+} from "./agents/index.js";
+export type { DefineAgentOptions } from "./agents/index.js";
+
+export { InMemoryStore } from "./store/InMemoryStore.js";
+export type { Identifiable, Timestamped } from "./store/InMemoryStore.js";
+
+export { Registry } from "./registry/Registry.js";
+export { ManagedRegistry } from "./registry/ManagedRegistry.js";
+export type { ManagedRegistryConfig } from "./registry/ManagedRegistry.js";
+export { AgentRegistry } from "./registry/agent/definitions.js";
+
+export { RunPersistence } from "./manager/run/persistence.js";
+export { RunDiskStore } from "./store/run/disk.js";
+export { SessionStore } from "./store/run/disk.js";
+
+export { ActivityStore } from "./store/activity/memory.js";
+export type { ActivityEvent, ActivityEventListener } from "./store/activity/memory.js";
+export { InMemoryTaskStore } from "./store/task/memory.js";
+export { DiskTaskStore } from "./store/task/disk.js";
+export type { DiskTaskStoreConfig } from "./store/task/disk.js";
+export { buildTaskTools, buildTaskCreateTool, buildTaskUpdateTool, buildTaskListTool } from "./tools/task/index.js";
+export { InMemoryConversationStore } from "./store/conversation/memory.js";
+export type { InMemoryConversationStoreConfig } from "./store/conversation/memory.js";
+export { PlanManager } from "./manager/plan/lifecycle.js";
+export type {
+	PlanEvent,
+	PlanEventListener,
+	PlanApprovalHandler,
+} from "./manager/plan/lifecycle.js";
+export { AgentManager } from "./manager/agent/lifecycle.js";
+export { LocalTaskGateway } from "./gateway/local.js";
+
+export {
+	OpenRouterProvider,
+	BedrockProvider,
+	ProviderFactory,
+	MockLLMProvider,
+	UnknownProviderError,
+} from "./provider/index.js";
+
+export { defineTool } from "./tools/defineTool.js";
+export type { DefineToolOptions } from "./tools/defineTool.js";
+export { ToolRegistry } from "./registry/tool/execute.js";
+export type { ToolExecutionResult } from "./registry/tool/execute.js";
+export { getBuiltinTools } from "./tools/builtins/index.js";
+export { ReadFileTool } from "./tools/builtins/read-file.js";
+export { WriteFileTool } from "./tools/builtins/write-file.js";
+export { BashTool } from "./tools/builtins/bash.js";
+export { GlobTool } from "./tools/builtins/glob.js";
+export { SearchToolsTool } from "./tools/builtins/search-tools.js";
+
+export {
+	TextChunker,
+	DEFAULT_CHUNKING_CONFIG,
+	OpenRouterEmbeddingProvider,
+	InMemoryVectorStore,
+	cosineSimilarity,
+	DefaultRetriever,
+	DEFAULT_RETRIEVAL_CONFIG,
+	DefaultIngestionPipeline,
+	assembleRAGContext,
+	DEFAULT_RAG_CONTEXT_CONFIG,
+	DefaultKnowledgeBase,
+	createRAGTool,
+} from "./rag/index.js";
+
+export {
+	BaseConnector,
+	ConnectorRegistry,
+	ConnectorManager,
+	HttpConnector,
+	WebhookConnector,
+	ScopedConnectorRegistry,
+	TenantConnectorManager,
+	EnvironmentConnectorManager,
+	BaseExecutionContext,
+	LocalExecutionContext,
+	RemoteExecutionContext,
+	HybridExecutionContext,
+	ExecutionContextFactory,
+	StdioTransport,
+	HttpSseTransport,
+	MCPClient,
+	mcpToolToToolDefinition,
+	toolDefinitionToMCPTool,
+	mcpJsonSchemaToZod,
+	zodToMCPJsonSchema,
+	mcpToolResultToToolResult,
+	toolResultToMCPToolResult,
+	MCPToolDiscovery,
+	MCPConnectorBridge,
+	MCPServer,
+} from "./connector/index.js";
+export type {
+	ConnectorManagerConfig,
+	TenantConnectorManagerConfig,
+	EnvironmentConnectorSetup,
+	EnvironmentConnectorManagerConfig,
+	LocalExecutionContextOptions,
+	RemoteExecutionContextOptions,
+	HybridExecutionContextOptions,
+	MCPServerToolProvider,
+	MCPServerResourceProvider,
+} from "./connector/index.js";
+
+export {
+	createConnectorExecuteTool,
+	createConnectorListTool,
+	createConnectorTools,
+	connectorMethodToTool,
+	connectorInstanceToTools,
+	allConnectorTools,
+	createConnectorRouterTool,
+	ConnectorToolRouter,
+} from "./bridge/tools/connector/index.js";
+export type {
+	ConnectorToolConfig,
+	ConnectorRouterInput,
+	ConnectorToolStrategy,
+	ConnectorToolRouterConfig,
+} from "./bridge/tools/connector/index.js";
+
+export {
+	buildAgentCard,
+	runToA2ATask,
+	isTerminalState,
+	runStatusToA2AState,
+	a2aMessageToCreateRun,
+	messageToA2A,
+	threadMessageToA2A,
+	extractTextFromA2AMessage,
+	a2aMessageToInput,
+	mapRunToA2AEvent,
+	mapSessionToA2AEvent,
+} from "./bridge/a2a/index.js";
+export type { CreateRunFromA2A } from "./bridge/a2a/index.js";
+
+export { mapRunToStreamEvent, mapSessionToStreamEvent } from "./bridge/sse/index.js";
+export type { MappedStreamEvent } from "./bridge/sse/index.js";
+
+export { InMemoryCredentialVault } from "./vault/index.js";
+
+export {
+	TelemetryProvider,
+	initTelemetry,
+	getTelemetry,
+	getTracer,
+	getMeter,
+	createPlatformMetrics,
+} from "./telemetry/index.js";
+export type { PlatformMetrics } from "./telemetry/index.js";
+export * from "./telemetry/attributes.js";

package/src/manager/agent/index.ts

@@ -0,0 +1 @@
+export { AgentManager } from "./lifecycle.js";

package/src/manager/agent/lifecycle.ts

@@ -0,0 +1,429 @@
+import type { AgentRegistry } from "../../registry/agent/definitions.js";
+import type {
+	BaseAgentConfig,
+	BaseAgentResult,
+} from "../../types/agent/base.js";
+import type {
+	AgentLifecycleEvent,
+	AgentLifecycleListener,
+} from "../../types/agent/lifecycle-event.js";
+import type {
+	AgentManagerConfig,
+	AgentTask,
+	AgentTaskContext,
+	AgentTaskState,
+	SendMessageOptions,
+} from "../../types/agent/task.js";
+import {
+	AGENT_MANAGER_DEFAULTS,
+	isTerminalAgentTaskState,
+} from "../../types/agent/task.js";
+import { EMPTY_TOKEN_USAGE } from "../../types/common/index.js";
+import type { RunId, TaskId } from "../../types/ids/index.js";
+import type { Message } from "../../types/message/index.js";
+import { createChildAbortController } from "../../utils/abort.js";
+import { ZERO_COST } from "../../utils/cost.js";
+import { toErrorMessage } from "../../utils/error.js";
+import { generateTaskId } from "../../utils/id.js";
+import { type Logger, getRootLogger } from "../../utils/logger.js";
+
+export class AgentManager {
+	private registry: AgentRegistry;
+	private instances: Map<TaskId, AgentTask> = new Map();
+	private completionCallbacks: Map<TaskId, Array<() => void>> = new Map();
+	private listeners: AgentLifecycleListener[] = [];
+	private log: Logger;
+	private config: Readonly<AgentManagerConfig>;
+	private evictionTimers: Map<TaskId, ReturnType<typeof setTimeout>> =
+		new Map();
+
+	constructor(registry: AgentRegistry, config?: Partial<AgentManagerConfig>) {
+		this.registry = registry;
+		this.config = { ...AGENT_MANAGER_DEFAULTS, ...config };
+		this.log = getRootLogger().child({ component: "AgentManager" });
+	}
+
+	async sendMessage(
+		options: SendMessageOptions,
+		context: AgentTaskContext,
+		listener?: import("../../types/run/events.js").RunEventListener,
+	): Promise<AgentTask> {
+		if (context.depth >= this.config.maxDepth) {
+			throw new Error(
+				`Max task depth ${this.config.maxDepth} exceeded (current: ${context.depth}). Recursive agent delegation is limited to prevent resource exhaustion.`,
+			);
+		}
+
+		const agent = this.registry.resolve(options.agentId);
+
+		const childAbortController = createChildAbortController(
+			context.parentAbortController,
+		);
+
+		const maxAllocation = Math.floor(
+			context.budgetTracker.remaining * this.config.maxBudgetFraction,
+		);
+		const allocatedTokens = Math.min(
+			options.budgetAllocation?.tokenBudget ?? maxAllocation,
+			maxAllocation,
+		);
+		context.budgetTracker.remaining -= allocatedTokens;
+
+		const taskId = generateTaskId();
+		const agentTask: AgentTask = {
+			taskId,
+			agentId: options.agentId,
+			agent,
+			childAbortController,
+			context,
+			state: "pending",
+			pendingMessages: [],
+			createdAt: Date.now(),
+			runEventListener: listener,
+		};
+
+		this.instances.set(taskId, agentTask);
+		this.emit({
+			type: "pending",
+			taskId,
+			agentId: options.agentId,
+			parentAgentId: context.parentAgentId,
+			depth: context.depth,
+		});
+
+		if (listener) {
+			listener({
+				type: "agent_pending",
+				runId: context.parentRunId,
+				taskId,
+				parentAgentId: context.parentAgentId,
+				childAgentId: options.agentId,
+				depth: context.depth,
+			});
+		}
+		this.log.info(
+			`Agent task pending: ${taskId} (${options.agentId}, depth=${context.depth})`,
+		);
+
+		const definition = this.registry.getOrThrow(options.agentId);
+		let childConfig: BaseAgentConfig;
+		if (definition.configBuilder && context.factoryOptions) {
+			childConfig = await definition.configBuilder({
+				...context.factoryOptions,
+				tokenBudget: allocatedTokens,
+				timeoutMs:
+					options.budgetAllocation?.timeoutMs ??
+					context.budgetTracker.remaining,
+				threadId: context.threadId as string | undefined,
+				parentRunId: context.parentRunId as string | undefined,
+				depth: context.depth + 1,
+				...options.configOverrides,
+			});
+
+			if (!childConfig.contextLevel && definition.contextLevel) {
+				childConfig.contextLevel = definition.contextLevel;
+			}
+		} else {
+			this.log.warn("No configBuilder or factoryOptions, using bare config", {
+				agentId: options.agentId,
+			});
+			childConfig = {
+				model: options.configOverrides?.model ?? "default",
+				tokenBudget: allocatedTokens,
+				timeoutMs:
+					options.budgetAllocation?.timeoutMs ??
+					context.budgetTracker.remaining,
+				temperature: options.configOverrides?.temperature,
+				maxIterations: options.configOverrides?.maxIterations,
+				maxResponseTokens: options.configOverrides?.maxResponseTokens,
+				env: options.configOverrides?.env,
+				threadId: context.threadId,
+				parentRunId: context.parentRunId,
+				depth: context.depth + 1,
+			};
+		}
+
+		this.runChild(agentTask, options, childConfig, listener).catch((err) => {
+			this.markFailed(taskId, toErrorMessage(err));
+		});
+
+		return agentTask;
+	}
+
+	cancel(taskId: TaskId): void {
+		const agentTask = this.instances.get(taskId);
+		if (!agentTask || isTerminalAgentTaskState(agentTask.state)) return;
+
+		agentTask.childAbortController.abort("canceled");
+		this.markCanceled(taskId);
+	}
+
+	cancelAll(parentRunId: RunId): void {
+		for (const agentTask of this.listByParent(parentRunId)) {
+			this.cancel(agentTask.taskId);
+		}
+	}
+
+	async continueTask(taskId: TaskId, message: string): Promise<void> {
+		const agentTask = this.requireInstance(taskId);
+		if (isTerminalAgentTaskState(agentTask.state)) {
+			throw new Error(
+				`Cannot continue terminal task: ${taskId} (state: ${agentTask.state})`,
+			);
+		}
+		agentTask.pendingMessages.push({
+			role: "user" as const,
+			content: message,
+		} as Message);
+		this.log.info(`Message queued for task ${taskId} via continueTask`);
+	}
+
+	queueMessage(taskId: TaskId, message: Message): void {
+		const agentTask = this.requireInstance(taskId);
+		agentTask.pendingMessages.push(message);
+	}
+
+	drainMessages(taskId: TaskId): Message[] {
+		const agentTask = this.requireInstance(taskId);
+		const messages = [...agentTask.pendingMessages];
+		agentTask.pendingMessages.length = 0;
+		return messages;
+	}
+
+	waitForCompletion(taskId: TaskId): Promise<void> {
+		const agentTask = this.instances.get(taskId);
+		if (!agentTask) {
+			return Promise.reject(new Error(`Agent task not found: "${taskId}"`));
+		}
+		if (isTerminalAgentTaskState(agentTask.state)) {
+			return Promise.resolve();
+		}
+		return new Promise<void>((resolve) => {
+			const existing = this.completionCallbacks.get(taskId) ?? [];
+			existing.push(resolve);
+			this.completionCallbacks.set(taskId, existing);
+		});
+	}
+
+	getInstance(taskId: TaskId): AgentTask | undefined {
+		return this.instances.get(taskId);
+	}
+
+	listByParent(parentRunId: RunId): AgentTask[] {
+		return Array.from(this.instances.values()).filter(
+			(t) => t.context.parentRunId === parentRunId,
+		);
+	}
+
+	listActive(): AgentTask[] {
+		return Array.from(this.instances.values()).filter(
+			(t) => !isTerminalAgentTaskState(t.state),
+		);
+	}
+
+	getState(taskId: TaskId): AgentTaskState | undefined {
+		return this.instances.get(taskId)?.state;
+	}
+
+	getRegistry(): AgentRegistry {
+		return this.registry;
+	}
+
+	on(listener: AgentLifecycleListener): void {
+		this.listeners.push(listener);
+	}
+
+	off(listener: AgentLifecycleListener): void {
+		const index = this.listeners.indexOf(listener);
+		if (index >= 0) this.listeners.splice(index, 1);
+	}
+
+	cleanup(): void {
+		for (const [taskId, agentTask] of this.instances) {
+			if (isTerminalAgentTaskState(agentTask.state)) {
+				this.clearEvictionTimer(taskId);
+				this.instances.delete(taskId);
+			}
+		}
+	}
+
+	dispose(): void {
+		for (const taskId of this.instances.keys()) {
+			this.clearEvictionTimer(taskId);
+		}
+		this.cancelAll("" as RunId);
+		this.instances.clear();
+		this.listeners.length = 0;
+	}
+
+	private async runChild(
+		agentTask: AgentTask,
+		options: SendMessageOptions,
+		childConfig: BaseAgentConfig,
+		listener?: import("../../types/run/events.js").RunEventListener,
+	): Promise<void> {
+		this.updateState(agentTask.taskId, "running");
+		this.emit({ type: "running", taskId: agentTask.taskId });
+
+		const input = {
+			...options.input,
+			signal: agentTask.childAbortController.signal,
+		};
+
+		const childListener = listener
+			? async (
+					event: import("../../types/run/events.js").RunEvent,
+				): Promise<void> => {
+					const annotated = Object.assign({}, event, {
+						sourceAgentId: agentTask.agentId,
+						parentTaskId: agentTask.taskId,
+					});
+					await listener(
+						annotated as import("../../types/run/events.js").RunEvent,
+					);
+				}
+			: undefined;
+
+		const result = await agentTask.agent.run(input, childConfig, childListener);
+		this.markCompleted(agentTask.taskId, result);
+	}
+
+	private markCompleted(taskId: TaskId, result: BaseAgentResult): void {
+		const agentTask = this.instances.get(taskId);
+		if (!agentTask || isTerminalAgentTaskState(agentTask.state)) return;
+
+		agentTask.result = result;
+		agentTask.completedAt = Date.now();
+		this.updateState(taskId, "completed");
+		this.emit({ type: "completed", taskId, result });
+		this.emitRunEvent(agentTask, {
+			type: "agent_completed",
+			runId: agentTask.context.parentRunId,
+			taskId,
+			result,
+		});
+		this.log.info(`Agent task completed: ${taskId}`);
+		this.scheduleEviction(taskId);
+		this.resolveCompletionCallbacks(taskId);
+	}
+
+	private markFailed(taskId: TaskId, error: string): void {
+		const agentTask = this.instances.get(taskId);
+		if (!agentTask || isTerminalAgentTaskState(agentTask.state)) return;
+
+		agentTask.result = {
+			runId: agentTask.context.parentRunId,
+			status: "failed",
+			usage: { ...EMPTY_TOKEN_USAGE },
+			cost: { ...ZERO_COST },
+			iterations: 0,
+			durationMs: Date.now() - agentTask.createdAt,
+			messages: [],
+			lastError: error,
+		};
+		agentTask.completedAt = Date.now();
+		this.updateState(taskId, "failed");
+		this.emit({ type: "failed", taskId, error });
+		this.emitRunEvent(agentTask, {
+			type: "agent_failed",
+			runId: agentTask.context.parentRunId,
+			taskId,
+			error,
+		});
+		this.log.error(`Agent task failed: ${taskId}`, { error });
+		this.scheduleEviction(taskId);
+		this.resolveCompletionCallbacks(taskId);
+	}
+
+	private markCanceled(taskId: TaskId): void {
+		const agentTask = this.instances.get(taskId);
+		if (!agentTask || isTerminalAgentTaskState(agentTask.state)) return;
+
+		agentTask.completedAt = Date.now();
+		this.updateState(taskId, "canceled");
+		this.emit({ type: "canceled", taskId });
+		this.emitRunEvent(agentTask, {
+			type: "agent_canceled",
+			runId: agentTask.context.parentRunId,
+			taskId,
+		});
+		this.log.info(`Agent task canceled: ${taskId}`);
+		this.scheduleEviction(taskId);
+		this.resolveCompletionCallbacks(taskId);
+	}
+
+	private updateState(taskId: TaskId, state: AgentTaskState): void {
+		const agentTask = this.instances.get(taskId);
+		if (agentTask) {
+			agentTask.state = state;
+		}
+	}
+
+	private requireInstance(taskId: TaskId): AgentTask {
+		const agentTask = this.instances.get(taskId);
+		if (!agentTask) {
+			throw new Error(`Agent task not found: "${taskId}"`);
+		}
+		return agentTask;
+	}
+
+	private scheduleEviction(taskId: TaskId): void {
+		const agentTask = this.instances.get(taskId);
+		if (!agentTask) return;
+
+		agentTask.evictAfter = Date.now() + this.config.evictionMs;
+
+		const timer = setTimeout(() => {
+			this.instances.delete(taskId);
+			this.evictionTimers.delete(taskId);
+			this.log.info(`Agent task evicted: ${taskId}`);
+		}, this.config.evictionMs);
+
+		this.evictionTimers.set(taskId, timer);
+	}
+
+	private resolveCompletionCallbacks(taskId: TaskId): void {
+		const callbacks = this.completionCallbacks.get(taskId);
+		if (callbacks) {
+			for (const resolve of callbacks) resolve();
+			this.completionCallbacks.delete(taskId);
+		}
+	}
+
+	private clearEvictionTimer(taskId: TaskId): void {
+		const timer = this.evictionTimers.get(taskId);
+		if (timer) {
+			clearTimeout(timer);
+			this.evictionTimers.delete(taskId);
+		}
+	}
+
+	private emit(event: AgentLifecycleEvent): void {
+		for (const listener of this.listeners) {
+			try {
+				listener(event);
+			} catch (err) {
+				this.log.error("Agent lifecycle listener error", {
+					eventType: event.type,
+					error: toErrorMessage(err),
+				});
+			}
+		}
+	}
+
+	private emitRunEvent(
+		agentTask: AgentTask,
+		event: import("../../types/run/events.js").RunEvent,
+	): void {
+		if (!agentTask.runEventListener) return;
+		try {
+			agentTask.runEventListener(event);
+		} catch (err) {
+			this.log.error("RunEvent emission error", {
+				eventType: event.type,
+				taskId: agentTask.taskId,
+				error: toErrorMessage(err),
+			});
+		}
+	}
+}