agents 0.23.0 → 0.25.0

package/dist/browser-DE3d-RLk.d.ts

@@ -0,0 +1,275 @@
+import { s as LifecycleCapability } from "./capability-runner-DBAnGr6L.js";
+import {
+  $ as CdpConnection,
+  F as LiveViewMode,
+  I as BrowserBinding,
+  M as BrowserLiveView,
+  O as BrowserSessionStore,
+  z as BrowserSessionGuardrails
+} from "./connector-Cl-VqPmA.js";
+
+//#region src/browser/spec.d.ts
+/**
+ * The element type of an array field or type. `$ref` is always
+ * domain-qualified (`"Network.Cookie"`), matching a type's `name`.
+ */
+interface CdpItems {
+  type?: string;
+  $ref?: string;
+  enum?: string[];
+}
+/**
+ * A command parameter, return value, event parameter, or type property.
+ * Either `type` (a JSON type such as `"string"` or `"array"`) or `$ref`
+ * (a domain-qualified type name matching a type's `name`) is set.
+ */
+interface CdpField {
+  name: string;
+  description?: string;
+  optional?: boolean;
+  experimental?: boolean;
+  deprecated?: boolean;
+  type?: string;
+  $ref?: string;
+  enum?: string[];
+  items?: CdpItems;
+}
+interface SearchableCdpSpec {
+  domains: Array<{
+    name: string;
+    description?: string;
+    experimental?: boolean;
+    deprecated?: boolean;
+    commands: Array<{
+      name: string;
+      method: string;
+      description?: string;
+      experimental?: boolean;
+      deprecated?: boolean;
+      parameters: CdpField[];
+      returns: CdpField[];
+    }>;
+    events: Array<{
+      name: string;
+      event: string;
+      description?: string;
+      experimental?: boolean;
+      deprecated?: boolean;
+      parameters: CdpField[];
+    }>;
+    types: Array<{
+      id: string;
+      name: string;
+      description?: string;
+      experimental?: boolean;
+      deprecated?: boolean /** JSON type of the value, e.g. `"string"`, `"object"`, `"array"`. */;
+      type?: string;
+      enum?: string[];
+      properties: CdpField[];
+      items?: CdpItems;
+    }>;
+  }>;
+}
+interface CdpSpecSource {
+  /** Browser Rendering binding (Fetcher) — used in production */
+  browser?: BrowserBinding;
+  /** CDP base URL override (e.g. http://localhost:9222) */
+  cdpUrl?: string;
+  /** Headers to send with CDP URL discovery requests */
+  cdpHeaders?: Record<string, string>;
+  /**
+   * An existing Browser Run session to read the protocol from. Without it,
+   * loading through the binding creates (and deletes) a throwaway session.
+   */
+  sessionId?: string;
+}
+/** Load the (cached) searchable CDP spec for a browser source. */
+declare function loadCdpSpec(source: CdpSpecSource): Promise<SearchableCdpSpec>;
+//#endregion
+//#region src/browser/browser.d.ts
+/**
+ * Browser Run settings applied every time a browser is created — including
+ * when a lost browser is replaced — so options like guardrails survive a
+ * restart.
+ */
+interface BrowserRunOptions {
+  /**
+   * Platform `keep_alive` in milliseconds: how long an idle browser lives.
+   * Defaults to {@link BROWSER_SESSION_KEEP_ALIVE_MAX_MS} (the platform
+   * maximum).
+   */
+  keepAliveMs?: number;
+  /** Opt into Browser Run session recording (rrweb capture). */
+  recording?: boolean;
+  /** Hostname guardrails, fixed at launch for every connection. */
+  guardrails?: BrowserSessionGuardrails;
+}
+/** A {@link Browser} provider backed by Cloudflare Browser Run. */
+interface BrowserRunProvider {
+  readonly kind: "browser-run";
+  readonly binding: BrowserBinding;
+  readonly options: BrowserRunOptions;
+}
+/** Where a {@link Browser} gets its browser from. */
+type BrowserProvider = BrowserRunProvider;
+/**
+ * Run the browser on Cloudflare Browser Run.
+ *
+ * @example
+ * ```ts
+ * new Browser({ provider: browserRun(env.BROWSER, { recording: true }) });
+ * ```
+ */
+declare function browserRun(
+  binding: BrowserBinding,
+  options?: BrowserRunOptions
+): BrowserRunProvider;
+interface BrowserOptions {
+  /** Where the browser runs. Create one with {@link browserRun}. */
+  provider: BrowserProvider;
+  /**
+   * Which browser this is. Two `Browser` objects on the same Durable Object
+   * need different names. Defaults to {@link DEFAULT_BROWSER_NAME}.
+   */
+  name?: string;
+  /**
+   * Where the browser's record lives. Defaults to a
+   * {@link DurableBrowserSessionStore} over the host object's storage, which
+   * requires installing the `Browser` with `Lifecycle.use()`. Passing a store
+   * lets the `Browser` work without Lifecycle.
+   */
+  store?: BrowserSessionStore;
+  /** Default CDP command timeout for {@link Browser.connect}. */
+  timeoutMs?: number;
+  /**
+   * Minimum interval between activity-driven `updatedAt` refreshes.
+   * Defaults to {@link SESSION_TOUCH_INTERVAL_MS}, capped at half the
+   * keep-alive window.
+   *
+   * @internal For tests.
+   */
+  touchIntervalMs?: number;
+}
+interface ResolvedBrowser {
+  name: string;
+  /** The Browser Run session id — host-side only, never model-visible. */
+  sessionId: string;
+  /**
+   * `true` when this resolution had to create a fresh browser to replace one
+   * that previously existed (was closed, or expired or died upstream). Page
+   * state from the prior browser is gone; surface this loudly to the model.
+   * `false` only on first-ever use of the name — nothing was lost.
+   */
+  restarted: boolean;
+  createdAt: number;
+  updatedAt: number;
+  /**
+   * The tab the agent last worked in, when one was recorded for this
+   * browser. Absent on a browser this resolution created; a replacement a
+   * concurrent caller already created and used may carry one.
+   */
+  activeTargetId?: string;
+}
+interface BrowserConnection {
+  name: string;
+  sessionId: string;
+  /**
+   * `true` when the browser this caller resolved is gone, even if a
+   * concurrent caller already replaced it. See
+   * {@link ResolvedBrowser.restarted}.
+   */
+  restarted: boolean;
+  /** See {@link ResolvedBrowser.activeTargetId}. */
+  activeTargetId?: string;
+  /** Closing this connection does NOT close the browser. */
+  cdp: CdpConnection;
+  /**
+   * Record the tab the agent is working in (or clear it with `undefined`).
+   * Never resurrects: returns `false` when the browser was closed or
+   * replaced since this connection resolved it.
+   */
+  setActiveTarget(targetId: string | undefined): Promise<boolean>;
+  /**
+   * The Chrome DevTools Protocol description this browser serves, read from
+   * the browser itself (cached per binding).
+   */
+  spec(): Promise<SearchableCdpSpec>;
+}
+/**
+ * One named, persistent browser.
+ *
+ * Install it with `Lifecycle.use()` — on an Agent subclass or any Durable
+ * Object that composes `Lifecycle` — and it stores its record in the
+ * object's own storage. It schedules nothing: Browser Run reclaims idle
+ * browsers itself once `keep_alive` elapses, and the next use replaces the
+ * lost browser with `restarted: true`.
+ *
+ * Everything here is host-side. Models never see browser names, Browser Run
+ * ids, or Live View URLs through this surface.
+ *
+ * Store discipline: locks wrap storage operations only — liveness probes and
+ * Browser Run create/delete calls always happen outside any lock, with a
+ * commit re-check to detect concurrent swaps.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class Browser extends LifecycleCapability {
+  #private;
+  /** Which browser this is; see {@link BrowserOptions.name}. */
+  readonly name: string;
+  constructor(options: BrowserOptions);
+  /**
+   * Reattach to the browser when it is still alive, otherwise create a fresh
+   * one. See {@link ResolvedBrowser.restarted} for the mortality signal.
+   */
+  resolve(): Promise<ResolvedBrowser>;
+  /**
+   * Resolve the browser and open a CDP connection to it. Commands sent over
+   * the connection refresh the record's `updatedAt` (throttled to
+   * {@link SESSION_TOUCH_INTERVAL_MS}), so hosts can tell an actively used
+   * browser from one the platform has likely reclaimed.
+   *
+   * If the browser expires between the liveness probe and the WebSocket
+   * upgrade, the record is retired and the browser resolved once more, so
+   * the caller gets a fresh browser with `restarted: true` instead of an
+   * error.
+   */
+  connect(): Promise<BrowserConnection>;
+  /**
+   * Close the browser: retire the record (so the next resolve reports
+   * `restarted: true`) and delete its Browser Run session. Returns `false`
+   * when there was nothing to close.
+   *
+   * The platform delete is best-effort: the retired record is the durable
+   * outcome, and a browser whose delete failed is unreachable through this
+   * store, so the pinned `keep_alive` (≤600s) reclaims it.
+   */
+  close(): Promise<boolean>;
+  /**
+   * Mint Live View URLs for the browser's open tabs, fresh from a target
+   * listing. `undefined` when the browser was never created, is closed, or
+   * is gone. The URLs are bearer credentials with a short connect window
+   * (~5 min) — hand them to a trusted human, never to the model, and never
+   * store them: re-mint instead.
+   */
+  liveView(options?: {
+    mode?: LiveViewMode;
+  }): Promise<BrowserLiveView | undefined>;
+}
+//#endregion
+export {
+  BrowserRunOptions as a,
+  browserRun as c,
+  CdpSpecSource as d,
+  SearchableCdpSpec as f,
+  BrowserProvider as i,
+  CdpField as l,
+  BrowserConnection as n,
+  BrowserRunProvider as o,
+  loadCdpSpec as p,
+  BrowserOptions as r,
+  ResolvedBrowser as s,
+  Browser as t,
+  CdpItems as u
+};
+//# sourceMappingURL=browser-DE3d-RLk.d.ts.map