pi-browser-harness 0.11.0 → 0.13.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 (90) hide show
  1. package/CHANGELOG.md +62 -0
  2. package/README.md +102 -1
  3. package/package.json +13 -7
  4. package/skills/pi-browser-harness/SKILL.md +84 -0
  5. package/src/cdp/commands.ts +204 -14
  6. package/src/cdp/console-buffer.ts +37 -23
  7. package/src/cdp/discovery.ts +72 -37
  8. package/src/cdp/events.ts +8 -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 +320 -217
  13. package/src/cdp/target-factory.ts +34 -15
  14. package/src/cdp/types.ts +17 -1
  15. package/src/client.ts +76 -43
  16. package/src/daemon/bridge.ts +115 -191
  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 +84 -27
  25. package/src/daemon/transport.ts +88 -52
  26. package/src/domains/ax-tree.ts +8 -8
  27. package/src/domains/cdp-call.ts +14 -7
  28. package/src/domains/click.ts +2 -7
  29. package/src/domains/concurrency.ts +50 -0
  30. package/src/domains/console.ts +20 -66
  31. package/src/domains/drag.ts +26 -28
  32. package/src/domains/element-call.ts +102 -68
  33. package/src/domains/files.ts +64 -11
  34. package/src/domains/form-batch.ts +13 -11
  35. package/src/domains/form.ts +79 -116
  36. package/src/domains/headers.ts +89 -0
  37. package/src/domains/history.ts +7 -7
  38. package/src/domains/io.ts +35 -0
  39. package/src/domains/isolated-tab.ts +6 -12
  40. package/src/domains/js.ts +68 -53
  41. package/src/domains/keyboard.ts +16 -18
  42. package/src/domains/navigate.ts +102 -69
  43. package/src/domains/network.ts +56 -98
  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/serp.page.ts +39 -0
  51. package/src/domains/page.ts +19 -58
  52. package/src/domains/poll.ts +42 -0
  53. package/src/domains/readpage/read-page.ts +48 -54
  54. package/src/domains/ref-resolve.ts +43 -29
  55. package/src/domains/ref-signature.ts +11 -0
  56. package/src/domains/render.ts +12 -23
  57. package/src/domains/screenshot-capture.ts +4 -2
  58. package/src/domains/screenshot.ts +13 -14
  59. package/src/domains/scroll.ts +4 -5
  60. package/src/domains/search/google-serp.ts +1 -1
  61. package/src/domains/search/web-search.ts +38 -34
  62. package/src/domains/setup.ts +0 -2
  63. package/src/domains/snapshot.ts +72 -77
  64. package/src/domains/tab-resolve.ts +36 -0
  65. package/src/domains/tabs.ts +19 -78
  66. package/src/domains/target.ts +1 -1
  67. package/src/domains/viewport.ts +0 -1
  68. package/src/index.ts +100 -39
  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 +42 -117
  76. package/src/registry.ts +68 -4
  77. package/src/schemas/parse.ts +2 -2
  78. package/src/setup.ts +28 -19
  79. package/src/state.ts +33 -2
  80. package/src/util/debug.ts +7 -1
  81. package/src/util/guards.ts +3 -0
  82. package/src/util/mutex.ts +1 -1
  83. package/src/util/paths.ts +12 -1
  84. package/src/util/result.ts +8 -0
  85. package/src/util/sharp-shim.ts +18 -11
  86. package/src/util/sleep.ts +18 -0
  87. package/src/util/tool.ts +163 -114
  88. package/src/util/truncate.ts +1 -1
  89. package/tsconfig.json +2 -1
  90. package/src/domains/fill-engine.ts +0 -80
@@ -1,9 +1,13 @@
1
- import { readFileSync, writeFileSync } from "node:fs";
1
+ import { readFileSync } from "node:fs";
2
2
  import { Type } from "typebox";
