@lssm/lib.ai-agent 0.0.0-canary-20251206160926

package/README.md

@@ -0,0 +1,41 @@
+# @lssm/lib.ai-agent
+
+**AI governance for ContractSpec** — Constrain what AI agents can change, enforce contracts they must respect.
+
+Stateful AI agent orchestration with type-safe specs, tool execution, knowledge bindings, and per-tenant guardrails. Agents read contracts as their source of truth, enabling triage, growth experiments, and DevOps automation with contract-enforced safety.
+
+## Features
+
+- Type-safe `AgentSpec` + registry for declarative agent definitions
+- `AgentRunner` with tool calling, iteration caps, and confidence-aware escalation
+- Memory framework that mixes working memory with long-term persistence hooks
+- Tool registry/executor with structured input validation and telemetry hooks
+- Approval workflow helpers for human-in-the-loop gates (see `/approval`)
+
+## Quickstart
+
+```ts
+import { AgentRegistry, AgentRunner, defineAgent } from '@lssm/lib.ai-agent';
+import { ToolExecutor } from '@lssm/lib.ai-agent/tools';
+import { InMemoryAgentMemory } from '@lssm/lib.ai-agent/memory';
+
+const SupportAgent = defineAgent({
+  meta: { name: 'support.bot', version: 1, owners: ['team-support'], domain: 'operations' },
+  instructions: 'Resolve support tickets. Escalate whenever confidence < 0.75.',
+  tools: [{ name: 'search_knowledge', description: 'Query support corpus', schema: { type: 'object', properties: { question: { type: 'string' } }, required: ['question'] } }],
+  policy: { confidence: { min: 0.75 }, escalation: { auto: true } },
+});
+
+const registry = new AgentRegistry().register(SupportAgent);
+const runner = new AgentRunner({
+  registry,
+  llm: mistralProvider,
+  toolExecutor: new ToolExecutor({ tools: [searchKnowledgeTool] }),
+  memoryManager: new InMemoryAgentMemory(),
+});
+
+const result = await runner.run({ agent: 'support.bot', input: 'My payout failed.', tenantId: 'acme' });
+if (result.requiresEscalation) notifyHuman(result);
+```
+
+See `examples/ai-support-bot` for a full workflow including ticket ingestion and approval queues.

package/dist/agent/agent-factory.d.ts

@@ -0,0 +1,103 @@
+import { AgentSpec } from "../spec/spec.js";
+import { AgentRegistry } from "../spec/registry.js";
+import { ToolHandler } from "../types.js";
+import { AgentSessionStore } from "../session/store.js";
+import { TelemetryCollector } from "../telemetry/adapter.js";
+import { ContractSpecAgent } from "./contract-spec-agent.js";
+import { LanguageModel, Tool } from "ai";
+import { KnowledgeRetriever } from "@lssm/lib.knowledge/retriever";
+
+//#region src/agent/agent-factory.d.ts
+
+/**
+ * Factory configuration for creating agents.
+ */
+interface AgentFactoryConfig {
+  /** Default language model to use */
+  defaultModel: LanguageModel;
+  /** Agent registry for looking up specs */
+  registry: AgentRegistry;
+  /** Global tool handlers map */
+  toolHandlers: Map<string, ToolHandler>;
+  /** Optional knowledge retriever */
+  knowledgeRetriever?: KnowledgeRetriever;
+  /** Optional session store */
+  sessionStore?: AgentSessionStore;
+  /** Optional telemetry collector */
+  telemetryCollector?: TelemetryCollector;
+  /** Additional tools to provide to all agents */
+  additionalTools?: Record<string, Tool<unknown, unknown>>;
+}
+/**
+ * Options for creating an agent instance.
+ */
+interface CreateAgentOptions {
+  /** Override the default model */
+  model?: LanguageModel;
+  /** Additional tool handlers specific to this instance */
+  toolHandlers?: Map<string, ToolHandler>;
+  /** Additional tools for this instance */
+  additionalTools?: Record<string, Tool<unknown, unknown>>;
+}
+/**
+ * Factory for creating ContractSpec agents from specs.
+ *
+ * Provides a centralized way to instantiate agents with
+ * consistent configuration.
+ *
+ * @example
+ * ```typescript
+ * const factory = createAgentFactory({
+ *   defaultModel: mistral('mistral-large-latest'),
+ *   registry: agentRegistry,
+ *   toolHandlers: globalToolHandlers,
+ *   sessionStore: mySessionStore,
+ * });
+ *
+ * const agent = await factory.create('support.bot');
+ * const result = await agent.generate({ prompt: 'Help me with...' });
+ * ```
+ */
+declare class AgentFactory {
+  private readonly config;
+  private readonly cache;
+  constructor(config: AgentFactoryConfig);
+  /**
+   * Create an agent by name.
+   *
+   * @param name - Agent name (e.g., "support.bot")
+   * @param version - Optional specific version
+   * @param options - Optional creation options
+   */
+  create(name: string, version?: number, options?: CreateAgentOptions): Promise<ContractSpecAgent>;
+  /**
+   * Create an agent from a spec directly.
+   *
+   * @param spec - Agent specification
+   * @param options - Optional creation options
+   */
+  createFromSpec(spec: AgentSpec, options?: CreateAgentOptions): Promise<ContractSpecAgent>;
+  /**
+   * Get or create a cached agent instance.
+   *
+   * Use this when you want to reuse agent instances.
+   *
+   * @param name - Agent name
+   * @param version - Optional specific version
+   */
+  getOrCreate(name: string, version?: number): Promise<ContractSpecAgent>;
+  /**
+   * Clear the agent cache.
+   */
+  clearCache(): void;
+  /**
+   * List all available agent names.
+   */
+  listAvailable(): string[];
+}
+/**
+ * Create an agent factory.
+ */
+declare function createAgentFactory(config: AgentFactoryConfig): AgentFactory;
+//#endregion
+export { AgentFactory, AgentFactoryConfig, CreateAgentOptions, createAgentFactory };

