@kolisachint/hoocode-agent 0.4.94 → 0.4.96

package/dist/core/tools/browser-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-flow.js","sourceRoot":"","sources":["../../../src/core/tools/browser-flow.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `browser_flow` tool: start a deterministic browsertools flow.\n *\n * Spawns a `browsertools serve` process and issues `flow_start`. If the flow\n * runs to completion deterministically it returns the evidence inline. If replay\n * hits a point only an LLM can resolve, the serve process suspends with\n * `Outcome::NeedsParent`: this tool fetches the suspension screenshot, parks the\n * live session under its `ResumeToken`, and returns the typed `ParentRequest`\n * (plus the screenshot as an image) to the agent. The agent reasons and answers\n * with the companion `browser_resume` tool. See {@link browsertools-shared}.\n */\n\nimport type { AgentTool } from \"@kolisachint/hoocode-agent-core\";\nimport type { ImageContent, TextContent } from \"@kolisachint/hoocode-ai\";\nimport { type Static, Type } from \"typebox\";\nimport type { AgentToolResult } from \"../extensions/types.js\";\nimport { defineTool, type ToolDefinition } from \"../extensions/types.js\";\nimport {\n\tBrowsertoolsServeClient,\n\ttype BrowsertoolsToolOptions,\n\ttype FlowOutcome,\n\ttype GetResourceResult,\n\ttype ParentRequest,\n\tparkSession,\n\ttype ResumeToken,\n\tresolveBrowsertoolsBinary,\n\tresolveBrowsertoolsOptions,\n} from \"./browsertools-shared.js\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.js\";\n\nconst browserFlowSchema = Type.Object({\n\tflow_path: Type.Optional(\n\t\tType.String({ description: \"Path to the .flow.json file to execute. Provide this or `flow`.\" }),\n\t),\n\tflow: Type.Optional(\n\t\tType.Record(Type.String(), Type.Unknown(), {\n\t\t\tdescription: \"Inline flow definition object (alternative to `flow_path`).\",\n\t\t}),\n\t),\n\tvars: Type.Optional(\n\t\tType.Record(Type.String(), Type.Unknown(), {\n\t\t\tdescription: \"Variables interpolated into the flow ({{var}} placeholders).\",\n\t\t}),\n\t),\n\tstore: Type.Optional(Type.String({ description: \"Path to the evidence store directory for this run.\" })),\n});\n\nexport type BrowserFlowInput = Static<typeof browserFlowSchema>;\n\n/** Structured details surfaced alongside the model-facing content. */\nexport interface BrowserFlowDetails {\n\tstatus: \"complete\" | \"needs_parent\";\n\t/** Present when status is \"needs_parent\": resume with this token. */\n\ttoken?: ResumeToken;\n\t/** Present when status is \"needs_parent\": the kind of parent request. */\n\trequestKind?: ParentRequest[\"request\"];\n\t/** Present when status is \"complete\": the flow result/evidence. */\n\tresult?: unknown;\n}\n\nexport interface BrowserFlowToolOptions extends BrowsertoolsToolOptions {}\n\n/** ParentResponse shape hint per ParentRequest kind (mirrors contract.rs). */\nfunction parentResponseHint(kind: ParentRequest[\"request\"]): string {\n\tswitch (kind) {\n\t\tcase \"classify_state\":\n\t\t\treturn 'Reply with browser_resume response: { \"response\": \"state\", \"state\": \"<your label>\" }';\n\t\tcase \"verify_visual\":\n\t\t\treturn 'Reply with browser_resume response: { \"response\": \"verified\", \"passed\": true | false }';\n\t\tcase \"extract_semantic\":\n\t\t\treturn 'Reply with browser_resume response: { \"response\": \"extracted\", \"fields\": { \"<field>\": \"<value>\", ... } }';\n\t\tcase \"decide_next_action\":\n\t\t\treturn 'Reply with browser_resume response: { \"response\": \"next_action\", \"action\": <action object> }';\n\t\tcase \"reidentify_element\":\n\t\t\treturn 'Reply with browser_resume response: { \"response\": \"element\", \"selector\": \"<css selector>\" }';\n\t\tdefault:\n\t\t\treturn \"Reply with browser_resume providing the appropriate ParentResponse object.\";\n\t}\n}\n\n/** Fetch the suspension screenshot for a ParentRequest as an ImageContent block.\n *  Best-effort: a fetch failure degrades to no image rather than failing the flow. */\nasync function fetchScreenshot(\n\tclient: BrowsertoolsServeClient,\n\trequest: ParentRequest,\n): Promise<ImageContent | undefined> {\n\tif (!request.screenshot_ref) return undefined;\n\ttry {\n\t\tconst resource = await client.request<GetResourceResult>(\"get_resource\", { ref: request.screenshot_ref });\n\t\tif (!resource?.png_base64) return undefined;\n\t\treturn { type: \"image\", data: resource.png_base64, mimeType: resource.mime || \"image/png\" };\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/**\n * Map a `flow_start`/`flow_resume` outcome to a tool result, owning the live\n * client: dispose it on terminal outcomes, or park it under the new resume token\n * when the flow suspends again. `rounds` is the number of NeedsParent yields seen\n * so far for this flow (including the one being processed), used for the cap.\n */\nexport async function advanceFlow(\n\tclient: BrowsertoolsServeClient,\n\toutcome: FlowOutcome,\n\trounds: number,\n\topts: ReturnType<typeof resolveBrowsertoolsOptions>,\n): Promise<AgentToolResult<BrowserFlowDetails>> {\n\tif (outcome.outcome === \"complete\") {\n\t\tclient.dispose();\n\t\tconst result = outcome.result;\n\t\treturn {\n\t\t\tcontent: [{ type: \"text\", text: `Flow complete.\\n${JSON.stringify(result ?? {}, null, 2)}` }],\n\t\t\tdetails: { status: \"complete\", result },\n\t\t};\n\t}\n\n\tif (outcome.outcome === \"failed\") {\n\t\tclient.dispose();\n\t\tconst where = outcome.step_id ? ` at step \"${outcome.step_id}\"` : \"\";\n\t\tconst kind = outcome.kind ? ` (${outcome.kind})` : \"\";\n\t\tthrow new Error(`browsertools flow failed${where}: ${outcome.detail ?? \"unknown error\"}${kind}`);\n\t}\n\n\tif (outcome.outcome === \"needs_parent\") {\n\t\tif (rounds > opts.maxParentRounds) {\n\t\t\tclient.dispose();\n\t\t\tthrow new Error(\n\t\t\t\t`browsertools flow exceeded the maximum of ${opts.maxParentRounds} NeedsParent rounds; aborting to avoid a runaway loop`,\n\t\t\t);\n\t\t}\n\t\tconst { request, token } = outcome;\n\t\tconst image = await fetchScreenshot(client, request);\n\t\tparkSession(token, client, rounds, opts.idleTimeoutMs);\n\n\t\tconst text =\n\t\t\t`Flow suspended — parent decision required (NeedsParent).\\n` +\n\t\t\t`request: ${JSON.stringify(request, null, 2)}\\n` +\n\t\t\t`resume token: ${token}\\n` +\n\t\t\t`${parentResponseHint(request.request)}\\n` +\n\t\t\t(image ? \"A screenshot of the current page is attached.\" : \"(no screenshot available)\");\n\t\tconst content: (TextContent | ImageContent)[] = [{ type: \"text\", text }];\n\t\tif (image) content.push(image);\n\t\treturn {\n\t\t\tcontent,\n\t\t\tdetails: { status: \"needs_parent\", token, requestKind: request.request },\n\t\t};\n\t}\n\n\tclient.dispose();\n\tthrow new Error(`browsertools returned an unrecognized flow outcome: ${JSON.stringify(outcome)}`);\n}\n\nexport function createBrowserFlowToolDefinition(\n\tcwd: string,\n\toptions?: BrowserFlowToolOptions,\n): ToolDefinition<typeof browserFlowSchema, BrowserFlowDetails> {\n\tconst opts = resolveBrowsertoolsOptions(options);\n\treturn defineTool({\n\t\tname: \"browser_flow\",\n\t\tlabel: \"browser flow\",\n\t\tdescription:\n\t\t\t\"Start a deterministic browser flow (browsertools). Runs a saved .flow.json (or inline flow) \" +\n\t\t\t\"against a headless browser and returns the evidence on completion. If the flow needs an LLM \" +\n\t\t\t\"decision mid-replay (classify a page state, verify a visual, extract a value, decide the next \" +\n\t\t\t\"action, or re-identify a drifted element) it suspends and returns a typed request plus a \" +\n\t\t\t\"screenshot; answer it with the browser_resume tool using the returned token. Off by default; \" +\n\t\t\t\"enabled with --enable-browsertools.\",\n\t\tpromptSnippet: \"Run a deterministic browser flow, pausing for LLM decisions when needed\",\n\t\tparameters: browserFlowSchema,\n\t\tasync execute(_toolCallId, params: BrowserFlowInput, signal) {\n\t\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\t\t\tif (!params.flow_path && !params.flow) {\n\t\t\t\tthrow new Error(\"browser_flow requires either `flow_path` or `flow`\");\n\t\t\t}\n\n\t\t\tconst binaryPath = await resolveBrowsertoolsBinary(options);\n\t\t\tconst client = new BrowsertoolsServeClient(binaryPath, {\n\t\t\t\tcwd,\n\t\t\t\tbrowserPath: opts.browserPath,\n\t\t\t\tserveArgs: opts.serveArgs,\n\t\t\t\trequestTimeoutMs: opts.requestTimeoutMs,\n\t\t\t});\n\n\t\t\t// If the call is aborted before we hand the client to the registry, make\n\t\t\t// sure the serve process is torn down.\n\t\t\tconst onAbort = () => client.dispose();\n\t\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\ttry {\n\t\t\t\tconst startParams: Record<string, unknown> = {};\n\t\t\t\tif (params.flow_path) startParams.flow_path = params.flow_path;\n\t\t\t\tif (params.flow) startParams.flow = params.flow;\n\t\t\t\tif (params.vars) startParams.vars = params.vars;\n\t\t\t\tif (params.store) startParams.store = params.store;\n\n\t\t\t\tconst outcome = await client.request<FlowOutcome>(\"flow_start\", startParams);\n\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\tclient.dispose();\n\t\t\t\t\tthrow new Error(\"Operation aborted\");\n\t\t\t\t}\n\t\t\t\treturn await advanceFlow(client, outcome, 1, opts);\n\t\t\t} catch (error) {\n\t\t\t\tclient.dispose();\n\t\t\t\tthrow error;\n\t\t\t} finally {\n\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t}\n\t\t},\n\t});\n}\n\nexport function createBrowserFlowTool(\n\tcwd: string,\n\toptions?: BrowserFlowToolOptions,\n): AgentTool<typeof browserFlowSchema> {\n\treturn wrapToolDefinition(createBrowserFlowToolDefinition(cwd, options));\n}\n"]}

