@contractspec/lib.ai-agent 1.57.0 → 1.59.0

package/dist/node/providers/claude-agent-sdk/adapter.js

@@ -0,0 +1,624 @@
+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/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/claude-agent-sdk/session-bridge.ts
+function toClaudeAgentSession(state) {
+  const messages = [];
+  for (const msg of state.messages) {
+    if (msg.role === "user" || msg.role === "assistant") {
+      const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
+      messages.push({
+        role: msg.role,
+        content
+      });
+    }
+  }
+  return {
+    sessionId: state.sessionId,
+    messages,
+    metadata: {
+      agentId: state.agentId,
+      tenantId: state.tenantId,
+      actorId: state.actorId
+    }
+  };
+}
+function createClaudeAgentSession(options) {
+  return {
+    sessionId: options?.sessionId,
+    messages: [],
+    metadata: {
+      tenantId: options?.tenantId,
+      actorId: options?.actorId,
+      ...options?.metadata
+    }
+  };
+}
+function createEmptyClaudeSession() {
+  return createClaudeAgentSession();
+}
+function buildClaudeAgentContext(options) {
+  return {
+    tenantId: options?.tenantId,
+    actorId: options?.actorId,
+    sessionId: options?.sessionId,
+    ...options?.metadata
+  };
+}
+function appendUserMessage(session, content) {
+  return {
+    ...session,
+    messages: [...session.messages, { role: "user", content }]
+  };
+}
+function appendAssistantMessage(session, content) {
+  return {
+    ...session,
+    messages: [...session.messages, { role: "assistant", content }]
+  };
+}
+function clearSession(session) {
+  return {
+    ...session,
+    messages: []
+  };
+}
+function getRecentMessages(session, count) {
+  return session.messages.slice(-count);
+}
+function extractToolUseBlocks(content) {
+  if (typeof content === "string") {
+    return [];
+  }
+  return content.filter((block) => block.type === "tool_use");
+}
+function createToolResultBlock(toolUseId, result, isError = false) {
+  return {
+    type: "tool_result",
+    tool_use_id: toolUseId,
+    content: typeof result === "string" ? result : JSON.stringify(result),
+    is_error: isError
+  };
+}
+function updateSessionMetadata(session, metadata) {
+  return {
+    ...session,
+    metadata: {
+      ...session.metadata,
+      ...metadata
+    }
+  };
+}
+function getMessageCount(session) {
+  return session.messages.length;
+}
+function estimateTokens(session) {
+  let chars = 0;
+  for (const msg of session.messages) {
+    if (typeof msg.content === "string") {
+      chars += msg.content.length;
+    } else {
+      chars += JSON.stringify(msg.content).length;
+    }
+  }
+  return Math.ceil(chars / 4);
+}
+function summarizeSession(session) {
+  let userMessages = 0;
+  let assistantMessages = 0;
+  for (const msg of session.messages) {
+    if (msg.role === "user") {
+      userMessages++;
+    } else {
+      assistantMessages++;
+    }
+  }
+  return {
+    messageCount: session.messages.length,
+    userMessages,
+    assistantMessages,
+    estimatedTokens: estimateTokens(session)
+  };
+}
+
+// src/providers/claude-agent-sdk/adapter.ts
+class ClaudeAgentSDKProvider {
+  name = "claude-agent-sdk";
+  version = "1.0.0";
+  config;
+  sdkAvailable = null;
+  constructor(config = {}) {
+    this.config = {
+      model: "claude-sonnet-4-20250514",
+      extendedThinking: false,
+      computerUse: false,
+      maxTokens: 4096,
+      temperature: 0.7,
+      ...config
+    };
+  }
+  isAvailable() {
+    if (this.sdkAvailable !== null) {
+      return this.sdkAvailable;
+    }
+    try {
+      __require.resolve("@anthropic-ai/claude-agent-sdk");
+      const apiKey = this.config.apiKey ?? process.env.ANTHROPIC_API_KEY;
+      this.sdkAvailable = Boolean(apiKey);
+    } catch {
+      this.sdkAvailable = false;
+    }
+    return this.sdkAvailable;
+  }
+  async createContext(spec) {
+    if (!this.isAvailable()) {
+      throw new ProviderNotAvailableError(this.name, "SDK not installed or API key not configured");
+    }
+    try {
+      const toolSet = {};
+      for (const tool of spec.tools) {
+        toolSet[tool.name] = specToolToExternalTool(tool);
+      }
+      const instructions = await injectStaticKnowledge(spec.instructions, spec.knowledge ?? [], undefined);
+      const contextId = `claude-${agentKey(spec.meta)}-${Date.now()}`;
+      const metadata = {
+        computerUseEnabled: this.config.computerUse ?? false,
+        extendedThinkingEnabled: this.config.extendedThinking ?? false,
+        mcpServerIds: this.config.mcpServers?.map((s) => s.name) ?? []
+      };
+      return {
+        id: contextId,
+        spec: {
+          ...spec,
+          instructions
+        },
+        tools: toolSet,
+        metadata,
+        cleanup: async () => {}
+      };
+    } 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 systemPrompt = params.systemOverride ? `${context.spec.instructions}
+
+${params.systemOverride}` : context.spec.instructions;
+      const claudeContext = buildClaudeAgentContext(params.options);
+      let session = createEmptyClaudeSession();
+      session = appendUserMessage(session, params.prompt);
+      const claudeTools = this.prepareToolsForSDK(context, params);
+      const rawResponse = await sdk.execute({
+        model: this.config.model,
+        system: systemPrompt,
+        messages: session.messages,
+        tools: claudeTools,
+        max_tokens: this.config.maxTokens,
+        temperature: this.config.temperature,
+        metadata: claudeContext,
+        extended_thinking: this.config.extendedThinking,
+        computer_use: this.config.computerUse
+      });
+      const response = rawResponse;
+      const toolCalls = extractToolCalls(response);
+      const toolResults = await this.executeTools(toolCalls, context, params);
+      if (response.content) {
+        const content = response.content;
+        session = appendAssistantMessage(session, content);
+      }
+      return {
+        text: this.extractTextContent(response),
+        toolCalls: toolCalls.map((tc) => ({
+          type: "tool-call",
+          toolCallId: tc.toolCallId,
+          toolName: tc.toolName,
+          args: tc.args
+        })),
+        toolResults: toolResults.map((tr) => ({
+          type: "tool-result",
+          toolCallId: tr.toolCallId,
+          toolName: tr.toolName,
+          output: tr.output
+        })),
+        usage: {
+          inputTokens: response.usage?.input_tokens ?? 0,
+          outputTokens: response.usage?.output_tokens ?? 0
+        },
+        finishReason: this.mapStopReason(response.stop_reason),
+        metadata: {
+          sessionId: context.metadata?.sessionId,
+          model: response.model
+        }
+      };
+    } 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 systemPrompt = params.systemOverride ? `${context.spec.instructions}
+
+${params.systemOverride}` : context.spec.instructions;
+      const claudeContext = buildClaudeAgentContext(params.options);
+      const claudeTools = this.prepareToolsForSDK(context, params);
+      const stream = await sdk.stream({
+        model: this.config.model,
+        system: systemPrompt,
+        messages: [{ role: "user", content: params.prompt }],
+        tools: claudeTools,
+        max_tokens: this.config.maxTokens,
+        temperature: this.config.temperature,
+        metadata: claudeContext,
+        extended_thinking: this.config.extendedThinking,
+        computer_use: this.config.computerUse
+      });
+      let fullText = "";
+      const allToolCalls = [];
+      const allToolResults = [];
+      let stepIndex = 0;
+      for await (const event of stream) {
+        if (event.type === "content_block_delta" && event.delta?.type === "text_delta") {
+          const text = event.delta.text ?? "";
+          fullText += text;
+          yield { type: "text", text };
+        }
+        if (event.type === "content_block_start" && event.content_block?.type === "tool_use") {
+          const toolCall = {
+            toolCallId: event.content_block.id ?? "",
+            toolName: event.content_block.name ?? "",
+            args: event.content_block.input
+          };
+          allToolCalls.push(toolCall);
+          yield {
+            type: "tool-call",
+            toolCall: {
+              type: "tool-call",
+              ...toolCall
+            }
+          };
+        }
+        if (event.type === "message_stop") {
+          stepIndex++;
+          yield { type: "step-complete", stepIndex };
+        }
+      }
+      for (const toolCall of allToolCalls) {
+        const result = await this.executeTool(toolCall, context, params);
+        allToolResults.push(result);
+        yield {
+          type: "tool-result",
+          toolResult: {
+            type: "tool-result",
+            ...result
+          }
+        };
+      }
+      yield {
+        type: "done",
+        result: {
+          text: fullText,
+          toolCalls: allToolCalls.map((tc) => ({
+            type: "tool-call",
+            ...tc
+          })),
+          toolResults: allToolResults.map((tr) => ({
+            type: "tool-result",
+            ...tr
+          })),
+          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("@anthropic-ai/claude-agent-sdk");
+      return module.default ?? module;
+    } catch {
+      throw new ProviderNotAvailableError(this.name, "@anthropic-ai/claude-agent-sdk is not installed");
+    }
+  }
+  prepareToolsForSDK(context, params) {
+    const handlers = new Map;
+    for (const tool of context.spec.tools) {
+      const externalTool = context.tools[tool.name];
+      if (externalTool?.execute) {
+        handlers.set(tool.name, async (input) => {
+          if (!externalTool.execute) {
+            throw new Error(`Tool ${tool.name} has no execute handler`);
+          }
+          const result = await externalTool.execute(input);
+          return typeof result === "string" ? result : JSON.stringify(result);
+        });
+      }
+    }
+    return specToolsToClaudeAgentTools(context.spec.tools, handlers, {
+      agentId: context.id,
+      sessionId: params.options?.sessionId,
+      tenantId: params.options?.tenantId,
+      actorId: params.options?.actorId,
+      metadata: params.options?.metadata,
+      signal: params.signal
+    });
+  }
+  async executeTool(toolCall, context, _params) {
+    const tool = context.tools[toolCall.toolName];
+    if (!tool?.execute) {
+      return {
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output: `Error: Tool '${toolCall.toolName}' not found or has no handler`
+      };
+    }
+    try {
+      const output = await tool.execute(toolCall.args);
+      return {
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output
+      };
+    } catch (error) {
+      return {
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output: `Error: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+  }
+  async executeTools(toolCalls, context, params) {
+    return Promise.all(toolCalls.map((tc) => this.executeTool(tc, context, params)));
+  }
+  extractTextContent(response) {
+    if (!response.content) {
+      return "";
+    }
+    return response.content.filter((block) => typeof block === "object" && block !== null && block.type === "text").map((block) => block.text).join("");
+  }
+  mapStopReason(stopReason) {
+    switch (stopReason) {
+      case "end_turn":
+      case "stop_sequence":
+        return "stop";
+      case "tool_use":
+        return "tool-calls";
+      case "max_tokens":
+        return "length";
+      default:
+        return "stop";
+    }
+  }
+}
+var init_adapter = __esm(() => {
+  init_types();
+});
+init_adapter();
+
+export {
+  ClaudeAgentSDKProvider
+};