@contractspec/lib.ai-agent 1.57.0 → 1.59.0

package/dist/node/exporters/index.js

@@ -0,0 +1,738 @@
+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/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/providers/opencode-sdk/agent-bridge.ts
+function inferAgentType(spec) {
+  const hasCodeTools = spec.tools.some((tool) => [
+    "write_file",
+    "edit_file",
+    "create_file",
+    "delete_file",
+    "bash",
+    "execute",
+    "run_command",
+    "terminal"
+  ].includes(tool.name.toLowerCase()));
+  const instructionsLower = spec.instructions.toLowerCase();
+  const hasPlanningKeywords = /\b(plan|design|architect|strategy|analyze|review|assess|evaluate)\b/.test(instructionsLower);
+  const hasExplorationKeywords = /\b(search|find|explore|discover|locate|grep|pattern)\b/.test(instructionsLower);
+  const hasResearchKeywords = /\b(research|investigate|understand|learn|gather|collect)\b/.test(instructionsLower);
+  if (hasCodeTools) {
+    return "build";
+  }
+  if (hasPlanningKeywords && !hasCodeTools) {
+    return "plan";
+  }
+  if (hasExplorationKeywords && !hasResearchKeywords) {
+    return "explore";
+  }
+  return "general";
+}
+function specToOpenCodeConfig(spec, options) {
+  const agentType = options?.agentType ?? inferAgentType(spec);
+  return {
+    name: spec.meta.key,
+    version: spec.meta.version,
+    description: spec.description ?? spec.meta.description,
+    instructions: spec.instructions,
+    agent_type: agentType,
+    tools: specToolsToOpenCodeTools(spec.tools),
+    config: {
+      max_steps: options?.maxSteps ?? spec.maxSteps ?? 10,
+      temperature: options?.temperature ?? 0.7,
+      model: options?.model,
+      permissions: buildPermissions(spec)
+    }
+  };
+}
+function buildPermissions(spec) {
+  const permissions = {};
+  for (const tool of spec.tools) {
+    if (tool.requiresApproval) {
+      permissions[tool.name] = "ask";
+    } else if (tool.automationSafe === false) {
+      permissions[tool.name] = "ask";
+    } else {
+      permissions[tool.name] = "allow";
+    }
+  }
+  return permissions;
+}
+function specToOpenCodeMarkdown(spec, options) {
+  const agentType = options?.agentType ?? inferAgentType(spec);
+  return {
+    frontmatter: {
+      name: spec.meta.key,
+      type: agentType,
+      version: spec.meta.version,
+      model: options?.model,
+      temperature: options?.temperature ?? 0.7,
+      max_steps: options?.maxSteps ?? spec.maxSteps ?? 10,
+      tools: spec.tools.map((t) => t.name)
+    },
+    body: buildMarkdownBody(spec)
+  };
+}
+function buildMarkdownBody(spec) {
+  const lines = [];
+  lines.push(`# ${spec.meta.key}`);
+  lines.push("");
+  if (spec.description ?? spec.meta.description) {
+    lines.push(spec.description ?? spec.meta.description ?? "");
+    lines.push("");
+  }
+  lines.push("## Instructions");
+  lines.push("");
+  lines.push(spec.instructions);
+  lines.push("");
+  if (spec.tools.length > 0) {
+    lines.push("## Tools");
+    lines.push("");
+    for (const tool of spec.tools) {
+      const permission = tool.requiresApproval ? "(requires approval)" : tool.automationSafe === false ? "(ask mode)" : "";
+      lines.push(`- **${tool.name}**: ${tool.description ?? "No description"} ${permission}`.trim());
+    }
+    lines.push("");
+  }
+  if (spec.knowledge && spec.knowledge.length > 0) {
+    lines.push("## Knowledge Sources");
+    lines.push("");
+    for (const k of spec.knowledge) {
+      const required = k.required ? "(required)" : "(optional)";
+      lines.push(`- ${k.key} ${required}`);
+    }
+    lines.push("");
+  }
+  return lines.join(`
+`);
+}
+function serializeOpenCodeMarkdown(markdown) {
+  const lines = [];
+  lines.push("---");
+  lines.push(`name: ${markdown.frontmatter.name}`);
+  lines.push(`type: ${markdown.frontmatter.type}`);
+  if (markdown.frontmatter.version) {
+    lines.push(`version: ${markdown.frontmatter.version}`);
+  }
+  if (markdown.frontmatter.model) {
+    lines.push(`model: ${markdown.frontmatter.model}`);
+  }
+  if (markdown.frontmatter.temperature !== undefined) {
+    lines.push(`temperature: ${markdown.frontmatter.temperature}`);
+  }
+  if (markdown.frontmatter.max_steps !== undefined) {
+    lines.push(`max_steps: ${markdown.frontmatter.max_steps}`);
+  }
+  if (markdown.frontmatter.tools && markdown.frontmatter.tools.length > 0) {
+    lines.push(`tools:`);
+    for (const tool of markdown.frontmatter.tools) {
+      lines.push(`  - ${tool}`);
+    }
+  }
+  lines.push("---");
+  lines.push("");
+  lines.push(markdown.body);
+  return lines.join(`
+`);
+}
+function openCodeConfigToSpec(config) {
+  return {
+    meta: {
+      key: config.name,
+      version: config.version ?? "1.0.0",
+      description: config.description ?? "",
+      stability: "experimental",
+      owners: [],
+      tags: []
+    },
+    description: config.description,
+    instructions: config.instructions ?? "",
+    tools: config.tools?.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      schema: tool.parameters,
+      requiresApproval: tool.permission === "ask",
+      automationSafe: tool.permission === "allow"
+    })) ?? [],
+    maxSteps: config.config?.max_steps ?? 10
+  };
+}
+var init_agent_bridge = () => {};
+
+// src/exporters/claude-agent-exporter.ts
+class ClaudeAgentExporter {
+  format = "claude-agent";
+  export(spec, options = {}) {
+    const tools = this.exportTools(spec);
+    const config = this.buildConfig(spec, tools, options);
+    const claudeMd = options.generateClaudeMd ? this.generateClaudeMd(spec, options) : undefined;
+    return {
+      config,
+      claudeMd,
+      tools,
+      exportedAt: new Date,
+      sourceSpec: agentKey(spec.meta)
+    };
+  }
+  exportMany(specs, options = {}) {
+    return specs.map((spec) => this.export(spec, options));
+  }
+  validate(spec) {
+    const errors = [];
+    if (!spec.meta?.key) {
+      errors.push("Spec must have a meta.key");
+    }
+    if (!spec.instructions) {
+      errors.push("Spec must have instructions");
+    }
+    if (!spec.tools || spec.tools.length === 0) {
+      errors.push("Spec must have at least one tool");
+    }
+    for (const tool of spec.tools ?? []) {
+      if (!tool.name) {
+        errors.push("All tools must have a name");
+      }
+      if (!tool.description && !tool.name) {
+        errors.push(`Tool must have a description or name`);
+      }
+    }
+    return { valid: errors.length === 0, errors };
+  }
+  buildConfig(spec, tools, options) {
+    const config = {
+      model: options.model ?? "claude-sonnet-4-20250514",
+      system: this.buildSystemPrompt(spec, options),
+      tools,
+      max_turns: spec.maxSteps ?? 10
+    };
+    if (options.computerUse) {
+      config.computer_use = true;
+    }
+    if (options.extendedThinking) {
+      config.extended_thinking = true;
+    }
+    if (options.mcpServers && options.mcpServers.length > 0) {
+      config.mcp_servers = options.mcpServers;
+    }
+    return config;
+  }
+  buildSystemPrompt(spec, options) {
+    const parts = [];
+    parts.push(spec.instructions);
+    if (spec.knowledge && spec.knowledge.length > 0) {
+      parts.push("");
+      parts.push("## Knowledge Sources");
+      for (const k of spec.knowledge) {
+        if (k.instructions) {
+          parts.push(`- ${k.key}: ${k.instructions}`);
+        }
+      }
+    }
+    if (spec.policy) {
+      parts.push("");
+      parts.push("## Policy");
+      if (spec.policy.confidence?.min) {
+        parts.push(`- Minimum confidence: ${spec.policy.confidence.min}`);
+      }
+      if (spec.policy.escalation) {
+        parts.push("- Escalation policy is configured");
+      }
+    }
+    if (options.metadata) {
+      parts.push("");
+      parts.push("## Additional Context");
+      for (const [key, value] of Object.entries(options.metadata)) {
+        parts.push(`- ${key}: ${String(value)}`);
+      }
+    }
+    return parts.join(`
+`);
+  }
+  exportTools(spec) {
+    return spec.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description ?? `Execute ${tool.name}`,
+      input_schema: this.normalizeSchema(tool.schema),
+      requires_confirmation: tool.requiresApproval ?? !tool.automationSafe
+    }));
+  }
+  normalizeSchema(schema) {
+    if (!schema) {
+      return { type: "object" };
+    }
+    if (schema.type === "object") {
+      return {
+        type: "object",
+        properties: schema.properties,
+        required: schema.required
+      };
+    }
+    return {
+      type: "object",
+      properties: { value: schema },
+      required: ["value"]
+    };
+  }
+  generateClaudeMd(spec, options) {
+    const lines = [];
+    lines.push("# Agent Configuration");
+    lines.push("");
+    if (spec.description) {
+      lines.push(`> ${spec.description}`);
+      lines.push("");
+    }
+    lines.push("## Metadata");
+    lines.push("");
+    lines.push(`- **Name**: ${spec.meta.key}`);
+    lines.push(`- **Version**: ${spec.meta.version}`);
+    if (spec.meta.owners && spec.meta.owners.length > 0) {
+      lines.push(`- **Owners**: ${spec.meta.owners.join(", ")}`);
+    }
+    if (options.model) {
+      lines.push(`- **Model**: ${options.model}`);
+    }
+    lines.push("");
+    lines.push("## Instructions");
+    lines.push("");
+    lines.push(spec.instructions);
+    lines.push("");
+    if (spec.tools.length > 0) {
+      lines.push("## Available Tools");
+      lines.push("");
+      for (const tool of spec.tools) {
+        const flags = [];
+        if (tool.requiresApproval) {
+          flags.push("requires approval");
+        }
+        if (tool.automationSafe === false) {
+          flags.push("not automation safe");
+        }
+        const flagStr = flags.length > 0 ? ` (${flags.join(", ")})` : "";
+        lines.push(`### ${tool.name}${flagStr}`);
+        lines.push("");
+        if (tool.description) {
+          lines.push(tool.description);
+          lines.push("");
+        }
+        if (tool.schema) {
+          lines.push("**Parameters:**");
+          lines.push("```json");
+          lines.push(JSON.stringify(tool.schema, null, 2));
+          lines.push("```");
+          lines.push("");
+        }
+      }
+    }
+    if (spec.knowledge && spec.knowledge.length > 0) {
+      lines.push("## Knowledge Sources");
+      lines.push("");
+      for (const k of spec.knowledge) {
+        const required = k.required ? "(required)" : "(optional)";
+        lines.push(`- **${k.key}** ${required}`);
+        if (k.instructions) {
+          lines.push(`  - ${k.instructions}`);
+        }
+      }
+      lines.push("");
+    }
+    if (spec.policy) {
+      lines.push("## Policy");
+      lines.push("");
+      if (spec.policy.confidence?.min) {
+        lines.push(`- Minimum confidence: ${spec.policy.confidence.min}`);
+      }
+      if (spec.policy.escalation) {
+        lines.push("- Escalation policy configured");
+      }
+      if (spec.policy.flags && spec.policy.flags.length > 0) {
+        lines.push(`- Feature flags: ${spec.policy.flags.join(", ")}`);
+      }
+      lines.push("");
+    }
+    if (options.mcpServers && options.mcpServers.length > 0) {
+      lines.push("## MCP Servers");
+      lines.push("");
+      for (const server of options.mcpServers) {
+        lines.push(`- **${server.name}**: \`${server.command}${server.args ? " " + server.args.join(" ") : ""}\``);
+      }
+      lines.push("");
+    }
+    lines.push("---");
+    lines.push("");
+    lines.push(`*Generated from ContractSpec: ${agentKey(spec.meta)}*`);
+    return lines.join(`
+`);
+  }
+}
+function exportToClaudeAgent(spec, options) {
+  const exporter = new ClaudeAgentExporter;
+  return exporter.export(spec, options);
+}
+function generateClaudeMd(spec, options) {
+  const exporter = new ClaudeAgentExporter;
+  const result = exporter.export(spec, { ...options, generateClaudeMd: true });
+  return result.claudeMd ?? "";
+}
+function validateForClaudeAgent(spec) {
+  const exporter = new ClaudeAgentExporter;
+  return exporter.validate(spec);
+}
+// src/exporters/opencode-exporter.ts
+init_agent_bridge();
+
+class OpenCodeExporter {
+  format = "opencode";
+  export(spec, options = {}) {
+    const jsonConfig = this.buildJsonConfig(spec, options);
+    const markdownConfig = this.generateMarkdown(spec, jsonConfig, options);
+    return {
+      jsonConfig,
+      markdownConfig,
+      exportedAt: new Date,
+      sourceSpec: agentKey(spec.meta)
+    };
+  }
+  exportMany(specs, options = {}) {
+    return specs.map((spec) => this.export(spec, options));
+  }
+  validate(spec) {
+    const errors = [];
+    if (!spec.meta?.key) {
+      errors.push("Spec must have a meta.key");
+    }
+    if (!spec.instructions) {
+      errors.push("Spec must have instructions");
+    }
+    for (const tool of spec.tools ?? []) {
+      if (!tool.name) {
+        errors.push("All tools must have a name");
+      }
+      if (tool.name && !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tool.name)) {
+        errors.push(`Tool name '${tool.name}' should be a valid identifier (letters, numbers, underscores)`);
+      }
+    }
+    return { valid: errors.length === 0, errors };
+  }
+  buildJsonConfig(spec, options) {
+    const agentType = options.agentType ?? inferAgentType(spec);
+    return {
+      name: spec.meta.key,
+      version: spec.meta.version,
+      description: spec.description,
+      type: agentType,
+      instructions: spec.instructions,
+      tools: this.exportTools(spec),
+      config: {
+        max_steps: options.maxSteps ?? spec.maxSteps ?? 10,
+        temperature: options.temperature ?? 0.7,
+        model: options.model
+      }
+    };
+  }
+  exportTools(spec) {
+    return spec.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description ?? `Execute ${tool.name}`,
+      schema: tool.schema ?? { type: "object" },
+      requires_approval: tool.requiresApproval ?? !tool.automationSafe
+    }));
+  }
+  generateMarkdown(spec, jsonConfig, options) {
+    const lines = [];
+    lines.push("---");
+    lines.push(`name: ${jsonConfig.name}`);
+    lines.push(`type: ${jsonConfig.type}`);
+    if (jsonConfig.version) {
+      lines.push(`version: ${jsonConfig.version}`);
+    }
+    if (jsonConfig.config.model) {
+      lines.push(`model: ${jsonConfig.config.model}`);
+    }
+    if (jsonConfig.config.temperature !== undefined) {
+      lines.push(`temperature: ${jsonConfig.config.temperature}`);
+    }
+    if (jsonConfig.config.max_steps !== undefined) {
+      lines.push(`max_steps: ${jsonConfig.config.max_steps}`);
+    }
+    if (jsonConfig.tools.length > 0) {
+      lines.push("tools:");
+      for (const tool of jsonConfig.tools) {
+        const permission = tool.requires_approval ? " # requires approval" : "";
+        lines.push(`  - ${tool.name}${permission}`);
+      }
+    }
+    lines.push("---");
+    lines.push("");
+    lines.push(`# ${spec.meta.key}`);
+    lines.push("");
+    if (spec.description) {
+      lines.push(spec.description);
+      lines.push("");
+    }
+    lines.push(`> Agent type: **${jsonConfig.type}**`);
+    lines.push("");
+    lines.push(this.getAgentTypeDescription(jsonConfig.type));
+    lines.push("");
+    lines.push("## Instructions");
+    lines.push("");
+    lines.push(spec.instructions);
+    lines.push("");
+    if (spec.tools.length > 0) {
+      lines.push("## Tools");
+      lines.push("");
+      for (const tool of spec.tools) {
+        const approval = tool.requiresApproval ? " *(requires approval)*" : "";
+        const safe = tool.automationSafe === false ? " *(not automation safe)*" : "";
+        lines.push(`### ${tool.name}${approval}${safe}`);
+        lines.push("");
+        if (tool.description) {
+          lines.push(tool.description);
+          lines.push("");
+        }
+        if (tool.schema && options.includeComments !== false) {
+          lines.push("**Parameters:**");
+          lines.push("");
+          lines.push("```json");
+          lines.push(JSON.stringify(tool.schema, null, options.prettyPrint !== false ? 2 : 0));
+          lines.push("```");
+          lines.push("");
+        }
+      }
+    }
+    if (spec.knowledge && spec.knowledge.length > 0) {
+      lines.push("## Knowledge Sources");
+      lines.push("");
+      for (const k of spec.knowledge) {
+        const required = k.required ? "(required)" : "(optional)";
+        lines.push(`- **${k.key}** ${required}`);
+        if (k.instructions) {
+          lines.push(`  - ${k.instructions}`);
+        }
+      }
+      lines.push("");
+    }
+    if (spec.policy) {
+      lines.push("## Policy");
+      lines.push("");
+      if (spec.policy.confidence?.min) {
+        lines.push(`- Minimum confidence: ${spec.policy.confidence.min}`);
+      }
+      if (spec.policy.escalation) {
+        lines.push("- Escalation policy configured");
+      }
+      lines.push("");
+    }
+    lines.push("## Configuration");
+    lines.push("");
+    lines.push("```json");
+    lines.push(JSON.stringify(jsonConfig.config, null, options.prettyPrint !== false ? 2 : 0));
+    lines.push("```");
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push(`*Generated from ContractSpec: ${agentKey(spec.meta)}*`);
+    lines.push(`*Exported at: ${new Date().toISOString()}*`);
+    return lines.join(`
+`);
+  }
+  getAgentTypeDescription(type) {
+    switch (type) {
+      case "build":
+        return "Primary agent with full tool access for code generation and modification.";
+      case "plan":
+        return "Restricted agent for analysis and planning. File edits and bash commands require approval.";
+      case "general":
+        return "General-purpose subagent for complex questions and multi-step tasks.";
+      case "explore":
+        return "Fast subagent optimized for codebase exploration and pattern searching.";
+      default:
+        return "";
+    }
+  }
+}
+function exportToOpenCode(spec, options) {
+  const exporter = new OpenCodeExporter;
+  return exporter.export(spec, options);
+}
+function generateOpenCodeMarkdown(spec, options) {
+  const exporter = new OpenCodeExporter;
+  const result = exporter.export(spec, options);
+  return result.markdownConfig;
+}
+function generateOpenCodeJSON(spec, options) {
+  const exporter = new OpenCodeExporter;
+  const result = exporter.export(spec, options);
+  return result.jsonConfig;
+}
+function validateForOpenCode(spec) {
+  const exporter = new OpenCodeExporter;
+  return exporter.validate(spec);
+}
+export {
+  validateForOpenCode,
+  validateForClaudeAgent,
+  generateOpenCodeMarkdown,
+  generateOpenCodeJSON,
+  generateClaudeMd,
+  exportToOpenCode,
+  exportToClaudeAgent,
+  OpenCodeExporter,
+  ClaudeAgentExporter
+};