@contractspec/lib.ai-agent 1.44.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @contractspec/lib.ai-agent
+
+[![npm version](https://img.shields.io/npm/v/@contractspec/lib.ai-agent)](https://www.npmjs.com/package/@contractspec/lib.ai-agent)
+[![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.ai-agent)](https://www.npmjs.com/package/@contractspec/lib.ai-agent)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/lssm-tech/contractspec)
+
+
+Website: https://contractspec.io/
+
+
+**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 '@contractspec/lib.ai-agent';
+import { ToolExecutor } from '@contractspec/lib.ai-agent/tools';
+import { InMemoryAgentMemory } from '@contractspec/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,104 @@
+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 "@contractspec/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 };
+//# sourceMappingURL=agent-factory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-factory.d.ts","names":[],"sources":["../../src/agent/agent-factory.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAYA;AAEgB,UAFC,kBAAA,CAED;EAEJ;EAEgB,YAAA,EAJZ,aAIY;EAAZ;EAEO,QAAA,EAJX,aAIW;EAEN;EAEM,YAAA,EANP,GAMO,CAAA,MAAA,EANK,WAML,CAAA;EAEY;EAAf,kBAAA,CAAA,EANG,kBAMH;EAAM;EAMT,YAAA,CAAA,EAVA,iBAUkB;EAEzB;EAEmB,kBAAA,CAAA,EAZN,kBAYM;EAAZ;EAEkB,eAAA,CAAA,EAZf,MAYe,CAAA,MAAA,EAZA,IAYA,CAAA,OAAA,EAAA,OAAA,CAAA,CAAA;;;AAsBnC;;AAkBc,UA9CG,kBAAA,CA8CH;EACD;EAAR,KAAA,CAAA,EA7CK,aA6CL;EAYK;EACI,YAAA,CAAA,EAxDG,GAwDH,CAAA,MAAA,EAxDe,WAwDf,CAAA;EACD;EAAR,eAAA,CAAA,EAvDe,MAuDf,CAAA,MAAA,EAvD8B,IAuD9B,CAAA,OAAA,EAAA,OAAA,CAAA,CAAA;;;;AAsEL;;;;;;;;;;;;;;;;;cAvGa,YAAA;;;sBAIS;;;;;;;;mDAcR,qBACT,QAAQ;;;;;;;uBAYH,qBACI,qBACT,QAAQ;;;;;;;;;+CAuCR,QAAQ;;;;;;;;;;;;;iBA+BG,kBAAA,SAA2B,qBAAqB"}

package/dist/agent/agent-factory.js

@@ -0,0 +1,103 @@
+import { ContractSpecAgent } from "./contract-spec-agent.js";
+
+//#region src/agent/agent-factory.ts
+/**
+* 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...' });
+* ```
+*/
+var AgentFactory = class {
+	config;
+	cache = /* @__PURE__ */ new Map();
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Create an agent by name.
+	*
+	* @param name - Agent name (e.g., "support.bot")
+	* @param version - Optional specific version
+	* @param options - Optional creation options
+	*/
+	async create(name, version, options) {
+		const spec = this.config.registry.require(name, version);
+		return this.createFromSpec(spec, options);
+	}
+	/**
+	* Create an agent from a spec directly.
+	*
+	* @param spec - Agent specification
+	* @param options - Optional creation options
+	*/
+	async createFromSpec(spec, options) {
+		const mergedHandlers = new Map(this.config.toolHandlers);
+		if (options?.toolHandlers) for (const [key, handler] of options.toolHandlers) mergedHandlers.set(key, handler);
+		const mergedTools = {
+			...this.config.additionalTools,
+			...options?.additionalTools
+		};
+		return ContractSpecAgent.create({
+			spec,
+			model: options?.model ?? this.config.defaultModel,
+			toolHandlers: mergedHandlers,
+			knowledgeRetriever: this.config.knowledgeRetriever,
+			sessionStore: this.config.sessionStore,
+			telemetryCollector: this.config.telemetryCollector,
+			additionalTools: mergedTools
+		});
+	}
+	/**
+	* 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
+	*/
+	async getOrCreate(name, version) {
+		const spec = this.config.registry.require(name, version);
+		const cacheKey = `${spec.meta.key}.v${spec.meta.version}`;
+		let agent = this.cache.get(cacheKey);
+		if (!agent) {
+			agent = await this.createFromSpec(spec);
+			this.cache.set(cacheKey, agent);
+		}
+		return agent;
+	}
+	/**
+	* Clear the agent cache.
+	*/
+	clearCache() {
+		this.cache.clear();
+	}
+	/**
+	* List all available agent names.
+	*/
+	listAvailable() {
+		return this.config.registry.listNames();
+	}
+};
+/**
+* Create an agent factory.
+*/
+function createAgentFactory(config) {
+	return new AgentFactory(config);
+}
+
+//#endregion
+export { AgentFactory, createAgentFactory };
+//# sourceMappingURL=agent-factory.js.map

package/dist/agent/agent-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-factory.js","names":[],"sources":["../../src/agent/agent-factory.ts"],"sourcesContent":["import type { LanguageModel, Tool } from 'ai';\nimport type { KnowledgeRetriever } from '@contractspec/lib.knowledge/retriever';\nimport type { AgentSpec } from '../spec/spec';\nimport type { AgentRegistry } from '../spec/registry';\nimport type { ToolHandler } from '../types';\nimport type { AgentSessionStore } from '../session/store';\nimport type { TelemetryCollector } from '../telemetry/adapter';\nimport { ContractSpecAgent } from './contract-spec-agent';\n\n/**\n * Factory configuration for creating agents.\n */\nexport interface AgentFactoryConfig {\n  /** Default language model to use */\n  defaultModel: LanguageModel;\n  /** Agent registry for looking up specs */\n  registry: AgentRegistry;\n  /** Global tool handlers map */\n  toolHandlers: Map<string, ToolHandler>;\n  /** Optional knowledge retriever */\n  knowledgeRetriever?: KnowledgeRetriever;\n  /** Optional session store */\n  sessionStore?: AgentSessionStore;\n  /** Optional telemetry collector */\n  telemetryCollector?: TelemetryCollector;\n  /** Additional tools to provide to all agents */\n  additionalTools?: Record<string, Tool<unknown, unknown>>;\n}\n\n/**\n * Options for creating an agent instance.\n */\nexport interface CreateAgentOptions {\n  /** Override the default model */\n  model?: LanguageModel;\n  /** Additional tool handlers specific to this instance */\n  toolHandlers?: Map<string, ToolHandler>;\n  /** Additional tools for this instance */\n  additionalTools?: Record<string, Tool<unknown, unknown>>;\n}\n\n/**\n * Factory for creating ContractSpec agents from specs.\n *\n * Provides a centralized way to instantiate agents with\n * consistent configuration.\n *\n * @example\n * ```typescript\n * const factory = createAgentFactory({\n *   defaultModel: mistral('mistral-large-latest'),\n *   registry: agentRegistry,\n *   toolHandlers: globalToolHandlers,\n *   sessionStore: mySessionStore,\n * });\n *\n * const agent = await factory.create('support.bot');\n * const result = await agent.generate({ prompt: 'Help me with...' });\n * ```\n */\nexport class AgentFactory {\n  private readonly config: AgentFactoryConfig;\n  private readonly cache = new Map<string, ContractSpecAgent>();\n\n  constructor(config: AgentFactoryConfig) {\n    this.config = config;\n  }\n\n  /**\n   * Create an agent by name.\n   *\n   * @param name - Agent name (e.g., \"support.bot\")\n   * @param version - Optional specific version\n   * @param options - Optional creation options\n   */\n  async create(\n    name: string,\n    version?: number,\n    options?: CreateAgentOptions\n  ): Promise<ContractSpecAgent> {\n    const spec = this.config.registry.require(name, version);\n    return this.createFromSpec(spec, options);\n  }\n\n  /**\n   * Create an agent from a spec directly.\n   *\n   * @param spec - Agent specification\n   * @param options - Optional creation options\n   */\n  async createFromSpec(\n    spec: AgentSpec,\n    options?: CreateAgentOptions\n  ): Promise<ContractSpecAgent> {\n    // Merge tool handlers\n    const mergedHandlers = new Map<string, ToolHandler>(\n      this.config.toolHandlers\n    );\n    if (options?.toolHandlers) {\n      for (const [key, handler] of options.toolHandlers) {\n        mergedHandlers.set(key, handler);\n      }\n    }\n\n    // Merge additional tools\n    const mergedTools = {\n      ...this.config.additionalTools,\n      ...options?.additionalTools,\n    };\n\n    return ContractSpecAgent.create({\n      spec,\n      model: options?.model ?? this.config.defaultModel,\n      toolHandlers: mergedHandlers,\n      knowledgeRetriever: this.config.knowledgeRetriever,\n      sessionStore: this.config.sessionStore,\n      telemetryCollector: this.config.telemetryCollector,\n      additionalTools: mergedTools,\n    });\n  }\n\n  /**\n   * Get or create a cached agent instance.\n   *\n   * Use this when you want to reuse agent instances.\n   *\n   * @param name - Agent name\n   * @param version - Optional specific version\n   */\n  async getOrCreate(\n    name: string,\n    version?: number\n  ): Promise<ContractSpecAgent> {\n    const spec = this.config.registry.require(name, version);\n    const cacheKey = `${spec.meta.key}.v${spec.meta.version}`;\n\n    let agent = this.cache.get(cacheKey);\n    if (!agent) {\n      agent = await this.createFromSpec(spec);\n      this.cache.set(cacheKey, agent);\n    }\n\n    return agent;\n  }\n\n  /**\n   * Clear the agent cache.\n   */\n  clearCache(): void {\n    this.cache.clear();\n  }\n\n  /**\n   * List all available agent names.\n   */\n  listAvailable(): string[] {\n    return this.config.registry.listNames();\n  }\n}\n\n/**\n * Create an agent factory.\n */\nexport function createAgentFactory(config: AgentFactoryConfig): AgentFactory {\n  return new AgentFactory(config);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA4DA,IAAa,eAAb,MAA0B;CACxB,AAAiB;CACjB,AAAiB,wBAAQ,IAAI,KAAgC;CAE7D,YAAY,QAA4B;AACtC,OAAK,SAAS;;;;;;;;;CAUhB,MAAM,OACJ,MACA,SACA,SAC4B;EAC5B,MAAM,OAAO,KAAK,OAAO,SAAS,QAAQ,MAAM,QAAQ;AACxD,SAAO,KAAK,eAAe,MAAM,QAAQ;;;;;;;;CAS3C,MAAM,eACJ,MACA,SAC4B;EAE5B,MAAM,iBAAiB,IAAI,IACzB,KAAK,OAAO,aACb;AACD,MAAI,SAAS,aACX,MAAK,MAAM,CAAC,KAAK,YAAY,QAAQ,aACnC,gBAAe,IAAI,KAAK,QAAQ;EAKpC,MAAM,cAAc;GAClB,GAAG,KAAK,OAAO;GACf,GAAG,SAAS;GACb;AAED,SAAO,kBAAkB,OAAO;GAC9B;GACA,OAAO,SAAS,SAAS,KAAK,OAAO;GACrC,cAAc;GACd,oBAAoB,KAAK,OAAO;GAChC,cAAc,KAAK,OAAO;GAC1B,oBAAoB,KAAK,OAAO;GAChC,iBAAiB;GAClB,CAAC;;;;;;;;;;CAWJ,MAAM,YACJ,MACA,SAC4B;EAC5B,MAAM,OAAO,KAAK,OAAO,SAAS,QAAQ,MAAM,QAAQ;EACxD,MAAM,WAAW,GAAG,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK;EAEhD,IAAI,QAAQ,KAAK,MAAM,IAAI,SAAS;AACpC,MAAI,CAAC,OAAO;AACV,WAAQ,MAAM,KAAK,eAAe,KAAK;AACvC,QAAK,MAAM,IAAI,UAAU,MAAM;;AAGjC,SAAO;;;;;CAMT,aAAmB;AACjB,OAAK,MAAM,OAAO;;;;;CAMpB,gBAA0B;AACxB,SAAO,KAAK,OAAO,SAAS,WAAW;;;;;;AAO3C,SAAgB,mBAAmB,QAA0C;AAC3E,QAAO,IAAI,aAAa,OAAO"}

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

@@ -0,0 +1,75 @@
+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 "@contractspec/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 };
+//# sourceMappingURL=contract-spec-agent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contract-spec-agent.d.ts","names":[],"sources":["../../src/agent/contract-spec-agent.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAuB+E;AAwB/E,KALK,cAAA,GAAiB,IAKL,CAAA,GAAuB,EAAA,GAAA,CAAA;;;;AAMxB,UANC,uBAAA,CAMD;EAEO;EAEN,IAAA,EART,SAQS;EAEM;EAEY,KAAA,EAV1B,aAU0B;EAAf;EAAM,YAAA,EARV,GAQU,CAAA,MAAA,EARE,WAQF,CAAA;EAcb;EAGI,kBAAA,CAAA,EAvBM,kBAuBN;EACgB;EAAf,YAAA,CAAA,EAtBD,iBAsBC;EA0CN;EACC,kBAAA,CAAA,EA/DU,kBA+DV;EAAR;EAoCoB,eAAA,CAAA,EAjGL,MAiGK,CAAA,MAAA,EAjGU,cAiGV,CAAA;;;;;;;;;;;;;cAnFZ,iBAAA;;;iBAGI;kBACC,eAAe;;;;;;;;;wBA0CrB,0BACP,QAAQ;;;;mBAoCY,sBAAsB,QAAQ;;;;iBAoEhC,oBAAiB,QAAA,GAAA,CAAA,iBAAA"}

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

@@ -0,0 +1,148 @@
+import { agentKey } from "../spec/spec.js";
+import { specToolsToAISDKTools } from "../tools/tool-adapter.js";
+import { createKnowledgeQueryTool } from "../tools/knowledge-tool.js";
+import { injectStaticKnowledge } from "../knowledge/injector.js";
+import { generateSessionId } from "../session/store.js";
+import { trackAgentStep } from "../telemetry/adapter.js";
+import { Experimental_Agent, stepCountIs } from "ai";
+import * as z$1 from "zod";
+
+//#region src/agent/contract-spec-agent.ts
+/**
+* Call options schema for AI SDK v6.
+* Maps ContractSpec's tenant/actor system to AI SDK callOptionsSchema.
+*/
+const ContractSpecCallOptionsSchema = z$1.object({
+	tenantId: z$1.string().optional(),
+	actorId: z$1.string().optional(),
+	sessionId: z$1.string().optional(),
+	metadata: z$1.record(z$1.string(), z$1.unknown()).optional()
+});
+/**
+* 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
+*/
+var ContractSpecAgent = class ContractSpecAgent {
+	version = "agent-v1";
+	id;
+	spec;
+	tools;
+	inner;
+	config;
+	instructions;
+	constructor(config, instructions, tools) {
+		this.config = config;
+		this.spec = config.spec;
+		this.id = agentKey(config.spec.meta);
+		this.tools = tools;
+		this.instructions = instructions;
+		this.inner = new Experimental_Agent({
+			model: config.model,
+			instructions,
+			tools,
+			stopWhen: stepCountIs(config.spec.maxSteps ?? 10),
+			callOptionsSchema: ContractSpecCallOptionsSchema,
+			onStepFinish: async (step) => {
+				await this.handleStepFinish(step);
+			}
+		});
+	}
+	/**
+	* Create a ContractSpecAgent instance.
+	* This is async because knowledge injection may need to fetch static content.
+	*/
+	static async create(config) {
+		const instructions = await injectStaticKnowledge(config.spec.instructions, config.spec.knowledge ?? [], config.knowledgeRetriever);
+		const specTools = specToolsToAISDKTools(config.spec.tools, config.toolHandlers, { agentId: agentKey(config.spec.meta) });
+		const knowledgeTool = config.knowledgeRetriever ? createKnowledgeQueryTool(config.knowledgeRetriever, config.spec.knowledge ?? []) : null;
+		return new ContractSpecAgent(config, instructions, {
+			...specTools,
+			...knowledgeTool ? { query_knowledge: knowledgeTool } : {},
+			...config.additionalTools ?? {}
+		});
+	}
+	/**
+	* Generate a response (non-streaming).
+	*/
+	async generate(params) {
+		const sessionId = params.options?.sessionId ?? generateSessionId();
+		if (this.config.sessionStore) {
+			if (!await this.config.sessionStore.get(sessionId)) await this.config.sessionStore.create({
+				sessionId,
+				agentId: this.id,
+				tenantId: params.options?.tenantId,
+				actorId: params.options?.actorId,
+				status: "running",
+				messages: [],
+				steps: [],
+				metadata: params.options?.metadata
+			});
+		}
+		const prompt = params.systemOverride ? `${this.instructions}\n\n${params.systemOverride}\n\n${params.prompt}` : params.prompt;
+		const result = await this.inner.generate({
+			prompt,
+			abortSignal: params.signal,
+			options: {
+				tenantId: params.options?.tenantId,
+				actorId: params.options?.actorId,
+				sessionId,
+				metadata: params.options?.metadata
+			}
+		});
+		if (this.config.sessionStore) await this.config.sessionStore.update(sessionId, { status: "completed" });
+		return {
+			text: result.text,
+			steps: result.steps,
+			toolCalls: result.toolCalls.map((tc) => ({
+				type: "tool-call",
+				toolCallId: tc.toolCallId,
+				toolName: tc.toolName,
+				args: "args" in tc ? tc.args : "input" in tc ? tc.input : void 0
+			})),
+			toolResults: result.toolResults.map((tr) => ({
+				type: "tool-result",
+				toolCallId: tr.toolCallId,
+				toolName: tr.toolName,
+				output: tr.output
+			})),
+			finishReason: result.finishReason,
+			usage: result.usage
+		};
+	}
+	/**
+	* Stream a response with real-time updates.
+	*/
+	async stream(params) {
+		const sessionId = params.options?.sessionId ?? generateSessionId();
+		const prompt = params.systemOverride ? `${this.instructions}\n\n${params.systemOverride}\n\n${params.prompt}` : params.prompt;
+		return this.inner.stream({
+			prompt,
+			abortSignal: params.signal,
+			options: {
+				tenantId: params.options?.tenantId,
+				actorId: params.options?.actorId,
+				sessionId,
+				metadata: params.options?.metadata
+			}
+		});
+	}
+	/**
+	* Handle step completion for persistence and telemetry.
+	*/
+	async handleStepFinish(step) {
+		const sessionId = step.options?.sessionId;
+		if (sessionId && this.config.sessionStore) await this.config.sessionStore.appendStep(sessionId, step);
+		if (this.config.telemetryCollector) await trackAgentStep(this.config.telemetryCollector, this.id, step);
+	}
+};
+
+//#endregion
+export { ContractSpecAgent };
+//# sourceMappingURL=contract-spec-agent.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contract-spec-agent.js","names":["z","ToolLoopAgent"],"sources":["../../src/agent/contract-spec-agent.ts"],"sourcesContent":["import {\n  Experimental_Agent as ToolLoopAgent,\n  type LanguageModel,\n  stepCountIs,\n  type StepResult,\n  type Tool,\n  type ToolSet,\n} from 'ai';\nimport * as z from 'zod';\nimport type { KnowledgeRetriever } from '@contractspec/lib.knowledge/retriever';\nimport type { AgentSpec } from '../spec/spec';\nimport { agentKey } from '../spec/spec';\nimport type {\n  AgentCallOptions,\n  AgentGenerateParams,\n  AgentGenerateResult,\n  AgentStreamParams,\n  ToolHandler,\n} from '../types';\nimport { specToolsToAISDKTools } from '../tools/tool-adapter';\nimport { createKnowledgeQueryTool } from '../tools/knowledge-tool';\nimport { injectStaticKnowledge } from '../knowledge/injector';\nimport { type AgentSessionStore, generateSessionId } from '../session/store';\nimport { type TelemetryCollector, trackAgentStep } from '../telemetry/adapter';\n\n/**\n * Call options schema for AI SDK v6.\n * Maps ContractSpec's tenant/actor system to AI SDK callOptionsSchema.\n */\nconst ContractSpecCallOptionsSchema = z.object({\n  tenantId: z.string().optional(),\n  actorId: z.string().optional(),\n  sessionId: z.string().optional(),\n  // Zod v4: z.record() requires both key and value schemas\n  metadata: z.record(z.string(), z.unknown()).optional(),\n});\n\n/**\n * Type for tool with execute function (compatible with AI SDK Tool)\n * Using `any` for broad compatibility with AI SDK tool types\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype ExecutableTool = Tool<any, any>;\n\n/**\n * Configuration for creating a ContractSpecAgent.\n */\nexport interface ContractSpecAgentConfig {\n  /** The agent specification */\n  spec: AgentSpec;\n  /** AI SDK language model */\n  model: LanguageModel;\n  /** Map of tool name to handler function */\n  toolHandlers: Map<string, ToolHandler>;\n  /** Optional knowledge retriever for RAG */\n  knowledgeRetriever?: KnowledgeRetriever;\n  /** Optional session store for persistence */\n  sessionStore?: AgentSessionStore;\n  /** Optional telemetry collector for evolution */\n  telemetryCollector?: TelemetryCollector;\n  /** Additional AI SDK tools (e.g., from MCP servers) */\n  additionalTools?: Record<string, ExecutableTool>;\n}\n\n/**\n * ContractSpec Agent implementation using AI SDK v6.\n *\n * Integrates ContractSpec's spec-first governance with AI SDK's\n * ToolLoopAgent, providing:\n * - Spec-defined tools with type-safe handlers\n * - Hybrid knowledge injection (static + dynamic RAG)\n * - Session persistence\n * - Telemetry for evolution\n * - MCP interoperability\n */\nexport class ContractSpecAgent {\n  readonly version = 'agent-v1';\n  readonly id: string;\n  readonly spec: AgentSpec;\n  readonly tools: Record<string, ExecutableTool>;\n\n  private readonly inner: ToolLoopAgent<\n    z.infer<typeof ContractSpecCallOptionsSchema>,\n    ToolSet,\n    never\n  >;\n  private readonly config: ContractSpecAgentConfig;\n  private instructions: string;\n\n  private constructor(\n    config: ContractSpecAgentConfig,\n    instructions: string,\n    tools: Record<string, ExecutableTool>\n  ) {\n    this.config = config;\n    this.spec = config.spec;\n    this.id = agentKey(config.spec.meta);\n    this.tools = tools;\n    this.instructions = instructions;\n\n    // Create the inner ToolLoopAgent with AI SDK v6 settings\n    this.inner = new ToolLoopAgent({\n      model: config.model,\n      instructions,\n      tools: tools as ToolSet,\n      // Use stopWhen instead of maxSteps (AI SDK v6 API)\n      stopWhen: stepCountIs(config.spec.maxSteps ?? 10),\n      // Schema for call options (tenant/actor context)\n      callOptionsSchema: ContractSpecCallOptionsSchema,\n      // Step-level telemetry callback\n      onStepFinish: async (step: StepResult<ToolSet>) => {\n        await this.handleStepFinish(step);\n      },\n    });\n  }\n\n  /**\n   * Create a ContractSpecAgent instance.\n   * This is async because knowledge injection may need to fetch static content.\n   */\n  static async create(\n    config: ContractSpecAgentConfig\n  ): Promise<ContractSpecAgent> {\n    // 1. Inject static knowledge into instructions\n    const instructions = await injectStaticKnowledge(\n      config.spec.instructions,\n      config.spec.knowledge ?? [],\n      config.knowledgeRetriever\n    );\n\n    // 2. Build tools from spec\n    const specTools = specToolsToAISDKTools(\n      config.spec.tools,\n      config.toolHandlers,\n      { agentId: agentKey(config.spec.meta) }\n    );\n\n    // 3. Add dynamic knowledge query tool\n    const knowledgeTool = config.knowledgeRetriever\n      ? createKnowledgeQueryTool(\n          config.knowledgeRetriever,\n          config.spec.knowledge ?? []\n        )\n      : null;\n\n    // 4. Combine all tools\n    const tools: Record<string, ExecutableTool> = {\n      ...specTools,\n      ...(knowledgeTool ? { query_knowledge: knowledgeTool } : {}),\n      ...(config.additionalTools ?? {}),\n    };\n\n    return new ContractSpecAgent(config, instructions, tools);\n  }\n\n  /**\n   * Generate a response (non-streaming).\n   */\n  async generate(params: AgentGenerateParams): Promise<AgentGenerateResult> {\n    const sessionId = params.options?.sessionId ?? generateSessionId();\n\n    // Ensure session exists\n    if (this.config.sessionStore) {\n      const existing = await this.config.sessionStore.get(sessionId);\n      if (!existing) {\n        await this.config.sessionStore.create({\n          sessionId,\n          agentId: this.id,\n          tenantId: params.options?.tenantId,\n          actorId: params.options?.actorId,\n          status: 'running',\n          messages: [],\n          steps: [],\n          metadata: params.options?.metadata,\n        });\n      }\n    }\n\n    // Build prompt with optional system override\n    const prompt = params.systemOverride\n      ? `${this.instructions}\\n\\n${params.systemOverride}\\n\\n${params.prompt}`\n      : params.prompt;\n\n    // AI SDK v6: maxSteps is controlled via stopWhen in agent settings\n    const result = await this.inner.generate({\n      prompt,\n      abortSignal: params.signal,\n      options: {\n        tenantId: params.options?.tenantId,\n        actorId: params.options?.actorId,\n        sessionId,\n        metadata: params.options?.metadata,\n      },\n    });\n\n    // Update session status\n    if (this.config.sessionStore) {\n      await this.config.sessionStore.update(sessionId, {\n        status: 'completed',\n      });\n    }\n\n    return {\n      text: result.text,\n      steps: result.steps,\n      // Map AI SDK types to our simplified types\n      toolCalls: result.toolCalls.map((tc) => ({\n        type: 'tool-call' as const,\n        toolCallId: tc.toolCallId,\n        toolName: tc.toolName,\n        args: 'args' in tc ? tc.args : 'input' in tc ? tc.input : undefined,\n      })),\n      toolResults: result.toolResults.map((tr) => ({\n        type: 'tool-result' as const,\n        toolCallId: tr.toolCallId,\n        toolName: tr.toolName,\n        output: tr.output,\n      })),\n      finishReason: result.finishReason,\n      usage: result.usage,\n    };\n  }\n\n  /**\n   * Stream a response with real-time updates.\n   */\n  async stream(params: AgentStreamParams) {\n    const sessionId = params.options?.sessionId ?? generateSessionId();\n\n    const prompt = params.systemOverride\n      ? `${this.instructions}\\n\\n${params.systemOverride}\\n\\n${params.prompt}`\n      : params.prompt;\n\n    // AI SDK v6: maxSteps is controlled via stopWhen in agent settings\n    // onStepFinish callback is already set in agent construction\n    return this.inner.stream({\n      prompt,\n      abortSignal: params.signal,\n      options: {\n        tenantId: params.options?.tenantId,\n        actorId: params.options?.actorId,\n        sessionId,\n        metadata: params.options?.metadata,\n      },\n    });\n  }\n\n  /**\n   * Handle step completion for persistence and telemetry.\n   */\n  private async handleStepFinish(step: StepResult<ToolSet>): Promise<void> {\n    // 1. Persist to session store\n    const sessionId = (step as { options?: AgentCallOptions }).options\n      ?.sessionId;\n    if (sessionId && this.config.sessionStore) {\n      await this.config.sessionStore.appendStep(sessionId, step);\n    }\n\n    // 2. Feed telemetry to evolution engine\n    if (this.config.telemetryCollector) {\n      await trackAgentStep(this.config.telemetryCollector, this.id, step);\n    }\n  }\n}\n"],"mappings":"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"}

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,4 @@
+import { ContractSpecAgent } from "./contract-spec-agent.js";
+import { AgentFactory, createAgentFactory } from "./agent-factory.js";
+
+export { AgentFactory, ContractSpecAgent, 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,3 @@
+import { ApprovalWorkflow, InMemoryApprovalStore, createApprovalWorkflow } from "./workflow.js";
+
+export { ApprovalWorkflow, InMemoryApprovalStore, createApprovalWorkflow };