@fungi.computer/oyster 0.2.0 → 0.3.0

package/dist/browser/errors.js

@@ -0,0 +1,32 @@
+import * as Data from "effect/Data";
+/**
+ * The cloud-browser backend's closed, typed failure channel. Every backend
+ * (today only Cloudflare Browser Run) throws exclusively from this union;
+ * `agent-cloud-browser-source.ts` is the one place that maps it onto
+ * Mycelium's `CapabilityFailed`, so the model only ever sees a bounded,
+ * owner-admitted message (never a raw provider error body or stack).
+ */
+/** The target URL failed policy before any provider call was made. */
+export class CloudBrowserUrlDenied extends Data.TaggedError("CloudBrowserUrlDenied") {
+}
+/** The provider (Cloudflare Browser Run) answered with a failure. */
+export class CloudBrowserUpstreamError extends Data.TaggedError("CloudBrowserUpstreamError") {
+}
+/** A call did not complete within its deadline. */
+export class CloudBrowserTimeout extends Data.TaggedError("CloudBrowserTimeout") {
+}
+/** The named lease is not held by this (teamId, agentId, sessionId). */
+export class CloudBrowserLeaseNotFound extends Data.TaggedError("CloudBrowserLeaseNotFound") {
+}
+/** A member was asked to take over; the Agent cannot drive it until "Done". */
+export class CloudBrowserLeasePaused extends Data.TaggedError("CloudBrowserLeasePaused") {
+}
+/** The Team has no more concurrent leases available right now. */
+export class CloudBrowserCapacityExceeded extends Data.TaggedError("CloudBrowserCapacityExceeded") {
+}
+/** The Team has no credit to start or continue a lease. */
+export class CloudBrowserCreditDenied extends Data.TaggedError("CloudBrowserCreditDenied") {
+}
+/** No backend is configured (credentials absent, or the feature is paused). */
+export class CloudBrowserUnavailable extends Data.TaggedError("CloudBrowserUnavailable") {
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@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.
+ */
+export { createBrowser, type Browser, type BrowserEvent, type BrowserHost, type BrowserLimits, type BrowserMemberAction, type BrowserMeter, } from "./browser.js";
+export { browserCapabilitySource, CLOUD_BROWSER_DESCRIPTIONS, type AgentBrowserDoor, type SaveBrowserFile, } from "./capability-source.js";
+export { CloudBrowserCapacityExceeded, CloudBrowserCreditDenied, CloudBrowserLeaseNotFound, CloudBrowserLeasePaused, CloudBrowserTimeout, CloudBrowserUnavailable, CloudBrowserUpstreamError, CloudBrowserUrlDenied, type CloudBrowserFailure, } from "./errors.js";
+export type { LeaseOwner } from "./lease-registry.js";
+export { cloudBrowserBounds, extractInputSchema, extractResultSchema, linksResultSchema, markdownInputSchema, markdownResultSchema, navigateResultSchema, openResultSchema, scrapeInputSchema, scrapeResultSchema, snapshotResultSchema, type BinaryResult, type CloudBrowserAck, type CloudBrowserClosed, type CloudBrowserOperation, type CloudBrowserOperationResult, type ExtractInput, type ExtractResult, type LinksResult, type MarkdownInput, type MarkdownResult, type NavigateResult, type OpenResult, type ScrapeInput, type ScrapeResult, type SnapshotResult, } from "./operations.js";
+export type { CdpSocket, HttpFetch } from "./cdp-client.js";
+export { browserRunQuickReads, type BrowserRunQuickReadsConfig, type QuickRead, type QuickReads, } from "./quick-reads.js";
+export { bindingSessions, browserRunSessions, type BrowserBinding, type BrowserSessions, type CdpConnect, } from "./sessions.js";

package/dist/browser/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@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.
+ */
+export { createBrowser, } from "./browser.js";
+export { browserCapabilitySource, CLOUD_BROWSER_DESCRIPTIONS, } from "./capability-source.js";
+export { CloudBrowserCapacityExceeded, CloudBrowserCreditDenied, CloudBrowserLeaseNotFound, CloudBrowserLeasePaused, CloudBrowserTimeout, CloudBrowserUnavailable, CloudBrowserUpstreamError, CloudBrowserUrlDenied, } from "./errors.js";
+export { cloudBrowserBounds, extractInputSchema, extractResultSchema, linksResultSchema, markdownInputSchema, markdownResultSchema, navigateResultSchema, openResultSchema, scrapeInputSchema, scrapeResultSchema, snapshotResultSchema, } from "./operations.js";
+export { browserRunQuickReads, } from "./quick-reads.js";
+export { bindingSessions, browserRunSessions, } from "./sessions.js";

package/dist/browser/lease-registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+export type LeaseOwner = Readonly<{
+    teamId: string;
+    agentId: string;
+    sessionId: string;
+}>;
+export type LeaseRecord = LeaseOwner & {
+    leaseId: string;
+    openedAt: number;
+    lastActiveAt: number;
+    /** Set by `cloudBrowser.handoff`; cleared when a member presses "Done". */
+    paused: boolean;
+};
+export type LeaseRegistryConfig = Readonly<{
+    /** Concurrent open leases one Team may hold. LIMIT DECISION PENDING (Levi). */
+    maxConcurrentPerTeam: number;
+    /** A lease older than this is reaped even if active. */
+    maxLifetimeMs: number;
+    /** A lease idle this long is reaped. */
+    idleTimeoutMs: number;
+    now?: () => number;
+}>;
+export type LeaseRegistry = Readonly<{
+    /**
+     * Reserve one of the Team's slots for an open still in flight. Throws
+     * `CloudBrowserCapacityExceeded` when registered leases plus reservations
+     * already fill the cap, so concurrent opens cannot overshoot it.
+     */
+    reserve: (leaseId: string, owner: LeaseOwner) => void;
+    /** Give back a reservation whose open failed. */
+    abandon: (leaseId: string) => void;
+    /** Turn a reservation into an open lease. */
+    /** `openedAt` is when the provider session was requested: lifetime and billing start there. */
+    register: (leaseId: string, owner: LeaseOwner, openedAt: number) => void;
+    /** Throws `CloudBrowserLeaseNotFound` for a wrong owner, unknown, or expired lease. */
+    touch: (leaseId: string, owner: LeaseOwner) => void;
+    release: (leaseId: string) => void;
+    /** Leases past their idle timeout or max lifetime, for a reap sweep. */
+    expired: () => readonly string[];
+    /** Read-only lookup, e.g. to bill a closing lease's real elapsed time. */
+    get: (leaseId: string) => Readonly<LeaseRecord> | undefined;
+    count: (teamId: string) => number;
+    /** `cloudBrowser.handoff`: the Agent cannot drive the lease until `resume`. */
+    pause: (leaseId: string) => void;
+    /** The member's "Done": the Agent may drive the lease again. */
+    resume: (leaseId: string, teamId: string) => void;
+    /**
+     * The live view's own admission: Team membership, not Agent identity.
+     * Throws `CloudBrowserLeaseNotFound` for a lease outside this Team.
+     */
+    touchAsMember: (leaseId: string, teamId: string) => void;
+}>;
+export declare function createLeaseRegistry(config: LeaseRegistryConfig): LeaseRegistry;

package/dist/browser/lease-registry.js

@@ -0,0 +1,101 @@
+import { CloudBrowserCapacityExceeded, CloudBrowserLeaseNotFound, CloudBrowserLeasePaused, } from "./errors.js";
+export function createLeaseRegistry(config) {
+    const now = config.now ?? Date.now;
+    const leases = new Map();
+    const reserved = new Map();
+    function countFor(teamId) {
+        let total = 0;
+        for (const lease of leases.values())
+            if (lease.teamId === teamId)
+                total += 1;
+        for (const reservedTeam of reserved.values())
+            if (reservedTeam === teamId)
+                total += 1;
+        return total;
+    }
+    function isExpired(lease, at) {
+        return (at - lease.openedAt > config.maxLifetimeMs ||
+            at - lease.lastActiveAt > config.idleTimeoutMs);
+    }
+    function ownedBy(lease, owner) {
+        return (lease.teamId === owner.teamId &&
+            lease.agentId === owner.agentId &&
+            lease.sessionId === owner.sessionId);
+    }
+    return {
+        reserve: (leaseId, owner) => {
+            if (countFor(owner.teamId) >= config.maxConcurrentPerTeam)
+                throw new CloudBrowserCapacityExceeded({
+                    teamId: owner.teamId,
+                    limit: config.maxConcurrentPerTeam,
+                });
+            reserved.set(leaseId, owner.teamId);
+        },
+        abandon: (leaseId) => {
+            reserved.delete(leaseId);
+        },
+        register: (leaseId, owner, openedAt) => {
+            reserved.delete(leaseId);
+            leases.set(leaseId, {
+                ...owner,
+                leaseId,
+                openedAt,
+                lastActiveAt: now(),
+                paused: false,
+            });
+        },
+        touch: (leaseId, owner) => {
+            const lease = leases.get(leaseId);
+            if (lease === undefined)
+                throw new CloudBrowserLeaseNotFound({ leaseId });
+            const at = now();
+            if (isExpired(lease, at)) {
+                leases.delete(leaseId);
+                throw new CloudBrowserLeaseNotFound({ leaseId });
+            }
+            if (!ownedBy(lease, owner))
+                throw new CloudBrowserLeaseNotFound({ leaseId });
+            if (lease.paused)
+                throw new CloudBrowserLeasePaused({ leaseId });
+            lease.lastActiveAt = at;
+        },
+        touchAsMember: (leaseId, teamId) => {
+            const lease = leases.get(leaseId);
+            if (lease === undefined)
+                throw new CloudBrowserLeaseNotFound({ leaseId });
+            const at = now();
+            if (isExpired(lease, at)) {
+                leases.delete(leaseId);
+                throw new CloudBrowserLeaseNotFound({ leaseId });
+            }
+            if (lease.teamId !== teamId)
+                throw new CloudBrowserLeaseNotFound({ leaseId });
+            lease.lastActiveAt = at;
+        },
+        release: (leaseId) => {
+            leases.delete(leaseId);
+        },
+        expired: () => {
+            const at = now();
+            const ids = [];
+            for (const lease of leases.values())
+                if (isExpired(lease, at))
+                    ids.push(lease.leaseId);
+            return ids;
+        },
+        get: (leaseId) => leases.get(leaseId),
+        count: countFor,
+        pause: (leaseId) => {
+            const lease = leases.get(leaseId);
+            if (lease !== undefined)
+                lease.paused = true;
+        },
+        resume: (leaseId, teamId) => {
+            const lease = leases.get(leaseId);
+            if (lease?.teamId !== teamId)
+                return;
+            lease.paused = false;
+            lease.lastActiveAt = now();
+        },
+    };
+}

package/dist/browser/operations.d.ts

@@ -0,0 +1,225 @@
+import { z } from "zod";
+/** The module's fixed output bounds (characters, links, selectors, bytes). */
+export declare const cloudBrowserBounds: Readonly<{
+    maxChars: 50000;
+    defaultMarkdownChars: 20000;
+    maxLinks: 500;
+    maxSelectors: 10;
+    maxScrapeBytes: number;
+    maxSnapshotBytes: number;
+    maxScreenshotBytes: number;
+    maxPdfBytes: number;
+}>;
+/** Input of a URL-only Quick Read (`links`). */
+export declare const urlInputSchema: z.ZodObject<{
+    url: z.ZodURL;
+}, z.core.$strict>;
+/** Input of `markdown`: a URL and a character bound. */
+export declare const markdownInputSchema: z.ZodObject<{
+    url: z.ZodURL;
+    maxChars: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/** Output of `markdown`: the page text, possibly truncated. */
+export declare const markdownResultSchema: z.ZodObject<{
+    url: z.ZodString;
+    text: z.ZodString;
+    truncated: z.ZodBoolean;
+}, z.core.$strict>;
+/** Output of `links`: bare URL strings, bounded. */
+export declare const linksResultSchema: z.ZodObject<{
+    url: z.ZodString;
+    links: z.ZodArray<z.ZodString>;
+    truncated: z.ZodBoolean;
+}, z.core.$strict>;
+/** Input of `scrape`: a URL and up to ten CSS selectors. */
+export declare const scrapeInputSchema: z.ZodObject<{
+    url: z.ZodURL;
+    selectors: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/** Output of `scrape`: matched elements per selector, bounded. */
+export declare const scrapeResultSchema: z.ZodObject<{
+    url: z.ZodString;
+    result: z.ZodArray<z.ZodObject<{
+        selector: z.ZodString;
+        elements: z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            html: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    truncated: z.ZodBoolean;
+}, z.core.$strict>;
+/** Input of `extract`: a URL and a prompt. */
+export declare const extractInputSchema: z.ZodObject<{
+    url: z.ZodURL;
+    prompt: z.ZodString;
+}, z.core.$strict>;
+/** Output of `extract`: JSON-safe structured data. */
+export declare const extractResultSchema: z.ZodObject<{
+    url: z.ZodString;
+    result: z.ZodJSONSchema;
+}, z.core.$strict>;
+/** Input of `open`: an optional first URL. */
+export declare const openInputSchema: z.ZodObject<{
+    url: z.ZodDefault<z.ZodNullable<z.ZodURL>>;
+}, z.core.$strict>;
+/** Output of `open`: the new lease and its first URL. */
+export declare const openResultSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    url: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/** Input of `navigate`: a lease and a URL. */
+export declare const navigateInputSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    url: z.ZodURL;
+}, z.core.$strict>;
+/** Output of `navigate`: the page's location after load. */
+export declare const navigateResultSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    url: z.ZodString;
+    status: z.ZodNullable<z.ZodNumber>;
+    title: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/** Input of `snapshot`: a lease. */
+export declare const snapshotInputSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+}, z.core.$strict>;
+/** Output of `snapshot`: a bounded accessibility-tree summary. */
+export declare const snapshotResultSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    tree: z.ZodString;
+    truncated: z.ZodBoolean;
+}, z.core.$strict>;
+/** Input of `click`: a lease and a viewport coordinate. */
+export declare const clickInputSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, z.core.$strict>;
+/** Input of `type`: a lease and text to insert. */
+export declare const typeInputSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>;
+/** Input of `press`: a lease and one key name. */
+export declare const pressInputSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    key: z.ZodString;
+}, z.core.$strict>;
+/** Input of `scroll`: a lease and a pixel delta. */
+export declare const scrollInputSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    deltaX: z.ZodDefault<z.ZodNumber>;
+    deltaY: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/** Output of a driven input step: the lease it acted on. */
+export declare const leaseAckSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+}, z.core.$strict>;
+/** Input of `close`: a lease. */
+export declare const closeInputSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+}, z.core.$strict>;
+/** Output of `close`: the closed lease. */
+export declare const closeResultSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    closed: z.ZodLiteral<true>;
+    provider: z.ZodEnum<{
+        closed: "closed";
+        closing: "closing";
+    }>;
+}, z.core.$strict>;
+/** Parsed `markdown` input. */
+export type MarkdownInput = z.output<typeof markdownInputSchema>;
+/** Parsed `markdown` output. */
+export type MarkdownResult = z.output<typeof markdownResultSchema>;
+/** Parsed `links` output. */
+export type LinksResult = z.output<typeof linksResultSchema>;
+/** Parsed `scrape` input. */
+export type ScrapeInput = z.output<typeof scrapeInputSchema>;
+/** Parsed `scrape` output. */
+export type ScrapeResult = z.output<typeof scrapeResultSchema>;
+/** Parsed `extract` input. */
+export type ExtractInput = z.output<typeof extractInputSchema>;
+/** Parsed `extract` output. */
+export type ExtractResult = z.output<typeof extractResultSchema>;
+/** Parsed `open` output. */
+export type OpenResult = z.output<typeof openResultSchema>;
+/** Parsed `navigate` output. */
+export type NavigateResult = z.output<typeof navigateResultSchema>;
+/** Parsed `snapshot` output. */
+export type SnapshotResult = z.output<typeof snapshotResultSchema>;
+/** Raw bytes never cross the Mycelium boundary; only a byte count does. */
+export type BinaryResult = Readonly<{
+    leaseId: string;
+    bytes: Uint8Array;
+    contentType: 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.
+ */
+export 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;
+}>;
+/** Acknowledgement of one driven input step. */
+export type CloudBrowserAck = Readonly<{
+    leaseId: string;
+}>;
+/** Acknowledgement that a lease closed. */
+export type CloudBrowserClosed = Readonly<{
+    leaseId: string;
+    closed: true;
+    provider: "closed" | "closing";
+}>;
+/** What one `CloudBrowserOperation` returns, before the agent tool shapes it. */
+export type CloudBrowserOperationResult = MarkdownResult | LinksResult | ScrapeResult | ExtractResult | OpenResult | NavigateResult | SnapshotResult | CloudBrowserAck | BinaryResult | CloudBrowserClosed;

