@parcha/pi-browser 0.0.0-stage → 0.1.0-beta.13

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 (104) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +33 -0
  4. package/README.md +329 -2
  5. package/dist/coding-agent-local.d.ts +16 -0
  6. package/dist/coding-agent-local.js +138 -0
  7. package/dist/coding-agent.d.ts +78 -0
  8. package/dist/coding-agent.js +446 -0
  9. package/dist/core/contract.d.ts +26 -0
  10. package/dist/core/contract.js +154 -0
  11. package/dist/core/custody.d.ts +111 -0
  12. package/dist/core/custody.js +122 -0
  13. package/dist/core/decisions.d.ts +43 -0
  14. package/dist/core/decisions.js +4 -0
  15. package/dist/core/downloads.d.ts +35 -0
  16. package/dist/core/downloads.js +131 -0
  17. package/dist/core/effects.d.ts +63 -0
  18. package/dist/core/effects.js +256 -0
  19. package/dist/core/evidence.d.ts +43 -0
  20. package/dist/core/evidence.js +6 -0
  21. package/dist/core/failures.d.ts +28 -0
  22. package/dist/core/failures.js +59 -0
  23. package/dist/core/find.d.ts +32 -0
  24. package/dist/core/find.js +179 -0
  25. package/dist/core/guard.d.ts +6 -0
  26. package/dist/core/guard.js +24 -0
  27. package/dist/core/host.d.ts +279 -0
  28. package/dist/core/host.js +2 -0
  29. package/dist/core/images.d.ts +37 -0
  30. package/dist/core/images.js +60 -0
  31. package/dist/core/lease.d.ts +16 -0
  32. package/dist/core/lease.js +30 -0
  33. package/dist/core/receipts.d.ts +19 -0
  34. package/dist/core/receipts.js +22 -0
  35. package/dist/core/redact.d.ts +13 -0
  36. package/dist/core/redact.js +83 -0
  37. package/dist/core/session-control.d.ts +25 -0
  38. package/dist/core/session-control.js +75 -0
  39. package/dist/core/sites.d.ts +33 -0
  40. package/dist/core/sites.js +102 -0
  41. package/dist/core/tools.d.ts +37 -0
  42. package/dist/core/tools.js +170 -0
  43. package/dist/core/uri.d.ts +11 -0
  44. package/dist/core/uri.js +37 -0
  45. package/dist/core/usage.d.ts +38 -0
  46. package/dist/core/usage.js +44 -0
  47. package/dist/core/web.d.ts +98 -0
  48. package/dist/core/web.js +327 -0
  49. package/dist/driver/stagehand.d.ts +25 -0
  50. package/dist/driver/stagehand.js +141 -0
  51. package/dist/durable-result.d.ts +6 -0
  52. package/dist/durable-result.js +2 -0
  53. package/dist/durable.d.ts +75 -0
  54. package/dist/durable.js +484 -0
  55. package/dist/index.d.ts +18 -0
  56. package/dist/index.js +19 -0
  57. package/dist/providers/browserbase-net.d.ts +13 -0
  58. package/dist/providers/browserbase-net.js +96 -0
  59. package/dist/providers/browserbase.d.ts +152 -0
  60. package/dist/providers/browserbase.js +262 -0
  61. package/dist/providers/cdp-call.d.ts +6 -0
  62. package/dist/providers/cdp-call.js +25 -0
  63. package/dist/providers/cdp.d.ts +48 -0
  64. package/dist/providers/cdp.js +353 -0
  65. package/dist/providers/http.d.ts +2 -0
  66. package/dist/providers/http.js +21 -0
  67. package/dist/providers/kernel.d.ts +49 -0
  68. package/dist/providers/kernel.js +246 -0
  69. package/dist/providers/shared.d.ts +47 -0
  70. package/dist/providers/shared.js +82 -0
  71. package/dist/recorder/credential.d.ts +9 -0
  72. package/dist/recorder/credential.js +49 -0
  73. package/dist/recorder/follow.d.ts +26 -0
  74. package/dist/recorder/follow.js +138 -0
  75. package/dist/recorder/frames.d.ts +80 -0
  76. package/dist/recorder/frames.js +309 -0
  77. package/dist/recorder/index.d.ts +3 -0
  78. package/dist/recorder/index.js +6 -0
  79. package/dist/recorder/jpeg.d.ts +5 -0
  80. package/dist/recorder/jpeg.js +34 -0
  81. package/dist/store.d.ts +56 -0
  82. package/dist/store.js +196 -0
  83. package/dist/testing/backend.d.ts +231 -0
  84. package/dist/testing/backend.js +414 -0
  85. package/dist/testing/driver.d.ts +28 -0
  86. package/dist/testing/driver.js +32 -0
  87. package/dist/testing/index.d.ts +4 -0
  88. package/dist/testing/index.js +4 -0
  89. package/dist/testing/pages.d.ts +3 -0
  90. package/dist/testing/pages.js +10 -0
  91. package/dist/testing/sentinels.d.ts +29 -0
  92. package/dist/testing/sentinels.js +38 -0
  93. package/dist/vendor/stagehand-facade/contract.d.ts +348 -0
  94. package/dist/vendor/stagehand-facade/contract.js +155 -0
  95. package/dist/vendor/stagehand-facade/runtime.d.ts +90 -0
  96. package/dist/vendor/stagehand-facade/runtime.js +1640 -0
  97. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +15 -0
  98. package/dist/vendor/stagehand-facade/screenshot-transport.js +51 -0
  99. package/dist/vendor/stagehand-facade/tools.d.ts +31 -0
  100. package/dist/vendor/stagehand-facade/tools.js +139 -0
  101. package/dist/web.d.ts +41 -0
  102. package/dist/web.js +38 -0
  103. package/package.json +123 -4
  104. package/src/vendor/stagehand-facade/UPSTREAM.json +24 -0
