@contractspec/lib.ai-agent 1.44.0

package/dist/tools/knowledge-tool.js

@@ -0,0 +1,54 @@
+import { tool } from "ai";
+import * as z$1 from "zod";
+
+//#region src/tools/knowledge-tool.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
+*/
+function createKnowledgeQueryTool(retriever, knowledgeRefs) {
+	const optionalSpaces = knowledgeRefs.filter((k) => !k.required).map((k) => k.key).filter((key) => retriever.supportsSpace(key));
+	if (optionalSpaces.length === 0) return null;
+	return tool({
+		description: `Query knowledge bases for relevant information. Use this tool when you need to look up specific information that may not be in your context.
+
+Available knowledge spaces:
+${knowledgeRefs.filter((k) => !k.required && retriever.supportsSpace(k.key)).map((k) => `- ${k.key}: ${k.instructions ?? "Knowledge space"}`).join("\n")}`,
+		inputSchema: z$1.object({
+			query: z$1.string().describe("The question or search query to find relevant information"),
+			spaceKey: z$1.enum(optionalSpaces).optional().describe("Specific knowledge space to query. If omitted, searches all available spaces."),
+			topK: z$1.number().optional().default(5).describe("Maximum number of results to return")
+		}),
+		execute: async ({ query, spaceKey, topK }) => {
+			const spacesToSearch = spaceKey ? [spaceKey] : optionalSpaces;
+			const allResults = [];
+			for (const space of spacesToSearch) try {
+				const results = await retriever.retrieve(query, {
+					spaceKey: space,
+					topK: topK ?? 5
+				});
+				for (const result of results) allResults.push({
+					space,
+					content: result.content,
+					score: result.score
+				});
+			} catch (error) {
+				console.warn(`Failed to query knowledge space ${space}:`, error);
+			}
+			if (allResults.length === 0) return "No relevant information found in the knowledge bases.";
+			allResults.sort((a, b) => b.score - a.score);
+			return allResults.slice(0, topK ?? 5).map((r, i) => `[Source ${i + 1} - ${r.space}] (relevance: ${(r.score * 100).toFixed(0)}%)\n${r.content}`).join("\n\n---\n\n");
+		}
+	});
+}
+
+//#endregion
+export { createKnowledgeQueryTool };
+//# sourceMappingURL=knowledge-tool.js.map