package/dist/browser/operations.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+/**
+ * The agent browser's closed operation vocabulary: input/output schemas,
+ * bounds and the one discriminated union `browser.ts` pattern-matches.
+ * There is deliberately no `send`/`execute`/`evaluate` member: the Agent
+ * can never reach raw CDP or run script in the page, only this typed set.
+ * Every failure comes from `./errors.js`'s `CloudBrowserFailure` union.
+ */
+const maxChars = 50_000;
+const defaultMarkdownChars = 20_000;
+const maxLinks = 500;
+const maxSelectors = 10;
+const maxScrapeBytes = 64 * 1024;
+const maxSnapshotBytes = 64 * 1024;
+const maxScreenshotBytes = 8 * 1024 * 1024;
+const maxPdfBytes = 8 * 1024 * 1024;
+/** The module's fixed output bounds (characters, links, selectors, bytes). */
+export const cloudBrowserBounds = Object.freeze({
+    maxChars,
+    defaultMarkdownChars,
+    maxLinks,
+    maxSelectors,
+    maxScrapeBytes,
+    maxSnapshotBytes,
+    maxScreenshotBytes,
+    maxPdfBytes,
+});
+/** Input of a URL-only Quick Read (`links`). */
+export const urlInputSchema = z.strictObject({ url: z.url().max(2_048) });
+/** Input of `markdown`: a URL and a character bound. */
+export const markdownInputSchema = z.strictObject({
+    url: z.url().max(2_048),
+    maxChars: z.number().int().min(1).max(maxChars).default(defaultMarkdownChars),
+});
+/** Output of `markdown`: the page text, possibly truncated. */
+export const markdownResultSchema = z.strictObject({
+    url: z.string(),
+    text: z.string(),
+    truncated: z.boolean(),
+});
+/** Output of `links`: bare URL strings, bounded. */
+export const linksResultSchema = z.strictObject({
+    url: z.string(),
+    /** Cloudflare's `/links` Quick Action returns bare URL strings, not anchor text. */
+    links: z.array(z.string()).max(maxLinks),
+    truncated: z.boolean(),
+});
+/** Input of `scrape`: a URL and up to ten CSS selectors. */
+export const scrapeInputSchema = z.strictObject({
+    url: z.url().max(2_048),
+    selectors: z.array(z.string().min(1).max(256)).min(1).max(maxSelectors),
+});
+/** Output of `scrape`: matched elements per selector, bounded. */
+export const scrapeResultSchema = z.strictObject({
+    url: z.string(),
+    result: z.array(z.strictObject({
+        selector: z.string(),
+        elements: z.array(z.strictObject({ text: z.string(), html: z.string() })),
+    })),
+    truncated: z.boolean(),
+});
+/** Input of `extract`: a URL and a prompt. */
+export const extractInputSchema = z.strictObject({
+    url: z.url().max(2_048),
+    prompt: z.string().min(1).max(2_000),
+});
+/** Output of `extract`: JSON-safe structured data. */
+export const extractResultSchema = z.strictObject({
+    url: z.string(),
+    // `z.json()`, not `z.unknown()`: Mycelium-facing schemas must stay JSON-safe.
+    result: z.json(),
+});
+const leaseIdSchema = z.string().min(1).max(128);
+/** Input of `open`: an optional first URL. */
+export const openInputSchema = z.strictObject({
+    // `.nullable().default(null)`, not `.optional()`: every Mycelium-facing
+    // schema's parsed output must stay JSON-safe (no `undefined`).
+    url: z.url().max(2_048).nullable().default(null),
+});
+/** Output of `open`: the new lease and its first URL. */
+export const openResultSchema = z.strictObject({
+    leaseId: leaseIdSchema,
+    url: z.string().nullable(),
+});
+/** Input of `navigate`: a lease and a URL. */
+export const navigateInputSchema = z.strictObject({
+    leaseId: leaseIdSchema,
+    url: z.url().max(2_048),
+});
+/** Output of `navigate`: the page's location after load. */
+export const navigateResultSchema = z.strictObject({
+    leaseId: leaseIdSchema,
+    url: z.string(),
+    status: z.number().int().nullable(),
+    title: z.string().nullable(),
+});
+/** Input of `snapshot`: a lease. */
+export const snapshotInputSchema = z.strictObject({ leaseId: leaseIdSchema });
+/** Output of `snapshot`: a bounded accessibility-tree summary. */
+export const snapshotResultSchema = z.strictObject({
+    leaseId: leaseIdSchema,
+    tree: z.string(),
+    truncated: z.boolean(),
+});
+/** Input of `click`: a lease and a viewport coordinate. */
+export const clickInputSchema = z.strictObject({
+    leaseId: leaseIdSchema,
+    x: z.number().int().min(0).max(20_000),
+    y: z.number().int().min(0).max(20_000),
+});
+/** Input of `type`: a lease and text to insert. */
+export const typeInputSchema = z.strictObject({
+    leaseId: leaseIdSchema,
+    text: z.string().max(10_000),
+});
+/** Input of `press`: a lease and one key name. */
+export const pressInputSchema = z.strictObject({
+    leaseId: leaseIdSchema,
+    key: z.string().min(1).max(64),
+});
+/** Input of `scroll`: a lease and a pixel delta. */
+export const scrollInputSchema = z.strictObject({
+    leaseId: leaseIdSchema,
+    deltaX: z.number().int().min(-100_000).max(100_000).default(0),
+    deltaY: z.number().int().min(-100_000).max(100_000).default(0),
+});
+/** Output of a driven input step: the lease it acted on. */
+export const leaseAckSchema = z.strictObject({ leaseId: leaseIdSchema });
+/** Input of `close`: a lease. */
+export const closeInputSchema = z.strictObject({ leaseId: leaseIdSchema });
+/** Output of `close`: the closed lease. */
+export const closeResultSchema = z.strictObject({
+    leaseId: leaseIdSchema,
+    closed: z.literal(true),
+    /** "closing" when the provider acknowledged but has not yet confirmed the end. */
+    provider: z.enum(["closed", "closing"]),
+});

