@lssm/lib.ai-agent 0.0.0-canary-20251207013726 → 0.0.0-canary-20251207123819

package/dist/schema/schema-output.d.ts

@@ -1,76 +0,0 @@
-import { Output } from "ai";
-import { ZodType } from "zod";
-
-//#region src/schema/schema-output.d.ts
-
-/**
- * Bridge between ContractSpec SchemaModel and AI SDK Output.
- *
- * This module provides utilities to convert ContractSpec schema definitions
- * to AI SDK v6 Output.* structured output configurations.
- */
-type ObjectOutputReturn = ReturnType<typeof Output.object>;
-type ArrayOutputReturn = ReturnType<typeof Output.array>;
-type ChoiceOutputReturn = ReturnType<typeof Output.choice>;
-type TextOutputReturn = ReturnType<typeof Output.text>;
-/**
- * Create an AI SDK Output.object from a JSON Schema.
- *
- * @param schema - JSON Schema object
- * @returns AI SDK Output configuration
- */
-declare function jsonSchemaToOutput(schema: Record<string, unknown>): ObjectOutputReturn;
-/**
- * Create an AI SDK Output.array from a JSON Schema items definition.
- *
- * @param itemSchema - JSON Schema for array items
- * @returns AI SDK Output configuration
- */
-declare function jsonSchemaToArrayOutput(itemSchema: Record<string, unknown>): ArrayOutputReturn;
-/**
- * Create an AI SDK Output.choice from enum values.
- *
- * @param choices - Array of choice values
- * @returns AI SDK Output configuration
- */
-declare function enumToChoiceOutput(choices: string[]): ChoiceOutputReturn;
-/**
- * Create an AI SDK Output from a Zod schema directly.
- *
- * @param schema - Zod schema
- * @returns AI SDK Output configuration
- */
-declare function zodToOutput<T extends ZodType>(schema: T): ObjectOutputReturn;
-/**
- * Create a simple text output configuration.
- *
- * @returns AI SDK Output configuration for text
- */
-declare function textOutput(): TextOutputReturn;
-/**
- * Output builder that can be used fluently.
- */
-declare const SchemaOutput: {
-  /**
-   * Create an object output from JSON Schema.
-   */
-  readonly fromJsonSchema: typeof jsonSchemaToOutput;
-  /**
-   * Create an array output from JSON Schema.
-   */
-  readonly arrayFromJsonSchema: typeof jsonSchemaToArrayOutput;
-  /**
-   * Create a choice output from enum.
-   */
-  readonly fromEnum: typeof enumToChoiceOutput;
-  /**
-   * Create an output from Zod schema.
-   */
-  readonly fromZod: typeof zodToOutput;
-  /**
-   * Create a text output.
-   */
-  readonly text: typeof textOutput;
-};
-//#endregion
-export { SchemaOutput, enumToChoiceOutput, jsonSchemaToArrayOutput, jsonSchemaToOutput, textOutput, zodToOutput };

package/dist/session/index.d.ts

@@ -1,2 +0,0 @@
-import { AgentSessionStore, InMemorySessionStore, createInMemorySessionStore, generateSessionId } from "./store.js";
-export { AgentSessionStore, InMemorySessionStore, createInMemorySessionStore, generateSessionId };

package/dist/session/store.d.ts

@@ -1,73 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

@@ -1,77 +0,0 @@
-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

@@ -1,129 +0,0 @@
-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

@@ -1,72 +0,0 @@
-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

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

package/dist/tools/index.d.ts

@@ -1,5 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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

@@ -1,58 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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

@@ -1,49 +0,0 @@
-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 };