@orkestrel/browser 0.0.26 → 0.0.27

package/dist/src/server/index.d.cts

@@ -1,10 +1,11 @@
 import type { BrowserCallOptions } from '@orkestrel/browser';
 import type { BrowserContextInterface } from '@orkestrel/browser';
-import type { BrowserContextOptions } from '@orkestrel/browser';
 import { BrowserError } from '@orkestrel/browser';
+import type { BrowserIsolateOptions } from '@orkestrel/browser';
 import type { BrowserJourney } from '@orkestrel/browser';
 import type { BrowserJourneyRevision } from '@orkestrel/browser';
 import type { BrowserJourneyStoreInterface } from '@orkestrel/browser';
+import type { BrowserJourneyWriteOptions } from '@orkestrel/browser';
 import type { BrowserPageInterface } from '@orkestrel/browser';
 import type { BrowserPageOptions } from '@orkestrel/browser';
 import type { BrowserRun } from '@orkestrel/browser';
@@ -12,7 +13,7 @@ import type { BrowserRunSlot } from '@orkestrel/browser';
 import type { BrowserRunStoreInterface } from '@orkestrel/browser';
 import type { BrowserStoreOptions } from '@orkestrel/browser';
 import type { BrowserStorePage } from '@orkestrel/browser';
-import type { BrowserToolsetInterface } from '@orkestrel/browser';
+import type { BrowserStorePageOptions } from '@orkestrel/browser';
 import type { BrowserViewport } from '@orkestrel/browser';
 import type { BrowserWriterInterface } from '@orkestrel/browser';
 import type { CDPTarget } from '@orkestrel/browser';
@@ -22,12 +23,10 @@ import type { ChildProcess } from 'node:child_process';
 import type { EmitterErrorHandler } from '@orkestrel/emitter';
 import type { EmitterHooks } from '@orkestrel/emitter';
 import type { EmitterInterface } from '@orkestrel/emitter';
-import type { PoolToken } from '@orkestrel/pool';
 import type { Readable } from 'node:stream';
 import type { Result } from '@orkestrel/contract';
 import type { StdioServerOptions } from '@orkestrel/mcp/server';
 import type { ToolDefinition } from '@orkestrel/tool';
-import type { ToolInterface } from '@orkestrel/tool';
 
 /**
  * Discovers, launches, connects to, and owns Chromium-family browser sessions.
@@ -59,7 +58,7 @@ export declare class Browser implements BrowserInterface {
     disconnect(): Promise<void>;
     context(index?: number): BrowserContextInterface | undefined;
     contexts(): readonly BrowserContextInterface[];
-    isolate(options?: BrowserContextOptions): Promise<BrowserContextInterface>;
+    isolate(options?: BrowserIsolateOptions): Promise<BrowserContextInterface>;
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
     destroy(): Promise<void>;
     close(): Promise<void>;
@@ -197,7 +196,7 @@ export declare const BROWSER_RUN_DIRECTORY = "runs";
 export declare const BROWSER_RUN_FILE = "run.json";
 
 /** Names the refusal when every browser is admitted to a holder. */
-export declare const BROWSER_SERVER_BUSY = "BROWSER_SERVER_BUSY";
+export declare const BROWSER_SERVER_BUSY = "SERVER_BUSY";
 
 /** Sets the default context capacity per browser, including the shared holder. */
 export declare const BROWSER_SERVER_CONTEXTS = 2;
@@ -209,19 +208,19 @@ export declare const BROWSER_SERVER_CONTEXTS_LIMIT = 4;
 export declare const BROWSER_SERVER_COPY: Readonly<Record<BrowserServerToolName, ToolDefinition>>;
 
 /** Names the notice that a browser and its session state were lost. */
-export declare const BROWSER_SERVER_CRASH = "BROWSER_SERVER_CRASH";
+export declare const BROWSER_SERVER_CRASH = "SERVER_CRASH";
 
 /** Names the diagnostic when the warm floor spends its restart bound. */
-export declare const BROWSER_SERVER_EXHAUSTED = "BROWSER_SERVER_EXHAUSTED";
+export declare const BROWSER_SERVER_EXHAUSTED = "SERVER_EXHAUSTED";
 
 /** Names the refusal for an unknown or ended holder. */
