@orkestrel/browser 0.0.23 → 0.0.24

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

@@ -22,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.
@@ -185,12 +188,21 @@ 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";
 
@@ -482,7 +494,7 @@ export declare interface BrowserInterface {
  * 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;
@@ -499,8 +511,11 @@ 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. Startup warms the pool and leases one validated browser. The legacy
- * handshake and every tool call await that setup; concurrent callers share a replacement lease.
+ * 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.
@@ -510,6 +525,8 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  * 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 every
@@ -545,7 +562,7 @@ export declare class BrowserMCPServer implements BrowserMCPServerInterface {
 export declare interface BrowserMCPServerInterface {
     /**
      * Serves stdio, sweeps the profiles ended servers left, warms the pool, and resolves after the
-     * session leases a warm browser; the legacy handshake and every tool call await the same setup.
+     * 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.
      */
@@ -566,6 +583,8 @@ export declare interface BrowserMCPServerInterface {
  *   `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;
+ *   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 each browser the pool warms. Default: `createBrowser`
@@ -580,6 +599,7 @@ 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;
@@ -653,6 +673,30 @@ 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;
@@ -832,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>;
@@ -1003,6 +1048,15 @@ export declare function parseBrowserLockEntry(name: string): number | undefined;
  */
 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[];
 

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

@@ -22,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.
@@ -185,12 +188,21 @@ 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";
 
@@ -482,7 +494,7 @@ export declare interface BrowserInterface {
  * 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;
@@ -499,8 +511,11 @@ 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. Startup warms the pool and leases one validated browser. The legacy
- * handshake and every tool call await that setup; concurrent callers share a replacement lease.
+ * 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.
@@ -510,6 +525,8 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  * 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 every
@@ -545,7 +562,7 @@ export declare class BrowserMCPServer implements BrowserMCPServerInterface {
 export declare interface BrowserMCPServerInterface {
     /**
      * Serves stdio, sweeps the profiles ended servers left, warms the pool, and resolves after the
-     * session leases a warm browser; the legacy handshake and every tool call await the same setup.
+     * 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.
      */
@@ -566,6 +583,8 @@ export declare interface BrowserMCPServerInterface {
  *   `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;
+ *   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 each browser the pool warms. Default: `createBrowser`
@@ -580,6 +599,7 @@ 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;
@@ -653,6 +673,30 @@ 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;
@@ -832,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>;
@@ -1003,6 +1048,15 @@ export declare function parseBrowserLockEntry(name: string): number | undefined;
  */
 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[];