@kolisachint/hoocode-agent 0.4.162 → 0.4.164

package/dist/core/tools/browser/browsertools-shared.d.ts

@@ -1,190 +0,0 @@
-/**
- * Shared plumbing for the `browser_run` and `browser_continue` tools.
- *
- * Unlike `webtools` (one-shot fetch/search subprocesses), `browsertools` drives
- * a *stateful* parent-in-the-loop protocol: a single long-lived `browsertools
- * serve` process holds the live Chromium and the paused-flow state in memory,
- * and the parent (hoocode) talks to it over newline-delimited JSON-RPC on
- * stdin/stdout. A flow can suspend mid-replay with `Outcome::NeedsParent`,
- * yielding a typed `ParentRequest` + `ResumeToken`; the parent reasons about it
- * (often by looking at a screenshot) and calls `flow_resume(token, response)` to
- * continue. See https://github.com/kolisachint/browsertools (contract.rs).
- *
- * Because that single serve process must survive *between* the `browser_run`
- * call that starts the flow and the `browser_continue` call that answers a
- * `NeedsParent`, this module owns a process-wide {@link sessionRegistry} keyed by
- * `ResumeToken`. Each paused session keeps its serve client alive and is reaped
- * after an idle timeout so an abandoned flow never leaks a Chromium forever.
- *
- * This module owns:
- * - the persistent JSON-RPC serve client (id-correlated request/response),
- * - the locked contract types (mirrors browsertools `src/contract.rs`),
- * - the paused-session registry + lifecycle (idle reap, round cap, teardown),
- * - binary + browser-path resolution.
- */
-/** Opaque token identifying a paused flow, returned with every `NeedsParent`. */
-export type ResumeToken = string;
-/** Reference to bytes (e.g. a screenshot) the parent can fetch via `get_resource`. */
-export type ResourceId = string;
-/**
- * A typed request the engine yields when replay hits ambiguity only an LLM can
- * resolve. The `request` discriminant matches the serde tag in contract.rs.
- * Fields beyond the discriminant are passed through verbatim to the model.
- */
-export interface ParentRequest {
-    request: "classify_state" | "verify_visual" | "extract_semantic" | "decide_next_action" | "reidentify_element";
-    /** Resource id of the screenshot captured at the suspension point, if any. */
-    screenshot_ref?: ResourceId;
-    [key: string]: unknown;
-}
-/** Result of a `flow_start` / `flow_resume` RPC (the `result` field's `outcome`). */
-export type FlowOutcome = {
-    outcome: "complete";
-    result?: unknown;
-} | {
-    outcome: "needs_parent";
-    request: ParentRequest;
-    token: ResumeToken;
-} | {
-    outcome: "failed";
-    step_id?: string;
-    kind?: string;
-    detail?: string;
-};
-/** Result of a `get_resource` RPC. */
-export interface GetResourceResult {
-    ref: ResourceId;
-    mime: string;
-    len: number;
-    png_base64: string;
-}
-/** Default per-request RPC timeout. Flow steps drive a real browser, so this is
- *  generous relative to webtools' 15s. */
-export declare const BROWSERTOOLS_REQUEST_TIMEOUT_MS = 120000;
-/** Default idle window a paused flow may sit in the registry before it is reaped
- *  (killing its serve process + Chromium). Reset on every resume round. The
- *  parent may reason / look at a screenshot / make other tool calls between
- *  rounds, so this is minutes, not seconds. */
-export declare const BROWSERTOOLS_DEFAULT_IDLE_MS: number;
-/** Default hard cap on `NeedsParent` rounds for a single flow, bounding a runaway
- *  suspend/resume loop. */
-export declare const BROWSERTOOLS_DEFAULT_MAX_ROUNDS = 12;
-/** Options threaded into the browser tools by their factories (tests/overrides). */
-export interface BrowsertoolsToolOptions {
-    /** Explicit path to the `browsertools` binary; otherwise resolved via {@link ensureTool}. */
-    binaryPath?: string;
-    /** Chromium/Chrome executable path forwarded to the serve process. */
-    browserPath?: string;
-    /** Idle reap window for paused sessions (ms). */
-    idleTimeoutMs?: number;
-    /** Hard cap on NeedsParent rounds per flow. */
-    maxParentRounds?: number;
-    /** Per-request RPC timeout (ms). */
-    requestTimeoutMs?: number;
-    /** Extra args appended after `serve` (mainly for tests). */
-    serveArgs?: string[];
-    /** Launch a real on-screen Chromium window instead of headless (sets
-     *  `BROWSERTOOLS_HEADFUL=1` on the serve process). */
-    headful?: boolean;
-    /** Default the streamed live viewer on for every flow (the per-call `live_view`
-     *  param still overrides). Set by the --enable-browser-live-preview flag. */
-    liveView?: boolean;
-}
-/** Resolve effective options from explicit overrides, then env, then defaults. */
-export declare function resolveBrowsertoolsOptions(options?: BrowsertoolsToolOptions): Required<Pick<BrowsertoolsToolOptions, "idleTimeoutMs" | "maxParentRounds" | "requestTimeoutMs">> & {
-    binaryPath?: string;
-    browserPath?: string;
-    serveArgs: string[];
-    headful: boolean;
-    liveView: boolean;
-};
-/** Resolve the `browsertools` binary path (explicit override, else download/PATH). */
-export declare function resolveBrowsertoolsBinary(options?: BrowsertoolsToolOptions): Promise<string>;
-/**
- * A live `browsertools serve` process spoken to over newline-delimited JSON-RPC.
- *
- * Wire format (browsertools `src/serve.rs`):
- *   request:  `{ "id": <n>, "method": <string>, "params": <object> }\n`
- *   response: `{ "id": <n>, "result": <value> }` or `{ "id": <n>, "error": <RpcError> }`\n
- *
- * Responses are correlated by `id`, so concurrent requests are safe, though the
- * tools drive it sequentially.
- */
-export declare class BrowsertoolsServeClient {
-    /** URL of the live viewer once `live_view_start` has been issued for this
-     *  serve process, cached so a reused (reclaimed-idle) client does not start a
-     *  second viewer or auto-open another OS tab on the next browser_run call. */
-    liveViewUrl?: string;
-    private readonly proc;
-    private readonly pending;
-    private readonly requestTimeoutMs;
-    private buffer;
-    private nextId;
-    private closed;
-    private exitError;
-    private stderrTail;
-    constructor(binaryPath: string, opts: {
-        cwd?: string;
-        browserPath?: string;
-        serveArgs: string[];
-        requestTimeoutMs: number;
-        headful?: boolean;
-    });
-    private onStdout;
-    private onLine;
-    /** Reject all in-flight requests and mark the client dead. Idempotent. */
-    private fail;
-    /** Send a JSON-RPC request and resolve with its `result` (or reject on `error`). */
-    request<T = unknown>(method: string, params: Record<string, unknown>): Promise<T>;
-    /** Kill the serve process and reject any outstanding requests. Idempotent. */
-    dispose(): void;
-}
-interface PausedSession {
-    client: BrowsertoolsServeClient;
-    /** Number of NeedsParent rounds yielded so far for this flow. */
-    rounds: number;
-    idleTimer: ReturnType<typeof setTimeout>;
-    idleTimeoutMs: number;
-    /** Whether the browser was launched in headful mode for this session. */
-    headful: boolean;
-    /** Explicit browser path used for this session, if any. */
-    browserPath?: string;
-}
-/**
- * Park a paused flow's live serve client under its resume token and arm the idle
- * reaper. Any previous entry for the token is disposed first.
- */
-export declare function parkSession(token: ResumeToken, client: BrowsertoolsServeClient, rounds: number, idleTimeoutMs: number, headful?: boolean, browserPath?: string): void;
-/**
- * Remove a paused session from the registry and return it, stopping its idle
- * timer. The caller now owns the client (to resume or dispose). Returns
- * undefined if the token is unknown (expired/reaped/already completed).
- */
-export declare function takeSession(token: ResumeToken): PausedSession | undefined;
-/** Dispose every parked session. Used on shutdown and in tests. */
-export declare function disposeAllSessions(): void;
-/** Number of currently parked sessions (for tests/diagnostics). */
-export declare function pausedSessionCount(): number;
-/** Configuration preserved from the original flow call so the idle client can
- *  be matched and reused by a subsequent browser_run with the same settings. */
-export interface BrowserClientConfig {
-    headful: boolean;
-    browserPath?: string;
-    idleTimeoutMs: number;
-}
-/**
- * Try to reclaim the shared idle client if its browser config matches.
- * Returns the live client (and clears the slot) on match, or null.
- */
-export declare function takeIdleClient(headful: boolean, browserPath?: string, _idleTimeoutMs?: number): BrowsertoolsServeClient | null;
-/**
- * Park a completed/failed flow's client as idle so the next browser_run call
- * can reuse the same Chromium process and live-view port.
- */
-export declare function parkIdleClient(client: BrowsertoolsServeClient, headful: boolean, browserPath?: string, idleTimeoutMs?: number): void;
-/** Dispose the shared idle client. Called on session shutdown. */
-export declare function disposeIdleClient(): void;
-/** Number of currently idle shared clients (0 or 1, for tests/diagnostics). */
-export declare function idleClientCount(): number;
-export {};
-//# sourceMappingURL=browsertools-shared.d.ts.map

