pi-browser-harness 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/README.md +132 -0
  3. package/package.json +15 -7
  4. package/skills/pi-browser-harness/SKILL.md +89 -2
  5. package/src/cdp/commands.ts +205 -14
  6. package/src/cdp/console-buffer.ts +37 -23
  7. package/src/cdp/discovery.ts +57 -25
  8. package/src/cdp/events.ts +9 -3
  9. package/src/cdp/network-buffer.ts +38 -32
  10. package/src/cdp/ownership.ts +22 -4
  11. package/src/cdp/record-store.ts +2 -2
  12. package/src/cdp/session.ts +358 -216
  13. package/src/cdp/target-factory.ts +34 -15
  14. package/src/cdp/types.ts +17 -1
  15. package/src/client.ts +127 -54
  16. package/src/daemon/bridge.ts +110 -349
  17. package/src/daemon/connection.ts +323 -0
  18. package/src/daemon/index.ts +77 -48
  19. package/src/daemon/lines.ts +40 -0
  20. package/src/daemon/main.ts +12 -0
  21. package/src/daemon/protocol.ts +55 -25
  22. package/src/daemon/server.ts +100 -63
  23. package/src/daemon/socket.ts +10 -0
  24. package/src/daemon/spawn.ts +21 -22
  25. package/src/daemon/transport.ts +80 -49
  26. package/src/domains/ax-tree.ts +27 -8
  27. package/src/domains/cdp-call.ts +14 -7
  28. package/src/domains/click.ts +2 -2
  29. package/src/domains/concurrency.ts +50 -0
  30. package/src/domains/console.ts +20 -64
  31. package/src/domains/drag.ts +26 -28
  32. package/src/domains/element-call.ts +102 -68
  33. package/src/domains/files.ts +13 -9
  34. package/src/domains/form-batch.ts +13 -10
  35. package/src/domains/form.ts +78 -107
  36. package/src/domains/headers.ts +2 -2
  37. package/src/domains/history.ts +4 -4
  38. package/src/domains/io.ts +35 -0
  39. package/src/domains/isolated-tab.ts +6 -12
  40. package/src/domains/js.ts +67 -46
  41. package/src/domains/keyboard.ts +14 -11
  42. package/src/domains/navigate.ts +102 -66
  43. package/src/domains/network.ts +55 -95
  44. package/src/domains/page/fill.page.ts +139 -0
  45. package/src/domains/page/form.page.ts +61 -0
  46. package/src/domains/page/inject.ts +37 -0
  47. package/src/domains/page/keyboard.page.ts +16 -0
  48. package/src/domains/page/live-value.page.ts +10 -0
  49. package/src/domains/page/read-page.page.ts +51 -0
  50. package/src/domains/page/recipe.page.ts +82 -0
  51. package/src/domains/page/serp.page.ts +42 -0
  52. package/src/domains/page.ts +18 -51
  53. package/src/domains/poll.ts +42 -0
  54. package/src/domains/readpage/read-page.ts +48 -53
  55. package/src/domains/ref-resolve.ts +43 -29
  56. package/src/domains/ref-signature.ts +11 -0
  57. package/src/domains/render.ts +12 -23
  58. package/src/domains/screenshot-capture.ts +4 -2
  59. package/src/domains/screenshot.ts +13 -10
  60. package/src/domains/scroll.ts +4 -4
  61. package/src/domains/search/google-serp.ts +78 -8
  62. package/src/domains/search/redirect-resolver.ts +41 -0
  63. package/src/domains/search/web-search.ts +103 -40
  64. package/src/domains/snapshot.ts +81 -78
  65. package/src/domains/tab-resolve.ts +36 -0
  66. package/src/domains/tabs.ts +18 -69
  67. package/src/domains/target.ts +1 -1
  68. package/src/index.ts +101 -33
  69. package/src/profile/bind.ts +45 -14
  70. package/src/profile/browser-process.ts +50 -12
  71. package/src/profile/command.ts +20 -12
  72. package/src/profile/launch.ts +13 -9
  73. package/src/profile/list.ts +9 -13
  74. package/src/profile/store.ts +2 -1
  75. package/src/prompt.ts +34 -8
  76. package/src/recipes/command.ts +96 -0
  77. package/src/recipes/compile.ts +198 -0
  78. package/src/recipes/find.ts +49 -0
  79. package/src/recipes/journal.ts +125 -0
  80. package/src/recipes/recipe.ts +215 -0
  81. package/src/recipes/recordable.ts +359 -0
  82. package/src/recipes/replay.ts +354 -0
  83. package/src/recipes/run-tool.ts +132 -0
  84. package/src/recipes/save-tool.ts +247 -0
  85. package/src/recipes/store.ts +103 -0
  86. package/src/recipes/trust.ts +172 -0
  87. package/src/registry.ts +69 -4
  88. package/src/schemas/parse.ts +2 -2
  89. package/src/setup.ts +28 -19
  90. package/src/state.ts +2 -1
  91. package/src/util/debug.ts +7 -1
  92. package/src/util/guards.ts +3 -0
  93. package/src/util/js-source.ts +28 -0
  94. package/src/util/mutex.ts +1 -1
  95. package/src/util/paths.ts +3 -2
  96. package/src/util/result.ts +8 -0
  97. package/src/util/sharp-shim.ts +18 -11
  98. package/src/util/sleep.ts +18 -0
  99. package/src/util/tool.ts +185 -114
  100. package/src/util/truncate.ts +1 -1
  101. package/tsconfig.json +2 -1
  102. package/src/domains/fill-engine.ts +0 -80
