browser

Exports

Kind	Export	Description
Cclass	CloudBrowserUrlDenied	The target URL failed policy before any provider call was made.
Cclass	CloudBrowserUpstreamError	The configured provider answered with a failure or is unreachable.
Cclass	CloudBrowserTimeout	A call did not complete within its deadline.
Cclass	CloudBrowserLeaseNotFound	The named lease is not held by this (teamId, agentId, sessionId).
Cclass	CloudBrowserLeasePaused	A member was asked to take over; the Agent cannot drive it until “Done”.
Cclass	CloudBrowserCapacityExceeded	The Team has no more concurrent leases available right now.
Cclass	CloudBrowserCreditDenied	The Team has no credit to start or continue a lease.
Cclass	CloudBrowserUnavailable	No backend is configured (credentials absent, or the feature is paused).
Ttype alias	BrowserMeter	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.
Ttype alias	BrowserEvent	Code-only observations; never a URL, page text, token or provider body.
Ttype alias	BrowserHost	The ONE host port for config, billing and provider egress.
Ttype alias	BrowserLimits	@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 or onboxBrowserSessions on staging, 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.
Ttype alias	BrowserMemberAction	What a Team member may do to a lease an Agent handed off.
Ttype alias	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 or onboxBrowserSessions on staging, 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.
Ttype alias	SaveBrowserFile	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.
Ttype alias	AgentBrowserDoor	The agent-facing slice of Browser, possibly behind a host RPC hop.
Ttype alias	CdpSocket	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.
Ttype alias	HttpFetch	The one fetch shape the module calls: global fetch or a binding’s.
Ttype alias	CloudBrowserFailure	Every typed failure the browser module throws; nothing else escapes it.
Ttype alias	LeaseOwner	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.
Ttype alias	MarkdownInput	Parsed markdown input.
Ttype alias	MarkdownResult	Parsed markdown output.
Ttype alias	LinksResult	Parsed links output.
Ttype alias	ScrapeInput	Parsed scrape input.
Ttype alias	ScrapeResult	Parsed scrape output.
Ttype alias	ExtractInput	Parsed extract input.
Ttype alias	ExtractResult	Parsed extract output.
Ttype alias	OpenResult	Parsed open output.
Ttype alias	NavigateResult	Parsed navigate output.
Ttype alias	SnapshotResult	Parsed snapshot output.
Ttype alias	BinaryResult	Raw bytes never cross the Mycelium boundary; only a byte count does.
Ttype alias	CloudBrowserOperation	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.
Ttype alias	CloudBrowserAck	Acknowledgement of one driven input step.
Ttype alias	CloudBrowserClosed	Acknowledgement that a lease closed.
Ttype alias	CloudBrowserOperationResult	What one CloudBrowserOperation returns, before the agent tool shapes it.
Ttype alias	BrowserRunQuickReadsConfig	The Browser Run account and API token a host’s Quick Reads use.
Ttype alias	QuickRead	A read’s result and the browser time the provider reports for it, if any.
Ttype alias	QuickReads	The stateless half of the host port; only browserRunQuickReads builds one. The caller (browser.ts) owns the deadline through signal.
Ttype alias	BrowserSessions	The provider half of the host port. Each step is separate so createBrowser owns a provider session id from the moment it exists, including when its CDP connect then fails.
Ttype alias	BrowserBinding	A Workers BROWSER binding (Fetcher), reduced to the call this module makes.
Ttype alias	CdpConnect	Opens the CDP WebSocket for one provider session URL.
constconstant	CLOUD_BROWSER_DESCRIPTIONS	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.
constconstant	cloudBrowserBounds	The module’s fixed output bounds (characters, links, selectors, bytes).
constconstant	markdownInputSchema	Input of markdown: a URL and a character bound.
constconstant	markdownResultSchema	Output of markdown: the page text, possibly truncated.
constconstant	linksResultSchema	Output of links: bare URL strings, bounded.
constconstant	scrapeInputSchema	Input of scrape: a URL and up to ten CSS selectors.
constconstant	scrapeResultSchema	Output of scrape: matched elements per selector, bounded.
constconstant	extractInputSchema	Input of extract: a URL and a prompt.
constconstant	extractResultSchema	Output of extract: JSON-safe structured data.
constconstant	openResultSchema	Output of open: the new lease and its first URL.
constconstant	navigateResultSchema	Output of navigate: the page’s location after load.
constconstant	snapshotResultSchema	Output of snapshot: a bounded accessibility-tree summary.
fnfunction	createBrowser()	@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 or onboxBrowserSessions on staging, 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.
fnfunction	browserCapabilitySource()	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.
fnfunction	browserRunQuickReads()	Browser Run’s REST Quick Actions as a host’s QuickReads.
fnfunction	browserRunSessions()	Cloudflare Browser Run over REST with an account token (Hub, any celld host).
fnfunction	bindingSessions()	A standalone Oyster’s own Workers BROWSER binding.
fnfunction	onboxBrowserSessions()	Staging uses Chromium’s native CDP browser contexts; no session store.

