@ouraihub/llm 0.2.0

package/dist/esm/index.mjs

@@ -0,0 +1,972 @@
+// src/logger.ts
+var noopLogger = {
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+var consoleLogger = {
+  info: (msg, data) => console.log(JSON.stringify({ level: "info", msg, ...data, ts: (/* @__PURE__ */ new Date()).toISOString() })),
+  warn: (msg, data) => console.warn(JSON.stringify({ level: "warn", msg, ...data, ts: (/* @__PURE__ */ new Date()).toISOString() })),
+  error: (msg, data) => console.error(JSON.stringify({ level: "error", msg, ...data, ts: (/* @__PURE__ */ new Date()).toISOString() }))
+};
+
+// src/errors.ts
+var LLMError = class extends Error {
+  constructor(message, vendor, statusCode, durationMs) {
+    super(message);
+    this.name = "LLMError";
+    this.vendor = vendor;
+    this.statusCode = statusCode;
+    this.durationMs = durationMs;
+  }
+};
+var LLMTimeoutError = class extends LLMError {
+  constructor(vendor, timeoutMs) {
+    super(`${vendor} request timed out after ${timeoutMs}ms`, vendor);
+    this.name = "LLMTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+var LLMSchemaError = class extends LLMError {
+  constructor(vendor, details) {
+    super(`${vendor} output failed schema validation: ${details}`, vendor);
+    this.name = "LLMSchemaError";
+  }
+};
+
+// src/base-provider.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 2;
+var RETRY_BASE_DELAY_MS = 1e3;
+var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var BaseLLMProvider = class {
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? this.getDefaultBaseUrl()).replace(/\/+$/, "");
+    this.model = config.model ?? this.getDefaultModel();
+    this.vendor = config.vendor ?? this.getVendorName();
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.logger = config.logger ?? noopLogger;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+  }
+  /** Structured completion with Zod schema validation */
+  async complete(prompt, schema, options) {
+    const result = await this.raw(prompt, { ...options, jsonMode: true });
+    return this.parseAndValidate(result.content, schema);
+  }
+  /** Raw completion without schema enforcement */
+  async raw(prompt, options) {
+    const { url, init } = this.buildRequest(prompt, options);
+    return this.executeRequest(url, init);
+  }
+  /** Multi-turn completion: native message history support */
+  async messages(messages, options) {
+    const { url, init } = this.buildMessagesRequest(messages, options);
+    return this.executeRequest(url, init);
+  }
+  /** Streaming completion: yields text chunks */
+  async *stream(prompt, options) {
+    const { url, init } = this.buildRequest(prompt, { ...options, stream: true });
+    yield* this.executeStream(url, init);
+  }
+  /** Streaming with full message history */
+  async *streamMessages(messages, options) {
+    const { url, init } = this.buildMessagesRequest(messages, { ...options, stream: true });
+    yield* this.executeStream(url, init);
+  }
+  async *executeStream(url, init) {
+    const start = Date.now();
+    this.logger.info("llm_stream_start", { vendor: this.vendor, model: this.model });
+    const response = await this.fetchWithTimeout(url, init);
+    if (!response.ok) {
+      const body = await safeReadText(response);
+      this.logger.error("llm_stream_failed", { vendor: this.vendor, status: response.status });
+      throw new LLMError(`${this.vendor} stream returned ${response.status}: ${body.slice(0, 200)}`, this.vendor, response.status);
+    }
+    if (!response.body) {
+      throw new LLMError(`${this.vendor} stream response has no body`, this.vendor);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const chunk = this.parseStreamLine(line);
+          if (chunk) yield chunk;
+          if (chunk?.done) {
+            this.logger.info("llm_stream_done", {
+              vendor: this.vendor,
+              duration: Date.now() - start,
+              finishReason: chunk.finishReason
+            });
+            return;
+          }
+        }
+      }
+      if (buffer.trim()) {
+        const chunk = this.parseStreamLine(buffer);
+        if (chunk) yield chunk;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    yield { text: "", done: true };
+    this.logger.info("llm_stream_done", { vendor: this.vendor, duration: Date.now() - start });
+  }
+  async executeRequest(url, init) {
+    const start = Date.now();
+    this.logger.info("llm_request_start", {
+      vendor: this.vendor,
+      model: this.model,
+      timeoutMs: this.timeoutMs
+    });
+    const response = await this.fetchWithRetry(url, init);
+    const duration = Date.now() - start;
+    if (!response.ok) {
+      const body = await safeReadText(response);
+      this.logger.error("llm_request_failed", {
+        vendor: this.vendor,
+        model: this.model,
+        status: response.status,
+        duration,
+        body: body.slice(0, 200)
+      });
+      throw new LLMError(
+        `${this.vendor} API returned ${response.status}: ${body.slice(0, 200)}`,
+        this.vendor,
+        response.status,
+        duration
+      );
+    }
+    let payload;
+    try {
+      payload = await response.json();
+    } catch {
+      this.logger.error("llm_invalid_json", { vendor: this.vendor, duration });
+      throw new LLMError(`${this.vendor} response is not valid JSON`, this.vendor, response.status, duration);
+    }
+    const result = this.parseResponse(payload);
+    this.logger.info("llm_request_done", {
+      vendor: this.vendor,
+      model: this.model,
+      duration,
+      finishReason: result.finishReason,
+      tokens: result.usage?.totalTokens,
+      hasToolCalls: Boolean(result.toolCalls?.length)
+    });
+    return result;
+  }
+  // ─── Retry logic ─────────────────────────────────────────────────────────
+  async fetchWithRetry(url, init) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const response = await this.fetchWithTimeout(url, init);
+        if (RETRYABLE_STATUS_CODES.has(response.status) && attempt < this.maxRetries) {
+          const delay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
+          this.logger.warn("llm_retrying", {
+            vendor: this.vendor,
+            attempt: attempt + 1,
+            status: response.status,
+            delayMs: delay
+          });
+          await sleep(delay);
+          continue;
+        }
+        return response;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (err instanceof LLMTimeoutError || attempt >= this.maxRetries) {
+          throw err;
+        }
+        const delay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
+        this.logger.warn("llm_retry_on_error", {
+          vendor: this.vendor,
+          attempt: attempt + 1,
+          error: lastError.message,
+          delayMs: delay
+        });
+        await sleep(delay);
+      }
+    }
+    throw lastError ?? new LLMError(`${this.vendor} request failed after retries`, this.vendor);
+  }
+  async fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new LLMTimeoutError(this.vendor, this.timeoutMs);
+      }
+      throw new LLMError(
+        `${this.vendor} network error: ${err instanceof Error ? err.message : "unknown"}`,
+        this.vendor
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  // ─── JSON parsing ────────────────────────────────────────────────────────
+  parseAndValidate(content, schema) {
+    const jsonStr = extractJsonObject(content);
+    let parsed;
+    try {
+      parsed = JSON.parse(jsonStr);
+    } catch {
+      this.logger.error("llm_invalid_output_json", {
+        vendor: this.vendor,
+        snippet: content.slice(0, 100)
+      });
+      throw new LLMError(`${this.vendor} output is not valid JSON: ${content.slice(0, 100)}`, this.vendor);
+    }
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+      const issues = result.error.issues.slice(0, 3).map((i) => `${i.path.join(".")}: ${i.message}`);
+      this.logger.error("llm_schema_validation_failed", {
+        vendor: this.vendor,
+        issues
+      });
+      throw new LLMError(`${this.vendor} output failed schema validation: ${issues.join("; ")}`, this.vendor);
+    }
+    return result.data;
+  }
+};
+function extractJsonObject(raw) {
+  const stripped = stripMarkdownFence(raw.trim());
+  const first = stripped.indexOf("{");
+  const last = stripped.lastIndexOf("}");
+  if (first === -1 || last === -1 || last < first) return stripped;
+  return stripped.slice(first, last + 1);
+}
+function stripMarkdownFence(raw) {
+  if (!raw.startsWith("```")) return raw;
+  const match = raw.match(/^```(?:json|JSON)?\s*\n?([\s\S]*?)\n?```$/);
+  return match?.[1]?.trim() ?? raw;
+}
+async function safeReadText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/openai-provider.ts
+var DEFAULT_TEMPERATURE = 0.7;
+var OpenAIProvider = class extends BaseLLMProvider {
+  constructor(config) {
+    super({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
+      model: config.model,
+      timeoutMs: config.timeoutMs,
+      vendor: config.vendor ?? "openai",
+      logger: config.logger,
+      maxRetries: config.maxRetries
+    });
+  }
+  getDefaultBaseUrl() {
+    return "https://api.openai.com/v1";
+  }
+  getDefaultModel() {
+    return "gpt-4o-mini";
+  }
+  getVendorName() {
+    return "openai";
+  }
+  buildRequest(prompt, options) {
+    const messages = [
+      { role: "system", content: prompt.system },
+      { role: "user", content: prompt.user }
+    ];
+    return this.buildChatRequest(messages, options);
+  }
+  buildMessagesRequest(messages, options) {
+    const formatted = messages.map((m) => {
+      const msg = { role: m.role, content: m.content };
+      if (m.name) msg.name = m.name;
+      if (m.tool_call_id) msg.tool_call_id = m.tool_call_id;
+      return msg;
+    });
+    return this.buildChatRequest(formatted, options);
+  }
+  buildChatRequest(messages, options) {
+    const url = `${this.baseUrl}/chat/completions`;
+    const body = {
+      model: this.model,
+      messages,
+      temperature: options?.temperature ?? DEFAULT_TEMPERATURE
+    };
+    if (options?.maxTokens) {
+      body.max_tokens = options.maxTokens;
+    }
+    if (options?.jsonMode) {
+      body.response_format = { type: "json_object" };
+    }
+    if (options?.tools && options.tools.length > 0) {
+      body.tools = options.tools.map((t) => ({
+        type: "function",
+        function: {
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters
+        }
+      }));
+    }
+    if (options?.stream) {
+      body.stream = true;
+    }
+    return {
+      url,
+      init: {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(body)
+      }
+    };
+  }
+  parseResponse(payload) {
+    const data = payload;
+    const choice = data.choices?.[0];
+    const content = choice?.message?.content ?? "";
+    const finishReason = choice?.finish_reason;
+    let toolCalls;
+    if (choice?.message?.tool_calls && choice.message.tool_calls.length > 0) {
+      toolCalls = choice.message.tool_calls.map((tc) => ({
+        id: tc.id,
+        name: tc.function.name,
+        arguments: tc.function.arguments
+      }));
+    }
+    return {
+      content,
+      toolCalls,
+      finishReason,
+      usage: data.usage ? {
+        promptTokens: data.usage.prompt_tokens,
+        completionTokens: data.usage.completion_tokens,
+        totalTokens: data.usage.total_tokens
+      } : void 0
+    };
+  }
+  parseStreamLine(line) {
+    if (!line.startsWith("data: ")) return null;
+    const data = line.slice(6).trim();
+    if (data === "[DONE]") return { text: "", done: true };
+    try {
+      const json = JSON.parse(data);
+      const choice = json.choices?.[0];
+      if (!choice) return null;
+      const delta = choice.delta;
+      const text = delta?.content ?? "";
+      const finishReason = choice.finish_reason ?? void 0;
+      const done = finishReason === "stop" || finishReason === "tool_calls";
+      let toolCall;
+      if (delta?.tool_calls?.[0]) {
+        const tc = delta.tool_calls[0];
+        toolCall = {
+          id: tc.id,
+          name: tc.function?.name,
+          argumentsDelta: tc.function?.arguments ?? ""
+        };
+      }
+      return {
+        text,
+        toolCall,
+        done,
+        finishReason: done ? finishReason : void 0,
+        usage: json.usage ? {
+          promptTokens: json.usage.prompt_tokens,
+          completionTokens: json.usage.completion_tokens,
+          totalTokens: json.usage.total_tokens
+        } : void 0
+      };
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/anthropic-provider.ts
+var DEFAULT_MAX_TOKENS = 4096;
+var AnthropicProvider = class extends BaseLLMProvider {
+  constructor(config) {
+    super({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
+      model: config.model,
+      timeoutMs: config.timeoutMs,
+      vendor: config.vendor ?? "anthropic",
+      logger: config.logger,
+      maxRetries: config.maxRetries
+    });
+  }
+  getDefaultBaseUrl() {
+    return "https://api.anthropic.com";
+  }
+  getDefaultModel() {
+    return "claude-sonnet-4-20250514";
+  }
+  getVendorName() {
+    return "anthropic";
+  }
+  buildRequest(prompt, options) {
+    const messages = [{ role: "user", content: prompt.user }];
+    return this.buildAnthropicRequest(prompt.system, messages, options);
+  }
+  buildMessagesRequest(messages, options) {
+    const system = messages.find((m) => m.role === "system")?.content ?? "";
+    const nonSystem = messages.filter((m) => m.role !== "system").map((m) => {
+      const msg = { role: m.role, content: m.content };
+      if (m.name) msg.name = m.name;
+      if (m.tool_call_id) msg.tool_call_id = m.tool_call_id;
+      return msg;
+    });
+    return this.buildAnthropicRequest(system, nonSystem, options);
+  }
+  buildAnthropicRequest(system, messages, options) {
+    const url = `${this.baseUrl}/v1/messages`;
+    const body = {
+      model: this.model,
+      max_tokens: options?.maxTokens ?? DEFAULT_MAX_TOKENS,
+      system,
+      messages
+    };
+    if (options?.temperature !== void 0) {
+      body.temperature = options.temperature;
+    }
+    if (options?.tools && options.tools.length > 0) {
+      body.tools = options.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.parameters
+      }));
+    }
+    if (options?.stream) {
+      body.stream = true;
+    }
+    return {
+      url,
+      init: {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey,
+          "anthropic-version": "2023-06-01"
+        },
+        body: JSON.stringify(body)
+      }
+    };
+  }
+  parseResponse(payload) {
+    const data = payload;
+    const textBlocks = data.content?.filter((b) => b.type === "text") ?? [];
+    const content = textBlocks.map((b) => b.text ?? "").join("");
+    let toolCalls;
+    const toolBlocks = data.content?.filter((b) => b.type === "tool_use") ?? [];
+    if (toolBlocks.length > 0) {
+      toolCalls = toolBlocks.map((b) => ({
+        id: b.id ?? "",
+        name: b.name ?? "",
+        arguments: JSON.stringify(b.input ?? {})
+      }));
+    }
+    return {
+      content,
+      toolCalls,
+      finishReason: data.stop_reason,
+      usage: data.usage ? {
+        promptTokens: data.usage.input_tokens,
+        completionTokens: data.usage.output_tokens,
+        totalTokens: (data.usage.input_tokens ?? 0) + (data.usage.output_tokens ?? 0)
+      } : void 0
+    };
+  }
+  parseStreamLine(line) {
+    if (!line.startsWith("data: ")) return null;
+    const data = line.slice(6).trim();
+    if (!data) return null;
+    try {
+      const json = JSON.parse(data);
+      switch (json.type) {
+        case "content_block_delta": {
+          const delta = json.delta;
+          if (delta?.type === "text_delta") {
+            return { text: delta.text ?? "", done: false };
+          }
+          if (delta?.type === "input_json_delta") {
+            return { text: "", toolCall: { argumentsDelta: delta.partial_json ?? "" }, done: false };
+          }
+          return null;
+        }
+        case "content_block_start": {
+          if (json.content_block?.type === "tool_use") {
+            return {
+              text: "",
+              toolCall: { id: json.content_block.id, name: json.content_block.name, argumentsDelta: "" },
+              done: false
+            };
+          }
+          return null;
+        }
+        case "message_delta": {
+          return {
+            text: "",
+            done: json.delta?.stop_reason === "end_turn" || json.delta?.stop_reason === "tool_use",
+            finishReason: json.delta?.stop_reason ?? void 0,
+            usage: json.usage ? {
+              promptTokens: json.usage.input_tokens,
+              completionTokens: json.usage.output_tokens,
+              totalTokens: (json.usage.input_tokens ?? 0) + (json.usage.output_tokens ?? 0)
+            } : void 0
+          };
+        }
+        case "message_stop":
+          return { text: "", done: true };
+        default:
+          return null;
+      }
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/tool-executor.ts
+var DEFAULT_MAX_ROUNDS = 5;
+var ToolExecutor = class {
+  constructor(options) {
+    this.tools = /* @__PURE__ */ new Map();
+    this.logger = options?.logger ?? noopLogger;
+  }
+  register(tools) {
+    for (const tool of tools) {
+      this.tools.set(tool.definition.name, tool);
+      this.logger.info("tool_registered", { name: tool.definition.name });
+    }
+  }
+  async completeWithTools(provider, prompt, schema, options) {
+    const maxRounds = options?.maxRounds ?? DEFAULT_MAX_ROUNDS;
+    const toolDefs = Array.from(this.tools.values()).map((t) => t.definition);
+    const messages = [
+      { role: "system", content: prompt.system },
+      { role: "user", content: prompt.user }
+    ];
+    let round = 0;
+    while (round <= maxRounds) {
+      round++;
+      this.logger.info("tool_round_start", { round, messageCount: messages.length });
+      const result = await this.callWithMessages(provider, messages, toolDefs);
+      if (!result.toolCalls || result.toolCalls.length === 0) {
+        this.logger.info("tool_round_final", { round, contentLength: result.content.length });
+        return this.validateOutput(result.content, schema);
+      }
+      this.logger.info("tool_calls_requested", {
+        round,
+        toolCount: result.toolCalls.length,
+        tools: result.toolCalls.map((tc) => tc.name)
+      });
+      messages.push({
+        role: "assistant",
+        content: result.content || "",
+        toolCalls: result.toolCalls
+      });
+      for (const call of result.toolCalls) {
+        const output = await this.executeTool(call);
+        messages.push({
+          role: "tool",
+          content: output,
+          toolCallId: call.id,
+          name: call.name
+        });
+      }
+    }
+    throw new LLMError(
+      `Tool call loop exceeded ${maxRounds} rounds without final response`,
+      "tool-executor"
+    );
+  }
+  // ─── Private methods ─────────────────────────────────────────────────────
+  async executeTool(call) {
+    const registration = this.tools.get(call.name);
+    if (!registration) {
+      this.logger.warn("tool_not_found", { name: call.name });
+      return JSON.stringify({ error: `Unknown tool: ${call.name}` });
+    }
+    try {
+      const args = JSON.parse(call.arguments);
+      this.logger.info("tool_executing", { name: call.name, callId: call.id });
+      const output = await registration.handler(args);
+      this.logger.info("tool_executed", { name: call.name, outputLength: output.length });
+      return output;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : "Tool execution failed";
+      this.logger.error("tool_execution_error", { name: call.name, error: msg });
+      return JSON.stringify({ error: msg });
+    }
+  }
+  /**
+   * Call LLM with native multi-turn messages API.
+   */
+  async callWithMessages(provider, messages, tools) {
+    const llmMessages = messages.map((m) => ({
+      role: m.role,
+      content: m.content,
+      name: m.name,
+      tool_call_id: m.toolCallId
+    }));
+    return provider.messages(llmMessages, { jsonMode: true, tools });
+  }
+  validateOutput(content, schema) {
+    if (!content) {
+      throw new LLMError("LLM returned empty content after tool calls", "tool-executor");
+    }
+    const jsonStr = extractJson(content);
+    let parsed;
+    try {
+      parsed = JSON.parse(jsonStr);
+    } catch {
+      throw new LLMError(`Final output is not valid JSON: ${content.slice(0, 100)}`, "tool-executor");
+    }
+    const validated = schema.safeParse(parsed);
+    if (!validated.success) {
+      const issue = validated.error.issues[0];
+      throw new LLMError(
+        `Final output failed schema validation: ${issue?.path.join(".")}: ${issue?.message}`,
+        "tool-executor"
+      );
+    }
+    return validated.data;
+  }
+};
+function extractJson(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("```")) {
+    const match = trimmed.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/);
+    if (match?.[1]) return match[1].trim();
+  }
+  const first = trimmed.indexOf("{");
+  const last = trimmed.lastIndexOf("}");
+  if (first !== -1 && last > first) return trimmed.slice(first, last + 1);
+  return trimmed;
+}
+
+// src/mcp-client.ts
+var MCPClient = class {
+  constructor() {
+    this.servers = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Connect to an MCP server and discover its tools.
+   * Returns the number of tools discovered.
+   */
+  async connect(config) {
+    const serverName = config.name ?? new URL(config.url).hostname;
+    const tools = await this.discoverTools(config);
+    this.servers.set(serverName, { config, tools });
+    return tools.length;
+  }
+  /** Disconnect from a server */
+  disconnect(name) {
+    this.servers.delete(name);
+  }
+  /** Refresh tool list from a connected server (re-discovery) */
+  async refresh(name) {
+    const state = this.servers.get(name);
+    if (!state) {
+      throw new LLMError(`MCP server '${name}' is not connected`, "mcp");
+    }
+    const tools = await this.discoverTools(state.config);
+    this.servers.set(name, { config: state.config, tools });
+    return tools.length;
+  }
+  /** Health check: ping a connected server */
+  async healthCheck(name) {
+    const state = this.servers.get(name);
+    if (!state) return false;
+    try {
+      await this.rpcCall(state.config, "ping", {});
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /** Get all connected server names */
+  getServerNames() {
+    return Array.from(this.servers.keys());
+  }
+  /** Get all tool definitions from all connected servers */
+  getAllTools() {
+    const tools = [];
+    for (const state of this.servers.values()) {
+      for (const tool of state.tools) {
+        tools.push({
+          name: tool.name,
+          description: tool.description ?? "",
+          parameters: tool.inputSchema ?? { type: "object", properties: {} }
+        });
+      }
+    }
+    return tools;
+  }
+  /**
+   * Get tool registrations ready for ToolExecutor.register().
+   * Each tool's handler calls the MCP server via HTTP.
+   */
+  getToolRegistrations() {
+    const registrations = [];
+    for (const state of this.servers.values()) {
+      for (const tool of state.tools) {
+        const definition = {
+          name: tool.name,
+          description: tool.description ?? "",
+          parameters: tool.inputSchema ?? { type: "object", properties: {} }
+        };
+        const handler = async (args) => {
+          return this.callTool(state.config, tool.name, args);
+        };
+        registrations.push({ definition, handler });
+      }
+    }
+    return registrations;
+  }
+  // ─── Private methods ─────────────────────────────────────────────────────
+  /** Discover tools from MCP server */
+  async discoverTools(config) {
+    const response = await this.rpcCall(config, "tools/list", {});
+    const data = response;
+    return data.tools ?? [];
+  }
+  /** Call a tool on the MCP server */
+  async callTool(config, toolName, args) {
+    const response = await this.rpcCall(config, "tools/call", {
+      name: toolName,
+      arguments: args
+    });
+    const result = response;
+    if (result.isError) {
+      const errorText = result.content?.find((c) => c.type === "text")?.text ?? "Tool call failed";
+      throw new LLMError(`MCP tool '${toolName}' returned error: ${errorText}`, "mcp");
+    }
+    const textParts = result.content?.filter((c) => c.type === "text").map((c) => c.text ?? "") ?? [];
+    return textParts.join("\n") || JSON.stringify(result);
+  }
+  /** Send JSON-RPC request to MCP server */
+  async rpcCall(config, method, params) {
+    const timeout = config.timeoutMs ?? 15e3;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (config.authToken) {
+      headers["Authorization"] = `Bearer ${config.authToken}`;
+    }
+    const body = JSON.stringify({
+      jsonrpc: "2.0",
+      id: crypto.randomUUID(),
+      method,
+      params
+    });
+    try {
+      const response = await fetch(config.url, {
+        method: "POST",
+        headers,
+        body,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new LLMError(
+          `MCP server '${config.name ?? config.url}' returned ${response.status}: ${text.slice(0, 200)}`,
+          "mcp",
+          response.status
+        );
+      }
+      const json = await response.json();
+      if (json.error) {
+        throw new LLMError(`MCP RPC error: ${json.error.message}`, "mcp");
+      }
+      return json.result;
+    } catch (err) {
+      if (err instanceof LLMError) throw err;
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new LLMError(`MCP server '${config.name ?? config.url}' timed out after ${timeout}ms`, "mcp");
+      }
+      throw new LLMError(
+        `MCP connection failed: ${err instanceof Error ? err.message : "unknown"}`,
+        "mcp"
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+
+// src/skill-loader.ts
+var SkillLoader = class {
+  constructor() {
+    this.skills = /* @__PURE__ */ new Map();
+  }
+  /** Add a skill from raw SKILL.md content */
+  add(id, rawContent) {
+    const { name, description, body } = parseFrontmatter(rawContent);
+    this.skills.set(id, { id, name: name || id, description: description || "", body });
+    return this;
+  }
+  /** Add a skill from pre-parsed entry */
+  addEntry(entry) {
+    this.skills.set(entry.id, entry);
+    return this;
+  }
+  /** Remove a skill by id */
+  remove(id) {
+    this.skills.delete(id);
+    return this;
+  }
+  /** Check if a skill is loaded */
+  has(id) {
+    return this.skills.has(id);
+  }
+  /** Get loaded skill ids */
+  ids() {
+    return Array.from(this.skills.keys());
+  }
+  /** Clear all loaded skills */
+  clear() {
+    this.skills.clear();
+    return this;
+  }
+  /**
+   * Assemble all loaded skills into a system prompt string.
+   *
+   * Format:
+   * ```
+   * {preamble}
+   *
+   * === SKILL: {name} ===
+   * {body}
+   *
+   * === SKILL: {name2} ===
+   * {body2}
+   *
+   * {postamble}
+   * ```
+   */
+  toSystemPrompt(options) {
+    const parts = [];
+    if (options?.preamble) {
+      parts.push(options.preamble);
+    }
+    for (const skill of this.skills.values()) {
+      const section = `
+=== SKILL: ${skill.name} ===
+${skill.body}`;
+      parts.push(section);
+    }
+    if (options?.postamble) {
+      parts.push(`
+${options.postamble}`);
+    }
+    let result = parts.join("\n");
+    if (options?.maxChars && result.length > options.maxChars) {
+      result = result.slice(0, options.maxChars) + "\n\n[... truncated due to length limit]";
+    }
+    return result;
+  }
+  /**
+   * Build a complete LLMPrompt with skills as system context.
+   *
+   * Convenience method that combines skill system prompt with user message.
+   */
+  buildPrompt(userMessage, options) {
+    return {
+      system: this.toSystemPrompt(options),
+      user: userMessage
+    };
+  }
+};
+function parseFrontmatter(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("---")) {
+    return { name: "", description: "", body: trimmed };
+  }
+  const endIndex = trimmed.indexOf("---", 3);
+  if (endIndex === -1) {
+    return { name: "", description: "", body: trimmed };
+  }
+  const yamlBlock = trimmed.slice(3, endIndex).trim();
+  const body = trimmed.slice(endIndex + 3).trim();
+  let name = "";
+  let description = "";
+  for (const line of yamlBlock.split("\n")) {
+    const nameMatch = line.match(/^name:\s*(.+)/);
+    if (nameMatch && nameMatch[1]) {
+      name = nameMatch[1].trim().replace(/^['"]|['"]$/g, "");
+      continue;
+    }
+    const descMatch = line.match(/^description:\s*(.+)/);
+    if (descMatch && descMatch[1]) {
+      description = descMatch[1].trim().replace(/^['"]|['"]$/g, "");
+      continue;
+    }
+    if (line.match(/^description:\s*[|>]/)) {
+      const descLines = [];
+      const allLines = yamlBlock.split("\n");
+      const startIdx = allLines.indexOf(line);
+      for (let i = startIdx + 1; i < allLines.length; i++) {
+        const currentLine = allLines[i];
+        if (currentLine && (currentLine.startsWith("  ") || currentLine.startsWith("	"))) {
+          descLines.push(currentLine.trim());
+        } else {
+          break;
+        }
+      }
+      description = descLines.join(" ");
+    }
+  }
+  return { name, description, body };
+}
+
+// src/index.ts
+function createProvider(options) {
+  const { provider = "openai", ...config } = options;
+  switch (provider) {
+    case "anthropic":
+      return new AnthropicProvider(config);
+    case "openai":
+    default:
+      return new OpenAIProvider(config);
+  }
+}
+export {
+  AnthropicProvider,
+  LLMError,
+  LLMSchemaError,
+  LLMTimeoutError,
+  MCPClient,
+  OpenAIProvider,
+  SkillLoader,
+  ToolExecutor,
+  consoleLogger,
+  createProvider,
+  extractJsonObject,
+  noopLogger
+};