agents/dist/connector-DZ71EjE-.d.ts

A home for your AI agents

import {
  d as BrowserBinding,
  h as BrowserSessionInfo,
  n as BrowserSessionStore,
  s as BrowserLiveView,
  u as LiveViewMode
} from "./session-store-B7Ca-u1t.js";
import {
  CodemodeConnector,
  ConnectorTool,
  ConnectorTools,
  ExecutionEndStatus,
  PassEndStatus
} from "@cloudflare/codemode";

//#region src/browser/quick-actions.d.ts
/**
 * A Browser Run binding that supports [Quick Actions](https://developers.cloudflare.com/browser-run/quick-actions/).
 *
 * This is the `quickAction()` surface of the `BrowserRun` binding generated by
 * `wrangler types`. Quick Actions are stateless one-shot tasks (screenshot,
 * PDF, markdown, structured extraction, …) — no session, no token, just the
 * binding.
 *
 * Requires a Worker `compatibility_date` of `2026-03-24` or later, and
 * `remote: true` on the browser binding for local `wrangler dev`.
 */
interface QuickActionBinding {
  quickAction(action: string, options: unknown): Promise<Response>;
}
/** The Quick Action endpoints exposed by Browser Run. */
type QuickAction =
  | "content"
  | "screenshot"
  | "pdf"
  | "markdown"
  | "snapshot"
  | "scrape"
  | "json"
  | "links"
  | "crawl";
type GotoOptions = {
  waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
  timeout?: number;
};
/** Options accepted by every Quick Action endpoint. */
interface QuickActionCommonOptions {
  gotoOptions?: GotoOptions;
  viewport?: {
    width: number;
    height: number;
    deviceScaleFactor?: number;
  };
  cookies?: unknown[];
  authenticate?: {
    username: string;
    password: string;
  };
  setExtraHTTPHeaders?: Record<string, string>;
  userAgent?: string;
  /** Regex strings for requests to drop before render (e.g. `["/\\.css$/"]`). */
  rejectRequestPattern?: string[];
}
/**
 * The page a Quick Action operates on: a `url` to load, or raw `html` to
 * render. Exactly one is required.
 */
type QuickActionPage =
  | ({
      url: string;
      html?: never;
    } & QuickActionCommonOptions)
  | ({
      html: string;
      url?: never;
    } & QuickActionCommonOptions);
/** Input for the AI-powered `/json` extraction endpoint. */
type QuickActionExtractInput = QuickActionPage & {
  /** Natural-language instruction for what to extract. */ prompt?: string /** A JSON Schema describing the desired output shape. */;
  response_format?: {
    type: "json_schema";
    json_schema: unknown;
  } /** Bring-your-own model(s), tried in order, for extraction. */;
  custom_ai?: {
    model: string;
    authorization: string;
  }[];
};
/** Input for the `/scrape` endpoint. */
type QuickActionScrapeInput = QuickActionPage & {
  elements: {
    selector: string;
  }[];
};
/** Input for the `/screenshot` endpoint. */
type QuickActionScreenshotInput = QuickActionPage & {
  screenshotOptions?: Record<string, unknown>;
  selector?: string;
};
/** Binary output (screenshot or PDF) with its reported content type. */
interface QuickActionBinary {
  data: Uint8Array;
  contentType: string;
}
/** Any Quick Action input accepted by the typed helpers. */
type QuickActionInput =
  | QuickActionPage
  | QuickActionExtractInput
  | QuickActionScrapeInput
  | QuickActionScreenshotInput;
