@parcha/pi-browser 0.1.0-beta.17 → 0.1.0-beta.19

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 (87) hide show
  1. package/CHANGELOG.md +5 -0
  2. package/README.md +177 -39
  3. package/dist/coding-agent-local.js +2 -1
  4. package/dist/coding-agent.d.ts +42 -2
  5. package/dist/coding-agent.js +159 -21
  6. package/dist/core/clip.d.ts +31 -0
  7. package/dist/core/clip.js +49 -0
  8. package/dist/core/contract.d.ts +4 -1
  9. package/dist/core/contract.js +40 -7
  10. package/dist/core/custody.d.ts +79 -5
  11. package/dist/core/custody.js +66 -5
  12. package/dist/core/decisions.d.ts +4 -0
  13. package/dist/core/dial.d.ts +7 -0
  14. package/dist/core/dial.js +41 -0
  15. package/dist/core/downloads.d.ts +1 -0
  16. package/dist/core/downloads.js +17 -5
  17. package/dist/core/driving-guard.d.ts +13 -0
  18. package/dist/core/driving-guard.js +61 -0
  19. package/dist/core/driving.d.ts +61 -0
  20. package/dist/core/driving.js +156 -0
  21. package/dist/core/effects.js +33 -13
  22. package/dist/core/evidence.d.ts +3 -1
  23. package/dist/core/failures.d.ts +5 -1
  24. package/dist/core/failures.js +20 -4
  25. package/dist/core/files.d.ts +8 -0
  26. package/dist/core/files.js +74 -0
  27. package/dist/core/find.d.ts +3 -1
  28. package/dist/core/find.js +2 -1
  29. package/dist/core/guard.d.ts +9 -1
  30. package/dist/core/guard.js +7 -2
  31. package/dist/core/host.d.ts +49 -1
  32. package/dist/core/images.d.ts +10 -2
  33. package/dist/core/images.js +4 -4
  34. package/dist/core/lease.d.ts +1 -1
  35. package/dist/core/lease.js +2 -1
  36. package/dist/core/session-control.d.ts +2 -0
  37. package/dist/core/session-control.js +5 -0
  38. package/dist/core/tools.d.ts +70 -4
  39. package/dist/core/tools.js +288 -45
  40. package/dist/core/unanswered.d.ts +3 -0
  41. package/dist/core/unanswered.js +17 -0
  42. package/dist/core/usage.d.ts +2 -0
  43. package/dist/core/usage.js +6 -0
  44. package/dist/core/web.d.ts +1 -1
  45. package/dist/core/web.js +9 -7
  46. package/dist/driver/extension-worker.d.ts +4 -2
  47. package/dist/driver/extension-worker.js +16 -10
  48. package/dist/driver/page-driver.d.ts +8 -0
  49. package/dist/driver/page-driver.js +128 -0
  50. package/dist/driver/stagehand.d.ts +3 -1
  51. package/dist/driver/stagehand.js +40 -66
  52. package/dist/durable.d.ts +16 -4
  53. package/dist/durable.js +415 -82
  54. package/dist/index.d.ts +2 -0
  55. package/dist/index.js +2 -0
  56. package/dist/live-view/index.d.ts +4 -0
  57. package/dist/live-view/index.js +4 -0
  58. package/dist/live-view/protocol.d.ts +152 -0
  59. package/dist/live-view/protocol.js +84 -0
  60. package/dist/live-view/provider.d.ts +6 -0
  61. package/dist/live-view/provider.js +23 -0
  62. package/dist/live-view/server.d.ts +50 -0
  63. package/dist/live-view/server.js +342 -0
  64. package/dist/live-view/stream.d.ts +7 -0
  65. package/dist/live-view/stream.js +388 -0
  66. package/dist/live-view/token.d.ts +6 -0
  67. package/dist/live-view/token.js +13 -0
  68. package/dist/live-view/viewer.d.ts +6 -0
  69. package/dist/live-view/viewer.js +350 -0
  70. package/dist/live-view/ws.d.ts +19 -0
  71. package/dist/live-view/ws.js +176 -0
  72. package/dist/providers/assigned.d.ts +18 -0
  73. package/dist/providers/assigned.js +76 -0
  74. package/dist/providers/cdp-call.js +12 -2
  75. package/dist/providers/cdp.js +37 -11
  76. package/dist/recorder/follow.d.ts +10 -0
  77. package/dist/recorder/follow.js +27 -2
  78. package/dist/recorder/frames.d.ts +7 -0
  79. package/dist/recorder/frames.js +73 -5
  80. package/dist/store.d.ts +22 -3
  81. package/dist/store.js +75 -4
  82. package/dist/testing/backend.d.ts +26 -0
  83. package/dist/testing/backend.js +21 -3
  84. package/dist/testing/driver.d.ts +18 -1
  85. package/dist/testing/driver.js +4 -0
  86. package/dist/web.js +2 -2
  87. package/package.json +10 -2
