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.
- package/CHANGELOG.md +56 -0
- package/README.md +132 -0
- package/package.json +15 -7
- package/skills/pi-browser-harness/SKILL.md +89 -2
- package/src/cdp/commands.ts +205 -14
- package/src/cdp/console-buffer.ts +37 -23
- package/src/cdp/discovery.ts +57 -25
- package/src/cdp/events.ts +9 -3
- package/src/cdp/network-buffer.ts +38 -32
- package/src/cdp/ownership.ts +22 -4
- package/src/cdp/record-store.ts +2 -2
- package/src/cdp/session.ts +358 -216
- package/src/cdp/target-factory.ts +34 -15
- package/src/cdp/types.ts +17 -1
- package/src/client.ts +127 -54
- package/src/daemon/bridge.ts +110 -349
- package/src/daemon/connection.ts +323 -0
- package/src/daemon/index.ts +77 -48
- package/src/daemon/lines.ts +40 -0
- package/src/daemon/main.ts +12 -0
- package/src/daemon/protocol.ts +55 -25
- package/src/daemon/server.ts +100 -63
- package/src/daemon/socket.ts +10 -0
- package/src/daemon/spawn.ts +21 -22
- package/src/daemon/transport.ts +80 -49
- package/src/domains/ax-tree.ts +27 -8
- package/src/domains/cdp-call.ts +14 -7
- package/src/domains/click.ts +2 -2
- package/src/domains/concurrency.ts +50 -0
- package/src/domains/console.ts +20 -64
- package/src/domains/drag.ts +26 -28
- package/src/domains/element-call.ts +102 -68
- package/src/domains/files.ts +13 -9
- package/src/domains/form-batch.ts +13 -10
- package/src/domains/form.ts +78 -107
- package/src/domains/headers.ts +2 -2
- package/src/domains/history.ts +4 -4
- package/src/domains/io.ts +35 -0
- package/src/domains/isolated-tab.ts +6 -12
- package/src/domains/js.ts +67 -46
- package/src/domains/keyboard.ts +14 -11
- package/src/domains/navigate.ts +102 -66
- package/src/domains/network.ts +55 -95
- package/src/domains/page/fill.page.ts +139 -0
- package/src/domains/page/form.page.ts +61 -0
- package/src/domains/page/inject.ts +37 -0
- package/src/domains/page/keyboard.page.ts +16 -0
- package/src/domains/page/live-value.page.ts +10 -0
- package/src/domains/page/read-page.page.ts +51 -0
- package/src/domains/page/recipe.page.ts +82 -0
- package/src/domains/page/serp.page.ts +42 -0
- package/src/domains/page.ts +18 -51
- package/src/domains/poll.ts +42 -0
- package/src/domains/readpage/read-page.ts +48 -53
- package/src/domains/ref-resolve.ts +43 -29
- package/src/domains/ref-signature.ts +11 -0
- package/src/domains/render.ts +12 -23
- package/src/domains/screenshot-capture.ts +4 -2
- package/src/domains/screenshot.ts +13 -10
- package/src/domains/scroll.ts +4 -4
- package/src/domains/search/google-serp.ts +78 -8
- package/src/domains/search/redirect-resolver.ts +41 -0
- package/src/domains/search/web-search.ts +103 -40
- package/src/domains/snapshot.ts +81 -78
- package/src/domains/tab-resolve.ts +36 -0
- package/src/domains/tabs.ts +18 -69
- package/src/domains/target.ts +1 -1
- package/src/index.ts +101 -33
- package/src/profile/bind.ts +45 -14
- package/src/profile/browser-process.ts +50 -12
- package/src/profile/command.ts +20 -12
- package/src/profile/launch.ts +13 -9
- package/src/profile/list.ts +9 -13
- package/src/profile/store.ts +2 -1
- package/src/prompt.ts +34 -8
- package/src/recipes/command.ts +96 -0
- package/src/recipes/compile.ts +198 -0
- package/src/recipes/find.ts +49 -0
- package/src/recipes/journal.ts +125 -0
- package/src/recipes/recipe.ts +215 -0
- package/src/recipes/recordable.ts +359 -0
- package/src/recipes/replay.ts +354 -0
- package/src/recipes/run-tool.ts +132 -0
- package/src/recipes/save-tool.ts +247 -0
- package/src/recipes/store.ts +103 -0
- package/src/recipes/trust.ts +172 -0
- package/src/registry.ts +69 -4
- package/src/schemas/parse.ts +2 -2
- package/src/setup.ts +28 -19
- package/src/state.ts +2 -1
- package/src/util/debug.ts +7 -1
- package/src/util/guards.ts +3 -0
- package/src/util/js-source.ts +28 -0
- package/src/util/mutex.ts +1 -1
- package/src/util/paths.ts +3 -2
- package/src/util/result.ts +8 -0
- package/src/util/sharp-shim.ts +18 -11
- package/src/util/sleep.ts +18 -0
- package/src/util/tool.ts +185 -114
- package/src/util/truncate.ts +1 -1
- package/tsconfig.json +2 -1
- 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
|
-
|
|
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 =
|
|
29
|
+
export type SetupResult = Result<string, string>;
|
|
23
30
|
|
|
24
|
-
export async function performSetup(
|
|
25
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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"
|
|
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 &&
|
|
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
|
|
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
|
-
|
|
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 ||
|
|
14
|
+
flagEnabled || envFlagEnabled(env["BH_DEBUG_CLICKS"]);
|
package/src/util/guards.ts
CHANGED
|
@@ -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
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
|
-
|
|
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_-]+$/;
|
package/src/util/result.ts
CHANGED
|
@@ -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);
|
package/src/util/sharp-shim.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
|
20
|
-
|
|
21
|
-
"
|
|
22
|
-
"
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
15
|
+
import { type Result, err, ok } from "./result";
|
|
14
16
|
|
|
15
|
-
|
|
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?:
|
|
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
|
|
76
|
+
ctx: HandlerContext<T>,
|
|
77
|
+
) => Promise<Result<ToolOk<T>, ToolErr>>;
|
|
78
|
+
|
|
79
|
+
export type ToolConcurrency = "serialized" | "parallel";
|
|
45
80
|
|
|
46
|
-
|
|
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
|
|
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<
|
|
56
|
-
readonly concurrency:
|
|
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
|
-
//
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
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
|
-
|
|
100
|
-
|
|
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
|
-
|
|
103
|
-
): void => {
|
|
104
|
-
type S = TSchema;
|
|
209
|
+
): ToolDefinition<S> => {
|
|
105
210
|
const defRenderCall = def.renderCall;
|
|
106
211
|
const defRenderResult = def.renderResult;
|
|
107
|
-
const
|
|
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
|
-
|
|
128
|
-
) =>
|
|
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
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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
|
+
});
|