@reticlehq/server 2.0.0

package/dist/mcp.js

@@ -0,0 +1,101 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { isToonable, resultToToon } from '@reticlehq/core';
+import { TOOLS } from './tools/tools.js';
+import { filterTools, TOOL_PROFILE } from './tools/profiles.js';
+import { buildDynamicTools } from './tools/dynamic-tools.js';
+import { runTool } from './tools/invoke-tool.js';
+import { buildErrorPayload } from './tools/error-recovery.js';
+import { log } from './log.js';
+import { SERVER_VERSION } from './server-version.js';
+const SERVER_INFO = { name: 'reticle', version: SERVER_VERSION };
+/** First sentence of a description (purpose only) for lean profiles — keeps per-turn def cost
+ * down. Cuts at the first sentence-ending period or newline; falls back to a 160-char cap. The
+ * first clause retains the essentials (enum hints like "role | text | label" live there). */
+function firstSentence(description) {
+    const nl = description.indexOf('\n');
+    const base = nl >= 0 ? description.slice(0, nl) : description;
+    const dot = base.search(/\.\s/);
+    const sentence = dot >= 0 ? base.slice(0, dot + 1) : base;
+    return sentence.length > 160 ? `${sentence.slice(0, 159)}…` : sentence;
+}
+/**
+ * Lean copy of a tool's zod input shape for lean profiles: each parameter's description is
+ * truncated to its first sentence via zod's own `.describe()` (which returns a new schema, so the
+ * shared shape is never mutated). The per-parameter prose is the bulk of the re-sent-every-turn
+ * schema cost; the first clause keeps each param's purpose and any enum hints. Params without a
+ * description pass through unchanged.
+ */
+function leanZodShape(shape) {
+    const out = {};
+    for (const [key, schema] of Object.entries(shape)) {
+        const desc = schema.description;
+        out[key] = typeof desc === 'string' ? schema.describe(firstSentence(desc)) : schema;
+    }
+    return out;
+}
+const ENCODING_ENV = 'RETICLE_ENCODING';
+const TOON_VALUE = 'toon';
+const PRETTY_VALUE = 'pretty';
+/**
+ * Serialize a tool result to the MCP `text` content block. The agent consumes this text — the
+ * typed contract travels separately as `structuredContent`, unchanged by encoding — so the text
+ * is compact JSON (no indentation) by default: pretty-printing spends a whitespace token on every
+ * field of every line, ~40% overhead on the structured payloads that dominate Reticle's cost, for
+ * readability only a human re-reading a raw transcript would notice. Opt into the older indented
+ * form with `RETICLE_ENCODING=pretty`; `RETICLE_ENCODING=toon` is the even-denser tabular encoding.
+ */
+export function encodeResult(result, encoding) {
+    if (encoding === TOON_VALUE && isToonable(result)) {
+        return resultToToon(result);
+    }
+    return encoding === PRETTY_VALUE ? JSON.stringify(result, null, 2) : JSON.stringify(result);
+}
+export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
+    const encoding = (process.env[ENCODING_ENV] ?? '').toLowerCase();
+    const server = new McpServer(SERVER_INFO);
+    // Cast once to our bridge type so every per-tool call site is typed without `any`.
+    const registerTool = server.registerTool.bind(server);
+    // `dynamic` advertises only the 2 meta-tools (reticle_tools + reticle_run); real tools load on demand.
+    // core/standard advertise the filtered set with terse descriptions (first sentence + trimmed
+    // param prose) — the full prose is re-sent every turn, and the first clause carries the purpose.
+    const advertised = profile === TOOL_PROFILE.DYNAMIC
+        ? buildDynamicTools(TOOLS)
+        : profile === TOOL_PROFILE.HYBRID
+            ? [...filterTools(TOOLS, TOOL_PROFILE.CORE), ...buildDynamicTools(TOOLS)]
+            : filterTools(TOOLS, profile);
+    const terse = profile === TOOL_PROFILE.CORE ||
+        profile === TOOL_PROFILE.STANDARD ||
+        profile === TOOL_PROFILE.HYBRID;
+    for (const tool of advertised) {
+        const config = {
+            description: terse ? firstSentence(tool.description) : tool.description,
+            inputSchema: terse ? leanZodShape(tool.inputSchema) : tool.inputSchema,
+            ...(tool.outputSchema !== undefined ? { outputSchema: tool.outputSchema } : {}),
+        };
+        registerTool(tool.name, config, async (args) => {
+            try {
+                const result = await runTool(tool, deps, args);
+                const text = encodeResult(result, encoding);
+                if (tool.outputSchema !== undefined) {
+                    return {
+                        content: [{ type: 'text', text }],
+                        structuredContent: result,
+                    };
+                }
+                return { content: [{ type: 'text', text }] };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                log('tool_error', { tool: tool.name, error: message });
+                // Every error the agent hits should answer "what next?", not just "what broke".
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: JSON.stringify(buildErrorPayload(message)) }],
+                };
+            }
+        });
+    }
+    return server;
+}
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/pairing-token.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Auto-provisioned bridge pairing token. The daemon reads-or-creates a per-user secret at
+ * ~/.reticle/pairing-token; the bridge then requires it, so a rogue localhost app (which, running in a
+ * browser sandbox, cannot read the file) can no longer register/drive sessions just by being on a
+ * loopback origin. The build plugins read the same file Node-side and inject it into connect(), so a
+ * legitimately-served app stays zero-config.
+ */
+/** Injectable IO + randomness so the provisioner is unit-testable without touching the real home dir. */
+export interface PairingTokenDeps {
+    readFile: (path: string) => Promise<string>;
+    writeFile: (path: string, data: string) => Promise<void>;
+    mkdir: (path: string) => Promise<void>;
+    randomToken: () => string;
+}
+/** Env override for the token directory (`RETICLE_PAIRING_TOKEN_DIR`) — relocate the secret off $HOME. */
+export declare const PAIRING_TOKEN_DIR_ENV: "RETICLE_PAIRING_TOKEN_DIR";
+/** The default directory that holds the token — the per-user ~/.reticle so it's shared across projects. */
+export declare function defaultPairingTokenDir(): string;
+export declare function pairingTokenPath(dir: string): string;
+/** Production IO adapter: 0600 file + 0700 dir so only the owner can read the secret. */
+export declare function nodePairingTokenDeps(): PairingTokenDeps;
+/**
+ * Read the stored token, or create + persist one on first run. Stable across restarts so a
+ * plugin-injected page keeps working after the daemon bounces. Best-effort: returns undefined if IO
+ * fails, so the caller degrades to the prior tokenless behavior rather than bricking the daemon.
+ */
+export declare function readOrCreatePairingToken(dir: string, deps: PairingTokenDeps): Promise<string | undefined>;
+//# sourceMappingURL=pairing-token.d.ts.map