@@ -0,0 +1,156 @@
1
+ import { BrowserFailureError } from "./custody.js";
2
+ import { browserFailure } from "./failures.js";
3
+ /** The typed marker a refused model call opens its message with, as #1000's busy refusals open theirs with `browser_busy (fill)`. */
4
+ export const PERSON_DRIVING = "person_driving";
5
+ /** The failure a model browser call gets while a person drives: `refused`, retryable (the person's turn ends), nothing was done. */
6
+ export const personDrivingFailure = () => browserFailure("refused", `${PERSON_DRIVING}: a person is driving this browser through the live view, and the agent does not act while they do. Wait a moment and try the call again.`, { retryable: true });
7
+ const NODE_TIMERS = { set: (run, ms) => { const handle = setTimeout(run, ms); handle.unref?.(); return handle; }, clear: (handle) => clearTimeout(handle) };
8
+ /** One browser's mutex. The state is `{ model, person }` (the model's calls in flight, and whether a person is driving), the shape of #1000's per-browser busy
9
+ * record (`{ code, fill }`): folding the two in means adding `person` to that record and asking `model()` and `input()` beside its fill/code checks. */
10
+ class Gate {
11
+ timers;
12
+ idleMs;
13
+ forget;
14
+ model_ = 0;
15
+ person = false;
16
+ idle;
17
+ viewing_ = false;
18
+ /** A person has driven and the model has not been told yet; kept (and the gate with it) until a call has been told. */
19
+ drove_ = false;
20
+ listeners = new Set();
21
+ constructor(timers, idleMs, forget) {
22
+ this.timers = timers;
23
+ this.idleMs = idleMs;
24
+ this.forget = forget;
25
+ }
26
+ state() { return this.model_ > 0 ? "agent" : this.person ? "person" : "idle"; }
27
+ /** Viewer input: discarded (never queued) while the model acts, so a keystroke is not replayed into a page the model has since moved. */
28
+ input() {
29
+ if (this.model_ > 0)
30
+ return "agent_acting";
31
+ const before = this.state();
32
+ this.person = true;
33
+ this.drove_ = true;
34
+ if (this.idle !== undefined)
35
+ this.timers.clear(this.idle);
36
+ this.idle = this.timers.set(() => this.stopDriving(), this.idleMs);
37
+ if (before !== "person")
38
+ this.announce("person");
39
+ return "driving";
40
+ }
41
+ model() {
42
+ if (this.person)
43
+ return PERSON_DRIVING;
44
+ const drove = this.drove_;
45
+ const before = this.state();
46
+ this.model_ += 1;
47
+ if (before !== "agent")
48
+ this.announce("agent");
49
+ let released = false;
50
+ return { drove, release: () => { if (released)
51
+ return; released = true; this.model_ -= 1; if (this.model_ === 0) {
52
+ this.announce(this.state());
53
+ this.settle();
54
+ } } };
55
+ }
56
+ told() { this.drove_ = false; this.settle(); }
57
+ viewing() { return this.viewing_; }
58
+ setViewing(on) { this.viewing_ = on; if (!on)
59
+ this.settle(); }
60
+ onChange(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); this.settle(); }; }
61
+ end() {
62
+ if (this.idle !== undefined)
63
+ this.timers.clear(this.idle);
64
+ this.idle = undefined;
65
+ this.person = false;
66
+ this.viewing_ = false;
67
+ this.drove_ = false;
68
+ this.model_ = 0;
69
+ this.listeners.clear();
70
+ this.forget(this);
71
+ }
72
+ stopDriving() {
73
+ this.idle = undefined;
74
+ if (!this.person)
75
+ return;
76
+ this.person = false;
77
+ this.announce(this.state());
78
+ this.settle();
79
+ }
80
+ /** A gate that no call, person, viewer or listener holds is dropped from the registry, so a long-running host does not keep one per session it ever ran: whoever asks again gets an
81
+ * identical one. A gate in use stays the same object. */
82
+ settle() {
83
+ if (this.model_ === 0 && !this.person && !this.drove_ && !this.viewing_ && this.listeners.size === 0)
84
+ this.forget(this);
85
+ }
86
+ announce(state) {
87
+ for (const listener of [...this.listeners]) {
88
+ try {
89
+ listener(state);
90
+ }
91
+ catch { /* a viewer that throws cannot stop the model */ }
92
+ }
93
+ }
94
+ }
95
+ /** The person/model mutex for every browser: `gates(tag)` is the tag's gate (the same object each time while anything holds it: a call, a person, a viewer or a listener, and until its `end()`). */
96
+ export function createDrivingGates(options = {}) {
97
+ const idleMs = options.idleMs ?? 3000;
98
+ const timers = options.timers ?? NODE_TIMERS;
99
+ const byTag = new Map();
100
+ return (tag) => {
101
+ let gate = byTag.get(tag);
102
+ if (!gate) {
103
+ const made = new Gate(timers, idleMs, (ended) => { if (byTag.get(tag) === ended)
104
+ byTag.delete(tag); });
105
+ byTag.set(tag, made);
106
+ gate = made;
107
+ }
108
+ return gate;
109
+ };
110
+ }
111
+ /** Runs `work` as one model browser call on `gate`: refused, typed, while a person drives; released whatever the work does. */
112
+ export async function withModelCall(gate, work) {
113
+ const call = gate.model();
114
+ if (call === PERSON_DRIVING)
115
+ throw new BrowserFailureError(personDrivingFailure());
116
+ try {
117
+ return await work();
118
+ }
119
+ finally {
120
+ call.release();
121
+ }
122
+ }
123
+ /** The process's own registry: the model side (where the toolset is registered) and the live view's default (`options.gates ?? drivingGates`) share the SAME gate per
124
+ * session tag without any plumbing. A test that wants an isolated one calls `createDrivingGates()`. */
125
+ export const drivingGates = createDrivingGates();
126
+ /** Why custody keeps a session it would otherwise release on its own (an idle window, a connection it cannot get back): a
127
+ * person drives it, or watches it, through the live view. Null when no person is on it. */
128
+ export const keptFor = (gate) => gate.state() === "person" ? "person_driving" : gate.viewing() ? "viewing" : null;
129
+ /** The session's gate when a person drives or watches it through the live view, else null. The registry makes a gate on its
130
+ * first lookup, so a gate nobody holds is let go again here (an unsubscribe settles it: a gate in use, a call, a person, a
131
+ * viewer or a listener, stays), and custody's own check never leaves one behind. */
132
+ export function personOn(gates, tag) {
133
+ const gate = gates(tag);
134
+ if (keptFor(gate) !== null)
135
+ return gate;
136
+ gate.onChange(() => { })();
137
+ return null;
138
+ }
139
+ /** A session custody kept for a person is released one idle window after they leave: the gate is polled (setViewing and end
140
+ * announce nothing), and the moment nobody is on it `rearm` starts the idle window again. Stops once `alive` says the session
141
+ * is gone; the returned function stops it at once (a release, a close). */
142
+ export function rearmWhenLeft(gate, alive, rearm, idleMs) {
143
+ const every = Math.max(25, Math.min(1000, Math.round(idleMs / 4)));
144
+ const poll = setInterval(() => {
145
+ if (!alive()) {
146
+ clearInterval(poll);
147
+ return;
148
+ }
149
+ if (keptFor(gate) === null) {
150
+ clearInterval(poll);
151
+ rearm();
152
+ }
153
+ }, every);
154
+ poll.unref?.();
155
+ return () => clearInterval(poll);
156
+ }
@@ -1,3 +1,6 @@
1
+ // Nothing about a request leaves this module but its method, origin, path, query-key and form-field names: never a
2
+ // body, a header or a value.
3
+ import { openDial } from "./dial.js";
1
4
  const SAFE = new Set(["GET", "HEAD", "OPTIONS"]);