CloudBrowserUrlDeniedCclass

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

Signature

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

Inherited from

Signature

Data.TaggedError(
  "CloudBrowserUrlDenied",
)<{
  readonly reason:
    | "invalid_url"
    | "unsupported_scheme"
    | "credentials_in_url"
    | "not_public"
    | "dns_unavailable";
  readonly message: string;
}>.constructor

Properties

reason

Signature

readonly reason:
  | "invalid_url"
  | "unsupported_scheme"
  | "credentials_in_url"
  | "not_public"
  | "dns_unavailable";

Inherited from

Signature

Data.TaggedError("CloudBrowserUrlDenied").reason;

message

Signature

message: string;

Inherited from

Signature

Data.TaggedError("CloudBrowserUrlDenied").message;

---

CloudBrowserUpstreamErrorCclass

The configured provider answered with a failure or is unreachable.

Extends

• YieldableError<this> & object & Readonly<{ op: string; status: number | null; message: string; }>

Constructors

Constructor

Signature

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

Inherited from

Signature

Data.TaggedError(
  "CloudBrowserUpstreamError",
)<{
  readonly op: string;
  readonly status: number | null;
  readonly message: string;
}>.constructor

Properties

op

Signature

readonly op: string;

Inherited from

Signature

Data.TaggedError("CloudBrowserUpstreamError").op;

status

Signature

readonly status: number | null;

Inherited from

Signature

Data.TaggedError("CloudBrowserUpstreamError").status;

message

Signature

message: string;

Inherited from

Signature

Data.TaggedError("CloudBrowserUpstreamError").message;

---

CloudBrowserTimeoutCclass

A call did not complete within its deadline.

Extends

• YieldableError<this> & object & Readonly<{ op: string; timeoutMs: number; }>

Constructors

Constructor

Signature

new CloudBrowserTimeout(args): CloudBrowserTimeout;

Parameters

Parameter	Type
args	{ op: string; timeoutMs: number; }
args.op	string
args.timeoutMs	number

Returns

CloudBrowserTimeout

Inherited from

Signature

Data.TaggedError(
  "CloudBrowserTimeout",
)<{
  readonly op: string;
  readonly timeoutMs: number;
}>.constructor

Properties

op

Signature

readonly op: string;

Inherited from

Signature

Data.TaggedError("CloudBrowserTimeout").op;

timeoutMs

Signature

readonly timeoutMs: number;

Inherited from

Signature

Data.TaggedError("CloudBrowserTimeout").timeoutMs;

---

CloudBrowserLeaseNotFoundCclass

The named lease is not held by this (teamId, agentId, sessionId).

Extends

• YieldableError<this> & object & Readonly<{ leaseId: string; }>

Constructors

Constructor

Signature

new CloudBrowserLeaseNotFound(args): CloudBrowserLeaseNotFound;

Parameters

Parameter	Type
args	{ leaseId: string; }
args.leaseId	string

Returns

CloudBrowserLeaseNotFound

Inherited from

Signature