package/dist/pairing-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-token.d.ts","sourceRoot":"","sources":["../src/pairing-token.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AAEH,yGAAyG;AACzG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,WAAW,EAAE,MAAM,MAAM,CAAC;CAC3B;AAKD,0GAA0G;AAC1G,eAAO,MAAM,qBAAqB,6BAA+B,CAAC;AAElE,2GAA2G;AAC3G,wBAAgB,sBAAsB,IAAI,MAAM,CAI/C;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,yFAAyF;AACzF,wBAAgB,oBAAoB,IAAI,gBAAgB,CAavD;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiB7B"}

package/dist/pairing-token.js

@@ -0,0 +1,62 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ReticleDir, ReticleEnv } from '@reticlehq/core';
+/** 24 random bytes → 48 hex chars: well under MAX_TOKEN_LENGTH, ample entropy for a local secret. */
+const TOKEN_BYTES = 24;
+/** Env override for the token directory (`RETICLE_PAIRING_TOKEN_DIR`) — relocate the secret off $HOME. */
+export const PAIRING_TOKEN_DIR_ENV = ReticleEnv.PAIRING_TOKEN_DIR;
+/** The default directory that holds the token — the per-user ~/.reticle so it's shared across projects. */
+export function defaultPairingTokenDir() {
+    const override = process.env[PAIRING_TOKEN_DIR_ENV];
+    if (override !== undefined && override.length > 0)
+        return override;
+    return join(homedir(), ReticleDir.ROOT);
+}
+export function pairingTokenPath(dir) {
+    return join(dir, ReticleDir.PAIRING_TOKEN_FILE);
+}
+/** Production IO adapter: 0600 file + 0700 dir so only the owner can read the secret. */
+export function nodePairingTokenDeps() {
+    return {
+        readFile: (path) => readFile(path, 'utf8'),
+        writeFile: async (path, data) => {
+            await writeFile(path, data, { encoding: 'utf8', mode: 0o600 });
+            // Enforce perms even if the file pre-existed with a looser mode (writeFile keeps old perms).
+            await chmod(path, 0o600);
+        },
+        mkdir: async (path) => {
+            await mkdir(path, { recursive: true, mode: 0o700 });
+        },
+        randomToken: () => randomBytes(TOKEN_BYTES).toString('hex'),
+    };
+}
+/**
+ * Read the stored token, or create + persist one on first run. Stable across restarts so a
+ * plugin-injected page keeps working after the daemon bounces. Best-effort: returns undefined if IO
+ * fails, so the caller degrades to the prior tokenless behavior rather than bricking the daemon.
+ */
+export async function readOrCreatePairingToken(dir, deps) {
+    const path = pairingTokenPath(dir);
+    try {
+        const existing = (await deps.readFile(path)).trim();
+        if (existing.length > 0)
+            return existing;
+    }
+    catch {
+        // Missing/unreadable — fall through to create one.
+    }
+    try {
+        const token = deps.randomToken().trim();
+        if (token.length === 0)
+            return undefined;
+        await deps.mkdir(dir);
+        await deps.writeFile(path, token);
+        return token;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=pairing-token.js.map

package/dist/pairing-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-token.js","sourceRoot":"","sources":["../src/pairing-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAkBzD,qGAAqG;AACrG,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB,0GAA0G;AAC1G,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC,iBAAiB,CAAC;AAElE,2GAA2G;AAC3G,MAAM,UAAU,sBAAsB;IACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACpD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IACnE,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC;AAClD,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAC1C,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC9B,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/D,6FAA6F;YAC7F,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC3B,CAAC;QACD,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACpB,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACtD,CAAC;QACD,WAAW,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,GAAW,EACX,IAAsB;IAEtB,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACpD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,QAAQ,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,mDAAmD;IACrD,CAAC;IACD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;QACxC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACzC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACtB,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/pool/browser-pool.d.ts

@@ -0,0 +1,90 @@
+/**
+ * BrowserPool — one headless browser, many cheap isolated contexts.
+ *
+ * The "10 agents test 10 flows" scenario does NOT mean 10 Chromiums (each ~hundreds of MB). It means
+ * ONE launched browser and N `newContext()` calls (each ~a few MB, fully isolated cookies/storage).
+ * The pool owns that single browser, hands out per-flow leases, caps concurrency so a machine is
+ * never overwhelmed (over-cap acquires queue FIFO), and transparently relaunches if the browser dies.
+ *
+ * The browser is injected via a `Launcher` so all lifecycle logic is testable without real Chromium;
+ * the thin Playwright adapter that satisfies these interfaces lives separately.
+ */
+/** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
+export interface PooledPage {
+    goto(url: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+    /** Fires when THIS page's renderer crashes — lets the pool reclaim just this lease, not the fleet. */
+    onCrash(handler: () => void): void;
+}
+/** An isolated browsing context (cookies/storage). Real Playwright `BrowserContext` satisfies this. */
+export interface PooledContext {
+    newPage(): Promise<PooledPage>;
+    close(): Promise<void>;
+}
+/** The launched browser. Real Playwright `Browser` satisfies this. */
+export interface PooledBrowser {
+    isConnected(): boolean;
+    newContext(): Promise<PooledContext>;
+    close(): Promise<void>;
+    /** Fires when the browser process dies/crashes so the pool can relaunch on the next acquire. */
+    onDisconnected(handler: () => void): void;
+}
+/** Produces a freshly launched browser. Injected so tests can supply a fake. */
+export type Launcher = () => Promise<PooledBrowser>;
+/** A leased context+page for one flow. `release()` frees the slot and closes the context. */
+export interface Lease {
+    readonly sessionId: string;
+    readonly url: string;
+    release(): Promise<void>;
+}
+/** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
+export declare const DEFAULT_LEASE_TTL_MS: number;
+interface BrowserPoolOptions {
+    /** Max simultaneous leased contexts. Over-cap acquires queue. */
+    maxContexts: number;
+    /** Stable id generator for lease sessionIds (injected to stay clock-/random-free in logic). */
+    genSessionId: () => string;
+    /** Injected clock (ms). Defaults to Date.now; tests pass a controllable one. */
+    now?: () => number;
+    /** A lease untouched for longer than this is reclaimed by sweepExpired(). */
+    leaseTtlMs?: number;
+    /** Per-lease navigation timeout — a page that won't load fails its own lease, never blocks a slot. */
+    navTimeoutMs?: number;
+}
+/**
+ * Owns a single browser and leases isolated contexts out of it, capped at `maxContexts`.
+ * Not exported as a singleton — the daemon owns one instance.
+ */
+export declare class BrowserPool {
+    #private;
+    constructor(launch: Launcher, opts: BrowserPoolOptions);
+    /** Currently leased contexts. */
+    activeCount(): number;
+    /** Acquires waiting for a free slot. */
+    queuedCount(): number;
+    /** The sessionIds of every currently leased context — used to report/group leased sessions. */
+    leasedSessionIds(): string[];
+    /** Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown. */
+    release(sessionId: string): Promise<void>;
+    /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
+    touch(sessionId: string): void;
+    /**
+     * Reclaim leases untouched for longer than the TTL — a hung/crashed agent never holds a slot
+     * forever. Returns the released sessionIds. This is the fault-tolerance backstop for the pool.
+     */
+    sweepExpired(): Promise<string[]>;
+    /**
+     * Lease an isolated context, navigate it to `url`, and return a handle. If the pool is at capacity,
+     * waits FIFO until a slot frees (or until `signal` aborts, if provided).
+     */
+    acquire(url: string, opts?: {
+        signal?: AbortSignal;
+        sessionId?: string;
+    }): Promise<Lease>;
+    /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
+    shutdown(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=browser-pool.d.ts.map

package/dist/pool/browser-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-pool.d.ts","sourceRoot":"","sources":["../../src/pool/browser-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uFAAuF;AACvF,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,sGAAsG;IACtG,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACpC;AAED,uGAAuG;AACvG,MAAM,WAAW,aAAa;IAC5B,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,WAAW,IAAI,OAAO,CAAC;IACvB,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IACrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,gGAAgG;IAChG,cAAc,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC3C;AAED,gFAAgF;AAChF,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;AAEpD,6FAA6F;AAC7F,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,sGAAsG;AACtG,eAAO,MAAM,oBAAoB,QAAa,CAAC;AAK/C,UAAU,kBAAkB;IAC1B,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sGAAsG;IACtG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAUD;;;GAGG;AACH,qBAAa,WAAW;;gBAuBV,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,kBAAkB;IAUtD,iCAAiC;IACjC,WAAW,IAAI,MAAM;IAIrB,wCAAwC;IACxC,WAAW,IAAI,MAAM;IAIrB,+FAA+F;IAC/F,gBAAgB,IAAI,MAAM,EAAE;IAI5B,+FAA+F;IAC/F,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,gGAAgG;IAChG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAK9B;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IASvC;;;OAGG;IACG,OAAO,CACX,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACtD,OAAO,CAAC,KAAK,CAAC;IAgCjB,oGAAoG;IAC9F,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CA4FhC"}

package/dist/pool/browser-pool.js

@@ -0,0 +1,221 @@
+/**
+ * BrowserPool — one headless browser, many cheap isolated contexts.
+ *
+ * The "10 agents test 10 flows" scenario does NOT mean 10 Chromiums (each ~hundreds of MB). It means
+ * ONE launched browser and N `newContext()` calls (each ~a few MB, fully isolated cookies/storage).
+ * The pool owns that single browser, hands out per-flow leases, caps concurrency so a machine is
+ * never overwhelmed (over-cap acquires queue FIFO), and transparently relaunches if the browser dies.
+ *
+ * The browser is injected via a `Launcher` so all lifecycle logic is testable without real Chromium;
+ * the thin Playwright adapter that satisfies these interfaces lives separately.
+ */
+/** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
+export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
+/** Default cap on how long a lease's initial navigation may take before it fails (frees the slot). */
+const DEFAULT_NAV_TIMEOUT_MS = 30_000;
+/**
+ * Owns a single browser and leases isolated contexts out of it, capped at `maxContexts`.
+ * Not exported as a singleton — the daemon owns one instance.
+ */
+export class BrowserPool {
+    #launch;
+    #max;
+    #genId;
+    #now;
+    #ttl;
+    #navTimeout;
+    #browser;
+    #launching;
+    #closed = false;
+    #active = new Map();
+    /**
+     * Slots claimed-or-active — the real concurrency gate. Incremented SYNCHRONOUSLY the instant an
+     * acquire passes the cap check, BEFORE the async context creation, so a burst of concurrent
+     * acquires (the "10 agents at once" case) can't all slip through the gate before any has been
+     * recorded. `#active.size` only reflects fully-created leases; `#occupied` also counts in-flight
+     * ones, and is what the cap is enforced against.
+     */
+    #occupied = 0;
+    /** FIFO of acquires waiting for a slot; each resolves when one frees. */
+    #waiters = [];
+    constructor(launch, opts) {
+        if (opts.maxContexts < 1)
+            throw new Error('maxContexts must be >= 1');
+        this.#launch = launch;
+        this.#max = opts.maxContexts;
+        this.#genId = opts.genSessionId;
+        this.#now = opts.now ?? (() => Date.now());
+        this.#ttl = opts.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
+        this.#navTimeout = opts.navTimeoutMs ?? DEFAULT_NAV_TIMEOUT_MS;
+    }
+    /** Currently leased contexts. */
+    activeCount() {
+        return this.#active.size;
+    }
+    /** Acquires waiting for a free slot. */
+    queuedCount() {
+        return this.#waiters.length;
+    }
+    /** The sessionIds of every currently leased context — used to report/group leased sessions. */
+    leasedSessionIds() {
+        return [...this.#active.keys()];
+    }
+    /** Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown. */
+    release(sessionId) {
+        return this.#release(sessionId);
+    }
+    /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
+    touch(sessionId) {
+        const lease = this.#active.get(sessionId);
+        if (lease !== undefined)
+            lease.touchedAt = this.#now();
+    }
+    /**
+     * Reclaim leases untouched for longer than the TTL — a hung/crashed agent never holds a slot
+     * forever. Returns the released sessionIds. This is the fault-tolerance backstop for the pool.
+     */
+    async sweepExpired() {
+        const now = this.#now();
+        const expired = [...this.#active.entries()]
+            .filter(([, lease]) => now - lease.touchedAt > this.#ttl)
+            .map(([sessionId]) => sessionId);
+        for (const sessionId of expired)
+            await this.#release(sessionId);
+        return expired;
+    }
+    /**
+     * Lease an isolated context, navigate it to `url`, and return a handle. If the pool is at capacity,
+     * waits FIFO until a slot frees (or until `signal` aborts, if provided).
+     */
+    async acquire(url, opts = {}) {
+        if (this.#closed)
+            throw new Error('browser pool is shut down');
+        // #waitForSlot claims the slot synchronously (bumps #occupied) before returning, so the cap holds
+        // even when many acquires race through the gate in the same tick.
+        await this.#waitForSlot(opts.signal);
+        const sessionId = opts.sessionId ?? this.#genId();
+        let context;
+        try {
+            const browser = await this.#ensureBrowser();
+            context = await browser.newContext();
+            const page = await context.newPage();
+            // Per-page crash isolation: if THIS renderer dies, reclaim only this lease — the shared browser
+            // and every other agent's context keep running. (A full browser death is handled by #onCrash.)
+            page.onCrash(() => {
+                void this.#release(sessionId);
+            });
+            await page.goto(url, { timeoutMs: this.#navTimeout });
+            this.#active.set(sessionId, { context, page, url, touchedAt: this.#now() });
+            return {
+                sessionId,
+                url,
+                release: () => this.#release(sessionId),
+            };
+        }
+        catch (err) {
+            // Setup failed after we claimed the slot — give it back so a queued acquire isn't stuck, and
+            // close the half-open context.
+            if (context !== undefined)
+                await context.close().catch(() => undefined);
+            this.#releaseSlot();
+            throw err;
+        }
+    }
+    /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
+    async shutdown() {
+        this.#closed = true; // set first so any woken waiter rejects instead of relaunching a browser
+        const contexts = [...this.#active.values()].map((a) => a.context);
+        this.#active.clear();
+        this.#occupied = 0;
+        await Promise.all(contexts.map((c) => c.close().catch(() => undefined)));
+        const browser = this.#browser;
+        this.#browser = undefined;
+        if (browser !== undefined)
+            await browser.close().catch(() => undefined);
+        for (const waiter of this.#waiters.splice(0))
+            waiter();
+    }
+    async #release(sessionId) {
+        const lease = this.#active.get(sessionId);
+        if (lease === undefined)
+            return; // already released or lost to a crash
+        this.#active.delete(sessionId);
+        await lease.context.close().catch(() => undefined);
+        this.#releaseSlot();
+    }
+    /** Synchronously claim a slot if under the cap. Returns true on success (caller proceeds). */
+    #tryClaim() {
+        if (this.#occupied < this.#max) {
+            this.#occupied += 1;
+            return true;
+        }
+        return false;
+    }
+    #waitForSlot(signal) {
+        if (this.#tryClaim())
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const onFree = () => {
+                // The pool shut down while we waited → reject rather than relaunch a browser.
+                if (this.#closed) {
+                    reject(new Error('browser pool is shut down'));
+                    return;
+                }
+                // Claim the freed slot; if another woken waiter beat us to it, re-queue.
+                if (this.#tryClaim())
+                    resolve();
+                else
+                    this.#waiters.push(onFree);
+            };
+            if (signal !== undefined) {
+                if (signal.aborted) {
+                    reject(new Error('acquire aborted'));
+                    return;
+                }
+                signal.addEventListener('abort', () => {
+                    // Remove ourselves from the queue so a later wake doesn't claim a slot we'll never use.
+                    const i = this.#waiters.indexOf(onFree);
+                    if (i >= 0)
+                        this.#waiters.splice(i, 1);
+                    reject(new Error('acquire aborted'));
+                }, { once: true });
+            }
+            this.#waiters.push(onFree);
+        });
+    }
+    /** Give back one occupied slot and hand it to the next waiter (which re-claims it synchronously). */
+    #releaseSlot() {
+        if (this.#occupied > 0)
+            this.#occupied -= 1;
+        const next = this.#waiters.shift();
+        if (next !== undefined)
+            next();
+    }
+    async #ensureBrowser() {
+        if (this.#closed)
+            throw new Error('browser pool is shut down');
+        if (this.#browser !== undefined && this.#browser.isConnected())
+            return this.#browser;
+        // De-dupe concurrent launches: the first acquire to find no browser starts one; the rest await it.
+        if (this.#launching === undefined) {
+            this.#launching = this.#launch().then((b) => {
+                b.onDisconnected(() => this.#onCrash(b));
+                this.#browser = b;
+                this.#launching = undefined;
+                return b;
+            });
+        }
+        return this.#launching;
+    }
+    /** The browser process died: drop every lease (they're invalid) and clear so the next acquire relaunches. */
+    #onCrash(crashed) {
+        if (this.#browser !== crashed)
+            return; // a stale handler from a prior browser
+        this.#browser = undefined;
+        this.#active.clear();
+        this.#occupied = 0; // every slot is gone with the browser
+        for (const waiter of this.#waiters.splice(0))
+            waiter(); // let them re-claim + relaunch
+    }
+}
+//# sourceMappingURL=browser-pool.js.map

package/dist/pool/browser-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-pool.js","sourceRoot":"","sources":["../../src/pool/browser-pool.ts"],"names":[],"mappings":"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"}

package/dist/pool/lease-reaper.d.ts

@@ -0,0 +1,16 @@
+/**
+ * LeaseReaper — periodic backstop that reclaims orphaned pool leases.
+ *
+ * A lease is "touched" on acquire and on every tool call that targets it. If an agent crashes or
+ * hangs mid-flow it stops touching its lease; after the pool's TTL the reaper closes that context and
+ * frees the slot for a queued acquire. This is what keeps "10 agents, headless" fault-tolerant: one
+ * dead agent can't starve the pool. Mirrors SessionReaper (unref'd interval, idempotent start).
+ */
+import type { BrowserPool } from './browser-pool.js';
+export declare class LeaseReaper {
+    #private;
+    constructor(pool: BrowserPool, intervalMs?: number);
+    start(): void;
+    stop(): void;
+}
+//# sourceMappingURL=lease-reaper.d.ts.map

package/dist/pool/lease-reaper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-reaper.d.ts","sourceRoot":"","sources":["../../src/pool/lease-reaper.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMrD,qBAAa,WAAW;;gBAKV,IAAI,EAAE,WAAW,EAAE,UAAU,GAAE,MAA+B;IAK1E,KAAK,IAAI,IAAI;IAab,IAAI,IAAI,IAAI;CAKb"}

package/dist/pool/lease-reaper.js

@@ -0,0 +1,41 @@
+/**
+ * LeaseReaper — periodic backstop that reclaims orphaned pool leases.
+ *
+ * A lease is "touched" on acquire and on every tool call that targets it. If an agent crashes or
+ * hangs mid-flow it stops touching its lease; after the pool's TTL the reaper closes that context and
+ * frees the slot for a queued acquire. This is what keeps "10 agents, headless" fault-tolerant: one
+ * dead agent can't starve the pool. Mirrors SessionReaper (unref'd interval, idempotent start).
+ */
+import { log } from '../log.js';
+/** How often the reaper sweeps for expired leases. */
+const LEASE_REAP_INTERVAL_MS = 30_000;
+export class LeaseReaper {
+    #timer;
+    #pool;
+    #intervalMs;
+    constructor(pool, intervalMs = LEASE_REAP_INTERVAL_MS) {
+        this.#pool = pool;
+        this.#intervalMs = intervalMs;
+    }
+    start() {
+        if (this.#timer !== undefined)
+            return;
+        this.#timer = setInterval(() => {
+            this.#pool
+                .sweepExpired()
+                .then((reclaimed) => {
+                if (reclaimed.length > 0)
+                    log('lease_reaped_expired', { leases: reclaimed });
+            })
+                .catch(() => undefined);
+        }, this.#intervalMs);
+        this.#timer.unref();
+    }
+    stop() {
+        if (this.#timer === undefined)
+            return;
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+    }
+}
+//# sourceMappingURL=lease-reaper.js.map

package/dist/pool/lease-reaper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-reaper.js","sourceRoot":"","sources":["../../src/pool/lease-reaper.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhC,sDAAsD;AACtD,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAEtC,MAAM,OAAO,WAAW;IACtB,MAAM,CAA6C;IAC1C,KAAK,CAAc;IACnB,WAAW,CAAS;IAE7B,YAAY,IAAiB,EAAE,aAAqB,sBAAsB;QACxE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;IAChC,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO;QACtC,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE;YAC7B,IAAI,CAAC,KAAK;iBACP,YAAY,EAAE;iBACd,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE;gBAClB,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;oBAAE,GAAG,CAAC,sBAAsB,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;YAC/E,CAAC,CAAC;iBACD,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5B,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACrB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO;QACtC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IAC1B,CAAC;CACF"}

package/dist/pool/playwright-launcher.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The real Playwright adapter behind BrowserPool: wraps `chromium.launch` into the pool's small
+ * PooledBrowser/Context/Page interfaces. Kept thin and separate so the pool's lifecycle logic stays
+ * unit-tested with a fake while this glue is exercised only by the e2e battery (it needs Chromium).
+ *
+ * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
+ */
+import type { Launcher } from './browser-pool.js';
+/** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
+export declare function playwrightLauncher(opts?: {
+    headless?: boolean;
+}): Launcher;
+/**
+ * Resolve the pool's concurrency cap. An explicit RETICLE_MAX_CONTEXTS wins (clamped to >=1); otherwise
+ * scale with the machine but never above a sane ceiling so a big box can't fan out into a fork bomb.
+ * Pure (env value + cpu count passed in) so it's testable.
+ */
+export declare function resolveMaxContexts(envValue: string | undefined, cpuCount: number): number;
+//# sourceMappingURL=playwright-launcher.d.ts.map

package/dist/pool/playwright-launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-launcher.d.ts","sourceRoot":"","sources":["../../src/pool/playwright-launcher.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAA4C,MAAM,mBAAmB,CAAC;AA4B5F,4FAA4F;AAC5F,wBAAgB,kBAAkB,CAAC,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,QAAQ,CAG9E;AAKD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOzF"}