/** Elements matched by one selector via `/scrape`. */
interface QuickActionScrapeResult {
  selector: string;
  results: {
    html: string;
    text: string;
    width: number;
    height: number;
    top: number;
    left: number;
    attributes: {
      name: string;
      value: string;
    }[];
  }[];
}
/** Result of a `/snapshot` request: rendered HTML plus a base64 screenshot. */
interface QuickActionSnapshot {
  /** HTML content of the page. */
  content: string;
  /** Base64-encoded screenshot image. */
  screenshot: string;
}
/**
 * Run a Quick Action and return the raw {@link Response} from the binding.
 *
 * Most callers want a typed helper ({@link browserMarkdown},
 * {@link browserExtract}, …) instead; reach for this only when you need an
 * endpoint or option not yet wrapped. The per-action overloads type `params`
 * against the action when it is a string literal (e.g. `"json"` requires a
 * {@link QuickActionExtractInput}); any {@link QuickActionInput} is accepted
 * otherwise.
 *
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function runQuickAction(
  browser: QuickActionBinding,
  action: "json",
  params: QuickActionExtractInput
): Promise<Response>;
/**
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function runQuickAction(
  browser: QuickActionBinding,
  action: "scrape",
  params: QuickActionScrapeInput
): Promise<Response>;
/**
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function runQuickAction(
  browser: QuickActionBinding,
  action: "screenshot",
  params: QuickActionScreenshotInput
): Promise<Response>;
/**
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function runQuickAction(
  browser: QuickActionBinding,
  action: QuickAction,
  params: QuickActionInput
): Promise<Response>;
/**
 * Fetch a page's fully rendered HTML via `/content`.
 *
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function browserContent(
  browser: QuickActionBinding,
  input: QuickActionPage
): Promise<string>;
/**
 * Convert a page (or raw HTML) to Markdown via `/markdown`.
 *
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function browserMarkdown(
  browser: QuickActionBinding,
  input: QuickActionPage
): Promise<string>;
/**
 * Extract structured data from a page with AI via `/json`. Provide a `prompt`,
 * a `response_format` JSON Schema, or both.
 *
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function browserExtract<T = unknown>(
  browser: QuickActionBinding,
  input: QuickActionExtractInput
): Promise<T>;
/**
 * Retrieve every link on a page via `/links`.
 *
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function browserLinks(
  browser: QuickActionBinding,
  input: QuickActionPage
): Promise<string[]>;
/**
 * Scrape specific elements (by CSS selector) via `/scrape`.
 *
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function browserScrape(
  browser: QuickActionBinding,
  input: QuickActionScrapeInput
): Promise<QuickActionScrapeResult[]>;
/**
 * Capture rendered HTML plus a base64 screenshot in one request via `/snapshot`.
 *
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function browserSnapshot(
  browser: QuickActionBinding,
  input: QuickActionPage
): Promise<QuickActionSnapshot>;
/**
 * Render a screenshot via `/screenshot`. Returns the raw bytes and their
 * content type — by default a PNG (`image/png`). Note that passing
 * `screenshotOptions.encoding: "base64"` makes the service return a `text/plain`
 * data-URI string instead of binary, which this helper hands back verbatim.
 *
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function browserScreenshot(
  browser: QuickActionBinding,
  input: QuickActionScreenshotInput
): Promise<QuickActionBinary>;
/**
 * Render a PDF via `/pdf`. Returns the PDF bytes.
 *
 * @deprecated Quick Actions are deprecated and won't change. Use
 * `browserTool` to drive a browser, the `web_fetch` tool from
 * `agents/webfetch` to read a page, or call the binding's
 * `quickAction()` directly.
 */
declare function browserPdf(
  browser: QuickActionBinding,
  input: QuickActionPage
): Promise<QuickActionBinary>;
//#endregion
//#region src/browser/connector.d.ts
/**
 * Browser session lifecycle for the connector (binding-backed only).
 *
 * @deprecated Part of `BrowserConnector`, which is deprecated.
 */