package/dist/agent/agent-factory.js

@@ -0,0 +1 @@
+import{ContractSpecAgent as e}from"./contract-spec-agent.js";var t=class{config;cache=new Map;constructor(e){this.config=e}async create(e,t,n){let r=this.config.registry.require(e,t);return this.createFromSpec(r,n)}async createFromSpec(t,n){let r=new Map(this.config.toolHandlers);if(n?.toolHandlers)for(let[e,t]of n.toolHandlers)r.set(e,t);let i={...this.config.additionalTools,...n?.additionalTools};return e.create({spec:t,model:n?.model??this.config.defaultModel,toolHandlers:r,knowledgeRetriever:this.config.knowledgeRetriever,sessionStore:this.config.sessionStore,telemetryCollector:this.config.telemetryCollector,additionalTools:i})}async getOrCreate(e,t){let n=this.config.registry.require(e,t),r=`${n.meta.name}.v${n.meta.version}`,i=this.cache.get(r);return i||(i=await this.createFromSpec(n),this.cache.set(r,i)),i}clearCache(){this.cache.clear()}listAvailable(){return this.config.registry.listNames()}};function n(e){return new t(e)}export{t as AgentFactory,n as createAgentFactory};

package/dist/agent/contract-spec-agent.d.ts

@@ -0,0 +1,74 @@
+import { AgentSpec } from "../spec/spec.js";
+import { AgentGenerateParams, AgentGenerateResult, AgentStreamParams, ToolHandler } from "../types.js";
+import { AgentSessionStore } from "../session/store.js";
+import { TelemetryCollector } from "../telemetry/adapter.js";
+import * as ai0 from "ai";
+import { LanguageModel, Tool, ToolSet } from "ai";
+import { KnowledgeRetriever } from "@lssm/lib.knowledge/retriever";
+
+//#region src/agent/contract-spec-agent.d.ts
+
+/**
+ * Type for tool with execute function (compatible with AI SDK Tool)
+ * Using `any` for broad compatibility with AI SDK tool types
+ */
+type ExecutableTool = Tool<any, any>;
+/**
+ * Configuration for creating a ContractSpecAgent.
+ */
+interface ContractSpecAgentConfig {
+  /** The agent specification */
+  spec: AgentSpec;
+  /** AI SDK language model */
+  model: LanguageModel;
+  /** Map of tool name to handler function */
+  toolHandlers: Map<string, ToolHandler>;
+  /** Optional knowledge retriever for RAG */
+  knowledgeRetriever?: KnowledgeRetriever;
+  /** Optional session store for persistence */
+  sessionStore?: AgentSessionStore;
+  /** Optional telemetry collector for evolution */
+  telemetryCollector?: TelemetryCollector;
+  /** Additional AI SDK tools (e.g., from MCP servers) */
+  additionalTools?: Record<string, ExecutableTool>;
+}
+/**
+ * ContractSpec Agent implementation using AI SDK v6.
+ *
+ * Integrates ContractSpec's spec-first governance with AI SDK's
+ * ToolLoopAgent, providing:
+ * - Spec-defined tools with type-safe handlers
+ * - Hybrid knowledge injection (static + dynamic RAG)
+ * - Session persistence
+ * - Telemetry for evolution
+ * - MCP interoperability
+ */
+declare class ContractSpecAgent {
+  readonly version = "agent-v1";
+  readonly id: string;
+  readonly spec: AgentSpec;
+  readonly tools: Record<string, ExecutableTool>;
+  private readonly inner;
+  private readonly config;
+  private instructions;
+  private constructor();
+  /**
+   * Create a ContractSpecAgent instance.
+   * This is async because knowledge injection may need to fetch static content.
+   */
+  static create(config: ContractSpecAgentConfig): Promise<ContractSpecAgent>;
+  /**
+   * Generate a response (non-streaming).
+   */
+  generate(params: AgentGenerateParams): Promise<AgentGenerateResult>;
+  /**
+   * Stream a response with real-time updates.
+   */
+  stream(params: AgentStreamParams): Promise<ai0.StreamTextResult<ToolSet, never>>;
+  /**
+   * Handle step completion for persistence and telemetry.
+   */
+  private handleStepFinish;
+}
+//#endregion
+export { ContractSpecAgent, ContractSpecAgentConfig };

package/dist/agent/contract-spec-agent.js