package/dist/core/tools/browser-resume.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `browser_resume` tool: answer a `NeedsParent` suspension from `browser_flow`.
+ *
+ * Looks up the paused serve session by its `ResumeToken`, issues `flow_resume`
+ * with the parent's decision (a `ParentResponse` object), and maps the next
+ * outcome the same way `browser_flow` does — completing, failing, or suspending
+ * again with a fresh token. The live serve process (and its browser state) is
+ * reused across rounds. See {@link browsertools-shared}.
+ */
+import type { AgentTool } from "@kolisachint/hoocode-agent-core";
+import { type Static, Type } from "typebox";
+import { type ToolDefinition } from "../extensions/types.js";
+import { type BrowserFlowDetails } from "./browser-flow.js";
+import { type BrowsertoolsToolOptions } from "./browsertools-shared.js";
+declare const browserResumeSchema: Type.TObject<{
+    token: Type.TString;
+    response: Type.TRecord<"^.*$", Type.TUnknown>;
+}>;
+export type BrowserResumeInput = Static<typeof browserResumeSchema>;
+export interface BrowserResumeToolOptions extends BrowsertoolsToolOptions {
+}
+export declare function createBrowserResumeToolDefinition(_cwd: string, options?: BrowserResumeToolOptions): ToolDefinition<typeof browserResumeSchema, BrowserFlowDetails>;
+export declare function createBrowserResumeTool(cwd: string, options?: BrowserResumeToolOptions): AgentTool<typeof browserResumeSchema>;
+export {};
+//# sourceMappingURL=browser-resume.d.ts.map

