tinker-agent 1.0.65

package/src/tools/web-fetch/browser-backend.ts

@@ -0,0 +1,126 @@
+import { extractMarkdownFromHtml } from "./local-backend";
+import type { WebFetchBackend, WebFetchBackendResult } from "./backend";
+import { cancellationError, throwIfTurnCancelled } from "../../agent/turn-cancellation";
+
+export type BrowserBackendOptions = {
+  timeoutMs?: number;
+  settleDelayMs?: number;
+  maxHtmlChars?: number;
+};
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+// Give page JavaScript time to render after the load event fires; JS-driven
+// pages are the whole reason this backend exists.
+const DEFAULT_SETTLE_DELAY_MS = 1000;
+const DEFAULT_MAX_HTML_CHARS = 5 * 1024 * 1024;
+
+export function isBrowserBackendAvailable(): boolean {
+  return typeof Bun !== "undefined" && typeof Bun.WebView === "function";
+}
+
+export function createBrowserWebFetchBackend(
+  options: BrowserBackendOptions = {},
+): WebFetchBackend {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const settleDelayMs = options.settleDelayMs ?? DEFAULT_SETTLE_DELAY_MS;
+  const maxHtmlChars = options.maxHtmlChars ?? DEFAULT_MAX_HTML_CHARS;
+
+  return {
+    route: "local-browser",
+    async fetch(input, context): Promise<WebFetchBackendResult> {
+      throwIfTurnCancelled(context.signal);
+      if (!isBrowserBackendAvailable()) {
+        return {
+          ok: false,
+          error: "Bun.WebView is not available in this Bun version.",
+        };
+      }
+
+      const view = new Bun.WebView({ width: 1280, height: 800 });
+
+      try {
+        await withTimeout(
+          view.navigate(input.url),
+          timeoutMs,
+          `Browser navigation timed out after ${timeoutMs}ms.`,
+          context.signal,
+        );
+        await withTimeout(
+          Bun.sleep(settleDelayMs),
+          timeoutMs,
+          `Browser settle delay timed out after ${timeoutMs}ms.`,
+          context.signal,
+        );
+
+        const html = await withTimeout(
+          view.evaluate<string>("document.documentElement.outerHTML"),
+          timeoutMs,
+          `Reading the rendered page timed out after ${timeoutMs}ms.`,
+          context.signal,
+        );
+
+        if (typeof html !== "string" || html.trim() === "") {
+          return { ok: false, error: "The browser returned an empty document." };
+        }
+
+        if (html.length > maxHtmlChars) {
+          return {
+            ok: false,
+            error: `The rendered page exceeds the ${maxHtmlChars} character limit.`,
+          };
+        }
+
+        const extracted = extractMarkdownFromHtml(html);
+
+        return {
+          ok: true,
+          finalUrl: view.url || input.url,
+          title: extracted.title ?? (view.title || undefined),
+          markdown: extracted.markdown,
+        };
+      } catch (error) {
+        if (context.signal.aborted) {
+          throw cancellationError(context.signal, error);
+        }
+
+        return {
+          ok: false,
+          error: `Browser rendering failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      } finally {
+        view.close();
+      }
+    },
+  };
+}
+
+async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  message: string,
+  signal: AbortSignal,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+  });
+  const cancellation = new Promise<never>((_, reject) => {
+    onAbort = () => reject(cancellationError(signal));
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+
+  try {
+    return await Promise.race([promise, timeout, cancellation]);
+  } finally {
+    clearTimeout(timer);
+    if (onAbort !== undefined) {
+      signal.removeEventListener("abort", onAbort);
+    }
+  }
+}

package/src/tools/web-fetch/exa-backend.ts

@@ -0,0 +1,172 @@
+import type { WebFetchBackend, WebFetchBackendResult } from "./backend";
+import { cancellationError, throwIfTurnCancelled } from "../../agent/turn-cancellation";
+
+export type ExaBackendOptions = {
+  apiKey: string;
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+};
+
+const DEFAULT_BASE_URL = "https://api.exa.ai";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const TEXT_MAX_CHARACTERS = 20_000;
+const LIVECRAWL_TIMEOUT_MS = 10_000;
+
+export function createExaWebFetchBackend(options: ExaBackendOptions): WebFetchBackend {
+  if (options.apiKey.trim() === "") {
+    throw new Error("Exa WebFetch backend requires a non-empty API key.");
+  }
+
+  const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  return {
+    route: "exa",
+    async fetch(input, context): Promise<WebFetchBackendResult> {
+      throwIfTurnCancelled(context.signal);
+      let response: Response;
+
+      try {
+        const requestSignal = AbortSignal.any([
+          context.signal,
+          AbortSignal.timeout(timeoutMs),
+        ]);
+        response = await fetchImpl(`${baseUrl}/contents`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-api-key": options.apiKey,
+          },
+          body: JSON.stringify({
+            urls: [input.url],
+            text: { maxCharacters: TEXT_MAX_CHARACTERS },
+            summary: { query: input.prompt },
+            highlights: { query: input.prompt },
+            livecrawlTimeout: LIVECRAWL_TIMEOUT_MS,
+          }),
+          signal: requestSignal,
+        });
+      } catch (error) {
+        if (context.signal.aborted) {
+          throw cancellationError(context.signal, error);
+        }
+
+        return { ok: false, error: requestErrorMessage(error, timeoutMs) };
+      }
+
+      let responseText: string;
+      try {
+        responseText = await response.text();
+      } catch (error) {
+        if (context.signal.aborted) {
+          throw cancellationError(context.signal, error);
+        }
+
+        return { ok: false, error: requestErrorMessage(error, timeoutMs) };
+      }
+
+      throwIfTurnCancelled(context.signal);
+
+      if (!response.ok) {
+        return {
+          ok: false,
+          httpStatusCode: response.status,
+          error: `Exa /contents returned HTTP ${response.status}: ${extractApiError(responseText)}`,
+        };
+      }
+
+      let payload: unknown;
+      try {
+        payload = JSON.parse(responseText);
+      } catch {
+        return { ok: false, error: "Exa /contents returned a non-JSON response body." };
+      }
+
+      if (!isRecord(payload)) {
+        return { ok: false, error: "Exa /contents returned an unexpected response." };
+      }
+
+      const status = Array.isArray(payload.statuses)
+        ? asRecord(payload.statuses[0])
+        : undefined;
+      const statusError = asRecord(status?.error);
+
+      if (status?.status === "error") {
+        const tag =
+          typeof statusError?.tag === "string" ? statusError.tag : "CRAWL_FAILED";
+        const httpStatusCode =
+          typeof statusError?.httpStatusCode === "number"
+            ? statusError.httpStatusCode
+            : undefined;
+
+        return {
+          ok: false,
+          errorTag: tag,
+          httpStatusCode,
+          error: `Exa could not fetch the page: ${tag}${httpStatusCode === undefined ? "" : ` (HTTP ${httpStatusCode})`}.`,
+        };
+      }
+
+      const result = Array.isArray(payload.results)
+        ? asRecord(payload.results[0])
+        : undefined;
+
+      if (result === undefined) {
+        return { ok: false, error: "Exa /contents response contains no results." };
+      }
+
+      return {
+        ok: true,
+        finalUrl: typeof result.url === "string" ? result.url : undefined,
+        title: typeof result.title === "string" ? result.title : undefined,
+        publishedDate:
+          typeof result.publishedDate === "string" ? result.publishedDate : undefined,
+        markdown: typeof result.text === "string" ? result.text : undefined,
+        refined: typeof result.summary === "string" ? result.summary : undefined,
+        highlights: Array.isArray(result.highlights)
+          ? result.highlights.filter(
+              (entry): entry is string => typeof entry === "string",
+            )
+          : undefined,
+        source: status?.source === "cached" ? "cached" : "crawled",
+        costDollars: extractTotalCost(payload.costDollars),
+      };
+    },
+  };
+}
+
+function extractTotalCost(value: unknown): number | undefined {
+  const record = asRecord(value);
+  return typeof record?.total === "number" ? record.total : undefined;
+}
+
+function extractApiError(responseText: string): string {
+  try {
+    const payload: unknown = JSON.parse(responseText);
+    if (isRecord(payload) && typeof payload.error === "string") {
+      return payload.error;
+    }
+  } catch {
+    // Fall through to the raw body.
+  }
+
+  return responseText === "" ? "(empty response body)" : responseText;
+}
+
+function requestErrorMessage(error: unknown, timeoutMs: number): string {
+  if (error instanceof Error && error.name === "TimeoutError") {
+    return `Exa /contents request timed out after ${timeoutMs}ms.`;
+  }
+
+  return `Exa /contents request failed: ${error instanceof Error ? error.message : String(error)}`;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return isRecord(value) ? value : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tools/web-fetch/index.ts

@@ -0,0 +1,298 @@
+import { cancellationError, throwIfTurnCancelled } from "../../agent/turn-cancellation";
+import { defineToolExecutor } from "../types";
+import type { ToolExecutionContext, ToolExecutor, WebFetchRawResult } from "../types";
+import type { WebFetchBackend, WebFetchBackendResult, WebFetchRoute } from "./backend";
+import {
+  createBrowserWebFetchBackend,
+  isBrowserBackendAvailable,
+} from "./browser-backend";
+import { createExaWebFetchBackend } from "./exa-backend";
+import { createLocalWebFetchBackend } from "./local-backend";
+import type { Refiner } from "./refiner";
+import { decideRoute, isPrivateHost, shouldEscalateToBrowser } from "./route";
+
+type WebFetchArgs = {
+  url: string;
+  prompt: string;
+};
+
+export type WebFetchToolOptions = {
+  exaApiKey?: string;
+  refiner?: Refiner;
+  fetchImpl?: typeof fetch;
+  refineThreshold?: number;
+  cacheTtlMs?: number;
+  browserBackend?: WebFetchBackend | false;
+};
+
+export const WEB_FETCH_DEFAULT_REFINE_THRESHOLD = 2000;
+export const WEB_FETCH_DEFAULT_CACHE_TTL_MS = 15 * 60 * 1000;
+
+type CacheEntry = {
+  expiresAt: number;
+  result: WebFetchRawResult;
+};
+
+export function createWebFetchToolExecutor(
+  options: WebFetchToolOptions = {},
+): ToolExecutor {
+  const localBackend = createLocalWebFetchBackend({ fetchImpl: options.fetchImpl });
+  const exaBackend: WebFetchBackend | undefined =
+    options.exaApiKey !== undefined && options.exaApiKey.trim() !== ""
+      ? createExaWebFetchBackend({
+          apiKey: options.exaApiKey,
+          fetchImpl: options.fetchImpl,
+        })
+      : undefined;
+  const browserBackend: WebFetchBackend | undefined =
+    options.browserBackend === false
+      ? undefined
+      : (options.browserBackend ??
+        (isBrowserBackendAvailable() ? createBrowserWebFetchBackend() : undefined));
+  const refineThreshold =
+    options.refineThreshold ??
+    parsePositiveInteger(
+      process.env.TINKER_WEBFETCH_REFINE_THRESHOLD,
+      WEB_FETCH_DEFAULT_REFINE_THRESHOLD,
+    );
+  const cacheTtlMs = options.cacheTtlMs ?? WEB_FETCH_DEFAULT_CACHE_TTL_MS;
+  const cache = new Map<string, CacheEntry>();
+
+  return defineToolExecutor("web_fetch", {
+    definition: {
+      name: "WebFetch",
+      description: [
+        "Fetch content from a URL and process it according to the prompt.",
+        "- Small pages are returned as markdown; large pages are condensed into an answer to the prompt",
+        "- Supports public web pages as well as localhost and private-network URLs",
+        "- HTTP URLs on the public web are upgraded to HTTPS",
+        "- If the page redirects to a different host, the redirect URL is returned; call WebFetch again with that URL",
+        "- Use it to read documentation, pages found via WebSearch, or local dev server responses",
+      ].join("\n"),
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          url: {
+            type: "string",
+            format: "uri",
+            description: "The URL to fetch content from",
+          },
+          prompt: {
+            type: "string",
+            minLength: 1,
+            description: "The prompt to run on the fetched content",
+          },
+        },
+        required: ["url", "prompt"],
+      },
+    },
+    async execute(
+      args,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<WebFetchRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseWebFetchArgs(args);
+
+      if (!parsed.ok) {
+        return { ok: false, url: "", error: parsed.error };
+      }
+
+      const input = parsed.value;
+      const url = normalizeUrl(input.url);
+      const cacheKey = `${url.toString()}\n${input.prompt}`;
+      pruneCache(cache);
+
+      const cached = cache.get(cacheKey);
+      if (cached !== undefined) {
+        return { ...cached.result, cacheHit: true };
+      }
+
+      throwIfTurnCancelled(context.signal);
+
+      let route = decideRoute(url, {
+        hasExaBackend: exaBackend !== undefined,
+        hasBrowserBackend: browserBackend !== undefined,
+      });
+      const backends: Record<WebFetchRoute, WebFetchBackend | undefined> = {
+        local: localBackend,
+        exa: exaBackend,
+        "local-browser": browserBackend,
+      };
+
+      const startedAt = Date.now();
+      let backendResult: WebFetchBackendResult = await (
+        backends[route] ?? localBackend
+      ).fetch(
+        {
+          url: url.toString(),
+          prompt: input.prompt,
+        },
+        context,
+      );
+
+      throwIfTurnCancelled(context.signal);
+
+      if (
+        route === "local" &&
+        browserBackend !== undefined &&
+        shouldEscalateToBrowser(backendResult)
+      ) {
+        const browserResult = await browserBackend.fetch(
+          {
+            url: url.toString(),
+            prompt: input.prompt,
+          },
+          context,
+        );
+        throwIfTurnCancelled(context.signal);
+        if (browserResult.ok && (browserResult.markdown ?? "").trim() !== "") {
+          backendResult = browserResult;
+          route = "local-browser";
+        }
+      }
+
+      const durationMs = Date.now() - startedAt;
+
+      const base: WebFetchRawResult = {
+        ok: false,
+        url: url.toString(),
+        route,
+        durationMs,
+        finalUrl: backendResult.finalUrl,
+        title: backendResult.title,
+        publishedDate: backendResult.publishedDate,
+        source: backendResult.source,
+        costDollars: backendResult.costDollars,
+        errorTag: backendResult.errorTag,
+        httpStatusCode: backendResult.httpStatusCode,
+      };
+
+      if (!backendResult.ok) {
+        return { ...base, error: backendResult.error ?? "Unknown error." };
+      }
+
+      if (backendResult.redirectUrl !== undefined) {
+        return { ...base, ok: true, redirectUrl: backendResult.redirectUrl };
+      }
+
+      const markdown = backendResult.markdown ?? "";
+      if (markdown.trim() === "") {
+        return { ...base, error: "The page returned no readable content." };
+      }
+
+      let result: WebFetchRawResult;
+
+      if (markdown.length <= refineThreshold) {
+        result = { ...base, ok: true, refined: false, content: markdown };
+      } else if (backendResult.refined !== undefined) {
+        result = {
+          ...base,
+          ok: true,
+          refined: true,
+          content: backendResult.refined,
+          highlights: backendResult.highlights,
+        };
+      } else if (options.refiner === undefined) {
+        return {
+          ...base,
+          error: `The page content is ${markdown.length} characters and no refiner is configured to condense it.`,
+        };
+      } else {
+        try {
+          const refined = await options.refiner.refine(
+            {
+              url: url.toString(),
+              prompt: input.prompt,
+              content: markdown,
+            },
+            context,
+          );
+          result = { ...base, ok: true, refined: true, content: refined };
+        } catch (error) {
+          if (context.signal.aborted) {
+            throw cancellationError(context.signal, error);
+          }
+
+          return {
+            ...base,
+            error: `Failed to refine the page content: ${error instanceof Error ? error.message : String(error)}`,
+          };
+        }
+      }
+
+      throwIfTurnCancelled(context.signal);
+      result.durationMs = Date.now() - startedAt;
+      cache.set(cacheKey, { expiresAt: Date.now() + cacheTtlMs, result });
+      return result;
+    },
+  });
+}
+
+function parseWebFetchArgs(
+  args: unknown,
+): { ok: true; value: WebFetchArgs } | { ok: false; error: string } {
+  if (!isRecord(args)) {
+    return { ok: false, error: "WebFetch arguments must be an object." };
+  }
+
+  if (typeof args.url !== "string" || args.url.trim() === "") {
+    return { ok: false, error: "WebFetch.url must be a non-empty string." };
+  }
+
+  let url: URL;
+  try {
+    url = new URL(args.url.trim());
+  } catch {
+    return { ok: false, error: `WebFetch.url is not a valid URL: ${args.url}` };
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return {
+      ok: false,
+      error: `WebFetch.url must use http or https, received ${url.protocol.replace(":", "")}.`,
+    };
+  }
+
+  if (typeof args.prompt !== "string" || args.prompt.trim() === "") {
+    return { ok: false, error: "WebFetch.prompt must be a non-empty string." };
+  }
+
+  return {
+    ok: true,
+    value: { url: url.toString(), prompt: args.prompt.trim() },
+  };
+}
+
+function normalizeUrl(rawUrl: string): URL {
+  const url = new URL(rawUrl);
+
+  if (url.protocol === "http:" && url.port === "" && !isPrivateHost(url.hostname)) {
+    url.protocol = "https:";
+  }
+
+  return url;
+}
+
+function pruneCache(cache: Map<string, CacheEntry>): void {
+  const now = Date.now();
+  for (const [key, entry] of cache) {
+    if (entry.expiresAt <= now) {
+      cache.delete(key);
+    }
+  }
+}
+
+function parsePositiveInteger(value: string | undefined, fallback: number): number {
+  if (value === undefined || value.trim() === "") {
+    return fallback;
+  }
+
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}