@@ -0,0 +1 @@
+import{specToolsToAISDKTools as e}from"../tools/tool-adapter.js";import{createKnowledgeQueryTool as t}from"../tools/knowledge-tool.js";import{injectStaticKnowledge as n}from"../knowledge/injector.js";import{generateSessionId as r}from"../session/store.js";import{trackAgentStep as i}from"../telemetry/adapter.js";import{agentKey as a}from"../spec/spec.js";import{Experimental_Agent as o,stepCountIs as s}from"ai";import{z as c}from"zod";const l=c.object({tenantId:c.string().optional(),actorId:c.string().optional(),sessionId:c.string().optional(),metadata:c.record(c.string(),c.unknown()).optional()});var u=class c{version=`agent-v1`;id;spec;tools;inner;config;instructions;constructor(e,t,n){this.config=e,this.spec=e.spec,this.id=a(e.spec.meta),this.tools=n,this.instructions=t,this.inner=new o({model:e.model,instructions:t,tools:n,stopWhen:s(e.spec.maxSteps??10),callOptionsSchema:l,onStepFinish:async e=>{await this.handleStepFinish(e)}})}static async create(r){let i=await n(r.spec.instructions,r.spec.knowledge??[],r.knowledgeRetriever),o=e(r.spec.tools,r.toolHandlers,{agentId:a(r.spec.meta)}),s=r.knowledgeRetriever?t(r.knowledgeRetriever,r.spec.knowledge??[]):null;return new c(r,i,{...o,...s?{query_knowledge:s}:{},...r.additionalTools??{}})}async generate(e){let t=e.options?.sessionId??r();this.config.sessionStore&&(await this.config.sessionStore.get(t)||await this.config.sessionStore.create({sessionId:t,agentId:this.id,tenantId:e.options?.tenantId,actorId:e.options?.actorId,status:`running`,messages:[],steps:[],metadata:e.options?.metadata}));let n=e.systemOverride?`${this.instructions}\n\n${e.systemOverride}\n\n${e.prompt}`:e.prompt,i=await this.inner.generate({prompt:n,abortSignal:e.signal,options:{tenantId:e.options?.tenantId,actorId:e.options?.actorId,sessionId:t,metadata:e.options?.metadata}});return this.config.sessionStore&&await this.config.sessionStore.update(t,{status:`completed`}),{text:i.text,steps:i.steps,toolCalls:i.toolCalls.map(e=>({type:`tool-call`,toolCallId:e.toolCallId,toolName:e.toolName,args:`args`in e?e.args:`input`in e?e.input:void 0})),toolResults:i.toolResults.map(e=>({type:`tool-result`,toolCallId:e.toolCallId,toolName:e.toolName,output:e.output})),finishReason:i.finishReason,usage:i.usage}}async stream(e){let t=e.options?.sessionId??r(),n=e.systemOverride?`${this.instructions}\n\n${e.systemOverride}\n\n${e.prompt}`:e.prompt;return this.inner.stream({prompt:n,abortSignal:e.signal,options:{tenantId:e.options?.tenantId,actorId:e.options?.actorId,sessionId:t,metadata:e.options?.metadata}})}async handleStepFinish(e){let t=e.options?.sessionId;t&&this.config.sessionStore&&await this.config.sessionStore.appendStep(t,e),this.config.telemetryCollector&&await i(this.config.telemetryCollector,this.id,e)}};export{u as ContractSpecAgent};

package/dist/agent/index.d.ts

@@ -0,0 +1,3 @@
+import { ContractSpecAgent, ContractSpecAgentConfig } from "./contract-spec-agent.js";
+import { AgentFactory, AgentFactoryConfig, CreateAgentOptions, createAgentFactory } from "./agent-factory.js";
+export { AgentFactory, AgentFactoryConfig, ContractSpecAgent, ContractSpecAgentConfig, CreateAgentOptions, createAgentFactory };

package/dist/agent/index.js

@@ -0,0 +1 @@
+import{ContractSpecAgent as e}from"./contract-spec-agent.js";import{AgentFactory as t,createAgentFactory as n}from"./agent-factory.js";export{t as AgentFactory,e as ContractSpecAgent,n as createAgentFactory};

package/dist/approval/index.d.ts

@@ -0,0 +1,2 @@
+import { ApprovalRequest, ApprovalStatus, ApprovalStore, ApprovalWorkflow, InMemoryApprovalStore, createApprovalWorkflow } from "./workflow.js";
+export { type ApprovalRequest, type ApprovalStatus, type ApprovalStore, ApprovalWorkflow, InMemoryApprovalStore, createApprovalWorkflow };

package/dist/approval/index.js

@@ -0,0 +1 @@
+import{ApprovalWorkflow as e,InMemoryApprovalStore as t,createApprovalWorkflow as n}from"./workflow.js";export{e as ApprovalWorkflow,t as InMemoryApprovalStore,n as createApprovalWorkflow};

package/dist/approval/workflow.d.ts