package/dist/core/tools/browser-resume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-resume.d.ts","sourceRoot":"","sources":["../../../src/core/tools/browser-resume.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EACN,KAAK,uBAAuB,EAI5B,MAAM,0BAA0B,CAAC;AAGlC,QAAA,MAAM,mBAAmB;;;EAOvB,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEpE,MAAM,WAAW,wBAAyB,SAAQ,uBAAuB;CAAG;AAE5E,wBAAgB,iCAAiC,CAGhD,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,wBAAwB,GAChC,cAAc,CAAC,OAAO,mBAAmB,EAAE,kBAAkB,CAAC,CA4ChE;AAED,wBAAgB,uBAAuB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,wBAAwB,GAChC,SAAS,CAAC,OAAO,mBAAmB,CAAC,CAEvC","sourcesContent":["/**\n * `browser_resume` tool: answer a `NeedsParent` suspension from `browser_flow`.\n *\n * Looks up the paused serve session by its `ResumeToken`, issues `flow_resume`\n * with the parent's decision (a `ParentResponse` object), and maps the next\n * outcome the same way `browser_flow` does — completing, failing, or suspending\n * again with a fresh token. The live serve process (and its browser state) is\n * reused across rounds. See {@link browsertools-shared}.\n */\n\nimport type { AgentTool } from \"@kolisachint/hoocode-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport { defineTool, type ToolDefinition } from \"../extensions/types.js\";\nimport { advanceFlow, type BrowserFlowDetails } from \"./browser-flow.js\";\nimport {\n\ttype BrowsertoolsToolOptions,\n\ttype FlowOutcome,\n\tresolveBrowsertoolsOptions,\n\ttakeSession,\n} from \"./browsertools-shared.js\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.js\";\n\nconst browserResumeSchema = Type.Object({\n\ttoken: Type.String({ description: \"The resume token returned by a browser_flow NeedsParent result.\" }),\n\tresponse: Type.Record(Type.String(), Type.Unknown(), {\n\t\tdescription:\n\t\t\t\"The ParentResponse object answering the request, e.g. \" +\n\t\t\t'{ \"response\": \"state\", \"state\": \"logged_in\" } or { \"response\": \"verified\", \"passed\": true }.',\n\t}),\n});\n\nexport type BrowserResumeInput = Static<typeof browserResumeSchema>;\n\nexport interface BrowserResumeToolOptions extends BrowsertoolsToolOptions {}\n\nexport function createBrowserResumeToolDefinition(\n\t// cwd is part of the factory signature for parity with other tools, but resume\n\t// reuses the serve process parked by browser_flow, so it is not needed here.\n\t_cwd: string,\n\toptions?: BrowserResumeToolOptions,\n): ToolDefinition<typeof browserResumeSchema, BrowserFlowDetails> {\n\tconst opts = resolveBrowsertoolsOptions(options);\n\treturn defineTool({\n\t\tname: \"browser_resume\",\n\t\tlabel: \"browser resume\",\n\t\tdescription:\n\t\t\t\"Resume a browser flow that suspended with a NeedsParent request. Pass the token from the \" +\n\t\t\t\"browser_flow result and a ParentResponse object answering the request. The flow continues \" +\n\t\t\t\"deterministically and either completes, fails, or suspends again with a new token. Off by \" +\n\t\t\t\"default; enabled with --enable-browsertools.\",\n\t\tparameters: browserResumeSchema,\n\t\tasync execute(_toolCallId, params: BrowserResumeInput, signal) {\n\t\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\n\t\t\tconst session = takeSession(params.token);\n\t\t\tif (!session) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`No paused browser flow for token \"${params.token}\" — it may have completed, expired (idle ` +\n\t\t\t\t\t\t`timeout), or never existed. Start a new flow with browser_flow.`,\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst { client } = session;\n\t\t\tconst onAbort = () => client.dispose();\n\t\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\ttry {\n\t\t\t\tconst outcome = await client.request<FlowOutcome>(\"flow_resume\", {\n\t\t\t\t\ttoken: params.token,\n\t\t\t\t\tresponse: params.response,\n\t\t\t\t});\n\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\tclient.dispose();\n\t\t\t\t\tthrow new Error(\"Operation aborted\");\n\t\t\t\t}\n\t\t\t\t// Count this resume as one more NeedsParent round if it suspends again.\n\t\t\t\treturn await advanceFlow(client, outcome, session.rounds + 1, opts);\n\t\t\t} catch (error) {\n\t\t\t\tclient.dispose();\n\t\t\t\tthrow error;\n\t\t\t} finally {\n\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t}\n\t\t},\n\t});\n}\n\nexport function createBrowserResumeTool(\n\tcwd: string,\n\toptions?: BrowserResumeToolOptions,\n): AgentTool<typeof browserResumeSchema> {\n\treturn wrapToolDefinition(createBrowserResumeToolDefinition(cwd, options));\n}\n"]}