package/src/setup.ts CHANGED
@@ -4,12 +4,19 @@ import { ensureDaemon } from "./daemon/spawn";
4
4
  import { DAEMON_SOCKET_PATH } from "./daemon/protocol";
5
5
  import { isBrowserRunning } from "./profile/browser-process";
6
6
  import { promptForProfileIfUnset } from "./profile/command";
7
+ import { type Result, err, ok } from "./util/result";
7
8
 
8
- export function registerSetupCommand(pi: ExtensionAPI, client: BrowserClient): void {
9
+ // The machine probes setup runs before touching the client. Each defaults to the real implementation.
10
+ export type SetupDeps = {
11
+ readonly isBrowserRunning?: () => Promise<boolean>;
12
+ readonly ensureDaemon?: () => Promise<boolean>;
13
+ };
14
+
15
+ export function registerSetupCommand(pi: ExtensionAPI, client: BrowserClient, deps: SetupDeps = {}): void {
9
16
  pi.registerCommand("browser-setup", {
10
17
  description: "Connect pi to your Chrome browser",
11
18
  handler: async (_args, ctx) => {
12
- const result = await performSetup(client, ctx);
19
+ const result = await performSetup(client, ctx, deps);
13
20
  if (result.success) {
14
21
  ctx.ui.notify(result.data, "info");
15
22
  } else {
@@ -19,22 +26,26 @@ export function registerSetupCommand(pi: ExtensionAPI, client: BrowserClient): v
19
26
  });
20
27
  }
21
28
 
22
- export type SetupResult = { success: true; data: string } | { success: false; error: string };
29
+ export type SetupResult = Result<string, string>;
23
30
 
24
- export async function performSetup(client: BrowserClient, ctx?: ExtensionContext): Promise<SetupResult> {
25
- const chromeRunning = await isBrowserRunning();
31
+ export async function performSetup(
32
+ client: BrowserClient,
33
+ ctx?: ExtensionContext,
34
+ deps: SetupDeps = {},
35
+ ): Promise<SetupResult> {
36
+ const chromeRunning = await (deps.isBrowserRunning ?? isBrowserRunning)();
26
37
  if (!chromeRunning) {
27
- return { success: false, error: "No browser instance running. Please open your browser and then run /browser-setup." };
38
+ return err("No browser instance running. Please open your browser and then run /browser-setup.");
28
39
  }
29
40
 
30
- const daemonReady = await ensureDaemon();
41
+ const daemonReady = await (deps.ensureDaemon ?? ensureDaemon)();
31
42
  if (!daemonReady) {
32
- return { success: false, error: `Could not start the browser daemon. Check ${DAEMON_SOCKET_PATH}.` };
43
+ return err(`Could not start the browser daemon. Check ${DAEMON_SOCKET_PATH}.`);
33
44
  }
34
45
 
35
46
  const profileNote = await promptForProfileIfUnset(client, ctx);
36
47
 
37
- const startResult = await client.start();
48
+ const startResult = await client.start({ reconnectNow: true });
38
49
  if (!startResult.success) {
39
50
  const msg = startResult.error.message;
40
51
  const lower = msg.toLowerCase();
@@ -45,35 +56,33 @@ export async function performSetup(client: BrowserClient, ctx?: ExtensionContext
45
56
  lower.includes("econnrefused") ||
46
57
  lower.includes("cannot reach chrome devtools")
47
58
  ) {
48
- return {
49
- success: false,
50
- error:
51
- "Browser remote debugging needs to be enabled.\n\n" +
59
+ return err(
60
+ "Browser remote debugging needs to be enabled.\n\n" +
52
61
  "Open chrome://inspect/#remote-debugging (or brave://inspect,\n" +
53
62
  "edge://inspect) in your browser, tick the\n" +
54
63
  '"Discover network targets" / Allow checkbox, then retry.\n\n' +
55
64
  "If that doesn't expose DevTools, relaunch the browser with\n" +
56
65
  "--remote-debugging-port=9222.\n\n" +
57
66
  "Or set BU_CDP_WS to a remote browser WebSocket URL.",
58
- };
67
+ );
59
68
  }
60
69
 
61
- return { success: false, error: `Connection failed: ${msg}` };
70
+ return err(`Connection failed: ${msg}`);
62
71
  }
63
72
 
64
73
  const tabResult = await client.newTab("https://github.com");
65
74
  if (!tabResult.success) {
66
- return { success: false, error: `Browser connected but test navigation failed: ${tabResult.error.message}` };
75
+ return err(`Browser connected but test navigation failed: ${tabResult.error.message}`);
67
76
  }
68
77
 
69
78
  const info = await client.pageInfo();
70
- if (info.success && "dialog" in info.data) {
79
+ if (info.success && info.data.kind === "dialog") {
71
80
  await client.session().call("Page.handleJavaScriptDialog", { accept: true });
72
81
  }
73
82
 
74
- const pageUrl = info.success && !("dialog" in info.data) ? info.data.url : "github.com";
83
+ const pageUrl = info.success && info.data.kind === "page" ? info.data.url : "github.com";
75
84
  const lines = ["Browser connected ✓", `Navigated to: ${pageUrl}`];
76
85
  if (profileNote) lines.push(profileNote);
77
- return { success: true, data: lines.join("\n") };
86
+ return ok(lines.join("\n"));
78
87
  }
79
88
 
package/src/state.ts CHANGED
@@ -31,7 +31,8 @@ export type StatePersister = {
31
31
  readonly markPersisted: (state: BrowserState) => void;
32
32
  };
33
33
 
34
- export const createStatePersister = (pi: ExtensionAPI): StatePersister => {
34
+ // Only appendEntry is needed, so a test can hand in a plain object instead of a whole ExtensionAPI.
35
+ export const createStatePersister = (pi: Pick<ExtensionAPI, "appendEntry">): StatePersister => {
35
36
  let last: string | undefined;
36
37
  return {
37
38
  persist: (state) => {
package/src/util/debug.ts CHANGED
@@ -4,5 +4,11 @@ export const setDebugClicks = (on: boolean): void => {
4
4
  flagEnabled = on;
5
5
  };
6
6
 
7
+ const TRUTHY: ReadonlySet<string> = new Set(["1", "true"]);
8
+
9
+ // Only an explicit "1" or "true" counts: "0" and "false" are set to turn the overlay off, not on.
10
+ const envFlagEnabled = (value: string | undefined): boolean =>
11
+ value !== undefined && TRUTHY.has(value.trim().toLowerCase());
12
+
7
13
  export const debugClicksEnabled = (env: NodeJS.ProcessEnv = process.env): boolean =>
8
- flagEnabled || Boolean(env["BH_DEBUG_CLICKS"]);
14
+ flagEnabled || envFlagEnabled(env["BH_DEBUG_CLICKS"]);
@@ -6,6 +6,9 @@ export const asRecord = (v: unknown): Readonly<Record<string, unknown>> | undefi
6
6
 
7
7
  export const asString = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
8
8
 
9
+ export const asNonEmptyString = (v: unknown): string | undefined =>
10
+ typeof v === "string" && v.length > 0 ? v : undefined;
11
+
9
12
  export const asNumber = (v: unknown): number | undefined => (typeof v === "number" ? v : undefined);
10
13
 
11
14
  export const asBoolean = (v: unknown): boolean | undefined => (typeof v === "boolean" ? v : undefined);
@@ -0,0 +1,28 @@
1
+ import { parse } from "acorn";
2
+ import { isRecord } from "./guards";
3
+
4
+ const FUNCTION_NODES: ReadonlySet<string> = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
5
+
6
+ // True when a return statement sits in the program body itself, not inside a function it defines.
7
+ const hasTopLevelReturn = (node: unknown): boolean => {
8
+ if (Array.isArray(node)) return node.some(hasTopLevelReturn);
9
+ if (!isRecord(node) || typeof node["type"] !== "string") return false;
10
+ if (node["type"] === "ReturnStatement") return true;
11
+ if (FUNCTION_NODES.has(node["type"])) return false;
12
+ return Object.values(node).some((v) => typeof v === "object" && v !== null && hasTopLevelReturn(v));
13
+ };
14
+
15
+ // The source Runtime.evaluate should run for what the model wrote. A top-level `return`, anywhere in the body,
16
+ // makes it a function body, so it runs inside an async function. The call is awaited in the source itself: in REPL
17
+ // mode awaitPromise waits only for the REPL's own completion, so a returned promise would come back unresolved
18
+ // (serialized as {}). Anything else, including source that does not parse, is sent as written, so the page reports
19
+ // its own error.
20
+ export const pageExpression = (src: string): string => {
21
+ let program: unknown;
22
+ try {
23
+ program = parse(src, { ecmaVersion: "latest", allowReturnOutsideFunction: true, allowAwaitOutsideFunction: true });
24
+ } catch {
25
+ return src;
26
+ }
27
+ return isRecord(program) && hasTopLevelReturn(program["body"]) ? `await (async () => {\n${src}\n})()` : src;
28
+ };
package/src/util/mutex.ts CHANGED
@@ -7,7 +7,7 @@ export const createMutex = (): Mutex => {
7
7
 
8
8
  return {
9
9
  async acquire(): Promise<() => void> {
10
- let release = () => {};
10
+ let release: () => void = () => undefined;
11
11
  const next = new Promise<void>((resolve) => {
12
12
  release = resolve;
13
13
  });
package/src/util/paths.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import { tmpdir } from "node:os";
3
- import { isAbsolute, join, relative, resolve } from "node:path";
3
+ import { isAbsolute, join, relative, resolve, sep } from "node:path";
4
4
 
5
5
  // `relative` rather than a string prefix: it is separator-agnostic and carries each platform's
6
6
  // own case rules, so a Windows path is not rejected for its backslashes or its drive-letter case.
@@ -9,7 +9,8 @@ export const isPathWithin = (root: string, target: string): boolean => {
9
9
  const absTarget = resolve(target);
10
10
  if (absTarget === absRoot) return true;
11
11
  const rel = relative(absRoot, absTarget);
12
- return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
12
+ // A bare ".." or a ".."-led segment escapes; a sibling merely named "..foo" does not.
13
+ return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
13
14
  };
14
15
 
15
16
  const NAMESPACE_RE = /^[a-zA-Z0-9_-]+$/;
@@ -7,3 +7,11 @@ export const err = <E>(error: E): Result<never, E> => ({ success: false, error }
7
7
 
8
8
  export const map = <T, U, E>(r: Result<T, E>, f: (t: T) => U): Result<U, E> =>
9
9
  r.success ? ok(f(r.data)) : r;
10
+
11
+ export const andThen = <T, U, E, F>(r: Result<T, E>, f: (t: T) => Result<U, F>): Result<U, E | F> =>
12
+ r.success ? f(r.data) : r;
13
+
14
+ export const mapErr = <T, E, F>(r: Result<T, E>, f: (e: E) => F): Result<T, F> =>
15
+ r.success ? r : err(f(r.error));
16
+
17
+ export const unwrapOr = <T, E>(r: Result<T, E>, fallback: T): T => (r.success ? r.data : fallback);
@@ -1,5 +1,7 @@
1
1
  // `sharp` is an optional dependency not installed in every workspace, so the import must stay dynamic and unresolvable to tsc.
2
2
 
3
+ import { errnoCode, isRecord } from "./guards";
4
+
3
5
  export type SharpInstance = {
4
6
  metadata(): Promise<{ width?: number; height?: number }>;
5
7
  composite(layers: ReadonlyArray<{ input: Buffer; top: number; left: number }>): SharpInstance;
@@ -14,29 +16,34 @@ export type SharpLoad =
14
16
  | { readonly kind: "missing" }
15
17
  | { readonly kind: "error"; readonly message: string };
16
18
 
17
- const SHARP_SPECIFIER: string = "sharp";
19
+ // Kept as a variable so the bundler does not try to resolve the optional dependency statically.
20
+ const SHARP_SPECIFIER = "sharp";
21
+
22
+ // Node reports an absent package through the error code: ERR_MODULE_NOT_FOUND from the ESM loader
23
+ // ("Cannot find package 'sharp' imported from …"), MODULE_NOT_FOUND from require. Matching the message
24
+ // text misses the ESM form, so an uninstalled sharp used to be reported as a load failure.
25
+ const MISSING_MODULE_CODES: ReadonlySet<string> = new Set(["ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"]);
18
26
 
19
- const MISSING_MODULE_MARKERS: ReadonlyArray<string> = [
20
- "Cannot find module",
21
- "MODULE_NOT_FOUND",
22
- "ERR_MODULE_NOT_FOUND",
23
- ];
27
+ export const classifySharpImportFailure = (e: unknown): SharpLoad => {
28
+ const code = errnoCode(e);
29
+ if (code !== undefined && MISSING_MODULE_CODES.has(code)) return { kind: "missing" };
30
+ return { kind: "error", message: e instanceof Error ? e.message : String(e) };
31
+ };
24
32
 
25
33
  export const loadSharp = async (): Promise<SharpLoad> => {
26
34
  let mod: unknown;
27
35
  try {
28
36
  mod = await import(SHARP_SPECIFIER);
29
37
  } catch (e) {
30
- const msg = e instanceof Error ? e.message : String(e);
31
- if (MISSING_MODULE_MARKERS.some((marker) => msg.includes(marker))) return { kind: "missing" };
32
- return { kind: "error", message: msg };
38
+ return classifySharpImportFailure(e);
33
39
  }
34
40
  if (mod === null || mod === undefined) return { kind: "missing" };
35
41
  // The CommonJS sharp module's default export IS the factory; ESM-wrapped sharp puts it on .default.
36
- const m = mod as { default?: unknown };
37
- const candidate: unknown = typeof m.default === "function" ? m.default : mod;
42
+ const candidate: unknown = isRecord(mod) && typeof mod["default"] === "function" ? mod["default"] : mod;
38
43
  if (typeof candidate !== "function") {
39
44
  return { kind: "error", message: "sharp module did not expose a callable factory" };
40
45
  }
46
+ // The only thing verifiable at runtime is that sharp exported a function; its signature is taken on trust.
47
+ // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- optional-dependency boundary, see scripts/boundary-allowlist.ts
41
48
  return { kind: "ok", sharp: candidate as SharpFactory };
42
49
  };
@@ -0,0 +1,18 @@
1
+ // Resolves (never rejects) after `ms`, or as soon as `signal` aborts. Shared by every poll loop so
2
+ // there is one spelling of "cancellable wait" across the cdp, profile and domain layers.
3
+ export const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
4
+ new Promise((resolve) => {
5
+ if (signal?.aborted) {
6
+ resolve();
7
+ return;
8
+ }
9
+ const onAbort = (): void => {
10
+ clearTimeout(timer);
11
+ resolve();
12
+ };
13
+ const timer = setTimeout(() => {
14
+ signal?.removeEventListener("abort", onAbort);
15
+ resolve();
16
+ }, ms);
17
+ signal?.addEventListener("abort", onAbort, { once: true });
18
+ });
package/src/util/tool.ts CHANGED
@@ -1,4 +1,6 @@
1
- import type { TSchema, Static } from "typebox";
1
+ import { isRecord } from "./guards";
2
+ import { Type, type TSchema, type Static } from "typebox";
3
+ import { Compile } from "typebox/compile";
2
4
  import type {
3
5
  AgentToolResult,
4
6
  ExtensionAPI,
@@ -7,14 +9,44 @@ import type {
7
9
  ToolDefinition,
8
10
  ToolRenderResultOptions,
9
11
  } from "@mariozechner/pi-coding-agent";
10
- import type { Component } from "@mariozechner/pi-tui";
12
+ import { type Component, Text } from "@mariozechner/pi-tui";
11
13
  import { daemonSocketMayExist } from "../daemon/spawn";
12
14
  import type { BrowserClient } from "../client";
13
- import type { Result } from "./result";
15
+ import { type Result, err, ok } from "./result";
14
16
 
15
- export type ToolOk = {
17
+ // Details are stored by pi as JSON and handed back on replay, so a renderer only ever reads them.
18
+ export type DeepReadonly<T> = T extends ReadonlyArray<infer U>
19
+ ? ReadonlyArray<DeepReadonly<U>>
20
+ : T extends object
21
+ ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
22
+ : T;
23
+
24
+ // pi serializes details to JSON, so a Map, a function or an undefined-valued key would be silently lost or
25
+ // mangled on replay; the untyped contract admits only what survives the round trip.
26
+ export type JsonValue = string | number | boolean | null | ReadonlyArray<JsonValue> | JsonObject;
27
+ export type JsonObject = { readonly [key: string]: JsonValue };
28
+
29
+ const isJsonValue = (v: unknown): v is JsonValue => {
30
+ if (v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean") return true;
31
+ if (Array.isArray(v)) return v.every(isJsonValue);
32
+ if (typeof v !== "object" || Object.getPrototypeOf(v) !== Object.prototype) return false;
33
+ return Object.values(v).every(isJsonValue);
34
+ };
35
+
36
+ export const isJsonObject = (v: unknown): v is JsonObject => isRecord(v) && isJsonValue(v);
37
+
38
+ // A tool that declares no `details` schema may still attach any JSON object for logs; its renderer (if any)
39
+ // sees that object untyped, or undefined when the handler attached nothing.
40
+ export const UntypedDetailsSchema = Type.Union([Type.Record(Type.String(), Type.Unknown()), Type.Undefined()]);
41
+ export type UntypedDetailsSchema = typeof UntypedDetailsSchema;
42
+ export type UntypedDetails = JsonObject | undefined;
43
+
44
+ // The value type a details schema describes, as the handler produces it and the renderer reads it back.
45
+ export type DetailsOf<D extends TSchema> = D extends UntypedDetailsSchema ? UntypedDetails : DeepReadonly<Static<D>>;
46
+
47
+ export type ToolOk<T = UntypedDetails> = {
16
48
  readonly text: string;
17
- readonly details?: Readonly<Record<string, unknown>>;
49
+ readonly details?: T;
18
50
  };
19
51
 
20
52
  export type ToolErrKind =
@@ -22,6 +54,7 @@ export type ToolErrKind =
22
54
  | "cdp_error"
23
55
  | "timeout"
24
56
  | "invalid_state"
57
+ | "invalid_args"
25
58
  | "io_error"
26
59
  | "internal";
27
60
 
@@ -31,80 +64,153 @@ export type ToolErr = {
31
64
  readonly details?: Readonly<Record<string, unknown>>;
32
65
  };
33
66
 
34
- export type HandlerContext = {
67
+ export type HandlerContext<T = UntypedDetails> = {
35
68
  readonly client: BrowserClient;
36
69
  readonly signal: AbortSignal | undefined;
37
- readonly onUpdate: (update: ToolOk) => void;
70
+ readonly onUpdate: (update: ToolOk<T>) => void;
38
71
  readonly extensionCtx: ExtensionContext;
39
72
  };
40
73
 
41
- export type ToolHandler<S extends TSchema> = (
74
+ export type ToolHandler<S extends TSchema, T = UntypedDetails> = (
42
75
  args: Static<S>,
43
- ctx: HandlerContext,
44
- ) => Promise<Result<ToolOk, ToolErr>>;
76
+ ctx: HandlerContext<T>,
77
+ ) => Promise<Result<ToolOk<T>, ToolErr>>;
78
+
79
+ export type ToolConcurrency = "serialized" | "parallel";
45
80
 
46
- export type BrowserToolDefinition<S extends TSchema> = {
81
+ // S types the arguments, D the structured details the handler attaches to a successful result. pi persists
82
+ // details and hands them back to renderResult on replay; declaring D lets the tool read them back typed, after
83
+ // the contract has validated them against the schema. A tool with no details leaves D at its default.
84
+ export type BrowserToolDefinition<S extends TSchema, D extends TSchema = UntypedDetailsSchema> = {
47
85
  readonly name: string;
48
86
  readonly label: string;
49
87
  readonly description: string;
50
88
  readonly promptSnippet: string;
51
89
  readonly promptGuidelines: ReadonlyArray<string>;
52
90
  readonly parameters: S;
53
- readonly handler: ToolHandler<S>;
91
+ readonly details?: D;
92
+ readonly handler: ToolHandler<S, DetailsOf<D>>;
54
93
  readonly renderCall?: (args: Static<S>, theme: Theme) => Component;
55
- readonly renderResult?: (result: AgentToolResult<unknown>, expanded: boolean, theme: Theme) => Component;
56
- readonly concurrency: "serialized" | "parallel";
94
+ readonly renderResult?: (result: AgentToolResult<DetailsOf<D>>, expanded: boolean, theme: Theme) => Component;
95
+ readonly concurrency: ToolConcurrency;
57
96
  readonly ensureAlive?: boolean;
58
97
  };
59
98
 
60
- // renderCall accepts `never` so any concrete args type satisfies it via function-parameter contravariance.
61
- export type AnyBrowserToolDefinition = Omit<BrowserToolDefinition<TSchema>, "renderCall" | "renderResult"> & {
62
- readonly renderCall?: (args: never, theme: Theme) => Component;
63
- readonly renderResult?: (result: AgentToolResult<unknown>, expanded: boolean, theme: Theme) => Component;
99
+ // The schema-erased view of a tool. Everything that depends on S or D (handler, renderers, the details
100
+ // validator) stays closed over inside `register`, which was built while they were still bound, so no cast is
101
+ // needed to hold tools of different schemas in one list.
102
+ export type BrowserTool = Pick<
103
+ BrowserToolDefinition<TSchema>,
104
+ "name" | "label" | "description" | "promptSnippet" | "promptGuidelines" | "concurrency" | "ensureAlive"
105
+ > & {
106
+ readonly register: (pi: Pick<ExtensionAPI, "registerTool">, client: BrowserClient) => void;
107
+ };
108
+
109
+ // A defined tool is both: tests reach the typed handler and parameters, the registry sees BrowserTool.
110
+ export type DefinedBrowserTool<S extends TSchema, D extends TSchema = UntypedDetailsSchema> =
111
+ BrowserToolDefinition<S, D> & BrowserTool;
112
+
113
+ // pi does not export ToolRenderContext from its index, so it is read off the renderer signature.
114
+ type RenderResultContext<S extends TSchema> = Parameters<NonNullable<ToolDefinition<S>["renderResult"]>>[3];
115
+
116
+ export const renderToolError = (toolName: string, e: ToolErr): string =>
117
+ `${toolName} failed (${e.kind}): ${e.message}`;
118
+
119
+ // Stored details are whatever the handler attached; the schema (not a marker) is what tells a renderer they
120
+ // are usable on replay.
121
+ const okResult = <T>(u: ToolOk<T>): AgentToolResult<unknown> => ({
122
+ content: [{ type: "text", text: u.text }],
123
+ details: u.details,
124
+ });
125
+
126
+ const storedText = (result: AgentToolResult<unknown>, fallback: string): string => {
127
+ const first = result.content[0];
128
+ return first?.type === "text" ? first.text : fallback;
64
129
  };
65
130
 
66
- export const defineBrowserTool = <S extends TSchema>(
67
- def: BrowserToolDefinition<S>,
68
- ): BrowserToolDefinition<S> => def;
69
-
70
- type OkDetails = { readonly ok: true } & Readonly<Record<string, unknown>>;
71
- type ErrDetails = { readonly ok: false; readonly kind: ToolErrKind; readonly message: string } & Readonly<Record<string, unknown>>;
72
-
73
- type ErrorFlagged<D> = AgentToolResult<D> & { readonly isError?: boolean };
74
-
75
- const toToolResult = (
76
- r: Result<ToolOk, ToolErr>,
77
- toolName: string,
78
- ): ErrorFlagged<OkDetails | ErrDetails> => {
79
- if (r.success) {
80
- const details: OkDetails = { ok: true, ...(r.data.details ?? {}) };
81
- return {
82
- content: [{ type: "text", text: r.data.text }],
83
- details,
84
- };
131
+ // Readonly-ness is a compile-time view, so a value the compiled schema accepts is a DetailsOf<D> value. This
132
+ // is the one place the predicate is asserted; tools get their details typed through it.
133
+ // Compiled once: most tools declare no schema, and compiling the shared fallback per tool is wasted codegen.
134
+ const UNTYPED_DETAILS_VALIDATOR = Compile(UntypedDetailsSchema);
135
+
136
+ const detailsGuard = <D extends TSchema>(schema: D | undefined): ((v: unknown) => v is DetailsOf<D>) => {
137
+ const validator = schema ? Compile(schema) : UNTYPED_DETAILS_VALIDATOR;
138
+ return (v: unknown): v is DetailsOf<D> => validator.Check(v);
139
+ };
140
+
141
+ const notConnected = (message: string): Result<never, ToolErr> =>
142
+ err({ kind: "not_connected", message });
143
+
144
+ export type CallOutcome = { readonly ok: boolean; readonly error?: string };
145
+
146
+ // Watches a tool call from outside the tool (the recipe journal). Returns the function that receives the call's
147
+ // outcome and may return a note for the end of a successful result, or undefined to skip the call. Errors it throws
148
+ // are swallowed by runHandler.
149
+ export type CallObserver = (call: {
150
+ readonly name: string;
151
+ readonly concurrency: ToolConcurrency;
152
+ readonly args: unknown;
153
+ readonly client: BrowserClient;
154
+ }) => Promise<((outcome: CallOutcome) => Promise<string | undefined>) | undefined>;
155
+
156
+ let callObserver: CallObserver | undefined;
157
+ export const setCallObserver = (o: CallObserver | undefined): void => {
158
+ callObserver = o;
159
+ };
160
+
161
+ const runHandler = async <S extends TSchema, D extends TSchema>(
162
+ def: BrowserToolDefinition<S, D>,
163
+ client: BrowserClient,
164
+ args: Static<S>,
165
+ signal: AbortSignal | undefined,
166
+ onUpdate: ((partial: AgentToolResult<unknown>) => void) | undefined,
167
+ extensionCtx: ExtensionContext,
168
+ ): Promise<Result<ToolOk<DetailsOf<D>>, ToolErr>> => {
169
+ if (def.ensureAlive !== false) {
170
+ if (!(await daemonSocketMayExist())) {
171
+ return notConnected("Browser harness not initialized. Run /browser-setup first");
172
+ }
173
+ const alive = await client.ensureAlive();
174
+ if (!alive.success) return notConnected(alive.error.message);
175
+ }
176
+ let release: (() => void) | undefined;
177
+ if (def.concurrency !== "parallel") {
178
+ release = await client.mutationMutex().acquire();
179
+ if (signal?.aborted) {
180
+ release();
181
+ return err({ kind: "invalid_state", message: "Tool execution aborted before entering serialized lane" });
182
+ }
183
+ }
184
+ const finish = await callObserver?.({ name: def.name, concurrency: def.concurrency, args, client }).catch(() => undefined);
185
+ try {
186
+ const result = await def.handler(args, {
187
+ client,
188
+ signal,
189
+ onUpdate: (u) => onUpdate?.(okResult(u)),
190
+ extensionCtx,
191
+ });
192
+ const note = await finish?.(result.success ? { ok: true } : { ok: false, error: result.error.message }).catch(() => undefined);
193
+ return result.success && note !== undefined ? ok({ ...result.data, text: `${result.data.text}\n\n${note}` }) : result;
194
+ } catch (e) {
195
+ // A throw is a bug in the handler, not a tool outcome; it still has to reach the model as an error.
196
+ const message = e instanceof Error ? e.message : String(e);
197
+ await finish?.({ ok: false, error: message }).catch(() => undefined);
198
+ return err({ kind: "internal", message });
199
+ } finally {
200
+ release?.();
85
201
  }
86
- const details: ErrDetails = {
87
- ok: false,
88
- kind: r.error.kind,
89
- message: r.error.message,
90
- ...(r.error.details ?? {}),
91
- };
92
- return {
93
- isError: true,
94
- content: [{ type: "text", text: `${toolName} failed (${r.error.kind}): ${r.error.message}` }],
95
- details,
96
- };
97
202
  };
98
203
 
99
- export const registerBrowserTool = (
100
- pi: ExtensionAPI,
204
+ // pi has no error field on a resolved tool result: the agent loop marks a result isError only when
205
+ // execute rejects, and then stores the thrown message as the result text. So a failed handler throws.
206
+ const toPiTool = <S extends TSchema, D extends TSchema>(
207
+ def: BrowserToolDefinition<S, D>,
101
208
  client: BrowserClient,
102
- def: AnyBrowserToolDefinition,
103
- ): void => {
104
- type S = TSchema;
209
+ ): ToolDefinition<S> => {
105
210
  const defRenderCall = def.renderCall;
106
211
  const defRenderResult = def.renderResult;
107
- const td: ToolDefinition<S> = {
212
+ const isDetails = detailsGuard(def.details);
213
+ return {
108
214
  name: def.name,
109
215
  label: def.label,
110
216
  description: def.description,
@@ -112,11 +218,7 @@ export const registerBrowserTool = (
112
218
  promptGuidelines: [...def.promptGuidelines],
113
219
  parameters: def.parameters,
114
220
  ...(defRenderCall
115
- ? {
116
- renderCall: (args: Static<S>, theme: Theme, _ctx: Parameters<NonNullable<ToolDefinition<S>["renderCall"]>>[2]) =>
117
- // Sanctioned cast: at runtime args is always the concrete Static<S> value the tool was defined with.
118
- (defRenderCall as (args: unknown, theme: Theme) => Component)(args, theme),
119
- }
221
+ ? { renderCall: (args: Static<S>, theme: Theme) => defRenderCall(args, theme) }
120
222
  : {}),
121
223
  ...(defRenderResult
122
224
  ? {
@@ -124,64 +226,33 @@ export const registerBrowserTool = (
124
226
  result: AgentToolResult<unknown>,
125
227
  options: ToolRenderResultOptions,
126
228
  theme: Theme,
127
- _ctx: Parameters<NonNullable<ToolDefinition<S>["renderResult"]>>[3],
128
- ) => defRenderResult(result, options.expanded ?? false, theme),
229
+ ctx: RenderResultContext<S>,
230
+ ) => {
231
+ // A replayed error carries only the thrown text (details are empty), so the tool's own renderer never sees it.
232
+ if (ctx.isError) {
233
+ const text = storedText(result, `${def.name} failed (internal): unknown error`);
234
+ return new Text(theme.fg("error", text), 0, 0);
235
+ }
236
+ // Replayed details may predate the schema (older session, changed shape); then the stored text stands in.
237
+ const details: unknown = result.details;
238
+ if (!isDetails(details)) return new Text(storedText(result, ""), 0, 0);
239
+ return defRenderResult({ ...result, details }, options.expanded, theme);
240
+ },
129
241
  }
130
242
  : {}),
131
243
  async execute(_toolCallId, args, signal, onUpdate, extensionCtx) {
132
- if (def.ensureAlive !== false) {
133
- if (!(await daemonSocketMayExist())) {
134
- return toToolResult(
135
- {
136
- success: false,
137
- error: {
138
- kind: "not_connected",
139
- message: "Browser harness not initialized. Run /browser-setup first",
140
- },
141
- },
142
- def.name,
143
- );
144
- }
145
- const alive = await client.ensureAlive();
146
- if (!alive.success) {
147
- return toToolResult(
148
- { success: false, error: { kind: "not_connected", message: alive.error.message } },
149
- def.name,
150
- );
151
- }
152
- }
153
- let release: (() => void) | undefined;
154
- if (def.concurrency !== "parallel") {
155
- const acquire = await client.mutationMutex().acquire();
156
- release = acquire;
157
- if (signal?.aborted) {
158
- release();
159
- return toToolResult(
160
- { success: false, error: { kind: "invalid_state", message: "Tool execution aborted before entering serialized lane" } },
161
- def.name,
162
- );
163
- }
164
- }
165
- try {
166
- const result = await def.handler(args, {
167
- client,
168
- signal,
169
- onUpdate: (u) => {
170
- if (onUpdate) {
171
- const update: AgentToolResult<OkDetails> = {
172
- content: [{ type: "text", text: u.text }],
173
- details: { ok: true, ...(u.details ?? {}) },
174
- };
175
- onUpdate(update);
176
- }
177
- },
178
- extensionCtx,
179
- });
180
- return toToolResult(result, def.name);
181
- } finally {
182
- release?.();
183
- }
244
+ const result = await runHandler(def, client, args, signal, onUpdate, extensionCtx);
245
+ if (!result.success) throw new Error(renderToolError(def.name, result.error));
246
+ return okResult(result.data);
184
247
  },
185
248
  };
186
- pi.registerTool(td);
187
249
  };
250
+
251
+ export const defineBrowserTool = <S extends TSchema, D extends TSchema = UntypedDetailsSchema>(
252
+ def: BrowserToolDefinition<S, D>,
253
+ ): DefinedBrowserTool<S, D> => ({
254
+ ...def,
255
+ register: (pi, client) => {
256
+ pi.registerTool(toPiTool(def, client));
257
+ },
258
+ });