Data.TaggedError(
  "CloudBrowserLeaseNotFound",
)<{
  readonly leaseId: string;
}>.constructor

Properties

leaseId

Signature

readonly leaseId: string;

Inherited from

Signature

Data.TaggedError("CloudBrowserLeaseNotFound").leaseId;

---

CloudBrowserLeasePausedCclass

A member was asked to take over; the Agent cannot drive it until “Done”.

Extends

• YieldableError<this> & object & Readonly<{ leaseId: string; }>

Constructors

Constructor

Signature

new CloudBrowserLeasePaused(args): CloudBrowserLeasePaused;

Parameters

Parameter	Type
args	{ leaseId: string; }
args.leaseId	string

Returns

CloudBrowserLeasePaused

Inherited from

Signature

Data.TaggedError(
  "CloudBrowserLeasePaused",
)<{
  readonly leaseId: string;
}>.constructor

Properties

leaseId

Signature

readonly leaseId: string;

Inherited from

Signature

Data.TaggedError("CloudBrowserLeasePaused").leaseId;

---

CloudBrowserCapacityExceededCclass

The Team has no more concurrent leases available right now.

Extends

• YieldableError<this> & object & Readonly<{ teamId: string; limit: number; }>

Constructors

Constructor

Signature

new CloudBrowserCapacityExceeded(args): CloudBrowserCapacityExceeded;

Parameters

Parameter	Type
args	{ teamId: string; limit: number; }
args.teamId	string
args.limit	number

Returns

CloudBrowserCapacityExceeded

Inherited from

Signature

Data.TaggedError(
  "CloudBrowserCapacityExceeded",
)<{
  readonly teamId: string;
  readonly limit: number;
}>.constructor

Properties

teamId

Signature

readonly teamId: string;

Inherited from

Signature

Data.TaggedError("CloudBrowserCapacityExceeded").teamId;

limit

Signature

readonly limit: number;

Inherited from

Signature

Data.TaggedError("CloudBrowserCapacityExceeded").limit;

---

CloudBrowserCreditDeniedCclass

The Team has no credit to start or continue a lease.

Extends

• YieldableError<this> & object & Readonly<{ teamId: string; }>

Constructors

Constructor

Signature

new CloudBrowserCreditDenied(args): CloudBrowserCreditDenied;

Parameters

Parameter	Type
args	{ teamId: string; }
args.teamId	string

Returns

CloudBrowserCreditDenied

Inherited from

Signature

Data.TaggedError(
  "CloudBrowserCreditDenied",
)<{
  readonly teamId: string;
}>.constructor

Properties

teamId

Signature

readonly teamId: string;

Inherited from

Signature

Data.TaggedError("CloudBrowserCreditDenied").teamId;

---

CloudBrowserUnavailableCclass

No backend is configured (credentials absent, or the feature is paused).

Extends

• YieldableError<this> & object & Readonly<{ reason: "paused" | "unconfigured"; }>

Constructors

Constructor

Signature

new CloudBrowserUnavailable(args): CloudBrowserUnavailable;

Parameters

Parameter	Type
args	{ reason: "paused" | "unconfigured"; }
args.reason	"paused" | "unconfigured"

Returns

CloudBrowserUnavailable

Inherited from

Signature

Data.TaggedError(
  "CloudBrowserUnavailable",
)<{
  readonly reason: "unconfigured" | "paused";
}>.constructor

Properties

reason

Signature

readonly reason: "paused" | "unconfigured";

Inherited from

Signature

Data.TaggedError("CloudBrowserUnavailable").reason;

BrowserMeterTtype alias

Signature

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.

---

BrowserEventTtype alias

Signature

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.

---

BrowserHostTtype alias

Signature

type BrowserHost = Readonly<{
  sessions: BrowserSessions;
  quickReads: QuickReads | null;
  meter: (owner) => BrowserMeter;
  report: (event) => void;
}>;

The ONE host port for config, billing and provider egress.

---

BrowserLimitsTtype alias

Signature

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 or onboxBrowserSessions on staging, 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.

---

BrowserMemberActionTtype alias

