@orkestrel/browser 0.0.17 → 0.0.19

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

@@ -1,8 +1,16 @@
 import type { BrowserContextInterface } from '@orkestrel/browser';
 import type { BrowserContextOptions } from '@orkestrel/browser';
 import { BrowserError } from '@orkestrel/browser';
+import type { BrowserJourney } from '@orkestrel/browser';
+import type { BrowserJourneyRevision } from '@orkestrel/browser';
+import type { BrowserJourneyStoreInterface } from '@orkestrel/browser';
 import type { BrowserPageInterface } from '@orkestrel/browser';
 import type { BrowserPageOptions } from '@orkestrel/browser';
+import type { BrowserRun } from '@orkestrel/browser';
+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 { BrowserViewport } from '@orkestrel/browser';
 import type { BrowserWriterInterface } from '@orkestrel/browser';
 import type { CDPTarget } from '@orkestrel/browser';
@@ -12,7 +20,9 @@ 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 { Readable } from 'node:stream';
 import type { Result } from '@orkestrel/contract';
+import type { StdioServerOptions } from '@orkestrel/mcp/server';
 
 /**
  * Discovers, launches, connects to, and owns Chromium-family browser sessions.
@@ -74,6 +84,27 @@ export declare const BROWSER_DEFAULT_CDP_PORT = 9222;
  */
 export declare const BROWSER_DEFAULT_HOST = "127.0.0.1";
 
+/**
+ * Matches the stderr line Chromium prints when its CDP endpoint accepts connections, and
+ * captures the `ws://` endpoint the line names.
+ *
+ * @remarks
+ * Chromium prints the line only when launched with `--remote-debugging-port`, which is why an
+ * owned launch always passes that flag.
+ */
+export declare const BROWSER_DEVTOOLS_PATTERN: RegExp;
+
+/**
+ * Sets the interval in milliseconds between liveness probes of a terminated browser process
+ * group.
+ *
+ * @remarks
+ * Node raises an exit event for the direct child only. Neither the rest of a POSIX process
+ * group nor a process a launcher handed the endpoint to raises one, so the bounded drain in
+ * `Browser` probes on this interval until the group is gone or the grace period ends.
+ */
+export declare const BROWSER_DRAIN_INTERVAL_MS = 100;
+
 /**
  * Lists the case-insensitive substrings identifying an executable path/name's browser
  * engine, checked by `parseBrowserEngine` in the order `edge` → `chromium` → `chrome`.
@@ -96,11 +127,26 @@ export declare const BROWSER_EXECUTABLE_NAMES: readonly string[];
  */
 export declare const BROWSER_EXECUTABLE_PATHS: Readonly<Record<string, readonly string[]>>;
 
+/** Bounds a file-store listing page by default. */
+export declare const BROWSER_FILE_STORE_LIMIT = 100;
+
 /**
  * Names the flag that enables headless mode on a launched browser process, `'--headless=new'`.
  */
 export declare const BROWSER_HEADLESS_ARG = "--headless=new";
 
+/** Bounds attempts to acquire a journey lock after concurrent recovery. */
+export declare const BROWSER_JOURNEY_LOCK_ATTEMPTS = 8;
+
+/** Names the exclusive journey write lock directory. */
+export declare const BROWSER_JOURNEY_LOCK_DIRECTORY = "journey.lock";
+
+/** Names the retained journey revision counter. */
+export declare const BROWSER_JOURNEY_REVISION_FILE = "revision";
+
+/** Names the persisted journey snapshot. */
+export declare const BROWSER_JOURNEY_SNAPSHOT_FILE = "journey.json";
+
 /**
  * Bounds each launched-process exit window during TERM-to-KILL teardown at `3_000`
  * milliseconds.
@@ -129,6 +175,12 @@ export declare const BROWSER_PROCESS_EXIT_CAUSE = "process-exit";
  */
 export declare const BROWSER_PROFILE_PREFIX = "orkestrel-browser-";
 
+/** Names the journey directory holding its runs. */
+export declare const BROWSER_RUN_DIRECTORY = "runs";
+
+/** Names the persisted run snapshot. */
+export declare const BROWSER_RUN_FILE = "run.json";
+
 /** 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>>;
 
@@ -161,8 +213,8 @@ export declare const BROWSER_TRANSPORT_LOSS_CAUSE = "transport-loss";
 
 /**
  * Defers once for `50` milliseconds when a transport loss is observed on an owned process,
- * giving a near-simultaneous process-exit event, which libuv may reap slightly later than the
- * socket close, first say over the diagnosis.
+ * so a near-simultaneous process-exit event, which libuv might reap slightly later than the
+ * socket close, decides the diagnosis first.
  */
 export declare const BROWSER_TRANSPORT_LOSS_DEFER_MS = 50;
 
