@contractspec/lib.ai-agent 0.0.0-canary-20260113162409

package/dist/spec/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","names":[],"sources":["../../src/spec/registry.ts"],"sourcesContent":["import type { AgentSpec } from './spec';\nimport { compareVersions } from 'compare-versions';\nimport { SpecContractRegistry } from '@contractspec/lib.contracts/registry';\n\n/**\n * Registry for managing agent specifications.\n *\n * Provides registration, lookup, and version management for agent specs.\n */\nexport class AgentRegistry extends SpecContractRegistry<'agent', AgentSpec> {\n  public constructor(items?: AgentSpec[]) {\n    super('agent', items);\n  }\n\n  /**\n   * List all unique agent names (without versions).\n   */\n  listNames(): string[] {\n    const names = new Set<string>();\n    for (const spec of this.items.values()) {\n      names.add(spec.meta.key);\n    }\n    return [...names];\n  }\n\n  /**\n   * Get an agent specification or throw if not found.\n   *\n   * @param name - Agent name\n   * @param version - Optional version\n   * @returns The agent spec\n   * @throws Error if the spec is not found\n   */\n  require(name: string, version?: string): AgentSpec {\n    const spec = this.get(name, version);\n    if (!spec) {\n      throw new Error(\n        `Agent spec not found for ${name}${version != null ? `.v${version}` : ''}`\n      );\n    }\n    return spec;\n  }\n\n  /**\n   * Check if an agent is registered.\n   *\n   * @param name - Agent name\n   * @param version - Optional version\n   */\n  has(name: string, version?: string): boolean {\n    return this.get(name, version) !== undefined;\n  }\n\n  /**\n   * Get all versions of an agent.\n   *\n   * @param name - Agent name\n   * @returns Array of specs sorted by version (ascending)\n   */\n  getVersions(name: string): AgentSpec[] {\n    const versions: AgentSpec[] = [];\n    for (const spec of this.items.values()) {\n      if (spec.meta.key === name) {\n        versions.push(spec);\n      }\n    }\n    return versions.sort((a, b) =>\n      compareVersions(a.meta.version, b.meta.version)\n    );\n  }\n}\n\n/**\n * Create a new agent registry.\n */\nexport function createAgentRegistry(): AgentRegistry {\n  return new AgentRegistry();\n}\n"],"mappings":";;;;;;;;;AASA,IAAa,gBAAb,cAAmC,qBAAyC;CAC1E,AAAO,YAAY,OAAqB;AACtC,QAAM,SAAS,MAAM;;;;;CAMvB,YAAsB;EACpB,MAAM,wBAAQ,IAAI,KAAa;AAC/B,OAAK,MAAM,QAAQ,KAAK,MAAM,QAAQ,CACpC,OAAM,IAAI,KAAK,KAAK,IAAI;AAE1B,SAAO,CAAC,GAAG,MAAM;;;;;;;;;;CAWnB,QAAQ,MAAc,SAA6B;EACjD,MAAM,OAAO,KAAK,IAAI,MAAM,QAAQ;AACpC,MAAI,CAAC,KACH,OAAM,IAAI,MACR,4BAA4B,OAAO,WAAW,OAAO,KAAK,YAAY,KACvE;AAEH,SAAO;;;;;;;;CAST,IAAI,MAAc,SAA2B;AAC3C,SAAO,KAAK,IAAI,MAAM,QAAQ,KAAK;;;;;;;;CASrC,YAAY,MAA2B;EACrC,MAAM,WAAwB,EAAE;AAChC,OAAK,MAAM,QAAQ,KAAK,MAAM,QAAQ,CACpC,KAAI,KAAK,KAAK,QAAQ,KACpB,UAAS,KAAK,KAAK;AAGvB,SAAO,SAAS,MAAM,GAAG,MACvB,gBAAgB,EAAE,KAAK,SAAS,EAAE,KAAK,QAAQ,CAChD;;;;;;AAOL,SAAgB,sBAAqC;AACnD,QAAO,IAAI,eAAe"}

package/dist/spec/spec.d.ts

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

