@fungi.computer/oyster 0.2.0 → 0.3.0

package/docs/api/browser.md

@@ -0,0 +1,1440 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / browser
+
+# browser
+
+## Classes
+
+### CloudBrowserUrlDenied
+
+The target URL failed policy before any provider call was made.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `reason`: \|
+  `"invalid_url"` \| `"unsupported_scheme"` \| `"credentials_in_url"` \|
+  `"not_public"` \| `"dns_unavailable"`; `message`: `string`; \}\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new CloudBrowserUrlDenied(args): CloudBrowserUrlDenied;
+```
+
+###### Parameters
+
+| Parameter      | Type                                                                                                                                                  |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `args`         | \{ `reason`: \| `"invalid_url"` \| `"unsupported_scheme"` \| `"credentials_in_url"` \| `"not_public"` \| `"dns_unavailable"`; `message`: `string`; \} |
+| `args.reason`  | \| `"invalid_url"` \| `"unsupported_scheme"` \| `"credentials_in_url"` \| `"not_public"` \| `"dns_unavailable"`                                       |
+| `args.message` | `string`                                                                                                                                              |
+
+###### Returns
+
+[`CloudBrowserUrlDenied`](#cloudbrowserurldenied)
+
+###### Inherited from
+
+```ts
+Data.TaggedError(
+  "CloudBrowserUrlDenied",
+)<{
+  readonly reason:
+    | "invalid_url"
+    | "unsupported_scheme"
+    | "credentials_in_url"
+    | "not_public"
+    | "dns_unavailable";
+  readonly message: string;
+}>.constructor
+```
+
+#### Properties
+
+##### reason
+
+```ts
+readonly reason:
+  | "invalid_url"
+  | "unsupported_scheme"
+  | "credentials_in_url"
+  | "not_public"
+  | "dns_unavailable";
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserUrlDenied").reason;
+```
+
+##### message
+
+```ts
+message: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserUrlDenied").message;
+```
+
+---
+
+### CloudBrowserUpstreamError
+
+The provider (Cloudflare Browser Run) answered with a failure.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `op`: `string`;
+  `status`: `number` \| `null`; `message`: `string`; \}\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new CloudBrowserUpstreamError(args): CloudBrowserUpstreamError;
+```
+
+###### Parameters
+
+| Parameter      | Type                                                                     |
+| -------------- | ------------------------------------------------------------------------ |
+| `args`         | \{ `op`: `string`; `status`: `number` \| `null`; `message`: `string`; \} |
+| `args.op`      | `string`                                                                 |
+| `args.status`  | `number` \| `null`                                                       |
+| `args.message` | `string`                                                                 |
+
+###### Returns
+
+[`CloudBrowserUpstreamError`](#cloudbrowserupstreamerror)
+
+###### Inherited from
+
+```ts
+Data.TaggedError(
+  "CloudBrowserUpstreamError",
+)<{
+  readonly op: string;
+  readonly status: number | null;
+  readonly message: string;
+}>.constructor
+```
+
+#### Properties
+
+##### op
+
+```ts
+readonly op: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserUpstreamError").op;
+```
+
+##### status
+
+```ts
+readonly status: number | null;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserUpstreamError").status;
+```
+
+##### message
+
+```ts
+message: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserUpstreamError").message;
+```
+
+---
+
+### CloudBrowserTimeout
+
+A call did not complete within its deadline.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `op`: `string`;
+  `timeoutMs`: `number`; \}\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new CloudBrowserTimeout(args): CloudBrowserTimeout;
+```
+
+###### Parameters
+
+| Parameter        | Type                                         |
+| ---------------- | -------------------------------------------- |
+| `args`           | \{ `op`: `string`; `timeoutMs`: `number`; \} |
+| `args.op`        | `string`                                     |
+| `args.timeoutMs` | `number`                                     |
+
+###### Returns
+
+[`CloudBrowserTimeout`](#cloudbrowsertimeout)
+
+###### Inherited from
+
+```ts
+Data.TaggedError(
+  "CloudBrowserTimeout",
+)<{
+  readonly op: string;
+  readonly timeoutMs: number;
+}>.constructor
+```
+
+#### Properties
+
+##### op
+
+```ts
+readonly op: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserTimeout").op;
+```
+
+##### timeoutMs
+
+```ts
+readonly timeoutMs: number;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserTimeout").timeoutMs;
+```
+
+---
+
+### CloudBrowserLeaseNotFound
+
+The named lease is not held by this (teamId, agentId, sessionId).
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `leaseId`: `string`;
+  \}\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new CloudBrowserLeaseNotFound(args): CloudBrowserLeaseNotFound;
+```
+
+###### Parameters
+
+| Parameter      | Type                       |
+| -------------- | -------------------------- |
+| `args`         | \{ `leaseId`: `string`; \} |
+| `args.leaseId` | `string`                   |
+
+###### Returns
+
+[`CloudBrowserLeaseNotFound`](#cloudbrowserleasenotfound)
+
+###### Inherited from
+
+```ts
+Data.TaggedError(
+  "CloudBrowserLeaseNotFound",
+)<{
+  readonly leaseId: string;
+}>.constructor
+```
+
+#### Properties
+
+##### leaseId
+
+```ts
+readonly leaseId: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserLeaseNotFound").leaseId;
+```
+
+---
+
+### CloudBrowserLeasePaused
+
+A member was asked to take over; the Agent cannot drive it until "Done".
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `leaseId`: `string`;
+  \}\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new CloudBrowserLeasePaused(args): CloudBrowserLeasePaused;
+```
+
+###### Parameters
+
+| Parameter      | Type                       |
+| -------------- | -------------------------- |
+| `args`         | \{ `leaseId`: `string`; \} |
+| `args.leaseId` | `string`                   |
+
+###### Returns
+
+[`CloudBrowserLeasePaused`](#cloudbrowserleasepaused)
+
+###### Inherited from
+
+```ts
+Data.TaggedError(
+  "CloudBrowserLeasePaused",
+)<{
+  readonly leaseId: string;
+}>.constructor
+```
+
+#### Properties
+
+##### leaseId
+
+```ts
+readonly leaseId: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserLeasePaused").leaseId;
+```
+
+---
+
+### CloudBrowserCapacityExceeded
+
+The Team has no more concurrent leases available right now.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `teamId`: `string`;
+  `limit`: `number`; \}\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new CloudBrowserCapacityExceeded(args): CloudBrowserCapacityExceeded;
+```
+
+###### Parameters
+
+| Parameter     | Type                                         |
+| ------------- | -------------------------------------------- |
+| `args`        | \{ `teamId`: `string`; `limit`: `number`; \} |
+| `args.teamId` | `string`                                     |
+| `args.limit`  | `number`                                     |
+
+###### Returns
+
+[`CloudBrowserCapacityExceeded`](#cloudbrowsercapacityexceeded)
+
+###### Inherited from
+
+```ts
+Data.TaggedError(
+  "CloudBrowserCapacityExceeded",
+)<{
+  readonly teamId: string;
+  readonly limit: number;
+}>.constructor
+```
+
+#### Properties
+
+##### teamId
+
+```ts
+readonly teamId: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserCapacityExceeded").teamId;
+```
+
+##### limit
+
+```ts
+readonly limit: number;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserCapacityExceeded").limit;
+```
+
+---
+
+### CloudBrowserCreditDenied
+
+The Team has no credit to start or continue a lease.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `teamId`: `string`;
+  \}\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new CloudBrowserCreditDenied(args): CloudBrowserCreditDenied;
+```
+
+###### Parameters
+
+| Parameter     | Type                      |
+| ------------- | ------------------------- |
+| `args`        | \{ `teamId`: `string`; \} |
+| `args.teamId` | `string`                  |
+
+###### Returns
+
+[`CloudBrowserCreditDenied`](#cloudbrowsercreditdenied)
+
+###### Inherited from
+
+```ts
+Data.TaggedError(
+  "CloudBrowserCreditDenied",
+)<{
+  readonly teamId: string;
+}>.constructor
+```
+
+#### Properties
+
+##### teamId
+
+```ts
+readonly teamId: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserCreditDenied").teamId;
+```
+
+---
+
+### CloudBrowserUnavailable
+
+No backend is configured (credentials absent, or the feature is paused).
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `reason`: `"paused"` \|
+  `"unconfigured"`; \}\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new CloudBrowserUnavailable(args): CloudBrowserUnavailable;
+```
+
+###### Parameters
+
+| Parameter     | Type                                            |
+| ------------- | ----------------------------------------------- |
+| `args`        | \{ `reason`: `"paused"` \| `"unconfigured"`; \} |
+| `args.reason` | `"paused"` \| `"unconfigured"`                  |
+
+###### Returns
+
+[`CloudBrowserUnavailable`](#cloudbrowserunavailable)
+
+###### Inherited from
+
+```ts
+Data.TaggedError(
+  "CloudBrowserUnavailable",
+)<{
+  readonly reason: "unconfigured" | "paused";
+}>.constructor
+```
+
+#### Properties
+
+##### reason
+
+```ts
+readonly reason: "paused" | "unconfigured";
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CloudBrowserUnavailable").reason;
+```
+
+## Type Aliases
+
+### BrowserMeter
+
+```ts
+type BrowserMeter = Readonly<{
+  hold: (input) => Promise<void>;
+  start: (input) => Promise<void>;
+  settle: (input) => Promise<void>;
+  release: (input) => Promise<void>;
+}>;
+```
+
+One metered execution (a lease or a Quick Read), driven only by `createBrowser`.
+`maxMs` is the execution's own ceiling: the hold covers it and settlement never
+exceeds it.
+
+---
+
+### BrowserEvent
+
+```ts
+type BrowserEvent = Readonly<{
+  kind:
+    | "reap_close_failed"
+    | "reap_settle_failed"
+    | "settle_failed"
+    | "open_cleanup_failed"
+    | "read_release_failed"
+    | "teardown_failed"
+    | "teardown_abandoned";
+  teamId: string;
+  executionId: string;
+  cause: unknown;
+}>;
+```
+
+Code-only observations; never a URL, page text, token or provider body.
+
+---
+
+### BrowserHost
+
+```ts
+type BrowserHost = Readonly<{
+  sessions: BrowserSessions;
+  quickReads: QuickReads | null;
+  meter: (owner) => BrowserMeter;
+  report: (event) => void;
+}>;
+```
+
+The ONE host port for config, billing and provider egress.
+
+---
+
+### BrowserLimits
+
+```ts
+type BrowserLimits = Readonly<{
+  maxConcurrentPerTeam: number;
+  maxLifetimeMs: number;
+  idleTimeoutMs: number;
+  navigationTimeoutMs?: number;
+  closeConfirmMs?: number;
+  quickReadTimeoutMs?: number;
+  now?: () => number;
+}>;
+```
+
+`@fungi.computer/oyster/browser`: the one agent browser for the Hub and a
+standalone Oyster. A host builds the port from a provider (`browserRunSessions`
+or `bindingSessions`, plus Browser Run Quick Reads when it has them), its
+required metering owner and an event sink; `createBrowser` owns lease ownership,
+egress policy and billing order; `browserCapabilitySource` is the agent's
+`cloudBrowser` tool. Raw CDP stays internal to this directory.
+
+---
+
+### BrowserMemberAction
+
+```ts
+type BrowserMemberAction =
+  | Readonly<{
+      kind: "screenshot";
+    }>
+  | Readonly<{
+      kind: "click";
+      x: number;
+      y: number;
+    }>
+  | Readonly<{
+      kind: "type";
+      text: string;
+    }>
+  | Readonly<{
+      kind: "scroll";
+      deltaX: number;
+      deltaY: number;
+    }>
+  | Readonly<{
+      kind: "resume";
+    }>;
+```
+
+What a Team member may do to a lease an Agent handed off.
+
+---
+
+### Browser
+
+```ts
+type Browser = Readonly<{
+  quickReads: boolean;
+  call: (owner, op, signal) => Promise<CloudBrowserOperationResult>;
+  handoff: (owner, leaseId) => void;
+  member: (teamId, leaseId, action, signal) => Promise<BinaryResult | null>;
+}>;
+```
+
+`@fungi.computer/oyster/browser`: the one agent browser for the Hub and a
+standalone Oyster. A host builds the port from a provider (`browserRunSessions`
+or `bindingSessions`, plus Browser Run Quick Reads when it has them), its
+required metering owner and an event sink; `createBrowser` owns lease ownership,
+egress policy and billing order; `browserCapabilitySource` is the agent's
+`cloudBrowser` tool. Raw CDP stays internal to this directory.
+
+---
+
+### SaveBrowserFile
+
+```ts
+type SaveBrowserFile = (input) => Promise<
+  Readonly<{
+    computerId: string;
+    path: string;
+    bytes: number;
+  }>
+>;
+```
+
+The host's door for screenshot/PDF bytes: a named path on a Computer the Agent
+is attached to. The model only ever receives the saved byte count.
+
+#### Parameters
+
+| Parameter | Type                                                                                                          |
+| --------- | ------------------------------------------------------------------------------------------------------------- |
+| `input`   | `Readonly`\<\{ `computerId`: `string`; `path`: `string`; `bytes`: `Uint8Array`; `contentType`: `string`; \}\> |
+
+#### Returns
+
+`Promise`\<`Readonly`\<\{ `computerId`: `string`; `path`: `string`; `bytes`:
+`number`; \}\>\>
+
+---
+
+### AgentBrowserDoor
+
+```ts
+type AgentBrowserDoor = Readonly<{
+  call: (owner, op, signal) => Promise<CloudBrowserOperationResult>;
+  handoff: (owner, leaseId) => Promise<void>;
+}>;
+```
+
+The agent-facing slice of `Browser`, possibly behind a host RPC hop.
+
+---
+
+### CdpSocket
+
+```ts
+type CdpSocket = Readonly<{
+  send: (data) => void;
+  close: (code?, reason?) => void;
+  addEventListener: (type, listener) => void;
+}>;
+```
+
+The minimal WebSocket surface this client drives (a fake in tests). A real
+`WebSocket`'s `addEventListener` structurally satisfies this: the listener
+accepts any platform `Event` and `readCdpMessage` parses a message's `data`.
+
+---
+
+### HttpFetch
+
+```ts
+type HttpFetch = (url, init?) => Promise<Response>;
+```
+
+The one fetch shape the module calls: global `fetch` or a binding's.
+
+#### Parameters
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `url`     | `string`      |
+| `init?`   | `RequestInit` |
+
+#### Returns
+
+`Promise`\<`Response`\>
+
+---
+
+### CloudBrowserFailure
+
+```ts
+type CloudBrowserFailure =
+  | CloudBrowserUrlDenied
+  | CloudBrowserUpstreamError
+  | CloudBrowserTimeout
+  | CloudBrowserLeaseNotFound
+  | CloudBrowserLeasePaused
+  | CloudBrowserCapacityExceeded
+  | CloudBrowserCreditDenied
+  | CloudBrowserUnavailable;
+```
+
+Every typed failure the browser module throws; nothing else escapes it.
+
+---
+
+### LeaseOwner
+
+```ts
+type LeaseOwner = Readonly<{
+  teamId: string;
+  agentId: string;
+  sessionId: string;
+}>;
+```
+
+The one place that binds a cloud-browser lease to the (teamId, agentId,
+sessionId) that opened it, enforces the per-Team concurrent cap, and times
+leases out. The provider (`sessions.ts`) only knows CDP connections; it has no
+idea which Team or Session owns one. This registry is in-process (one Hub
+instance): see the report for why a durable, cross-instance counter (the
+`TeamDO`-backed shape Computer admission uses) is the better home for this
+long-term.
+
+---
+
+### MarkdownInput
+
+```ts
+type MarkdownInput = z.output<typeof markdownInputSchema>;
+```
+
+Parsed `markdown` input.
+
+---
+
+### MarkdownResult
+
+```ts
+type MarkdownResult = z.output<typeof markdownResultSchema>;
+```
+
+Parsed `markdown` output.
+
+---
+
+### LinksResult
+
+```ts
+type LinksResult = z.output<typeof linksResultSchema>;
+```
+
+Parsed `links` output.
+
+---
+
+### ScrapeInput
+
+```ts
+type ScrapeInput = z.output<typeof scrapeInputSchema>;
+```
+
+Parsed `scrape` input.
+
+---
+
+### ScrapeResult
+
+```ts
+type ScrapeResult = z.output<typeof scrapeResultSchema>;
+```
+
+Parsed `scrape` output.
+
+---
+
+### ExtractInput
+
+```ts
+type ExtractInput = z.output<typeof extractInputSchema>;
+```
+
+Parsed `extract` input.
+
+---
+
+### ExtractResult
+
+```ts
+type ExtractResult = z.output<typeof extractResultSchema>;
+```
+
+Parsed `extract` output.
+
+---
+
+### OpenResult
+
+```ts
+type OpenResult = z.output<typeof openResultSchema>;
+```
+
+Parsed `open` output.
+
+---
+
+### NavigateResult
+
+```ts
+type NavigateResult = z.output<typeof navigateResultSchema>;
+```
+
+Parsed `navigate` output.
+
+---
+
+### SnapshotResult
+
+```ts
+type SnapshotResult = z.output<typeof snapshotResultSchema>;
+```
+
+Parsed `snapshot` output.
+
+---
+
+### BinaryResult
+
+```ts
+type BinaryResult = Readonly<{
+  leaseId: string;
+  bytes: Uint8Array;
+  contentType: string;
+}>;
+```
+
+Raw bytes never cross the Mycelium boundary; only a byte count does.
+
+---
+
+### CloudBrowserOperation
+
+```ts
+type CloudBrowserOperation =
+  | Readonly<{
+      kind: "markdown";
+      input: MarkdownInput;
+    }>
+  | Readonly<{
+      kind: "links";
+      url: string;
+    }>
+  | Readonly<{
+      kind: "scrape";
+      input: ScrapeInput;
+    }>
+  | Readonly<{
+      kind: "extract";
+      input: ExtractInput;
+    }>
+  | Readonly<{
+      kind: "open";
+      url: string | null;
+    }>
+  | Readonly<{
+      kind: "navigate";
+      leaseId: string;
+      url: string;
+    }>
+  | Readonly<{
+      kind: "snapshot";
+      leaseId: string;
+    }>
+  | Readonly<{
+      kind: "click";
+      leaseId: string;
+      x: number;
+      y: number;
+    }>
+  | Readonly<{
+      kind: "type";
+      leaseId: string;
+      text: string;
+    }>
+  | Readonly<{
+      kind: "press";
+      leaseId: string;
+      key: string;
+    }>
+  | Readonly<{
+      kind: "scroll";
+      leaseId: string;
+      deltaX: number;
+      deltaY: number;
+    }>
+  | Readonly<{
+      kind: "screenshot";
+      leaseId: string;
+    }>
+  | Readonly<{
+      kind: "pdf";
+      leaseId: string;
+    }>
+  | Readonly<{
+      kind: "close";
+      leaseId: string;
+    }>;
+```
+
+Every call the agent tool can make. `markdown`/`links`/`scrape`/`extract` are
+stateless Quick Reads (absent on a host without them); `open`..`close` share one
+driven session keyed by `leaseId`. "screenshot"/"pdf" return raw bytes here;
+`capability-source.ts` saves them through the host's door and hands the model
+only a byte count.
+
+---
+
+### CloudBrowserAck
+
+```ts
+type CloudBrowserAck = Readonly<{
+  leaseId: string;
+}>;
+```
+
+Acknowledgement of one driven input step.
+
+---
+
+### CloudBrowserClosed
+
+```ts
+type CloudBrowserClosed = Readonly<{
+  leaseId: string;
+  closed: true;
+  provider: "closed" | "closing";
+}>;
+```
+
+Acknowledgement that a lease closed.
+
+---
+
+### CloudBrowserOperationResult
+
+```ts
+type CloudBrowserOperationResult =
+  | MarkdownResult
+  | LinksResult
+  | ScrapeResult
+  | ExtractResult
+  | OpenResult
+  | NavigateResult
+  | SnapshotResult
+  | CloudBrowserAck
+  | BinaryResult
+  | CloudBrowserClosed;
+```
+
+What one `CloudBrowserOperation` returns, before the agent tool shapes it.
+
+---
+
+### BrowserRunQuickReadsConfig
+
+```ts
+type BrowserRunQuickReadsConfig = Readonly<{
+  accountId: string;
+  apiToken: string;
+  fetch?: HttpFetch;
+}>;
+```
+
+The Browser Run account and API token a host's Quick Reads use.
+
+---
+
+### QuickRead
+
+```ts
+type QuickRead<Result> = Readonly<{
+  result: Result;
+  browserMs: number | null;
+}>;
+```
+
+A read's result and the browser time the provider reports for it, if any.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Result`       |
+
+---
+
+### QuickReads
+
+```ts
+type QuickReads = Readonly<{
+  markdown: (url, maxChars, signal) => Promise<QuickRead<MarkdownResult>>;
+  links: (url, signal) => Promise<QuickRead<LinksResult>>;
+  scrape: (url, selectors, signal) => Promise<QuickRead<ScrapeResult>>;
+  extract: (url, prompt, signal) => Promise<QuickRead<ExtractResult>>;
+}>;
+```
+
+The stateless half of the host port; only `browserRunQuickReads` builds one. The
+caller (`browser.ts`) owns the deadline through `signal`.
+
+---
+
+### BrowserSessions
+
+```ts
+type BrowserSessions = Readonly<{}>;
+```
+
+The provider half of the host port. Built only by the two functions below. Each
+step is separate so `createBrowser` owns a provider session id from the moment
+it exists, including when its CDP connect then fails.
+
+---
+
+### BrowserBinding
+
+```ts
+type BrowserBinding = Readonly<{
+  fetch: HttpFetch;
+}>;
+```
+
+A Workers BROWSER binding (`Fetcher`), reduced to the call this module makes.
+
+---
+
+### CdpConnect
+
+```ts
+type CdpConnect = (url, headers, signal) => Promise<CdpSocket>;
+```
+
+Opens the CDP WebSocket for one provider session URL.
+
+#### Parameters
+
+| Parameter | Type                                         |
+| --------- | -------------------------------------------- |
+| `url`     | `string`                                     |
+| `headers` | `Readonly`\<`Record`\<`string`, `string`\>\> |
+| `signal`  | `AbortSignal`                                |
+
+#### Returns
+
+`Promise`\<[`CdpSocket`](#cdpsocket)\>
+
+## Variables
+
+### CLOUD\_BROWSER\_DESCRIPTIONS
+
+```ts
+const CLOUD_BROWSER_DESCRIPTIONS: Readonly<{
+  module: string;
+  markdown: "Render a JavaScript page and return it as markdown, truncated to maxChars (default 20000).";
+  links: "Render a page and return up to 500 links found on it.";
+  scrape: "Render a page and return matched elements for up to 10 CSS selectors, bounded to 64 KiB.";
+  extract: "Render a page and extract structured data matching a prompt.";
+  open: "Open a driven browser session, optionally navigating to a URL, and return its leaseId.";
+  navigate: "Navigate an open session's page to a URL.";
+  snapshot: "Read an open session's page as a bounded accessibility-tree text summary.";
+  click: "Click at a viewport pixel coordinate in an open session.";
+  type: "Insert text at the current focus in an open session.";
+  press: 'Press one key (e.g. "Enter", "Tab") in an open session.';
+  scroll: "Scroll an open session's page by a pixel delta.";
+  screenshot: "Capture a PNG screenshot of an open session's page and save it to a Computer path; returns the saved byte count, never the bytes.";
+  pdf: "Render an open session's page to PDF and save it to a Computer path; returns the saved byte count, never the bytes.";
+  handoff: "Ask a Team member to take over an open session for a login or captcha; a card appears in the conversation and the run continues once they finish.";
+  close: "End a driven session and release its lease.";
+}>;
+```
+
+The one source of truth for every `cloudBrowser` description: the module itself
+and each operation. `cloud-browser-descriptions.test.ts` imports this and
+asserts every entry stays under 1000 characters (the acceptance criterion in
+`issues/retained-features-v1/02-*.md`); the guard right below repeats that check
+at import time so a regression fails fast either way.
+
+---
+
+### cloudBrowserBounds
+
+```ts
+const cloudBrowserBounds: Readonly<{
+  maxChars: 50000;
+  defaultMarkdownChars: 20000;
+  maxLinks: 500;
+  maxSelectors: 10;
+  maxScrapeBytes: number;
+  maxSnapshotBytes: number;
+  maxScreenshotBytes: number;
+  maxPdfBytes: number;
+}>;
+```
+
+The module's fixed output bounds (characters, links, selectors, bytes).
+
+---
+
+### markdownInputSchema
+
+```ts
+const markdownInputSchema: ZodObject<
+  {
+    url: ZodURL;
+    maxChars: ZodDefault<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+Input of `markdown`: a URL and a character bound.
+
+---
+
+### markdownResultSchema
+
+```ts
+const markdownResultSchema: ZodObject<
+  {
+    url: ZodString;
+    text: ZodString;
+    truncated: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Output of `markdown`: the page text, possibly truncated.
+
+---
+
+### linksResultSchema
+
+```ts
+const linksResultSchema: ZodObject<
+  {
+    url: ZodString;
+    links: ZodArray<ZodString>;
+    truncated: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Output of `links`: bare URL strings, bounded.
+
+---
+
+### scrapeInputSchema
+
+```ts
+const scrapeInputSchema: ZodObject<
+  {
+    url: ZodURL;
+    selectors: ZodArray<ZodString>;
+  },
+  $strict
+>;
+```
+
+Input of `scrape`: a URL and up to ten CSS selectors.
+
+---
+
+### scrapeResultSchema
+
+```ts
+const scrapeResultSchema: ZodObject<
+  {
+    url: ZodString;
+    result: ZodArray<
+      ZodObject<
+        {
+          selector: ZodString;
+          elements: ZodArray<
+            ZodObject<
+              {
+                text: ZodString;
+                html: ZodString;
+              },
+              $strict
+            >
+          >;
+        },
+        $strict
+      >
+    >;
+    truncated: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Output of `scrape`: matched elements per selector, bounded.
+
+---
+
+### extractInputSchema
+
+```ts
+const extractInputSchema: ZodObject<
+  {
+    url: ZodURL;
+    prompt: ZodString;
+  },
+  $strict
+>;
+```
+
+Input of `extract`: a URL and a prompt.
+
+---
+
+### extractResultSchema
+
+```ts
+const extractResultSchema: ZodObject<
+  {
+    url: ZodString;
+    result: ZodJSONSchema;
+  },
+  $strict
+>;
+```
+
+Output of `extract`: JSON-safe structured data.
+
+---
+
+### openResultSchema
+
+```ts
+const openResultSchema: ZodObject<
+  {
+    leaseId: ZodString;
+    url: ZodNullable<ZodString>;
+  },
+  $strict
+>;
+```
+
+Output of `open`: the new lease and its first URL.
+
+---
+
+### navigateResultSchema
+
+```ts
+const navigateResultSchema: ZodObject<
+  {
+    leaseId: ZodString;
+    url: ZodString;
+    status: ZodNullable<ZodNumber>;
+    title: ZodNullable<ZodString>;
+  },
+  $strict
+>;
+```
+
+Output of `navigate`: the page's location after load.
+
+---
+
+### snapshotResultSchema
+
+```ts
+const snapshotResultSchema: ZodObject<
+  {
+    leaseId: ZodString;
+    tree: ZodString;
+    truncated: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Output of `snapshot`: a bounded accessibility-tree summary.
+
+## Functions
+
+### createBrowser()
+
+```ts
+function createBrowser(host, limits): Browser;
+```
+
+`@fungi.computer/oyster/browser`: the one agent browser for the Hub and a
+standalone Oyster. A host builds the port from a provider (`browserRunSessions`
+or `bindingSessions`, plus Browser Run Quick Reads when it has them), its
+required metering owner and an event sink; `createBrowser` owns lease ownership,
+egress policy and billing order; `browserCapabilitySource` is the agent's
+`cloudBrowser` tool. Raw CDP stays internal to this directory.
+
+#### Parameters
+
+| Parameter | Type                              |
+| --------- | --------------------------------- |
+| `host`    | [`BrowserHost`](#browserhost)     |
+| `limits`  | [`BrowserLimits`](#browserlimits) |
+
+#### Returns
+
+[`Browser`](#browser)
+
+---
+
+### browserCapabilitySource()
+
+```ts
+function browserCapabilitySource(deps): CapabilitySource;
+```
+
+Compose the `cloudBrowser` source for one Session, on either host. `browser` is
+the module's lease door (in-process, or the Hub's egress RPC); `saveFile` is the
+host's Computer bytes writer and `requestHandoff` its "needs you" card. A host
+without one passes `null` and the matching operations are not offered. A lease
+needs a Session identity, so a session-free host (e.g. the MCP execute path)
+gets no module at all.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                        |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deps`    | `Readonly`\<\{ `identity`: () => \| `Readonly`\<\{ `teamId`: `string`; `agentId`: `string`; \}\> \| `null`; `browser`: [`AgentBrowserDoor`](#agentbrowserdoor); `quickReads`: `boolean`; `saveFile`: [`SaveBrowserFile`](#savebrowserfile) \| `null`; `requestHandoff`: ((`sessionId`, `reason`) => `void`) \| `null`; \}\> |
+
+#### Returns
+
+`CapabilitySource`
+
+---
+
+### browserRunQuickReads()
+
+```ts
+function browserRunQuickReads(config): QuickReads;
+```
+
+Browser Run's REST Quick Actions as a host's `QuickReads`.
+
+#### Parameters
+
+| Parameter | Type                                                        |
+| --------- | ----------------------------------------------------------- |
+| `config`  | [`BrowserRunQuickReadsConfig`](#browserrunquickreadsconfig) |
+
+#### Returns
+
+[`QuickReads`](#quickreads)
+
+---
+
+### browserRunSessions()
+
+```ts
+function browserRunSessions(config): BrowserSessions;
+```
+
+Cloudflare Browser Run over REST with an account token (Hub, any celld host).
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                           |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `config`  | `Readonly`\<\{ `accountId`: `string`; `apiToken`: `string`; `fetch?`: [`HttpFetch`](#httpfetch); `connect?`: [`CdpConnect`](#cdpconnect); \}\> |
+
+#### Returns
+
+[`BrowserSessions`](#browsersessions)
+
+---
+
+### bindingSessions()
+
+```ts
+function bindingSessions(binding): BrowserSessions;
+```
+
+A standalone Oyster's own Workers BROWSER binding.
+
+#### Parameters
+
+| Parameter | Type                                |
+| --------- | ----------------------------------- |
+| `binding` | [`BrowserBinding`](#browserbinding) |
+
+#### Returns
+
+[`BrowserSessions`](#browsersessions)