@contractspec/lib.ai-agent 1.57.0 → 1.59.0

package/dist/interop/spec-consumer.js

@@ -1,287 +1,307 @@
-import { agentKey } from "../spec/spec.js";
-
-//#region src/interop/spec-consumer.ts
-/**
-* ContractSpec consumer for external agents.
-*
-* @example
-* ```typescript
-* const consumer = createSpecConsumer({
-*   specs: [myAgentSpec, anotherSpec],
-*   includeMetadata: true,
-* });
-*
-* // Get markdown representation
-* const markdown = consumer.getSpecMarkdown('my-agent.v1.0.0');
-*
-* // Get prompt for LLM
-* const prompt = consumer.getSpecPrompt('my-agent.v1.0.0', {
-*   includeTools: true,
-* });
-* ```
-*/
-var ContractSpecConsumer = class {
-	specs;
-	includeMetadata;
-	baseUrl;
-	constructor(config) {
-		this.specs = /* @__PURE__ */ new Map();
-		this.includeMetadata = config.includeMetadata ?? true;
-		this.baseUrl = config.baseUrl;
-		for (const spec of config.specs) {
-			const key = agentKey(spec.meta);
-			this.specs.set(key, spec);
-		}
-	}
-	/**
-	* Get a spec as markdown.
-	*/
-	getSpecMarkdown(specKey, options) {
-		const spec = this.specs.get(specKey);
-		if (!spec) throw new Error(`Spec not found: ${specKey}`);
-		const sections = [];
-		const opts = {
-			includeToc: options?.includeToc ?? true,
-			includeTools: options?.includeTools ?? true,
-			...options
-		};
-		if (opts.customHeader) {
-			sections.push(opts.customHeader);
-			sections.push("");
-		}
-		const specName = spec.meta.key;
-		sections.push(`# ${specName}`);
-		sections.push("");
-		if (spec.description) {
-			sections.push(spec.description);
-			sections.push("");
-		}
-		if (opts.includeToc) {
-			sections.push("## Table of Contents");
-			sections.push("");
-			sections.push("- [Overview](#overview)");
-			sections.push("- [Instructions](#instructions)");
-			if (opts.includeTools && spec.tools && spec.tools.length > 0) sections.push("- [Tools](#tools)");
-			if (spec.knowledge && spec.knowledge.length > 0) sections.push("- [Knowledge](#knowledge)");
-			sections.push("");
-		}
-		sections.push("## Overview");
-		sections.push("");
-		if (this.includeMetadata) {
-			sections.push(`- **Key**: \`${spec.meta.key}\``);
-			sections.push(`- **Version**: ${spec.meta.version}`);
-			if (spec.meta.stability) sections.push(`- **Stability**: ${spec.meta.stability}`);
-			if (spec.meta.owners && spec.meta.owners.length > 0) sections.push(`- **Owners**: ${spec.meta.owners.join(", ")}`);
-			if (spec.tags && spec.tags.length > 0) sections.push(`- **Tags**: ${spec.tags.join(", ")}`);
-		}
-		sections.push("");
-		sections.push("## Instructions");
-		sections.push("");
-		sections.push(spec.instructions);
-		sections.push("");
-		if (opts.includeTools && spec.tools && spec.tools.length > 0) {
-			sections.push("## Tools");
-			sections.push("");
-			for (const tool of spec.tools) {
-				sections.push(`### ${tool.name}`);
-				sections.push("");
-				if (tool.description) {
-					sections.push(tool.description);
-					sections.push("");
-				}
-				if (tool.schema) {
-					sections.push("**Schema:**");
-					sections.push("");
-					sections.push("```json");
-					sections.push(JSON.stringify(tool.schema, null, 2));
-					sections.push("```");
-					sections.push("");
-				}
-				if (tool.automationSafe !== void 0) {
-					sections.push(`**Automation Safe**: ${tool.automationSafe ? "Yes" : "No"}`);
-					sections.push("");
-				}
-			}
-		}
-		if (spec.knowledge && spec.knowledge.length > 0) {
-			sections.push("## Knowledge");
-			sections.push("");
-			for (const k of spec.knowledge) {
-				sections.push(`- **${k.key}**${k.required ? " (required)" : ""}`);
-				if (k.instructions) sections.push(`  - ${k.instructions}`);
-			}
-			sections.push("");
-		}
-		if (spec.policy) {
-			sections.push("## Policy");
-			sections.push("");
-			if (spec.policy.confidence) sections.push(`- **Minimum Confidence**: ${spec.policy.confidence.min ?? .7}`);
-			if (spec.policy.escalation) {
-				const esc = spec.policy.escalation;
-				if (esc.confidenceThreshold) sections.push(`- **Escalation Threshold**: ${esc.confidenceThreshold}`);
-				if (esc.onToolFailure) sections.push("- **Escalate on Tool Failure**: Yes");
-				if (esc.onTimeout) sections.push("- **Escalate on Timeout**: Yes");
-			}
-			sections.push("");
-		}
-		return sections.join("\n");
-	}
-	/**
-	* Get a spec as an LLM prompt.
-	*/
-	getSpecPrompt(specKey, options) {
-		const spec = this.specs.get(specKey);
-		if (!spec) throw new Error(`Spec not found: ${specKey}`);
-		const sections = [];
-		const opts = {
-			includeTools: options?.includeTools ?? true,
-			format: options?.format ?? "structured",
-			...options
-		};
-		sections.push("# Agent Identity");
-		sections.push("");
-		sections.push(`You are ${spec.meta.key} (v${spec.meta.version}).`);
-		sections.push("");
-		if (spec.description) {
-			sections.push("## Description");
-			sections.push("");
-			sections.push(spec.description);
-			sections.push("");
-		}
-		sections.push("## Instructions");
-		sections.push("");
-		sections.push(spec.instructions);
-		sections.push("");
-		if (opts.includeTools && spec.tools && spec.tools.length > 0) {
-			sections.push("## Available Tools");
-			sections.push("");
-			sections.push("You have access to the following tools:");
-			sections.push("");
-			for (const tool of spec.tools) {
-				sections.push(`### ${tool.name}`);
-				sections.push("");
-				if (tool.description) {
-					sections.push(tool.description);
-					sections.push("");
-				}
-				if (tool.schema && opts.format === "structured") {
-					sections.push("Parameters:");
-					sections.push("```json");
-					sections.push(JSON.stringify(tool.schema, null, 2));
-					sections.push("```");
-					sections.push("");
-				}
-			}
-		}
-		if (spec.knowledge && spec.knowledge.length > 0) {
-			const requiredKnowledge = spec.knowledge.filter((k) => k.required);
-			if (requiredKnowledge.length > 0) {
-				sections.push("## Knowledge Context");
-				sections.push("");
-				for (const k of requiredKnowledge) if (k.instructions) {
-					sections.push(k.instructions);
-					sections.push("");
-				}
-			}
-		}
-		if (options?.customContext) {
-			sections.push("## Additional Context");
-			sections.push("");
-			sections.push(options.customContext);
-			sections.push("");
-		}
-		return sections.join("\n");
-	}
-	/**
-	* List available specs.
-	*/
-	listSpecs(options) {
-		const results = [];
-		for (const [key, spec] of this.specs) {
-			if (options?.stability && spec.meta.stability !== options.stability) continue;
-			if (options?.tags && options.tags.length > 0) {
-				const specTags = spec.tags ?? [];
-				if (!options.tags.some((tag) => specTags.includes(tag))) continue;
-			}
-			results.push({
-				key,
-				name: spec.meta.key,
-				version: spec.meta.version,
-				description: spec.description,
-				stability: spec.meta.stability,
-				tags: spec.tags,
-				toolCount: spec.tools?.length ?? 0
-			});
-		}
-		return results;
-	}
-	/**
-	* Query a spec by key.
-	*/
-	querySpec(specKey) {
-		const spec = this.specs.get(specKey);
-		if (!spec) return;
-		return {
-			key: specKey,
-			spec,
-			markdown: this.getSpecMarkdown(specKey),
-			prompt: this.getSpecPrompt(specKey)
-		};
-	}
-	/**
-	* Check if a spec exists.
-	*/
-	hasSpec(specKey) {
-		return this.specs.has(specKey);
-	}
-	/**
-	* Get a spec by key.
-	*/
-	getSpec(specKey) {
-		return this.specs.get(specKey);
-	}
-	/**
-	* Get all specs.
-	*/
-	getAllSpecs() {
-		return Array.from(this.specs.values());
-	}
-	/**
-	* Get spec count.
-	*/
-	getSpecCount() {
-		return this.specs.size;
-	}
-	/**
-	* Add a spec to the consumer.
-	*/
-	addSpec(spec) {
-		const key = agentKey(spec.meta);
-		this.specs.set(key, spec);
-	}
-	/**
-	* Remove a spec from the consumer.
-	*/
-	removeSpec(specKey) {
-		return this.specs.delete(specKey);
-	}
+// @bun
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
 };