@@ -0,0 +1,155 @@
+import { ToolCallInfo } from "../types.js";
+
+//#region src/approval/workflow.d.ts
+type ApprovalStatus = 'pending' | 'approved' | 'rejected';
+/**
+ * Approval request for a tool execution.
+ *
+ * When a tool has `needsApproval: true` in AI SDK v6, the agent
+ * will pause and wait for approval before executing the tool.
+ */
+interface ApprovalRequest {
+  /** Unique request ID */
+  id: string;
+  /** Agent session ID */
+  sessionId: string;
+  /** Agent ID */
+  agentId: string;
+  /** Tenant ID for scoping */
+  tenantId?: string;
+  /** Tool name requiring approval */
+  toolName: string;
+  /** Tool call ID from AI SDK */
+  toolCallId: string;
+  /** Tool arguments */
+  toolArgs: unknown;
+  /** Human-readable reason for approval */
+  reason: string;
+  /** When the approval was requested */
+  requestedAt: Date;
+  /** Current status */
+  status: ApprovalStatus;
+  /** Additional context payload */
+  payload?: Record<string, unknown>;
+  /** Who resolved the approval */
+  reviewer?: string;
+  /** When the approval was resolved */
+  resolvedAt?: Date;
+  /** Reviewer notes */
+  notes?: string;
+}
+/**
+ * Storage interface for approval requests.
+ */
+interface ApprovalStore {
+  create(request: ApprovalRequest): Promise<void>;
+  get(id: string): Promise<ApprovalRequest | null>;
+  getByToolCallId(toolCallId: string): Promise<ApprovalRequest | null>;
+  update(id: string, updates: Partial<Omit<ApprovalRequest, 'id' | 'sessionId'>>): Promise<void>;
+  list(options?: {
+    status?: ApprovalStatus;
+    agentId?: string;
+    tenantId?: string;
+  }): Promise<ApprovalRequest[]>;
+}
+/**
+ * In-memory approval store for development and testing.
+ */
+declare class InMemoryApprovalStore implements ApprovalStore {
+  private readonly items;
+  create(request: ApprovalRequest): Promise<void>;
+  get(id: string): Promise<ApprovalRequest | null>;
+  getByToolCallId(toolCallId: string): Promise<ApprovalRequest | null>;
+  update(id: string, updates: Partial<Omit<ApprovalRequest, 'id' | 'sessionId'>>): Promise<void>;
+  list(options?: {
+    status?: ApprovalStatus;
+    agentId?: string;
+    tenantId?: string;
+  }): Promise<ApprovalRequest[]>;
+  clear(): void;
+}
+/**
+ * Approval workflow for managing tool execution approvals.
+ *
+ * Integrates with AI SDK v6's `needsApproval` feature on tools.
+ *
+ * @example
+ * ```typescript
+ * const workflow = new ApprovalWorkflow();
+ *
+ * // When a tool needs approval
+ * const request = await workflow.requestApproval({
+ *   sessionId: 'sess_123',
+ *   agentId: 'support.bot.v1',
+ *   toolName: 'delete_account',
+ *   toolCallId: 'call_abc',
+ *   toolArgs: { userId: 'user_123' },
+ *   reason: 'Account deletion requires human approval',
+ * });
+ *
+ * // When approval is granted
+ * await workflow.approve(request.id, 'admin@example.com', 'Verified identity');
+ *
+ * // Or rejected
+ * await workflow.reject(request.id, 'admin@example.com', 'Suspicious activity');
+ * ```
+ */
+declare class ApprovalWorkflow {
+  private readonly store;
+  constructor(store?: ApprovalStore);
+  /**
+   * Request approval for a tool execution.
+   */
+  requestApproval(params: {
+    sessionId: string;
+    agentId: string;
+    tenantId?: string;
+    toolName: string;
+    toolCallId: string;
+    toolArgs: unknown;
+    reason: string;
+    payload?: Record<string, unknown>;
+  }): Promise<ApprovalRequest>;
+  /**
+   * Request approval from an AI SDK tool call.
+   */
+  requestApprovalFromToolCall(toolCall: ToolCallInfo, context: {
+    sessionId: string;
+    agentId: string;
+    tenantId?: string;
+    reason?: string;
+  }): Promise<ApprovalRequest>;
+  /**
+   * Approve a pending request.
+   */
+  approve(id: string, reviewer: string, notes?: string): Promise<void>;
+  /**
+   * Reject a pending request.
+   */
+  reject(id: string, reviewer: string, notes?: string): Promise<void>;
+  /**
+   * Get approval status for a tool call.
+   */
+  getStatus(toolCallId: string): Promise<ApprovalStatus | null>;
+  /**
+   * Check if a tool call is approved.
+   */
+  isApproved(toolCallId: string): Promise<boolean>;
+  /**
+   * List pending approvals.
+   */
+  listPending(options?: {
+    agentId?: string;
+    tenantId?: string;
+  }): Promise<ApprovalRequest[]>;
+  /**
+   * Get approval request by ID.
+   */
+  get(id: string): Promise<ApprovalRequest | null>;
+}
+/**
+ * Create an approval workflow instance.
+ */
+declare function createApprovalWorkflow(store?: ApprovalStore): ApprovalWorkflow;
+//#endregion
+export { ApprovalRequest, ApprovalStatus, ApprovalStore, ApprovalWorkflow, InMemoryApprovalStore, createApprovalWorkflow };

package/dist/approval/workflow.js

