@orkestrel/browser 0.0.24 → 0.0.26

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

@@ -160,7 +160,15 @@ export declare const BROWSER_JOURNEY_SNAPSHOT_FILE = "journey.json";
  */
 export declare const BROWSER_KILL_GRACE_MS = 3000;
 
-/** Lists the flags always passed to a launched browser process, alongside the caller's own. */
+/**
+ * Lists the flags always passed to a launched browser process, alongside the caller's own.
+ *
+ * @remarks
+ * Disables account sync so extension installs cannot reset URL loader factories during page imports.
+ * Disables Edge's implicit sign-in so fresh automation profiles carry no Microsoft account.
+ * Chromium ignores the unknown Edge feature name on Chrome and Chromium.
+ * The launcher merges disabled features with the caller's into one switch.
+ */
 export declare const BROWSER_LAUNCH_ARGS: readonly string[];
 
 /**
@@ -191,6 +199,12 @@ 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";
 
+/** Sets the default context capacity per browser, including the shared holder. */
+export declare const BROWSER_SERVER_CONTEXTS = 2;
+
+/** Limits context capacity to the largest measured per-browser count. */
+export declare const BROWSER_SERVER_CONTEXTS_LIMIT = 4;
+
 /** Defines the holder tools independently of the shared browser's vocabulary. */
 export declare const BROWSER_SERVER_COPY: Readonly<Record<BrowserServerToolName, ToolDefinition>>;
 
@@ -512,17 +526,18 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  * 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 server also advertises `acquire`, `execute`, `tools`, and `destroy` with
- * `BROWSER_SERVER_COPY`. Startup warms the pool and leases the shared browser. The legacy
+ * `BROWSER_SERVER_COPY`. Startup warms the pool and assigns a prepared context to the shared holder. 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.
+ * closes its context and releases its lease, 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;
+ * A disconnect retires its browser and every hosted generation. A current-page crash retires only
+ * that holder's context. 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
@@ -530,7 +545,8 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  *
  * `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
- * slot through the pool — its toolset, which aborts the active replay, then its browser, then its
+ * slot through the pool — each toolset, which aborts its active replay, then its context and downloads,
+ * then its browser and 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
@@ -562,7 +578,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
-     * shared holder leases a warm browser; the legacy handshake and every tool call await the same setup.
+     * 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.
      */
@@ -592,8 +608,10 @@ export declare interface BrowserMCPServerInterface {
  *   `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`.
+ * - `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` is outside that 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 `BROWSER_SERVER_OPTIONS`
  */
 export declare interface BrowserMCPServerOptions {
     readonly root?: string;
@@ -605,6 +623,7 @@ export declare interface BrowserMCPServerOptions {
     readonly stdio?: StdioServerOptions;
     readonly pool?: {
         readonly size?: number;
+        readonly contexts?: number;
     };
     readonly log?: NodeJS.WritableStream;
 }
@@ -679,6 +698,13 @@ 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;
@@ -686,9 +712,21 @@ export declare interface BrowserServerHolder {
     readonly abort: AbortController;
 }
 
-/** Binds shared catalog subscriptions to the exact token that published them. */
-export declare interface BrowserServerMirror {
+/** 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;
@@ -697,20 +735,22 @@ export declare interface BrowserServerMirror {
 /** 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. */
+/** 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;
-    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;
 }
 
@@ -869,6 +909,8 @@ export declare class FileBrowserJourneyStore implements BrowserJourneyStoreInter
 /**
  * Persists runs and captures only in directories allocated by this instance.
  * @remarks Requires an existing root. Reopened stores can read and delete saved runs.
+ * Allocations of one journey share a process-local queue across instances; the filesystem lock
+ * still refuses conflicting mutations and allocations from another process.
  * @example
  * const store = new FileBrowserRunStore({ root: directory })
  * const slot = await store.open('check-ready')
@@ -1000,6 +1042,10 @@ export declare function isBrowserNotConnectedError(value: unknown): value is Bro
  * Launches a browser process with raw-CDP debugging flags.
  *
  * @remarks
+ * Merges every caller and library `--disable-features` value into one switch because Chromium
+ * reads only the last occurrence. Keeps `msImplicitSignin` disabled alongside caller features;
+ * Chrome and Chromium ignore this Edge feature name. Preserves the caller's other arguments.
+ *
  * POSIX launches own an isolated process group so lifecycle teardown can
  * signal and await every Chromium subprocess without affecting the caller.
  * Windows launches are not detached and own no group, so teardown there

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

@@ -160,7 +160,15 @@ export declare const BROWSER_JOURNEY_SNAPSHOT_FILE = "journey.json";
  */
 export declare const BROWSER_KILL_GRACE_MS = 3000;
 
-/** Lists the flags always passed to a launched browser process, alongside the caller's own. */
+/**
+ * Lists the flags always passed to a launched browser process, alongside the caller's own.
+ *
+ * @remarks
+ * Disables account sync so extension installs cannot reset URL loader factories during page imports.
+ * Disables Edge's implicit sign-in so fresh automation profiles carry no Microsoft account.
+ * Chromium ignores the unknown Edge feature name on Chrome and Chromium.
+ * The launcher merges disabled features with the caller's into one switch.
+ */
 export declare const BROWSER_LAUNCH_ARGS: readonly string[];
 
 /**
@@ -191,6 +199,12 @@ 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";
 
+/** Sets the default context capacity per browser, including the shared holder. */
+export declare const BROWSER_SERVER_CONTEXTS = 2;
+
+/** Limits context capacity to the largest measured per-browser count. */
+export declare const BROWSER_SERVER_CONTEXTS_LIMIT = 4;
+
 /** Defines the holder tools independently of the shared browser's vocabulary. */
 export declare const BROWSER_SERVER_COPY: Readonly<Record<BrowserServerToolName, ToolDefinition>>;
 
@@ -512,17 +526,18 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  * 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 server also advertises `acquire`, `execute`, `tools`, and `destroy` with
- * `BROWSER_SERVER_COPY`. Startup warms the pool and leases the shared browser. The legacy
+ * `BROWSER_SERVER_COPY`. Startup warms the pool and assigns a prepared context to the shared holder. 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.
+ * closes its context and releases its lease, 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;
+ * A disconnect retires its browser and every hosted generation. A current-page crash retires only
+ * that holder's context. 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
@@ -530,7 +545,8 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  *
  * `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