-/**
-* Create a new spec consumer.
-*/
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/spec/spec.ts
+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 = 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);
+}
+function agentKey(meta) {
+  return `${meta.key}.v${meta.version}`;
+}
+
+// src/interop/spec-consumer.ts
+class ContractSpecConsumer {
+  specs;
+  includeMetadata;
+  baseUrl;
+  constructor(config) {
+    this.specs = new Map;
+    this.includeMetadata = config.includeMetadata ?? true;
+    this.baseUrl = config.baseUrl;
+    for (const spec of config.specs) {
+      const key = agentKey(spec.meta);
+      this.specs.set(key, spec);
+    }
+  }
+  getSpecMarkdown(specKey, options) {
+    const spec = this.specs.get(specKey);
+    if (!spec) {
+      throw new Error(`Spec not found: ${specKey}`);
+    }
+    const sections = [];
+    const opts = {
+      includeToc: options?.includeToc ?? true,
+      includeTools: options?.includeTools ?? true,
+      ...options
+    };
+    if (opts.customHeader) {
+      sections.push(opts.customHeader);
+      sections.push("");
+    }
+    const specName = spec.meta.key;
+    sections.push(`# ${specName}`);
+    sections.push("");
+    if (spec.description) {
+      sections.push(spec.description);
+      sections.push("");
+    }
+    if (opts.includeToc) {
+      sections.push("## Table of Contents");
+      sections.push("");
+      sections.push("- [Overview](#overview)");
+      sections.push("- [Instructions](#instructions)");
+      if (opts.includeTools && spec.tools && spec.tools.length > 0) {
+        sections.push("- [Tools](#tools)");
+      }
+      if (spec.knowledge && spec.knowledge.length > 0) {
+        sections.push("- [Knowledge](#knowledge)");
+      }
+      sections.push("");
+    }
+    sections.push("## Overview");
+    sections.push("");
+    if (this.includeMetadata) {
+      sections.push(`- **Key**: \`${spec.meta.key}\``);
+      sections.push(`- **Version**: ${spec.meta.version}`);
+      if (spec.meta.stability) {
+        sections.push(`- **Stability**: ${spec.meta.stability}`);
+      }
+      if (spec.meta.owners && spec.meta.owners.length > 0) {
+        sections.push(`- **Owners**: ${spec.meta.owners.join(", ")}`);
+      }
+      if (spec.tags && spec.tags.length > 0) {
+        sections.push(`- **Tags**: ${spec.tags.join(", ")}`);
+      }
+    }
+    sections.push("");
+    sections.push("## Instructions");
+    sections.push("");
+    sections.push(spec.instructions);
+    sections.push("");
+    if (opts.includeTools && spec.tools && spec.tools.length > 0) {
+      sections.push("## Tools");
+      sections.push("");
+      for (const tool of spec.tools) {
+        sections.push(`### ${tool.name}`);
+        sections.push("");
+        if (tool.description) {
+          sections.push(tool.description);
+          sections.push("");
+        }
+        if (tool.schema) {
+          sections.push("**Schema:**");
+          sections.push("");
+          sections.push("```json");
+          sections.push(JSON.stringify(tool.schema, null, 2));
+          sections.push("```");
+          sections.push("");
+        }
+        if (tool.automationSafe !== undefined) {
+          sections.push(`**Automation Safe**: ${tool.automationSafe ? "Yes" : "No"}`);
+          sections.push("");
+        }
+      }
+    }
+    if (spec.knowledge && spec.knowledge.length > 0) {
+      sections.push("## Knowledge");
+      sections.push("");
+      for (const k of spec.knowledge) {
+        sections.push(`- **${k.key}**${k.required ? " (required)" : ""}`);
+        if (k.instructions) {
+          sections.push(`  - ${k.instructions}`);
+        }
+      }
+      sections.push("");
+    }
+    if (spec.policy) {
+      sections.push("## Policy");
+      sections.push("");
+      if (spec.policy.confidence) {
+        sections.push(`- **Minimum Confidence**: ${spec.policy.confidence.min ?? 0.7}`);
+      }
+      if (spec.policy.escalation) {
+        const esc = spec.policy.escalation;
+        if (esc.confidenceThreshold) {
+          sections.push(`- **Escalation Threshold**: ${esc.confidenceThreshold}`);
+        }
+        if (esc.onToolFailure) {
+          sections.push("- **Escalate on Tool Failure**: Yes");
+        }
+        if (esc.onTimeout) {
+          sections.push("- **Escalate on Timeout**: Yes");
+        }
+      }
+      sections.push("");
+    }
+    return sections.join(`
+`);
+  }
+  getSpecPrompt(specKey, options) {
+    const spec = this.specs.get(specKey);
+    if (!spec) {
+      throw new Error(`Spec not found: ${specKey}`);
+    }
+    const sections = [];
+    const opts = {
+      includeTools: options?.includeTools ?? true,
+      format: options?.format ?? "structured",
+      ...options
+    };
+    sections.push("# Agent Identity");
+    sections.push("");
+    sections.push(`You are ${spec.meta.key} (v${spec.meta.version}).`);
+    sections.push("");
+    if (spec.description) {
+      sections.push("## Description");
+      sections.push("");
+      sections.push(spec.description);
+      sections.push("");
+    }
+    sections.push("## Instructions");
+    sections.push("");
+    sections.push(spec.instructions);
+    sections.push("");
+    if (opts.includeTools && spec.tools && spec.tools.length > 0) {
+      sections.push("## Available Tools");
+      sections.push("");
+      sections.push("You have access to the following tools:");
+      sections.push("");
+      for (const tool of spec.tools) {
+        sections.push(`### ${tool.name}`);
+        sections.push("");
+        if (tool.description) {
+          sections.push(tool.description);
+          sections.push("");
+        }
+        if (tool.schema && opts.format === "structured") {
+          sections.push("Parameters:");
+          sections.push("```json");
+          sections.push(JSON.stringify(tool.schema, null, 2));
+          sections.push("```");
+          sections.push("");
+        }
+      }
+    }
+    if (spec.knowledge && spec.knowledge.length > 0) {
+      const requiredKnowledge = spec.knowledge.filter((k) => k.required);
+      if (requiredKnowledge.length > 0) {
+        sections.push("## Knowledge Context");
+        sections.push("");
+        for (const k of requiredKnowledge) {
+          if (k.instructions) {
+            sections.push(k.instructions);
+            sections.push("");
+          }
+        }
+      }
+    }
+    if (options?.customContext) {
+      sections.push("## Additional Context");
+      sections.push("");
+      sections.push(options.customContext);
+      sections.push("");
+    }
+    return sections.join(`
+`);
+  }
+  listSpecs(options) {
+    const results = [];
+    for (const [key, spec] of this.specs) {
+      if (options?.stability && spec.meta.stability !== options.stability) {
+        continue;
+      }
+      if (options?.tags && options.tags.length > 0) {
+        const specTags = spec.tags ?? [];
+        const hasMatchingTag = options.tags.some((tag) => specTags.includes(tag));
+        if (!hasMatchingTag) {
+          continue;
+        }
+      }
+      results.push({
+        key,
+        name: spec.meta.key,
+        version: spec.meta.version,
+        description: spec.description,
+        stability: spec.meta.stability,
+        tags: spec.tags,
+        toolCount: spec.tools?.length ?? 0
+      });
+    }
+    return results;
+  }
+  querySpec(specKey) {
+    const spec = this.specs.get(specKey);
+    if (!spec) {
+      return;
+    }
+    return {
+      key: specKey,
+      spec,
+      markdown: this.getSpecMarkdown(specKey),
+      prompt: this.getSpecPrompt(specKey)
+    };
+  }
+  hasSpec(specKey) {
+    return this.specs.has(specKey);
+  }
+  getSpec(specKey) {
+    return this.specs.get(specKey);
+  }
+  getAllSpecs() {
+    return Array.from(this.specs.values());
+  }
+  getSpecCount() {
+    return this.specs.size;
+  }
+  addSpec(spec) {
+    const key = agentKey(spec.meta);
+    this.specs.set(key, spec);
+  }
+  removeSpec(specKey) {
+    return this.specs.delete(specKey);
+  }
+}
 function createSpecConsumer(config) {
-	return new ContractSpecConsumer(config);
+  return new ContractSpecConsumer(config);
 }
-/**
-* Create a spec consumer from a single spec.
-*/
 function createSingleSpecConsumer(spec, options) {
-	return new ContractSpecConsumer({
-		specs: [spec],
-		...options
-	});
+  return new ContractSpecConsumer({
+    specs: [spec],
+    ...options
+  });
 }
-
-//#endregion
-export { ContractSpecConsumer, createSingleSpecConsumer, createSpecConsumer };
-//# sourceMappingURL=spec-consumer.js.map
+export {
+  createSpecConsumer,
+  createSingleSpecConsumer,
+  ContractSpecConsumer
+};