@parcha/pi-browser 0.1.0-beta.18 → 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
@@ -1,6 +1,6 @@
1
1
  import { type BrowserFailure } from "./failures.js";
2
2
  import type { EffectObserver } from "./effects.js";
3
- import type { AttachTarget, BrowserConfig, Geo, ProviderCaps, ReleaseReason, SentEffect, SessionRecord, SessionSpec, SessionsState } from "./host.js";
3
+ import type { AttachTarget, BrowserConfig, BrowserProvider, Geo, HandoffOutcome, ProviderCaps, ReleaseReason, SentEffect, SessionRecord, SessionSpec, SessionsState } from "./host.js";
4
4
  import { type LeaseState } from "./lease.js";
5
5
  export type BrowserDriver = {
6
6
  close(): Promise<void>;
@@ -17,6 +17,8 @@ export declare class BrowserFailureError extends Error {
17
17
  name: string;
18
18
  constructor(failure: BrowserFailure);
19
19
  }
20
+ /** `verified: true` raises the run's Verified policy for one session; false or absent keeps the policy, which nothing
21
+ * here can lower. */
20
22
  export type Overrides = {
21
23
  verified?: boolean;
22
24
  geolocation?: Geo | null;
@@ -29,12 +31,24 @@ export type AttachedSession<D> = {
29
31
  notice: string | null;
30
32
  /** The cut this call answers for: a journal entry an earlier custody process left without a committed answer. */
31
33
  interrupted: SessionRecord["pendingEffect"];
34
+ /** Every cut in the journal chain, oldest first (`interrupted` is the one this call tells): a repeat of any is refused. */
35
+ cuts?: Array<NonNullable<SessionRecord["pendingEffect"]>>;
32
36
  recorded: boolean;
33
37
  effects: Pick<EffectObserver, "record" | "flush" | "holding"> | null;
38
+ downloads: BrowserProvider["downloads"] | null;
39
+ fence: number;
40
+ /** The session this one replaced after a release the model did not ask for (idle, close): by what and when (null while
41
+ * that release is in flight) and its last page. Present while this session has loaded no page. */
42
+ replaced?: {
43
+ reason: ReleaseReason;
44
+ at: string | null;
45
+ lastUrl: string | null;
46
+ } | null;
34
47
  };
35
48
  export interface CustodyPort<D extends BrowserDriver = BrowserDriver> {
36
- /** A call rerun after an interruption runs only on its first session, or fails with `session_replaced`. */
37
- session(): Promise<AttachedSession<D>>;
49
+ /** A call rerun after an interruption runs only on its first session, or fails with `session_replaced`. `signal` bounds
50
+ * this attach beside the call's own (a reconnect passes what is left of its budget). */
51
+ session(signal?: AbortSignal): Promise<AttachedSession<D>>;
38
52
  /** A rerun finds the session it launched. */
39
53
  relaunch(overrides: Overrides): Promise<AttachedSession<D>>;
40
54
  /** No session, or one already released, is not an error. */
@@ -47,9 +61,12 @@ export interface CustodyPort<D extends BrowserDriver = BrowserDriver> {
47
61
  at: string | null;
48
62
  };
49
63
  }>;
50
- /** Committed before the `run` is dispatched. */
64
+ /** The lease tag of the conversation's attached live session, or null: what `browser_release` and `browser_relaunch` are checked against (the live view's driving gate) before they act. */
65
+ current?(): Promise<string | null>;
66
+ /** Committed before a replay-unsafe action (`run`, `browser_upload`) is dispatched. */
51
67
  dispatching(effect: {
52
68
  callId: string;
69
+ tool?: "run" | "browser_upload";
53
70
  codeSha: string;
54
71
  url: string | null;
55
72
  observed: boolean;
@@ -57,7 +74,7 @@ export interface CustodyPort<D extends BrowserDriver = BrowserDriver> {
57
74
  }): Promise<void>;
58
75
  journal(row: SentEffect): Promise<void>;
59
76
  /** A journal entry's next step, by its call: the action returned, its cut was told, or an identical action was refused. */
60
- mark(step: "finished" | "told" | "refused", callId: string): Promise<void>;
77
+ mark(step: "finished" | "told" | "refused", callId: string, by?: string): Promise<void>;
61
78
  /** Clears the journal entry of that call only: another action's entry, journaled meanwhile, stays. */
62
79
  settle(callId: string): Promise<void>;
63
80
  navigated(url: string): Promise<void>;
@@ -65,6 +82,32 @@ export interface CustodyPort<D extends BrowserDriver = BrowserDriver> {
65
82
  ended(): Promise<boolean>;
66
83
  /** The provider still runs the session: the next `session()` reconnects to it. */
67
84
  dropped(): Promise<void>;
85
+ /** Hands the live session to a person: until `resume`, every call fails `waiting_for_human`. */
86
+ hold(requestId: string): Promise<{
87
+ tag: string;
88
+ sessionId: string;
89
+ }>;
90
+ /** Gives a held session back; `notice` is told on the next call. */
91
+ resume(notice: string | null): Promise<void>;
92
+ /** The provider still runs the session but every reconnect within the budget failed: custody releases it as `lost` (so a
93
+ * stuck session stops billing) and tells the next call, which opens a fresh one. `kept`: a person holds or drives it, so
94
+ * it stays. */
95
+ unreachable(): Promise<{
96
+ released: boolean;
97
+ lastUrl: string | null;
98
+ kept?: "held" | "viewing" | "person_driving";
99
+ }>;
100
+ /** Holds the session, asks the host's handoff port for a person, and waits for its answer; a rerun waits on the same
101
+ * request. */
102
+ handoff(ask: {
103
+ requestId: string;
104
+ instruction: string;
105
+ completionCondition: string;
106
+ }, signal?: AbortSignal): Promise<{
107
+ outcome: HandoffOutcome;
108
+ } | {
109
+ refused: string;
110
+ }>;
68
111
  }
69
112
  /** `details` reach the host's UI and wraps, never the model; `usage` is pi's, for the call's spend. */
70
113
  export type ToolOutput = {
@@ -86,10 +129,28 @@ export declare const VIEWPORT: Readonly<{
86
129
  height: 711;
87
130
  }>;
88
131
  export declare const SESSION_REPLACED: BrowserFailure;
132
+ export declare const waitingForHuman: (requestId: string) => BrowserFailure;
133
+ export declare const HANDED_BACK: BrowserFailure;
134
+ export declare const NO_HANDOFF: BrowserFailure;
135
+ export declare const NOTHING_TO_HOLD: BrowserFailure;
136
+ /** The fence a session is at in this process, and what a driver attached under an older one is told. */
137
+ export type FenceMark = {
138
+ fence: number;
139
+ failure: BrowserFailure;
140
+ };
141
+ /** A fenced driver's refusal: the call was made after the session moved past the driver's fence, so it never reached the page. */
142
+ export declare class FenceRefusal extends BrowserFailureError {
143
+ }
144
+ /** How many calls a fenced driver has let through; null for a driver that is not fenced. */
145
+ export declare const passedThrough: (driver: object) => number | null;
146
+ export declare function fenced<D extends BrowserDriver>(driver: D, fence: number, mark: () => FenceMark | undefined): D;
147
+ export declare const backoffMs: (attempt: number) => number;
89
148
  export declare const notices: {
90
149
  kept: (url: string | null) => string;
91
150
  lost: (url: string | null) => string;
92
151
  ended: (url: string | null) => string;
152
+ unreachable: (url: string | null) => string;
153
+ handedBack: (outcome: HandoffOutcome, condition: string) => string;
93
154
  released: (reason: "idle" | "close", url: string | null, idleS: number) => string;
94
155
  };
95
156
  export declare function currentRecord(state: SessionsState | undefined, plane: string): SessionRecord | null;
@@ -101,17 +162,23 @@ export declare function newSessionRecord(input: {
101
162
  at: string;
102
163
  honours?: ProviderCaps["settings"];
103
164
  }): SessionRecord;
165
+ /** A session whose browser has loaded no page yet: nothing but about:blank was ever recorded for it (a run that loads no
166
+ * page records the blank page it is on). */
167
+ export declare const loadedNoPage: (record: SessionRecord) => boolean;
104
168
  export declare function moveRecord(record: SessionRecord, next: {
105
169
  state: LeaseState;
106
170
  resourceId?: string;
107
171
  reason?: ReleaseReason;
108
172
  at: string;
173
+ handoff?: string;
109
174
  }): void;
110
175
  export declare const PROFILE_NAME: RegExp;
111
176
  export declare function sessionSpec(config: BrowserConfig, tag: string, overrides?: Overrides): SessionSpec;
112
177
  export declare function profileRefusal(spec: SessionSpec, caps: ProviderCaps): BrowserFailure | null;
113
178
  /** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
114
179
  * silently. */
180
+ /** browser_relaunch on a provider whose session the host assigned: nothing to relaunch onto, and nothing released. */
181
+ export declare const FIXED_SESSION_RELAUNCH: BrowserFailure;
115
182
  export declare function relaunchRefusal(policy: BrowserConfig["policy"], overrides: Overrides): BrowserFailure | null;
116
183
  /** An ISO alpha-2 country, a US state abbreviation, a city in capitals; null when the country is not two letters. */
117
184
  export declare function normalizeGeolocation(raw: unknown): Geo | null;
@@ -121,4 +188,11 @@ export declare const custodyTools: {
121
188
  verified?: boolean;
122
189
  geolocation?: unknown;
123
190
  }, port: CustodyPort): Promise<ToolOutput>;
191
+ browser_request_handoff(args: {
192
+ request_id: string;
193
+ instruction: string;
194
+ completion_condition: string;
195
+ }, port: CustodyPort, call?: {
196
+ signal?: AbortSignal;
197
+ }): Promise<ToolOutput>;
124
198
  };
@@ -19,10 +19,44 @@ export class BrowserFailureError extends Error {
19
19
  export const NAVIGATION_CAP = 500;
20
20
  export const VIEWPORT = Object.freeze({ width: 1288, height: 711 });
21
21
  export const SESSION_REPLACED = browserFailure("session_replaced", "The browser session this call was using ended in an interruption, so its page is gone. Navigate again with run, or take a snapshot, to continue in a fresh session.", { retryable: true });
22
+ export const waitingForHuman = (requestId) => browserFailure("waiting_for_human", `The browser is with a person right now (your handoff ${requestId}). Do not browse; wait for the handoff result.`);
23
+ export const HANDED_BACK = browserFailure("stale_snapshot", "A person used the browser while this call waited, so the page may have changed. Take a snapshot before acting again.", { retryable: true });
24
+ export const NO_HANDOFF = browserFailure("refused", "No person can be reached from this browser, so nothing was handed over.");
25
+ export const NOTHING_TO_HOLD = browserFailure("refused", "There is no open browser session to hand to a person. Open one with a browser call first.");
26
+ /** A fenced driver's refusal: the call was made after the session moved past the driver's fence, so it never reached the page. */
27
+ export class FenceRefusal extends BrowserFailureError {
28
+ }
29
+ const PASSED = Symbol("calls that passed the fence");
30
+ /** How many calls a fenced driver has let through; null for a driver that is not fenced. */
31
+ export const passedThrough = (driver) => driver[PASSED] ?? null;
32
+ export function fenced(driver, fence, mark) {
33
+ let passed = 0;
34
+ return new Proxy(driver, {
35
+ get(target, key) {
36
+ if (key === PASSED)
37
+ return passed;
38
+ const value = Reflect.get(target, key);
39
+ if (typeof value !== "function")
40
+ return value;
41
+ return (...args) => {
42
+ const moved = mark();
43
+ if (moved && moved.fence > fence)
44
+ return Promise.reject(new FenceRefusal(moved.failure));
45
+ passed += 1;
46
+ return value.apply(target, args);
47
+ };
48
+ },
49
+ });
50
+ }
51
+ export const backoffMs = (attempt) => Math.min(30_000, 500 * 2 ** attempt);
22
52
  export const notices = {
23
53
  kept: (url) => `Your browser session survived an interruption and is still open${url ? ` on ${url}` : ""}. Take a snapshot before acting again.`,
24
54
  lost: (url) => `Your browser session ended during an interruption. The next browser call opens a fresh session with no cookies or page state${url ? `; the last page was ${url}` : ""}.`,
25
55
  ended: (url) => `Your previous browser session had ended (the provider closed it), so this call runs in a fresh session with no cookies or page state${url ? `; the last page was ${url}` : ""}.`,
56
+ unreachable: (url) => `Your previous browser session could not be reconnected and was released, so this call runs in a fresh session with no cookies or page state${url ? `; the last page was ${url}, so navigate there again to continue` : ""}.`,
57
+ handedBack: (outcome, condition) => outcome === "done"
58
+ ? `A person finished your handoff: verify on the page that ${condition} before acting.`
59
+ : `Your handoff ended ${outcome} before the person finished it. Take a snapshot to see the page before acting.`,
26
60
  released: (reason, url, idleS) => `Your previous browser session was released ${reason === "idle" ? `after ${idleS} seconds without a browser call` : "when the host closed it"}, so this call runs in a fresh session that starts on a blank page with no cookies or page state${url ? `; the last page was ${url}, so navigate there again to continue` : ""}.`,
27
61
  };
28
62
  export function currentRecord(state, plane) {
@@ -43,11 +77,20 @@ export function newSessionRecord(input) {
43
77
  navigation: [], lastUrl: null, pendingEffect: null, spent: startSpent(input.at),
44
78
  };
45
79
  }
80
+ /** A session whose browser has loaded no page yet: nothing but about:blank was ever recorded for it (a run that loads no
81
+ * page records the blank page it is on). */
82
+ export const loadedNoPage = (record) => (record.lastUrl === null || record.lastUrl === "about:blank") && record.navigation.every((step) => step.url === "about:blank");
46
83
  export function moveRecord(record, next) {
47
84
  if (record.state === next.state && next.resourceId === undefined)
48
85
  return;
49
86
  if (!isLeaseTransition(record.state, next.state))
50
87
  throw new Error(`session ${record.tag}: ${record.state} cannot become ${next.state}`);
88
+ if (next.state === "held" || (record.state === "held" && next.state === "live"))
89
+ record.fence = (record.fence ?? 0) + 1;
90
+ if (record.state === "held")
91
+ delete record.handoff;
92
+ if (next.handoff !== undefined)
93
+ record.handoff = next.handoff;
51
94
  record.state = next.state;
52
95
  if (next.resourceId !== undefined)
53
96
  record.resourceId = next.resourceId;
@@ -68,7 +111,7 @@ export function sessionSpec(config, tag, overrides = {}) {
68
111
  return {
69
112
  tag, maxLifetimeS: policy.sessionTimeoutS, idleTimeoutS: policy.idleReleaseS,
70
113
  proxies: !policy.proxies ? false : geolocation ? { geolocation } : true,
71
- verified: overrides.verified ?? policy.verified, captcha: policy.captcha,
114
+ verified: policy.verified || overrides.verified === true, captcha: policy.captcha,
72
115
  ...(policy.region ? { region: policy.region } : {}),
73
116
  viewport: { ...VIEWPORT },
74
117
  ...(policy.contextId ? { contextId: policy.contextId } : {}),
@@ -82,11 +125,15 @@ export function profileRefusal(spec, caps) {
82
125
  }
83
126
  /** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
84
127
  * silently. */
128
+ /** browser_relaunch on a provider whose session the host assigned: nothing to relaunch onto, and nothing released. */
129
+ export const FIXED_SESSION_RELAUNCH = Object.freeze({ ok: false, code: "refused", retryable: false, effect: "none", message: "browser_relaunch: this task's browser is the one session its host assigned it, and there is no other to relaunch onto. Nothing was relaunched and your session is unchanged; keep using it." });
85
130
  export function relaunchRefusal(policy, overrides) {
86
131
  if (!overrides.geolocation || policy.proxies)
87
132
  return null;
88
133
  return browserFailure("refused", "browser_relaunch: geolocation needs a proxy, and this run's browser policy has proxies off, so no session can browse from a chosen place. Nothing was relaunched and your session is unchanged; browser_relaunch can still change verified, with geolocation left out.");
89
134
  }
135
+ /** The route's model fills every optional property with a blank, so an absent, null or all-blank object names no place. */
136
+ const unsetGeolocation = (raw) => raw === undefined || raw === null || (typeof raw === "object" && Object.values(raw).every((v) => v === undefined || v === null || (typeof v === "string" && v.trim() === "")));
90
137
  /** An ISO alpha-2 country, a US state abbreviation, a city in capitals; null when the country is not two letters. */
91
138
  export function normalizeGeolocation(raw) {
92
139
  if (!raw || typeof raw !== "object")
@@ -104,6 +151,7 @@ export function normalizeGeolocation(raw) {
104
151
  out.city = city;
105
152
  return out;
106
153
  }
154
+ const VERIFIED_KEPT = "This run's sessions are Verified, so the new one is too: a relaunch can ask for Verified with verified: true but never drop it.";
107
155
  const text = (value, isError = false) => ({ content: [{ type: "text", text: JSON.stringify(value) }], ...(isError ? { isError } : {}) });
108
156
  const failed = (error) => {
109
157
  if (error instanceof BrowserFailureError)
@@ -124,13 +172,26 @@ export const custodyTools = {
124
172
  }
125
173
  },
126
174
  async browser_relaunch(args, port) {
127
- const geolocation = args.geolocation === undefined ? undefined : normalizeGeolocation(args.geolocation);
175
+ const geolocation = unsetGeolocation(args.geolocation) ? undefined : normalizeGeolocation(args.geolocation);
128
176
  if (geolocation === null)
129
177
  return text(browserFailure("refused", 'browser_relaunch: geolocation needs a two-letter ISO country code (e.g. {country: "GB"}).'), true);
130
178
  try {
131
- // A relaunch that names no `verified` keeps the run's policy: an omitted flag never downgrades a Verified session.
132
- const { sessionId, record } = await port.relaunch({ ...(args.verified !== undefined ? { verified: args.verified === true } : {}), ...(geolocation ? { geolocation } : {}) });
133
- return text({ ok: true, session: sessionId, verified: record.settings.verified, proxies: record.settings.proxies, geolocation: record.settings.geolocation });
179
+ // The route's model fills every optional property, so a false is no instruction: only true is passed on.
180
+ const { sessionId, record } = await port.relaunch({ ...(args.verified === true ? { verified: true } : {}), ...(geolocation ? { geolocation } : {}) });
181
+ const kept = args.verified === false && record.settings.verified;
182
+ return text({ ok: true, session: sessionId, verified: record.settings.verified, proxies: record.settings.proxies, geolocation: record.settings.geolocation, ...(kept ? { note: VERIFIED_KEPT } : {}) });
183
+ }
184
+ catch (error) {
185
+ return failed(error);
186
+ }
187
+ },
188
+ async browser_request_handoff(args, port, call) {
189
+ try {
190
+ const answer = await port.handoff({ requestId: args.request_id, instruction: args.instruction, completionCondition: args.completion_condition }, call?.signal);
191
+ if ("refused" in answer)
192
+ return text(browserFailure("refused", `No person could take the browser: ${answer.refused}. Your session is unchanged; go on without the handoff.`), true);
193
+ const next = answer.outcome === "done" ? "Take a snapshot and verify the completion condition on the page before acting." : "The person did not finish. Take a snapshot to see the page before deciding what to do next.";
194
+ return text({ ok: true, outcome: answer.outcome, completion_condition: args.completion_condition, next });
134
195
  }
135
196
  catch (error) {
136
197
  return failed(error);
@@ -5,6 +5,10 @@ export type PageForJudgment = {
5
5
  status: number | null;
6
6
  contentType: string | null;
7
7
  text: string;
8
+ /** The distinct origins of the page's frames (at most five, in document order, redacted), when it has any. A frame's content is not in `text`: a page whose content sits in a challenge frame has almost none of its own. */
9
+ frames?: string[];
10
+ /** What the page puts INSIDE its frame elements (their fallback text, whitespace collapsed, at most 200 characters each, at most five, redacted), when any is there: a browser does not render it, so `text` lacks it, and a block page (Incapsula's) keeps its message there. */
11
+ frameText?: string[];
8
12
  };
9
13
  export type PageVerdict = {
10
14
  /** "content" files the page `ok`; a wall class files it `failed` with a typed way out. */
@@ -0,0 +1,7 @@
1
+ import type { AttachTarget } from "./host.js";
2
+ type Dialable = Pick<AttachTarget, "sdkCdpUrl" | "dial">;
3
+ export declare const dialUrl: (target: Dialable) => string;
4
+ export declare const placeholderUrl: (id: string) => string;
5
+ export declare const isPlaceholder: (url: string) => boolean;
6
+ export declare function openDial(target: Dialable): WebSocket;
7
+ export {};
@@ -0,0 +1,41 @@
1
+ // The one way a CDP socket is opened from an AttachTarget: its dial URL with its headers (a relay's capability) when it has
2
+ // them, its driver URL otherwise. A dial's address and headers carry credentials, so no error names more than the host, and
3
+ // a dial whose credential ends (`expiresAt`) is closed at that moment.
4
+ import { randomUUID } from "node:crypto";
5
+ export const dialUrl = (target) => target.dial?.url ?? target.sdkCdpUrl;
6
+ /** A driver URL no browser can dial, for a target whose browser has no URL of its own (a relay that needs a header the
7
+ * browser cannot send). Unique per call, so a binding keyed on one never catches another session's socket; a driver
8
+ * refuses such a target by this marker, never by guessing from its headers. */
9
+ const PLACEHOLDER = "ws://127.0.0.1:1/no-browser-url/";
10
+ export const placeholderUrl = (id) => `${PLACEHOLDER}${encodeURIComponent(id)}/${randomUUID()}`;
11
+ export const isPlaceholder = (url) => typeof url === "string" && url.startsWith(PLACEHOLDER);
12
+ /** A URL's host, for messages: never its path, query or userinfo. */
13
+ function hostOf(url) {
14
+ try {
15
+ return new URL(url).host || "an unnamed host";
16
+ }
17
+ catch {
18
+ return "an unreadable address";
19
+ }
20
+ }
21
+ export function openDial(target) {
22
+ const url = dialUrl(target);
23
+ const expiresAt = target.dial?.expiresAt;
24
+ if (expiresAt !== undefined && !(expiresAt > Date.now()))
25
+ throw new Error(`the CDP dial to ${hostOf(url)} has expired`);
26
+ const headers = target.dial?.headers;
27
+ let socket;
28
+ try {
29
+ // Node's WebSocket (undici) takes its headers in an init object.
30
+ socket = headers ? new WebSocket(url, { headers: { ...headers } }) : new WebSocket(url);
31
+ }
32
+ catch {
33
+ throw new Error(`the CDP socket to ${hostOf(url)} could not be opened`);
34
+ }
35
+ if (expiresAt !== undefined) {
36
+ const deadline = setTimeout(() => socket.close(), Math.max(0, expiresAt - Date.now()));
37
+ deadline.unref?.();
38
+ socket.addEventListener("close", () => clearTimeout(deadline), { once: true });
39
+ }
40
+ return socket;
41
+ }
@@ -33,4 +33,5 @@ export declare function fetchDownloads(options: {
33
33
  maxBytes?: number;
34
34
  maxFiles?: number;
35
35
  now?: () => Date;
36
+ redact?: (text: string) => string;
36
37
  }): Promise<DownloadsResult>;
@@ -1,6 +1,7 @@
1
1
  import { createHash, randomBytes } from "node:crypto";
2
2
  import { lstat, mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
3
3
  import path from "node:path";
4
+ import { BrowserFailureError } from "./custody.js";
4
5
  export const DOWNLOADS_DIR = "downloads";
5
6
  export const DOWNLOADS_MANIFEST = "downloads/manifest.json";
6
7
  /** Beside `downloads/`, not in it, so no downloaded file can take its name; temporary names start with a dot, which no
@@ -41,14 +42,25 @@ export async function withLock(file, run, what = "downloads/manifest.json") {
41
42
  await rm(file, { force: true });
42
43
  }
43
44
  }
45
+ /** A manifest that is there but unreadable is refused, never replaced: its rows are the only record of earlier fetches. */
44
46
  async function readManifest(file) {
47
+ let raw;
45
48
  try {
46
- const parsed = JSON.parse(await readFile(file, "utf8"));
47
- if (parsed?.schema === "pi-browser.downloads.v1" && Array.isArray(parsed.files))
48
- return parsed;
49
+ raw = await readFile(file, "utf8");
50
+ }
51
+ catch (error) {
52
+ if (error.code === "ENOENT")
53
+ return { schema: "pi-browser.downloads.v1", files: [] };
54
+ throw error;
55
+ }
56
+ let parsed = null;
57
+ try {
58
+ parsed = JSON.parse(raw);
49
59
  }
50
60
  catch { }
51
- return { schema: "pi-browser.downloads.v1", files: [] };
61
+ if (parsed?.schema === "pi-browser.downloads.v1" && Array.isArray(parsed.files))
62
+ return parsed;
63
+ throw new BrowserFailureError({ ok: false, code: "refused", retryable: false, effect: "none", message: `${DOWNLOADS_MANIFEST} exists but is not a pi-browser downloads manifest; fix or move it, then call browser_downloads again.` });
52
64
  }
53
65
  /** Skips what the workspace already holds; one failing file is skipped with its reason. */
54
66
  export async function fetchDownloads(options) {
@@ -124,7 +136,7 @@ export async function fetchDownloads(options) {
124
136
  }
125
137
  catch (error) {
126
138
  await rm(part, { force: true });
127
- result.skipped.push({ name: file.name, reason: error instanceof Error ? error.message.slice(0, 200) : "the read failed" });
139
+ result.skipped.push({ name: file.name, reason: error instanceof Error ? (options.redact ?? ((text) => text))(error.message).slice(0, 200) : "the read failed" });
128
140
  }
129
141
  }
130
142
  return result;
@@ -0,0 +1,13 @@
1
+ import { type BrowserDriver } from "./custody.js";
2
+ import { type DrivingGates } from "./driving.js";
3
+ import type { ToolImpl } from "./tools.js";
4
+ /** Told to the model's next call once a person has driven the session through the live view: the page can change without its URL changing. */
5
+ export declare const PERSON_DROVE = "A person used this browser through the live view since your last call, so the page may have changed even where its address did not: take a snapshot before you act on an element by its id.";
6
+ /** One browser tool as a model call on its session's driving gate: it is refused, typed and before it has done anything, while a person drives that session
7
+ * through the live view, and it holds the gate for as long as it runs, so the viewer's input is held meanwhile. The session is known when the tool first
8
+ * asks its port for it (`session()` or `relaunch()`), which is every tool's first act on the browser. */
9
+ export declare function drivingGuard<D extends BrowserDriver, A = unknown>(impl: ToolImpl<D, A>, gates?: DrivingGates, options?: {
10
+ early?: boolean;
11
+ }): ToolImpl<D, A>;
12
+ /** Every implementation of a toolset guarded as above. */
13
+ export declare function drivingGuarded<D extends BrowserDriver>(impls: Partial<Record<string, ToolImpl<D>>>, gates?: DrivingGates): Partial<Record<string, ToolImpl<D>>>;
@@ -0,0 +1,61 @@
1
+ import { BrowserFailureError } from "./custody.js";
2
+ import { drivingGates, personDrivingFailure, PERSON_DRIVING } from "./driving.js";
3
+ /** Told to the model's next call once a person has driven the session through the live view: the page can change without its URL changing. */
4
+ export const PERSON_DROVE = "A person used this browser through the live view since your last call, so the page may have changed even where its address did not: take a snapshot before you act on an element by its id.";
5
+ /** One browser tool as a model call on its session's driving gate: it is refused, typed and before it has done anything, while a person drives that session
6
+ * through the live view, and it holds the gate for as long as it runs, so the viewer's input is held meanwhile. The session is known when the tool first
7
+ * asks its port for it (`session()` or `relaunch()`), which is every tool's first act on the browser. */
8
+ export function drivingGuard(impl, gates = drivingGates, options = {}) {
9
+ return async (args, port, call) => {
10
+ let held = null;
11
+ /** Takes the tag's gate for the model; true when a person has driven that session since the model's last call. */
12
+ const enter = (tag) => {
13
+ if (held?.tag === tag)
14
+ return false;
15
+ const entered = gates(tag).model();
16
+ // A BrowserFailureError is what a tool already turns into a typed failure result, as it does for its own refusals.
17
+ if (entered === PERSON_DRIVING)
18
+ throw new BrowserFailureError(personDrivingFailure());
19
+ held?.release();
20
+ held = { tag, release: entered.release };
21
+ return entered.drove === true;
22
+ };
23
+ /** A person drove: the session's snapshot ids are dropped (an old id then fails as a stale snapshot, whatever the URL), the call is told why,
24
+ * and only then is the gate told. A call that took the gate without its session (release, relaunch) tells nothing and uses nothing up. */
25
+ const told = (attached, drove) => {
26
+ if (!drove)
27
+ return attached;
28
+ try {
29
+ void Promise.resolve(attached.driver.forgetSnapshots?.()).catch(() => undefined);
30
+ }
31
+ catch { /* a driver without snapshot ids has none to drop */ }
32
+ gates(attached.tag).told();
33
+ return { ...attached, notice: [attached.notice, PERSON_DROVE].filter(Boolean).join(" ") };
34
+ };
35
+ // Every other member runs on the real port (`this` is the port, so a class-based port's own state is written to it, not to a copy).
36
+ const overrides = {
37
+ session: async (signal) => { const attached = await port.session(signal); return told(attached, enter(attached.tag)); },
38
+ relaunch: async (o) => { const attached = await port.relaunch(o); enter(attached.tag); return attached; },
39
+ };
40
+ const guarded = new Proxy(port, { get(target, key) { if (key in overrides)
41
+ return overrides[key]; const value = Reflect.get(target, key, target); return typeof value === "function" ? value.bind(target) : value; } });
42
+ try {
43
+ // A tool that ends the session (release, relaunch) does not ask for it first: the gate is taken for the session that is attached now.
44
+ if (options.early) {
45
+ const tag = await port.current?.();
46
+ if (tag)
47
+ enter(tag);
48
+ }
49
+ return await impl(args, guarded, call);
50
+ }
51
+ finally {
52
+ held?.release();
53
+ }
54
+ };
55
+ }
56
+ /** The tools that end the live session they find, so they are checked against it before they act, not at their first `session()`. */
57
+ const ENDS_SESSION = new Set(["browser_release", "browser_relaunch"]);
58
+ /** Every implementation of a toolset guarded as above. */
59
+ export function drivingGuarded(impls, gates) {
60
+ return Object.fromEntries(Object.entries(impls).map(([name, impl]) => [name, impl && drivingGuard(impl, gates, { early: ENDS_SESSION.has(name) })]));
61
+ }
@@ -0,0 +1,61 @@
1
+ import { type BrowserFailure } from "./failures.js";
2
+ /** Who is acting on the browser. `person`: input arrived from the viewer within the idle window. `agent`: a model browser call is in flight,
3
+ * and viewer input is discarded (never queued, so a keystroke is not replayed into a page the model has since moved). */
4
+ export type DriveState = "idle" | "person" | "agent";
5
+ /** The person/model mutex for one browser (core/driving.ts, keyed by the session's lease tag). Person input and a model's browser call never
6
+ * interleave: while a call is in flight the viewer's input is discarded with a notice, and while a person drives a model call is refused. */
7
+ export type DrivingGate = {
8
+ state(): DriveState;
9
+ /** Viewer input arrived: `driving` marks the person as driving until the idle window passes; `agent_acting` means a model call is in flight. */
10
+ input(): "driving" | "agent_acting";
11
+ /** A model browser call is about to start: a release function, or `person_driving` when a person is driving. `drove` is true when a person has driven
12
+ * this session and the model has not yet been told (`told`): the page may have changed under the model's last snapshot, whatever its URL says. */
13
+ model(): {
14
+ release(): void;
15
+ drove: boolean;
16
+ } | "person_driving";
17
+ /** The model's call has been told a person drove (its snapshot ids dropped, the notice given): `drove` is false until a person drives again. */
18
+ told(): void;
19
+ /** Called with the new state at every change. Returns the unsubscribe. */
20
+ onChange(listener: (state: DriveState) => void): () => void;
21
+ /** True while an AUTHENTICATED viewer is connected to this session's live view, whether or not it has touched anything lately: `person` lasts only the idle window
22
+ * after the last input, and a person mid-sign-in can sit still longer than that with the viewer open. Custody reads it before it releases a session on its own. */
23
+ viewing(): boolean;
24
+ /** The live view's server sets it when a viewer's hello is accepted and clears it when that viewer's socket closes or the session is released. */
25
+ setViewing(on: boolean): void;
26
+ /** The session was released: listeners dropped, the gate forgotten, no viewer. */
27
+ end(): void;
28
+ };
29
+ export type DrivingGates = (tag: string) => DrivingGate;
30
+ /** The typed marker a refused model call opens its message with, as #1000's busy refusals open theirs with `browser_busy (fill)`. */
31
+ export declare const PERSON_DRIVING = "person_driving";
32
+ /** The failure a model browser call gets while a person drives: `refused`, retryable (the person's turn ends), nothing was done. */
33
+ export declare const personDrivingFailure: () => BrowserFailure;
34
+ export type Timers = {
35
+ set(run: () => void, ms: number): unknown;
36
+ clear(handle: unknown): void;
37
+ };
38
+ export type DrivingOptions = {
39
+ /** A person keeps driving this long after their last input, then the model may act again. Default 3 s. */
40
+ idleMs?: number;
41
+ /** For tests: the timer functions. */
42
+ timers?: Timers;
43
+ };
44
+ /** 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()`). */
45
+ export declare function createDrivingGates(options?: DrivingOptions): DrivingGates;
46
+ /** Runs `work` as one model browser call on `gate`: refused, typed, while a person drives; released whatever the work does. */
47
+ export declare function withModelCall<T>(gate: DrivingGate, work: () => Promise<T>): Promise<T>;
48
+ /** 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
49
+ * session tag without any plumbing. A test that wants an isolated one calls `createDrivingGates()`. */
50
+ export declare const drivingGates: DrivingGates;
51
+ /** Why custody keeps a session it would otherwise release on its own (an idle window, a connection it cannot get back): a
52
+ * person drives it, or watches it, through the live view. Null when no person is on it. */
53
+ export declare const keptFor: (gate: DrivingGate) => "person_driving" | "viewing" | null;
54
+ /** The session's gate when a person drives or watches it through the live view, else null. The registry makes a gate on its
55
+ * 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
56
+ * viewer or a listener, stays), and custody's own check never leaves one behind. */
57
+ export declare function personOn(gates: DrivingGates, tag: string): DrivingGate | null;
58
+ /** A session custody kept for a person is released one idle window after they leave: the gate is polled (setViewing and end
59
+ * announce nothing), and the moment nobody is on it `rearm` starts the idle window again. Stops once `alive` says the session
60
+ * is gone; the returned function stops it at once (a release, a close). */
61
+ export declare function rearmWhenLeft(gate: DrivingGate, alive: () => boolean, rearm: () => void, idleMs: number): () => void;