package/dist/tools/knowledge-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-tool.js","names":["z","allResults: { space: string; content: string; score: number }[]"],"sources":["../../src/tools/knowledge-tool.ts"],"sourcesContent":["import { tool, type Tool } from 'ai';\nimport * as z from 'zod';\nimport type { KnowledgeRetriever } from '@contractspec/lib.knowledge/retriever';\nimport type { AgentKnowledgeRef } from '../spec/spec';\n\n/**\n * Create a knowledge query tool for dynamic RAG.\n *\n * This tool allows the agent to query optional knowledge spaces\n * at runtime. Required knowledge is injected statically via\n * the knowledge injector.\n *\n * @param retriever - The knowledge retriever to use\n * @param knowledgeRefs - Knowledge references from the agent spec\n * @returns AI SDK CoreTool for knowledge queries\n */\nexport function createKnowledgeQueryTool(\n  retriever: KnowledgeRetriever,\n  knowledgeRefs: AgentKnowledgeRef[]\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): Tool<any, any> | null {\n  // Only include optional (non-required) knowledge spaces\n  const optionalSpaces = knowledgeRefs\n    .filter((k) => !k.required)\n    .map((k) => k.key)\n    .filter((key) => retriever.supportsSpace(key));\n\n  if (optionalSpaces.length === 0) {\n    return null;\n  }\n\n  // Build space descriptions for the tool\n  const spaceDescriptions = knowledgeRefs\n    .filter((k) => !k.required && retriever.supportsSpace(k.key))\n    .map((k) => `- ${k.key}: ${k.instructions ?? 'Knowledge space'}`)\n    .join('\\n');\n\n  return tool({\n    description: `Query knowledge bases for relevant information. Use this tool when you need to look up specific information that may not be in your context.\n\nAvailable knowledge spaces:\n${spaceDescriptions}`,\n    // AI SDK v6 uses inputSchema instead of parameters\n    inputSchema: z.object({\n      query: z\n        .string()\n        .describe('The question or search query to find relevant information'),\n      spaceKey: z\n        .enum(optionalSpaces as [string, ...string[]])\n        .optional()\n        .describe(\n          'Specific knowledge space to query. If omitted, searches all available spaces.'\n        ),\n      topK: z\n        .number()\n        .optional()\n        .default(5)\n        .describe('Maximum number of results to return'),\n    }),\n    execute: async ({ query, spaceKey, topK }) => {\n      const spacesToSearch = spaceKey ? [spaceKey] : optionalSpaces;\n      const allResults: { space: string; content: string; score: number }[] =\n        [];\n\n      for (const space of spacesToSearch) {\n        try {\n          const results = await retriever.retrieve(query, {\n            spaceKey: space,\n            topK: topK ?? 5,\n          });\n\n          for (const result of results) {\n            allResults.push({\n              space,\n              content: result.content,\n              score: result.score,\n            });\n          }\n        } catch (error) {\n          // Log but don't fail on individual space errors\n          console.warn(`Failed to query knowledge space ${space}:`, error);\n        }\n      }\n\n      if (allResults.length === 0) {\n        return 'No relevant information found in the knowledge bases.';\n      }\n\n      // Sort by score and format results\n      allResults.sort((a, b) => b.score - a.score);\n      const topResults = allResults.slice(0, topK ?? 5);\n\n      return topResults\n        .map(\n          (r, i) =>\n            `[Source ${i + 1} - ${r.space}] (relevance: ${(r.score * 100).toFixed(0)}%)\\n${r.content}`\n        )\n        .join('\\n\\n---\\n\\n');\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgBA,SAAgB,yBACd,WACA,eAEuB;CAEvB,MAAM,iBAAiB,cACpB,QAAQ,MAAM,CAAC,EAAE,SAAS,CAC1B,KAAK,MAAM,EAAE,IAAI,CACjB,QAAQ,QAAQ,UAAU,cAAc,IAAI,CAAC;AAEhD,KAAI,eAAe,WAAW,EAC5B,QAAO;AAST,QAAO,KAAK;EACV,aAAa;;;EANW,cACvB,QAAQ,MAAM,CAAC,EAAE,YAAY,UAAU,cAAc,EAAE,IAAI,CAAC,CAC5D,KAAK,MAAM,KAAK,EAAE,IAAI,IAAI,EAAE,gBAAgB,oBAAoB,CAChE,KAAK,KAAK;EAQX,aAAaA,IAAE,OAAO;GACpB,OAAOA,IACJ,QAAQ,CACR,SAAS,4DAA4D;GACxE,UAAUA,IACP,KAAK,eAAwC,CAC7C,UAAU,CACV,SACC,gFACD;GACH,MAAMA,IACH,QAAQ,CACR,UAAU,CACV,QAAQ,EAAE,CACV,SAAS,sCAAsC;GACnD,CAAC;EACF,SAAS,OAAO,EAAE,OAAO,UAAU,WAAW;GAC5C,MAAM,iBAAiB,WAAW,CAAC,SAAS,GAAG;GAC/C,MAAMC,aACJ,EAAE;AAEJ,QAAK,MAAM,SAAS,eAClB,KAAI;IACF,MAAM,UAAU,MAAM,UAAU,SAAS,OAAO;KAC9C,UAAU;KACV,MAAM,QAAQ;KACf,CAAC;AAEF,SAAK,MAAM,UAAU,QACnB,YAAW,KAAK;KACd;KACA,SAAS,OAAO;KAChB,OAAO,OAAO;KACf,CAAC;YAEG,OAAO;AAEd,YAAQ,KAAK,mCAAmC,MAAM,IAAI,MAAM;;AAIpE,OAAI,WAAW,WAAW,EACxB,QAAO;AAIT,cAAW,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM;AAG5C,UAFmB,WAAW,MAAM,GAAG,QAAQ,EAAE,CAG9C,KACE,GAAG,MACF,WAAW,IAAI,EAAE,KAAK,EAAE,MAAM,iBAAiB,EAAE,QAAQ,KAAK,QAAQ,EAAE,CAAC,MAAM,EAAE,UACpF,CACA,KAAK,cAAc;;EAEzB,CAAC"}

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

@@ -0,0 +1,59 @@
+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 };
+//# sourceMappingURL=mcp-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.d.ts","names":[],"sources":["../../src/tools/mcp-client.ts"],"sourcesContent":[],"mappings":";;;;;;AAOA;AAciB,UAdA,eAAA,CAce;EAER;EAAf,IAAA,EAAA,MAAA;EAEQ;EAAO,OAAA,EAAA,MAAA;EAyBF;EACZ,IAAA,CAAA,EAAA,MAAA,EAAA;EACC;EAAR,GAAA,CAAA,EArCK,MAqCL,CAAA,MAAA,EAAA,MAAA,CAAA;;AAsBH;;;AAEG,UAvDc,eAAA,CAuDd;EAAO;SArDD,eAAe;;iBAEP;;;;;;;;;;;;;;;;;;;;;;;;iBAyBK,gBAAA,SACZ,kBACP,QAAQ;;;;;;;iBAsBW,iBAAA,UACX,oBACR,QAAQ"}

package/dist/tools/mcp-client.js

