@lssm/lib.ai-agent 0.0.0-canary-20251217052941 → 0.0.0-canary-20251217060433

package/dist/session/store.d.ts

@@ -0,0 +1,73 @@
+import { AgentSessionState } from "../types.js";
+import { ModelMessage, StepResult, ToolSet } from "ai";
+
+//#region src/session/store.d.ts
+
+/**
+ * Interface for persisting agent session state.
+ *
+ * Implementations can use in-memory storage, databases,
+ * or external services like Redis.
+ */
+interface AgentSessionStore {
+  /**
+   * Get a session by ID.
+   */
+  get(sessionId: string): Promise<AgentSessionState | null>;
+  /**
+   * Create a new session.
+   */
+  create(session: Omit<AgentSessionState, 'createdAt' | 'updatedAt'>): Promise<AgentSessionState>;
+  /**
+   * Append a step to a session.
+   */
+  appendStep(sessionId: string, step: StepResult<ToolSet>): Promise<void>;
+  /**
+   * Append a message to a session.
+   */
+  appendMessage(sessionId: string, message: ModelMessage): Promise<void>;
+  /**
+   * Update session properties.
+   */
+  update(sessionId: string, updates: Partial<Pick<AgentSessionState, 'status' | 'metadata'>>): Promise<void>;
+  /**
+   * Delete a session.
+   */
+  delete(sessionId: string): Promise<boolean>;
+  /**
+   * List sessions by agent ID.
+   */
+  listByAgent(agentId: string, limit?: number): Promise<AgentSessionState[]>;
+  /**
+   * List sessions by tenant ID.
+   */
+  listByTenant(tenantId: string, limit?: number): Promise<AgentSessionState[]>;
+}
+/**
+ * In-memory session store for development and testing.
+ */
+declare class InMemorySessionStore implements AgentSessionStore {
+  private readonly sessions;
+  get(sessionId: string): Promise<AgentSessionState | null>;
+  create(session: Omit<AgentSessionState, 'createdAt' | 'updatedAt'>): Promise<AgentSessionState>;
+  appendStep(sessionId: string, step: StepResult<ToolSet>): Promise<void>;
+  appendMessage(sessionId: string, message: ModelMessage): Promise<void>;
+  update(sessionId: string, updates: Partial<Pick<AgentSessionState, 'status' | 'metadata'>>): Promise<void>;
+  delete(sessionId: string): Promise<boolean>;
+  listByAgent(agentId: string, limit?: number): Promise<AgentSessionState[]>;
+  listByTenant(tenantId: string, limit?: number): Promise<AgentSessionState[]>;
+  /**
+   * Clear all sessions (for testing).
+   */
+  clear(): void;
+}
+/**
+ * Create an in-memory session store.
+ */
+declare function createInMemorySessionStore(): AgentSessionStore;
+/**
+ * Generate a unique session ID.
+ */
+declare function generateSessionId(): string;
+//#endregion
+export { AgentSessionStore, InMemorySessionStore, createInMemorySessionStore, generateSessionId };

package/dist/spec/index.d.ts

@@ -0,0 +1,3 @@
+import { AgentConfidencePolicy, AgentEscalationPolicy, AgentKnowledgeRef, AgentMemoryConfig, AgentMeta, AgentPolicy, AgentSpec, AgentToolConfig, agentKey, defineAgent } from "./spec.js";
+import { AgentRegistry, createAgentRegistry } from "./registry.js";
+export { AgentConfidencePolicy, AgentEscalationPolicy, AgentKnowledgeRef, AgentMemoryConfig, AgentMeta, AgentPolicy, AgentRegistry, AgentSpec, AgentToolConfig, agentKey, createAgentRegistry, defineAgent };

package/dist/spec/registry.d.ts