package/dist/core/tools/browser-resume.js

@@ -0,0 +1,71 @@
+/**
+ * `browser_resume` tool: answer a `NeedsParent` suspension from `browser_flow`.
+ *
+ * Looks up the paused serve session by its `ResumeToken`, issues `flow_resume`
+ * with the parent's decision (a `ParentResponse` object), and maps the next
+ * outcome the same way `browser_flow` does — completing, failing, or suspending
+ * again with a fresh token. The live serve process (and its browser state) is
+ * reused across rounds. See {@link browsertools-shared}.
+ */
+import { Type } from "typebox";
+import { defineTool } from "../extensions/types.js";
+import { advanceFlow } from "./browser-flow.js";
+import { resolveBrowsertoolsOptions, takeSession, } from "./browsertools-shared.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+const browserResumeSchema = Type.Object({
+    token: Type.String({ description: "The resume token returned by a browser_flow NeedsParent result." }),
+    response: Type.Record(Type.String(), Type.Unknown(), {
+        description: "The ParentResponse object answering the request, e.g. " +
+            '{ "response": "state", "state": "logged_in" } or { "response": "verified", "passed": true }.',
+    }),
+});
+export function createBrowserResumeToolDefinition(
+// cwd is part of the factory signature for parity with other tools, but resume
+// reuses the serve process parked by browser_flow, so it is not needed here.
+_cwd, options) {
+    const opts = resolveBrowsertoolsOptions(options);
+    return defineTool({
+        name: "browser_resume",
+        label: "browser resume",
+        description: "Resume a browser flow that suspended with a NeedsParent request. Pass the token from the " +
+            "browser_flow result and a ParentResponse object answering the request. The flow continues " +
+            "deterministically and either completes, fails, or suspends again with a new token. Off by " +
+            "default; enabled with --enable-browsertools.",
+        parameters: browserResumeSchema,
+        async execute(_toolCallId, params, signal) {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            const session = takeSession(params.token);
+            if (!session) {
+                throw new Error(`No paused browser flow for token "${params.token}" — it may have completed, expired (idle ` +
+                    `timeout), or never existed. Start a new flow with browser_flow.`);
+            }
+            const { client } = session;
+            const onAbort = () => client.dispose();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            try {
+                const outcome = await client.request("flow_resume", {
+                    token: params.token,
+                    response: params.response,
+                });
+                if (signal?.aborted) {
+                    client.dispose();
+                    throw new Error("Operation aborted");
+                }
+                // Count this resume as one more NeedsParent round if it suspends again.
+                return await advanceFlow(client, outcome, session.rounds + 1, opts);
+            }
+            catch (error) {
+                client.dispose();
+                throw error;
+            }
+            finally {
+                signal?.removeEventListener("abort", onAbort);
+            }
+        },
+    });
+}
+export function createBrowserResumeTool(cwd, options) {
+    return wrapToolDefinition(createBrowserResumeToolDefinition(cwd, options));
+}
+//# sourceMappingURL=browser-resume.js.map

