@contractspec/lib.ai-agent 1.57.0 → 1.59.0

package/dist/node/interop/spec-consumer.js

@@ -0,0 +1,307 @@
+import { createRequire } from "node:module";
+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
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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);
+}
+function createSingleSpecConsumer(spec, options) {
+  return new ContractSpecConsumer({
+    specs: [spec],
+    ...options
+  });
+}
+export {
+  createSpecConsumer,
+  createSingleSpecConsumer,
+  ContractSpecConsumer
+};

package/dist/node/interop/tool-consumer.js

@@ -0,0 +1,419 @@
+import { createRequire } from "node:module";
+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
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/providers/claude-agent-sdk/tool-bridge.ts
+function specToolToClaudeAgentTool(tool, handler, context) {
+  return {
+    name: tool.name,
+    description: tool.description ?? `Execute ${tool.name}`,
+    input_schema: normalizeSchema(tool.schema),
+    requires_confirmation: tool.requiresApproval ?? !tool.automationSafe,
+    execute: async (input) => {
+      const fullContext = {
+        agentId: context.agentId ?? "unknown",
+        sessionId: context.sessionId ?? "unknown",
+        tenantId: context.tenantId,
+        actorId: context.actorId,
+        metadata: context.metadata,
+        signal: context.signal
+      };
+      return handler(input, fullContext);
+    }
+  };
+}
+function specToolsToClaudeAgentTools(tools, handlers, context) {
+  return tools.filter((tool) => handlers.has(tool.name)).map((tool) => {
+    const handler = handlers.get(tool.name);
+    if (!handler) {
+      throw new Error(`Handler not found for tool ${tool.name}`);
+    }
+    return specToolToClaudeAgentTool(tool, handler, context);
+  });
+}
+function claudeAgentToolToSpecTool(claudeTool, execute) {
+  const config = {
+    name: claudeTool.name,
+    description: claudeTool.description,
+    schema: claudeTool.input_schema,
+    requiresApproval: claudeTool.requires_confirmation,
+    automationSafe: !claudeTool.requires_confirmation
+  };
+  const handler = execute ? async (input, _ctx) => String(await execute(input)) : undefined;
+  return { config, handler };
+}
+function claudeAgentToolsToSpecTools(claudeTools) {
+  const configs = [];
+  const handlers = new Map;
+  for (const claudeTool of claudeTools) {
+    const { config, handler } = claudeAgentToolToSpecTool(claudeTool, claudeTool.execute);
+    configs.push(config);
+    if (handler) {
+      handlers.set(config.name, handler);
+    }
+  }
+  return { configs, handlers };
+}
+function specToolToExternalTool(tool, handler, context) {
+  return {
+    name: tool.name,
+    description: tool.description ?? `Execute ${tool.name}`,
+    inputSchema: tool.schema ?? { type: "object" },
+    requiresApproval: tool.requiresApproval ?? !tool.automationSafe,
+    execute: handler ? async (input) => {
+      const fullContext = {
+        agentId: context?.agentId ?? "unknown",
+        sessionId: context?.sessionId ?? "unknown",
+        tenantId: context?.tenantId,
+        actorId: context?.actorId,
+        metadata: context?.metadata,
+        signal: context?.signal
+      };
+      return handler(input, fullContext);
+    } : undefined
+  };
+}
+function normalizeSchema(schema) {
+  if (!schema) {
+    return { type: "object" };
+  }
+  if (schema.type === "object") {
+    return schema;
+  }
+  return {
+    type: "object",
+    properties: {
+      value: schema
+    },
+    required: ["value"]
+  };
+}
+function extractToolCalls(response) {
+  if (!response.content) {
+    return [];
+  }
+  return response.content.filter((block) => block.type === "tool_use").map((block) => ({
+    toolCallId: block.id ?? "",
+    toolName: block.name ?? "",
+    args: block.input
+  }));
+}
+
+// src/providers/opencode-sdk/tool-bridge.ts
+function specToolToOpenCodeTool(tool) {
+  return {
+    name: tool.name,
+    description: tool.description ?? `Execute ${tool.name}`,
+    parameters: normalizeToOpenCodeParameters(tool.schema),
+    permission: getPermissionLevel(tool)
+  };
+}
+function specToolsToOpenCodeTools(tools) {
+  return tools.map(specToolToOpenCodeTool);
+}
+function getPermissionLevel(tool) {
+  if (tool.requiresApproval) {
+    return "ask";
+  }
+  if (tool.automationSafe === false) {
+    return "ask";
+  }
+  return "allow";
+}
+function openCodeToolToSpecTool(openCodeTool) {
+  return {
+    name: openCodeTool.name,
+    description: openCodeTool.description,
+    schema: openCodeTool.parameters,
+    requiresApproval: openCodeTool.permission === "ask",
+    automationSafe: openCodeTool.permission === "allow"
+  };
+}
+function openCodeToolsToSpecTools(openCodeTools) {
+  return openCodeTools.map(openCodeToolToSpecTool);
+}
+function specToolToExternalToolForOpenCode(tool, handler, context) {
+  return {
+    name: tool.name,
+    description: tool.description ?? `Execute ${tool.name}`,
+    inputSchema: tool.schema ?? { type: "object" },
+    requiresApproval: tool.requiresApproval ?? !tool.automationSafe,
+    execute: handler ? async (input) => {
+      const fullContext = {
+        agentId: context?.agentId ?? "unknown",
+        sessionId: context?.sessionId ?? "unknown",
+        tenantId: context?.tenantId,
+        actorId: context?.actorId,
+        metadata: context?.metadata,
+        signal: context?.signal
+      };
+      return handler(input, fullContext);
+    } : undefined
+  };
+}
+function normalizeToOpenCodeParameters(schema) {
+  if (!schema) {
+    return { type: "object" };
+  }
+  if (schema.type === "object") {
+    return {
+      type: "object",
+      properties: schema.properties,
+      required: schema.required
+    };
+  }
+  return {
+    type: "object",
+    properties: {
+      value: convertToOpenCodeParameter(schema)
+    },
+    required: ["value"]
+  };
+}
+function convertToOpenCodeParameter(schema) {
+  const param = {
+    type: schema.type ?? "string"
+  };
+  if (schema.description) {
+    param.description = schema.description;
+  }
+  if (schema.enum) {
+    param.enum = schema.enum;
+  }
+  if (schema.default !== undefined) {
+    param.default = schema.default;
+  }
+  return param;
+}
+function createToolHandlerMap(tools) {
+  const handlers = new Map;
+  for (const [name, tool] of Object.entries(tools)) {
+    if (tool.execute) {
+      handlers.set(name, tool.execute);
+    }
+  }
+  return handlers;
+}
+async function executeToolCall(toolCall, handlers) {
+  const handler = handlers.get(toolCall.name);
+  if (!handler) {
+    return {
+      tool_call_id: toolCall.id,
+      output: `Error: Tool '${toolCall.name}' not found`,
+      is_error: true
+    };
+  }
+  try {
+    const result = await handler(toolCall.arguments);
+    return {
+      tool_call_id: toolCall.id,
+      output: typeof result === "string" ? result : JSON.stringify(result)
+    };
+  } catch (error) {
+    return {
+      tool_call_id: toolCall.id,
+      output: `Error: ${error instanceof Error ? error.message : String(error)}`,
+      is_error: true
+    };
+  }
+}
+
+// src/interop/tool-consumer.ts
+class MCPToolServer {
+  tools;
+  name;
+  version;
+  running = false;
+  constructor(config) {
+    this.tools = new Map;
+    this.name = config.name ?? "contractspec-tools";
+    this.version = config.version ?? "1.0.0";
+    for (const tool of config.tools) {
+      this.tools.set(tool.config.name, tool);
+    }
+  }
+  async start() {
+    if (this.running) {
+      return;
+    }
+    this.running = true;
+    console.log(`[MCPToolServer] Started ${this.name}@${this.version} with ${this.tools.size} tools`);
+  }
+  async stop() {
+    if (!this.running) {
+      return;
+    }
+    this.running = false;
+    console.log(`[MCPToolServer] Stopped ${this.name}`);
+  }
+  isRunning() {
+    return this.running;
+  }
+  getTools() {
+    return Array.from(this.tools.values()).map((t) => t.config);
+  }
+  async executeTool(toolName, args, context) {
+    const tool = this.tools.get(toolName);
+    if (!tool) {
+      throw new Error(`Tool not found: ${toolName}`);
+    }
+    if (!tool.handler) {
+      throw new Error(`No handler registered for tool: ${toolName}`);
+    }
+    const fullContext = {
+      agentId: context?.agentId ?? "mcp-server",
+      sessionId: context?.sessionId ?? "mcp-session",
+      tenantId: context?.tenantId,
+      actorId: context?.actorId,
+      metadata: context?.metadata,
+      signal: context?.signal
+    };
+    return await tool.handler(args, fullContext);
+  }
+  getMCPToolDefinitions() {
+    const definitions = [];
+    for (const [name, tool] of this.tools) {
+      definitions.push({
+        name,
+        description: tool.config.description ?? "",
+        inputSchema: tool.config.schema ?? { type: "object", properties: {} }
+      });
+    }
+    return definitions;
+  }
+  getServerInfo() {
+    return {
+      name: this.name,
+      version: this.version,
+      tools: this.tools.size,
+      running: this.running
+    };
+  }
+}
+
+class ContractSpecToolConsumer {
+  tools;
+  constructor(config) {
+    this.tools = new Map;
+    for (const tool of config.tools) {
+      this.tools.set(tool.config.name, tool);
+    }
+  }
+  createToolServer(config) {
+    return new MCPToolServer({
+      tools: Array.from(this.tools.values()),
+      ...config
+    });
+  }
+  exportToolsForSDK(format) {
+    const tools = Array.from(this.tools.values());
+    const defaultContext = {
+      agentId: "export",
+      sessionId: "export"
+    };
+    switch (format) {
+      case "claude-agent":
+        return tools.filter((tool) => !!tool.handler).map((tool) => specToolToClaudeAgentTool(tool.config, tool.handler, defaultContext));
+      case "opencode":
+        return tools.map((tool) => specToolToOpenCodeTool(tool.config));
+      case "mcp":
+        return tools.map((tool) => ({
+          name: tool.config.name,
+          description: tool.config.description ?? "",
+          inputSchema: tool.config.schema ?? { type: "object", properties: {} }
+        }));
+      case "openai":
+        return tools.map((tool) => ({
+          type: "function",
+          function: {
+            name: tool.config.name,
+            description: tool.config.description ?? "",
+            parameters: tool.config.schema ?? {
+              type: "object",
+              properties: {}
+            }
+          }
+        }));
+      default:
+        throw new Error(`Unknown export format: ${format}`);
+    }
+  }
+  createBridgedHandler(toolName, _format) {
+    const tool = this.tools.get(toolName);
+    if (!tool || !tool.handler) {
+      return;
+    }
+    const handler = tool.handler;
+    return async (args) => {
+      const context = {
+        agentId: "bridge",
+        sessionId: "bridge"
+      };
+      return handler(args, context);
+    };
+  }
+  getTools() {
+    return Array.from(this.tools.values()).map((t) => t.config);
+  }
+  getTool(name) {
+    return this.tools.get(name)?.config;
+  }
+  hasTool(name) {
+    return this.tools.has(name);
+  }
+  async executeTool(name, args, context) {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new Error(`Tool not found: ${name}`);
+    }
+    if (!tool.handler) {
+      throw new Error(`No handler for tool: ${name}`);
+    }
+    const fullContext = {
+      agentId: context?.agentId ?? "consumer",
+      sessionId: context?.sessionId ?? "consumer-session",
+      tenantId: context?.tenantId,
+      actorId: context?.actorId,
+      metadata: context?.metadata,
+      signal: context?.signal
+    };
+    return await tool.handler(args, fullContext);
+  }
+  addTool(config, handler) {
+    this.tools.set(config.name, { config, handler });
+  }
+  removeTool(name) {
+    return this.tools.delete(name);
+  }
+  getToolCount() {
+    return this.tools.size;
+  }
+}
+function createToolConsumer(config) {
+  return new ContractSpecToolConsumer(config);
+}
+function createToolServer(config) {
+  return new MCPToolServer(config);
+}
+function exportToolsForExternalSDK(tools, format) {
+  const consumer = new ContractSpecToolConsumer({
+    tools: tools.map((config) => ({ config }))
+  });
+  return consumer.exportToolsForSDK(format);
+}
+export {
+  exportToolsForExternalSDK,
+  createToolServer,
+  createToolConsumer,
+  ContractSpecToolConsumer
+};