3
- import { Container, Image, type ImageTheme, Markdown, Text, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
3
+ import { Container, Image, type ImageTheme, Markdown, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
4
4
  import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
5
+ import type { BrowserClient } from "../client";
5
6
  import { boxOf } from "./box";
6
- import { cdpCall } from "./cdp-call";
7
+ import { cdpCall, fromClient } from "./cdp-call";
8
+ import { deadlineSignal, runLimited } from "./concurrency";
9
+ import { writeFileResult } from "./io";
10
+ import { type RefSignature, signatureOf } from "./ref-signature";
7
11
  import {
8
12
  buildTree,
9
13
  collectInteractiveTargets,
@@ -14,11 +18,10 @@ import {
14
18
  stripInternals,
15
19
  VALUE_ROLES,
16
20
  } from "./ax-tree";
17
- import { type Result, err, ok } from "../util/result";
18
- import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
21
+ import { type Result, ok } from "../util/result";
22
+ import { type DetailsOf, defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
19
23
  import { applyTruncation } from "../util/truncate";
20
24
  import { screenshotPath } from "../util/paths";
21
- import { asBoolean, asNumber, asRecord, asString } from "../util/guards";
22
25
 
23
26
  const SnapshotArgs = Type.Object({
24
27
  includeScreenshot: Type.Optional(
@@ -82,13 +85,28 @@ const renderOutline = (nodes: ReadonlyArray<SlimNode>): string => {
82
85
  return lines.join("\n");
83
86
  };
84
87
 
85
- type SnapshotDetails = {
86
- nodeCount: number;
87
- truncated: boolean;
88
- fullOutputPath?: string;
89
- screenshotPath?: string;
90
- url: string;
91
- title: string;
88
+ const SnapshotDetailsSchema = Type.Object({
89
+ nodeCount: Type.Number(),
90
+ truncated: Type.Boolean(),
91
+ fullOutputPath: Type.Optional(Type.String()),
92
+ screenshotPath: Type.Optional(Type.String()),
93
+ url: Type.String(),
94
+ title: Type.String(),
95
+ summary: Type.String(),
96
+ });
97
+
98
+ export type SnapshotDetails = DetailsOf<typeof SnapshotDetailsSchema>;
99
+
100
+ const BOX_BUDGET_MS = 1_500;
101
+ const BOX_CONCURRENCY = 8;
102
+
103
+ // Best-effort: a capture or write failure just drops the screenshot from the result.
104
+ const captureJpeg = async (client: BrowserClient): Promise<string | undefined> => {
105
+ const shot = await cdpCall(client, "Page.captureScreenshot", { format: "jpeg", quality: 80 });
106
+ if (!shot.success) return undefined;
107
+ const path = screenshotPath(client.namespace, "jpeg");
108
+ const written = await writeFileResult(path, Buffer.from(shot.data.data, "base64"));
109
+ return written.success ? path : undefined;
92
110
  };
93
111
 
94
112
  export const snapshotTool = defineBrowserTool({
@@ -98,27 +116,25 @@ export const snapshotTool = defineBrowserTool({
98
116
  "DEFAULT tool for understanding what is on the page. Returns the structured accessibility tree (roles, names, states, hierarchy). Every interactive element gets a stable ref shown as [eN] plus click coordinates @(x,y). Pass the ref to browser_click/browser_fill/etc. — refs survive re-renders, coordinates don't. Use this BEFORE deciding whether you need a screenshot. Pair with browser_execute_js for surgical reads of specific element values.",
99
117
  promptSnippet: "Get accessibility-tree snapshot with stable element refs (default for page inspection)",
100
118
  promptGuidelines: [
101
- "DEFAULT — use this whenever you need to know what's on a page, what's clickable, or how the page is structured.",
102
- "Refs come for free: every interactive element shows '[eN]' in the outline. Pass eN as `ref` to browser_click/browser_fill/browser_select_option/browser_focus/browser_upload_file — refs survive re-renders, so prefer them over the '@(x,y)' coordinates (a fallback).",
103
- "DO NOT call browser_screenshot just to understand the page. This tool already gives you structure, labels, states, refs, and click targets.",
104
- "Re-run after a navigation or a major re-render to get fresh refs; a 'ref is stale' error from an interaction tool means you need a new snapshot.",
119
+ "Re-run browser_snapshot after a navigation or a major re-render to get fresh refs.",
105
120
  "Pass includeScreenshot:true ONLY if you also need to verify visual rendering (rare).",
106
121
  "format:'json' returns the raw slim structure (with `ref` and `box` per node) for programmatic use; default 'outline' is human/LLM-readable.",
107
122
  ],
108
123
  parameters: SnapshotArgs,
124
+ details: SnapshotDetailsSchema,
109
125
  concurrency: "parallel",
110
126
 
111
- async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
127
+ async handler(args, { client, signal }): Promise<Result<ToolOk<SnapshotDetails>, ToolErr>> {
112
128
  const session = client.session();
113
129
 
114
130
  const axRes = await cdpCall(client, "Accessibility.getFullAXTree", {});
115
131
  if (!axRes.success) return axRes;
116
132
  const rawNodes = axRes.data.nodes;
117
133
 
118
- const piRes = await client.pageInfo();
119
- if (!piRes.success) return err({ kind: "cdp_error", message: piRes.error.message });
120
- const pageUrl = "dialog" in piRes.data ? "" : piRes.data.url;
121
- const pageTitle = "dialog" in piRes.data ? "" : piRes.data.title;
134
+ const piRes = fromClient(await client.pageInfo(), "pageInfo");
135
+ if (!piRes.success) return piRes;
136
+ const pageUrl = piRes.data.kind === "dialog" ? "" : piRes.data.url;
137
+ const pageTitle = piRes.data.kind === "dialog" ? "" : piRes.data.title;
122
138
 
123
139
  const slim = buildTree(rawNodes, {
124
140
  interestingOnly: args.interestingOnly ?? true,
@@ -135,101 +151,80 @@ export const snapshotTool = defineBrowserTool({
135
151
  });
136
152
 
137
153
  if (targets.length > 0) {
138
- const ac = new AbortController();
139
- const timer = setTimeout(() => ac.abort(), 1_500);
140
- await Promise.allSettled(
141
- targets.map(async ({ node, backendId }) => {
142
- if (ac.signal.aborted) return;
143
- const box = await boxOf(client, backendId);
144
- if (!box.success) return;
145
- if (box.data.x < 0 || box.data.y < 0) return;
146
- node.box = box.data;
147
- if (ac.signal.aborted || !VALUE_ROLES.has(node.role)) return;
148
- const live = await liveValue(client, backendId);
149
- if (live !== undefined) node.value = live;
150
- }),
151
- );
152
- clearTimeout(timer);
154
+ // Geometry and live values are best-effort decoration: whatever lands inside the budget is kept, the rest is omitted.
155
+ const deadline = deadlineSignal(BOX_BUDGET_MS, signal);
156
+ await runLimited(targets, { limit: BOX_CONCURRENCY, signal: deadline.signal }, async ({ node, backendId }, sig) => {
157
+ const box = await boxOf(client, backendId);
158
+ if (!box.success || sig.aborted) return;
159
+ if (box.data.x < 0 || box.data.y < 0) return;
160
+ node.box = box.data;
161
+ if (!VALUE_ROLES.has(node.role)) return;
162
+ const live = await liveValue(client, backendId);
163
+ if (live !== undefined) node.value = live;
164
+ });
165
+ deadline.clear();
153
166
  }
154
167
 
155
- const refSig = new Map<string, string>();
168
+ const refSig = new Map<string, RefSignature>();
156
169
  for (const { node } of targets) {
157
170
  if (node.ref === undefined) continue;
158
- refSig.set(node.ref, `${node.role}|${node.name ?? ""}|${node.value ?? ""}|${node.state ?? ""}`);
171
+ refSig.set(node.ref, signatureOf(node));
159
172
  }
160
173
  session.setRefMap(refMap, refSig);
161
174
 
162
- const stripped = stripInternals(slim);
163
- const text = (args.format ?? "outline") === "outline" ? renderOutline(slim) : JSON.stringify(stripped, null, 2);
175
+ const text = (args.format ?? "outline") === "outline" ? renderOutline(slim) : JSON.stringify(stripInternals(slim), null, 2);
164
176
  const trunc = await applyTruncation(text, "snapshot");
165
177
 
166
- let shotPath: string | undefined;
167
- if (args.includeScreenshot) {
168
- const shot = await cdpCall(client, "Page.captureScreenshot", { format: "jpeg", quality: 80 });
169
- if (shot.success) {
170
- shotPath = screenshotPath(client.namespace, "jpeg");
171
- writeFileSync(shotPath, Buffer.from(shot.data.data, "base64"));
172
- }
173
- }
178
+ const shotPath = args.includeScreenshot ? await captureJpeg(client) : undefined;
174
179
 
175
180
  const details: SnapshotDetails = {
176
181
  nodeCount: countNodes(slim),
177
182
  truncated: trunc.wasTruncated,
178
183
  url: pageUrl,
179
184
  title: pageTitle,
185
+ summary: summarize(slim),
186
+ ...(trunc.fullOutputPath !== undefined ? { fullOutputPath: trunc.fullOutputPath } : {}),
187
+ ...(shotPath !== undefined ? { screenshotPath: shotPath } : {}),
180
188
  };
181
- if (trunc.fullOutputPath !== undefined) details.fullOutputPath = trunc.fullOutputPath;
182
- if (shotPath !== undefined) details.screenshotPath = shotPath;
183
189
 
184
- return ok({ text: trunc.text, details: { ...details, summary: summarize(slim) } });
190
+ return ok({ text: trunc.text, details });
185
191
  },
186
192
 
187
193
  renderResult(result, expanded, theme) {
188
- const raw = asRecord(result.details);
189
- if (raw === undefined) return new Text(theme.fg("error", "snapshot: no details"), 0, 0);
190
- const details = {
191
- nodeCount: asNumber(raw["nodeCount"]),
192
- truncated: asBoolean(raw["truncated"]),
193
- fullOutputPath: asString(raw["fullOutputPath"]),
194
- screenshotPath: asString(raw["screenshotPath"]),
195
- url: asString(raw["url"]),
196
- title: asString(raw["title"]),
197
- summary: asString(raw["summary"]),
198
- };
199
-
200
- const titleLine = details.title ? ` "${details.title}"` : "";
201
- const summary = details.summary ?? "";
202
- const screenshotNote = details.screenshotPath ? "screenshot attached" : "screenshot omitted";
203
- const truncNote = details.truncated && details.fullOutputPath ? `\n\nFull tree at \`${details.fullOutputPath}\`` : "";
194
+ const details = result.details;
195
+ const titleLine = details.title !== "" ? ` "${details.title}"` : "";
196
+ const urlLabel = details.url !== "" ? details.url : "(no url)";
197
+ const screenshotNote = details.screenshotPath !== undefined ? "screenshot attached" : "screenshot omitted";
198
+ const truncNote = details.truncated && details.fullOutputPath !== undefined ? `\n\nFull tree at \`${details.fullOutputPath}\`` : "";
204
199
 
205
200
  if (!expanded) {
206
201
  const md = [
207
- `**AX tree:** ${details.nodeCount} nodes · \`${details.url || "(no url)"}\``,
208
- `${titleLine ? " " + titleLine : ""}`,
209
- summary ? ` • ${summary}` : "",
202
+ `**AX tree:** ${details.nodeCount} nodes · \`${urlLabel}\``,
203
+ titleLine !== "" ? ` ${titleLine}` : "",
204
+ details.summary !== "" ? ` • ${details.summary}` : "",
210
205
  ` ${keyHint("app.tools.expand", "to expand")} · ${screenshotNote}`,
211
206
  ].filter((l) => l !== "").join("\n");
212
207
  return new Markdown(md, 0, 0, getMarkdownTheme());
213
208
  }
214
209
 
215
210
  const content = result.content[0];
216
- const treeText = content && content.type === "text" ? content.text : "";
211
+ const treeText = content?.type === "text" ? content.text : "";
217
212
 
218
213
  const headerMd = [
219
- `**AX tree:** ${details.nodeCount} nodes · \`${details.url || "(no url)"}\``,
220
- titleLine ? ` ${titleLine}` : "",
214
+ `**AX tree:** ${details.nodeCount} nodes · \`${urlLabel}\``,
215
+ titleLine !== "" ? ` ${titleLine}` : "",
221
216
  "",
222
217
  "```",
223
218
  treeText,
224
219
  "```",
225
220
  truncNote,
226
221
  "",
227
- `${keyHint("app.tools.expand", "to collapse")}`,
222
+ keyHint("app.tools.expand", "to collapse"),
228
223
  ].filter((l) => l !== "").join("\n");
229
224
 
230
225
  const treeBlock = new Markdown(headerMd, 0, 0, getMarkdownTheme());
231
226
 
232
- if (!details.screenshotPath) return treeBlock;
227
+ if (details.screenshotPath === undefined) return treeBlock;
233
228
 
234
229
  try {
235
230
  const buf = readFileSync(details.screenshotPath);
@@ -241,7 +236,7 @@ export const snapshotTool = defineBrowserTool({
241
236
  filename: details.screenshotPath,
242
237
  });
243
238
  const safeImage = {
244
- invalidate: () => image.invalidate(),
239
+ invalidate: () => { image.invalidate(); },
245
240
  render: (width: number) =>
246
241
  image.render(width).map((line) => (visibleWidth(line) > width ? truncateToWidth(line, width) : line)),
247
242
  };
@@ -0,0 +1,36 @@
1
+ import type { BrowserClient } from "../client";
2
+ import { type Result, err, ok } from "../util/result";
3
+ import type { ToolErr } from "../util/tool";
4
+
5
+ const HEX_PREFIX = /^[0-9A-Fa-f]{8,}$/;
6
+
7
+ export const ownershipDeniedMessage = (id: string, namespace: string): string =>
8
+ `Tab ${id} is not owned by this harness session (namespace: ${namespace}). ` +
9
+ `Use browser_list_tabs with scope:'all' to see it, or browser_new_tab to open one this session can control.`;
10
+
11
+ // Resolves a user-supplied target id against the tabs this session owns, and only those:
12
+ // - an exact owned id resolves to itself;
13
+ // - a hex prefix of 8+ characters resolves when it matches exactly one owned tab;
14
+ // - a prefix matching several owned tabs is invalid_args;
15
+ // - anything else (unowned id, prefix matching nothing owned) is invalid_state with the ownership message.
16
+ // Ownership is read from the registry, so no CDP round trip is made.
17
+ export const resolveOwnedTargetId = (client: BrowserClient, input: string): Result<string, ToolErr> => {
18
+ if (client.owns(input)) return ok(input);
19
+ if (HEX_PREFIX.test(input)) {
20
+ const matches = client.ownership().list().filter((id) => id.startsWith(input));
21
+ const first = matches[0];
22
+ if (matches.length === 1 && first !== undefined) return ok(first);
23
+ if (matches.length > 1) {
24
+ return err({
25
+ kind: "invalid_args",
26
+ message: `Ambiguous prefix "${input}" matches ${matches.length} owned tabs: ${matches.join(", ")}`,
27
+ details: { matches },
28
+ });
29
+ }
30
+ }
31
+ return err({
32
+ kind: "invalid_state",
33
+ message: ownershipDeniedMessage(input, client.namespace),
34
+ details: { targetId: input, namespace: client.namespace },
35
+ });
36
+ };
@@ -1,7 +1,8 @@
1
1
  import { Type } from "typebox";
2
2
  import { type Result, err, ok } from "../util/result";
3
3
  import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
4
- import { cdpCallBrowser } from "./cdp-call";
4
+ import { cdpCallBrowser, fromClient } from "./cdp-call";
5
+ import { resolveOwnedTargetId } from "./tab-resolve";
5
6
 
6
7
  const ListTabsArgs = Type.Object({
7
8
  includeInternal: Type.Optional(Type.Boolean({ default: true, description: "Include chrome:// pages" })),
@@ -19,16 +20,13 @@ export const listTabsTool = defineBrowserTool({
19
20
  description: "List browser tabs. Defaults to tabs this harness session opened (scope:'owned'). Pass scope:'all' to see the user's other tabs too.",
20
21
  promptSnippet: "List browser tabs",
21
22
  promptGuidelines: [
22
- "Defaults to scope:'owned' — only tabs this session created. Pass scope:'all' to inspect the user's other tabs.",
23
- "browser_switch_tab and browser_close_tab refuse non-owned tabs; use browser_new_tab to open one this session controls.",
24
23
  "Each tab shows its full 32-char hex targetId — use the exact value with browser_switch_tab.",
25
- "Internal tabs (chrome://) included by default; pass includeInternal=false to exclude them.",
26
24
  ],
27
25
  parameters: ListTabsArgs,
28
26
  concurrency: "parallel",
29
27
  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
30
- const r = await client.listTabs(args.includeInternal ?? true);
31
- if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
28
+ const r = fromClient(await client.listTabs(args.includeInternal ?? true), "Target.getTargets");
29
+ if (!r.success) return r;
32
30
  const scope = args.scope ?? "owned";
33
31
  const filtered = scope === "owned" ? r.data.filter((t) => t.owned) : r.data;
34
32
  const lines = filtered.map((t, i) => {
@@ -71,10 +69,6 @@ const SwitchTabArgs = Type.Object({
71
69
  targetId: Type.String({ description: "Target ID from browser_list_tabs" }),
72
70
  });
73
71
 
74
- const ownershipDeniedMessage = (id: string, namespace: string): string =>
75
- `Tab ${id} is not owned by this harness session (namespace: ${namespace}). ` +
76
- `Use browser_list_tabs with scope:'all' to see it, or browser_new_tab to open one this session can control.`;
77
-
78
72
  export const switchTabTool = defineBrowserTool({
79
73
  name: "browser_switch_tab",
80
74
  label: "Browser Switch Tab",
@@ -82,45 +76,16 @@ export const switchTabTool = defineBrowserTool({
82
76
  promptSnippet: "Switch tabs",
83
77
  promptGuidelines: [
84
78
  "Get a targetId via browser_list_tabs first.",
85
- "Accepts exact targetId or a unique prefix of at least 8 hex characters.",
86
- "Refuses tabs not owned by this session — use browser_new_tab to open a controllable tab instead.",
79
+ "Accepts exact targetId or a unique prefix (>=8 hex characters) of an owned tab.",
87
80
  ],
88
81
  parameters: SwitchTabArgs,
89
82
  concurrency: "serialized",
90
83
  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
91
- let resolved = args.targetId;
92
- if (!client.owns(resolved)) {
93
- const isHexPrefix = /^[0-9A-Fa-f]{8,}$/.test(args.targetId);
94
- if (isHexPrefix) {
95
- const tabs = await client.listTabs(true);
96
- if (!tabs.success) return err({ kind: "cdp_error", message: tabs.error.message });
97
- const matches = tabs.data.filter((t) => t.targetId.startsWith(args.targetId));
98
- if (matches.length === 0) {
99
- return err({ kind: "cdp_error", message: `No tab found with prefix "${args.targetId}"` });
100
- }
101
- if (matches.length > 1) {
102
- const ids = matches.map((t) => t.targetId).join(", ");
103
- return err({
104
- kind: "invalid_state",
105
- message: `Ambiguous prefix "${args.targetId}" matches ${matches.length} tabs: ${ids}`,
106
- details: { matches: matches.map((t) => ({ targetId: t.targetId, url: t.url })) },
107
- });
108
- }
109
- const first = matches[0];
110
- if (first === undefined) return err({ kind: "invalid_state", message: "no matching tab" });
111
- resolved = first.targetId;
112
- }
113
- if (!client.owns(resolved)) {
114
- return err({
115
- kind: "invalid_state",
116
- message: ownershipDeniedMessage(resolved, client.namespace),
117
- details: { targetId: resolved, namespace: client.namespace },
118
- });
119
- }
120
- }
121
-
122
- const r = await client.switchTab(resolved);
123
- if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
84
+ const target = resolveOwnedTargetId(client, args.targetId);
85
+ if (!target.success) return target;
86
+ const resolved = target.data;
87
+ const r = fromClient(await client.switchTab(resolved), "Target.attachToTarget");
88
+ if (!r.success) return r;
124
89
  const note = resolved === args.targetId ? "" : ` (resolved from prefix "${args.targetId}")`;
125
90
  return ok({
126
91
  text: `Switched to ${resolved}${note}`,
@@ -138,15 +103,12 @@ export const newTabTool = defineBrowserTool({
138
103
  label: "Browser New Tab",
139
104
  description: "Open a new tab in the harness's dedicated Chrome window and switch to it. Optionally navigate to a URL.",
140
105
  promptSnippet: "Open a new tab",
141
- promptGuidelines: [
142
- "All tabs opened by this tool live in a single dedicated Chrome window separate from the user's main browsing.",
143
- "Pass url to navigate immediately.",
144
- ],
106
+ promptGuidelines: [],
145
107
  parameters: NewTabArgs,
146
108
  concurrency: "serialized",
147
109
  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
148
- const r = await client.newTab(args.url);
149
- if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
110
+ const r = fromClient(await client.newTab(args.url), "Target.createTarget");
111
+ if (!r.success) return r;
150
112
  return ok({
151
113
  text: `New tab: ${r.data}${args.url ? ` (${args.url})` : ""}`,
152
114
  details: args.url !== undefined
@@ -166,37 +128,16 @@ export const closeTabTool = defineBrowserTool({
166
128
  description: "Close a tab the harness owns. Refuses tabs not opened by this session.",
167
129
  promptSnippet: "Close an owned tab",
168
130
  promptGuidelines: [
169
- "Only closes tabs this session opened (visible in browser_list_tabs default scope).",
170
- "Accepts exact targetId or a unique hex prefix (>=8 chars).",
131
+ "Same targetId rules as browser_switch_tab: exact id or a unique prefix (>=8 hex) of an owned tab.",
171
132
  ],
172
133
  parameters: CloseTabArgs,
173
134
  concurrency: "serialized",
174
135
  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
175
- let resolved = args.targetId;
176
- if (!client.owns(resolved)) {
177
- const isHexPrefix = /^[0-9A-Fa-f]{8,}$/.test(args.targetId);
178
- if (isHexPrefix) {
179
- const owned = client.ownership().list();
180
- const matches = owned.filter((id) => id.startsWith(args.targetId));
181
- const first = matches[0];
182
- if (matches.length === 1 && first !== undefined) resolved = first;
183
- else if (matches.length > 1) {
184
- return err({
185
- kind: "invalid_state",
186
- message: `Ambiguous prefix "${args.targetId}" matches ${matches.length} owned tabs: ${matches.join(", ")}`,
187
- });
188
- }
189
- }
190
- if (!client.owns(resolved)) {
191
- return err({
192
- kind: "invalid_state",
193
- message: ownershipDeniedMessage(resolved, client.namespace),
194
- details: { targetId: resolved, namespace: client.namespace },
195
- });
196
- }
197
- }
198
- const r = await client.closeTab(resolved);
199
- if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
136
+ const target = resolveOwnedTargetId(client, args.targetId);
137
+ if (!target.success) return target;
138
+ const resolved = target.data;
139
+ const r = fromClient(await client.closeTab(resolved), "Target.closeTarget");
140
+ if (!r.success) return r;
200
141
  return ok({ text: `Closed tab ${resolved}`, details: { targetId: resolved } });
201
142
  },
202
143
  });
@@ -31,5 +31,5 @@ export const resolveTarget = async (
31
31
  if (args.x !== undefined && args.y !== undefined) {
32
32
  return ok({ x: args.x, y: args.y, label: `(${args.x}, ${args.y})` });
33
33
  }
34
- return err({ kind: "invalid_state", message: "Provide either `ref` or both `x` and `y`." });
34
+ return err({ kind: "invalid_args", message: "Provide either `ref` or both `x` and `y`." });
35
35
  };
@@ -17,7 +17,6 @@ export const viewportResizeTool = defineBrowserTool({
17
17
  description: "Override the viewport size and device pixel ratio for responsive testing.",
18
18
  promptSnippet: "Resize the viewport (responsive testing)",
19
19
  promptGuidelines: [
20
- "Width/height in CSS pixels (e.g., 375x667 for iPhone SE).",
21
20
  "Pass deviceScaleFactor=2 to simulate retina displays.",
22
21
  ],
23
22
  parameters: ViewportArgs,