agents 0.15.0 → 0.16.1

package/dist/connector-v2M1zlZp.d.ts

@@ -0,0 +1,659 @@
+import {
+  CodemodeConnector,
+  ConnectorTools,
+  ExecutionEndStatus,
+  PassEndStatus
+} from "@cloudflare/codemode";
+
+//#region src/browser/cdp-session.d.ts
+interface DebugEntry {
+  at: string;
+  type: string;
+  [key: string]: unknown;
+}
+interface CdpSendOptions {
+  timeoutMs?: number;
+  sessionId?: string;
+}
+interface CdpAttachOptions {
+  timeoutMs?: number;
+}
+/**
+ * A CDP session over an open WebSocket. Manages command correlation,
+ * timeouts, target sessions, and a debug event ring buffer.
+ *
+ * Used host-side (not in the sandbox) — the sandbox calls into this
+ * via DynamicWorkerExecutor's ToolDispatcher RPC.
+ */
+declare class CdpSession {
+  #private;
+  readonly sessionId?: string;
+  constructor(
+    socket: WebSocket,
+    defaultTimeoutMs?: number,
+    dispose?: () => void,
+    sessionId?: string
+  );
+  send(
+    method: string,
+    params?: unknown,
+    options?: CdpSendOptions
+  ): Promise<unknown>;
+  attachToTarget(targetId: string, options?: CdpAttachOptions): Promise<string>;
+  getDebugLog(limit?: number): DebugEntry[];
+  clearDebugLog(): void;
+  disconnect(): void;
+  close(): void;
+}
+/**
+ * Connect to a browser via a CDP base URL (e.g. http://localhost:9222).
+ * Discovers the WebSocket debugger URL via /json/version,
+ * rewrites localhost URLs to the base URL host, and opens the WebSocket.
+ *
+ * Useful for local development with `chrome --remote-debugging-port=9222`
+ * or when connecting through a tunnel.
+ */
+declare function connectUrl(
+  baseUrl: string,
+  options?: {
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+  }
+): Promise<CdpSession>;
+//#endregion
+//#region src/browser/browser-run.d.ts
+/**
+ * A Browser Rendering binding. Structural so it accepts both the classic
+ * `Fetcher`-typed binding and the newer `BrowserRun` type generated by
+ * `wrangler types` — we only ever use its `fetch` surface.
+ */
+interface BrowserBinding {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+interface BrowserTargetInfo {
+  id: string;
+  type?: string;
+  url?: string;
+  title?: string;
+  description?: string;
+  devtoolsFrontendUrl?: string;
+  webSocketDebuggerUrl?: string;
+}
+interface BrowserSessionInfo {
+  sessionId: string;
+  targets?: BrowserTargetInfo[];
+  webSocketDebuggerUrl?: string;
+}
+interface ConnectBrowserOptions {
+  timeoutMs?: number;
+  keepAliveMs?: number;
+  includeTargets?: boolean;
+  /**
+   * Opt into Browser Run [session recording](https://developers.cloudflare.com/browser-run/features/session-recording/):
+   * an rrweb capture of DOM changes, input, and navigation, finalized when the
+   * session closes. Set at session-launch time. Retrieve later with
+   * {@link getBrowserRecording}.
+   */
+  recording?: boolean;
+}
+/** An rrweb session recording for a closed Browser Run session. */
+interface BrowserRecording {
+  sessionId: string;
+  /** Recording length in milliseconds. */
+  duration: number;
+  /**
+   * rrweb event arrays keyed by CDP target id (one per tab). Each value can be
+   * passed directly to `rrweb-player` to replay that tab.
+   */
+  events: Record<string, unknown[]>;
+}
+declare class BrowserRenderingError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number);
+}
+declare function createBrowserSession(
+  browser: BrowserBinding,
+  options?: {
+    keepAliveMs?: number;
+    includeTargets?: boolean;
+    recording?: boolean;
+  }
+): Promise<BrowserSessionInfo>;
+declare function listBrowserTargets(
+  browser: BrowserBinding,
+  sessionId: string
+): Promise<BrowserTargetInfo[]>;
+declare function deleteBrowserSession(
+  browser: BrowserBinding,
+  sessionId: string
+): Promise<void>;
+/**
+ * Connect to a Browser Rendering session and delete it when closed.
+ */
+declare function connectBrowser(
+  browser: BrowserBinding,
+  options?: number | ConnectBrowserOptions
+): Promise<CdpSession>;
+/**
+ * Fetch a Browser Run [session recording](https://developers.cloudflare.com/browser-run/features/session-recording/)
+ * by session id, via the Browser Rendering REST API.
+ *
+ * A recording is only available **after** the session closes (explicit
+ * `closeSession()`, idle `keep_alive` expiry, or sweep) and is retained for 30
+ * days. Capture the session id while the session is alive — e.g. from
+ * `connector.liveView()`/`sessionInfo()` — then call this once it has ended.
+ *
+ * Unlike the binding-based helpers, this hits `api.cloudflare.com` directly, so
+ * it needs an account id and an API token with `Browser Rendering` read access
+ * (the Workers Browser Run binding cannot read recordings).
+ */
+declare function getBrowserRecording(options: {
+  accountId: string;
+  apiToken: string;
+  sessionId: string /** Override for testing; defaults to the global `fetch`. */;
+  fetchImpl?: typeof fetch;
+}): Promise<BrowserRecording>;
+/**
+ * Connect to an existing Browser Rendering session without deleting it on close.
+ */
+declare function connectBrowserSession(
+  browser: BrowserBinding,
+  sessionId: string,
+  timeoutMs?: number
+): Promise<CdpSession>;
+//#endregion
+//#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";
+    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.
+ */
+declare function runQuickAction(
+  browser: QuickActionBinding,
+  action: "json",
+  params: QuickActionExtractInput
+): Promise<Response>;
+declare function runQuickAction(
+  browser: QuickActionBinding,
+  action: "scrape",
+  params: QuickActionScrapeInput
+): Promise<Response>;
+declare function runQuickAction(
+  browser: QuickActionBinding,
+  action: "screenshot",
+  params: QuickActionScreenshotInput
+): Promise<Response>;
+declare function runQuickAction(
+  browser: QuickActionBinding,
+  action: QuickAction,
+  params: QuickActionInput
+): Promise<Response>;
+/** Fetch a page's fully rendered HTML via `/content`. */
+declare function browserContent(
+  browser: QuickActionBinding,
+  input: QuickActionPage
+): Promise<string>;
+/** Convert a page (or raw HTML) to Markdown via `/markdown`. */
+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.
+ */
+declare function browserExtract<T = unknown>(
+  browser: QuickActionBinding,
+  input: QuickActionExtractInput
+): Promise<T>;
+/** Retrieve every link on a page via `/links`. */
+declare function browserLinks(
+  browser: QuickActionBinding,
+  input: QuickActionPage
+): Promise<string[]>;
+/** Scrape specific elements (by CSS selector) via `/scrape`. */
+declare function browserScrape(
+  browser: QuickActionBinding,
+  input: QuickActionScrapeInput
+): Promise<QuickActionScrapeResult[]>;
+/** Capture rendered HTML plus a base64 screenshot in one request via `/snapshot`. */
+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.
+ */
+declare function browserScreenshot(
+  browser: QuickActionBinding,
+  input: QuickActionScreenshotInput
+): Promise<QuickActionBinary>;
+/** Render a PDF via `/pdf`. Returns the PDF bytes. */
+declare function browserPdf(
+  browser: QuickActionBinding,
+  input: QuickActionPage
+): Promise<QuickActionBinary>;
+//#endregion
+//#region src/browser/session-manager.d.ts
+type MaybePromise<T> = T | Promise<T>;
+interface StoredBrowserSession {
+  sessionId: string;
+  createdAt: number;
+  updatedAt: number;
+  /**
+   * Set when a sweep closed this entry's Browser Run session but kept the
+   * entry as a tombstone, so a later resume of the owning execution fails
+   * loudly instead of silently continuing in a fresh browser.
+   */
+  closedAt?: number;
+}
+interface BrowserSessionLock {
+  release(): MaybePromise<void>;
+}
+interface BrowserSessionStore {
+  /**
+   * Acquire an exclusive lock for this session key. The lock must serialize
+   * all holders using the same key. Held only around storage reads/writes —
+   * never across Browser Rendering network calls.
+   */
+  acquireLock(key: string): MaybePromise<BrowserSessionLock>;
+  get(key: string): MaybePromise<StoredBrowserSession | undefined>;
+  set(key: string, session: StoredBrowserSession): MaybePromise<void>;
+  delete(key: string): MaybePromise<void>;
+  /**
+   * List stored sessions by key prefix. Optional — used by sweeps to find
+   * orphaned per-execution sessions; without it only the shared session key
+   * is swept.
+   */
+  list?(prefix: string): MaybePromise<Map<string, StoredBrowserSession>>;
+}
+declare class DurableBrowserSessionStore implements BrowserSessionStore {
+  #private;
+  private readonly storage;
+  constructor(storage: DurableObjectStorage);
+  acquireLock(key: string): Promise<BrowserSessionLock>;
+  get(key: string): Promise<StoredBrowserSession | undefined>;
+  set(key: string, session: StoredBrowserSession): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(prefix: string): Promise<Map<string, StoredBrowserSession>>;
+}
+/**
+ * Default idle window used by {@link BrowserConnector.sweep} for the shared
+ * (reuse/promoted) session entry.
+ */
+declare const DEFAULT_SWEEP_IDLE_MS: number;
+//#endregion
+//#region src/browser/connector.d.ts
+/** Browser session lifecycle for the connector (binding-backed only). */
+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;
+}
+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;
+};
+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;
+}
+interface BrowserConnectorSweepResult {
+  /** Store keys (and their Browser Run session ids) closed by this sweep. */
+  swept: Array<{
+    key: string;
+    sessionId: string;
+  }>;
+}
+/**
+ * Live View rendering mode (the `mode` query param the hosted UI at
+ * `live.browser.run` understands):
+ *
+ * - `"tab"` — a standalone, interactive page view (best for handing control
+ *   to a human).
+ * - `"devtools"` — the full DevTools inspector panel (Elements, Console,
+ *   Network, …).
+ *
+ * Omit it to use whatever mode the binding's `devtoolsFrontendUrl` defaults
+ * to.
+ */
+type LiveViewMode = "tab" | "devtools";
+/** A single tab's Live View URL. */
+interface BrowserLiveViewUrl {
+  /** Open this in a browser to watch/control the tab in real time. */
+  url: string;
+  /** CDP target (tab) id the URL points at. */
+  targetId: string;
+  /** Milliseconds the URL stays valid from when it was generated (~5 min). */
+  expiresInMs: number;
+}
+interface BrowserLiveViewTarget {
+  targetId: string;
+  /** Embeddable Live View URL (the `devtoolsFrontendUrl`) for this tab. */
+  url: string;
+  /** The page the tab is currently showing (e.g. `https://example.com`). */
+  pageUrl?: string;
+  title?: string;
+  type?: string;
+}
+/** Live View URLs for every tab in a (shared) session. */
+interface BrowserLiveView {
+  sessionId: string;
+  targets: BrowserLiveViewTarget[];
+  /** Milliseconds the URLs stay valid from when they were generated (~5 min). */
+  expiresInMs: number;
+}
+/**
+ * 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.
+ */
+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.
+ */
+declare class BrowserConnector extends CodemodeConnector {
+  #private;
+  constructor(
+    ctx: DurableObjectState | ExecutionContext,
+    options: BrowserConnectorOptions
+  );
+  name(): string;
+  protected instructions(): string;
+  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.
+   */
+  sweep(
+    options?: BrowserConnectorSweepOptions
+  ): Promise<BrowserConnectorSweepResult>;
+}
+//#endregion
+export {
+  browserMarkdown as A,
+  BrowserTargetInfo as B,
+  QuickActionScrapeInput as C,
+  browserContent as D,
+  QuickActionSnapshot as E,
+  runQuickAction as F,
+  deleteBrowserSession as G,
+  connectBrowser as H,
+  BrowserBinding as I,
+  CdpAttachOptions as J,
+  getBrowserRecording as K,
+  BrowserRecording as L,
+  browserScrape as M,
+  browserScreenshot as N,
+  browserExtract as O,
+  browserSnapshot as P,
+  BrowserRenderingError as R,
+  QuickActionPage as S,
+  QuickActionScreenshotInput as T,
+  connectBrowserSession as U,
+  ConnectBrowserOptions as V,
+  createBrowserSession as W,
+  CdpSession as X,
+  CdpSendOptions as Y,
+  connectUrl as Z,
+  QuickActionBinary as _,
+  BrowserConnectorSweepResult as a,
+  QuickActionExtractInput as b,
+  BrowserLiveViewUrl as c,
+  BrowserSessionLock as d,
+  BrowserSessionStore as f,
+  QuickAction as g,
+  StoredBrowserSession as h,
+  BrowserConnectorSweepOptions as i,
+  browserPdf as j,
+  browserLinks as k,
+  DEFAULT_EXEC_SWEEP_IDLE_MS as l,
+  DurableBrowserSessionStore as m,
+  BrowserConnectorOptions as n,
+  BrowserLiveView as o,
+  DEFAULT_SWEEP_IDLE_MS as p,
+  listBrowserTargets as q,
+  BrowserConnectorSessionOptions as r,
+  BrowserLiveViewTarget as s,
+  BrowserConnector as t,
+  LiveViewMode as u,
+  QuickActionBinding as v,
+  QuickActionScrapeResult as w,
+  QuickActionInput as x,
+  QuickActionCommonOptions as y,
+  BrowserSessionInfo as z
+};
+//# sourceMappingURL=connector-v2M1zlZp.d.ts.map