-export declare const BROWSER_SERVER_HOLDER = "BROWSER_SERVER_HOLDER";
+export declare const BROWSER_SERVER_HOLDER = "SERVER_HOLDER";
 
 /** Names a failed attempt to warm a browser. */
-export declare const BROWSER_SERVER_LAUNCH = "BROWSER_SERVER_LAUNCH";
+export declare const BROWSER_SERVER_LAUNCH = "SERVER_LAUNCH";
 
 /** Names a refused browser server option. */
-export declare const BROWSER_SERVER_OPTIONS = "BROWSER_SERVER_OPTIONS";
+export declare const BROWSER_SERVER_OPTIONS = "ARGUMENT";
 
 /** Limits the number of warm browsers to 3. */
 export declare const BROWSER_SERVER_POOL_LIMIT = 3;
@@ -236,16 +235,16 @@ export declare const BROWSER_SERVER_RECORD = "browse.json";
 export declare const BROWSER_SERVER_RESTARTS = 1;
 
 /** Names a failed profile sweep. */
-export declare const BROWSER_SERVER_SWEEP = "BROWSER_SERVER_SWEEP";
+export declare const BROWSER_SERVER_SWEEP = "SERVER_SWEEP";
 
 /** Names a failed browser server teardown. */
-export declare const BROWSER_SERVER_TEARDOWN = "BROWSER_SERVER_TEARDOWN";
+export declare const BROWSER_SERVER_TEARDOWN = "SERVER_TEARDOWN";
 
 /** Names the refusal when no browser can serve a call. */
-export declare const BROWSER_SERVER_UNAVAILABLE = "BROWSER_SERVER_UNAVAILABLE";
+export declare const BROWSER_SERVER_UNAVAILABLE = "SERVER_UNAVAILABLE";
 
 /** Names an interrupted call whose outcome is unknown. */
-export declare const BROWSER_SERVER_UNRESOLVED = "BROWSER_SERVER_UNRESOLVED";
+export declare const BROWSER_SERVER_UNRESOLVED = "SERVER_UNRESOLVED";
 
 /** Names the per-OS default Playwright browser cache directory, relative to the home directory (win32 uses `LOCALAPPDATA` directly). */
 export declare const BROWSER_STORE_CACHE_DIRS: Readonly<Record<string, string>>;