@@ -0,0 +1 @@
+import{randomUUID as e}from"node:crypto";var t=class{items=new Map;async create(e){this.items.set(e.id,e)}async get(e){return this.items.get(e)??null}async getByToolCallId(e){for(let t of this.items.values())if(t.toolCallId===e)return t;return null}async update(e,t){let n=this.items.get(e);n&&this.items.set(e,{...n,...t})}async list(e){let t=[...this.items.values()];return e?.status&&(t=t.filter(t=>t.status===e.status)),e?.agentId&&(t=t.filter(t=>t.agentId===e.agentId)),e?.tenantId&&(t=t.filter(t=>t.tenantId===e.tenantId)),t.sort((e,t)=>t.requestedAt.getTime()-e.requestedAt.getTime())}clear(){this.items.clear()}},n=class{constructor(e=new t){this.store=e}async requestApproval(t){let n={id:e(),sessionId:t.sessionId,agentId:t.agentId,tenantId:t.tenantId,toolName:t.toolName,toolCallId:t.toolCallId,toolArgs:t.toolArgs,reason:t.reason,requestedAt:new Date,status:`pending`,payload:t.payload};return await this.store.create(n),n}async requestApprovalFromToolCall(e,t){return this.requestApproval({sessionId:t.sessionId,agentId:t.agentId,tenantId:t.tenantId,toolName:e.toolName,toolCallId:e.toolCallId,toolArgs:e.args,reason:t.reason??`Tool "${e.toolName}" requires approval`})}async approve(e,t,n){await this.store.update(e,{status:`approved`,reviewer:t,resolvedAt:new Date,notes:n})}async reject(e,t,n){await this.store.update(e,{status:`rejected`,reviewer:t,resolvedAt:new Date,notes:n})}async getStatus(e){return(await this.store.getByToolCallId(e))?.status??null}async isApproved(e){return await this.getStatus(e)===`approved`}async listPending(e){return this.store.list({...e,status:`pending`})}async get(e){return this.store.get(e)}};function r(e){return new n(e)}export{n as ApprovalWorkflow,t as InMemoryApprovalStore,r as createApprovalWorkflow};

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { AgentConfidencePolicy, AgentEscalationPolicy, AgentKnowledgeRef, AgentMemoryConfig, AgentMeta, AgentPolicy, AgentSpec, AgentToolConfig, agentKey, defineAgent } from "./spec/spec.js";
+import { AgentRegistry, createAgentRegistry } from "./spec/registry.js";
+import { AgentCallOptions, AgentEventEmitter, AgentEventName, AgentEventPayload, AgentGenerateParams, AgentGenerateResult, AgentMessage, AgentRunRequestInput, AgentRunResult, AgentSessionState, AgentStatus, AgentStepMetrics, AgentStreamParams, AgentToolContext, AgentToolInvocation, AgentToolResult, ToolCallInfo, ToolExecutionContext, ToolHandler, ToolResultInfo } from "./types.js";
+import { AgentSessionStore, InMemorySessionStore, createInMemorySessionStore, generateSessionId } from "./session/store.js";
+import { InMemoryTelemetryCollector, OperationMetricSample, TelemetryCollector, createInMemoryTelemetryCollector, noopTelemetryCollector, trackAgentStep } from "./telemetry/adapter.js";
+import { ContractSpecAgent, ContractSpecAgentConfig } from "./agent/contract-spec-agent.js";
+import { AgentFactory, AgentFactoryConfig, CreateAgentOptions, createAgentFactory } from "./agent/agent-factory.js";
+import "./agent/index.js";
+import { ApprovalRequest, ApprovalStatus, ApprovalStore, ApprovalWorkflow, InMemoryApprovalStore, createApprovalWorkflow } from "./approval/workflow.js";
+import "./approval/index.js";
+import { buildToolHandlers, createToolHandler, specToolToAISDKTool, specToolsToAISDKTools } from "./tools/tool-adapter.js";
+import { createKnowledgeQueryTool } from "./tools/knowledge-tool.js";
+import { McpClientConfig, McpClientResult, createMcpToolsets, mcpServerToTools } from "./tools/mcp-client.js";
+import { AgentMcpServerConfig, agentToMcpServer, createAgentMcpServer } from "./tools/mcp-server.js";
+import "./tools/index.js";
+import { jsonSchemaToZod, jsonSchemaToZodSafe } from "./schema/json-schema-to-zod.js";
+import { SchemaOutput, enumToChoiceOutput, jsonSchemaToArrayOutput, jsonSchemaToOutput, textOutput, zodToOutput } from "./schema/schema-output.js";
+import "./schema/index.js";
+import { createKnowledgeInjector, injectStaticKnowledge } from "./knowledge/injector.js";
+import "./session/index.js";
+import "./telemetry/index.js";
+import { Experimental_Agent as ToolLoopAgent, LanguageModel, LanguageModelUsage, ModelMessage, StepResult, Tool, ToolSet } from "ai";
+export { AgentCallOptions, AgentConfidencePolicy, AgentEscalationPolicy, AgentEventEmitter, AgentEventName, AgentEventPayload, AgentFactory, AgentFactoryConfig, AgentGenerateParams, AgentGenerateResult, AgentKnowledgeRef, AgentMcpServerConfig, AgentMemoryConfig, AgentMessage, AgentMeta, AgentPolicy, AgentRegistry, AgentRunRequestInput, AgentRunResult, AgentSessionState, AgentSessionStore, AgentSpec, AgentStatus, AgentStepMetrics, AgentStreamParams, AgentToolConfig, AgentToolContext, AgentToolInvocation, AgentToolResult, ApprovalRequest, ApprovalStatus, ApprovalStore, ApprovalWorkflow, ContractSpecAgent, ContractSpecAgentConfig, CreateAgentOptions, InMemoryApprovalStore, InMemorySessionStore, InMemoryTelemetryCollector, type LanguageModel, type LanguageModelUsage, McpClientConfig, McpClientResult, type ModelMessage, OperationMetricSample, SchemaOutput, type StepResult, TelemetryCollector, type Tool, ToolCallInfo, ToolExecutionContext, ToolHandler, ToolLoopAgent, ToolResultInfo, type ToolSet, agentKey, agentToMcpServer, buildToolHandlers, createAgentFactory, createAgentMcpServer, createAgentRegistry, createApprovalWorkflow, createInMemorySessionStore, createInMemoryTelemetryCollector, createKnowledgeInjector, createKnowledgeQueryTool, createMcpToolsets, createToolHandler, defineAgent, enumToChoiceOutput, generateSessionId, injectStaticKnowledge, jsonSchemaToArrayOutput, jsonSchemaToOutput, jsonSchemaToZod, jsonSchemaToZodSafe, mcpServerToTools, noopTelemetryCollector, specToolToAISDKTool, specToolsToAISDKTools, textOutput, trackAgentStep, zodToOutput };