@@ -0,0 +1,58 @@
+import { experimental_createMCPClient } from "@ai-sdk/mcp";
+import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";
+
+//#region src/tools/mcp-client.ts
+/**
+* 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();
+* ```
+*/
+async function mcpServerToTools(config) {
+	const client = await experimental_createMCPClient({ transport: new Experimental_StdioMCPTransport({
+		command: config.command,
+		args: config.args,
+		env: config.env
+	}) });
+	return {
+		tools: await client.tools(),
+		cleanup: () => client.close()
+	};
+}
+/**
+* Create multiple MCP tool sets from configurations.
+*
+* @param configs - Array of MCP server configurations
+* @returns Combined tools and cleanup function
+*/
+async function createMcpToolsets(configs) {
+	const results = await Promise.all(configs.map(mcpServerToTools));
+	const combinedTools = {};
+	for (const result of results) Object.assign(combinedTools, result.tools);
+	return {
+		tools: combinedTools,
+		cleanup: async () => {
+			await Promise.all(results.map((r) => r.cleanup()));
+		}
+	};
+}
+
+//#endregion
+export { createMcpToolsets, mcpServerToTools };
+//# sourceMappingURL=mcp-client.js.map

package/dist/tools/mcp-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.js","names":["StdioClientTransport","combinedTools: Record<string, Tool<unknown, unknown>>"],"sources":["../../src/tools/mcp-client.ts"],"sourcesContent":["import { experimental_createMCPClient } from '@ai-sdk/mcp';\nimport { Experimental_StdioMCPTransport as StdioClientTransport } from '@ai-sdk/mcp/mcp-stdio';\nimport type { Tool } from 'ai';\n\n/**\n * Configuration for connecting to an MCP server.\n */\nexport interface McpClientConfig {\n  /** Display name for the MCP server */\n  name: string;\n  /** Command to spawn the MCP server process */\n  command: string;\n  /** Arguments to pass to the command */\n  args?: string[];\n  /** Environment variables for the process */\n  env?: Record<string, string>;\n}\n\n/**\n * Result of creating an MCP client with tools.\n */\nexport interface McpClientResult {\n  /** AI SDK tools from the MCP server */\n  tools: Record<string, Tool<unknown, unknown>>;\n  /** Cleanup function to close the connection */\n  cleanup: () => Promise<void>;\n}\n\n/**\n * Create AI SDK tools from an MCP server.\n *\n * This adapter allows ContractSpec agents to consume tools\n * from external MCP servers (e.g., filesystem, database, etc.).\n *\n * @param config - MCP server configuration\n * @returns Tools and cleanup function\n *\n * @example\n * ```typescript\n * const { tools, cleanup } = await mcpServerToTools({\n *   name: 'filesystem',\n *   command: 'npx',\n *   args: ['-y', '@modelcontextprotocol/server-filesystem', '/path'],\n * });\n *\n * // Use tools in agent...\n *\n * await cleanup();\n * ```\n */\nexport async function mcpServerToTools(\n  config: McpClientConfig\n): Promise<McpClientResult> {\n  const transport = new StdioClientTransport({\n    command: config.command,\n    args: config.args,\n    env: config.env,\n  });\n\n  const client = await experimental_createMCPClient({ transport });\n  const tools = await client.tools();\n\n  return {\n    tools: tools as Record<string, Tool<unknown, unknown>>,\n    cleanup: () => client.close(),\n  };\n}\n\n/**\n * Create multiple MCP tool sets from configurations.\n *\n * @param configs - Array of MCP server configurations\n * @returns Combined tools and cleanup function\n */\nexport async function createMcpToolsets(\n  configs: McpClientConfig[]\n): Promise<McpClientResult> {\n  const results = await Promise.all(configs.map(mcpServerToTools));\n\n  const combinedTools: Record<string, Tool<unknown, unknown>> = {};\n  for (const result of results) {\n    Object.assign(combinedTools, result.tools);\n  }\n\n  return {\n    tools: combinedTools,\n    cleanup: async () => {\n      await Promise.all(results.map((r) => r.cleanup()));\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,eAAsB,iBACpB,QAC0B;CAO1B,MAAM,SAAS,MAAM,6BAA6B,EAAE,WANlC,IAAIA,+BAAqB;EACzC,SAAS,OAAO;EAChB,MAAM,OAAO;EACb,KAAK,OAAO;EACb,CAAC,EAE6D,CAAC;AAGhE,QAAO;EACL,OAHY,MAAM,OAAO,OAAO;EAIhC,eAAe,OAAO,OAAO;EAC9B;;;;;;;;AASH,eAAsB,kBACpB,SAC0B;CAC1B,MAAM,UAAU,MAAM,QAAQ,IAAI,QAAQ,IAAI,iBAAiB,CAAC;CAEhE,MAAMC,gBAAwD,EAAE;AAChE,MAAK,MAAM,UAAU,QACnB,QAAO,OAAO,eAAe,OAAO,MAAM;AAG5C,QAAO;EACL,OAAO;EACP,SAAS,YAAY;AACnB,SAAM,QAAQ,IAAI,QAAQ,KAAK,MAAM,EAAE,SAAS,CAAC,CAAC;;EAErD"}

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

@@ -0,0 +1,46 @@
+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 };
+//# sourceMappingURL=mcp-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","names":[],"sources":["../../src/tools/mcp-server.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAyBA;;;;;AA+EA;AAcA;;;;;;;;;;;iBA7FgB,gBAAA,QACP,yBACD,YACL;;;;UA4Ec,oBAAA;;SAER;;QAED;;;;;;;;;iBAUQ,oBAAA,SAA6B,uBAAuB"}

package/dist/tools/mcp-server.js

@@ -0,0 +1,69 @@
+import { jsonSchemaToZodSafe } from "../schema/json-schema-to-zod.js";
+import * as z$1 from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/tools/mcp-server.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);
+* ```
+*/
+function agentToMcpServer(agent, spec) {
+	const server = new McpServer({
+		name: spec.meta.key,
+		version: `${spec.meta.version}`
+	});
+	server.registerTool(spec.meta.key, {
+		description: spec.description ?? `Interact with ${spec.meta.key} agent`,
+		inputSchema: z$1.object({
+			message: z$1.string().describe("The message or query to send to the agent"),
+			sessionId: z$1.string().optional().describe("Optional session ID to continue a conversation")
+		})
+	}, async (args) => {
+		const { message, sessionId } = args;
+		return { content: [{
+			type: "text",
+			text: (await agent.generate({
+				prompt: message,
+				options: { sessionId }
+			})).text
+		}] };
+	});
+	for (const toolConfig of spec.tools) {
+		const inputSchema = toolConfig.schema ? jsonSchemaToZodSafe(toolConfig.schema) : z$1.object({});
+		server.registerTool(`${spec.meta.key}.${toolConfig.name}`, {
+			description: toolConfig.description ?? `Execute ${toolConfig.name} tool`,
+			inputSchema
+		}, async (args) => {
+			return { content: [{
+				type: "text",
+				text: (await agent.generate({ prompt: `Execute the ${toolConfig.name} tool with the following arguments: ${JSON.stringify(args)}` })).text
+			}] };
+		});
+	}
+	return server;
+}
+/**
+* Create an MCP server from configuration.
+*/
+function createAgentMcpServer(config) {
+	return agentToMcpServer(config.agent, config.spec);
+}
+
+//#endregion
+export { agentToMcpServer, createAgentMcpServer };
+//# sourceMappingURL=mcp-server.js.map

package/dist/tools/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","names":["z"],"sources":["../../src/tools/mcp-server.ts"],"sourcesContent":["import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport * as z from 'zod';\nimport type { AgentSpec } from '../spec/spec';\nimport type { ContractSpecAgent } from '../agent/contract-spec-agent';\nimport { jsonSchemaToZodSafe } from '../schema/json-schema-to-zod';\n\n/**\n * Generate an MCP server that exposes a ContractSpec agent as a tool.\n *\n * This allows other AI agents (e.g., Claude Desktop, Cursor) to use\n * your ContractSpec agents as tools, enabling agent-to-agent composition.\n *\n * @param agent - The ContractSpec agent to expose\n * @param spec - The agent specification\n * @returns MCP Server instance\n *\n * @example\n * ```typescript\n * const server = agentToMcpServer(myAgent, myAgentSpec);\n *\n * // Run via stdio transport\n * const transport = new StdioServerTransport();\n * await server.connect(transport);\n * ```\n */\nexport function agentToMcpServer(\n  agent: ContractSpecAgent,\n  spec: AgentSpec\n): McpServer {\n  const server = new McpServer({\n    name: spec.meta.key,\n    version: `${spec.meta.version}`,\n  });\n\n  // Expose agent as a conversational tool using registerTool\n  server.registerTool(\n    spec.meta.key,\n    {\n      description: spec.description ?? `Interact with ${spec.meta.key} agent`,\n      inputSchema: z.object({\n        message: z\n          .string()\n          .describe('The message or query to send to the agent'),\n        sessionId: z\n          .string()\n          .optional()\n          .describe('Optional session ID to continue a conversation'),\n      }),\n    },\n    async (args) => {\n      const { message, sessionId } = args;\n\n      const result = await agent.generate({\n        prompt: message,\n        options: { sessionId },\n      });\n\n      return {\n        content: [\n          {\n            type: 'text',\n            text: result.text,\n          },\n        ],\n      };\n    }\n  );\n\n  // Expose individual tools from the agent spec\n  for (const toolConfig of spec.tools) {\n    const inputSchema = toolConfig.schema\n      ? jsonSchemaToZodSafe(toolConfig.schema)\n      : z.object({});\n\n    server.registerTool(\n      `${spec.meta.key}.${toolConfig.name}`,\n      {\n        description:\n          toolConfig.description ?? `Execute ${toolConfig.name} tool`,\n        inputSchema,\n      },\n      async (args) => {\n        const result = await agent.generate({\n          prompt: `Execute the ${toolConfig.name} tool with the following arguments: ${JSON.stringify(args)}`,\n        });\n\n        return {\n          content: [\n            {\n              type: 'text',\n              text: result.text,\n            },\n          ],\n        };\n      }\n    );\n  }\n\n  return server;\n}\n\n/**\n * Configuration for running an agent as an MCP server.\n */\nexport interface AgentMcpServerConfig {\n  /** The agent to expose */\n  agent: ContractSpecAgent;\n  /** The agent specification */\n  spec: AgentSpec;\n  /** Optional server name override */\n  name?: string;\n  /** Optional version override */\n  version?: string;\n}\n\n/**\n * Create an MCP server from configuration.\n */\nexport function createAgentMcpServer(config: AgentMcpServerConfig): McpServer {\n  return agentToMcpServer(config.agent, config.spec);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,iBACd,OACA,MACW;CACX,MAAM,SAAS,IAAI,UAAU;EAC3B,MAAM,KAAK,KAAK;EAChB,SAAS,GAAG,KAAK,KAAK;EACvB,CAAC;AAGF,QAAO,aACL,KAAK,KAAK,KACV;EACE,aAAa,KAAK,eAAe,iBAAiB,KAAK,KAAK,IAAI;EAChE,aAAaA,IAAE,OAAO;GACpB,SAASA,IACN,QAAQ,CACR,SAAS,4CAA4C;GACxD,WAAWA,IACR,QAAQ,CACR,UAAU,CACV,SAAS,iDAAiD;GAC9D,CAAC;EACH,EACD,OAAO,SAAS;EACd,MAAM,EAAE,SAAS,cAAc;AAO/B,SAAO,EACL,SAAS,CACP;GACE,MAAM;GACN,OATS,MAAM,MAAM,SAAS;IAClC,QAAQ;IACR,SAAS,EAAE,WAAW;IACvB,CAAC,EAMiB;GACd,CACF,EACF;GAEJ;AAGD,MAAK,MAAM,cAAc,KAAK,OAAO;EACnC,MAAM,cAAc,WAAW,SAC3B,oBAAoB,WAAW,OAAO,GACtCA,IAAE,OAAO,EAAE,CAAC;AAEhB,SAAO,aACL,GAAG,KAAK,KAAK,IAAI,GAAG,WAAW,QAC/B;GACE,aACE,WAAW,eAAe,WAAW,WAAW,KAAK;GACvD;GACD,EACD,OAAO,SAAS;AAKd,UAAO,EACL,SAAS,CACP;IACE,MAAM;IACN,OARS,MAAM,MAAM,SAAS,EAClC,QAAQ,eAAe,WAAW,KAAK,sCAAsC,KAAK,UAAU,KAAK,IAClG,CAAC,EAMiB;IACd,CACF,EACF;IAEJ;;AAGH,QAAO;;;;;AAoBT,SAAgB,qBAAqB,QAAyC;AAC5E,QAAO,iBAAiB,OAAO,OAAO,OAAO,KAAK"}

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

@@ -0,0 +1,50 @@
+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 };
+//# sourceMappingURL=tool-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-adapter.d.ts","names":[],"sources":["../../src/tools/tool-adapter.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAcA;;;;;;AAIO,iBAJS,mBAAA,CAIT,QAAA,EAHK,eAGL,EAAA,OAAA,EAFI,WAEJ,EAAA,OAAA,CAAA,EADI,OACJ,CADY,oBACZ,CAAA,CAAA,EAAJ,IAAI,CAAA,GAAA,EAAA,GAAA,CAAA;AA6BP;;;;;;;;AAIS,iBAJO,qBAAA,CAIP,SAAA,EAHI,eAGJ,EAAA,EAAA,QAAA,EAFG,GAEH,CAAA,MAAA,EAFe,WAEf,CAAA,EAAA,OAAA,CAAA,EADE,OACF,CADU,oBACV,CAAA,CAAA,EAAN,MAAM,CAAA,MAAA,EAAS,IAAT,CAAA,GAAA,EAAA,GAAA,CAAA,CAAA;AAyBT;;;;;;;;;;AAsBgB,iBAtBA,iBAsBiB,CAAA,SAAA,OAAA,EAAA,UAAA,MAAA,CAAA,CAAA,OAAA,EAAA,CAAA,KAAA,EApBtB,MAoBsB,EAAA,OAAA,EAnBpB,oBAmBoB,EAAA,GAlB1B,OAkB0B,CAlBlB,OAkBkB,CAAA,GAlBP,OAkBO,CAAA,EAjB9B,WAiB8B,CAjBlB,MAiBkB,EAjBV,OAiBU,CAAA;;;;;;;;;;;;iBAAjB,iBAAA,cACD,eAAe,eAC3B,YAAY"}