package/dist/core/tools/browser-resume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-resume.js","sourceRoot":"","sources":["../../../src/core/tools/browser-resume.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAe,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAuB,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAGN,0BAA0B,EAC1B,WAAW,GACX,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE,MAAM,mBAAmB,GAAG,IAAI,CAAC,MAAM,CAAC;IACvC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,iEAAiE,EAAE,CAAC;IACtG,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE;QACpD,WAAW,EACV,wDAAwD;YACxD,8FAA8F;KAC/F,CAAC;CACF,CAAC,CAAC;AAMH,MAAM,UAAU,iCAAiC;AAChD,+EAA+E;AAC/E,6EAA6E;AAC7E,IAAY,EACZ,OAAkC,EAC+B;IACjE,MAAM,IAAI,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,UAAU,CAAC;QACjB,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,gBAAgB;QACvB,WAAW,EACV,2FAA2F;YAC3F,4FAA4F;YAC5F,4FAA4F;YAC5F,8CAA8C;QAC/C,UAAU,EAAE,mBAAmB;QAC/B,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,MAA0B,EAAE,MAAM,EAAE;YAC9D,IAAI,MAAM,EAAE,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;YAE1D,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CACd,qCAAqC,MAAM,CAAC,KAAK,6CAA2C;oBAC3F,iEAAiE,CAClE,CAAC;YACH,CAAC;YAED,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;YAC3B,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACvC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,IAAI,CAAC;gBACJ,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,OAAO,CAAc,aAAa,EAAE;oBAChE,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;iBACzB,CAAC,CAAC;gBACH,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;oBACrB,MAAM,CAAC,OAAO,EAAE,CAAC;oBACjB,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;gBACtC,CAAC;gBACD,wEAAwE;gBACxE,OAAO,MAAM,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;YACrE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,CAAC,OAAO,EAAE,CAAC;gBACjB,MAAM,KAAK,CAAC;YACb,CAAC;oBAAS,CAAC;gBACV,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC/C,CAAC;QAAA,CACD;KACD,CAAC,CAAC;AAAA,CACH;AAED,MAAM,UAAU,uBAAuB,CACtC,GAAW,EACX,OAAkC,EACM;IACxC,OAAO,kBAAkB,CAAC,iCAAiC,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AAAA,CAC3E","sourcesContent":["/**\n * `browser_resume` tool: answer a `NeedsParent` suspension from `browser_flow`.\n *\n * Looks up the paused serve session by its `ResumeToken`, issues `flow_resume`\n * with the parent's decision (a `ParentResponse` object), and maps the next\n * outcome the same way `browser_flow` does — completing, failing, or suspending\n * again with a fresh token. The live serve process (and its browser state) is\n * reused across rounds. See {@link browsertools-shared}.\n */\n\nimport type { AgentTool } from \"@kolisachint/hoocode-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport { defineTool, type ToolDefinition } from \"../extensions/types.js\";\nimport { advanceFlow, type BrowserFlowDetails } from \"./browser-flow.js\";\nimport {\n\ttype BrowsertoolsToolOptions,\n\ttype FlowOutcome,\n\tresolveBrowsertoolsOptions,\n\ttakeSession,\n} from \"./browsertools-shared.js\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.js\";\n\nconst browserResumeSchema = Type.Object({\n\ttoken: Type.String({ description: \"The resume token returned by a browser_flow NeedsParent result.\" }),\n\tresponse: Type.Record(Type.String(), Type.Unknown(), {\n\t\tdescription:\n\t\t\t\"The ParentResponse object answering the request, e.g. \" +\n\t\t\t'{ \"response\": \"state\", \"state\": \"logged_in\" } or { \"response\": \"verified\", \"passed\": true }.',\n\t}),\n});\n\nexport type BrowserResumeInput = Static<typeof browserResumeSchema>;\n\nexport interface BrowserResumeToolOptions extends BrowsertoolsToolOptions {}\n\nexport function createBrowserResumeToolDefinition(\n\t// cwd is part of the factory signature for parity with other tools, but resume\n\t// reuses the serve process parked by browser_flow, so it is not needed here.\n\t_cwd: string,\n\toptions?: BrowserResumeToolOptions,\n): ToolDefinition<typeof browserResumeSchema, BrowserFlowDetails> {\n\tconst opts = resolveBrowsertoolsOptions(options);\n\treturn defineTool({\n\t\tname: \"browser_resume\",\n\t\tlabel: \"browser resume\",\n\t\tdescription:\n\t\t\t\"Resume a browser flow that suspended with a NeedsParent request. Pass the token from the \" +\n\t\t\t\"browser_flow result and a ParentResponse object answering the request. The flow continues \" +\n\t\t\t\"deterministically and either completes, fails, or suspends again with a new token. Off by \" +\n\t\t\t\"default; enabled with --enable-browsertools.\",\n\t\tparameters: browserResumeSchema,\n\t\tasync execute(_toolCallId, params: BrowserResumeInput, signal) {\n\t\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\n\t\t\tconst session = takeSession(params.token);\n\t\t\tif (!session) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`No paused browser flow for token \"${params.token}\" — it may have completed, expired (idle ` +\n\t\t\t\t\t\t`timeout), or never existed. Start a new flow with browser_flow.`,\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst { client } = session;\n\t\t\tconst onAbort = () => client.dispose();\n\t\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\ttry {\n\t\t\t\tconst outcome = await client.request<FlowOutcome>(\"flow_resume\", {\n\t\t\t\t\ttoken: params.token,\n\t\t\t\t\tresponse: params.response,\n\t\t\t\t});\n\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\tclient.dispose();\n\t\t\t\t\tthrow new Error(\"Operation aborted\");\n\t\t\t\t}\n\t\t\t\t// Count this resume as one more NeedsParent round if it suspends again.\n\t\t\t\treturn await advanceFlow(client, outcome, session.rounds + 1, opts);\n\t\t\t} catch (error) {\n\t\t\t\tclient.dispose();\n\t\t\t\tthrow error;\n\t\t\t} finally {\n\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t}\n\t\t},\n\t});\n}\n\nexport function createBrowserResumeTool(\n\tcwd: string,\n\toptions?: BrowserResumeToolOptions,\n): AgentTool<typeof browserResumeSchema> {\n\treturn wrapToolDefinition(createBrowserResumeToolDefinition(cwd, options));\n}\n"]}

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