package/dist/index.js

@@ -0,0 +1 @@
+import{jsonSchemaToZod as e,jsonSchemaToZodSafe as t}from"./schema/json-schema-to-zod.js";import{buildToolHandlers as n,createToolHandler as r,specToolToAISDKTool as i,specToolsToAISDKTools as a}from"./tools/tool-adapter.js";import{createKnowledgeQueryTool as o}from"./tools/knowledge-tool.js";import{createKnowledgeInjector as s,injectStaticKnowledge as c}from"./knowledge/injector.js";import{InMemorySessionStore as l,createInMemorySessionStore as u,generateSessionId as d}from"./session/store.js";import{InMemoryTelemetryCollector as f,createInMemoryTelemetryCollector as p,noopTelemetryCollector as m,trackAgentStep as h}from"./telemetry/adapter.js";import{agentKey as g,defineAgent as _}from"./spec/spec.js";import{ContractSpecAgent as v}from"./agent/contract-spec-agent.js";import{AgentFactory as y,createAgentFactory as b}from"./agent/agent-factory.js";import"./agent/index.js";import{AgentRegistry as x,createAgentRegistry as S}from"./spec/registry.js";import{createMcpToolsets as C,mcpServerToTools as w}from"./tools/mcp-client.js";import{agentToMcpServer as T,createAgentMcpServer as E}from"./tools/mcp-server.js";import"./tools/index.js";import{SchemaOutput as D,enumToChoiceOutput as O,jsonSchemaToArrayOutput as k,jsonSchemaToOutput as A,textOutput as j,zodToOutput as M}from"./schema/schema-output.js";import"./schema/index.js";import{ApprovalWorkflow as N,InMemoryApprovalStore as P,createApprovalWorkflow as F}from"./approval/workflow.js";import"./approval/index.js";import{Experimental_Agent as I}from"ai";export{y as AgentFactory,x as AgentRegistry,N as ApprovalWorkflow,v as ContractSpecAgent,P as InMemoryApprovalStore,l as InMemorySessionStore,f as InMemoryTelemetryCollector,D as SchemaOutput,I as ToolLoopAgent,g as agentKey,T as agentToMcpServer,n as buildToolHandlers,b as createAgentFactory,E as createAgentMcpServer,S as createAgentRegistry,F as createApprovalWorkflow,u as createInMemorySessionStore,p as createInMemoryTelemetryCollector,s as createKnowledgeInjector,o as createKnowledgeQueryTool,C as createMcpToolsets,r as createToolHandler,_ as defineAgent,O as enumToChoiceOutput,d as generateSessionId,c as injectStaticKnowledge,k as jsonSchemaToArrayOutput,A as jsonSchemaToOutput,e as jsonSchemaToZod,t as jsonSchemaToZodSafe,w as mcpServerToTools,m as noopTelemetryCollector,i as specToolToAISDKTool,a as specToolsToAISDKTools,j as textOutput,h as trackAgentStep,M as zodToOutput};

package/dist/knowledge/index.d.ts

@@ -0,0 +1,2 @@
+import { createKnowledgeInjector, injectStaticKnowledge } from "./injector.js";
+export { createKnowledgeInjector, injectStaticKnowledge };

package/dist/knowledge/index.js

@@ -0,0 +1 @@
+import{createKnowledgeInjector as e,injectStaticKnowledge as t}from"./injector.js";export{e as createKnowledgeInjector,t as injectStaticKnowledge};

package/dist/knowledge/injector.d.ts

@@ -0,0 +1,37 @@
+import { AgentKnowledgeRef } from "../spec/spec.js";
+import { KnowledgeRetriever } from "@lssm/lib.knowledge/retriever";
+
+//#region src/knowledge/injector.d.ts
+
+/**
+ * Inject static knowledge into agent instructions.
+ *
+ * This function handles the "required" knowledge that should be
+ * injected into the system prompt at agent initialization time.
+ * Optional knowledge is handled by the knowledge query tool.
+ *
+ * @param instructions - Base agent instructions
+ * @param knowledgeRefs - Knowledge references from the agent spec
+ * @param retriever - Optional knowledge retriever
+ * @returns Instructions with injected knowledge
+ */
+declare function injectStaticKnowledge(instructions: string, knowledgeRefs: AgentKnowledgeRef[], retriever?: KnowledgeRetriever): Promise<string>;
+/**
+ * Create a knowledge injector instance for reuse.
+ */
+declare function createKnowledgeInjector(retriever?: KnowledgeRetriever): {
+  /**
+   * Inject static knowledge into instructions.
+   */
+  inject: (instructions: string, knowledgeRefs: AgentKnowledgeRef[]) => Promise<string>;
+  /**
+   * Check if a knowledge space is available.
+   */
+  hasSpace: (spaceKey: string) => boolean;
+  /**
+   * List available knowledge spaces.
+   */
+  listSpaces: () => string[];
+};
+//#endregion
+export { createKnowledgeInjector, injectStaticKnowledge };