interface BrowserConnectorSessionOptions {
  /**
   * - `"one-shot"` (default) — one Browser Run session per codemode
   *   execution, deleted when the execution ends.
   * - `"reuse"` — all executions share one stored session under `key`.
   * - `"dynamic"` — per-execution sessions by default; the model can call
   *   `cdp.startSession()` to promote the current session into the shared
   *   slot so later executions reuse it.
   */
  mode?: "one-shot" | "reuse" | "dynamic";
  /** Logical owner key for the shared (reuse/promoted) session. Default `"default"`. */
  key?: string;
  /** Browser Run inactivity timeout. Browser Run currently caps this server-side. */
  keepAliveMs?: number;
  /**
   * Opt into Browser Run [session recording](https://developers.cloudflare.com/browser-run/features/session-recording/)
   * for sessions this connector creates: an rrweb capture of everything the
   * agent did, finalized when the session closes. Retrieve it afterward with
   * {@link getBrowserRecording} using the session id from
   * {@link BrowserConnector.liveView}/`sessionInfo()`.
   */
  recording?: boolean;
  /**
   * Select the browser engine. Defaults to Chromium. Kitesurf is scoped to
   * one CDP WebSocket, so it supports only one-shot execution without
   * pause/resume, Live View, recording, or keep-alive.
   */
  browser?: "kitesurf";
}
/**
 * Options for {@link BrowserConnector}.
 *
 * @deprecated Part of `BrowserConnector`, which is deprecated.
 */
type BrowserConnectorOptions = (
  | {
      /** Browser Rendering binding (Fetcher) — used in production. */ browser: BrowserBinding;
      /**
       * Durable store for Browser Run session ids. Required with the binding:
       * a session must survive a pause (approval) and resume on a fresh
       * instance, so its id cannot live in connector memory.
       */
      store: BrowserSessionStore;
      session?: BrowserConnectorSessionOptions;
      cdpUrl?: never;
      cdpHeaders?: never;
    }
  | {
      /**
       * CDP base URL override (e.g. http://localhost:9222). The browser is
       * externally managed: no Browser Run sessions are created or deleted,
       * and session modes don't apply.
       */
      cdpUrl: string /** Headers to send with CDP URL discovery requests (e.g. Access headers). */;
      cdpHeaders?: Record<string, string>;
      browser?: never;
      store?: never;
      session?: never;
    }
) & {
  /** CDP command timeout in milliseconds (default: 10000). */ timeout?: number;
};
/**
 * Options for {@link BrowserConnector.sweep}.
 *
 * @deprecated Part of `BrowserConnector`, which is deprecated.
 */
interface BrowserConnectorSweepOptions {
  /**
   * Close the shared (reuse/promoted) session when idle for at least this
   * many milliseconds. Defaults to the connector's `keepAliveMs`, or
   * {@link DEFAULT_SWEEP_IDLE_MS}.
   */
  maxIdleMs?: number;
  /**
   * Close *per-execution* sessions when idle for at least this many
   * milliseconds. Defaults to {@link DEFAULT_EXEC_SWEEP_IDLE_MS} (24h) —
   * deliberately at least as long as the codemode runtime's default paused
   * TTL, so a run awaiting approval is normally expired (and disposed) by
   * `expirePaused` before the sweep backstop ever touches its browser.
   */
  maxExecIdleMs?: number;
}
/**
 * What {@link BrowserConnector.sweep} reclaimed.
 *
 * @deprecated Part of `BrowserConnector`, which is deprecated.
 */
interface BrowserConnectorSweepResult {
  /** Store keys (and their Browser Run session ids) closed by this sweep. */
  swept: Array<{
    key: string;
    sessionId: string;
  }>;
}
/**
 * Default idle window before {@link BrowserConnector.sweep} reclaims a
 * per-execution session. Matches the codemode runtime's default paused TTL
 * (24h): an execution paused for approval keeps its browser until the run
 * itself is expired.
 *
 * @deprecated Part of `BrowserConnector`, which is deprecated.
 */
declare const DEFAULT_EXEC_SWEEP_IDLE_MS: number;
/**
 * Codemode connector exposing a live browser over the Chrome DevTools
 * Protocol as the `cdp` global.
 *
 * Per-execution resources are keyed by the codemode `executionId`:
 *
 * - The Browser Run session id is stored durably under `cdp:exec:<id>`, so a
 *   run that pauses for approval reconnects to the *same* browser when it
 *   resumes — even on a fresh instance.
 * - The CDP WebSocket is per-pass: `onPassEnd` disconnects it (a paused run
 *   holds no socket), and the next pass reconnects from the stored id.
 * - `disposeExecution` deletes the session unless it was promoted to the
 *   shared slot via `cdp.startSession()` (dynamic mode).
 *
 * Locks on the session store are held only around store reads/writes, never
 * across network calls to Browser Run or while a socket is open.
 *
 * @deprecated Use `browserTool` from `agents/browser/ai-sdk`,
 * `agents/browser/tanstack-ai` or `agents/browser/pi`. See
 * https://github.com/cloudflare/agents/blob/main/docs/agents/browse-the-web.md#persistent-browser
 */