package/dist/browser/page.d.ts

@@ -0,0 +1,25 @@
+import { type BinaryResult, type SnapshotResult } from "./operations.js";
+import type { CdpClient } from "./cdp-client.js";
+export type Page = Readonly<{
+    client: CdpClient;
+    cdpSessionId: string;
+    /** The attached page target, so observers can tell it from pages it opens. */
+    targetId: string;
+}>;
+/** Attach to the session's first page target (or a new blank one). */
+export declare function attachPage(client: CdpClient): Promise<Page>;
+export type PageLocation = Readonly<{
+    url: string;
+    title: string | null;
+}>;
+/** The page's current history entry. */
+export declare function pageLocation({ client, cdpSessionId }: Page, fallbackUrl: string): Promise<PageLocation>;
+/** Navigate to an already policy-checked URL and wait for its load event. */
+export declare function navigatePage(page: Page, url: URL, timeoutMs: number): Promise<PageLocation>;
+export declare function snapshotPage({ client, cdpSessionId }: Page, leaseId: string, signal: AbortSignal): Promise<SnapshotResult>;
+export declare function clickPage({ client, cdpSessionId }: Page, x: number, y: number, signal: AbortSignal): Promise<void>;
+export declare function typePage({ client, cdpSessionId }: Page, text: string, signal: AbortSignal): Promise<void>;
+export declare function pressPage({ client, cdpSessionId }: Page, key: string, signal: AbortSignal): Promise<void>;
+export declare function scrollPage({ client, cdpSessionId }: Page, deltaX: number, deltaY: number, signal: AbortSignal): Promise<void>;
+export declare function screenshotPage(page: Page, leaseId: string, signal: AbortSignal): Promise<BinaryResult>;
+export declare function pdfPage(page: Page, leaseId: string, signal: AbortSignal): Promise<BinaryResult>;