package/dist/core/tools/browser/browsertools-shared.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"browsertools-shared.d.ts","sourceRoot":"","sources":["../../../../src/core/tools/browser/browsertools-shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared plumbing for the `browser_run` and `browser_continue` tools.\n *\n * Unlike `webtools` (one-shot fetch/search subprocesses), `browsertools` drives\n * a *stateful* parent-in-the-loop protocol: a single long-lived `browsertools\n * serve` process holds the live Chromium and the paused-flow state in memory,\n * and the parent (hoocode) talks to it over newline-delimited JSON-RPC on\n * stdin/stdout. A flow can suspend mid-replay with `Outcome::NeedsParent`,\n * yielding a typed `ParentRequest` + `ResumeToken`; the parent reasons about it\n * (often by looking at a screenshot) and calls `flow_resume(token, response)` to\n * continue. See https://github.com/kolisachint/browsertools (contract.rs).\n *\n * Because that single serve process must survive *between* the `browser_run`\n * call that starts the flow and the `browser_continue` call that answers a\n * `NeedsParent`, this module owns a process-wide {@link sessionRegistry} keyed by\n * `ResumeToken`. Each paused session keeps its serve client alive and is reaped\n * after an idle timeout so an abandoned flow never leaks a Chromium forever.\n *\n * This module owns:\n * - the persistent JSON-RPC serve client (id-correlated request/response),\n * - the locked contract types (mirrors browsertools `src/contract.rs`),\n * - the paused-session registry + lifecycle (idle reap, round cap, teardown),\n * - binary + browser-path resolution.\n */\n\nimport { type ChildProcess, spawn } from \"node:child_process\";\nimport { ensureTool } from \"../../../utils/tools-manager.js\";\n\n// ============================================================================\n// Contract types (locked against browsertools `src/contract.rs`)\n// ============================================================================\n\n/** Opaque token identifying a paused flow, returned with every `NeedsParent`. */\nexport type ResumeToken = string;\n\n/** Reference to bytes (e.g. a screenshot) the parent can fetch via `get_resource`. */\nexport type ResourceId = string;\n\n/**\n * A typed request the engine yields when replay hits ambiguity only an LLM can\n * resolve. The `request` discriminant matches the serde tag in contract.rs.\n * Fields beyond the discriminant are passed through verbatim to the model.\n */\nexport interface ParentRequest {\n\trequest: \"classify_state\" | \"verify_visual\" | \"extract_semantic\" | \"decide_next_action\" | \"reidentify_element\";\n\t/** Resource id of the screenshot captured at the suspension point, if any. */\n\tscreenshot_ref?: ResourceId;\n\t[key: string]: unknown;\n}\n\n/** Result of a `flow_start` / `flow_resume` RPC (the `result` field's `outcome`). */\nexport type FlowOutcome =\n\t| { outcome: \"complete\"; result?: unknown }\n\t| { outcome: \"needs_parent\"; request: ParentRequest; token: ResumeToken }\n\t| { outcome: \"failed\"; step_id?: string; kind?: string; detail?: string };\n\n/** Result of a `get_resource` RPC. */\nexport interface GetResourceResult {\n\tref: ResourceId;\n\tmime: string;\n\tlen: number;\n\tpng_base64: string;\n}\n\n// ============================================================================\n// Configuration\n// ============================================================================\n\n/** Default per-request RPC timeout. Flow steps drive a real browser, so this is\n *  generous relative to webtools' 15s. */\nexport const BROWSERTOOLS_REQUEST_TIMEOUT_MS = 120_000;\n\n/** Default idle window a paused flow may sit in the registry before it is reaped\n *  (killing its serve process + Chromium). Reset on every resume round. The\n *  parent may reason / look at a screenshot / make other tool calls between\n *  rounds, so this is minutes, not seconds. */\nexport const BROWSERTOOLS_DEFAULT_IDLE_MS = 5 * 60 * 1000;\n\n/** Default hard cap on `NeedsParent` rounds for a single flow, bounding a runaway\n *  suspend/resume loop. */\nexport const BROWSERTOOLS_DEFAULT_MAX_ROUNDS = 12;\n\n/** Options threaded into the browser tools by their factories (tests/overrides). */\nexport interface BrowsertoolsToolOptions {\n\t/** Explicit path to the `browsertools` binary; otherwise resolved via {@link ensureTool}. */\n\tbinaryPath?: string;\n\t/** Chromium/Chrome executable path forwarded to the serve process. */\n\tbrowserPath?: string;\n\t/** Idle reap window for paused sessions (ms). */\n\tidleTimeoutMs?: number;\n\t/** Hard cap on NeedsParent rounds per flow. */\n\tmaxParentRounds?: number;\n\t/** Per-request RPC timeout (ms). */\n\trequestTimeoutMs?: number;\n\t/** Extra args appended after `serve` (mainly for tests). */\n\tserveArgs?: string[];\n\t/** Launch a real on-screen Chromium window instead of headless (sets\n\t *  `BROWSERTOOLS_HEADFUL=1` on the serve process). */\n\theadful?: boolean;\n\t/** Default the streamed live viewer on for every flow (the per-call `live_view`\n\t *  param still overrides). Set by the --enable-browser-live-preview flag. */\n\tliveView?: boolean;\n}\n\nfunction envNumber(name: string): number | undefined {\n\tconst raw = process.env[name];\n\tif (!raw) return undefined;\n\tconst n = Number(raw);\n\treturn Number.isFinite(n) && n > 0 ? n : undefined;\n}\n\n/** Resolve effective options from explicit overrides, then env, then defaults. */\nexport function resolveBrowsertoolsOptions(options?: BrowsertoolsToolOptions): Required<\n\tPick<BrowsertoolsToolOptions, \"idleTimeoutMs\" | \"maxParentRounds\" | \"requestTimeoutMs\">\n> & {\n\tbinaryPath?: string;\n\tbrowserPath?: string;\n\tserveArgs: string[];\n\theadful: boolean;\n\tliveView: boolean;\n} {\n\treturn {\n\t\tbinaryPath: options?.binaryPath,\n\t\tbrowserPath: options?.browserPath ?? (process.env.HOOCODE_BROWSERTOOLS_BROWSER_PATH?.trim() || undefined),\n\t\theadful: options?.headful ?? false,\n\t\tliveView: options?.liveView ?? false,\n\t\tidleTimeoutMs:\n\t\t\toptions?.idleTimeoutMs ?? envNumber(\"HOOCODE_BROWSERTOOLS_IDLE_MS\") ?? BROWSERTOOLS_DEFAULT_IDLE_MS,\n\t\tmaxParentRounds:\n\t\t\toptions?.maxParentRounds ?? envNumber(\"HOOCODE_BROWSERTOOLS_MAX_ROUNDS\") ?? BROWSERTOOLS_DEFAULT_MAX_ROUNDS,\n\t\trequestTimeoutMs:\n\t\t\toptions?.requestTimeoutMs ??\n\t\t\tenvNumber(\"HOOCODE_BROWSERTOOLS_REQUEST_TIMEOUT_MS\") ??\n\t\t\tBROWSERTOOLS_REQUEST_TIMEOUT_MS,\n\t\tserveArgs: options?.serveArgs ?? [],\n\t};\n}\n\nconst BINARY_MISSING_MESSAGE =\n\t\"browsertools binary unavailable and could not be downloaded — the browser tools require the `browsertools` CLI on PATH or a published release for this platform\";\n\n/** Resolve the `browsertools` binary path (explicit override, else download/PATH). */\nexport async function resolveBrowsertoolsBinary(options?: BrowsertoolsToolOptions): Promise<string> {\n\tif (options?.binaryPath) return options.binaryPath;\n\tconst binaryPath = await ensureTool(\"browsertools\", true);\n\tif (!binaryPath) throw new Error(BINARY_MISSING_MESSAGE);\n\treturn binaryPath;\n}\n\n// ============================================================================\n// Persistent JSON-RPC serve client\n// ============================================================================\n\ninterface PendingRequest {\n\tresolve: (value: unknown) => void;\n\treject: (error: Error) => void;\n\ttimer: ReturnType<typeof setTimeout>;\n}\n\n/**\n * A live `browsertools serve` process spoken to over newline-delimited JSON-RPC.\n *\n * Wire format (browsertools `src/serve.rs`):\n *   request:  `{ \"id\": <n>, \"method\": <string>, \"params\": <object> }\\n`\n *   response: `{ \"id\": <n>, \"result\": <value> }` or `{ \"id\": <n>, \"error\": <RpcError> }`\\n\n *\n * Responses are correlated by `id`, so concurrent requests are safe, though the\n * tools drive it sequentially.\n */\nexport class BrowsertoolsServeClient {\n\t/** URL of the live viewer once `live_view_start` has been issued for this\n\t *  serve process, cached so a reused (reclaimed-idle) client does not start a\n\t *  second viewer or auto-open another OS tab on the next browser_run call. */\n\tliveViewUrl?: string;\n\tprivate readonly proc: ChildProcess;\n\tprivate readonly pending = new Map<number, PendingRequest>();\n\tprivate readonly requestTimeoutMs: number;\n\tprivate buffer = \"\";\n\tprivate nextId = 1;\n\tprivate closed = false;\n\tprivate exitError: Error | undefined;\n\tprivate stderrTail = \"\";\n\n\tconstructor(\n\t\tbinaryPath: string,\n\t\topts: {\n\t\t\tcwd?: string;\n\t\t\tbrowserPath?: string;\n\t\t\tserveArgs: string[];\n\t\t\trequestTimeoutMs: number;\n\t\t\theadful?: boolean;\n\t\t},\n\t) {\n\t\tthis.requestTimeoutMs = opts.requestTimeoutMs;\n\t\t// The exact CLI flag for the browser path is not part of the locked RPC\n\t\t// contract; v0.1.3 added a \"configurable browser path\". We forward it via\n\t\t// env vars the binary is likely to read. Passing extra env is harmless if\n\t\t// the binary ignores them, and centralizing it here makes it a one-line\n\t\t// change once the exact mechanism is confirmed.\n\t\tconst env = { ...process.env };\n\t\tif (opts.browserPath) {\n\t\t\tenv.BROWSERTOOLS_BROWSER_PATH = opts.browserPath;\n\t\t\tenv.CHROME_PATH = opts.browserPath;\n\t\t}\n\t\t// Opt into a real on-screen Chromium window. The serve process reads this\n\t\t// in `Driver::launch`; harmless if an older binary ignores it.\n\t\tif (opts.headful) {\n\t\t\tenv.BROWSERTOOLS_HEADFUL = \"1\";\n\t\t}\n\t\t// Run the serve process in the project cwd so relative flow paths and the\n\t\t// evidence store resolve the same way the user expects.\n\t\tthis.proc = spawn(binaryPath, [\"serve\", ...opts.serveArgs], {\n\t\t\tcwd: opts.cwd,\n\t\t\tshell: false,\n\t\t\tstdio: [\"pipe\", \"pipe\", \"pipe\"],\n\t\t\tenv,\n\t\t});\n\t\tthis.proc.stdout?.setEncoding(\"utf8\");\n\t\tthis.proc.stdout?.on(\"data\", (chunk: string) => this.onStdout(chunk));\n\t\tthis.proc.stderr?.setEncoding(\"utf8\");\n\t\tthis.proc.stderr?.on(\"data\", (chunk: string) => {\n\t\t\t// Keep only a bounded tail so a chatty serve can't grow unbounded; it is\n\t\t\t// surfaced in the error when the process dies unexpectedly.\n\t\t\tthis.stderrTail = (this.stderrTail + chunk).slice(-4000);\n\t\t});\n\t\tthis.proc.on(\"error\", (err) => this.fail(err instanceof Error ? err : new Error(String(err))));\n\t\tthis.proc.on(\"exit\", (code, sig) => {\n\t\t\tif (this.closed) return;\n\t\t\tconst detail = this.stderrTail.trim();\n\t\t\tthis.fail(\n\t\t\t\tnew Error(\n\t\t\t\t\t`browsertools serve exited unexpectedly (code=${code ?? \"null\"}, signal=${sig ?? \"null\"})` +\n\t\t\t\t\t\t(detail ? `: ${detail}` : \"\"),\n\t\t\t\t),\n\t\t\t);\n\t\t});\n\t}\n\n\tprivate onStdout(chunk: string): void {\n\t\tthis.buffer += chunk;\n\t\tlet newlineIndex = this.buffer.indexOf(\"\\n\");\n\t\twhile (newlineIndex !== -1) {\n\t\t\tconst line = this.buffer.slice(0, newlineIndex).trim();\n\t\t\tthis.buffer = this.buffer.slice(newlineIndex + 1);\n\t\t\tif (line) this.onLine(line);\n\t\t\tnewlineIndex = this.buffer.indexOf(\"\\n\");\n\t\t}\n\t}\n\n\tprivate onLine(line: string): void {\n\t\tlet message: { id?: unknown; result?: unknown; error?: unknown };\n\t\ttry {\n\t\t\tmessage = JSON.parse(line);\n\t\t} catch {\n\t\t\t// Non-JSON noise on stdout (shouldn't happen; logs go to stderr). Skip it\n\t\t\t// rather than corrupt id correlation.\n\t\t\treturn;\n\t\t}\n\t\tconst id = typeof message.id === \"number\" ? message.id : undefined;\n\t\tif (id === undefined) return;\n\t\tconst entry = this.pending.get(id);\n\t\tif (!entry) return;\n\t\tthis.pending.delete(id);\n\t\tclearTimeout(entry.timer);\n\t\tif (message.error !== undefined && message.error !== null) {\n\t\t\tentry.reject(new Error(`browsertools ${describeRpcError(message.error)}`));\n\t\t} else {\n\t\t\tentry.resolve(message.result);\n\t\t}\n\t}\n\n\t/** Reject all in-flight requests and mark the client dead. Idempotent. */\n\tprivate fail(error: Error): void {\n\t\tif (this.closed) return;\n\t\tthis.exitError = error;\n\t\tfor (const [, entry] of this.pending) {\n\t\t\tclearTimeout(entry.timer);\n\t\t\tentry.reject(error);\n\t\t}\n\t\tthis.pending.clear();\n\t}\n\n\t/** Send a JSON-RPC request and resolve with its `result` (or reject on `error`). */\n\trequest<T = unknown>(method: string, params: Record<string, unknown>): Promise<T> {\n\t\tif (this.closed) {\n\t\t\treturn Promise.reject(this.exitError ?? new Error(\"browsertools serve client is closed\"));\n\t\t}\n\t\tconst id = this.nextId++;\n\t\treturn new Promise<T>((resolve, reject) => {\n\t\t\tconst timer = setTimeout(() => {\n\t\t\t\tif (this.pending.delete(id)) {\n\t\t\t\t\treject(new Error(`browsertools ${method} timed out after ${this.requestTimeoutMs}ms`));\n\t\t\t\t}\n\t\t\t}, this.requestTimeoutMs);\n\t\t\tthis.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer });\n\t\t\tconst payload = `${JSON.stringify({ id, method, params })}\\n`;\n\t\t\tthis.proc.stdin?.write(payload, (err) => {\n\t\t\t\tif (err && this.pending.delete(id)) {\n\t\t\t\t\tclearTimeout(timer);\n\t\t\t\t\treject(err);\n\t\t\t\t}\n\t\t\t});\n\t\t});\n\t}\n\n\t/** Kill the serve process and reject any outstanding requests. Idempotent. */\n\tdispose(): void {\n\t\tif (this.closed) return;\n\t\tthis.fail(new Error(\"browsertools serve client disposed\"));\n\t\tthis.closed = true;\n\t\t// Best-effort graceful shutdown, then ensure the process is gone.\n\t\ttry {\n\t\t\tthis.proc.stdin?.write(`${JSON.stringify({ id: this.nextId++, method: \"shutdown\", params: {} })}\\n`);\n\t\t} catch {\n\t\t\t// stdin may already be closed; fall through to kill.\n\t\t}\n\t\tthis.proc.stdin?.end();\n\t\tthis.proc.kill(\"SIGTERM\");\n\t\tconst proc = this.proc;\n\t\tsetTimeout(() => {\n\t\t\tif (proc.exitCode === null && proc.signalCode === null) proc.kill(\"SIGKILL\");\n\t\t}, 3000).unref?.();\n\t}\n}\n\nfunction describeRpcError(error: unknown): string {\n\tif (error && typeof error === \"object\") {\n\t\tconst message = (error as { message?: unknown }).message;\n\t\tif (typeof message === \"string\" && message) return message;\n\t}\n\tif (typeof error === \"string\" && error) return error;\n\treturn `RPC error: ${JSON.stringify(error)}`;\n}\n\n// ============================================================================\n// Paused-session registry (process-wide, keyed by ResumeToken)\n// ============================================================================\n\ninterface PausedSession {\n\tclient: BrowsertoolsServeClient;\n\t/** Number of NeedsParent rounds yielded so far for this flow. */\n\trounds: number;\n\tidleTimer: ReturnType<typeof setTimeout>;\n\tidleTimeoutMs: number;\n\t/** Whether the browser was launched in headful mode for this session. */\n\theadful: boolean;\n\t/** Explicit browser path used for this session, if any. */\n\tbrowserPath?: string;\n}\n\nconst sessionRegistry = new Map<ResumeToken, PausedSession>();\n\n/**\n * Park a paused flow's live serve client under its resume token and arm the idle\n * reaper. Any previous entry for the token is disposed first.\n */\nexport function parkSession(\n\ttoken: ResumeToken,\n\tclient: BrowsertoolsServeClient,\n\trounds: number,\n\tidleTimeoutMs: number,\n\theadful = false,\n\tbrowserPath?: string,\n): void {\n\tconst existing = sessionRegistry.get(token);\n\tif (existing && existing.client !== client) {\n\t\tclearTimeout(existing.idleTimer);\n\t\texisting.client.dispose();\n\t}\n\tconst idleTimer = setTimeout(() => {\n\t\tconst session = sessionRegistry.get(token);\n\t\tif (session) {\n\t\t\tsessionRegistry.delete(token);\n\t\t\tsession.client.dispose();\n\t\t}\n\t}, idleTimeoutMs);\n\tidleTimer.unref?.();\n\tsessionRegistry.set(token, { client, rounds, idleTimer, idleTimeoutMs, headful, browserPath });\n}\n\n/**\n * Remove a paused session from the registry and return it, stopping its idle\n * timer. The caller now owns the client (to resume or dispose). Returns\n * undefined if the token is unknown (expired/reaped/already completed).\n */\nexport function takeSession(token: ResumeToken): PausedSession | undefined {\n\tconst session = sessionRegistry.get(token);\n\tif (!session) return undefined;\n\tclearTimeout(session.idleTimer);\n\tsessionRegistry.delete(token);\n\treturn session;\n}\n\n/** Dispose every parked session. Used on shutdown and in tests. */\nexport function disposeAllSessions(): void {\n\tfor (const [, session] of sessionRegistry) {\n\t\tclearTimeout(session.idleTimer);\n\t\tsession.client.dispose();\n\t}\n\tsessionRegistry.clear();\n\tdisposeIdleClient();\n}\n\n/** Number of currently parked sessions (for tests/diagnostics). */\nexport function pausedSessionCount(): number {\n\treturn sessionRegistry.size;\n}\n\n// ============================================================================\n// Shared idle client (one per session, reused across browser_run calls)\n// ============================================================================\n\n/** Configuration preserved from the original flow call so the idle client can\n *  be matched and reused by a subsequent browser_run with the same settings. */\nexport interface BrowserClientConfig {\n\theadful: boolean;\n\tbrowserPath?: string;\n\tidleTimeoutMs: number;\n}\n\ninterface IdleClientEntry {\n\tclient: BrowsertoolsServeClient;\n\theadful: boolean;\n\tbrowserPath?: string;\n\tidleTimer: ReturnType<typeof setTimeout>;\n}\n\nlet sharedIdleClient: IdleClientEntry | null = null;\n\n/**\n * Try to reclaim the shared idle client if its browser config matches.\n * Returns the live client (and clears the slot) on match, or null.\n */\nexport function takeIdleClient(\n\theadful: boolean,\n\tbrowserPath?: string,\n\t_idleTimeoutMs: number = BROWSERTOOLS_DEFAULT_IDLE_MS,\n): BrowsertoolsServeClient | null {\n\tif (!sharedIdleClient) return null;\n\tclearTimeout(sharedIdleClient.idleTimer);\n\tif (sharedIdleClient.headful === headful && sharedIdleClient.browserPath === browserPath) {\n\t\tconst client = sharedIdleClient.client;\n\t\tsharedIdleClient = null;\n\t\treturn client;\n\t}\n\t// Config changed — dispose the stale idle client.\n\tsharedIdleClient.client.dispose();\n\tsharedIdleClient = null;\n\treturn null;\n}\n\n/**\n * Park a completed/failed flow's client as idle so the next browser_run call\n * can reuse the same Chromium process and live-view port.\n */\nexport function parkIdleClient(\n\tclient: BrowsertoolsServeClient,\n\theadful: boolean,\n\tbrowserPath?: string,\n\tidleTimeoutMs: number = BROWSERTOOLS_DEFAULT_IDLE_MS,\n): void {\n\tif (sharedIdleClient) {\n\t\tclearTimeout(sharedIdleClient.idleTimer);\n\t\tsharedIdleClient.client.dispose();\n\t}\n\tconst idleTimer = setTimeout(() => {\n\t\tif (sharedIdleClient?.client === client) {\n\t\t\tclient.dispose();\n\t\t\tsharedIdleClient = null;\n\t\t}\n\t}, idleTimeoutMs);\n\tidleTimer.unref?.();\n\tsharedIdleClient = { client, headful, browserPath, idleTimer };\n}\n\n/** Dispose the shared idle client. Called on session shutdown. */\nexport function disposeIdleClient(): void {\n\tif (sharedIdleClient) {\n\t\tclearTimeout(sharedIdleClient.idleTimer);\n\t\tsharedIdleClient.client.dispose();\n\t\tsharedIdleClient = null;\n\t}\n}\n\n/** Number of currently idle shared clients (0 or 1, for tests/diagnostics). */\nexport function idleClientCount(): number {\n\treturn sharedIdleClient ? 1 : 0;\n}\n"]}

