@guidekit/core 0.1.0-beta.2 → 0.1.0-beta.3

package/README.md

@@ -63,7 +63,7 @@ All errors extend `GuideKitError` with structured metadata:
 
 - **DOM Scanner** — TreeWalker-based page model with `data-guidekit-ignore` support
 - **Context Manager** — Token budgeting and truncation for LLM context windows
-- **LLM Orchestrator** — Streaming responses with tool calling (Gemini adapter)
+- **LLM Orchestrator** — Streaming responses with tool calling (Gemini (default), custom adapters via `LLMProviderAdapter`)
 - **Resource Manager** — AbortController pattern and lifecycle tracking
 
 ## Documentation

package/dist/index.cjs

@@ -1094,7 +1094,7 @@ var DOMScanner = class {
       const style = window.getComputedStyle(el);
       const position = style.position;
       const zIndex = parseInt(style.zIndex, 10) || 0;
-      if ((position === "fixed" || position === "absolute") && !isNaN(zIndex) && zIndex >= 1e3) {
+      if ((position === "fixed" || position === "absolute") && !Number.isNaN(zIndex) && zIndex >= 1e3) {
         const visible = isElementVisible(el);
         if (!visible) return;
         const overlayType = this.classifyOverlay(el, style);
@@ -1122,10 +1122,10 @@ var DOMScanner = class {
       return "dropdown";
     const width = parseFloat(style.width);
     const height = parseFloat(style.height);
-    if (typeof window !== "undefined" && !isNaN(width) && !isNaN(height) && width > window.innerWidth * 0.5 && height > window.innerHeight * 0.5) {
+    if (typeof window !== "undefined" && !Number.isNaN(width) && !Number.isNaN(height) && width > window.innerWidth * 0.5 && height > window.innerHeight * 0.5) {
       return "modal";
     }
-    if (!isNaN(width) && width < 400) return "popover";
+    if (!Number.isNaN(width) && width < 400) return "popover";
     return null;
   }
   // -------------------------------------------------------------------------
@@ -1841,424 +1841,9 @@ function isGuideKitError(error) {
   return error instanceof GuideKitError;
 }
 
-// src/llm/openai-adapter.ts
-var DEFAULT_OPENAI_MODEL = "gpt-4o";
-var DEFAULT_TIMEOUT_MS = 15e3;
-var OPENAI_CHAT_URL = "https://api.openai.com/v1/chat/completions";
-function emptyUsage() {
-  return { prompt: 0, completion: 0, total: 0 };
-}
-var OpenAIAdapter = class {
-  apiKey;
-  model;
-  /** Tracks whether the last extractChunks call emitted a done chunk. */
-  lastExtractEmittedDone = false;
-  /**
-   * Token usage extracted from the most recent `parseResponse` call.
-   * Updated as each SSE chunk is parsed.
-   */
-  _lastUsage = emptyUsage();
-  constructor(config) {
-    this.apiKey = config.apiKey;
-    this.model = config.model ?? DEFAULT_OPENAI_MODEL;
-  }
-  /** Token usage from the most recent parseResponse call. */
-  get lastUsage() {
-    return this._lastUsage;
-  }
-  // -----------------------------------------------------------------------
-  // LLMProviderAdapter implementation
-  // -----------------------------------------------------------------------
-  /**
-   * Convert GuideKit tool definitions into OpenAI's `tools` format.
-   * Each tool is wrapped as `{ type: 'function', function: { name, description, parameters } }`.
-   */
-  formatTools(tools) {
-    if (tools.length === 0) return void 0;
-    return tools.map((tool) => ({
-      type: "function",
-      function: {
-        name: tool.name,
-        description: tool.description,
-        parameters: {
-          type: "object",
-          properties: { ...tool.parameters },
-          required: tool.required ?? []
-        }
-      }
-    }));
-  }
-  /**
-   * Convert an array of `ConversationTurn` objects into OpenAI's messages
-   * format with `role: 'user' | 'assistant'`.
-   */
-  formatConversation(history) {
-    return history.map((turn) => ({
-      role: turn.role,
-      content: turn.content
-    }));
-  }
-  /**
-   * Parse an OpenAI SSE streaming response into an async iterable of
-   * `TextChunk` and `ToolCall` objects.
-   *
-   * The OpenAI streaming endpoint sends each chunk as a JSON object
-   * prefixed by `data: `. The final line is `data: [DONE]`.
-   * Text content arrives in `choices[0].delta.content` and tool calls
-   * arrive in `choices[0].delta.tool_calls`.
-   *
-   * This method also:
-   * - Detects content filtering and throws `ContentFilterError`.
-   * - Tracks token usage (accessible via `lastUsage` after iteration).
-   */
-  async *parseResponse(stream) {
-    const reader = stream.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    let doneEmitted = false;
-    this._lastUsage = emptyUsage();
-    const pendingToolCalls = /* @__PURE__ */ new Map();
-    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 trimmed = line.trim();
-          if (!trimmed.startsWith("data:")) continue;
-          const jsonStr = trimmed.slice(5).trim();
-          if (jsonStr === "" || jsonStr === "[DONE]") {
-            if (jsonStr === "[DONE]") {
-              yield* this.flushPendingToolCalls(pendingToolCalls);
-              if (!doneEmitted) {
-                doneEmitted = true;
-                yield { text: "", done: true };
-              }
-            }
-            continue;
-          }
-          let parsed;
-          try {
-            parsed = JSON.parse(jsonStr);
-          } catch {
-            continue;
-          }
-          if (this.isContentFiltered(parsed)) {
-            throw new ContentFilterError({
-              code: ErrorCodes.CONTENT_FILTER_TRIGGERED,
-              message: "Response was blocked by provider content safety filter.",
-              provider: "openai",
-              suggestion: "Rephrase your question or adjust safety settings."
-            });
-          }
-          const chunkUsage = this.extractUsage(parsed);
-          if (chunkUsage) {
-            this._lastUsage = chunkUsage;
-          }
-          yield* this.extractChunks(parsed, pendingToolCalls, doneEmitted);
-          if (!doneEmitted && this.lastExtractEmittedDone) {
-            doneEmitted = true;
-          }
-        }
-      }
-      if (buffer.trim().startsWith("data:")) {
-        const jsonStr = buffer.trim().slice(5).trim();
-        if (jsonStr === "[DONE]") {
-          yield* this.flushPendingToolCalls(pendingToolCalls);
-          if (!doneEmitted) {
-            doneEmitted = true;
-            yield { text: "", done: true };
-          }
-        } else if (jsonStr !== "") {
-          try {
-            const parsed = JSON.parse(jsonStr);
-            if (this.isContentFiltered(parsed)) {
-              throw new ContentFilterError({
-                code: ErrorCodes.CONTENT_FILTER_TRIGGERED,
-                message: "Response was blocked by provider content safety filter.",
-                provider: "openai",
-                suggestion: "Rephrase your question or adjust safety settings."
-              });
-            }
-            const chunkUsage = this.extractUsage(parsed);
-            if (chunkUsage) {
-              this._lastUsage = chunkUsage;
-            }
-            yield* this.extractChunks(parsed, pendingToolCalls, doneEmitted);
-            if (!doneEmitted && this.lastExtractEmittedDone) {
-              doneEmitted = true;
-            }
-          } catch (error) {
-            if (error instanceof ContentFilterError) throw error;
-          }
-        }
-      }
-      yield* this.flushPendingToolCalls(pendingToolCalls);
-    } finally {
-      reader.releaseLock();
-    }
-  }
-  /**
-   * Format a tool result so it can be sent back to OpenAI as a
-   * `tool` role message with the `tool_call_id`.
-   */
-  formatToolResult(callId, result) {
-    return {
-      role: "tool",
-      tool_call_id: callId,
-      content: typeof result === "string" ? result : JSON.stringify(result)
-    };
-  }
-  // -----------------------------------------------------------------------
-  // Streaming request
-  // -----------------------------------------------------------------------
-  /**
-   * Build and execute a streaming request to the OpenAI Chat Completions API.
-   * Returns the raw `ReadableStream` for the response body together with
-   * the raw Response object.
-   */
-  async streamRequest(params) {
-    const contentsArray = params.contents;
-    const messages = [
-      { role: "system", content: params.systemPrompt },
-      ...contentsArray
-    ];
-    if (params.userMessage) {
-      messages.push({ role: "user", content: params.userMessage });
-    }
-    const body = {
-      model: this.model,
-      messages,
-      stream: true,
-      temperature: 0.7,
-      top_p: 0.95
-    };
-    if (params.tools) {
-      body.tools = params.tools;
-    }
-    const timeoutMs = params.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-    if (params.signal) {
-      params.signal.addEventListener(
-        "abort",
-        () => controller.abort(params.signal.reason),
-        { once: true }
-      );
-    }
-    let response;
-    try {
-      response = await fetch(OPENAI_CHAT_URL, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`
-        },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof DOMException && error.name === "AbortError") {
-        if (params.signal?.aborted) {
-          throw error;
-        }
-        throw new TimeoutError({
-          code: ErrorCodes.TIMEOUT_LLM_RESPONSE,
-          message: `OpenAI request timed out after ${timeoutMs}ms`,
-          provider: "openai",
-          recoverable: true,
-          suggestion: "Try again or increase the timeout.",
-          operationName: "openai.chatCompletions",
-          timeoutMs
-        });
-      }
-      throw new NetworkError({
-        code: ErrorCodes.NETWORK_CONNECTION_LOST,
-        message: `Failed to connect to OpenAI API: ${error.message}`,
-        provider: "openai",
-        suggestion: "Check your network connection and try again.",
-        cause: error instanceof Error ? error : void 0
-      });
-    }
-    clearTimeout(timeoutId);
-    if (!response.ok) {
-      await this.handleHttpError(response);
-    }
-    if (!response.body) {
-      throw new NetworkError({
-        code: ErrorCodes.NETWORK_CONNECTION_LOST,
-        message: "OpenAI response body is null -- streaming unavailable.",
-        provider: "openai",
-        suggestion: "Retry the request."
-      });
-    }
-    return { stream: response.body, response };
-  }
-  // -----------------------------------------------------------------------
-  // Internal helpers
-  // -----------------------------------------------------------------------
-  /**
-   * Extract `TextChunk` and accumulate `ToolCall` data from a single parsed
-   * OpenAI SSE JSON object.
-   *
-   * OpenAI tool calls arrive incrementally: the first chunk for a tool call
-   * carries the `id` and `function.name`, while subsequent chunks append to
-   * `function.arguments`. We accumulate these in `pendingToolCalls` and only
-   * yield complete `ToolCall` objects when the finish_reason is 'tool_calls'
-   * or when flushed.
-   */
-  *extractChunks(parsed, pendingToolCalls, doneEmitted) {
-    this.lastExtractEmittedDone = false;
-    const choices = parsed.choices;
-    if (!choices || choices.length === 0) return;
-    for (const choice of choices) {
-      const delta = choice.delta;
-      const finishReason = choice.finish_reason;
-      if (delta) {
-        if (typeof delta.content === "string" && delta.content !== "") {
-          yield {
-            text: delta.content,
-            done: false
-          };
-        }
-        const toolCallDeltas = delta.tool_calls;
-        if (toolCallDeltas) {
-          for (const tc of toolCallDeltas) {
-            const existing = pendingToolCalls.get(tc.index);
-            if (existing) {
-              if (tc.function?.arguments) {
-                existing.argumentsJson += tc.function.arguments;
-              }
-            } else {
-              pendingToolCalls.set(tc.index, {
-                id: tc.id ?? "",
-                name: tc.function?.name ?? "",
-                argumentsJson: tc.function?.arguments ?? ""
-              });
-            }
-          }
-        }
-      }
-      if (finishReason === "tool_calls") {
-        yield* this.flushPendingToolCalls(pendingToolCalls);
-      }
-      if (finishReason === "stop" && !doneEmitted && !this.lastExtractEmittedDone) {
-        this.lastExtractEmittedDone = true;
-        yield { text: "", done: true };
-      }
-    }
-  }
-  /**
-   * Flush all accumulated pending tool calls as complete `ToolCall` objects.
-   */
-  *flushPendingToolCalls(pendingToolCalls) {
-    const sorted = [...pendingToolCalls.entries()].sort(
-      ([a], [b]) => a - b
-    );
-    for (const [, tc] of sorted) {
-      let args = {};
-      try {
-        args = JSON.parse(tc.argumentsJson);
-      } catch (_e) {
-        console.warn("[GuideKit:LLM] Failed to parse tool call arguments:", tc.argumentsJson);
-      }
-      yield {
-        id: tc.id,
-        name: tc.name,
-        arguments: args
-      };
-    }
-    pendingToolCalls.clear();
-  }
-  /**
-   * Extract token usage from a parsed OpenAI response chunk.
-   * Usage data typically appears in the final chunk when `stream_options`
-   * includes `include_usage`, or in the non-streaming response.
-   * Returns `null` if no usage data is present.
-   */
-  extractUsage(parsed) {
-    const usage = parsed.usage;
-    if (!usage) return null;
-    return {
-      prompt: usage.prompt_tokens ?? 0,
-      completion: usage.completion_tokens ?? 0,
-      total: usage.total_tokens ?? 0
-    };
-  }
-  /**
-   * Check whether a parsed OpenAI chunk indicates the response was
-   * blocked by a content filter.
-   *
-   * OpenAI signals content filtering through:
-   * - `choices[].finish_reason === 'content_filter'`
-   * - `choices[].content_filter_results` with `filtered: true`
-   */
-  isContentFiltered(parsed) {
-    const choices = parsed.choices;
-    if (!choices || choices.length === 0) return false;
-    return choices.some((choice) => {
-      if (choice.finish_reason === "content_filter") return true;
-      const filterResults = choice.content_filter_results;
-      if (filterResults) {
-        return Object.values(filterResults).some((r) => r.filtered === true);
-      }
-      return false;
-    });
-  }
-  /**
-   * Translate an HTTP error response from OpenAI into the appropriate
-   * GuideKit error class.
-   */
-  async handleHttpError(response) {
-    let errorBody = "";
-    try {
-      errorBody = await response.text();
-    } catch {
-    }
-    const status = response.status;
-    if (status === 401 || status === 403) {
-      throw new AuthenticationError({
-        code: ErrorCodes.AUTH_INVALID_KEY,
-        message: `OpenAI API authentication failed (${status}): ${errorBody}`,
-        provider: "openai",
-        suggestion: "Verify your OpenAI API key is correct and has not expired."
-      });
-    }
-    if (status === 429) {
-      const retryAfterHeader = response.headers.get("retry-after");
-      const retryAfterMs = retryAfterHeader ? parseInt(retryAfterHeader, 10) * 1e3 : 6e4;
-      throw new RateLimitError({
-        code: ErrorCodes.RATE_LIMIT_PROVIDER,
-        message: `OpenAI API rate limit exceeded (429): ${errorBody}`,
-        provider: "openai",
-        recoverable: true,
-        suggestion: `Rate limited by OpenAI. Retry after ${Math.ceil(retryAfterMs / 1e3)}s.`,
-        retryAfterMs
-      });
-    }
-    if (status >= 500) {
-      throw new NetworkError({
-        code: ErrorCodes.NETWORK_CONNECTION_LOST,
-        message: `OpenAI API server error (${status}): ${errorBody}`,
-        provider: "openai",
-        suggestion: "The OpenAI API is experiencing issues. Please try again later."
-      });
-    }
-    throw new NetworkError({
-      code: ErrorCodes.NETWORK_CONNECTION_LOST,
-      message: `OpenAI API request failed (${status}): ${errorBody}`,
-      provider: "openai",
-      suggestion: "Check the request parameters and try again."
-    });
-  }
-};
-
 // src/llm/index.ts
 var DEFAULT_GEMINI_MODEL = "gemini-2.5-flash";
-var DEFAULT_TIMEOUT_MS2 = 15e3;
+var DEFAULT_TIMEOUT_MS = 15e3;
 var GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models";
 var DEFAULT_SAFETY_SETTINGS = [
   { category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_ONLY_HIGH" },
@@ -2266,7 +1851,7 @@ var DEFAULT_SAFETY_SETTINGS = [
   { category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", threshold: "BLOCK_ONLY_HIGH" },
   { category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "BLOCK_ONLY_HIGH" }
 ];
-function emptyUsage2() {
+function emptyUsage() {
   return { prompt: 0, completion: 0, total: 0 };
 }
 var GeminiAdapter = class {
@@ -2277,7 +1862,7 @@ var GeminiAdapter = class {
    * Updated as each SSE chunk is parsed; the final value reflects the
    * cumulative usage metadata sent by Gemini (typically in the last chunk).
    */
-  _lastUsage = emptyUsage2();
+  _lastUsage = emptyUsage();
   constructor(config) {
     this.apiKey = config.apiKey;
     this.model = config.model ?? DEFAULT_GEMINI_MODEL;
@@ -2335,7 +1920,7 @@ var GeminiAdapter = class {
     const reader = stream.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
-    this._lastUsage = emptyUsage2();
+    this._lastUsage = emptyUsage();
     try {
       while (true) {
         const { done, value } = await reader.read();
@@ -2444,7 +2029,7 @@ var GeminiAdapter = class {
     if (params.tools) {
       body.tools = params.tools;
     }
-    const timeoutMs = params.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+    const timeoutMs = params.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     if (params.signal) {
@@ -2719,7 +2304,7 @@ var LLMOrchestrator = class {
       }
     }
     this.callbacks.onChunk?.({ text: "", done: true });
-    let usage = emptyUsage2();
+    let usage = emptyUsage();
     if ("lastUsage" in adapter) {
       usage = adapter.lastUsage;
     }
@@ -2739,7 +2324,7 @@ var LLMOrchestrator = class {
    *
    * Custom adapters:
    * - Pass `{ adapter: myAdapter }` to use any `LLMProviderAdapter`.
-   *   Example: `llm: { adapter: new OpenAIAdapter({ ... }) }`
+   *   Example: `llm: { adapter: myCustomAdapter }`
    */
   createAdapter(config) {
     if ("adapter" in config) {
@@ -9637,7 +9222,6 @@ exports.InitializationError = InitializationError;
 exports.LLMOrchestrator = LLMOrchestrator;
 exports.NavigationController = NavigationController;
 exports.NetworkError = NetworkError;
-exports.OpenAIAdapter = OpenAIAdapter;
 exports.PermissionError = PermissionError;
 exports.ProactiveTriggerEngine = ProactiveTriggerEngine;
 exports.RateLimitError = RateLimitError;