- * slot through the pool — its toolset, which aborts the active replay, then its browser, then its
+ * slot through the pool — each toolset, which aborts its active replay, then its context and downloads,
+ * then its browser and 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
@@ -562,7 +578,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
-     * shared holder leases a warm browser; the legacy handshake and every tool call await the same setup.
+     * 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.
      */
@@ -592,8 +608,10 @@ export declare interface BrowserMCPServerInterface {
  *   `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`.
+ * - `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` is outside that 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 `BROWSER_SERVER_OPTIONS`
  */
 export declare interface BrowserMCPServerOptions {
     readonly root?: string;
@@ -605,6 +623,7 @@ export declare interface BrowserMCPServerOptions {
     readonly stdio?: StdioServerOptions;
     readonly pool?: {
         readonly size?: number;
+        readonly contexts?: number;
     };
     readonly log?: NodeJS.WritableStream;
 }
@@ -679,6 +698,13 @@ 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;
@@ -686,9 +712,21 @@ export declare interface BrowserServerHolder {
     readonly abort: AbortController;
 }
 
-/** Binds shared catalog subscriptions to the exact token that published them. */
-export declare interface BrowserServerMirror {
+/** 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;
@@ -697,20 +735,22 @@ export declare interface BrowserServerMirror {
 /** 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. */
+/** 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;
-    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;
 }
 
@@ -869,6 +909,8 @@ export declare class FileBrowserJourneyStore implements BrowserJourneyStoreInter
 /**
  * Persists runs and captures only in directories allocated by this instance.
  * @remarks Requires an existing root. Reopened stores can read and delete saved runs.
+ * Allocations of one journey share a process-local queue across instances; the filesystem lock
+ * still refuses conflicting mutations and allocations from another process.
  * @example
  * const store = new FileBrowserRunStore({ root: directory })
  * const slot = await store.open('check-ready')
@@ -1000,6 +1042,10 @@ export declare function isBrowserNotConnectedError(value: unknown): value is Bro
  * Launches a browser process with raw-CDP debugging flags.
  *
  * @remarks
+ * Merges every caller and library `--disable-features` value into one switch because Chromium
+ * reads only the last occurrence. Keeps `msImplicitSignin` disabled alongside caller features;
+ * Chrome and Chromium ignore this Edge feature name. Preserves the caller's other arguments.
+ *
  * POSIX launches own an isolated process group so lifecycle teardown can
  * signal and await every Chromium subprocess without affecting the caller.
  * Windows launches are not detached and own no group, so teardown there