@@ -318,14 +317,6 @@ export declare interface BrowserCDPOptions {
 /** Names how the browser connection was established. */
 export declare type BrowserConnection = 'cdp' | 'launch' | 'persistent';
 
-/**
- * Reports that an operation was attempted after the browser wrapper was destroyed, under the
- * code `BROWSER_DESTROYED_ERROR`.
- */
-export declare class BrowserDestroyedError extends BrowserError {
-    constructor(context?: Readonly<Record<string, unknown>>);
-}
-
 /**
  * Describes the result of passive browser discovery.
  *
@@ -479,7 +470,7 @@ export declare interface BrowserInterface {
      * Creates and registers an isolated CDP context with validated proxy, download, origin,
      * and emulation options.
      */
-    isolate(options?: BrowserContextOptions): Promise<BrowserContextInterface>;
+    isolate(options?: BrowserIsolateOptions): Promise<BrowserContextInterface>;
     /** Opens a page in the default context. */
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
     /**
@@ -518,9 +509,9 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  * the Model Context Protocol on stdio, and warms Chromium at server start.
  *
  * @remarks
- * The server's own manager holds one dispatcher per name of the vocabulary — `look`, `read`, `plain`,
- * `click`, `type`, `press`, `navigate`, `wait`, `dialog`, `tabs`, `switch`, `record`, `save`,
- * `journeys`, `edit`, `replay`, and `forget` — each carrying the description, parameters, and annotations
+ * The server's own manager holds one dispatcher per name of the vocabulary — `read`, `click`,
+ * `type`, `press`, `navigate`, `wait`, `dialog`, `switch`, `record`, `save`, `journeys`, `edit`,
+ * `replay`, `forget`, and `capture` — each carrying the description, parameters, and annotations
  * `BROWSER_TOOL_COPY` gives, so `tools/list` answers before Chromium starts and with Chromium
  * absent. After the launch, a tool the toolset's manager adds under another name, such as a page
  * tool it adopts, is mirrored as a dispatcher with that tool's definition, and the mirror is
@@ -557,7 +548,7 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  * ```ts
  * import { BrowserMCPServer } from '@orkestrel/browser/server'
  *
- * const server = new BrowserMCPServer({ root: 'tmp/browsers', readonly: true })
+ * const server = new BrowserMCPServer({ root: 'tmp/browsers', journeys: { readonly: true } })
  * await server.start()
  * await server.destroy()
  * ```
@@ -580,7 +571,7 @@ export declare interface BrowserMCPServerInterface {
      * Serves stdio, sweeps the profiles ended servers left, warms the pool, and resolves after the
      * shared holder consumes a prepared context on a warm browser; the legacy handshake and every tool call await the same setup.
      * Rejects with `BROWSER_SERVER_UNAVAILABLE` when no browser can serve and with
-     * `BROWSER_TOOLSET_ENDED` after `destroy()`, and resolves when `destroy()` interrupts setup.
+     * `CLOSED` after `destroy()`, and resolves when `destroy()` interrupts setup.
      */
     start(): Promise<void>;
     /**
@@ -595,15 +586,15 @@ export declare interface BrowserMCPServerInterface {
  * @remarks
  * - `root` — the directory the journeys, the runs, and the browser profiles live under, resolved
  *   against the working directory at construction. Default: `tmp/browsers`
- * - `headless` — if `true`, launches Chromium without a window; if `false`, with one. Default:
+ * - `browser.headless` — if `true`, launches Chromium without a window; if `false`, with one. Default:
  *   `true`
- * - `executable` — the path of the Chromium executable the server launches. Default: the browser
- *   `findSystemBrowser` finds
- * - `viewport` — the default viewport for every page in each browser's isolated context;
+ * - `browser.executable` — the path of the Chromium executable the server launches. Default: the first browser
+ *   `findSystemBrowsers` finds
+ * - `browser.viewport` — the default viewport for every page in each browser's isolated context;
  *   omission keeps the browser's launch default
- * - `readonly` — if `true`, refuses `record`, `save`, `edit`, and `forget`, and `replay` still writes runs;
+ * - `journeys.readonly` — if `true`, refuses `record`, `save`, `edit`, and `forget`, and `replay` still writes runs;
  *   if `false` or omitted, every tool runs
- * - `launch` — creates each browser the pool warms. Default: `createBrowser`
+ * - `pool.launch` — creates each browser the pool warms. Default: `createBrowser`
  * - `stdio` — the streams the server reads requests from and writes answers to; the end of
  *   `input` destroys the server. Default: `process.stdin` and `process.stdout`
  * - `pool.size` — the integer number of browsers kept warm, from 1 through
@@ -611,31 +602,27 @@ export declare interface BrowserMCPServerInterface {
  * - `pool.contexts` — the integer context capacity per browser, shared holder included, from 1
  *   through `BROWSER_SERVER_CONTEXTS_LIMIT`. Default: `BROWSER_SERVER_CONTEXTS`.
  * - `log` — receives diagnostic lines. Default: `process.stderr`
- * @throws Thrown when `pool.size` or `pool.contexts` is outside its range or is not an integer, with `BROWSER_SERVER_OPTIONS`
+ * @throws Thrown when `pool.size` or `pool.contexts` is outside its range or is not an integer, with `ARGUMENT`
  */
 export declare interface BrowserMCPServerOptions {
     readonly root?: string;
-    readonly headless?: boolean;
-    readonly executable?: string;
-    readonly viewport?: BrowserViewport;
-    readonly readonly?: boolean;
-    readonly launch?: BrowserLaunchFunction;
+    readonly browser?: {
+        readonly headless?: boolean;
+        readonly executable?: string;
+        readonly viewport?: BrowserViewport;
+    };
+    readonly journeys?: {
+        readonly readonly?: boolean;
+    };
     readonly stdio?: StdioServerOptions;
     readonly pool?: {
         readonly size?: number;
         readonly contexts?: number;
+        readonly launch?: BrowserLaunchFunction;
     };
     readonly log?: NodeJS.WritableStream;
 }
 
-/**
- * Reports that an operation requiring an active connection was attempted while disconnected,
- * under the code `BROWSER_NOT_CONNECTED_ERROR`.
- */
-export declare class BrowserNotConnectedError extends BrowserError {
-    constructor(context?: Readonly<Record<string, unknown>>);
-}
-
 /**
  * Describes the options for creating a `Browser` instance.
  *
@@ -651,11 +638,8 @@ export declare class BrowserNotConnectedError extends BrowserError {
  * - `viewport` — default viewport dimensions for new pages
  * - `signal` — external AbortSignal for cancelling the connection attempt
  * - `args` — additional command-line flags passed to the launched browser process
- * - `engine` — preferred browser engine to launch; narrows system browser
- *   discovery to this engine (ignored when `executable` is given); takes
- *   precedence over `browsers.engine`
  * - `browsers` — candidate-source overrides consulted when `connect()` needs
- *   to launch (same shape `findSystemBrowsers` takes); ignored when
+ *   to launch, with `browsers.engine` selecting the engine; ignored when
  *   `executable` is given, which bypasses discovery entirely
  */
 export declare interface BrowserOptions {
@@ -669,7 +653,6 @@ export declare interface BrowserOptions {
     readonly viewport?: BrowserViewport;
     readonly signal?: AbortSignal;
     readonly args?: readonly string[];
-    readonly engine?: BrowserEngine;
     readonly browsers?: SystemBrowserOptions;
 }
 
@@ -698,62 +681,9 @@ export declare interface BrowserServerCatalog {
     readonly tools: readonly ToolDefinition[];
 }
 
-/** Holds one prepared or assigned context generation and its downloads directory. */
-export declare interface BrowserServerContext {
-    readonly context: BrowserContextInterface;
-    readonly toolset: BrowserToolsetInterface;
-    readonly directory: string;
-}
-
-/** Identifies one admitted browser lifetime independently of its current pool token. */
-export declare interface BrowserServerHolder {
-    readonly id: string;
-    readonly purpose: string;
-    readonly abort: AbortController;
-}
-
-/** Binds a holder generation to the exact browser lease reserved for its lifetime. */
-export declare interface BrowserServerLease {
-    readonly token: PoolToken<BrowserSlot>;
-    readonly generation: BrowserServerContext;
-}
-
-/** Records a lost generation's cause and its own last URL. */
-export declare interface BrowserServerLoss {
-    readonly cause: unknown;
-    readonly url: string;
-}
-
-/** Binds shared catalog subscriptions to the exact generation that published them. */
-export declare interface BrowserServerMirror {
-    readonly lease: BrowserServerLease;
-    readonly added: (tool: ToolInterface) => void;
-    readonly removed: (tool: ToolInterface) => void;
-    readonly cleared: (tools: readonly ToolInterface[]) => void;
-}
-
 /** Names the server tools that manage independent browser holders. */
 export declare type BrowserServerToolName = 'acquire' | 'execute' | 'tools' | 'destroy';
 
-/** Holds page subscriptions for one prepared or assigned context generation. */
-export declare interface BrowserServerWatch {
-    readonly page: (page: BrowserPageInterface) => void;
-    readonly crashes: ReadonlyMap<BrowserPageInterface, () => void>;
-}
-
-/** Holds one pooled browser and its exclusively owned profile. */
-export declare interface BrowserSlot {
-    readonly browser: BrowserInterface;
-    readonly profile: string;
-}
-
-/** Holds the listeners and resolver of one browser slot's loss watch. */
-export declare interface BrowserSlotWatch {
-    readonly resolve: (cause: unknown) => void;
-    readonly disconnect: () => void;
-    readonly subscription: Disposable;
-}
-
 /** Names the lifecycle status of a browser wrapper. */
 export declare type BrowserStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
 
@@ -801,7 +731,7 @@ export declare function createBrowser(options?: BrowserOptions): BrowserInterfac
  * ```ts
  * import { createBrowserMCPServer } from '@orkestrel/browser/server'
  *
- * const server = createBrowserMCPServer({ root: 'tmp/browsers', headless: true })
+ * const server = createBrowserMCPServer({ root: 'tmp/browsers', browser: { headless: true } })
  * await server.start() // resolves after leasing a connected browser
  * await server.destroy()
  * ```
@@ -816,22 +746,6 @@ export declare function createBrowserMCPServer(options?: BrowserMCPServerOptions
  */
 export declare function createBrowserProfile(path?: string): Promise<BrowserProfileResult>;
 
-/**
- * Creates a filesystem-backed `BrowserWriterInterface` that persists bytes through
- * `node:fs/promises`.
- *
- * @returns A {@link BrowserWriterInterface} that persists bytes through `node:fs/promises`
- */
-export declare function createBrowserWriter(): BrowserWriterInterface;
-
-/**
- * Creates a Node `WebSocket`-backed `CDPTransportInterface` for the given CDP debugger URL.
- *
- * @param options - The CDP WebSocket debugger URL (and optional timeout)
- * @returns A {@link CDPTransportInterface}
- */
-export declare function createCDPTransport(options: WebSocketCDPTransportOptions): CDPTransportInterface;
-
 /**
  * Creates a journey store over an existing filesystem root.
  * @param options - Root and listing cap
@@ -850,6 +764,22 @@ export declare function createFileBrowserJourneyStore(options: FileBrowserStoreO
  */
 export declare function createFileBrowserRunStore(options: FileBrowserStoreOptions): BrowserRunStoreInterface;
 
+/**
+ * Creates a filesystem-backed `BrowserWriterInterface` that persists bytes through
+ * `node:fs/promises`.
+ *
+ * @returns A {@link BrowserWriterInterface} that persists bytes through `node:fs/promises`
+ */
+export declare function createFileBrowserWriter(): BrowserWriterInterface;
+
+/**
+ * Creates a Node `WebSocket`-backed `CDPTransportInterface` for the given CDP debugger URL.
+ *
+ * @param options - The CDP WebSocket debugger URL (and optional timeout)
+ * @returns A {@link CDPTransportInterface}
+ */
+export declare function createWebSocketCDPTransport(options: WebSocketCDPTransportOptions): CDPTransportInterface;
+
 /**
  * Describes a browser loss with its code, cause, and the session state it invalidates.
  * @param code - Browser server diagnostic code
@@ -857,18 +787,18 @@ export declare function createFileBrowserRunStore(options: FileBrowserStoreOptio
  * @param url - The lost page's last URL, when known
  * @returns The coded diagnostic and any operation-lifecycle guidance
  * @example
- * describeBrowserServerLoss('BROWSER_SERVER_UNAVAILABLE', new Error('Browser exited'))
+ * describeBrowserServerLoss('SERVER_UNAVAILABLE', new Error('Browser exited'))
  */
 export declare function describeBrowserServerLoss(code: string, cause: unknown, url?: string): string;
 
 /**
  * Fetches the current CDP target list from a browser's `/json/list` endpoint, as a `Result`
- * carrying either the targets or a coded `BrowserConnectionError`.
+ * carrying either the targets or a coded `BrowserError`.
  *
  * @remarks
  * The endpoint is a network boundary, so an unreachable host, a non-2xx
  * response, and a body that is not a JSON array each come back as a failed
- * `Result` carrying a coded `BrowserConnectionError`. An entry missing a
+ * `Result` carrying a coded `BrowserError`. An entry missing a
  * required string field is skipped rather than failing the whole list.
  *
  * @param port - Port the browser exposes its CDP endpoint on
@@ -898,12 +828,9 @@ export declare class FileBrowserJourneyStore implements BrowserJourneyStoreInter
     #private;
     constructor(options: FileBrowserStoreOptions);
     get(name: string, options?: BrowserStoreOptions): Promise<BrowserJourneyRevision | undefined>;
-    set(journey: BrowserJourney, expected?: number, options?: BrowserStoreOptions): Promise<BrowserJourneyRevision>;
+    set(journey: BrowserJourney, options?: BrowserJourneyWriteOptions): Promise<BrowserJourneyRevision>;
     delete(name: string, options?: BrowserStoreOptions): Promise<void>;
-    list(options?: BrowserStoreOptions & {
-        readonly offset?: number;
-        readonly limit?: number;
-    }): Promise<BrowserStorePage<BrowserJourneyRevision>>;
+    list(options?: BrowserStorePageOptions): Promise<BrowserStorePage<BrowserJourneyRevision>>;
 }
 
 /**
@@ -913,22 +840,19 @@ export declare class FileBrowserJourneyStore implements BrowserJourneyStoreInter
  * still refuses conflicting mutations and allocations from another process.
  * @example
  * const store = new FileBrowserRunStore({ root: directory })
- * const slot = await store.open('check-ready')
+ * const slot = await store.create('check-ready')
  */
 export declare class FileBrowserRunStore implements BrowserRunStoreInterface {
     #private;
     constructor(options: FileBrowserStoreOptions);
-    snapshot(bytes: Uint8Array, options?: BrowserStoreOptions): Promise<string>;
-    open(name: string, options?: BrowserStoreOptions): Promise<BrowserRunSlot>;
+    write(bytes: Uint8Array, options?: BrowserStoreOptions): Promise<string>;
+    create(name: string, options?: BrowserStoreOptions): Promise<BrowserRunSlot>;
     get(name: string, id: string, options?: BrowserStoreOptions): Promise<BrowserRun | undefined>;
     set(run: BrowserRun, options?: BrowserStoreOptions): Promise<void>;
     capture(slot: BrowserRunSlot, name: string, bytes: Uint8Array, options?: BrowserStoreOptions): Promise<string>;
     delete(name: string, id: string, options?: BrowserStoreOptions): Promise<void>;
     clear(name: string, options?: BrowserStoreOptions): Promise<number>;
-    list(name: string, options?: BrowserStoreOptions & {
-        readonly offset?: number;
-        readonly limit?: number;
-    }): Promise<BrowserStorePage<BrowserRun>>;
+    list(name: string, options?: BrowserStorePageOptions): Promise<BrowserStorePage<BrowserRun>>;
 }
 
 /**
@@ -979,15 +903,6 @@ export declare function findInstallPaths(paths: readonly string[]): readonly str
 /** Searches one store base for the top-level `chromium` link and every `chromium-*` install, highest revision first. */
 export declare function findStorePaths(base: string, platform: string): readonly string[];
 
-/**
- * Locates a Chrome/Chromium/Edge executable on this machine — the first entry
- * of {@link findSystemBrowsers}.
- *
- * @param options - Overrides for the candidate sources; see {@link SystemBrowserOptions}
- * @returns The first discovered browser, or undefined
- */
-export declare function findSystemBrowser(options?: SystemBrowserOptions): SystemBrowser | undefined;
-
 /**
  * Enumerates every Chrome/Chromium/Edge executable discoverable on this
  * machine, deduplicated by normalized absolute path.
@@ -1022,22 +937,6 @@ export declare function findSystemBrowsers(options?: SystemBrowserOptions): read
  */
 export declare function formatBrowserLockEntry(pid: number, token: string): string;
 
-/**
- * Narrows an unknown value to a `BrowserDestroyedError`.
- *
- * @param value - Value to check
- * @returns True if value is a BrowserDestroyedError instance; false otherwise
- */
-export declare function isBrowserDestroyedError(value: unknown): value is BrowserDestroyedError;
-
-/**
- * Narrows an unknown value to a `BrowserNotConnectedError`.
- *
- * @param value - Value to check
- * @returns True if value is a BrowserNotConnectedError instance; false otherwise
- */
-export declare function isBrowserNotConnectedError(value: unknown): value is BrowserNotConnectedError;
-
 /**
  * Launches a browser process with raw-CDP debugging flags.
  *
@@ -1167,7 +1066,7 @@ export declare function removeBrowserProfile(profile: BrowserProfileResult): Pro
  * Represents one discovered browser executable on this machine.
  *
  * @remarks
- * Returned by `findSystemBrowsers`/`findSystemBrowser` — pairs the resolved
+ * Returned by `findSystemBrowsers` — pairs the resolved
  * absolute executable path with its classified engine.
  */
 export declare type SystemBrowser = {
@@ -1176,7 +1075,7 @@ export declare type SystemBrowser = {
 };
 
 /**
- * Describes the options overriding `findSystemBrowsers`'/`findSystemBrowser`'s candidate sources.
+ * Describes the options overriding the candidate sources for `findSystemBrowsers`.
  *
  * @remarks
  * Each field replaces the default candidate list for its category — a field