package/dist/core/tools/browser/browsertools-shared.js

@@ -1,335 +0,0 @@
-/**
- * Shared plumbing for the `browser_run` and `browser_continue` tools.
- *
- * Unlike `webtools` (one-shot fetch/search subprocesses), `browsertools` drives
- * a *stateful* parent-in-the-loop protocol: a single long-lived `browsertools
- * serve` process holds the live Chromium and the paused-flow state in memory,
- * and the parent (hoocode) talks to it over newline-delimited JSON-RPC on
- * stdin/stdout. A flow can suspend mid-replay with `Outcome::NeedsParent`,
- * yielding a typed `ParentRequest` + `ResumeToken`; the parent reasons about it
- * (often by looking at a screenshot) and calls `flow_resume(token, response)` to
- * continue. See https://github.com/kolisachint/browsertools (contract.rs).
- *
- * Because that single serve process must survive *between* the `browser_run`
- * call that starts the flow and the `browser_continue` call that answers a
- * `NeedsParent`, this module owns a process-wide {@link sessionRegistry} keyed by
- * `ResumeToken`. Each paused session keeps its serve client alive and is reaped
- * after an idle timeout so an abandoned flow never leaks a Chromium forever.
- *
- * This module owns:
- * - the persistent JSON-RPC serve client (id-correlated request/response),
- * - the locked contract types (mirrors browsertools `src/contract.rs`),
- * - the paused-session registry + lifecycle (idle reap, round cap, teardown),
- * - binary + browser-path resolution.
- */
-import { spawn } from "node:child_process";
-import { ensureTool } from "../../../utils/tools-manager.js";
-// ============================================================================
-// Configuration
-// ============================================================================
-/** Default per-request RPC timeout. Flow steps drive a real browser, so this is
- *  generous relative to webtools' 15s. */
-export const BROWSERTOOLS_REQUEST_TIMEOUT_MS = 120_000;
-/** Default idle window a paused flow may sit in the registry before it is reaped
- *  (killing its serve process + Chromium). Reset on every resume round. The
- *  parent may reason / look at a screenshot / make other tool calls between
- *  rounds, so this is minutes, not seconds. */
-export const BROWSERTOOLS_DEFAULT_IDLE_MS = 5 * 60 * 1000;
-/** Default hard cap on `NeedsParent` rounds for a single flow, bounding a runaway
- *  suspend/resume loop. */
-export const BROWSERTOOLS_DEFAULT_MAX_ROUNDS = 12;
-function envNumber(name) {
-    const raw = process.env[name];
-    if (!raw)
-        return undefined;
-    const n = Number(raw);
-    return Number.isFinite(n) && n > 0 ? n : undefined;
-}
-/** Resolve effective options from explicit overrides, then env, then defaults. */
-export function resolveBrowsertoolsOptions(options) {
-    return {
-        binaryPath: options?.binaryPath,
-        browserPath: options?.browserPath ?? (process.env.HOOCODE_BROWSERTOOLS_BROWSER_PATH?.trim() || undefined),
-        headful: options?.headful ?? false,
-        liveView: options?.liveView ?? false,
-        idleTimeoutMs: options?.idleTimeoutMs ?? envNumber("HOOCODE_BROWSERTOOLS_IDLE_MS") ?? BROWSERTOOLS_DEFAULT_IDLE_MS,
-        maxParentRounds: options?.maxParentRounds ?? envNumber("HOOCODE_BROWSERTOOLS_MAX_ROUNDS") ?? BROWSERTOOLS_DEFAULT_MAX_ROUNDS,
-        requestTimeoutMs: options?.requestTimeoutMs ??
-            envNumber("HOOCODE_BROWSERTOOLS_REQUEST_TIMEOUT_MS") ??
-            BROWSERTOOLS_REQUEST_TIMEOUT_MS,
-        serveArgs: options?.serveArgs ?? [],
-    };
-}
-const BINARY_MISSING_MESSAGE = "browsertools binary unavailable and could not be downloaded — the browser tools require the `browsertools` CLI on PATH or a published release for this platform";
-/** Resolve the `browsertools` binary path (explicit override, else download/PATH). */
-export async function resolveBrowsertoolsBinary(options) {
-    if (options?.binaryPath)
-        return options.binaryPath;
-    const binaryPath = await ensureTool("browsertools", true);
-    if (!binaryPath)
-        throw new Error(BINARY_MISSING_MESSAGE);
-    return binaryPath;
-}
-/**
- * A live `browsertools serve` process spoken to over newline-delimited JSON-RPC.
- *
- * Wire format (browsertools `src/serve.rs`):
- *   request:  `{ "id": <n>, "method": <string>, "params": <object> }\n`
- *   response: `{ "id": <n>, "result": <value> }` or `{ "id": <n>, "error": <RpcError> }`\n
- *
- * Responses are correlated by `id`, so concurrent requests are safe, though the
- * tools drive it sequentially.
- */
-export class BrowsertoolsServeClient {
-    /** URL of the live viewer once `live_view_start` has been issued for this
-     *  serve process, cached so a reused (reclaimed-idle) client does not start a
-     *  second viewer or auto-open another OS tab on the next browser_run call. */
-    liveViewUrl;
-    proc;
-    pending = new Map();
-    requestTimeoutMs;
-    buffer = "";
-    nextId = 1;
-    closed = false;
-    exitError;
-    stderrTail = "";
-    constructor(binaryPath, opts) {
-        this.requestTimeoutMs = opts.requestTimeoutMs;
-        // The exact CLI flag for the browser path is not part of the locked RPC
-        // contract; v0.1.3 added a "configurable browser path". We forward it via
-        // env vars the binary is likely to read. Passing extra env is harmless if
-        // the binary ignores them, and centralizing it here makes it a one-line
-        // change once the exact mechanism is confirmed.
-        const env = { ...process.env };
-        if (opts.browserPath) {
-            env.BROWSERTOOLS_BROWSER_PATH = opts.browserPath;
-            env.CHROME_PATH = opts.browserPath;
-        }
-        // Opt into a real on-screen Chromium window. The serve process reads this
-        // in `Driver::launch`; harmless if an older binary ignores it.
-        if (opts.headful) {
-            env.BROWSERTOOLS_HEADFUL = "1";
-        }
-        // Run the serve process in the project cwd so relative flow paths and the
-        // evidence store resolve the same way the user expects.
-        this.proc = spawn(binaryPath, ["serve", ...opts.serveArgs], {
-            cwd: opts.cwd,
-            shell: false,
-            stdio: ["pipe", "pipe", "pipe"],
-            env,
-        });
-        this.proc.stdout?.setEncoding("utf8");
-        this.proc.stdout?.on("data", (chunk) => this.onStdout(chunk));
-        this.proc.stderr?.setEncoding("utf8");
-        this.proc.stderr?.on("data", (chunk) => {
-            // Keep only a bounded tail so a chatty serve can't grow unbounded; it is
-            // surfaced in the error when the process dies unexpectedly.
-            this.stderrTail = (this.stderrTail + chunk).slice(-4000);
-        });
-        this.proc.on("error", (err) => this.fail(err instanceof Error ? err : new Error(String(err))));
-        this.proc.on("exit", (code, sig) => {
-            if (this.closed)
-                return;
-            const detail = this.stderrTail.trim();
-            this.fail(new Error(`browsertools serve exited unexpectedly (code=${code ?? "null"}, signal=${sig ?? "null"})` +
-                (detail ? `: ${detail}` : "")));
-        });
-    }
-    onStdout(chunk) {
-        this.buffer += chunk;
-        let newlineIndex = this.buffer.indexOf("\n");
-        while (newlineIndex !== -1) {
-            const line = this.buffer.slice(0, newlineIndex).trim();
-            this.buffer = this.buffer.slice(newlineIndex + 1);
-            if (line)
-                this.onLine(line);
-            newlineIndex = this.buffer.indexOf("\n");
-        }
-    }
-    onLine(line) {
-        let message;
-        try {
-            message = JSON.parse(line);
-        }
-        catch {
-            // Non-JSON noise on stdout (shouldn't happen; logs go to stderr). Skip it
-            // rather than corrupt id correlation.
-            return;
-        }
-        const id = typeof message.id === "number" ? message.id : undefined;
-        if (id === undefined)
-            return;
-        const entry = this.pending.get(id);
-        if (!entry)
-            return;
-        this.pending.delete(id);
-        clearTimeout(entry.timer);
-        if (message.error !== undefined && message.error !== null) {
-            entry.reject(new Error(`browsertools ${describeRpcError(message.error)}`));
-        }
-        else {
-            entry.resolve(message.result);
-        }
-    }
-    /** Reject all in-flight requests and mark the client dead. Idempotent. */
-    fail(error) {
-        if (this.closed)
-            return;
-        this.exitError = error;
-        for (const [, entry] of this.pending) {
-            clearTimeout(entry.timer);
-            entry.reject(error);
-        }
-        this.pending.clear();
-    }
-    /** Send a JSON-RPC request and resolve with its `result` (or reject on `error`). */
-    request(method, params) {
-        if (this.closed) {
-            return Promise.reject(this.exitError ?? new Error("browsertools serve client is closed"));
-        }
-        const id = this.nextId++;
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                if (this.pending.delete(id)) {
-                    reject(new Error(`browsertools ${method} timed out after ${this.requestTimeoutMs}ms`));
-                }
-            }, this.requestTimeoutMs);
-            this.pending.set(id, { resolve: resolve, reject, timer });
-            const payload = `${JSON.stringify({ id, method, params })}\n`;
-            this.proc.stdin?.write(payload, (err) => {
-                if (err && this.pending.delete(id)) {
-                    clearTimeout(timer);
-                    reject(err);
-                }
-            });
-        });
-    }
-    /** Kill the serve process and reject any outstanding requests. Idempotent. */
-    dispose() {
-        if (this.closed)
-            return;
-        this.fail(new Error("browsertools serve client disposed"));
-        this.closed = true;
-        // Best-effort graceful shutdown, then ensure the process is gone.
-        try {
-            this.proc.stdin?.write(`${JSON.stringify({ id: this.nextId++, method: "shutdown", params: {} })}\n`);
-        }
-        catch {
-            // stdin may already be closed; fall through to kill.
-        }
-        this.proc.stdin?.end();
-        this.proc.kill("SIGTERM");
-        const proc = this.proc;
-        setTimeout(() => {
-            if (proc.exitCode === null && proc.signalCode === null)
-                proc.kill("SIGKILL");
-        }, 3000).unref?.();
-    }
-}
-function describeRpcError(error) {
-    if (error && typeof error === "object") {
-        const message = error.message;
-        if (typeof message === "string" && message)
-            return message;
-    }
-    if (typeof error === "string" && error)
-        return error;
-    return `RPC error: ${JSON.stringify(error)}`;
-}
-const sessionRegistry = new Map();
-/**
- * Park a paused flow's live serve client under its resume token and arm the idle
- * reaper. Any previous entry for the token is disposed first.
- */
-export function parkSession(token, client, rounds, idleTimeoutMs, headful = false, browserPath) {
-    const existing = sessionRegistry.get(token);
-    if (existing && existing.client !== client) {
-        clearTimeout(existing.idleTimer);
-        existing.client.dispose();
-    }
-    const idleTimer = setTimeout(() => {
-        const session = sessionRegistry.get(token);
-        if (session) {
-            sessionRegistry.delete(token);
-            session.client.dispose();
-        }
-    }, idleTimeoutMs);
-    idleTimer.unref?.();
-    sessionRegistry.set(token, { client, rounds, idleTimer, idleTimeoutMs, headful, browserPath });
-}
-/**
- * Remove a paused session from the registry and return it, stopping its idle
- * timer. The caller now owns the client (to resume or dispose). Returns
- * undefined if the token is unknown (expired/reaped/already completed).
- */
-export function takeSession(token) {
-    const session = sessionRegistry.get(token);
-    if (!session)
-        return undefined;
-    clearTimeout(session.idleTimer);
-    sessionRegistry.delete(token);
-    return session;
-}
-/** Dispose every parked session. Used on shutdown and in tests. */
-export function disposeAllSessions() {
-    for (const [, session] of sessionRegistry) {
-        clearTimeout(session.idleTimer);
-        session.client.dispose();
-    }
-    sessionRegistry.clear();
-    disposeIdleClient();
-}
-/** Number of currently parked sessions (for tests/diagnostics). */
-export function pausedSessionCount() {
-    return sessionRegistry.size;
-}
-let sharedIdleClient = null;
-/**
- * Try to reclaim the shared idle client if its browser config matches.
- * Returns the live client (and clears the slot) on match, or null.
- */
-export function takeIdleClient(headful, browserPath, _idleTimeoutMs = BROWSERTOOLS_DEFAULT_IDLE_MS) {
-    if (!sharedIdleClient)
-        return null;
-    clearTimeout(sharedIdleClient.idleTimer);
-    if (sharedIdleClient.headful === headful && sharedIdleClient.browserPath === browserPath) {
-        const client = sharedIdleClient.client;
-        sharedIdleClient = null;
-        return client;
-    }
-    // Config changed — dispose the stale idle client.
-    sharedIdleClient.client.dispose();
-    sharedIdleClient = null;
-    return null;
-}
-/**
- * Park a completed/failed flow's client as idle so the next browser_run call
- * can reuse the same Chromium process and live-view port.
- */
-export function parkIdleClient(client, headful, browserPath, idleTimeoutMs = BROWSERTOOLS_DEFAULT_IDLE_MS) {
-    if (sharedIdleClient) {
-        clearTimeout(sharedIdleClient.idleTimer);
-        sharedIdleClient.client.dispose();
-    }
-    const idleTimer = setTimeout(() => {
-        if (sharedIdleClient?.client === client) {
-            client.dispose();
-            sharedIdleClient = null;
-        }
-    }, idleTimeoutMs);
-    idleTimer.unref?.();
-    sharedIdleClient = { client, headful, browserPath, idleTimer };
-}
-/** Dispose the shared idle client. Called on session shutdown. */
-export function disposeIdleClient() {
-    if (sharedIdleClient) {
-        clearTimeout(sharedIdleClient.idleTimer);
-        sharedIdleClient.client.dispose();
-        sharedIdleClient = null;
-    }
-}
-/** Number of currently idle shared clients (0 or 1, for tests/diagnostics). */
-export function idleClientCount() {
-    return sharedIdleClient ? 1 : 0;
-}
-//# sourceMappingURL=browsertools-shared.js.map