Signature

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.

---

BrowserTtype alias

Signature

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 or onboxBrowserSessions on staging, 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.

---

SaveBrowserFileTtype alias

Signature

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; }>>

---

AgentBrowserDoorTtype alias

Signature

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.

---

CdpSocketTtype alias

Signature

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.

---

HttpFetchTtype alias

Signature

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>

---

CloudBrowserFailureTtype alias

Signature

type CloudBrowserFailure =
  | CloudBrowserUrlDenied
  | CloudBrowserUpstreamError
  | CloudBrowserTimeout
  | CloudBrowserLeaseNotFound
  | CloudBrowserLeasePaused
  | CloudBrowserCapacityExceeded
  | CloudBrowserCreditDenied
  | CloudBrowserUnavailable;

Every typed failure the browser module throws; nothing else escapes it.

---

LeaseOwnerTtype alias

Signature

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.

---

MarkdownInputTtype alias

Signature

type MarkdownInput = z.output<typeof markdownInputSchema>;

Parsed markdown input.

---

MarkdownResultTtype alias

Signature

type MarkdownResult = z.output<typeof markdownResultSchema>;

Parsed markdown output.

---

LinksResultTtype alias

Signature

type LinksResult = z.output<typeof linksResultSchema>;

Parsed links output.

---

ScrapeInputTtype alias

Signature

type ScrapeInput = z.output<typeof scrapeInputSchema>;

Parsed scrape input.

---

ScrapeResultTtype alias

Signature

type ScrapeResult = z.output<typeof scrapeResultSchema>;

Parsed scrape output.

---

ExtractInputTtype alias

Signature

type ExtractInput = z.output<typeof extractInputSchema>;

Parsed extract input.

---

ExtractResultTtype alias

Signature

type ExtractResult = z.output<typeof extractResultSchema>;

Parsed extract output.

---

OpenResultTtype alias

Signature

type OpenResult = z.output<typeof openResultSchema>;

Parsed open output.

---

NavigateResultTtype alias

Signature

type NavigateResult = z.output<typeof navigateResultSchema>;

Parsed navigate output.

---

SnapshotResultTtype alias

Signature

type SnapshotResult = z.output<typeof snapshotResultSchema>;

Parsed snapshot output.

---

BinaryResultTtype alias

Signature

type BinaryResult = Readonly<{
  leaseId: string;
  bytes: Uint8Array;
  contentType: string;
}>;

Raw bytes never cross the Mycelium boundary; only a byte count does.

---

CloudBrowserOperationTtype alias

Signature

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.

---

CloudBrowserAckTtype alias

Signature

type CloudBrowserAck = Readonly<{
  leaseId: string;
}>;

Acknowledgement of one driven input step.

---

CloudBrowserClosedTtype alias

Signature

type CloudBrowserClosed = Readonly<{
  leaseId: string;
  closed: true;
  provider: "closed" | "closing";
}>;

Acknowledgement that a lease closed.

---

CloudBrowserOperationResultTtype alias

Signature

type CloudBrowserOperationResult =
  | MarkdownResult
  | LinksResult
  | ScrapeResult
  | ExtractResult
  | OpenResult
  | NavigateResult
  | SnapshotResult
  | CloudBrowserAck
  | BinaryResult
  | CloudBrowserClosed;

What one CloudBrowserOperation returns, before the agent tool shapes it.

---

BrowserRunQuickReadsConfigTtype alias

Signature

type BrowserRunQuickReadsConfig = Readonly<{
  accountId: string;
  apiToken: string;
  fetch?: HttpFetch;
}>;

The Browser Run account and API token a host’s Quick Reads use.

---

QuickReadTtype alias

Signature

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

---

QuickReadsTtype alias

Signature

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.

---

BrowserSessionsTtype alias

Signature

type BrowserSessions = Readonly<{}>;

The provider half of the host port. Each step is separate so createBrowser owns a provider session id from the moment it exists, including when its CDP connect then fails.

---

BrowserBindingTtype alias

Signature