package/dist/spec/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../src/spec/spec.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAOA;AAKiB,KALL,SAAA,GAAY,aAWb;AAgBX;AAgBA;AAcA;AAUiB,UA9DA,eAAA,CA8DqB;EAcrB;EAUA,IAAA,EAAA,MAAS;EAClB;EAQC,WAAA,CAAA,EAAA,MAAA;EAEE;EAEG,MAAA,CAAA,EA7FH,MA6FG,CAAA,MAAA,EAAA,OAAA,CAAA;EAEH;EAAW,UAAA,CAAA,EAAA,MAAA;EAYN;EA+BA,SAAA,CAAA,EAAQ,MAAA;;;;;;WAhIb;;;;;UAMM,iBAAA;;;;;;aAMJ;;;;;;;;;UAUI,iBAAA;;;;;;;;;;;;;UAcA,qBAAA;;;;;;;;;UAUA,qBAAA;;;;;;;;;;;;;UAcA,WAAA;eACF;eACA;;;;;;;UAQE,SAAA;QACT;;;;;;;;SAQC;;WAEE;;cAEG;;WAEH;;;;;;;;;;;iBAYK,WAAA,OAAkB,YAAY;;;;iBA+B9B,QAAA,OAAe"}

package/dist/spec/spec.js

@@ -0,0 +1,30 @@
+//#region src/spec/spec.ts
+/**
+* Define and validate an agent specification.
+*
+* @param spec - The agent specification
+* @returns The frozen, validated specification
+* @throws Error if the specification is invalid
+*/
+function defineAgent(spec) {
+	if (!spec.meta?.key) throw new Error("Agent key is required");
+	if (typeof spec.meta.version !== "string") throw new Error(`Agent ${spec.meta.key} is missing a string version`);
+	if (!spec.instructions?.trim()) throw new Error(`Agent ${spec.meta.key} requires instructions`);
+	if (!spec.tools?.length) throw new Error(`Agent ${spec.meta.key} must expose at least one tool`);
+	const toolNames = /* @__PURE__ */ new Set();
+	for (const tool of spec.tools) {
+		if (toolNames.has(tool.name)) throw new Error(`Agent ${spec.meta.key} has duplicate tool name: ${tool.name}`);
+		toolNames.add(tool.name);
+	}
+	return Object.freeze(spec);
+}
+/**
+* Generate a unique key for an agent spec.
+*/
+function agentKey(meta) {
+	return `${meta.key}.v${meta.version}`;
+}
+
+//#endregion
+export { agentKey, defineAgent };
+//# sourceMappingURL=spec.js.map