@@ -200,14 +252,6 @@ export declare interface BrowserCDPOptions {
 /** Names how the browser connection was established. */
 export declare type BrowserConnection = 'cdp' | 'launch' | 'persistent';
 
-/**
- * Reports that a CDP connection, discovery, or launch attempt failed, under the code
- * `BROWSER_CONNECTION_ERROR`.
- */
-export declare class BrowserConnectionError extends BrowserError {
-    constructor(message: string, context?: Readonly<Record<string, unknown>>);
-}
-
 /**
  * Reports that an operation was attempted after the browser wrapper was destroyed, under the
  * code `BROWSER_DESTROYED_ERROR`.
@@ -350,11 +394,11 @@ export declare interface BrowserInterface {
     /** Assumes responsibility for terminating the connected browser. */
     adopt(): void;
     /**
-     * Detaches the client-side transport while the remote browser keeps running. A merely
-     * attached CDP session forgets the endpoint and its ownership becomes `undefined`. A
-     * launched or explicitly adopted session retains ownership and its endpoint, so the same
-     * instance can reconnect and stays responsible for eventual termination. Transport loss
-     * while an owned browser remains alive is resumable the same way.
+     * Detaches the client-side transport while the remote browser keeps running. An attached CDP
+     * session that this instance neither launched nor adopted forgets the endpoint and its
+     * ownership becomes `undefined`. A launched or explicitly adopted session retains ownership
+     * and its endpoint, so the same instance can reconnect and stays responsible for eventual
+     * termination. Transport loss while an owned browser remains alive is resumable the same way.
      */
     disconnect(): Promise<void>;
     /** Returns one context by index, or the first. */
@@ -374,8 +418,9 @@ export declare interface BrowserInterface {
      * process group and awaits its drain, and on Windows it terminates one process by
      * identifier, the spawned process or the one a launcher handed the endpoint to — which
      * leaves the profile unlocked before cleanup. An adopted attachment is sent CDP
-     * `Browser.close`. A merely attached browser is detached locally and nothing more, because
-     * other clients may share its targets. Idempotent.
+     * `Browser.close`. An attached browser that this instance neither launched nor adopted is
+     * detached locally and nothing more, because other clients might share its targets.
+     * Idempotent.
      */
     destroy(): Promise<void>;
     /**
@@ -389,6 +434,104 @@ export declare interface BrowserInterface {
     close(): Promise<void>;
 }
 
+/**
+ * Creates the browser a browse server connects on its first tool call.
+ *
+ * @param options - The launch the server composes: `headless`, `executable`, the profile it
+ *   owns, `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.
+ *
+ * @remarks
+ * The server's own manager holds one dispatcher per name of the vocabulary — `look`, `read`,
+ * `click`, `type`, `press`, `navigate`, `wait`, `dialog`, `tabs`, `switch`, `record`, `save`,
+ * `journeys`, `edit`, and `replay` — 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
+ * 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
+ * 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.
+ *
+ * `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.
+ *
+ * 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
+ * sandboxed is never changed.
+ *
+ * @example
+ * ```ts
+ * import { BrowserMCPServer } from '@orkestrel/browser/server'
+ *
+ * const server = new BrowserMCPServer({ root: 'tmp/browsers', readonly: true })
+ * await server.start()
+ * await server.destroy()
+ * ```
+ */
+export declare class BrowserMCPServer implements BrowserMCPServerInterface {
+    #private;
+    /**
+     * Registers the dispatchers and binds the protocol to the stdio streams without reading them.
+     *
+     * @param options - The root, the launch, the journeys' read-only switch, and the streams
+     */
+    constructor(options?: BrowserMCPServerOptions);
+    start(): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/** 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.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops admission, aborts the active replay, destroys the toolset and the browser it launched,
+     * and removes its profile.
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Configures the browse server.
+ *
+ * @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:
+ *   `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;
+ *   if `false` or omitted, every tool runs
+ * - `launch` — creates the browser the first tool call connects. 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`
+ */
+export declare interface BrowserMCPServerOptions {
+    readonly root?: string;
+    readonly headless?: boolean;
+    readonly executable?: string;
+    readonly readonly?: boolean;
+    readonly launch?: BrowserLaunchFunction;
+    readonly stdio?: StdioServerOptions;
+}
+
 /**
  * Reports that an operation requiring an active connection was attempted while disconnected,
  * under the code `BROWSER_NOT_CONNECTED_ERROR`.
@@ -476,13 +619,31 @@ export declare function buildWindowsRoots(env: Readonly<Record<string, string |
  * const browser = createBrowser({ headless: true })
  * await browser.connect() // CDP endpoint discovery → connect, else launch
  * const page = await browser.create({ url: 'https://example.com' })
- * await page.click('#accept')
+ * await (await page.elements.find({ css: '#accept' }))[0]?.click()
  * const shot = await page.screenshot({ path: './out.png' })
  * await browser.destroy()
  * ```
  */
 export declare function createBrowser(options?: BrowserOptions): BrowserInterface;
 
+/**
+ * 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.
+ *
+ * @param options - The root, the launch, the journeys' read-only switch, and the streams
+ * @returns A {@link BrowserMCPServerInterface} that reads nothing until `start()`
+ *
+ * @example
+ * ```ts
+ * 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.destroy()
+ * ```
+ */
+export declare function createBrowserMCPServer(options?: BrowserMCPServerOptions): BrowserMCPServerInterface;
+
 /**
  * Resolves a persistent caller profile or creates an isolated temporary one.
  *
@@ -507,6 +668,24 @@ export declare function createBrowserWriter(): BrowserWriterInterface;
  */
 export declare function createCDPTransport(options: WebSocketCDPTransportOptions): CDPTransportInterface;
 
+/**
+ * Creates a journey store over an existing filesystem root.
+ * @param options - Root and listing cap
+ * @returns A durable journey store
+ * @example
+ * const store = createFileBrowserJourneyStore({ root: directory })
+ */
+export declare function createFileBrowserJourneyStore(options: FileBrowserStoreOptions): BrowserJourneyStoreInterface;
+
+/**
+ * Creates a run store over an existing filesystem root.
+ * @param options - Root and listing cap
+ * @returns A durable run and capture store
+ * @example
+ * const store = createFileBrowserRunStore({ root: directory })
+ */
+export declare function createFileBrowserRunStore(options: FileBrowserStoreOptions): BrowserRunStoreInterface;
+
 /**
  * Fetches the current CDP target list from a browser's `/json/list` endpoint, as a `Result`
  * carrying either the targets or a coded `BrowserConnectionError`.
@@ -533,6 +712,60 @@ export declare function createCDPTransport(options: WebSocketCDPTransportOptions
  */
 export declare function fetchCDPTargets(port: number, timeout: number, host?: string): Promise<Result<readonly CDPTarget[], BrowserError>>;
 
+/**
+ * Persists journeys with exclusive writes and revision counters retained across deletion.
+ * @remarks Requires an existing root. A live holder refuses immediately; dead or empty locks are reclaimed within a bounded attempt count.
+ * @example
+ * const store = new FileBrowserJourneyStore({ root: directory })
+ * await store.set(journey)
+ */
+export declare class FileBrowserJourneyStore implements BrowserJourneyStoreInterface {
+    #private;
+    constructor(options: FileBrowserStoreOptions);
+    get(name: string, options?: BrowserStoreOptions): Promise<BrowserJourneyRevision | undefined>;
+    set(journey: BrowserJourney, expected?: number, options?: BrowserStoreOptions): Promise<BrowserJourneyRevision>;
+    delete(name: string, options?: BrowserStoreOptions): Promise<void>;
+    list(options?: BrowserStoreOptions & {
+        readonly offset?: number;
+        readonly limit?: number;
+    }): Promise<BrowserStorePage<BrowserJourneyRevision>>;
+}
+
+/**
+ * Persists runs and captures only in directories allocated by this instance.
+ * @remarks Requires an existing root. Reopened stores can read and delete saved runs.
+ * @example
+ * const store = new FileBrowserRunStore({ root: directory })
+ * const slot = await store.open('check-ready')
+ */
+export declare class FileBrowserRunStore implements BrowserRunStoreInterface {
+    #private;
+    constructor(options: FileBrowserStoreOptions);
+    open(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>>;
+}
+
+/**
+ * Configures a file store: its root under the checkout and the listing cap.
+ *
+ * @remarks
+ * - `root` — the directory the store keeps its entries under, such as `tmp/browsers`, resolved
+ *   through `realpath` one time; every path the store reads or writes lies inside it
+ * - `limit` — the most entries one `list` page holds
+ */
+export declare interface FileBrowserStoreOptions {
+    readonly root: string;
+    readonly limit?: number;
+}
+
 /**
  * Persists captured browser bytes to the filesystem through `node:fs/promises`.
  *
@@ -602,12 +835,14 @@ export declare function findSystemBrowser(options?: SystemBrowserOptions): Syste
 export declare function findSystemBrowsers(options?: SystemBrowserOptions): readonly SystemBrowser[];
 
 /**
- * Narrows an unknown value to a `BrowserConnectionError`.
- *
- * @param value - Value to check
- * @returns True if value is a BrowserConnectionError instance; false otherwise
+ * Formats a process identifier and UUID token as a lock entry name.
+ * @param pid - Positive safe integer identifying the holder process
+ * @param token - Lowercase UUID token identifying this acquisition
+ * @returns The entry name
+ * @example
+ * formatBrowserLockEntry(123, '11111111-1111-4111-8111-111111111111')
  */
-export declare function isBrowserConnectionError(value: unknown): value is BrowserConnectionError;
+export declare function formatBrowserLockEntry(pid: number, token: string): string;
 
 /**
  * Narrows an unknown value to a `BrowserDestroyedError`.
@@ -638,13 +873,13 @@ export declare function isBrowserNotConnectedError(value: unknown): value is Bro
  * subprocesses with it, so that single signal drains the tree.
  *
  * @param executable - Absolute path to the browser executable
- * @param port - Port the browser exposes its CDP endpoint on
+ * @param port - Port the browser exposes its CDP endpoint on, or undefined for a port the operating system picks
  * @param headless - Whether to launch in headless mode
  * @param profile - Optional user-data-dir for a persistent profile
  * @param extra - Additional command-line flags
- * @returns The spawned ChildProcess
+ * @returns The spawned ChildProcess, whose standard error carries the endpoint line `readBrowserEndpoint` reads
  */
-export declare function launchBrowserProcess(executable: string, port: number, headless: boolean, profile?: string, extra?: readonly string[]): ChildProcess;
+export declare function launchBrowserProcess(executable: string, port: number | undefined, headless: boolean, profile?: string, extra?: readonly string[]): ChildProcess;
 
 /** Normalizes an executable path for cross-source deduplication (case-insensitive on Windows). */
 export declare function normalizeExecutablePath(path: string, platform: string): string;
@@ -658,9 +893,36 @@ export declare function normalizeExecutablePath(path: string, platform: string):
  */
 export declare function parseBrowserEngine(executable: string): BrowserEngine | undefined;
 
+/**
+ * Parses the holder process identifier from a lock entry name.
+ * @remarks Requires a positive safe integer followed by a lowercase UUID token.
+ * @param name - Directory entry name
+ * @returns The process identifier, or undefined when the entry is malformed
+ * @example
+ * parseBrowserLockEntry('123-11111111-1111-4111-8111-111111111111') // 123
+ */
+export declare function parseBrowserLockEntry(name: string): number | 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[];
 
+/**
+ * Reads the CDP endpoint a launched browser announces on its standard error.
+ *
+ * @remarks
+ * Chromium prints `DevTools listening on ws://HOST:PORT/devtools/browser/ID` after it binds the
+ * debugging port. The read splits arriving text on line breaks across chunks, so a line split
+ * between two chunks and a line ending `\r\n` both resolve. After resolving, the stream keeps
+ * draining until it closes so the browser's logging never fills the pipe.
+ *
+ * @param stream - The browser's standard error
+ * @param signal - Abort that rejects the read with its reason
+ * @returns The `ws://` endpoint the browser announced
+ *
+ * @throws When the stream closes without the line, or the signal aborts first
+ */
+export declare function readBrowserEndpoint(stream: Readable, signal: AbortSignal): Promise<string>;
+
 /**
  * Returns the first non-empty line of a command's output, without its
  * surrounding whitespace.
@@ -733,19 +995,6 @@ export declare interface SystemBrowserOptions {
     readonly engine?: BrowserEngine;
 }
 
-/**
- * Polls a browser's CDP version endpoint until it responds or the timeout elapses.
- *
- * @param port - Port the browser exposes its CDP endpoint on
- * @param timeout - Maximum time to wait in milliseconds
- * @param host - Host the browser exposes its CDP endpoint on (default `127.0.0.1`)
- * @param signal - Optional external abort; an abort while waiting rethrows rather than resolving
- * @returns The browser's WebSocket debugger URL
- *
- * @throws When the endpoint does not become ready before the timeout
- */
-export declare function waitForCDPReady(port: number, timeout: number, host?: string, signal?: AbortSignal): Promise<string>;
-
 /**
  * Provides a raw CDP text transport backed by `@orkestrel/websocket`.
  *