@orkestrel/browser 0.0.22 → 0.0.24

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

@@ -1,3 +1,4 @@
+import type { BrowserCallOptions } from '@orkestrel/browser';
 import type { BrowserContextInterface } from '@orkestrel/browser';
 import type { BrowserContextOptions } from '@orkestrel/browser';
 import { BrowserError } from '@orkestrel/browser';
@@ -11,6 +12,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 { BrowserViewport } from '@orkestrel/browser';
 import type { BrowserWriterInterface } from '@orkestrel/browser';
 import type { CDPTarget } from '@orkestrel/browser';
@@ -20,9 +22,12 @@ 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.
@@ -46,6 +51,8 @@ export declare class Browser implements BrowserInterface {
     get connection(): BrowserConnection | undefined;
     get owned(): boolean | undefined;
     get pid(): number | undefined;
+    get endpoint(): string | undefined;
+    ping(options?: BrowserCallOptions): Promise<void>;
     discover(): Promise<BrowserDiscoveryResult>;
     connect(): Promise<void>;
     adopt(): void;
@@ -181,6 +188,51 @@ export declare const BROWSER_RUN_DIRECTORY = "runs";
 /** Names the persisted run snapshot. */
 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";
+
+/** Defines the holder tools independently of the shared browser's vocabulary. */
+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";
+
+/** Names the diagnostic when the warm floor spends its restart bound. */
+export declare const BROWSER_SERVER_EXHAUSTED = "BROWSER_SERVER_EXHAUSTED";
+
+/** Names the refusal for an unknown or ended holder. */
+export declare const BROWSER_SERVER_HOLDER = "BROWSER_SERVER_HOLDER";
+
+/** Names a failed attempt to warm a browser. */
+export declare const BROWSER_SERVER_LAUNCH = "BROWSER_SERVER_LAUNCH";
+
+/** Names a refused browser server option. */
+export declare const BROWSER_SERVER_OPTIONS = "BROWSER_SERVER_OPTIONS";
+
+/** Limits the number of warm browsers to 3. */
+export declare const BROWSER_SERVER_POOL_LIMIT = 3;
+
+/** Sets the default number of warm browsers to 1. */
+export declare const BROWSER_SERVER_POOL_SIZE = 1;
+
+/** Names the browser process record in each profile. */
+export declare const BROWSER_SERVER_RECORD = "browse.json";
+
+/** Permits one failed refill before the next failure spends the bound. */
+export declare const BROWSER_SERVER_RESTARTS = 1;
+
+/** Names a failed profile sweep. */
+export declare const BROWSER_SERVER_SWEEP = "BROWSER_SERVER_SWEEP";
+
+/** Names a failed browser server teardown. */
+export declare const BROWSER_SERVER_TEARDOWN = "BROWSER_SERVER_TEARDOWN";
+
+/** Names the refusal when no browser can serve a call. */
+export declare const BROWSER_SERVER_UNAVAILABLE = "BROWSER_SERVER_UNAVAILABLE";
+
+/** Names an interrupted call whose outcome is unknown. */
+export declare const BROWSER_SERVER_UNRESOLVED = "BROWSER_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>>;
 
@@ -237,7 +289,7 @@ export declare const BROWSER_WINDOWS_SUFFIXES: readonly string[];
  * - `endpoint` — explicit CDP WebSocket URL; when provided, skips discovery
  * - `discover` — whether `connect()` passively probes for an existing browser
  *   before launching (default `true`); set `false` to skip discovery and go
- *   straight to launch — a short probe of `port` still runs first and rejects
+ *   straight to launch — when `port` is explicit, a short probe runs first and rejects
  *   with a coded error naming the occupied port if something is already
  *   listening there, so a demanded fresh launch never silently attaches to a
  *   stranger browser
@@ -355,6 +407,10 @@ export declare type BrowserEventMap = {
  * - `create(options?)` → shortcut to open a page in the default context
  */
 export declare interface BrowserInterface {
+    /** Reports the CDP WebSocket endpoint of the represented session, or undefined when none is. */
+    readonly endpoint: string | undefined;
+    /** Sends CDP `Browser.getVersion` and resolves when the browser answers, changing no state. */
+    ping(options?: BrowserCallOptions): Promise<void>;
     readonly emitter: EmitterInterface<BrowserEventMap>;
     readonly engine: BrowserEngine;
     readonly status: BrowserStatus;
@@ -435,17 +491,17 @@ export declare interface BrowserInterface {
 }
 
 /**
- * Creates the browser a browse server connects on its first tool call.
+ * Creates a browser a browse server connects while warming its pool.
  *
  * @param options - The launch the server composes: `headless`, `executable`, the profile it
- *   owns, `cdp.discover` set to `false`, and the signal its `destroy()` aborts
+ *   owns, the optional `viewport`, `cdp.discover` set to `false`, and the signal its `destroy()` aborts
  * @returns A browser whose `connect()` launches it
  */
 export declare type BrowserLaunchFunction = (options: BrowserOptions) => BrowserInterface;
 
 /**
  * Implements `BrowserMCPServerInterface`: serves the browser vocabulary and the journey tools over
- * the Model Context Protocol on stdio, and launches Chromium on the first tool call.
+ * 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`,
@@ -455,18 +511,27 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  * 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
  * removed when the toolset withdraws the tool, so the server's tool list changes and a subscribed
- * client is notified. The first call of any dispatcher launches Chromium one time: concurrent callers await
- * the same launch, a failed launch rejects every one of them, and the next call launches again.
- * A launch creates `ROOT/.profiles/ID/` exclusively, connects a browser that never attaches to an
+ * client is notified. The server also advertises `acquire`, `execute`, `tools`, and `destroy` with
+ * `BROWSER_SERVER_COPY`. Startup warms the pool and leases the shared browser. The legacy
+ * handshake and browser calls await that setup. Named holders each own a lease, a pending grant,
+ * and loss notices; concurrent calls on a holder share its replacement grant. Ending a holder
+ * destroys its token, and admission counts that holder until disposal settles.
+ * A launch creates `ROOT/.profiles/PID-UUID/` exclusively, connects a browser that never attaches to an
  * existing endpoint, opens one page in an isolated context, and constructs the page toolset with
  * that context and the file journey and run stores under the root, on a manager the toolset owns.
  * A dispatcher forwards its arguments and the call's context, signal included, to the toolset's
  * manager and returns that manager's value, or rejects with its failure message; a text value
  * reaches the client as one text block rather than as its JSON text.
+ * A disconnect or current-page crash retires its slot. A failed call receives a liveness ping;
+ * loss makes its outcome unresolved, while a known success remains successful. Pending losses
+ * prefix the next outcome on a successor, or a refusal, and calls are never repeated.
+ * Concurrent checks share one ping per slot. Cancelling a call ends only its wait; the ping keeps
+ * its deadline and records loss for the next call.
  *
  * `start()` serves stdio and destroys the server at the end of its input, on `SIGINT`, and on
- * `SIGTERM`. `destroy()` stops reading requests and removes every dispatcher, then destroys the
- * toolset, which aborts the active replay, then the browser it launched, then removes the profile.
+ * `SIGTERM`. `destroy()` stops reading requests and removes every dispatcher, then destroys every
+ * slot through the pool — its toolset, which aborts the active replay, then its browser, then its
+ * profile — and rechecks the profile folders this server made or kept.
  *
  * Chromium on Linux refuses to start as the root user unless its sandbox is disabled, so a server
  * running as root on Linux launches Chromium with `--no-sandbox`; a launch that could run
@@ -496,13 +561,14 @@ export declare class BrowserMCPServer implements BrowserMCPServerInterface {
 /** Serves the browser vocabulary and the journey tools over MCP on stdio. */
 export declare interface BrowserMCPServerInterface {
     /**
-     * Serves the tool list over stdio before Chromium starts; the first tool call launches Chromium
-     * with a profile the server owns.
+     * Serves stdio, sweeps the profiles ended servers left, warms the pool, and resolves after the
+     * shared holder leases 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.
      */
     start(): Promise<void>;
     /**
-     * Stops admission, aborts the active replay, destroys the toolset and the browser it launched,
-     * and removes its profile.
+     * Stops admission, tears down every browser, its toolset, and its profile, then rechecks the folders it answers for.
      */
     destroy(): Promise<void>;
 }
@@ -517,19 +583,30 @@ export declare interface BrowserMCPServerInterface {
  *   `true`
  * - `executable` — the path of the Chromium executable the server launches. Default: the browser
  *   `findSystemBrowser` finds
- * - `readonly` — if `true`, refuses `record`, `save`, and `edit`, and `replay` still writes runs;
+ * - `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;
  *   if `false` or omitted, every tool runs
- * - `launch` — creates the browser the first tool call connects. Default: `createBrowser`
+ * - `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
+ *   `BROWSER_SERVER_POOL_LIMIT`. Default: `BROWSER_SERVER_POOL_SIZE`.
+ * - `log` — receives diagnostic lines. Default: `process.stderr`
+ * @throws Thrown when `pool.size` is outside that range or is not an integer, with `BROWSER_SERVER_OPTIONS`
  */
 export declare interface BrowserMCPServerOptions {
     readonly root?: string;
     readonly headless?: boolean;
     readonly executable?: string;
+    readonly viewport?: BrowserViewport;
     readonly readonly?: boolean;
     readonly launch?: BrowserLaunchFunction;
     readonly stdio?: StdioServerOptions;
+    readonly pool?: {
+        readonly size?: number;
+    };
+    readonly log?: NodeJS.WritableStream;
 }
 
 /**
@@ -577,6 +654,12 @@ export declare interface BrowserOptions {
     readonly browsers?: SystemBrowserOptions;
 }
 
+/** Names the browser a browse profile serves, which a later start's sweep reads. */
+export declare interface BrowserProfileRecord {
+    readonly pid: number;
+    readonly endpoint: string;
+}
+
 /**
  * Describes the resolved browser profile directory used for a Chromium-family launch.
  *
@@ -590,6 +673,47 @@ export declare interface BrowserProfileResult {
     readonly temporary: boolean;
 }
 
+/** Describes the JSON catalog returned by the holder tools. */
+export declare interface BrowserServerCatalog {
+    readonly holder: string;
+    readonly tools: readonly ToolDefinition[];
+}
+
+/** 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 shared catalog subscriptions to the exact token that published them. */
+export declare interface BrowserServerMirror {
+    readonly token: PoolToken<BrowserSlot>;
+    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 one warm browser a browse server owns: the browser, its profile, its isolated context, and its started toolset. */
+export declare interface BrowserSlot {
+    readonly browser: BrowserInterface;
+    readonly profile: string;
+    readonly context: BrowserContextInterface;
+    readonly toolset: BrowserToolsetInterface;
+}
+
+/** 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 page: (page: BrowserPageInterface) => void;
+    readonly crashes: ReadonlyMap<BrowserPageInterface, () => void>;
+    readonly subscription: Disposable;
+}
+
 /** Names the lifecycle status of a browser wrapper. */
 export declare type BrowserStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
 
@@ -628,7 +752,7 @@ export declare function createBrowser(options?: BrowserOptions): BrowserInterfac
 
 /**
  * Creates the browse server, which serves the browser vocabulary and the journey tools over the
- * Model Context Protocol on stdio and launches Chromium on the first tool call.
+ * Model Context Protocol on stdio and warms Chromium at server start.
  *
  * @param options - The root, the launch, the journeys' read-only switch, and the streams
  * @returns A {@link BrowserMCPServerInterface} that reads nothing until `start()`
@@ -638,7 +762,7 @@ export declare function createBrowser(options?: BrowserOptions): BrowserInterfac
  * import { createBrowserMCPServer } from '@orkestrel/browser/server'
  *
  * const server = createBrowserMCPServer({ root: 'tmp/browsers', headless: true })
- * await server.start() // answers tools/list before Chromium starts
+ * await server.start() // resolves after leasing a connected browser
  * await server.destroy()
  * ```
  */
@@ -686,6 +810,17 @@ export declare function createFileBrowserJourneyStore(options: FileBrowserStoreO
  */
 export declare function createFileBrowserRunStore(options: FileBrowserStoreOptions): BrowserRunStoreInterface;
 
+/**
+ * Describes a browser loss with its code, cause, and the session state it invalidates.
+ * @param code - Browser server diagnostic code
+ * @param cause - The loss or refusal, including its process context when present
+ * @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'))
+ */
+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`.
@@ -741,6 +876,7 @@ export declare class FileBrowserJourneyStore implements BrowserJourneyStoreInter
 export declare class FileBrowserRunStore implements BrowserRunStoreInterface {
     #private;
     constructor(options: FileBrowserStoreOptions);
+    snapshot(bytes: Uint8Array, options?: BrowserStoreOptions): Promise<string>;
     open(name: string, options?: BrowserStoreOptions): Promise<BrowserRunSlot>;
     get(name: string, id: string, options?: BrowserStoreOptions): Promise<BrowserRun | undefined>;
     set(run: BrowserRun, options?: BrowserStoreOptions): Promise<void>;
@@ -903,9 +1039,36 @@ export declare function parseBrowserEngine(executable: string): BrowserEngine |
  */
 export declare function parseBrowserLockEntry(name: string): number | undefined;
 
+/**
+ * Parses a profile record naming a positive process identifier and a loopback DevTools endpoint.
+ * @param text - JSON record read from a browse profile
+ * @returns The record, or undefined when its shape or endpoint is refused
+ * @example
+ * parseBrowserProfileRecord('{"pid":123,"endpoint":"ws://127.0.0.1:9222/devtools/browser/session"}')
+ */
+export declare function parseBrowserProfileRecord(text: string): BrowserProfileRecord | undefined;
+
+/**
+ * Parses positive integer viewport dimensions in WIDTHxHEIGHT form.
+ * @param value - The viewport environment variable, or undefined when unset
+ * @returns The viewport, or undefined when absent or malformed
+ * @example
+ * parseBrowserViewport('1280x720') // { width: 1280, height: 720 }
+ */
+export declare function parseBrowserViewport(value: string | undefined): BrowserViewport | undefined;
+
 /** Probes PATH (`which`/`where`) for every resolvable command name, in the given order. */
 export declare function probePathNames(names: readonly string[], platform: string): readonly string[];
 
+/**
+ * Probes whether a process has not been confirmed absent.
+ * @param pid - Process identifier to probe with signal zero
+ * @returns True if the host has not confirmed absence with ESRCH; false otherwise
+ * @example
+ * probeProcess(process.pid) // true
+ */
+export declare function probeProcess(pid: number): boolean;
+
 /**
  * Reads the CDP endpoint a launched browser announces on its standard error.
  *