@@ -0,0 +1,348 @@
1
+ import { z } from "zod/v4";
2
+ export declare const RUN_TOOL_DESCRIPTION = "Browse and automate websites in the persistent Stagehand browser. Navigate with JavaScript such as await page.goto(\"https://example.com\"); there is no separate navigate or start tool. Execute either a JavaScript workflow against the Stagehand Playwright facade or a batch of actions using IDs from the latest snapshot. Provide exactly one of code or actions. Each action must use \"op\" (never \"kind\") and \"id\" (never \"ref\"). Copy the bracketed snapshot ID as a string. Examples: {\"actions\":[{\"op\":\"click\",\"id\":\"1-42\"}]}, {\"actions\":[{\"op\":\"fill\",\"id\":\"2-14\",\"value\":\"Miami\"}]}, {\"actions\":[{\"op\":\"select\",\"id\":\"3-9\",\"values\":\"Lowest price\"}]}.";
3
+ export declare const SNAPSHOT_TOOL_DESCRIPTION = "Capture the active page's Stagehand accessibility tree and hydrate its displayed IDs for subsequent run actions. Every call replaces the active page's ID map.";
4
+ export declare const SCREENSHOT_TOOL_DESCRIPTION = "Capture a screenshot of the active page. For size-constrained MCP clients, prefer a viewport JPEG: {\"type\":\"jpeg\",\"quality\":40,\"fullPage\":false}.";
5
+ export declare const RUN_INPUT_SCHEMA: {
6
+ readonly type: "object";
7
+ readonly properties: {
8
+ readonly code: {
9
+ readonly type: "string";
10
+ readonly minLength: 1;
11
+ };
12
+ readonly actions: {
13
+ readonly type: "array";
14
+ readonly description: "Snapshot actions with the exact fields \"op\" and \"id\". Do not use \"kind\" or \"ref\".";
15
+ readonly items: {
16
+ readonly oneOf: readonly [{
17
+ type: string;
18
+ properties: {
19
+ op: {
20
+ const: string;
21
+ description: string;
22
+ };
23
+ id: {
24
+ type: string;
25
+ description: string;
26
+ };
27
+ };
28
+ required: string[];
29
+ additionalProperties: boolean;
30
+ }, {
31
+ type: string;
32
+ properties: {
33
+ op: {
34
+ const: string;
35
+ description: string;
36
+ };
37
+ id: {
38
+ type: string;
39
+ description: string;
40
+ };
41
+ };
42
+ required: string[];
43
+ additionalProperties: boolean;
44
+ }, {
45
+ type: string;
46
+ properties: {
47
+ op: {
48
+ const: string;
49
+ description: string;
50
+ };
51
+ id: {
52
+ type: string;
53
+ description: string;
54
+ };
55
+ };
56
+ required: string[];
57
+ additionalProperties: boolean;
58
+ }, {
59
+ type: string;
60
+ properties: {
61
+ op: {
62
+ const: string;
63
+ description: string;
64
+ };
65
+ id: {
66
+ type: string;
67
+ description: string;
68
+ };
69
+ };
70
+ required: string[];
71
+ additionalProperties: boolean;
72
+ }, {
73
+ type: string;
74
+ properties: {
75
+ op: {
76
+ const: string;
77
+ description: string;
78
+ };
79
+ id: {
80
+ type: string;
81
+ description: string;
82
+ };
83
+ };
84
+ required: string[];
85
+ additionalProperties: boolean;
86
+ }, {
87
+ type: string;
88
+ properties: {
89
+ op: {
90
+ const: string;
91
+ description: string;
92
+ };
93
+ id: {
94
+ type: string;
95
+ description: string;
96
+ };
97
+ };
98
+ required: string[];
99
+ additionalProperties: boolean;
100
+ }];
101
+ };
102
+ readonly minItems: 1;
103
+ };
104
+ };
105
+ readonly additionalProperties: false;
106
+ };
107
+ export declare const SNAPSHOT_INPUT_SCHEMA: {
108
+ readonly type: "object";
109
+ readonly properties: {
110
+ readonly includeIframes: {
111
+ readonly type: "boolean";
112
+ readonly default: true;
113
+ };
114
+ };
115
+ readonly additionalProperties: false;
116
+ };
117
+ export declare const SCREENSHOT_INPUT_SCHEMA: {
118
+ readonly type: "object";
119
+ readonly properties: {
120
+ readonly fullPage: {
121
+ readonly type: "boolean";
122
+ };
123
+ readonly type: {
124
+ readonly type: "string";
125
+ readonly enum: readonly ["png", "jpeg"];
126
+ };
127
+ readonly quality: {
128
+ readonly type: "number";
129
+ readonly minimum: 0;
130
+ readonly maximum: 100;
131
+ };
132
+ };
133
+ readonly additionalProperties: false;
134
+ };
135
+ export declare const FACADE_TOOLS: readonly [{
136
+ readonly name: "run";
137
+ readonly description: "Browse and automate websites in the persistent Stagehand browser. Navigate with JavaScript such as await page.goto(\"https://example.com\"); there is no separate navigate or start tool. Execute either a JavaScript workflow against the Stagehand Playwright facade or a batch of actions using IDs from the latest snapshot. Provide exactly one of code or actions. Each action must use \"op\" (never \"kind\") and \"id\" (never \"ref\"). Copy the bracketed snapshot ID as a string. Examples: {\"actions\":[{\"op\":\"click\",\"id\":\"1-42\"}]}, {\"actions\":[{\"op\":\"fill\",\"id\":\"2-14\",\"value\":\"Miami\"}]}, {\"actions\":[{\"op\":\"select\",\"id\":\"3-9\",\"values\":\"Lowest price\"}]}.";
138
+ readonly inputSchema: {
139
+ readonly type: "object";
140
+ readonly properties: {
141
+ readonly code: {
142
+ readonly type: "string";
143
+ readonly minLength: 1;
144
+ };
145
+ readonly actions: {
146
+ readonly type: "array";
147
+ readonly description: "Snapshot actions with the exact fields \"op\" and \"id\". Do not use \"kind\" or \"ref\".";
148
+ readonly items: {
149
+ readonly oneOf: readonly [{
150
+ type: string;
151
+ properties: {
152
+ op: {
153
+ const: string;
154
+ description: string;
155
+ };
156
+ id: {
157
+ type: string;
158
+ description: string;
159
+ };
160
+ };
161
+ required: string[];
162
+ additionalProperties: boolean;
163
+ }, {
164
+ type: string;
165
+ properties: {
166
+ op: {
167
+ const: string;
168
+ description: string;
169
+ };
170
+ id: {
171
+ type: string;
172
+ description: string;
173
+ };
174
+ };
175
+ required: string[];
176
+ additionalProperties: boolean;
177
+ }, {
178
+ type: string;
179
+ properties: {
180
+ op: {
181
+ const: string;
182
+ description: string;
183
+ };
184
+ id: {
185
+ type: string;
186
+ description: string;
187
+ };
188
+ };
189
+ required: string[];
190
+ additionalProperties: boolean;
191
+ }, {
192
+ type: string;
193
+ properties: {
194
+ op: {
195
+ const: string;
196
+ description: string;
197
+ };
198
+ id: {
199
+ type: string;
200
+ description: string;
201
+ };
202
+ };
203
+ required: string[];
204
+ additionalProperties: boolean;
205
+ }, {
206
+ type: string;
207
+ properties: {
208
+ op: {
209
+ const: string;
210
+ description: string;
211
+ };
212
+ id: {
213
+ type: string;
214
+ description: string;
215
+ };
216
+ };
217
+ required: string[];
218
+ additionalProperties: boolean;
219
+ }, {
220
+ type: string;
221
+ properties: {
222
+ op: {
223
+ const: string;
224
+ description: string;
225
+ };
226
+ id: {
227
+ type: string;
228
+ description: string;
229
+ };
230
+ };
231
+ required: string[];
232
+ additionalProperties: boolean;
233
+ }];
234
+ };
235
+ readonly minItems: 1;
236
+ };
237
+ };
238
+ readonly additionalProperties: false;
239
+ };
240
+ }, {
241
+ readonly name: "snapshot";
242
+ readonly description: "Capture the active page's Stagehand accessibility tree and hydrate its displayed IDs for subsequent run actions. Every call replaces the active page's ID map.";
243
+ readonly inputSchema: {
244
+ readonly type: "object";
245
+ readonly properties: {
246
+ readonly includeIframes: {
247
+ readonly type: "boolean";
248
+ readonly default: true;
249
+ };
250
+ };
251
+ readonly additionalProperties: false;
252
+ };
253
+ }, {
254
+ readonly name: "screenshot";
255
+ readonly description: "Capture a screenshot of the active page. For size-constrained MCP clients, prefer a viewport JPEG: {\"type\":\"jpeg\",\"quality\":40,\"fullPage\":false}.";
256
+ readonly inputSchema: {
257
+ readonly type: "object";
258
+ readonly properties: {
259
+ readonly fullPage: {
260
+ readonly type: "boolean";
261
+ };
262
+ readonly type: {
263
+ readonly type: "string";
264
+ readonly enum: readonly ["png", "jpeg"];
265
+ };
266
+ readonly quality: {
267
+ readonly type: "number";
268
+ readonly minimum: 0;
269
+ readonly maximum: 100;
270
+ };
271
+ };
272
+ readonly additionalProperties: false;
273
+ };
274
+ }];
275
+ /**
276
+ * Canonical agent system prompt for the facade tool surface. Host examples
277
+ * (Eve, Vercel AI SDK, deepagents) should use this text rather than authoring
278
+ * their own so agent guidance stays identical across frameworks.
279
+ */
280
+ export declare const FACADE_AGENT_INSTRUCTIONS = "You control one persistent browser through exactly three tools:\n- snapshot: inspect the active page and hydrate bracketed element IDs.\n- run: provide either snapshot actions or JavaScript using the Playwright-shaped page API.\n- screenshot: inspect the rendered page visually.\n\nUse snapshot actions for simple interactions and run code for multi-step workflows. Pass run exactly one of code or actions; every action uses \"op\" and \"id\", never \"kind\" or \"ref\". Snapshot IDs are valid only for the latest snapshot of the active page; snapshot again after navigation or stale IDs. Do not launch another browser.";
281
+ export declare const NO_HYDRATED_SNAPSHOT_ERROR = "No hydrated snapshot exists for the active page; call snapshot first.";
282
+ export declare const NAVIGATED_SNAPSHOT_ERROR = "The active page navigated after its snapshot; call snapshot again.";
283
+ export declare const STALE_SNAPSHOT_ID_ERROR = "Snapshot ID \"${id}\" is stale or not actionable; call snapshot again.";
284
+ export declare function staleSnapshotIdError(id: string): string;
285
+ export declare const RefActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
286
+ op: z.ZodLiteral<"click">;
287
+ id: z.ZodString;
288
+ }, z.core.$strict>, z.ZodObject<{
289
+ op: z.ZodLiteral<"hover">;
290
+ id: z.ZodString;
291
+ }, z.core.$strict>, z.ZodObject<{
292
+ op: z.ZodLiteral<"fill">;
293
+ id: z.ZodString;
294
+ value: z.ZodString;
295
+ }, z.core.$strict>, z.ZodObject<{
296
+ op: z.ZodLiteral<"type">;
297
+ id: z.ZodString;
298
+ text: z.ZodString;
299
+ delay: z.ZodOptional<z.ZodNumber>;
300
+ }, z.core.$strict>, z.ZodObject<{
301
+ op: z.ZodLiteral<"press">;
302
+ id: z.ZodString;
303
+ key: z.ZodString;
304
+ }, z.core.$strict>, z.ZodObject<{
305
+ op: z.ZodLiteral<"select">;
306
+ id: z.ZodString;
307
+ values: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
308
+ }, z.core.$strict>], "op">;
309
+ export declare const CodeModeRunInputSchema: z.ZodObject<{
310
+ code: z.ZodOptional<z.ZodString>;
311
+ actions: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
312
+ op: z.ZodLiteral<"click">;
313
+ id: z.ZodString;
314
+ }, z.core.$strict>, z.ZodObject<{
315
+ op: z.ZodLiteral<"hover">;
316
+ id: z.ZodString;
317
+ }, z.core.$strict>, z.ZodObject<{
318
+ op: z.ZodLiteral<"fill">;
319
+ id: z.ZodString;
320
+ value: z.ZodString;
321
+ }, z.core.$strict>, z.ZodObject<{
322
+ op: z.ZodLiteral<"type">;
323
+ id: z.ZodString;
324
+ text: z.ZodString;
325
+ delay: z.ZodOptional<z.ZodNumber>;
326
+ }, z.core.$strict>, z.ZodObject<{
327
+ op: z.ZodLiteral<"press">;
328
+ id: z.ZodString;
329
+ key: z.ZodString;
330
+ }, z.core.$strict>, z.ZodObject<{
331
+ op: z.ZodLiteral<"select">;
332
+ id: z.ZodString;
333
+ values: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
334
+ }, z.core.$strict>], "op">>>;
335
+ }, z.core.$strict>;
336
+ export declare const SnapshotInputSchema: z.ZodObject<{
337
+ includeIframes: z.ZodOptional<z.ZodBoolean>;
338
+ }, z.core.$strict>;
339
+ export declare const ScreenshotInputSchema: z.ZodObject<{
340
+ fullPage: z.ZodOptional<z.ZodBoolean>;
341
+ type: z.ZodOptional<z.ZodEnum<{
342
+ png: "png";
343
+ jpeg: "jpeg";
344
+ }>>;
345
+ quality: z.ZodOptional<z.ZodNumber>;
346
+ }, z.core.$strict>;
347
+ export type RefAction = z.infer<typeof RefActionSchema>;
348
+ export type CodeModeRunInput = z.infer<typeof CodeModeRunInputSchema>;
@@ -0,0 +1,155 @@
1
+ import { z } from "zod/v4";
2
+ /**
3
+ * This file intentionally carries the same contract twice:
4
+ *
5
+ * - The JSON-schema literals below are the WIRE contract — the exact bytes
6
+ * advertised to MCP clients via tools/list. They are hand-written because
7
+ * they cannot be generated from the zod schemas: the `const`-typed `op`
8
+ * discriminators and the per-property guidance descriptions do not survive
9
+ * zod-to-JSON-schema conversion, and `.refine()` emits nothing at all.
10
+ * Their wording is pinned string-exact to the reference contract (models
11
+ * are prompted against these descriptions) — see
12
+ * tests/facade-contract.test.ts. One deliberate deviation is documented on
13
+ * RUN_INPUT_SCHEMA below.
14
+ *
15
+ * - The zod schemas at the bottom are the RUNTIME validators: they parse
16
+ * tools/call arguments into typed values and enforce what the wire schema
17
+ * states (e.g. the code/actions exclusivity via `.refine`).
18
+ *
19
+ * If you change one half, change the other; the contract test exists to
20
+ * catch drift between them.
21
+ */
22
+ const actionSchema = (op, extra = {}) => ({
23
+ type: "object",
24
+ properties: {
25
+ op: {
26
+ const: op,
27
+ description: `Action operation. Use "op": "${op}"; never use a "kind" field.`,
28
+ },
29
+ id: {
30
+ type: "string",
31
+ description: 'Bracketed ID copied from the latest snapshot, as a string. Use "id"; never use "ref".',
32
+ },
33
+ ...extra,
34
+ },
35
+ required: ["op", "id", ...Object.keys(extra).filter((key) => key !== "delay")],
36
+ additionalProperties: false,
37
+ });
38
+ export const RUN_TOOL_DESCRIPTION = 'Browse and automate websites in the persistent Stagehand browser. Navigate with JavaScript such as await page.goto("https://example.com"); there is no separate navigate or start tool. Execute either a JavaScript workflow against the Stagehand Playwright facade or a batch of actions using IDs from the latest snapshot. Provide exactly one of code or actions. Each action must use "op" (never "kind") and "id" (never "ref"). Copy the bracketed snapshot ID as a string. Examples: {"actions":[{"op":"click","id":"1-42"}]}, {"actions":[{"op":"fill","id":"2-14","value":"Miami"}]}, {"actions":[{"op":"select","id":"3-9","values":"Lowest price"}]}.';
39
+ export const SNAPSHOT_TOOL_DESCRIPTION = "Capture the active page's Stagehand accessibility tree and hydrate its displayed IDs for subsequent run actions. Every call replaces the active page's ID map.";
40
+ export const SCREENSHOT_TOOL_DESCRIPTION = 'Capture a screenshot of the active page. For size-constrained MCP clients, prefer a viewport JPEG: {"type":"jpeg","quality":40,"fullPage":false}.';
41
+ export const RUN_INPUT_SCHEMA = {
42
+ type: "object",
43
+ properties: {
44
+ code: { type: "string", minLength: 1 },
45
+ actions: {
46
+ type: "array",
47
+ description: 'Snapshot actions with the exact fields "op" and "id". Do not use "kind" or "ref".',
48
+ items: {
49
+ oneOf: [
50
+ actionSchema("click"),
51
+ actionSchema("hover"),
52
+ actionSchema("fill", { value: { type: "string" } }),
53
+ actionSchema("type", {
54
+ text: { type: "string" },
55
+ delay: { type: "number", minimum: 0 },
56
+ }),
57
+ actionSchema("press", { key: { type: "string" } }),
58
+ actionSchema("select", {
59
+ values: {
60
+ oneOf: [
61
+ { type: "string" },
62
+ { type: "array", items: { type: "string" }, minItems: 1 },
63
+ ],
64
+ },
65
+ }),
66
+ ],
67
+ },
68
+ minItems: 1,
69
+ },
70
+ },
71
+ // Deliberate deviation from the reference contract: no top-level
72
+ // `oneOf: [{required:["code"]},{required:["actions"]}]` here. AI-SDK-based
73
+ // MCP clients (Eve, Vercel AI SDK) reject tool input schemas with a
74
+ // top-level oneOf, failing every `run` call client-side before it reaches
75
+ // the server. The code/actions exclusivity is stated in the description
76
+ // and enforced at runtime by CodeModeRunInputSchema's `.refine`.
77
+ additionalProperties: false,
78
+ };
79
+ export const SNAPSHOT_INPUT_SCHEMA = {
80
+ type: "object",
81
+ properties: { includeIframes: { type: "boolean", default: true } },
82
+ additionalProperties: false,
83
+ };
84
+ export const SCREENSHOT_INPUT_SCHEMA = {
85
+ type: "object",
86
+ properties: {
87
+ fullPage: { type: "boolean" },
88
+ type: { type: "string", enum: ["png", "jpeg"] },
89
+ quality: { type: "number", minimum: 0, maximum: 100 },
90
+ },
91
+ additionalProperties: false,
92
+ };
93
+ export const FACADE_TOOLS = [
94
+ { name: "run", description: RUN_TOOL_DESCRIPTION, inputSchema: RUN_INPUT_SCHEMA },
95
+ {
96
+ name: "snapshot",
97
+ description: SNAPSHOT_TOOL_DESCRIPTION,
98
+ inputSchema: SNAPSHOT_INPUT_SCHEMA,
99
+ },
100
+ {
101
+ name: "screenshot",
102
+ description: SCREENSHOT_TOOL_DESCRIPTION,
103
+ inputSchema: SCREENSHOT_INPUT_SCHEMA,
104
+ },
105
+ ];
106
+ /**
107
+ * Canonical agent system prompt for the facade tool surface. Host examples
108
+ * (Eve, Vercel AI SDK, deepagents) should use this text rather than authoring
109
+ * their own so agent guidance stays identical across frameworks.
110
+ */
111
+ export const FACADE_AGENT_INSTRUCTIONS = `You control one persistent browser through exactly three tools:
112
+ - snapshot: inspect the active page and hydrate bracketed element IDs.
113
+ - run: provide either snapshot actions or JavaScript using the Playwright-shaped page API.
114
+ - screenshot: inspect the rendered page visually.
115
+
116
+ Use snapshot actions for simple interactions and run code for multi-step workflows. Pass run exactly one of code or actions; every action uses "op" and "id", never "kind" or "ref". Snapshot IDs are valid only for the latest snapshot of the active page; snapshot again after navigation or stale IDs. Do not launch another browser.`;
117
+ export const NO_HYDRATED_SNAPSHOT_ERROR = "No hydrated snapshot exists for the active page; call snapshot first.";
118
+ export const NAVIGATED_SNAPSHOT_ERROR = "The active page navigated after its snapshot; call snapshot again.";
119
+ export const STALE_SNAPSHOT_ID_ERROR = 'Snapshot ID "${id}" is stale or not actionable; call snapshot again.';
120
+ export function staleSnapshotIdError(id) {
121
+ return STALE_SNAPSHOT_ID_ERROR.replace("${id}", id);
122
+ }
123
+ export const RefActionSchema = z.discriminatedUnion("op", [
124
+ z.strictObject({ op: z.literal("click"), id: z.string().min(1) }),
125
+ z.strictObject({ op: z.literal("hover"), id: z.string().min(1) }),
126
+ z.strictObject({ op: z.literal("fill"), id: z.string().min(1), value: z.string() }),
127
+ z.strictObject({
128
+ op: z.literal("type"),
129
+ id: z.string().min(1),
130
+ text: z.string(),
131
+ delay: z.number().nonnegative().optional(),
132
+ }),
133
+ z.strictObject({ op: z.literal("press"), id: z.string().min(1), key: z.string().min(1) }),
134
+ z.strictObject({
135
+ op: z.literal("select"),
136
+ id: z.string().min(1),
137
+ values: z.union([z.string(), z.array(z.string()).min(1)]),
138
+ }),
139
+ ]);
140
+ export const CodeModeRunInputSchema = z
141
+ .strictObject({
142
+ code: z.string().min(1).optional(),
143
+ actions: z.array(RefActionSchema).min(1).optional(),
144
+ })
145
+ .refine((input) => (input.code === undefined) !== (input.actions === undefined), {
146
+ message: "run requires exactly one of code or actions",
147
+ });
148
+ export const SnapshotInputSchema = z.strictObject({
149
+ includeIframes: z.boolean().optional(),
150
+ });
151
+ export const ScreenshotInputSchema = z.strictObject({
152
+ fullPage: z.boolean().optional(),
153
+ type: z.enum(["png", "jpeg"]).optional(),
154
+ quality: z.number().min(0).max(100).optional(),
155
+ });
@@ -0,0 +1,90 @@
1
+ type RawLocator = {
2
+ click(options?: {
3
+ button?: "left" | "right" | "middle";
4
+ clickCount?: number;
5
+ }): Promise<void>;
6
+ hover(): Promise<void>;
7
+ fill(value: string): Promise<void>;
8
+ type(text: string, options?: {
9
+ delay?: number;
10
+ }): Promise<void>;
11
+ selectOption(values: string | string[]): Promise<string[]>;
12
+ setInputFiles(files: unknown): Promise<void>;
13
+ };
14
+ type RawPage = {
15
+ readonly pageId?: string;
16
+ goto(url: string, options?: Record<string, unknown>): Promise<unknown>;
17
+ reload(options?: Record<string, unknown>): Promise<unknown>;
18
+ goBack(options?: Record<string, unknown>): Promise<unknown>;
19
+ goForward(options?: Record<string, unknown>): Promise<unknown>;
20
+ evaluate<Result = unknown, Arg = unknown>(expression: string | ((arg: Arg) => Result | Promise<Result>), arg?: Arg): Promise<Result>;
21
+ screenshot(options?: Record<string, unknown>): Promise<Uint8Array>;
22
+ setViewportSize(width: number, height: number): Promise<void>;
23
+ waitForLoadState(state: string, timeout?: number): Promise<void>;
24
+ waitForTimeout(ms: number): Promise<void>;
25
+ waitForSelector(selector: string, options?: Record<string, unknown>): Promise<boolean>;
26
+ url(): Promise<string>;
27
+ title(): Promise<string>;
28
+ close(): Promise<void>;
29
+ locator(selector: string): RawLocator;
30
+ type(text: string, options?: {
31
+ delay?: number;
32
+ }): Promise<void>;
33
+ keyPress(key: string, options?: {
34
+ delay?: number;
35
+ }): Promise<void>;
36
+ click(x: number, y: number, options?: Record<string, unknown>): Promise<void>;
37
+ hover(x: number, y: number): Promise<void>;
38
+ scroll(x: number, y: number, deltaX: number, deltaY: number): Promise<void>;
39
+ setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
40
+ addInitScript(script: string | ((arg: unknown) => unknown), arg?: unknown): Promise<void>;
41
+ snapshot(options?: Record<string, unknown>): Promise<unknown>;
42
+ on(event: "console" | "download" | "request" | "response" | "requestfailed", listener: (event: any) => unknown): Promise<{
43
+ unsubscribe(): Promise<void>;
44
+ }>;
45
+ onCDP(method: string, listener: (event: any) => unknown): Promise<{
46
+ unsubscribe(): Promise<void>;
47
+ }>;
48
+ sendCDP<Result = unknown>(method: string, params?: Record<string, unknown>): Promise<Result>;
49
+ };
50
+ type RawContext = {
51
+ pages(): Promise<RawPage[]>;
52
+ newPage(url?: string): Promise<RawPage>;
53
+ setActivePage(page: RawPage): Promise<void>;
54
+ cookies(urls?: string | string[]): Promise<unknown[]>;
55
+ addCookies(cookies: unknown[]): Promise<void>;
56
+ clearCookies(options?: Record<string, unknown>): Promise<void>;
57
+ setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
58
+ addInitScript(script: string | ((arg: unknown) => unknown), arg?: unknown): Promise<void>;
59
+ request?: {
60
+ fetch(url: string, options?: Record<string, unknown>): Promise<unknown>;
61
+ get(url: string, options?: Record<string, unknown>): Promise<unknown>;
62
+ post(url: string, options?: Record<string, unknown>): Promise<unknown>;
63
+ };
64
+ };
65
+ type BatchStagehandRuntime = {
66
+ page: RawPage;
67
+ context: RawContext;
68
+ };
69
+ export type PlaywrightCompatTelemetry = {
70
+ calls: Record<string, number>;
71
+ misses: Record<string, number>;
72
+ };
73
+ export type PlaywrightCompatRuntime = {
74
+ page: unknown;
75
+ context: unknown;
76
+ browser: unknown;
77
+ telemetry: () => PlaywrightCompatTelemetry;
78
+ artifacts: () => Array<{
79
+ path: string;
80
+ base64: string;
81
+ }>;
82
+ closeRequested: () => boolean;
83
+ };
84
+ /**
85
+ * Builds a Playwright-shaped facade entirely inside a Stagehand callback batch.
86
+ * Keep this function self-contained: its source is serialized into the
87
+ * extension service worker with Function#toString.
88
+ */
89
+ export declare function createPlaywrightCompatRuntime(stagehand: BatchStagehandRuntime): Promise<PlaywrightCompatRuntime>;
90
+ export {};