type BrowserBinding = Readonly<{
  fetch: HttpFetch;
}>;

A Workers BROWSER binding (Fetcher), reduced to the call this module makes.

---

CdpConnectTtype alias

Signature

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>

CLOUD_BROWSER_DESCRIPTIONSconstconstant

Signature

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.

---

cloudBrowserBoundsconstconstant

Signature

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).

---

markdownInputSchemaconstconstant

Signature

const markdownInputSchema: ZodObject<
  {
    url: ZodURL;
    maxChars: ZodDefault<ZodNumber>;
  },
  $strict
>;

Input of markdown: a URL and a character bound.

---

markdownResultSchemaconstconstant

Signature

const markdownResultSchema: ZodObject<
  {
    url: ZodString;
    text: ZodString;
    truncated: ZodBoolean;
  },
  $strict
>;

Output of markdown: the page text, possibly truncated.

---

linksResultSchemaconstconstant

Signature

const linksResultSchema: ZodObject<
  {
    url: ZodString;
    links: ZodArray<ZodString>;
    truncated: ZodBoolean;
  },
  $strict
>;

Output of links: bare URL strings, bounded.

---

scrapeInputSchemaconstconstant

Signature

const scrapeInputSchema: ZodObject<
  {
    url: ZodURL;
    selectors: ZodArray<ZodString>;
  },
  $strict
>;

Input of scrape: a URL and up to ten CSS selectors.

---

scrapeResultSchemaconstconstant

Signature

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.

---

extractInputSchemaconstconstant

Signature

const extractInputSchema: ZodObject<
  {
    url: ZodURL;
    prompt: ZodString;
  },
  $strict
>;

Input of extract: a URL and a prompt.

---

extractResultSchemaconstconstant

Signature

const extractResultSchema: ZodObject<
  {
    url: ZodString;
    result: ZodJSONSchema;
  },
  $strict
>;

Output of extract: JSON-safe structured data.

---

openResultSchemaconstconstant

Signature

const openResultSchema: ZodObject<
  {
    leaseId: ZodString;
    url: ZodNullable<ZodString>;
  },
  $strict
>;

Output of open: the new lease and its first URL.

---

navigateResultSchemaconstconstant

Signature

const navigateResultSchema: ZodObject<
  {
    leaseId: ZodString;
    url: ZodString;
    status: ZodNullable<ZodNumber>;
    title: ZodNullable<ZodString>;
  },
  $strict
>;

Output of navigate: the page’s location after load.

---

snapshotResultSchemaconstconstant

Signature

const snapshotResultSchema: ZodObject<
  {
    leaseId: ZodString;
    tree: ZodString;
    truncated: ZodBoolean;
  },
  $strict
>;

Output of snapshot: a bounded accessibility-tree summary.

createBrowser()fnfunction

Signature

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 or onboxBrowserSessions on staging, 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
limits	BrowserLimits

Returns

Browser

---

browserCapabilitySource()fnfunction

Signature

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; quickReads: boolean; saveFile: SaveBrowserFile | null; requestHandoff: ((sessionId, reason) => void) | null; }>

Returns

CapabilitySource

---

browserRunQuickReads()fnfunction

Signature

function browserRunQuickReads(config): QuickReads;

Browser Run’s REST Quick Actions as a host’s QuickReads.

Parameters

Parameter	Type
config	BrowserRunQuickReadsConfig

Returns

QuickReads

---

browserRunSessions()fnfunction

Signature

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; connect?: CdpConnect; }>

Returns

BrowserSessions

---

bindingSessions()fnfunction

Signature

function bindingSessions(binding): BrowserSessions;

A standalone Oyster’s own Workers BROWSER binding.

Parameters

Parameter	Type
binding	BrowserBinding

Returns

BrowserSessions

---

onboxBrowserSessions()fnfunction

Signature

function onboxBrowserSessions(origin, fetcher?): BrowserSessions;

Staging uses Chromium’s native CDP browser contexts; no session store.

Parameters

Parameter	Type
origin	string
fetcher	HttpFetch

Returns

BrowserSessions