package/dist/spec/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","names":[],"sources":["../../src/spec/spec.ts"],"sourcesContent":["import type { OwnerShipMeta } from '@contractspec/lib.contracts/ownership';\nimport type { KnowledgeCategory } from '@contractspec/lib.contracts/knowledge/spec';\nimport type { PolicyRef } from '@contractspec/lib.contracts/policy/spec';\n\n/**\n * Metadata for an agent specification.\n */\nexport type AgentMeta = OwnerShipMeta;\n\n/**\n * Configuration for a tool that an agent can use.\n */\nexport interface AgentToolConfig {\n  /** Tool name (unique within the agent) */\n  name: string;\n  /** Human-readable description for the LLM */\n  description?: string;\n  /** JSON Schema fragment for tool parameters */\n  schema?: Record<string, unknown>;\n  /** Optional cooldown in milliseconds between invocations */\n  cooldownMs?: number;\n  /** Maximum execution time before timeout */\n  timeoutMs?: number;\n  /** Whether the tool can be executed without human approval (AI SDK needsApproval = !automationSafe) */\n  automationSafe?: boolean;\n  /** Explicit approval requirement (overrides automationSafe) */\n  requiresApproval?: boolean;\n  /** Optional policy guard that must evaluate to allow the tool call */\n  policy?: PolicyRef;\n}\n\n/**\n * Reference to a knowledge space that the agent can access.\n */\nexport interface AgentKnowledgeRef {\n  /** Knowledge space key */\n  key: string;\n  /** Optional specific version */\n  version?: number;\n  /** Filter by knowledge category */\n  category?: KnowledgeCategory;\n  /** Whether the knowledge is required (static injection) or optional (dynamic RAG) */\n  required?: boolean;\n  /** Additional instructions appended when the space is available */\n  instructions?: string;\n}\n\n/**\n * Memory configuration for agent session persistence.\n */\nexport interface AgentMemoryConfig {\n  /** Maximum entries to keep in memory */\n  maxEntries?: number;\n  /** Time-to-live in minutes */\n  ttlMinutes?: number;\n  /** Number of messages before triggering summarization */\n  summaryTrigger?: number;\n  /** Whether to persist to long-term storage */\n  persistLongTerm?: boolean;\n}\n\n/**\n * Confidence policy for agent responses.\n */\nexport interface AgentConfidencePolicy {\n  /** Minimum acceptable confidence before escalation. Defaults to 0.7 */\n  min?: number;\n  /** Default value used when provider does not report confidence */\n  default?: number;\n}\n\n/**\n * Escalation policy for handling uncertain or failed agent responses.\n */\nexport interface AgentEscalationPolicy {\n  /** Auto escalate when confidence < threshold */\n  confidenceThreshold?: number;\n  /** Escalate when a tool throws irrecoverable errors */\n  onToolFailure?: boolean;\n  /** Escalate when iteration budget exceeded */\n  onTimeout?: boolean;\n  /** Optional human approval workflow ID */\n  approvalWorkflow?: string;\n}\n\n/**\n * Combined policy configuration for an agent.\n */\nexport interface AgentPolicy {\n  confidence?: AgentConfidencePolicy;\n  escalation?: AgentEscalationPolicy;\n  /** Feature flags to apply to this agent */\n  flags?: string[];\n}\n\n/**\n * Complete specification for a ContractSpec agent.\n */\nexport interface AgentSpec {\n  meta: AgentMeta;\n  /** System instructions for the agent */\n  instructions: string;\n  /** Human-readable description */\n  description?: string;\n  /** Tags for categorization */\n  tags?: string[];\n  /** Tools the agent can use */\n  tools: AgentToolConfig[];\n  /** Memory/session configuration */\n  memory?: AgentMemoryConfig;\n  /** Knowledge spaces the agent can access */\n  knowledge?: AgentKnowledgeRef[];\n  /** Policy configuration */\n  policy?: AgentPolicy;\n  /** Maximum steps per generation (defaults to 10) */\n  maxSteps?: number;\n}\n\n/**\n * Define and validate an agent specification.\n *\n * @param spec - The agent specification\n * @returns The frozen, validated specification\n * @throws Error if the specification is invalid\n */\nexport function defineAgent(spec: AgentSpec): AgentSpec {\n  if (!spec.meta?.key) {\n    throw new Error('Agent key is required');\n  }\n  if (typeof spec.meta.version !== 'string') {\n    throw new Error(`Agent ${spec.meta.key} is missing a string version`);\n  }\n  if (!spec.instructions?.trim()) {\n    throw new Error(`Agent ${spec.meta.key} requires instructions`);\n  }\n  if (!spec.tools?.length) {\n    throw new Error(`Agent ${spec.meta.key} must expose at least one tool`);\n  }\n\n  // Validate tool names are unique\n  const toolNames = new Set<string>();\n  for (const tool of spec.tools) {\n    if (toolNames.has(tool.name)) {\n      throw new Error(\n        `Agent ${spec.meta.key} has duplicate tool name: ${tool.name}`\n      );\n    }\n    toolNames.add(tool.name);\n  }\n\n  return Object.freeze(spec);\n}\n\n/**\n * Generate a unique key for an agent spec.\n */\nexport function agentKey(meta: AgentMeta): string {\n  return `${meta.key}.v${meta.version}`;\n}\n"],"mappings":";;;;;;;;AA6HA,SAAgB,YAAY,MAA4B;AACtD,KAAI,CAAC,KAAK,MAAM,IACd,OAAM,IAAI,MAAM,wBAAwB;AAE1C,KAAI,OAAO,KAAK,KAAK,YAAY,SAC/B,OAAM,IAAI,MAAM,SAAS,KAAK,KAAK,IAAI,8BAA8B;AAEvE,KAAI,CAAC,KAAK,cAAc,MAAM,CAC5B,OAAM,IAAI,MAAM,SAAS,KAAK,KAAK,IAAI,wBAAwB;AAEjE,KAAI,CAAC,KAAK,OAAO,OACf,OAAM,IAAI,MAAM,SAAS,KAAK,KAAK,IAAI,gCAAgC;CAIzE,MAAM,4BAAY,IAAI,KAAa;AACnC,MAAK,MAAM,QAAQ,KAAK,OAAO;AAC7B,MAAI,UAAU,IAAI,KAAK,KAAK,CAC1B,OAAM,IAAI,MACR,SAAS,KAAK,KAAK,IAAI,4BAA4B,KAAK,OACzD;AAEH,YAAU,IAAI,KAAK,KAAK;;AAG1B,QAAO,OAAO,OAAO,KAAK;;;;;AAM5B,SAAgB,SAAS,MAAyB;AAChD,QAAO,GAAG,KAAK,IAAI,IAAI,KAAK"}

package/dist/telemetry/adapter.d.ts

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

package/dist/telemetry/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","names":[],"sources":["../../src/telemetry/adapter.ts"],"sourcesContent":[],"mappings":";;;;;;AAKA;AAgBiB,UAhBA,qBAAA,CAoBC;EA0BI,SAAA,EAAA;IACT,IAAA,EAAA,MAAA;IAEM,OAAA,EAAA,MAAA;EAAX,CAAA;EAEL,UAAA,EAAA,MAAA;EAAO,OAAA,EAAA,OAAA;EAyCG,SAAA,EAxFA,IAwFA;EAGW,QAAA,CAAA,EA1FX,MA0FW,CAAA,MAAA,EAAA,OAAA,CAAA;;;;;;AA6BxB;AAOA;;;UAnHiB,kBAAA;;;;kBAIC,wBAAwB;;;;;;;;;;;;;iBA0BpB,cAAA,YACT,2CAEL,WAAW,gCAEhB;;;;cAyCU,0BAAA,YAAsC;;kBAG3B,wBAAwB;;;;gBAOhC;;;;iDAOiC;;;;;;;;;iBAejC,gCAAA,CAAA,GAAoC;;;;cAOvC,wBAAwB"}

package/dist/telemetry/adapter.js

@@ -0,0 +1,103 @@
+//#region src/telemetry/adapter.ts
+/**
+* Parse agent ID into name and version.
+*/
+function parseAgentId(agentId) {
+	const match = agentId.match(/^(.+)\.v(\s+)$/);
+	if (match) return {
+		name: match[1],
+		version: match[2]
+	};
+	return {
+		name: agentId,
+		version: "1.0.0"
+	};
+}
+/**
+* Track an agent step for telemetry.
+*
+* Called from ContractSpecAgent.onStepFinish to feed metrics
+* to the evolution engine.
+*
+* @param collector - Telemetry collector
+* @param agentId - Agent identifier (e.g., "support.bot.v1")
+* @param step - AI SDK step result
+* @param durationMs - Optional step duration in milliseconds
+*/
+async function trackAgentStep(collector, agentId, step, durationMs) {
+	const { name, version } = parseAgentId(agentId);
+	for (const toolCall of step.toolCalls ?? []) {
+		const toolSample = {
+			operation: {
+				name: `${name}.${toolCall.toolName}`,
+				version
+			},
+			durationMs: durationMs ?? 0,
+			success: step.toolResults?.some((r) => r.toolCallId === toolCall.toolCallId && r.output !== void 0) ?? false,
+			timestamp: /* @__PURE__ */ new Date(),
+			metadata: {
+				agentId,
+				toolName: toolCall.toolName,
+				finishReason: step.finishReason
+			}
+		};
+		await collector.collect(toolSample);
+	}
+	const stepSample = {
+		operation: {
+			name,
+			version
+		},
+		durationMs: durationMs ?? 0,
+		success: step.finishReason !== "error",
+		timestamp: /* @__PURE__ */ new Date(),
+		metadata: {
+			agentId,
+			finishReason: step.finishReason,
+			tokenUsage: step.usage,
+			toolCallCount: step.toolCalls?.length ?? 0
+		}
+	};
+	await collector.collect(stepSample);
+}
+/**
+* In-memory telemetry collector for testing.
+*/
+var InMemoryTelemetryCollector = class {
+	samples = [];
+	async collect(sample) {
+		this.samples.push(sample);
+	}
+	/**
+	* Get all collected samples.
+	*/
+	getSamples() {
+		return [...this.samples];
+	}
+	/**
+	* Get samples for a specific operation.
+	*/
+	getSamplesForOperation(operationName) {
+		return this.samples.filter((s) => s.operation.name === operationName);
+	}
+	/**
+	* Clear all samples.
+	*/
+	clear() {
+		this.samples.length = 0;
+	}
+};
+/**
+* Create an in-memory telemetry collector.
+*/
+function createInMemoryTelemetryCollector() {
+	return new InMemoryTelemetryCollector();
+}
+/**
+* No-op telemetry collector that discards all metrics.
+*/
+const noopTelemetryCollector = { collect: async () => {} };
+
+//#endregion
+export { InMemoryTelemetryCollector, createInMemoryTelemetryCollector, noopTelemetryCollector, trackAgentStep };
+//# sourceMappingURL=adapter.js.map

package/dist/telemetry/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":[],"sources":["../../src/telemetry/adapter.ts"],"sourcesContent":["import type { StepResult, ToolSet } from 'ai';\n\n/**\n * Metric sample compatible with @contractspec/lib.evolution OperationMetricSample.\n */\nexport interface OperationMetricSample {\n  operation: { name: string; version: string };\n  durationMs: number;\n  success: boolean;\n  timestamp: Date;\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Interface for collecting telemetry metrics.\n *\n * Implementations can send metrics to:\n * - @contractspec/lib.evolution for self-improvement\n * - PostHog for analytics\n * - Custom monitoring systems\n */\nexport interface TelemetryCollector {\n  /**\n   * Collect a metric sample.\n   */\n  collect(sample: OperationMetricSample): Promise<void>;\n}\n\n/**\n * Parse agent ID into name and version.\n */\nfunction parseAgentId(agentId: string): { name: string; version: string } {\n  const match = agentId.match(/^(.+)\\.v(\\s+)$/);\n  if (match) {\n    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n    return { name: match[1]!, version: match[2]! };\n  }\n  return { name: agentId, version: '1.0.0' };\n}\n\n/**\n * Track an agent step for telemetry.\n *\n * Called from ContractSpecAgent.onStepFinish to feed metrics\n * to the evolution engine.\n *\n * @param collector - Telemetry collector\n * @param agentId - Agent identifier (e.g., \"support.bot.v1\")\n * @param step - AI SDK step result\n * @param durationMs - Optional step duration in milliseconds\n */\nexport async function trackAgentStep(\n  collector: TelemetryCollector,\n  agentId: string,\n  step: StepResult<ToolSet>,\n  durationMs?: number\n): Promise<void> {\n  const { name, version } = parseAgentId(agentId);\n\n  // Track tool invocations\n  for (const toolCall of step.toolCalls ?? []) {\n    const toolSample: OperationMetricSample = {\n      operation: { name: `${name}.${toolCall.toolName}`, version },\n      durationMs: durationMs ?? 0,\n      success:\n        step.toolResults?.some(\n          (r) => r.toolCallId === toolCall.toolCallId && r.output !== undefined\n        ) ?? false,\n      timestamp: new Date(),\n      metadata: {\n        agentId,\n        toolName: toolCall.toolName,\n        finishReason: step.finishReason,\n      },\n    };\n    await collector.collect(toolSample);\n  }\n\n  // Track overall step\n  const stepSample: OperationMetricSample = {\n    operation: { name, version },\n    durationMs: durationMs ?? 0,\n    success: step.finishReason !== 'error',\n    timestamp: new Date(),\n    metadata: {\n      agentId,\n      finishReason: step.finishReason,\n      tokenUsage: step.usage,\n      toolCallCount: step.toolCalls?.length ?? 0,\n    },\n  };\n  await collector.collect(stepSample);\n}\n\n/**\n * In-memory telemetry collector for testing.\n */\nexport class InMemoryTelemetryCollector implements TelemetryCollector {\n  private readonly samples: OperationMetricSample[] = [];\n\n  async collect(sample: OperationMetricSample): Promise<void> {\n    this.samples.push(sample);\n  }\n\n  /**\n   * Get all collected samples.\n   */\n  getSamples(): OperationMetricSample[] {\n    return [...this.samples];\n  }\n\n  /**\n   * Get samples for a specific operation.\n   */\n  getSamplesForOperation(operationName: string): OperationMetricSample[] {\n    return this.samples.filter((s) => s.operation.name === operationName);\n  }\n\n  /**\n   * Clear all samples.\n   */\n  clear(): void {\n    this.samples.length = 0;\n  }\n}\n\n/**\n * Create an in-memory telemetry collector.\n */\nexport function createInMemoryTelemetryCollector(): InMemoryTelemetryCollector {\n  return new InMemoryTelemetryCollector();\n}\n\n/**\n * No-op telemetry collector that discards all metrics.\n */\nexport const noopTelemetryCollector: TelemetryCollector = {\n  collect: async () => {\n    /* noop */\n  },\n};\n"],"mappings":";;;;AA+BA,SAAS,aAAa,SAAoD;CACxE,MAAM,QAAQ,QAAQ,MAAM,iBAAiB;AAC7C,KAAI,MAEF,QAAO;EAAE,MAAM,MAAM;EAAK,SAAS,MAAM;EAAK;AAEhD,QAAO;EAAE,MAAM;EAAS,SAAS;EAAS;;;;;;;;;;;;;AAc5C,eAAsB,eACpB,WACA,SACA,MACA,YACe;CACf,MAAM,EAAE,MAAM,YAAY,aAAa,QAAQ;AAG/C,MAAK,MAAM,YAAY,KAAK,aAAa,EAAE,EAAE;EAC3C,MAAM,aAAoC;GACxC,WAAW;IAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAAY;IAAS;GAC5D,YAAY,cAAc;GAC1B,SACE,KAAK,aAAa,MACf,MAAM,EAAE,eAAe,SAAS,cAAc,EAAE,WAAW,OAC7D,IAAI;GACP,2BAAW,IAAI,MAAM;GACrB,UAAU;IACR;IACA,UAAU,SAAS;IACnB,cAAc,KAAK;IACpB;GACF;AACD,QAAM,UAAU,QAAQ,WAAW;;CAIrC,MAAM,aAAoC;EACxC,WAAW;GAAE;GAAM;GAAS;EAC5B,YAAY,cAAc;EAC1B,SAAS,KAAK,iBAAiB;EAC/B,2BAAW,IAAI,MAAM;EACrB,UAAU;GACR;GACA,cAAc,KAAK;GACnB,YAAY,KAAK;GACjB,eAAe,KAAK,WAAW,UAAU;GAC1C;EACF;AACD,OAAM,UAAU,QAAQ,WAAW;;;;;AAMrC,IAAa,6BAAb,MAAsE;CACpE,AAAiB,UAAmC,EAAE;CAEtD,MAAM,QAAQ,QAA8C;AAC1D,OAAK,QAAQ,KAAK,OAAO;;;;;CAM3B,aAAsC;AACpC,SAAO,CAAC,GAAG,KAAK,QAAQ;;;;;CAM1B,uBAAuB,eAAgD;AACrE,SAAO,KAAK,QAAQ,QAAQ,MAAM,EAAE,UAAU,SAAS,cAAc;;;;;CAMvE,QAAc;AACZ,OAAK,QAAQ,SAAS;;;;;;AAO1B,SAAgB,mCAA+D;AAC7E,QAAO,IAAI,4BAA4B;;;;;AAMzC,MAAa,yBAA6C,EACxD,SAAS,YAAY,IAGtB"}

package/dist/telemetry/index.d.ts

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

package/dist/telemetry/index.js

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

package/dist/tools/index.d.ts

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

package/dist/tools/index.js

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-tool.d.ts","names":[],"sources":["../../src/tools/knowledge-tool.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAgBA;;;;;;;;;iBAAgB,wBAAA,YACH,mCACI,sBAEd"}

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"],"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,MAAM,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"],"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,MAAM,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"}