2
5
  const SESSIONS = new Set(["page", "iframe", "worker", "service_worker", "shared_worker"]);
3
6
  const HARMLESS = { irreversibleBelow: 0.5, atLeast: 0.7 };
@@ -72,22 +75,32 @@ export class EffectObserver {
72
75
  get holding() { return this.decide !== null && !this.closed; }
73
76
  /** `decide` null observes without holding; a decision not made within `decideMs` is a refusal. */
74
77
  static async open(target, decide, decideMs = 60_000) {
75
- const init = target.dial?.headers ? { headers: target.dial.headers } : undefined;
76
- const ws = new WebSocket(target.dial?.url ?? target.sdkCdpUrl, init);
78
+ const ws = openDial(target);
77
79
  await new Promise((resolve, reject) => { ws.onopen = () => resolve(); ws.onerror = () => reject(failed("attach_refused", "the effect observer could not reach the browser")); });
78
80
  const observer = new EffectObserver(ws, decide, decideMs);
79
- ws.onmessage = (event) => observer.receive(JSON.parse(String(event.data)));
81
+ // A throw in a socket listener is an uncaught exception that ends the process: a frame the observer cannot read is dropped.
82
+ ws.onmessage = (event) => { try {
83
+ observer.receive(JSON.parse(String(event.data)));
84
+ }
85
+ catch { } };
80
86
  ws.onclose = () => { observer.closed = true; for (const p of observer.pending.values())
81
87
  p.reject(failed("cdp_closed", "the effect observer's socket closed")); observer.pending.clear(); };
82
- // New targets start paused, so nothing they send escapes before their Network and Fetch domains are on.
83
- await observer.send("Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: true, flatten: true });
84
- await new Promise((r) => setTimeout(r, 150));
85
- const attached = new Set([...observer.sessions.values()].map((s) => s.targetId));
86
- for (const t of (await observer.send("Target.getTargets")).targetInfos) {
87
- if (t.type === "page" && !attached.has(t.targetId))
88
- await observer.send("Target.attachToTarget", { targetId: t.targetId, flatten: true });
88
+ try {
89
+ // New targets start paused, so nothing they send escapes before their Network and Fetch domains are on.
90
+ await observer.send("Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: true, flatten: true });
91
+ await new Promise((r) => setTimeout(r, 150));
92
+ const attached = new Set([...observer.sessions.values()].map((s) => s.targetId));
93
+ for (const t of (await observer.send("Target.getTargets")).targetInfos) {
94
+ if (t.type === "page" && !attached.has(t.targetId))
95
+ await observer.send("Target.attachToTarget", { targetId: t.targetId, flatten: true });
96
+ }
97
+ return observer;
98
+ }
99
+ catch (error) {
100
+ // An observer that failed its setup is never returned, so nothing else would close its socket.
101
+ observer.close();
102
+ throw error;
89
103
  }
90
- return observer;
91
104
  }
92
105
  /** Journal every effect from now on (a held one before it is sent); returns the stop. Lifts the previous call's cut. */
93
106
  record(listener) {
@@ -143,7 +156,7 @@ export class EffectObserver {
143
156
  return;
144
157
  }
145
158
  if (m.method === "Target.attachedToTarget")
146
- void this.setup(m.params);
159
+ this.setup(m.params).catch(() => { });
147
160
  else if (m.method === "Target.detachedFromTarget") {
148
161
  this.sessions.delete(m.params.sessionId);
149
162
  for (const [id, entry] of [...this.announced])
@@ -239,7 +252,14 @@ export class EffectObserver {
239
252
  const { method, url, postData, headers } = p.request;
240
253
  if (SAFE.has(method) || !this.decide)
241
254
  return this.send("Fetch.continueRequest", { requestId: p.requestId }, sessionId);
242
- const request = describeRequest(method, url, postData, headers);
255
+ let request;
256
+ // A request the observer cannot describe cannot be judged or journaled, and a held request nobody answers waits forever: refuse it.
257
+ try {
258
+ request = describeRequest(method, url, postData, headers);
259
+ }
260
+ catch {
261
+ return this.send("Fetch.failRequest", { requestId: p.requestId, errorReason: "BlockedByClient" }, sessionId);
262
+ }
243
263
  const cutoff = this.cutoff;
244
264
  // Journaled `pending` and committed before deciding: a process that dies mid-decision loses the hold and the
245
265
  // request goes, so the journal must already name it. A request whose row could not be saved never leaves.
@@ -23,10 +23,12 @@ export type EvidenceRecord = {
23
23
  ext?: string;
24
24
  };
25
25
  export type EvidenceSink = {
26
- /** `path` is what the model cites; `bodyLine` is the 1-indexed line where the body starts. Null: nothing was filed. */
26
+ /** `path` is what the model cites; `bodyLine` is the 1-indexed line where the body starts; `bodyPath` is where a binary body (a capture) was
27
+ * written, relative to the same root as `path`. Null: nothing was filed. */
27
28
  file(label: string, record: EvidenceRecord): Promise<{
28
29
  path: string;
29
30
  bodyLine?: number;
31
+ bodyPath?: string;
30
32
  } | null>;
31
33
  /** The model's whole result for a filed body; absent, a head under DEFAULT_INLINE_CHARS and the file's path. */
32
34
  inline?(body: string, at: {
@@ -1,4 +1,4 @@
1
- export declare const FAILURE_CODES: readonly ["browser_unavailable", "auth", "timeout", "aborted", "refused", "stale_snapshot", "session_ended", "session_replaced", "effect_unknown", "code_error", "command_failed", "not_content", "blocked", "rate_limited"];
1
+ export declare const FAILURE_CODES: readonly ["browser_unavailable", "auth", "timeout", "aborted", "refused", "stale_snapshot", "session_ended", "session_replaced", "effect_unknown", "code_error", "command_failed", "not_content", "blocked", "rate_limited", "waiting_for_human"];
2
2
  export type FailureCode = (typeof FAILURE_CODES)[number];
3
3
  export type BrowserFailure = {
4
4
  ok: false;
@@ -15,10 +15,14 @@ export declare const browserFailure: (code: FailureCode, message: string, option
15
15
  detail?: string;
16
16
  }) => BrowserFailure;
17
17
  /** `timedOut`: the call ran to the driver's batch deadline, which Stagehand reports as a plain Error. */
18
+ /** `action`: what an effectful call ran, named when it threw; "Your browser code" when unset. */
19
+ /** `redact` removes the run's registered values from the error text; it runs over the whole text before any cut below, so no fragment of a value survives a cut point. */
18
20
  export type FailureFacts = {
19
21
  sessionEnded?: boolean;
20
22
  aborted?: boolean;
21
23
  timedOut?: boolean;
24
+ action?: string;
25
+ redact?: (text: string) => string;
22
26
  };
23
27
  export declare const NO_HYDRATED_SNAPSHOT_ERROR = "No hydrated snapshot exists for the active page; call snapshot first.";
24
28
  export declare const NAVIGATED_SNAPSHOT_ERROR = "The active page navigated after its snapshot; call snapshot again.";
@@ -1,8 +1,9 @@
1
1
  // A code comes from typed facts only (status, class names, cause-chain codes, refusal constants by identity), never
2
2
  // from an error's message.
3
+ import { UNANSWERED_CALL } from "./unanswered.js";
3
4
  export const FAILURE_CODES = Object.freeze([
4
5
  "browser_unavailable", "auth", "timeout", "aborted", "refused", "stale_snapshot", "session_ended",
5
- "session_replaced", "effect_unknown", "code_error", "command_failed", "not_content", "blocked", "rate_limited",
6
+ "session_replaced", "effect_unknown", "code_error", "command_failed", "not_content", "blocked", "rate_limited", "waiting_for_human",
6
7
  ]);
7
8
  export const browserFailure = (code, message, options = {}) => ({ ok: false, code, retryable: options.retryable ?? false, effect: options.effect ?? "none", message, ...(options.detail === undefined ? {} : { detail: options.detail }) });
8
9
  export const NO_HYDRATED_SNAPSHOT_ERROR = "No hydrated snapshot exists for the active page; call snapshot first.";
@@ -20,7 +21,8 @@ const lostLoopback = (error) => {
20
21
  return !!cause && typeof cause === "object" && cause.code === JSONRPC_INTERNAL_ERROR && cause.message === STAGEHAND_LOOPBACK_DISCONNECTED;
21
22
  };
22
23
  const UNREACHABLE_CAUSES = new Set(["ECONNREFUSED", "ENOTFOUND", "ECONNRESET", "EAI_AGAIN", "EPIPE", "UND_ERR_SOCKET", "UND_ERR_CONNECT_TIMEOUT"]);
23
- const UNREACHABLE_NAMES = new Set(["CDPConnectionClosedError"]);
24
+ // A host call the browser left unanswered past its deadline is a dropped connection too.
25
+ const UNREACHABLE_NAMES = new Set(["CDPConnectionClosedError", UNANSWERED_CALL]);
24
26
  /** A throw site's `transport` record, else class name, `code` and `status` down the cause chain; first found wins. */
25
27
  export function transportFactOf(error) {
26
28
  const out = {};
@@ -41,11 +43,25 @@ export function transportFactOf(error) {
41
43
  }
42
44
  return out;
43
45
  }
46
+ /** An error's text with its cause's: a JSON-RPC error object (Stagehand's extension answers with one) gives its own text
47
+ * and code, never "[object Object]". */
48
+ function withCause(own, cause) {
49
+ if (cause instanceof Error)
50
+ return [own, cause.message].filter(Boolean).join(": ");
51
+ if (!cause)
52
+ return own;
53
+ if (typeof cause !== "object")
54
+ return [own, String(cause)].filter(Boolean).join(": ");
55
+ const { code, message } = cause;
56
+ const text = typeof message === "string" && message && message !== own ? `: ${message}` : "";
57
+ const tag = typeof code === "number" || (typeof code === "string" && code) ? ` (code ${code})` : "";
58
+ return `${own}${text}${tag}`;
59
+ }
44
60
  export function classifyBrowserError(error, effectful, facts = {}) {
45
61
  // Stagehand wraps SDK failures with { cause }: the HTTP status and the real message live on the cause.
46
62
  const cause = error?.cause;
47
63
  const own = error instanceof Error ? error.message : String(error);
48
- const message = [own, cause instanceof Error ? cause.message : cause ? String(cause) : ""].filter(Boolean).join(": ");
64
+ const message = (facts.redact ?? ((text) => text))(withCause(own, cause));
49
65
  const fact = transportFactOf(error);
50
66
  const status = fact.status ?? Number(error?.statusCode ?? cause?.statusCode ?? NaN);
51
67
  const effect = effectful ? "possibly_effected" : "none";
@@ -64,5 +80,5 @@ export function classifyBrowserError(error, effectful, facts = {}) {
64
80
  return browserFailure("stale_snapshot", message, { retryable: true, detail });
65
81
  if ((fact.causeCode && UNREACHABLE_CAUSES.has(fact.causeCode)) || (fact.errorName && UNREACHABLE_NAMES.has(fact.errorName)) || lostLoopback(error))
66
82
  return browserFailure("browser_unavailable", "The browser could not be reached on this lane. The browser plane is unavailable for this run; use web_fetch or executor tools.", { effect, detail });
67
- return browserFailure(effectful ? "code_error" : "command_failed", effectful ? `Your browser code threw: ${message.slice(0, 600)}` : `The browser call failed: ${message.slice(0, 600)}`, { retryable: true, effect, detail });
83
+ return browserFailure(effectful ? "code_error" : "command_failed", effectful ? `${facts.action ?? "Your browser code"} threw: ${message.slice(0, 600)}` : `The browser call failed: ${message.slice(0, 600)}`, { retryable: true, effect, detail });
68
84
  }
@@ -0,0 +1,8 @@
1
+ import type { WorkspaceFiles } from "./host.js";
2
+ export declare const MAX_UPLOAD_BYTES: number;
3
+ /** Files under `root` only: a relative path with no `..`, inside `root` once symlinks resolve, at most `maxBytes`, and
4
+ * not one `refuse` names (a host's private files). */
5
+ export declare function workspaceFiles(root: string, { maxBytes, refuse }?: {
6
+ maxBytes?: number;
7
+ refuse?: (real: string) => string | null;
8
+ }): WorkspaceFiles;
@@ -0,0 +1,74 @@
1
+ import { constants } from "node:fs";
2
+ import { open, readlink, realpath, stat } from "node:fs/promises";
3
+ import path from "node:path";
4
+ export const MAX_UPLOAD_BYTES = 8 * 1024 * 1024;
5
+ const MIME = {
6
+ ".csv": "text/csv", ".doc": "application/msword", ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
7
+ ".gif": "image/gif", ".htm": "text/html", ".html": "text/html", ".jpeg": "image/jpeg", ".jpg": "image/jpeg", ".json": "application/json",
8
+ ".md": "text/markdown", ".pdf": "application/pdf", ".png": "image/png", ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
9
+ ".svg": "image/svg+xml", ".txt": "text/plain", ".webp": "image/webp", ".xls": "application/vnd.ms-excel",
10
+ ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", ".xml": "application/xml", ".zip": "application/zip",
11
+ };
12
+ // Where the opened file really is, so a parent directory swapped for a symlink after the check is caught.
13
+ async function openedPath(handle, checked) {
14
+ if (process.platform === "linux")
15
+ return readlink(`/proc/self/fd/${handle.fd}`).catch(() => null);
16
+ const [opened, now] = await Promise.all([handle.stat(), stat(checked).catch(() => null)]);
17
+ return now && opened.dev === now.dev && opened.ino === now.ino ? realpath(checked).catch(() => null) : null;
18
+ }
19
+ /** Files under `root` only: a relative path with no `..`, inside `root` once symlinks resolve, at most `maxBytes`, and
20
+ * not one `refuse` names (a host's private files). */
21
+ export function workspaceFiles(root, { maxBytes = MAX_UPLOAD_BYTES, refuse } = {}) {
22
+ return {
23
+ async resolve(rel) {
24
+ if (typeof rel !== "string" || !rel.trim() || rel.includes("\0"))
25
+ return { refused: "path must name a file in the workspace" };
26
+ if (path.isAbsolute(rel) || path.win32.isAbsolute(rel))
27
+ return { refused: `${rel} is absolute; give a path relative to the workspace` };
28
+ if (rel.split(/[\\/]/).includes(".."))
29
+ return { refused: `${rel} contains '..'; give a path inside the workspace` };
30
+ let base;
31
+ try {
32
+ base = await realpath(root);
33
+ }
34
+ catch {
35
+ return { refused: "the workspace does not exist" };
36
+ }
37
+ let real;
38
+ try {
39
+ real = await realpath(path.join(base, rel));
40
+ }
41
+ catch {
42
+ return { refused: `no file at ${rel} in the workspace` };
43
+ }
44
+ if (!real.startsWith(base + path.sep))
45
+ return { refused: `${rel} resolves outside the workspace` };
46
+ const handle = await open(real, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0)).catch(() => null);
47
+ if (!handle)
48
+ return { refused: `${rel} cannot be opened` };
49
+ try {
50
+ const where = await openedPath(handle, real);
51
+ if (!where?.startsWith(base + path.sep))
52
+ return { refused: `${rel} resolves outside the workspace` };
53
+ const vetoed = refuse?.(where);
54
+ if (vetoed)
55
+ return { refused: `${rel}: ${vetoed}` };
56
+ const info = await handle.stat();
57
+ if (!info.isFile())
58
+ return { refused: `${rel} is not a regular file` };
59
+ if (info.size > maxBytes)
60
+ return { refused: `${rel} is ${info.size} bytes, over the ${maxBytes}-byte limit` };
61
+ const buffer = Buffer.alloc(info.size + 1);
62
+ let size = 0;
63
+ for (let read; size < buffer.length && (read = (await handle.read(buffer, size, buffer.length - size, size)).bytesRead) > 0; size += read)
64
+ ;
65
+ if (size !== info.size)
66
+ return { refused: `${rel} changed while it was read; try again` };
67
+ return { bytes: new Uint8Array(buffer.subarray(0, size)), name: path.basename(where), mime: MIME[path.extname(where).toLowerCase()] ?? "application/octet-stream" };
68
+ }
69
+ finally {
70
+ await handle.close();
71
+ }
72
+ },
73
+ };
74
+ }
@@ -16,6 +16,8 @@ export declare function chunkPage(markdown: string, max?: number): Chunk[];
16
16
  export type FindOptions = {
17
17
  kind: "tree" | "page";
18
18
  rank?: Decisions["rankChunks"];
19
+ /** The run's redactor. It runs over the whole source before chunking, so a registered value across a chunk boundary is removed, not left as two halves. */
20
+ redact?: (text: string) => string;
19
21
  filedAt?: string | null;
20
22
  maxChars?: number;
21
23
  shownChunks?: number;
@@ -29,4 +31,4 @@ export type FindResult = {
29
31
  ids: string[];
30
32
  };
31
33
  /** Without a usable ranker the whole source comes back with a line saying find was not applied: never a silent cut. */
32
- export declare function findInText(source: string, query: string, options: FindOptions): Promise<FindResult>;
34
+ export declare function findInText(rawSource: string, rawQuery: string, options: FindOptions): Promise<FindResult>;
package/dist/core/find.js CHANGED
@@ -137,7 +137,8 @@ export function chunkPage(markdown, max = FIND_CHUNK_CHARS) {
137
137
  }
138
138
  const quote = (query) => JSON.stringify(query.length > 120 ? `${query.slice(0, 120)}…` : query);
139
139
  /** Without a usable ranker the whole source comes back with a line saying find was not applied: never a silent cut. */
140
- export async function findInText(source, query, options) {
140
+ export async function findInText(rawSource, rawQuery, options) {
141
+ const [source, query] = options.redact ? [options.redact(rawSource), options.redact(rawQuery)] : [rawSource, rawQuery];
141
142
  const whole = (why) => ({ text: `find ${quote(query)} was not applied: ${why}. The whole ${options.kind === "tree" ? "snapshot" : "page"} follows.\n${source}`, applied: false, chunks: 0, shown: [], ids: [] });
142
143
  if (!options.rank)
143
144
  return whole("this host has no ranker");
@@ -2,5 +2,13 @@ import { type BrowserFailure } from "./failures.js";
2
2
  export type RepeatGuard = {
3
3
  check(tool: string, args: unknown): BrowserFailure | null;
4
4
  note(tool: string, args: unknown, failure: BrowserFailure | null): void;
5
+ /** An effectful call the page never answered may have acted: the identical call (the same tool and effect key) is
6
+ * refused, as after an interruption, until the next look. In memory only, like the strikes: the failure that held
7
+ * it tells the model to look first, so a restart that forgets the hold loses nothing it was not told. */
8
+ hold(tool: string, effect: string): void;
9
+ held(tool: string, effect: string): boolean;
10
+ /** A snapshot or browser_read: every held call may run again. */
11
+ looked(): void;
5
12
  };
6
- export declare function createRepeatGuard(): RepeatGuard;
13
+ /** `redact` runs over the whole error before the cuts below, so no fragment of a registered value reaches the refusal. */
14
+ export declare function createRepeatGuard(redact?: (text: string) => string): RepeatGuard;
@@ -1,6 +1,8 @@
1
1
  import { browserFailure } from "./failures.js";
2
- export function createRepeatGuard() {
2
+ /** `redact` runs over the whole error before the cuts below, so no fragment of a registered value reaches the refusal. */
3
+ export function createRepeatGuard(redact = (text) => text) {
3
4
  const strikes = new Map();
5
+ const holds = new Set();
4
6
  const keyOf = (tool, args) => `${tool}:${JSON.stringify(args ?? {})}`;
5
7
  return {
6
8
  check(tool, args) {
@@ -9,6 +11,9 @@ export function createRepeatGuard() {
9
11
  return null;
10
12
  return browserFailure("refused", `Refused: ${tool} with these exact arguments already failed ${prior.count} times with the same error ("${prior.error.slice(0, 200)}"). Change approach: snapshot again and use current IDs, change the code or the URL, browser_relaunch({verified:true}) if the site blocks you, or fall back to web_fetch.`);
11
13
  },
14
+ hold(tool, effect) { holds.add(`${tool}:${effect}`); },
15
+ held(tool, effect) { return holds.has(`${tool}:${effect}`); },
16
+ looked() { holds.clear(); },
12
17
  note(tool, args, failure) {
13
18
  if (failure?.code === "aborted")
14
19
  return;
@@ -17,7 +22,7 @@ export function createRepeatGuard() {
17
22
  strikes.delete(key);
18
23
  return;
19
24
  }
20
- const error = `${failure.code}:${(failure.detail || failure.message).slice(0, 300)}`;
25
+ const error = `${failure.code}:${redact(failure.detail || failure.message).slice(0, 300)}`;
21
26
  const prior = strikes.get(key);
22
27
  strikes.set(key, prior && prior.error === error ? { error, count: prior.count + 1 } : { error, count: 1 });
23
28
  },
@@ -78,9 +78,11 @@ export type SessionSpec = {
78
78
  * memory only. */
79
79
  export type AttachTarget = {
80
80
  sdkCdpUrl: string;
81
+ /** `expiresAt` (epoch ms): the dial's credential ends then, so a socket opened on it is closed at that moment. */
81
82
  dial?: {
82
83
  url: string;
83
84
  headers?: Record<string, string>;
85
+ expiresAt?: number;
84
86
  };
85
87
  extensionId?: string;
86
88
  };
@@ -91,8 +93,12 @@ export type ProviderCaps = {
91
93
  releaseIsAsync: boolean;
92
94
  profiles: boolean;
93
95
  extension: "uploaded-per-launch" | "preinstalled" | "loaded-locally";
96
+ /** Every session attaches to the same browser (an endpoint the host named), so two at once would drive the same pages. */
97
+ sharedBrowser?: boolean;
94
98
  /** The session settings this provider applies; a setting left out is applied. */
95
99
  settings?: Partial<SessionSettingsSupport>;
100
+ /** The host assigned the run this one session: there is no other to relaunch onto. */
101
+ fixedSession?: boolean;
96
102
  };
97
103
  export type SessionSettingsSupport = {
98
104
  proxies: boolean;
@@ -171,6 +177,16 @@ export interface BrowserProvider {
171
177
  fetch?(request: FetchRequest, signal?: AbortSignal): Promise<FetchResult>;
172
178
  search?(request: SearchRequest, signal?: AbortSignal): Promise<SearchResult>;
173
179
  }
180
+ /** The host owns the file boundary for `browser_upload`: a path the model names is resolved here or refused. */
181
+ export interface WorkspaceFiles {
182
+ resolve(rel: string): Promise<{
183
+ bytes: Uint8Array;
184
+ name: string;
185
+ mime: string;
186
+ } | {
187
+ refused: string;
188
+ }>;
189
+ }
174
190
  /** A site use_website can open: configuration, never model input. */
175
191
  export type SiteInfo = {
176
192
  site: string;
@@ -204,6 +220,26 @@ export interface SiteRunPort {
204
220
  report: string;
205
221
  }>;
206
222
  }
223
+ export type HandoffOutcome = "done" | "cancelled" | "expired";
224
+ /** Hands the live browser to a person and reports how it ended. Polled by id, so a restarted process resumes the wait;
225
+ * when a request expires is the port's to decide. */
226
+ export interface HandoffPort {
227
+ /** Idempotent by `requestId`. `sessionId` is the provider's id for the held session, by which a host finds the
228
+ * session's own grants. `liveView` reaches the host only, never the model. */
229
+ request(ask: {
230
+ requestId: string;
231
+ sessionTag: string;
232
+ sessionId: string;
233
+ liveView: LiveView | null;
234
+ instruction: string;
235
+ completionCondition: string;
236
+ }, signal: AbortSignal): Promise<{
237
+ interactionId: string;
238
+ } | {
239
+ refused: string;
240
+ }>;
241
+ outcome(interactionId: string, signal: AbortSignal): Promise<"pending" | HandoffOutcome>;
242
+ }
207
243
  export type ReleaseReason = "tool" | "idle" | "relaunch" | "close" | "ended" | "lost" | "create_failed";
208
244
  export type SessionRecord = {
209
245
  tag: string;
@@ -229,6 +265,10 @@ export type SessionRecord = {
229
265
  }>;
230
266
  lastUrl: string | null;
231
267
  pendingEffect: PendingEffect | null;
268
+ /** Moves on each hand-over to a person and back; a driver attached under an older fence cannot act. Absent: 0. */
269
+ fence?: number;
270
+ /** While held: the request id of the handoff holding it. */
271
+ handoff?: string;
232
272
  spent: {
233
273
  seconds: number;
234
274
  usd: number;
@@ -236,6 +276,9 @@ export type SessionRecord = {
236
276
  final?: true;
237
277
  /** An unpriced or invalid price records seconds and no dollars, shown as unknown, never $0. */
238
278
  state?: PriceState;
279
+ /** The dollars of `usd` that were billed at the package's own `LIST_PRICES` (the host named no price when they were charged): an estimate, not a price the host named.
280
+ * Tracked as charges accumulate, so a record that resumes under a different price source keeps each charge's own label. */
281
+ estimatedUsd?: number;
239
282
  /** The sub-picodollar remainder carried to the next charge, so one rate's total is exact however many calls charged
240
283
  * it. */
241
284
  carry?: number;
@@ -255,9 +298,12 @@ export type SentEffect = {
255
298
  /** A replay-unsafe page action's journal entry. `observed`: a holding observer committed each request before it left the
256
299
  * browser; `watched`: an observer recorded the requests it sent, holding them or not. `incarnation`: the custody process that wrote it; an entry from an earlier one belongs to a resumed run.
257
300
  * `after`: the conversation's newest entry when it was journaled, where a resumed run's look for its answer starts.
258
- * `finished`: the action returned. `told` and `refused`: how far a cut has been answered. */
301
+ * `finished`: the action returned. `told` and `refused`: how far a cut has been answered. `toldBy`: the call that told it; it
302
+ * counts as told only once that call's answer, carrying this cut's facts, is saved. `prior`: an earlier entry this one
303
+ * replaced while its warning was still owed (a cut not yet told by a saved answer); it is told first. */
259
304
  export type PendingEffect = {
260
305
  callId: string;
306
+ tool?: "run" | "browser_upload";
261
307
  codeSha: string;
262
308
  url: string | null;
263
309
  at: string;
@@ -268,7 +314,9 @@ export type PendingEffect = {
268
314
  after?: number;
269
315
  finished?: boolean;
270
316
  told?: boolean;
317
+ toldBy?: string;
271
318
  refused?: boolean;
319
+ prior?: PendingEffect;
272
320
  };
273
321
  /** A cut action's facts, beside the notice in the call's `details.pendingEffect`. `sent` is null when no observer ran, so
274
322
  * an unknown never reads as none. */
@@ -6,12 +6,20 @@ export type ImageSize = {
6
6
  height: number;
7
7
  };
8
8
  export declare function imageSize(bytes: Uint8Array): ImageSize | null;
9
- /** `scale: "css"` takes one image pixel per CSS pixel, so a high-density display does not double the size. */
9
+ /** A region of the page in CSS pixels, from the viewport's top-left corner. */
10
+ export type Clip = {
11
+ x: number;
12
+ y: number;
13
+ width: number;
14
+ height: number;
15
+ };
16
+ /** `scale: "css"` takes one image pixel per CSS pixel, so a high-density display does not double the size. `clip` captures that region alone. */
10
17
  export type ScreenshotOptions = {
11
18
  fullPage?: boolean;
12
19
  type?: "png" | "jpeg";
13
20
  quality?: number;
14
21
  scale?: "css" | "device";
22
+ clip?: Clip;
15
23
  };
16
24
  export type Capture = (options: ScreenshotOptions) => Promise<{
17
25
  data: string;
@@ -30,7 +38,7 @@ export type BudgetedScreenshot = {
30
38
  export declare class ScreenshotBudgetError extends Error {
31
39
  name: string;
32
40
  }
33
- /** Over budget, retakes as a viewport JPEG at CSS scale, quality 40, 25, 10; throws ScreenshotBudgetError. */
41
+ /** Over budget, retakes as a viewport JPEG at CSS scale, quality 40, 25, 10 (of the same clip, when there is one); throws ScreenshotBudgetError. */
34
42
  export declare function captureWithinBudget(capture: Capture, requested: ScreenshotOptions, budget?: {
35
43
  maxEdgePx: number;
36
44
  maxBase64Bytes: number;