package/dist/knowledge/injector.js

@@ -0,0 +1,13 @@
+async function e(e,t,n){if(!n)return e;let r=t.filter(e=>e.required);if(r.length===0)return e;let i=[];for(let e of r){if(!n.supportsSpace(e.key)){console.warn(`Required knowledge space "${e.key}" is not available`);continue}try{let t=await n.getStatic(e.key);if(t){let n=e.instructions?`## ${e.key}\n${e.instructions}`:`## ${e.key}`;i.push(`${n}\n\n${t}`)}}catch(t){console.warn(`Failed to load required knowledge "${e.key}":`,t)}}return i.length===0?e:`${e}
+
+---
+
+# Reference Knowledge
+
+The following information is provided for your reference. Use it to inform your responses.
+
+${i.join(`
+
+---
+
+`)}`}function t(t){return{inject:(n,r)=>e(n,r,t),hasSpace:e=>t?.supportsSpace(e)??!1,listSpaces:()=>t?.listSpaces()??[]}}export{t as createKnowledgeInjector,e as injectStaticKnowledge};

package/dist/memory/in-memory.d.ts

@@ -0,0 +1,21 @@
+import { AgentSessionState } from "../types.js";
+import { AgentMemorySnapshot, AgentSessionMemory, BaseAgentMemoryManager } from "./manager.js";
+
+//#region src/memory/in-memory.d.ts
+interface InMemoryAgentMemoryOptions {
+  ttlMinutes?: number;
+  maxEntries?: number;
+}
+declare class InMemoryAgentMemory extends BaseAgentMemoryManager {
+  private readonly ttlMs;
+  private readonly maxEntries;
+  private readonly store;
+  constructor(options?: InMemoryAgentMemoryOptions);
+  load(sessionId: string): Promise<AgentSessionMemory | null>;
+  save(snapshot: AgentSessionMemory): Promise<void>;
+  summarize(session: AgentSessionState): Promise<AgentMemorySnapshot>;
+  private trim;
+  private evictExpired;
+}
+//#endregion
+export { InMemoryAgentMemory, InMemoryAgentMemoryOptions };

package/dist/memory/in-memory.js

@@ -0,0 +1,2 @@
+import{BaseAgentMemoryManager as e}from"./manager.js";var t=class extends e{ttlMs;maxEntries;store=new Map;constructor(e){super(),this.ttlMs=(e?.ttlMinutes??60)*60*1e3,this.maxEntries=e?.maxEntries??250}async load(e){this.evictExpired();let t=this.store.get(e);return t?(t.data.session.updatedAt=new Date,t.expiresAt=Date.now()+this.ttlMs,t.data):null}async save(e){this.trim(e.memory.entries),this.store.set(e.session.sessionId,{data:e,expiresAt:Date.now()+this.ttlMs})}async summarize(e){let t=await this.load(e.sessionId)??this.bootstrapMemory(e),n=t.memory.entries.slice(-10).map(e=>`- ${e.type}: ${e.content}`).join(`
+`);return t.memory.summary=n,t.memory.lastSummarizedAt=new Date,await this.save(t),t.memory}trim(e){e.length<=this.maxEntries||e.splice(0,e.length-this.maxEntries)}evictExpired(){let e=Date.now();for(let[t,n]of this.store.entries())n.expiresAt<=e&&this.store.delete(t)}};export{t as InMemoryAgentMemory};

package/dist/memory/index.d.ts

@@ -0,0 +1,3 @@
+import { AgentMemoryEntry, AgentMemoryManager, AgentMemorySnapshot, AgentSessionMemory, BaseAgentMemoryManager, trackMessageInMemory } from "./manager.js";
+import { InMemoryAgentMemory, InMemoryAgentMemoryOptions } from "./in-memory.js";
+export { AgentMemoryEntry, AgentMemoryManager, AgentMemorySnapshot, AgentSessionMemory, BaseAgentMemoryManager, InMemoryAgentMemory, InMemoryAgentMemoryOptions, trackMessageInMemory };

package/dist/memory/index.js

@@ -0,0 +1 @@
+import{BaseAgentMemoryManager as e,trackMessageInMemory as t}from"./manager.js";import{InMemoryAgentMemory as n}from"./in-memory.js";export{e as BaseAgentMemoryManager,n as InMemoryAgentMemory,t as trackMessageInMemory};

package/dist/memory/manager.d.ts

