@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.
- package/CHANGELOG.md +5 -0
- package/README.md +177 -39
- package/dist/coding-agent-local.js +2 -1
- package/dist/coding-agent.d.ts +42 -2
- package/dist/coding-agent.js +159 -21
- package/dist/core/clip.d.ts +31 -0
- package/dist/core/clip.js +49 -0
- package/dist/core/contract.d.ts +4 -1
- package/dist/core/contract.js +40 -7
- package/dist/core/custody.d.ts +79 -5
- package/dist/core/custody.js +66 -5
- package/dist/core/decisions.d.ts +4 -0
- package/dist/core/dial.d.ts +7 -0
- package/dist/core/dial.js +41 -0
- package/dist/core/downloads.d.ts +1 -0
- package/dist/core/downloads.js +17 -5
- package/dist/core/driving-guard.d.ts +13 -0
- package/dist/core/driving-guard.js +61 -0
- package/dist/core/driving.d.ts +61 -0
- package/dist/core/driving.js +156 -0
- package/dist/core/effects.js +33 -13
- package/dist/core/evidence.d.ts +3 -1
- package/dist/core/failures.d.ts +5 -1
- package/dist/core/failures.js +20 -4
- package/dist/core/files.d.ts +8 -0
- package/dist/core/files.js +74 -0
- package/dist/core/find.d.ts +3 -1
- package/dist/core/find.js +2 -1
- package/dist/core/guard.d.ts +9 -1
- package/dist/core/guard.js +7 -2
- package/dist/core/host.d.ts +49 -1
- package/dist/core/images.d.ts +10 -2
- package/dist/core/images.js +4 -4
- package/dist/core/lease.d.ts +1 -1
- package/dist/core/lease.js +2 -1
- package/dist/core/session-control.d.ts +2 -0
- package/dist/core/session-control.js +5 -0
- package/dist/core/tools.d.ts +70 -4
- package/dist/core/tools.js +288 -45
- package/dist/core/unanswered.d.ts +3 -0
- package/dist/core/unanswered.js +17 -0
- package/dist/core/usage.d.ts +2 -0
- package/dist/core/usage.js +6 -0
- package/dist/core/web.d.ts +1 -1
- package/dist/core/web.js +9 -7
- package/dist/driver/extension-worker.d.ts +4 -2
- package/dist/driver/extension-worker.js +16 -10
- package/dist/driver/page-driver.d.ts +8 -0
- package/dist/driver/page-driver.js +128 -0
- package/dist/driver/stagehand.d.ts +3 -1
- package/dist/driver/stagehand.js +40 -66
- package/dist/durable.d.ts +16 -4
- package/dist/durable.js +415 -82
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/live-view/index.d.ts +4 -0
- package/dist/live-view/index.js +4 -0
- package/dist/live-view/protocol.d.ts +152 -0
- package/dist/live-view/protocol.js +84 -0
- package/dist/live-view/provider.d.ts +6 -0
- package/dist/live-view/provider.js +23 -0
- package/dist/live-view/server.d.ts +50 -0
- package/dist/live-view/server.js +342 -0
- package/dist/live-view/stream.d.ts +7 -0
- package/dist/live-view/stream.js +388 -0
- package/dist/live-view/token.d.ts +6 -0
- package/dist/live-view/token.js +13 -0
- package/dist/live-view/viewer.d.ts +6 -0
- package/dist/live-view/viewer.js +350 -0
- package/dist/live-view/ws.d.ts +19 -0
- package/dist/live-view/ws.js +176 -0
- package/dist/providers/assigned.d.ts +18 -0
- package/dist/providers/assigned.js +76 -0
- package/dist/providers/cdp-call.js +12 -2
- package/dist/providers/cdp.js +37 -11
- package/dist/recorder/follow.d.ts +10 -0
- package/dist/recorder/follow.js +27 -2
- package/dist/recorder/frames.d.ts +7 -0
- package/dist/recorder/frames.js +73 -5
- package/dist/store.d.ts +22 -3
- package/dist/store.js +75 -4
- package/dist/testing/backend.d.ts +26 -0
- package/dist/testing/backend.js +21 -3
- package/dist/testing/driver.d.ts +18 -1
- package/dist/testing/driver.js +4 -0
- package/dist/web.js +2 -2
- package/package.json +10 -2
package/dist/core/custody.d.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
/**
|
|
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
|
};
|
package/dist/core/custody.js
CHANGED
|
@@ -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:
|
|
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
|
|
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
|
-
//
|
|
132
|
-
const { sessionId, record } = await port.relaunch({ ...(args.verified
|
|
133
|
-
|
|
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);
|
package/dist/core/decisions.d.ts
CHANGED
|
@@ -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
|
+
}
|
package/dist/core/downloads.d.ts
CHANGED
package/dist/core/downloads.js
CHANGED
|
@@ -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
|
-
|
|
47
|
-
|
|
48
|
-
|
|
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
|
-
|
|
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;
|