@@ -0,0 +1,77 @@
+import { AgentSpec } from "./spec.js";
+
+//#region src/spec/registry.d.ts
+
+/**
+ * Registry for managing agent specifications.
+ *
+ * Provides registration, lookup, and version management for agent specs.
+ */
+declare class AgentRegistry {
+  private readonly specs;
+  /**
+   * Register an agent specification.
+   *
+   * @param spec - The agent specification to register
+   * @returns This registry for chaining
+   * @throws Error if the spec is already registered
+   */
+  register(spec: AgentSpec): this;
+  /**
+   * Unregister an agent specification.
+   *
+   * @param name - Agent name
+   * @param version - Agent version
+   * @returns True if the spec was removed
+   */
+  unregister(name: string, version: number): boolean;
+  /**
+   * List all registered agent specifications.
+   */
+  list(): AgentSpec[];
+  /**
+   * List all unique agent names (without versions).
+   */
+  listNames(): string[];
+  /**
+   * Get an agent specification by name and optional version.
+   *
+   * @param name - Agent name
+   * @param version - Optional version. If omitted, returns the latest version.
+   * @returns The agent spec or undefined if not found
+   */
+  get(name: string, version?: number): AgentSpec | undefined;
+  /**
+   * Get an agent specification or throw if not found.
+   *
+   * @param name - Agent name
+   * @param version - Optional version
+   * @returns The agent spec
+   * @throws Error if the spec is not found
+   */
+  require(name: string, version?: number): AgentSpec;
+  /**
+   * Check if an agent is registered.
+   *
+   * @param name - Agent name
+   * @param version - Optional version
+   */
+  has(name: string, version?: number): boolean;
+  /**
+   * Get all versions of an agent.
+   *
+   * @param name - Agent name
+   * @returns Array of specs sorted by version (ascending)
+   */
+  getVersions(name: string): AgentSpec[];
+  /**
+   * Clear all registered specs.
+   */
+  clear(): void;
+}
+/**
+ * Create a new agent registry.
+ */
+declare function createAgentRegistry(): AgentRegistry;
+//#endregion
+export { AgentRegistry, createAgentRegistry };

package/dist/spec/spec.d.ts

@@ -0,0 +1,129 @@
+import { OwnerShipMeta } from "@lssm/lib.contracts/ownership";
+import { KnowledgeCategory } from "@lssm/lib.contracts/knowledge/spec";
+import { PolicyRef } from "@lssm/lib.contracts/policy/spec";
+
+//#region src/spec/spec.d.ts
+
+/**
+ * Metadata for an agent specification.
+ */
+interface AgentMeta extends OwnerShipMeta {
+  name: string;
+  version: number;
+}
+/**
+ * Configuration for a tool that an agent can use.
+ */
+interface AgentToolConfig {
+  /** Tool name (unique within the agent) */
+  name: string;
+  /** Human-readable description for the LLM */
+  description?: string;
+  /** JSON Schema fragment for tool parameters */
+  schema?: Record<string, unknown>;
+  /** Optional cooldown in milliseconds between invocations */
+  cooldownMs?: number;
+  /** Maximum execution time before timeout */
+  timeoutMs?: number;
+  /** Whether the tool can be executed without human approval (AI SDK needsApproval = !automationSafe) */
+  automationSafe?: boolean;
+  /** Explicit approval requirement (overrides automationSafe) */
+  requiresApproval?: boolean;
+  /** Optional policy guard that must evaluate to allow the tool call */
+  policy?: PolicyRef;
+}
+/**
+ * Reference to a knowledge space that the agent can access.
+ */
+interface AgentKnowledgeRef {
+  /** Knowledge space key */
+  key: string;
+  /** Optional specific version */
+  version?: number;
+  /** Filter by knowledge category */
+  category?: KnowledgeCategory;
+  /** Whether the knowledge is required (static injection) or optional (dynamic RAG) */
+  required?: boolean;
+  /** Additional instructions appended when the space is available */
+  instructions?: string;
+}
+/**
+ * Memory configuration for agent session persistence.
+ */
+interface AgentMemoryConfig {
+  /** Maximum entries to keep in memory */
+  maxEntries?: number;
+  /** Time-to-live in minutes */
+  ttlMinutes?: number;
+  /** Number of messages before triggering summarization */
+  summaryTrigger?: number;
+  /** Whether to persist to long-term storage */
+  persistLongTerm?: boolean;
+}
+/**
+ * Confidence policy for agent responses.
+ */
+interface AgentConfidencePolicy {
+  /** Minimum acceptable confidence before escalation. Defaults to 0.7 */
+  min?: number;
+  /** Default value used when provider does not report confidence */
+  default?: number;
+}
+/**
+ * Escalation policy for handling uncertain or failed agent responses.
+ */
+interface AgentEscalationPolicy {
+  /** Auto escalate when confidence < threshold */
+  confidenceThreshold?: number;
+  /** Escalate when a tool throws irrecoverable errors */
+  onToolFailure?: boolean;
+  /** Escalate when iteration budget exceeded */
+  onTimeout?: boolean;
+  /** Optional human approval workflow ID */
+  approvalWorkflow?: string;
+}
+/**
+ * Combined policy configuration for an agent.
+ */
+interface AgentPolicy {
+  confidence?: AgentConfidencePolicy;
+  escalation?: AgentEscalationPolicy;
+  /** Feature flags to apply to this agent */
+  flags?: string[];
+}
+/**
+ * Complete specification for a ContractSpec agent.
+ */
+interface AgentSpec {
+  meta: AgentMeta;
+  /** System instructions for the agent */
+  instructions: string;
+  /** Human-readable description */
+  description?: string;
+  /** Tags for categorization */
+  tags?: string[];
+  /** Tools the agent can use */
+  tools: AgentToolConfig[];
+  /** Memory/session configuration */
+  memory?: AgentMemoryConfig;
+  /** Knowledge spaces the agent can access */
+  knowledge?: AgentKnowledgeRef[];
+  /** Policy configuration */
+  policy?: AgentPolicy;
+  /** Maximum steps per generation (defaults to 10) */
+  maxSteps?: number;
+}
+/**
+ * Define and validate an agent specification.
+ *
+ * @param spec - The agent specification
+ * @returns The frozen, validated specification
+ * @throws Error if the specification is invalid
+ */
+declare function defineAgent(spec: AgentSpec): AgentSpec;
+/**
+ * Generate a unique key for an agent spec.
+ */
+declare function agentKey(meta: AgentMeta): string;
+//#endregion
+export { AgentConfidencePolicy, AgentEscalationPolicy, AgentKnowledgeRef, AgentMemoryConfig, AgentMeta, AgentPolicy, AgentSpec, AgentToolConfig, agentKey, defineAgent };