package/dist/tools/tool-adapter.js

@@ -0,0 +1,80 @@
+import { jsonSchemaToZodSafe } from "../schema/json-schema-to-zod.js";
+import { tool } from "ai";
+
+//#region src/tools/tool-adapter.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
+*/
+function specToolToAISDKTool(specTool, handler, context = {}) {
+	return tool({
+		description: specTool.description ?? specTool.name,
+		inputSchema: jsonSchemaToZodSafe(specTool.schema),
+		needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,
+		execute: async (input) => {
+			const result = await handler(input, {
+				agentId: context.agentId ?? "unknown",
+				sessionId: context.sessionId ?? "unknown",
+				tenantId: context.tenantId,
+				actorId: context.actorId,
+				metadata: context.metadata,
+				signal: context.signal
+			});
+			return typeof result === "string" ? result : JSON.stringify(result);
+		}
+	});
+}
+/**
+* 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
+*/
+function specToolsToAISDKTools(specTools, handlers, context = {}) {
+	const tools = {};
+	for (const specTool of specTools) {
+		const handler = handlers.get(specTool.name);
+		if (!handler) throw new Error(`Missing handler for tool: ${specTool.name}`);
+		tools[specTool.name] = specToolToAISDKTool(specTool, handler, context);
+	}
+	return tools;
+}
+/**
+* Type-safe tool handler builder.
+*
+* @example
+* ```typescript
+* const handler = createToolHandler<{ query: string }>((input, ctx) => {
+*   return `Searched for: ${input.query}`;
+* });
+* ```
+*/
+function createToolHandler(handler) {
+	return async (input, context) => {
+		return handler(input, context);
+	};
+}
+/**
+* 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}`,
+* });
+* ```
+*/
+function buildToolHandlers(handlersObj) {
+	return new Map(Object.entries(handlersObj));
+}
+
+//#endregion
+export { buildToolHandlers, createToolHandler, specToolToAISDKTool, specToolsToAISDKTools };
+//# sourceMappingURL=tool-adapter.js.map

