@contractspec/lib.ai-agent 1.57.0 → 1.59.0

package/dist/node/providers/opencode-sdk/index.js

@@ -0,0 +1,703 @@
+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/knowledge/injector.ts
+async function injectStaticKnowledge(instructions, knowledgeRefs, retriever) {
+  if (!retriever)
+    return instructions;
+  const requiredRefs = knowledgeRefs.filter((ref) => ref.required);
+  if (requiredRefs.length === 0)
+    return instructions;
+  const blocks = [];
+  for (const ref of requiredRefs) {
+    if (!retriever.supportsSpace(ref.key)) {
+      console.warn(`Required knowledge space "${ref.key}" is not available`);
+      continue;
+    }
+    try {
+      const content = await retriever.getStatic(ref.key);
+      if (content) {
+        const header = ref.instructions ? `## ${ref.key}
+${ref.instructions}` : `## ${ref.key}`;
+        blocks.push(`${header}
+
+${content}`);
+      }
+    } catch (error) {
+      console.warn(`Failed to load required knowledge "${ref.key}":`, error);
+    }
+  }
+  if (blocks.length === 0)
+    return instructions;
+  return `${instructions}
+
+---
+
+# Reference Knowledge
+
+The following information is provided for your reference. Use it to inform your responses.
+
+${blocks.join(`
+
+---
+
+`)}`;
+}
+function createKnowledgeInjector(retriever) {
+  return {
+    inject: (instructions, knowledgeRefs) => injectStaticKnowledge(instructions, knowledgeRefs, retriever),
+    hasSpace: (spaceKey) => retriever?.supportsSpace(spaceKey) ?? false,
+    listSpaces: () => retriever?.listSpaces() ?? []
+  };
+}
+
+// src/providers/types.ts
+var ExternalProviderError, ProviderNotAvailableError, ProviderExecutionError, ContextCreationError;
+var init_types = __esm(() => {
+  ExternalProviderError = class ExternalProviderError extends Error {
+    provider;
+    code;
+    cause;
+    constructor(message, provider, code, cause) {
+      super(message);
+      this.provider = provider;
+      this.code = code;
+      this.cause = cause;
+      this.name = "ExternalProviderError";
+    }
+  };
+  ProviderNotAvailableError = class ProviderNotAvailableError extends ExternalProviderError {
+    constructor(provider, reason) {
+      super(`Provider '${provider}' is not available${reason ? `: ${reason}` : ""}`, provider, "PROVIDER_NOT_AVAILABLE");
+      this.name = "ProviderNotAvailableError";
+    }
+  };
+  ProviderExecutionError = class ProviderExecutionError extends ExternalProviderError {
+    constructor(provider, message, cause) {
+      super(message, provider, "EXECUTION_FAILED", cause);
+      this.name = "ProviderExecutionError";
+    }
+  };
+  ContextCreationError = class ContextCreationError extends ExternalProviderError {
+    constructor(provider, message, cause) {
+      super(message, provider, "CONTEXT_CREATION_FAILED", cause);
+      this.name = "ContextCreationError";
+    }
+  };
+});
+
+// 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/providers/opencode-sdk/adapter.ts
+class OpenCodeSDKProvider {
+  name = "opencode-sdk";
+  version = "1.0.0";
+  config;
+  sdkAvailable = null;
+  constructor(config = {}) {
+    this.config = {
+      serverUrl: "http://127.0.0.1:4096",
+      port: 4096,
+      agentType: "general",
+      temperature: 0.7,
+      timeout: 30000,
+      ...config
+    };
+    if (!config.serverUrl && config.port) {
+      this.config.serverUrl = `http://127.0.0.1:${config.port}`;
+    }
+  }
+  isAvailable() {
+    if (this.sdkAvailable !== null) {
+      return this.sdkAvailable;
+    }
+    try {
+      __require.resolve("@opencode-ai/sdk");
+      this.sdkAvailable = true;
+    } catch {
+      this.sdkAvailable = false;
+    }
+    return this.sdkAvailable;
+  }
+  async createContext(spec) {
+    if (!this.isAvailable()) {
+      throw new ProviderNotAvailableError(this.name, "SDK not installed");
+    }
+    try {
+      const sdk = await this.loadSDK();
+      const { client } = await sdk.createOpencode({
+        hostname: this.getHostname(),
+        port: this.config.port ?? 4096,
+        timeout: this.config.timeout
+      });
+      const session = await client.session.create({
+        agent: this.config.agentType ?? inferAgentType(spec),
+        model: this.config.model
+      });
+      const toolSet = {};
+      for (const tool of spec.tools) {
+        toolSet[tool.name] = specToolToExternalToolForOpenCode(tool);
+      }
+      const instructions = await injectStaticKnowledge(spec.instructions, spec.knowledge ?? [], undefined);
+      const contextId = `opencode-${agentKey(spec.meta)}-${Date.now()}`;
+      const metadata = {
+        sessionId: session.id,
+        agentType: this.config.agentType ?? inferAgentType(spec),
+        serverUrl: this.config.serverUrl ?? `http://127.0.0.1:${this.config.port ?? 4096}`
+      };
+      return {
+        id: contextId,
+        spec: {
+          ...spec,
+          instructions
+        },
+        tools: toolSet,
+        metadata,
+        cleanup: async () => {
+          try {
+            await client.session.delete({ id: session.id });
+          } catch {}
+        }
+      };
+    } catch (error) {
+      throw new ContextCreationError(this.name, `Failed to create context: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+    }
+  }
+  async execute(context, params) {
+    try {
+      const sdk = await this.loadSDK();
+      const metadata = context.metadata;
+      const { client } = await sdk.createOpencodeClient({
+        baseUrl: metadata.serverUrl
+      });
+      const systemPrompt = params.systemOverride ? `${context.spec.instructions}
+
+${params.systemOverride}` : context.spec.instructions;
+      const response = await client.session.prompt({
+        id: metadata.sessionId,
+        body: {
+          content: params.prompt,
+          system: systemPrompt
+        }
+      });
+      const toolCalls = this.extractToolCalls(response);
+      const toolHandlers = createToolHandlerMap(context.tools);
+      const toolResults = await Promise.all(toolCalls.map((tc) => executeToolCall(tc, toolHandlers)));
+      return {
+        text: this.extractTextContent(response),
+        toolCalls: toolCalls.map((tc) => ({
+          type: "tool-call",
+          toolCallId: tc.id,
+          toolName: tc.name,
+          args: tc.arguments
+        })),
+        toolResults: toolResults.map((tr) => ({
+          type: "tool-result",
+          toolCallId: tr.tool_call_id,
+          toolName: toolCalls.find((tc) => tc.id === tr.tool_call_id)?.name ?? "",
+          output: tr.output
+        })),
+        usage: {
+          inputTokens: response.usage?.input_tokens ?? 0,
+          outputTokens: response.usage?.output_tokens ?? 0
+        },
+        finishReason: this.mapFinishReason(response.finish_reason),
+        metadata: {
+          sessionId: metadata.sessionId,
+          agentType: metadata.agentType
+        }
+      };
+    } catch (error) {
+      throw new ProviderExecutionError(this.name, `Execution failed: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+    }
+  }
+  async* stream(context, params) {
+    try {
+      const sdk = await this.loadSDK();
+      const metadata = context.metadata;
+      const { client } = await sdk.createOpencodeClient({
+        baseUrl: metadata.serverUrl
+      });
+      const systemPrompt = params.systemOverride ? `${context.spec.instructions}
+
+${params.systemOverride}` : context.spec.instructions;
+      const events = client.session.subscribe({
+        id: metadata.sessionId
+      });
+      await client.session.prompt({
+        id: metadata.sessionId,
+        body: {
+          content: params.prompt,
+          system: systemPrompt
+        }
+      });
+      let fullText = "";
+      const allToolCalls = [];
+      const toolHandlers = createToolHandlerMap(context.tools);
+      let stepIndex = 0;
+      for await (const event of events) {
+        if (event.type === "message.delta") {
+          const text = event.delta?.content ?? "";
+          fullText += text;
+          yield { type: "text", text };
+        }
+        if (event.type === "tool.call") {
+          const toolCall = {
+            id: event.tool_call_id ?? `tc-${Date.now()}`,
+            name: event.tool_name ?? "",
+            arguments: event.arguments ?? {}
+          };
+          allToolCalls.push(toolCall);
+          yield {
+            type: "tool-call",
+            toolCall: {
+              type: "tool-call",
+              toolCallId: toolCall.id,
+              toolName: toolCall.name,
+              args: toolCall.arguments
+            }
+          };
+        }
+        if (event.type === "step.complete") {
+          stepIndex++;
+          yield { type: "step-complete", stepIndex };
+        }
+        if (event.type === "message.complete") {
+          break;
+        }
+      }
+      for (const toolCall of allToolCalls) {
+        const result = await executeToolCall(toolCall, toolHandlers);
+        yield {
+          type: "tool-result",
+          toolResult: {
+            type: "tool-result",
+            toolCallId: result.tool_call_id,
+            toolName: toolCall.name,
+            output: result.output
+          }
+        };
+      }
+      yield {
+        type: "done",
+        result: {
+          text: fullText,
+          toolCalls: allToolCalls.map((tc) => ({
+            type: "tool-call",
+            toolCallId: tc.id,
+            toolName: tc.name,
+            args: tc.arguments
+          })),
+          toolResults: [],
+          usage: { inputTokens: 0, outputTokens: 0 },
+          finishReason: "stop"
+        }
+      };
+    } catch (error) {
+      throw new ProviderExecutionError(this.name, `Stream failed: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+    }
+  }
+  async loadSDK() {
+    try {
+      const module = __require("@opencode-ai/sdk");
+      return module;
+    } catch {
+      throw new ProviderNotAvailableError(this.name, "@opencode-ai/sdk is not installed");
+    }
+  }
+  getHostname() {
+    if (!this.config.serverUrl) {
+      return "127.0.0.1";
+    }
+    try {
+      const url = new URL(this.config.serverUrl);
+      return url.hostname;
+    } catch {
+      return "127.0.0.1";
+    }
+  }
+  extractToolCalls(response) {
+    if (!response.tool_calls) {
+      return [];
+    }
+    return response.tool_calls.map((tc) => ({
+      id: tc.id,
+      name: tc.name,
+      arguments: tc.arguments ?? {}
+    }));
+  }
+  extractTextContent(response) {
+    return response.content ?? response.message?.content ?? "";
+  }
+  mapFinishReason(finishReason) {
+    switch (finishReason) {
+      case "stop":
+      case "end":
+        return "stop";
+      case "tool_use":
+      case "tool_calls":
+        return "tool-calls";
+      case "length":
+      case "max_tokens":
+        return "length";
+      default:
+        return "stop";
+    }
+  }
+}
+var init_adapter = __esm(() => {
+  init_types();
+  init_agent_bridge();
+});
+
+// src/providers/opencode-sdk/index.ts
+var exports_opencode_sdk = {};
+__export(exports_opencode_sdk, {
+  specToolsToOpenCodeTools: () => specToolsToOpenCodeTools,
+  specToolToOpenCodeTool: () => specToolToOpenCodeTool,
+  specToolToExternalToolForOpenCode: () => specToolToExternalToolForOpenCode,
+  specToOpenCodeMarkdown: () => specToOpenCodeMarkdown,
+  specToOpenCodeConfig: () => specToOpenCodeConfig,
+  serializeOpenCodeMarkdown: () => serializeOpenCodeMarkdown,
+  openCodeToolsToSpecTools: () => openCodeToolsToSpecTools,
+  openCodeToolToSpecTool: () => openCodeToolToSpecTool,
+  openCodeConfigToSpec: () => openCodeConfigToSpec,
+  inferAgentType: () => inferAgentType,
+  executeToolCall: () => executeToolCall,
+  createToolHandlerMap: () => createToolHandlerMap,
+  OpenCodeSDKProvider: () => OpenCodeSDKProvider
+});
+var init_opencode_sdk = __esm(() => {
+  init_adapter();
+  init_agent_bridge();
+});
+init_opencode_sdk();
+
+export {
+  specToolsToOpenCodeTools,
+  specToolToOpenCodeTool,
+  specToolToExternalToolForOpenCode,
+  specToOpenCodeMarkdown,
+  specToOpenCodeConfig,
+  serializeOpenCodeMarkdown,
+  openCodeToolsToSpecTools,
+  openCodeToolToSpecTool,
+  openCodeConfigToSpec,
+  inferAgentType,
+  executeToolCall,
+  createToolHandlerMap,
+  OpenCodeSDKProvider
+};