package/dist/telemetry/adapter.d.ts

@@ -0,0 +1,72 @@
+import { StepResult, ToolSet } from "ai";
+
+//#region src/telemetry/adapter.d.ts
+
+/**
+ * Metric sample compatible with @lssm/lib.evolution OperationMetricSample.
+ */
+interface OperationMetricSample {
+  operation: {
+    name: string;
+    version: number;
+  };
+  durationMs: number;
+  success: boolean;
+  timestamp: Date;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Interface for collecting telemetry metrics.
+ *
+ * Implementations can send metrics to:
+ * - @lssm/lib.evolution for self-improvement
+ * - PostHog for analytics
+ * - Custom monitoring systems
+ */
+interface TelemetryCollector {
+  /**
+   * Collect a metric sample.
+   */
+  collect(sample: OperationMetricSample): Promise<void>;
+}
+/**
+ * Track an agent step for telemetry.
+ *
+ * Called from ContractSpecAgent.onStepFinish to feed metrics
+ * to the evolution engine.
+ *
+ * @param collector - Telemetry collector
+ * @param agentId - Agent identifier (e.g., "support.bot.v1")
+ * @param step - AI SDK step result
+ * @param durationMs - Optional step duration in milliseconds
+ */
+declare function trackAgentStep(collector: TelemetryCollector, agentId: string, step: StepResult<ToolSet>, durationMs?: number): Promise<void>;
+/**
+ * In-memory telemetry collector for testing.
+ */
+declare class InMemoryTelemetryCollector implements TelemetryCollector {
+  private readonly samples;
+  collect(sample: OperationMetricSample): Promise<void>;
+  /**
+   * Get all collected samples.
+   */
+  getSamples(): OperationMetricSample[];
+  /**
+   * Get samples for a specific operation.
+   */
+  getSamplesForOperation(operationName: string): OperationMetricSample[];
+  /**
+   * Clear all samples.
+   */
+  clear(): void;
+}
+/**
+ * Create an in-memory telemetry collector.
+ */
+declare function createInMemoryTelemetryCollector(): InMemoryTelemetryCollector;
+/**
+ * No-op telemetry collector that discards all metrics.
+ */
+declare const noopTelemetryCollector: TelemetryCollector;
+//#endregion
+export { InMemoryTelemetryCollector, OperationMetricSample, TelemetryCollector, createInMemoryTelemetryCollector, noopTelemetryCollector, trackAgentStep };

package/dist/telemetry/index.d.ts

@@ -0,0 +1,2 @@
+import { InMemoryTelemetryCollector, OperationMetricSample, TelemetryCollector, createInMemoryTelemetryCollector, noopTelemetryCollector, trackAgentStep } from "./adapter.js";
+export { InMemoryTelemetryCollector, OperationMetricSample, TelemetryCollector, createInMemoryTelemetryCollector, noopTelemetryCollector, trackAgentStep };

package/dist/tools/index.d.ts

@@ -0,0 +1,5 @@
+import { buildToolHandlers, createToolHandler, specToolToAISDKTool, specToolsToAISDKTools } from "./tool-adapter.js";
+import { createKnowledgeQueryTool } from "./knowledge-tool.js";
+import { McpClientConfig, McpClientResult, createMcpToolsets, mcpServerToTools } from "./mcp-client.js";
+import { AgentMcpServerConfig, agentToMcpServer, createAgentMcpServer } from "./mcp-server.js";
+export { AgentMcpServerConfig, McpClientConfig, McpClientResult, agentToMcpServer, buildToolHandlers, createAgentMcpServer, createKnowledgeQueryTool, createMcpToolsets, createToolHandler, mcpServerToTools, specToolToAISDKTool, specToolsToAISDKTools };

package/dist/tools/knowledge-tool.d.ts

@@ -0,0 +1,20 @@
+import { AgentKnowledgeRef } from "../spec/spec.js";
+import { Tool } from "ai";
+import { KnowledgeRetriever } from "@lssm/lib.knowledge/retriever";
+
+//#region src/tools/knowledge-tool.d.ts
+
+/**
+ * Create a knowledge query tool for dynamic RAG.
+ *
+ * This tool allows the agent to query optional knowledge spaces
+ * at runtime. Required knowledge is injected statically via
+ * the knowledge injector.
+ *
+ * @param retriever - The knowledge retriever to use
+ * @param knowledgeRefs - Knowledge references from the agent spec
+ * @returns AI SDK CoreTool for knowledge queries
+ */
+declare function createKnowledgeQueryTool(retriever: KnowledgeRetriever, knowledgeRefs: AgentKnowledgeRef[]): Tool<any, any> | null;
+//#endregion
+export { createKnowledgeQueryTool };

package/dist/tools/mcp-client.d.ts

@@ -0,0 +1,58 @@
+import { Tool } from "ai";
+
+//#region src/tools/mcp-client.d.ts
+
+/**
+ * Configuration for connecting to an MCP server.
+ */
+interface McpClientConfig {
+  /** Display name for the MCP server */
+  name: string;
+  /** Command to spawn the MCP server process */
+  command: string;
+  /** Arguments to pass to the command */
+  args?: string[];
+  /** Environment variables for the process */
+  env?: Record<string, string>;
+}
+/**
+ * Result of creating an MCP client with tools.
+ */
+interface McpClientResult {
+  /** AI SDK tools from the MCP server */
+  tools: Record<string, Tool<unknown, unknown>>;
+  /** Cleanup function to close the connection */
+  cleanup: () => Promise<void>;
+}
+/**
+ * Create AI SDK tools from an MCP server.
+ *
+ * This adapter allows ContractSpec agents to consume tools
+ * from external MCP servers (e.g., filesystem, database, etc.).
+ *
+ * @param config - MCP server configuration
+ * @returns Tools and cleanup function
+ *
+ * @example
+ * ```typescript
+ * const { tools, cleanup } = await mcpServerToTools({
+ *   name: 'filesystem',
+ *   command: 'npx',
+ *   args: ['-y', '@modelcontextprotocol/server-filesystem', '/path'],
+ * });
+ *
+ * // Use tools in agent...
+ *
+ * await cleanup();
+ * ```
+ */
+declare function mcpServerToTools(config: McpClientConfig): Promise<McpClientResult>;
+/**
+ * Create multiple MCP tool sets from configurations.
+ *
+ * @param configs - Array of MCP server configurations
+ * @returns Combined tools and cleanup function
+ */
+declare function createMcpToolsets(configs: McpClientConfig[]): Promise<McpClientResult>;
+//#endregion
+export { McpClientConfig, McpClientResult, createMcpToolsets, mcpServerToTools };

package/dist/tools/mcp-server.d.ts

@@ -0,0 +1,45 @@
+import { AgentSpec } from "../spec/spec.js";
+import { ContractSpecAgent } from "../agent/contract-spec-agent.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/tools/mcp-server.d.ts
+
+/**
+ * Generate an MCP server that exposes a ContractSpec agent as a tool.
+ *
+ * This allows other AI agents (e.g., Claude Desktop, Cursor) to use
+ * your ContractSpec agents as tools, enabling agent-to-agent composition.
+ *
+ * @param agent - The ContractSpec agent to expose
+ * @param spec - The agent specification
+ * @returns MCP Server instance
+ *
+ * @example
+ * ```typescript
+ * const server = agentToMcpServer(myAgent, myAgentSpec);
+ *
+ * // Run via stdio transport
+ * const transport = new StdioServerTransport();
+ * await server.connect(transport);
+ * ```
+ */
+declare function agentToMcpServer(agent: ContractSpecAgent, spec: AgentSpec): McpServer;
+/**
+ * Configuration for running an agent as an MCP server.
+ */
+interface AgentMcpServerConfig {
+  /** The agent to expose */
+  agent: ContractSpecAgent;
+  /** The agent specification */
+  spec: AgentSpec;
+  /** Optional server name override */
+  name?: string;
+  /** Optional version override */
+  version?: string;
+}
+/**
+ * Create an MCP server from configuration.
+ */
+declare function createAgentMcpServer(config: AgentMcpServerConfig): McpServer;
+//#endregion
+export { AgentMcpServerConfig, agentToMcpServer, createAgentMcpServer };

package/dist/tools/tool-adapter.d.ts

@@ -0,0 +1,49 @@
+import { AgentToolConfig } from "../spec/spec.js";
+import { ToolExecutionContext, ToolHandler } from "../types.js";
+import { Tool } from "ai";
+
+//#region src/tools/tool-adapter.d.ts
+
+/**
+ * Convert ContractSpec AgentToolConfig to AI SDK CoreTool.
+ *
+ * @param specTool - The tool configuration from AgentSpec
+ * @param handler - The handler function for the tool
+ * @param context - Partial context to inject into handler calls
+ * @returns AI SDK CoreTool
+ */
+declare function specToolToAISDKTool(specTool: AgentToolConfig, handler: ToolHandler, context?: Partial<ToolExecutionContext>): Tool<any, any>;
+/**
+ * Convert multiple ContractSpec tool configs to AI SDK tools.
+ *
+ * @param specTools - Array of tool configurations
+ * @param handlers - Map of tool name to handler function
+ * @param context - Partial context to inject into handler calls
+ * @returns Record of AI SDK tools keyed by name
+ */
+declare function specToolsToAISDKTools(specTools: AgentToolConfig[], handlers: Map<string, ToolHandler>, context?: Partial<ToolExecutionContext>): Record<string, Tool<any, any>>;
+/**
+ * Type-safe tool handler builder.
+ *
+ * @example
+ * ```typescript
+ * const handler = createToolHandler<{ query: string }>((input, ctx) => {
+ *   return `Searched for: ${input.query}`;
+ * });
+ * ```
+ */
+declare function createToolHandler<TInput = unknown, TOutput = string>(handler: (input: TInput, context: ToolExecutionContext) => Promise<TOutput> | TOutput): ToolHandler<TInput, TOutput>;
+/**
+ * Build a tool handlers map from an object.
+ *
+ * @example
+ * ```typescript
+ * const handlers = buildToolHandlers({
+ *   search: async (input: { query: string }) => `Found: ${input.query}`,
+ *   calculate: async (input: { a: number, b: number }) => `${input.a + input.b}`,
+ * });
+ * ```
+ */
+declare function buildToolHandlers(handlersObj: Record<string, ToolHandler>): Map<string, ToolHandler>;
+//#endregion
+export { buildToolHandlers, createToolHandler, specToolToAISDKTool, specToolsToAISDKTools };