@@ -0,0 +1,152 @@
+/**
+ * Shared plumbing for the `browser_flow` and `browser_resume` 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_flow`
+ * call that starts the flow and the `browser_resume` 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[];
+}
+/** 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[];
+};
+/** 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 {
+    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;
+    });
+    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;
+}
+/**
+ * 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): 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;
+export {};
+//# sourceMappingURL=browsertools-shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browsertools-shared.d.ts","sourceRoot":"","sources":["../../../src/core/tools/browsertools-shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared plumbing for the `browser_flow` and `browser_resume` 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_flow`\n * call that starts the flow and the `browser_resume` 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}\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} {\n\treturn {\n\t\tbinaryPath: options?.binaryPath,\n\t\tbrowserPath: options?.browserPath ?? (process.env.HOOCODE_BROWSERTOOLS_BROWSER_PATH?.trim() || undefined),\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\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: { cwd?: string; browserPath?: string; serveArgs: string[]; requestTimeoutMs: number },\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// 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}\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): 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 });\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}\n\n/** Number of currently parked sessions (for tests/diagnostics). */\nexport function pausedSessionCount(): number {\n\treturn sessionRegistry.size;\n}\n"]}

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

@@ -0,0 +1,274 @@
+/**
+ * Shared plumbing for the `browser_flow` and `browser_resume` 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_flow`
+ * call that starts the flow and the `browser_resume` 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),
+        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 {
+    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;
+        }
+        // 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) {
+    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 });
+}
+/**
+ * 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();
+}
+/** Number of currently parked sessions (for tests/diagnostics). */
+export function pausedSessionCount() {
+    return sessionRegistry.size;
+}
+//# sourceMappingURL=browsertools-shared.js.map