declare class BrowserConnector extends CodemodeConnector {
  #private;
  constructor(
    ctx: DurableObjectState | ExecutionContext,
    options: BrowserConnectorOptions
  );
  name(): string;
  protected instructions(): string;
  protected tool(name: string, tool: ConnectorTool): ConnectorTool;
  protected tools(): ConnectorTools;
  /**
   * A pass is over (completed, errored, or paused awaiting approval) — drop
   * the CDP socket. The Browser Run session itself stays alive; a resume
   * reconnects from the durably stored session id.
   */
  onPassEnd(executionId: string, status: PassEndStatus): Promise<void>;
  /**
   * The execution is terminal — delete its Browser Run session unless it was
   * promoted to the shared slot via `cdp.startSession()`.
   */
  disposeExecution(
    executionId: string,
    _status: ExecutionEndStatus
  ): Promise<void>;
  /** Info about the shared (reuse/promoted) session, if one exists. */
  sessionInfo(): Promise<BrowserSessionInfo | undefined>;
  /**
   * Live View URLs for the shared (reuse/promoted) session's tabs, or
   * `undefined` when no shared session exists. Each URL opens an interactive,
   * real-time view of the browser — surface them in your UI (or send them via
   * Slack/email) to let a human watch or take over a running session
   * (human-in-the-loop). URLs are valid for ~5 minutes; call again for fresh
   * ones. Only meaningful with the Browser Rendering binding in
   * `reuse`/`dynamic` mode.
   */
  liveView(options?: {
    mode?: LiveViewMode;
  }): Promise<BrowserLiveView | undefined>;
  /** Close the shared (reuse/promoted) session, if one exists. */
  closeSession(): Promise<void>;
  /**
   * Close stored sessions (shared and per-execution) idle past the threshold.
   * Per-execution entries normally die with `disposeExecution` (or the
   * codemode runtime's `expirePaused`); the sweep is the backstop for crashed
   * hosts. Call it from a recurring alarm/scheduled task.
   *
   * Active executions bump their entry's `updatedAt` on use, so only runs
   * idle past `maxExecIdleMs` (default 24h) are reclaimed. A swept
   * per-execution entry is kept as a tombstone (`closedAt`) rather than
   * deleted, so a later resume fails with a clear "session expired" error
   * instead of silently continuing in a fresh browser; tombstones are
   * deleted once they age past the threshold again.
   *
   * Kitesurf entries are reclaimed the same way, minus the Browser Run
   * delete: their stored id is a synthetic per-execution marker, not a
   * session, and the connection died with the execution.
   */
  sweep(
    options?: BrowserConnectorSweepOptions
  ): Promise<BrowserConnectorSweepResult>;
}
//#endregion
export {
  browserScrape as C,
  runQuickAction as E,
  browserPdf as S,
  browserSnapshot as T,
  QuickActionSnapshot as _,
  BrowserConnectorSweepResult as a,
  browserLinks as b,
  QuickActionBinary as c,
  QuickActionExtractInput as d,
  QuickActionInput as f,
  QuickActionScreenshotInput as g,
  QuickActionScrapeResult as h,
  BrowserConnectorSweepOptions as i,
  QuickActionBinding as l,
  QuickActionScrapeInput as m,
  BrowserConnectorOptions as n,
  DEFAULT_EXEC_SWEEP_IDLE_MS as o,
  QuickActionPage as p,
  BrowserConnectorSessionOptions as r,
  QuickAction as s,
  BrowserConnector as t,
  QuickActionCommonOptions as u,
  browserContent as v,
  browserScreenshot as w,
  browserMarkdown as x,
  browserExtract as y
};
//# sourceMappingURL=connector-DZ71EjE-.d.ts.map