@@ -0,0 +1,41 @@
+import { AgentMessage, AgentSessionState } from "../types.js";
+
+//#region src/memory/manager.d.ts
+interface AgentMemoryEntry {
+  id: string;
+  type: 'user' | 'assistant' | 'tool' | 'system';
+  content: string;
+  createdAt: Date;
+  metadata?: Record<string, string>;
+}
+interface AgentMemorySnapshot {
+  entries: AgentMemoryEntry[];
+  summary?: string;
+  lastSummarizedAt?: Date;
+}
+interface AgentSessionMemory {
+  session: AgentSessionState;
+  memory: AgentMemorySnapshot;
+}
+interface AgentMemoryManager {
+  load(sessionId: string): Promise<AgentSessionMemory | null>;
+  save(snapshot: AgentSessionMemory): Promise<void>;
+  append(session: AgentSessionState, entry: Omit<AgentMemoryEntry, 'id' | 'createdAt'> & {
+    createdAt?: Date;
+  }): Promise<AgentSessionMemory>;
+  summarize(session: AgentSessionState): Promise<AgentMemorySnapshot | undefined>;
+  prune(session: AgentSessionState): Promise<void>;
+}
+declare abstract class BaseAgentMemoryManager implements AgentMemoryManager {
+  abstract load(sessionId: string): Promise<AgentSessionMemory | null>;
+  abstract save(snapshot: AgentSessionMemory): Promise<void>;
+  append(session: AgentSessionState, entry: Omit<AgentMemoryEntry, 'id' | 'createdAt'> & {
+    createdAt?: Date;
+  }): Promise<AgentSessionMemory>;
+  summarize(_session: AgentSessionState): Promise<AgentMemorySnapshot | undefined>;
+  prune(_session: AgentSessionState): Promise<void>;
+  protected bootstrapMemory(session: AgentSessionState): AgentSessionMemory;
+}
+declare function trackMessageInMemory(manager: AgentMemoryManager | undefined, session: AgentSessionState, message: AgentMessage): void;
+//#endregion
+export { AgentMemoryEntry, AgentMemoryManager, AgentMemorySnapshot, AgentSessionMemory, BaseAgentMemoryManager, trackMessageInMemory };

package/dist/memory/manager.js

@@ -0,0 +1 @@
+import{randomUUID as e}from"node:crypto";function t(e){let t=e.content;return typeof t==`string`?t:Array.isArray(t)?t.map(e=>typeof e==`string`?e:`text`in e&&typeof e.text==`string`?e.text:``).filter(Boolean).join(``):``}function n(e){let t=e.content;return typeof t==`string`?t:Array.isArray(t)?t.map(e=>typeof e==`string`?e:`text`in e&&typeof e.text==`string`?e.text:``).filter(Boolean).join(``):``}function r(e){switch(e){case`assistant`:return`assistant`;case`system`:return`system`;case`tool`:return`tool`;case`user`:default:return`user`}}var i=class{async append(t,n){let r=await this.load(t.sessionId)??this.bootstrapMemory(t),i={id:e(),createdAt:n.createdAt??new Date,...n};return r.memory.entries.push(i),await this.save(r),r}async summarize(e){}async prune(e){}bootstrapMemory(n){return{session:n,memory:{entries:n.messages.map(n=>({id:e(),createdAt:new Date,type:r(n.role),content:t(n)}))}}}};function a(e,t,r){e&&e.append(t,{type:r.role,content:n(r),metadata:r.metadata})}export{i as BaseAgentMemoryManager,a as trackMessageInMemory};

package/dist/schema/index.d.ts

@@ -0,0 +1,3 @@
+import { jsonSchemaToZod, jsonSchemaToZodSafe } from "./json-schema-to-zod.js";
+import { SchemaOutput, enumToChoiceOutput, jsonSchemaToArrayOutput, jsonSchemaToOutput, textOutput, zodToOutput } from "./schema-output.js";
+export { SchemaOutput, enumToChoiceOutput, jsonSchemaToArrayOutput, jsonSchemaToOutput, jsonSchemaToZod, jsonSchemaToZodSafe, textOutput, zodToOutput };

package/dist/schema/index.js

@@ -0,0 +1 @@
+import{jsonSchemaToZod as e,jsonSchemaToZodSafe as t}from"./json-schema-to-zod.js";import{SchemaOutput as n,enumToChoiceOutput as r,jsonSchemaToArrayOutput as i,jsonSchemaToOutput as a,textOutput as o,zodToOutput as s}from"./schema-output.js";export{n as SchemaOutput,r as enumToChoiceOutput,i as jsonSchemaToArrayOutput,a as jsonSchemaToOutput,e as jsonSchemaToZod,t as jsonSchemaToZodSafe,o as textOutput,s as zodToOutput};

package/dist/schema/json-schema-to-zod.d.ts

@@ -0,0 +1,54 @@
+import { ZodType } from "zod";
+
+//#region src/schema/json-schema-to-zod.d.ts
+
+/**
+ * JSON Schema type definitions for conversion.
+ */
+interface JsonSchema {
+  type?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  enum?: (string | number | boolean)[];
+  const?: unknown;
+  anyOf?: JsonSchema[];
+  oneOf?: JsonSchema[];
+  allOf?: JsonSchema[];
+  description?: string;
+  default?: unknown;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+  nullable?: boolean;
+  [key: string]: unknown;
+}
+/**
+ * Convert a JSON Schema to a Zod schema.
+ *
+ * Supports common JSON Schema types and constraints:
+ * - string, number, integer, boolean, null
+ * - object with properties and required
+ * - array with items
+ * - enum and const
+ * - anyOf, oneOf, allOf
+ * - format constraints (email, uri, uuid, date-time)
+ * - numeric constraints (minimum, maximum)
+ * - string constraints (minLength, maxLength, pattern)
+ *
+ * @param schema - JSON Schema object
+ * @returns Zod schema
+ */
+declare function jsonSchemaToZod(schema: JsonSchema | Record<string, unknown>): ZodType;
+/**
+ * Convert a JSON Schema to a Zod schema with a default empty object fallback.
+ *
+ * @param schema - Optional JSON Schema object
+ * @returns Zod schema (defaults to empty object schema)
+ */
+declare function jsonSchemaToZodSafe(schema?: Record<string, unknown>): ZodType;
+//#endregion
+export { jsonSchemaToZod, jsonSchemaToZodSafe };