package/dist/tools/tool-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-adapter.js","names":["tools: Record<string, Tool<any, any>>"],"sources":["../../src/tools/tool-adapter.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { tool, type Tool } from 'ai';\nimport type { AgentToolConfig } from '../spec/spec';\nimport type { ToolExecutionContext, ToolHandler } from '../types';\nimport { jsonSchemaToZodSafe } from '../schema/json-schema-to-zod';\n\n/**\n * Convert ContractSpec AgentToolConfig to AI SDK CoreTool.\n *\n * @param specTool - The tool configuration from AgentSpec\n * @param handler - The handler function for the tool\n * @param context - Partial context to inject into handler calls\n * @returns AI SDK CoreTool\n */\nexport function specToolToAISDKTool(\n  specTool: AgentToolConfig,\n  handler: ToolHandler,\n  context: Partial<ToolExecutionContext> = {}\n): Tool<any, any> {\n  return tool({\n    description: specTool.description ?? specTool.name,\n    // AI SDK v6 uses inputSchema instead of parameters\n    inputSchema: jsonSchemaToZodSafe(specTool.schema),\n    // AI SDK v6 native approval support\n    needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,\n    execute: async (input) => {\n      const result = await handler(input, {\n        agentId: context.agentId ?? 'unknown',\n        sessionId: context.sessionId ?? 'unknown',\n        tenantId: context.tenantId,\n        actorId: context.actorId,\n        metadata: context.metadata,\n        signal: context.signal,\n      });\n      return typeof result === 'string' ? result : JSON.stringify(result);\n    },\n  });\n}\n\n/**\n * Convert multiple ContractSpec tool configs to AI SDK tools.\n *\n * @param specTools - Array of tool configurations\n * @param handlers - Map of tool name to handler function\n * @param context - Partial context to inject into handler calls\n * @returns Record of AI SDK tools keyed by name\n */\nexport function specToolsToAISDKTools(\n  specTools: AgentToolConfig[],\n  handlers: Map<string, ToolHandler>,\n  context: Partial<ToolExecutionContext> = {}\n): Record<string, Tool<any, any>> {\n  const tools: Record<string, Tool<any, any>> = {};\n\n  for (const specTool of specTools) {\n    const handler = handlers.get(specTool.name);\n    if (!handler) {\n      throw new Error(`Missing handler for tool: ${specTool.name}`);\n    }\n\n    tools[specTool.name] = specToolToAISDKTool(specTool, handler, context);\n  }\n\n  return tools;\n}\n\n/**\n * Type-safe tool handler builder.\n *\n * @example\n * ```typescript\n * const handler = createToolHandler<{ query: string }>((input, ctx) => {\n *   return `Searched for: ${input.query}`;\n * });\n * ```\n */\nexport function createToolHandler<TInput = unknown, TOutput = string>(\n  handler: (\n    input: TInput,\n    context: ToolExecutionContext\n  ) => Promise<TOutput> | TOutput\n): ToolHandler<TInput, TOutput> {\n  return async (input, context) => {\n    return handler(input as TInput, context);\n  };\n}\n\n/**\n * Build a tool handlers map from an object.\n *\n * @example\n * ```typescript\n * const handlers = buildToolHandlers({\n *   search: async (input: { query: string }) => `Found: ${input.query}`,\n *   calculate: async (input: { a: number, b: number }) => `${input.a + input.b}`,\n * });\n * ```\n */\nexport function buildToolHandlers(\n  handlersObj: Record<string, ToolHandler>\n): Map<string, ToolHandler> {\n  return new Map(Object.entries(handlersObj));\n}\n"],"mappings":";;;;;;;;;;;;AAcA,SAAgB,oBACd,UACA,SACA,UAAyC,EAAE,EAC3B;AAChB,QAAO,KAAK;EACV,aAAa,SAAS,eAAe,SAAS;EAE9C,aAAa,oBAAoB,SAAS,OAAO;EAEjD,eAAe,SAAS,oBAAoB,CAAC,SAAS;EACtD,SAAS,OAAO,UAAU;GACxB,MAAM,SAAS,MAAM,QAAQ,OAAO;IAClC,SAAS,QAAQ,WAAW;IAC5B,WAAW,QAAQ,aAAa;IAChC,UAAU,QAAQ;IAClB,SAAS,QAAQ;IACjB,UAAU,QAAQ;IAClB,QAAQ,QAAQ;IACjB,CAAC;AACF,UAAO,OAAO,WAAW,WAAW,SAAS,KAAK,UAAU,OAAO;;EAEtE,CAAC;;;;;;;;;;AAWJ,SAAgB,sBACd,WACA,UACA,UAAyC,EAAE,EACX;CAChC,MAAMA,QAAwC,EAAE;AAEhD,MAAK,MAAM,YAAY,WAAW;EAChC,MAAM,UAAU,SAAS,IAAI,SAAS,KAAK;AAC3C,MAAI,CAAC,QACH,OAAM,IAAI,MAAM,6BAA6B,SAAS,OAAO;AAG/D,QAAM,SAAS,QAAQ,oBAAoB,UAAU,SAAS,QAAQ;;AAGxE,QAAO;;;;;;;;;;;;AAaT,SAAgB,kBACd,SAI8B;AAC9B,QAAO,OAAO,OAAO,YAAY;AAC/B,SAAO,QAAQ,OAAiB,QAAQ;;;;;;;;;;;;;;AAe5C,SAAgB,kBACd,aAC0B;AAC1B,QAAO,IAAI,IAAI,OAAO,QAAQ,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,146 @@
+import { LanguageModelUsage, ModelMessage, StepResult, ToolSet } from "ai";
+
+//#region src/types.d.ts
+
+/**
+ * Simplified tool call type for ContractSpec usage.
+ * Compatible with AI SDK v6 TypedToolCall.
+ */
+interface ToolCallInfo {
+  type: 'tool-call';
+  toolCallId: string;
+  toolName: string;
+  args: unknown;
+}
+/**
+ * Simplified tool result type for ContractSpec usage.
+ * Compatible with AI SDK v6 TypedToolResult.
+ */
+interface ToolResultInfo {
+  type: 'tool-result';
+  toolCallId: string;
+  toolName: string;
+  output: unknown;
+}
+/**
+ * Extended message type that adds metadata support to ModelMessage.
+ * Used for session memory tracking.
+ */
+interface AgentMessage {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string | {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+  }[];
+  metadata?: Record<string, string>;
+}
+type AgentStatus = 'idle' | 'running' | 'waiting' | 'completed' | 'failed' | 'escalated';
+type AgentEventName = 'agent.session.created' | 'agent.session.updated' | 'agent.step.started' | 'agent.step.completed' | 'agent.tool.called' | 'agent.tool.completed' | 'agent.tool.failed' | 'agent.tool.approval_requested' | 'agent.escalated' | 'agent.completed' | 'agent.failed';
+type AgentFinishReason = 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'error' | 'other' | 'unknown';
+interface AgentEventPayload {
+  sessionId: string;
+  agentId: string;
+  tenantId?: string;
+  stepIndex?: number;
+  toolName?: string;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Runtime context passed to agent calls via AI SDK v6 callOptionsSchema.
+ * Maps to ContractSpec's tenant/actor system.
+ */
+interface AgentCallOptions {
+  /** Tenant scoping for guardrails and data isolation */
+  tenantId?: string;
+  /** Unique end-user identifier (for personalization) */
+  actorId?: string;
+  /** Session to resume; new session created when omitted */
+  sessionId?: string;
+  /** Arbitrary metadata forwarded to events and tool handlers */
+  metadata?: Record<string, string>;
+}
+interface AgentSessionState {
+  sessionId: string;
+  agentId: string;
+  tenantId?: string;
+  actorId?: string;
+  status: AgentStatus;
+  messages: ModelMessage[];
+  steps: StepResult<ToolSet>[];
+  createdAt: Date;
+  updatedAt: Date;
+  metadata?: Record<string, string>;
+}
+interface AgentGenerateParams {
+  /** User prompt or message */
+  prompt: string;
+  /** System prompt override (appended to agent instructions) */
+  systemOverride?: string;
+  /** Runtime context options */
+  options?: AgentCallOptions;
+  /** Maximum number of steps/iterations */
+  maxSteps?: number;
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+}
+interface AgentStreamParams extends AgentGenerateParams {
+  /** Called when a step completes */
+  onStepFinish?: (step: StepResult<ToolSet>) => void | Promise<void>;
+}
+interface AgentGenerateResult<TOutput = string> {
+  /** The final text response */
+  text: string;
+  /** Structured output if configured */
+  output?: TOutput;
+  /** All steps taken during generation */
+  steps: StepResult<ToolSet>[];
+  /** All tool calls made during generation */
+  toolCalls: ToolCallInfo[];
+  /** All tool results */
+  toolResults: ToolResultInfo[];
+  /** Reason generation finished */
+  finishReason: AgentFinishReason;
+  /** Token usage statistics */
+  usage?: LanguageModelUsage;
+  /** Updated session state */
+  session?: AgentSessionState;
+  /** Whether approval is pending for a tool call */
+  pendingApproval?: {
+    toolName: string;
+    toolCallId: string;
+    args: unknown;
+  };
+}
+/**
+ * Context provided to tool handlers during execution.
+ */
+interface ToolExecutionContext {
+  agentId: string;
+  sessionId: string;
+  tenantId?: string;
+  actorId?: string;
+  metadata?: Record<string, string>;
+  signal?: AbortSignal;
+}
+/**
+ * Handler function for a tool.
+ */
+type ToolHandler<TInput = unknown, TOutput = string> = (input: TInput, context: ToolExecutionContext) => Promise<TOutput>;
+interface AgentStepMetrics {
+  agentId: string;
+  stepIndex: number;
+  toolCalls: {
+    toolName: string;
+    durationMs?: number;
+    success: boolean;
+    error?: string;
+  }[];
+  finishReason: string;
+  usage?: LanguageModelUsage;
+  timestamp: Date;
+}
+type AgentEventEmitter = (event: AgentEventName, payload: AgentEventPayload) => void | Promise<void>;
+//#endregion
+export { AgentCallOptions, AgentEventEmitter, AgentEventName, AgentEventPayload, AgentFinishReason, AgentGenerateParams, AgentGenerateResult, AgentMessage, AgentSessionState, AgentStatus, AgentStepMetrics, AgentStreamParams, ToolCallInfo, ToolExecutionContext, ToolHandler, ToolResultInfo };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;;;;;AAUA;AAWA;AAeiB,UA1BA,YAAA,CA6BJ;EAOD,IAAA,EAAA,WAAW;EAQX,UAAA,EAAA,MAAc;EAad,QAAA,EAAA,MAAA;EASK,IAAA,EAAA,OAAA;AAiBjB;AAeA;;;;AAOS,UA9FQ,cAAA,CA8FR;EACI,IAAA,EAAA,aAAA;EACA,UAAA,EAAA,MAAA;EACA,QAAA,EAAA,MAAA;EAAM,MAAA,EAAA,OAAA;AAOnB;AAaA;;;;AAA2C,UAtG1B,YAAA,CAsG0B;EAAmB,IAAA,EAAA,MAAA,GAAA,WAAA,GAAA,QAAA,GAAA,MAAA;EAS7C,OAAA,EAAA,MAAA,GAAA;IAIN,IAAA,EAAA,MAAA;IAES,IAAA,CAAA,EAAA,MAAA;IAAX,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;EAEI,CAAA,EAAA;EAEE,QAAA,CAAA,EAtHF,MAsHE,CAAA,MAAA,EAAA,MAAA,CAAA;;AAIL,KAnHE,WAAA,GAmHF,MAAA,GAAA,SAAA,GAAA,SAAA,GAAA,WAAA,GAAA,QAAA,GAAA,WAAA;AAEE,KA7GA,cAAA,GA6GA,uBAAA,GAAA,uBAAA,GAAA,oBAAA,GAAA,sBAAA,GAAA,mBAAA,GAAA,sBAAA,GAAA,mBAAA,GAAA,+BAAA,GAAA,iBAAA,GAAA,iBAAA,GAAA,cAAA;AAAiB,KAhGjB,iBAAA,GAgGiB,MAAA,GAAA,YAAA,GAAA,QAAA,GAAA,gBAAA,GAAA,OAAA,GAAA,OAAA,GAAA,SAAA;AAgBZ,UAvGA,iBAAA,CAuGoB;EAYzB,SAAA,EAAA,MAAW;EACd,OAAA,EAAA,MAAA;EACE,QAAA,CAAA,EAAA,MAAA;EACE,SAAA,CAAA,EAAA,MAAA;EAAR,QAAA,CAAA,EAAA,MAAA;EAAO,QAAA,CAAA,EAhHC,MAgHD,CAAA,MAAA,EAAA,OAAA,CAAA;AAMZ;AAkBA;;;;AAGmB,UAhIF,gBAAA,CAgIE;;;;;;;;aAxHN;;UAOI,iBAAA;;;;;UAKP;YACE;SACH,WAAW;aACP;aACA;aACA;;UAOI,mBAAA;;;;;;YAML;;;;WAID;;UAGM,iBAAA,SAA0B;;wBAEnB,WAAW,oBAAoB;;UAOtC;;;;WAIN;;SAEF,WAAW;;aAEP;;eAEE;;gBAEC;;UAEN;;YAEE;;;;;;;;;;;UAgBK,oBAAA;;;;;aAKJ;WACF;;;;;KAMC,0DACH,iBACE,yBACN,QAAQ;UAMI,gBAAA;;;;;;;;;;UAUP;aACG;;KAOD,iBAAA,WACH,yBACE,6BACC"}