package/dist/core/tools/browser/browsertools-shared.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"browsertools-shared.js","sourceRoot":"","sources":["../../../../src/core/tools/browser/browsertools-shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared plumbing for the `browser_run` and `browser_continue` tools.\n *\n * Unlike `webtools` (one-shot fetch/search subprocesses), `browsertools` drives\n * a *stateful* parent-in-the-loop protocol: a single long-lived `browsertools\n * serve` process holds the live Chromium and the paused-flow state in memory,\n * and the parent (hoocode) talks to it over newline-delimited JSON-RPC on\n * stdin/stdout. A flow can suspend mid-replay with `Outcome::NeedsParent`,\n * yielding a typed `ParentRequest` + `ResumeToken`; the parent reasons about it\n * (often by looking at a screenshot) and calls `flow_resume(token, response)` to\n * continue. See https://github.com/kolisachint/browsertools (contract.rs).\n *\n * Because that single serve process must survive *between* the `browser_run`\n * call that starts the flow and the `browser_continue` call that answers a\n * `NeedsParent`, this module owns a process-wide {@link sessionRegistry} keyed by\n * `ResumeToken`. Each paused session keeps its serve client alive and is reaped\n * after an idle timeout so an abandoned flow never leaks a Chromium forever.\n *\n * This module owns:\n * - the persistent JSON-RPC serve client (id-correlated request/response),\n * - the locked contract types (mirrors browsertools `src/contract.rs`),\n * - the paused-session registry + lifecycle (idle reap, round cap, teardown),\n * - binary + browser-path resolution.\n */\n\nimport { type ChildProcess, spawn } from \"node:child_process\";\nimport { ensureTool } from \"../../../utils/tools-manager.js\";\n\n// ============================================================================\n// Contract types (locked against browsertools `src/contract.rs`)\n// ============================================================================\n\n/** Opaque token identifying a paused flow, returned with every `NeedsParent`. */\nexport type ResumeToken = string;\n\n/** Reference to bytes (e.g. a screenshot) the parent can fetch via `get_resource`. */\nexport type ResourceId = string;\n\n/**\n * A typed request the engine yields when replay hits ambiguity only an LLM can\n * resolve. The `request` discriminant matches the serde tag in contract.rs.\n * Fields beyond the discriminant are passed through verbatim to the model.\n */\nexport interface ParentRequest {\n\trequest: \"classify_state\" | \"verify_visual\" | \"extract_semantic\" | \"decide_next_action\" | \"reidentify_element\";\n\t/** Resource id of the screenshot captured at the suspension point, if any. */\n\tscreenshot_ref?: ResourceId;\n\t[key: string]: unknown;\n}\n\n/** Result of a `flow_start` / `flow_resume` RPC (the `result` field's `outcome`). */\nexport type FlowOutcome =\n\t| { outcome: \"complete\"; result?: unknown }\n\t| { outcome: \"needs_parent\"; request: ParentRequest; token: ResumeToken }\n\t| { outcome: \"failed\"; step_id?: string; kind?: string; detail?: string };\n\n/** Result of a `get_resource` RPC. */\nexport interface GetResourceResult {\n\tref: ResourceId;\n\tmime: string;\n\tlen: number;\n\tpng_base64: string;\n}\n\n// ============================================================================\n// Configuration\n// ============================================================================\n\n/** Default per-request RPC timeout. Flow steps drive a real browser, so this is\n *  generous relative to webtools' 15s. */\nexport const BROWSERTOOLS_REQUEST_TIMEOUT_MS = 120_000;\n\n/** Default idle window a paused flow may sit in the registry before it is reaped\n *  (killing its serve process + Chromium). Reset on every resume round. The\n *  parent may reason / look at a screenshot / make other tool calls between\n *  rounds, so this is minutes, not seconds. */\nexport const BROWSERTOOLS_DEFAULT_IDLE_MS = 5 * 60 * 1000;\n\n/** Default hard cap on `NeedsParent` rounds for a single flow, bounding a runaway\n *  suspend/resume loop. */\nexport const BROWSERTOOLS_DEFAULT_MAX_ROUNDS = 12;\n\n/** Options threaded into the browser tools by their factories (tests/overrides). */\nexport interface BrowsertoolsToolOptions {\n\t/** Explicit path to the `browsertools` binary; otherwise resolved via {@link ensureTool}. */\n\tbinaryPath?: string;\n\t/** Chromium/Chrome executable path forwarded to the serve process. */\n\tbrowserPath?: string;\n\t/** Idle reap window for paused sessions (ms). */\n\tidleTimeoutMs?: number;\n\t/** Hard cap on NeedsParent rounds per flow. */\n\tmaxParentRounds?: number;\n\t/** Per-request RPC timeout (ms). */\n\trequestTimeoutMs?: number;\n\t/** Extra args appended after `serve` (mainly for tests). */\n\tserveArgs?: string[];\n\t/** Launch a real on-screen Chromium window instead of headless (sets\n\t *  `BROWSERTOOLS_HEADFUL=1` on the serve process). */\n\theadful?: boolean;\n\t/** Default the streamed live viewer on for every flow (the per-call `live_view`\n\t *  param still overrides). Set by the --enable-browser-live-preview flag. */\n\tliveView?: boolean;\n}\n\nfunction envNumber(name: string): number | undefined {\n\tconst raw = process.env[name];\n\tif (!raw) return undefined;\n\tconst n = Number(raw);\n\treturn Number.isFinite(n) && n > 0 ? n : undefined;\n}\n\n/** Resolve effective options from explicit overrides, then env, then defaults. */\nexport function resolveBrowsertoolsOptions(options?: BrowsertoolsToolOptions): Required<\n\tPick<BrowsertoolsToolOptions, \"idleTimeoutMs\" | \"maxParentRounds\" | \"requestTimeoutMs\">\n> & {\n\tbinaryPath?: string;\n\tbrowserPath?: string;\n\tserveArgs: string[];\n\theadful: boolean;\n\tliveView: boolean;\n} {\n\treturn {\n\t\tbinaryPath: options?.binaryPath,\n\t\tbrowserPath: options?.browserPath ?? (process.env.HOOCODE_BROWSERTOOLS_BROWSER_PATH?.trim() || undefined),\n\t\theadful: options?.headful ?? false,\n\t\tliveView: options?.liveView ?? false,\n\t\tidleTimeoutMs:\n\t\t\toptions?.idleTimeoutMs ?? envNumber(\"HOOCODE_BROWSERTOOLS_IDLE_MS\") ?? BROWSERTOOLS_DEFAULT_IDLE_MS,\n\t\tmaxParentRounds:\n\t\t\toptions?.maxParentRounds ?? envNumber(\"HOOCODE_BROWSERTOOLS_MAX_ROUNDS\") ?? BROWSERTOOLS_DEFAULT_MAX_ROUNDS,\n\t\trequestTimeoutMs:\n\t\t\toptions?.requestTimeoutMs ??\n\t\t\tenvNumber(\"HOOCODE_BROWSERTOOLS_REQUEST_TIMEOUT_MS\") ??\n\t\t\tBROWSERTOOLS_REQUEST_TIMEOUT_MS,\n\t\tserveArgs: options?.serveArgs ?? [],\n\t};\n}\n\nconst BINARY_MISSING_MESSAGE =\n\t\"browsertools binary unavailable and could not be downloaded — the browser tools require the `browsertools` CLI on PATH or a published release for this platform\";\n\n/** Resolve the `browsertools` binary path (explicit override, else download/PATH). */\nexport async function resolveBrowsertoolsBinary(options?: BrowsertoolsToolOptions): Promise<string> {\n\tif (options?.binaryPath) return options.binaryPath;\n\tconst binaryPath = await ensureTool(\"browsertools\", true);\n\tif (!binaryPath) throw new Error(BINARY_MISSING_MESSAGE);\n\treturn binaryPath;\n}\n\n// ============================================================================\n// Persistent JSON-RPC serve client\n// ============================================================================\n\ninterface PendingRequest {\n\tresolve: (value: unknown) => void;\n\treject: (error: Error) => void;\n\ttimer: ReturnType<typeof setTimeout>;\n}\n\n/**\n * A live `browsertools serve` process spoken to over newline-delimited JSON-RPC.\n *\n * Wire format (browsertools `src/serve.rs`):\n *   request:  `{ \"id\": <n>, \"method\": <string>, \"params\": <object> }\\n`\n *   response: `{ \"id\": <n>, \"result\": <value> }` or `{ \"id\": <n>, \"error\": <RpcError> }`\\n\n *\n * Responses are correlated by `id`, so concurrent requests are safe, though the\n * tools drive it sequentially.\n */\nexport class BrowsertoolsServeClient {\n\t/** URL of the live viewer once `live_view_start` has been issued for this\n\t *  serve process, cached so a reused (reclaimed-idle) client does not start a\n\t *  second viewer or auto-open another OS tab on the next browser_run call. */\n\tliveViewUrl?: string;\n\tprivate readonly proc: ChildProcess;\n\tprivate readonly pending = new Map<number, PendingRequest>();\n\tprivate readonly requestTimeoutMs: number;\n\tprivate buffer = \"\";\n\tprivate nextId = 1;\n\tprivate closed = false;\n\tprivate exitError: Error | undefined;\n\tprivate stderrTail = \"\";\n\n\tconstructor(\n\t\tbinaryPath: string,\n\t\topts: {\n\t\t\tcwd?: string;\n\t\t\tbrowserPath?: string;\n\t\t\tserveArgs: string[];\n\t\t\trequestTimeoutMs: number;\n\t\t\theadful?: boolean;\n\t\t},\n\t) {\n\t\tthis.requestTimeoutMs = opts.requestTimeoutMs;\n\t\t// The exact CLI flag for the browser path is not part of the locked RPC\n\t\t// contract; v0.1.3 added a \"configurable browser path\". We forward it via\n\t\t// env vars the binary is likely to read. Passing extra env is harmless if\n\t\t// the binary ignores them, and centralizing it here makes it a one-line\n\t\t// change once the exact mechanism is confirmed.\n\t\tconst env = { ...process.env };\n\t\tif (opts.browserPath) {\n\t\t\tenv.BROWSERTOOLS_BROWSER_PATH = opts.browserPath;\n\t\t\tenv.CHROME_PATH = opts.browserPath;\n\t\t}\n\t\t// Opt into a real on-screen Chromium window. The serve process reads this\n\t\t// in `Driver::launch`; harmless if an older binary ignores it.\n\t\tif (opts.headful) {\n\t\t\tenv.BROWSERTOOLS_HEADFUL = \"1\";\n\t\t}\n\t\t// Run the serve process in the project cwd so relative flow paths and the\n\t\t// evidence store resolve the same way the user expects.\n\t\tthis.proc = spawn(binaryPath, [\"serve\", ...opts.serveArgs], {\n\t\t\tcwd: opts.cwd,\n\t\t\tshell: false,\n\t\t\tstdio: [\"pipe\", \"pipe\", \"pipe\"],\n\t\t\tenv,\n\t\t});\n\t\tthis.proc.stdout?.setEncoding(\"utf8\");\n\t\tthis.proc.stdout?.on(\"data\", (chunk: string) => this.onStdout(chunk));\n\t\tthis.proc.stderr?.setEncoding(\"utf8\");\n\t\tthis.proc.stderr?.on(\"data\", (chunk: string) => {\n\t\t\t// Keep only a bounded tail so a chatty serve can't grow unbounded; it is\n\t\t\t// surfaced in the error when the process dies unexpectedly.\n\t\t\tthis.stderrTail = (this.stderrTail + chunk).slice(-4000);\n\t\t});\n\t\tthis.proc.on(\"error\", (err) => this.fail(err instanceof Error ? err : new Error(String(err))));\n\t\tthis.proc.on(\"exit\", (code, sig) => {\n\t\t\tif (this.closed) return;\n\t\t\tconst detail = this.stderrTail.trim();\n\t\t\tthis.fail(\n\t\t\t\tnew Error(\n\t\t\t\t\t`browsertools serve exited unexpectedly (code=${code ?? \"null\"}, signal=${sig ?? \"null\"})` +\n\t\t\t\t\t\t(detail ? `: ${detail}` : \"\"),\n\t\t\t\t),\n\t\t\t);\n\t\t});\n\t}\n\n\tprivate onStdout(chunk: string): void {\n\t\tthis.buffer += chunk;\n\t\tlet newlineIndex = this.buffer.indexOf(\"\\n\");\n\t\twhile (newlineIndex !== -1) {\n\t\t\tconst line = this.buffer.slice(0, newlineIndex).trim();\n\t\t\tthis.buffer = this.buffer.slice(newlineIndex + 1);\n\t\t\tif (line) this.onLine(line);\n\t\t\tnewlineIndex = this.buffer.indexOf(\"\\n\");\n\t\t}\n\t}\n\n\tprivate onLine(line: string): void {\n\t\tlet message: { id?: unknown; result?: unknown; error?: unknown };\n\t\ttry {\n\t\t\tmessage = JSON.parse(line);\n\t\t} catch {\n\t\t\t// Non-JSON noise on stdout (shouldn't happen; logs go to stderr). Skip it\n\t\t\t// rather than corrupt id correlation.\n\t\t\treturn;\n\t\t}\n\t\tconst id = typeof message.id === \"number\" ? message.id : undefined;\n\t\tif (id === undefined) return;\n\t\tconst entry = this.pending.get(id);\n\t\tif (!entry) return;\n\t\tthis.pending.delete(id);\n\t\tclearTimeout(entry.timer);\n\t\tif (message.error !== undefined && message.error !== null) {\n\t\t\tentry.reject(new Error(`browsertools ${describeRpcError(message.error)}`));\n\t\t} else {\n\t\t\tentry.resolve(message.result);\n\t\t}\n\t}\n\n\t/** Reject all in-flight requests and mark the client dead. Idempotent. */\n\tprivate fail(error: Error): void {\n\t\tif (this.closed) return;\n\t\tthis.exitError = error;\n\t\tfor (const [, entry] of this.pending) {\n\t\t\tclearTimeout(entry.timer);\n\t\t\tentry.reject(error);\n\t\t}\n\t\tthis.pending.clear();\n\t}\n\n\t/** Send a JSON-RPC request and resolve with its `result` (or reject on `error`). */\n\trequest<T = unknown>(method: string, params: Record<string, unknown>): Promise<T> {\n\t\tif (this.closed) {\n\t\t\treturn Promise.reject(this.exitError ?? new Error(\"browsertools serve client is closed\"));\n\t\t}\n\t\tconst id = this.nextId++;\n\t\treturn new Promise<T>((resolve, reject) => {\n\t\t\tconst timer = setTimeout(() => {\n\t\t\t\tif (this.pending.delete(id)) {\n\t\t\t\t\treject(new Error(`browsertools ${method} timed out after ${this.requestTimeoutMs}ms`));\n\t\t\t\t}\n\t\t\t}, this.requestTimeoutMs);\n\t\t\tthis.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer });\n\t\t\tconst payload = `${JSON.stringify({ id, method, params })}\\n`;\n\t\t\tthis.proc.stdin?.write(payload, (err) => {\n\t\t\t\tif (err && this.pending.delete(id)) {\n\t\t\t\t\tclearTimeout(timer);\n\t\t\t\t\treject(err);\n\t\t\t\t}\n\t\t\t});\n\t\t});\n\t}\n\n\t/** Kill the serve process and reject any outstanding requests. Idempotent. */\n\tdispose(): void {\n\t\tif (this.closed) return;\n\t\tthis.fail(new Error(\"browsertools serve client disposed\"));\n\t\tthis.closed = true;\n\t\t// Best-effort graceful shutdown, then ensure the process is gone.\n\t\ttry {\n\t\t\tthis.proc.stdin?.write(`${JSON.stringify({ id: this.nextId++, method: \"shutdown\", params: {} })}\\n`);\n\t\t} catch {\n\t\t\t// stdin may already be closed; fall through to kill.\n\t\t}\n\t\tthis.proc.stdin?.end();\n\t\tthis.proc.kill(\"SIGTERM\");\n\t\tconst proc = this.proc;\n\t\tsetTimeout(() => {\n\t\t\tif (proc.exitCode === null && proc.signalCode === null) proc.kill(\"SIGKILL\");\n\t\t}, 3000).unref?.();\n\t}\n}\n\nfunction describeRpcError(error: unknown): string {\n\tif (error && typeof error === \"object\") {\n\t\tconst message = (error as { message?: unknown }).message;\n\t\tif (typeof message === \"string\" && message) return message;\n\t}\n\tif (typeof error === \"string\" && error) return error;\n\treturn `RPC error: ${JSON.stringify(error)}`;\n}\n\n// ============================================================================\n// Paused-session registry (process-wide, keyed by ResumeToken)\n// ============================================================================\n\ninterface PausedSession {\n\tclient: BrowsertoolsServeClient;\n\t/** Number of NeedsParent rounds yielded so far for this flow. */\n\trounds: number;\n\tidleTimer: ReturnType<typeof setTimeout>;\n\tidleTimeoutMs: number;\n\t/** Whether the browser was launched in headful mode for this session. */\n\theadful: boolean;\n\t/** Explicit browser path used for this session, if any. */\n\tbrowserPath?: string;\n}\n\nconst sessionRegistry = new Map<ResumeToken, PausedSession>();\n\n/**\n * Park a paused flow's live serve client under its resume token and arm the idle\n * reaper. Any previous entry for the token is disposed first.\n */\nexport function parkSession(\n\ttoken: ResumeToken,\n\tclient: BrowsertoolsServeClient,\n\trounds: number,\n\tidleTimeoutMs: number,\n\theadful = false,\n\tbrowserPath?: string,\n): void {\n\tconst existing = sessionRegistry.get(token);\n\tif (existing && existing.client !== client) {\n\t\tclearTimeout(existing.idleTimer);\n\t\texisting.client.dispose();\n\t}\n\tconst idleTimer = setTimeout(() => {\n\t\tconst session = sessionRegistry.get(token);\n\t\tif (session) {\n\t\t\tsessionRegistry.delete(token);\n\t\t\tsession.client.dispose();\n\t\t}\n\t}, idleTimeoutMs);\n\tidleTimer.unref?.();\n\tsessionRegistry.set(token, { client, rounds, idleTimer, idleTimeoutMs, headful, browserPath });\n}\n\n/**\n * Remove a paused session from the registry and return it, stopping its idle\n * timer. The caller now owns the client (to resume or dispose). Returns\n * undefined if the token is unknown (expired/reaped/already completed).\n */\nexport function takeSession(token: ResumeToken): PausedSession | undefined {\n\tconst session = sessionRegistry.get(token);\n\tif (!session) return undefined;\n\tclearTimeout(session.idleTimer);\n\tsessionRegistry.delete(token);\n\treturn session;\n}\n\n/** Dispose every parked session. Used on shutdown and in tests. */\nexport function disposeAllSessions(): void {\n\tfor (const [, session] of sessionRegistry) {\n\t\tclearTimeout(session.idleTimer);\n\t\tsession.client.dispose();\n\t}\n\tsessionRegistry.clear();\n\tdisposeIdleClient();\n}\n\n/** Number of currently parked sessions (for tests/diagnostics). */\nexport function pausedSessionCount(): number {\n\treturn sessionRegistry.size;\n}\n\n// ============================================================================\n// Shared idle client (one per session, reused across browser_run calls)\n// ============================================================================\n\n/** Configuration preserved from the original flow call so the idle client can\n *  be matched and reused by a subsequent browser_run with the same settings. */\nexport interface BrowserClientConfig {\n\theadful: boolean;\n\tbrowserPath?: string;\n\tidleTimeoutMs: number;\n}\n\ninterface IdleClientEntry {\n\tclient: BrowsertoolsServeClient;\n\theadful: boolean;\n\tbrowserPath?: string;\n\tidleTimer: ReturnType<typeof setTimeout>;\n}\n\nlet sharedIdleClient: IdleClientEntry | null = null;\n\n/**\n * Try to reclaim the shared idle client if its browser config matches.\n * Returns the live client (and clears the slot) on match, or null.\n */\nexport function takeIdleClient(\n\theadful: boolean,\n\tbrowserPath?: string,\n\t_idleTimeoutMs: number = BROWSERTOOLS_DEFAULT_IDLE_MS,\n): BrowsertoolsServeClient | null {\n\tif (!sharedIdleClient) return null;\n\tclearTimeout(sharedIdleClient.idleTimer);\n\tif (sharedIdleClient.headful === headful && sharedIdleClient.browserPath === browserPath) {\n\t\tconst client = sharedIdleClient.client;\n\t\tsharedIdleClient = null;\n\t\treturn client;\n\t}\n\t// Config changed — dispose the stale idle client.\n\tsharedIdleClient.client.dispose();\n\tsharedIdleClient = null;\n\treturn null;\n}\n\n/**\n * Park a completed/failed flow's client as idle so the next browser_run call\n * can reuse the same Chromium process and live-view port.\n */\nexport function parkIdleClient(\n\tclient: BrowsertoolsServeClient,\n\theadful: boolean,\n\tbrowserPath?: string,\n\tidleTimeoutMs: number = BROWSERTOOLS_DEFAULT_IDLE_MS,\n): void {\n\tif (sharedIdleClient) {\n\t\tclearTimeout(sharedIdleClient.idleTimer);\n\t\tsharedIdleClient.client.dispose();\n\t}\n\tconst idleTimer = setTimeout(() => {\n\t\tif (sharedIdleClient?.client === client) {\n\t\t\tclient.dispose();\n\t\t\tsharedIdleClient = null;\n\t\t}\n\t}, idleTimeoutMs);\n\tidleTimer.unref?.();\n\tsharedIdleClient = { client, headful, browserPath, idleTimer };\n}\n\n/** Dispose the shared idle client. Called on session shutdown. */\nexport function disposeIdleClient(): void {\n\tif (sharedIdleClient) {\n\t\tclearTimeout(sharedIdleClient.idleTimer);\n\t\tsharedIdleClient.client.dispose();\n\t\tsharedIdleClient = null;\n\t}\n}\n\n/** Number of currently idle shared clients (0 or 1, for tests/diagnostics). */\nexport function idleClientCount(): number {\n\treturn sharedIdleClient ? 1 : 0;\n}\n"]}