@withgateway/sdk 0.6.0 → 0.9.3
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/dist/agents/index.d.mts +581 -0
- package/dist/agents/index.d.ts +581 -0
- package/dist/agents/index.js +1473 -0
- package/dist/agents/index.js.map +1 -0
- package/dist/agents/index.mjs +1424 -0
- package/dist/agents/index.mjs.map +1 -0
- package/dist/apiError-DHpfbmdx.d.mts +17 -0
- package/dist/apiError-DHpfbmdx.d.ts +17 -0
- package/dist/cli.js +11611 -6845
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +10090 -5325
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +3 -1
- package/dist/files/index.d.ts +3 -1
- package/dist/files/index.js +371 -102
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +371 -102
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.js +346 -136
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +346 -136
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
- package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
- package/dist/index.d.mts +7 -4
- package/dist/index.d.ts +7 -4
- package/dist/index.js +3177 -748
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2987 -590
- package/dist/index.mjs.map +1 -1
- package/dist/media-CQUC7TkS.d.mts +39 -0
- package/dist/media-DQnBloaX.d.ts +39 -0
- package/dist/traces/index.d.mts +3 -1
- package/dist/traces/index.d.ts +3 -1
- package/dist/traces/index.js +371 -102
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +371 -102
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +3 -2
- package/dist/tracing/index.d.ts +3 -2
- package/dist/tracing/index.js +257 -16
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +257 -16
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/transport-CpRe7zgd.d.mts +123 -0
- package/dist/transport-CpRe7zgd.d.ts +123 -0
- package/dist/worlds/index.d.mts +1986 -1746
- package/dist/worlds/index.d.ts +1986 -1746
- package/dist/worlds/index.js +1470 -290
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1465 -286
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +6 -1
- package/runtime/gatewaysdk/environment/bundle_manifest.py +531 -0
- package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
- package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
- package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
- package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
- package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
- package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
- package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
- package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
- package/runtime/gatewaysdk/environment/schema/api.py +3 -4
- package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
- package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
- package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
- package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
- package/runtime/gatewaysdk/environment/schema/host.py +94 -12
- package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
- package/runtime/gatewaysdk/environment/schema/host_control.py +35 -2
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
- package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
- package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
- package/runtime/gatewaysdk/environment/schema/host_requests.py +35 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +20 -2
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +100 -19
- package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
- package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
- package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
- package/runtime/gatewaysdk/environment/schema/local.py +32 -7
- package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
- package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
- package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +80 -270
- package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
- package/runtime/gatewaysdk/environment/schema/platform_templates.py +420 -0
- package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
- package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
- package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +57 -5
- package/runtime/gatewaysdk/environment/schema/scaffold.py +386 -219
- package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
- package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
- package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
- package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +2 -2
- package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +8 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
- package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
- package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
- package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
- package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
- package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
- package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
- package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
- package/runtime/gatewaysdk/environment/schema/validation.py +24 -1
- package/runtime/gatewaysdk/environment/schema/worker.py +12 -5
- package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
- package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
- package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
- package/runtime/gatewaysdk/environment/schema/workers.py +245 -69
- package/runtime/gatewaysdk/environment/schema/world_host.py +96 -73
- package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
- package/runtime/gatewaysdk/environment/secret_values.py +1 -1
- package/runtime/gatewaysdk/environment/world.py +34 -43
- package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
- package/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/skills/connector-schema-authoring/SKILL.md +2 -2
- package/skills/connector-schema-authoring/connector-worlds.md +3 -2
- package/skills/connector-schema-authoring/world-schema.md +36 -23
- package/skills/factory-orchestrator/SKILL.md +147 -0
- package/skills/world-data-ingestion/ROWS.md +5 -1
- package/skills/world-data-ingestion/SKILL.md +8 -6
- package/skills/worlds-getting-started/SKILL.md +9 -9
- package/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
- package/skills/worlds-getting-started/references/gotchas.md +6 -6
- package/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
- package/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/dist/media-BIApiPzS.d.mts +0 -102
- package/dist/media-BIApiPzS.d.ts +0 -102
package/dist/worlds/index.d.mts
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export {
|
|
1
|
+
import { R as RetryPolicy, k as PersonalToken, e as PlatformMethod } from '../transport-CpRe7zgd.mjs';
|
|
2
|
+
export { a as PLATFORM_STREAM_IDLE_MS, b as PLATFORM_TIMEOUT_DEFAULT_MS, c as PLATFORM_TIMEOUT_ENV, d as PlatformEndpoint, f as PlatformReply, g as PlatformSendOptions, h as PlatformStream, i as PlatformStreamOptions, P as PlatformTransport, T as TransportCause, U as UnreachableError, p as platformAuthorization, j as platformTimeoutMs } from '../transport-CpRe7zgd.mjs';
|
|
3
|
+
export { A as ApiError, i as invalidFields, p as parseErrorBody } from '../apiError-DHpfbmdx.mjs';
|
|
4
|
+
import { d as MediaUploader } from '../media-CQUC7TkS.mjs';
|
|
5
|
+
|
|
6
|
+
declare const SECRET_KEY: RegExp;
|
|
7
|
+
/** What of an action's arguments may leave the process. Selectors, paths and
|
|
8
|
+
* keys are what a reviewer needs; anything keyed like a credential, or typed
|
|
9
|
+
* into a field whose selector names one, or shaped like a known key, is
|
|
10
|
+
* replaced. Strings are capped, nested values dropped. Twin of
|
|
11
|
+
* `credential_field.redact_action_args`. */
|
|
12
|
+
declare function redactActionArgs(action: string, args: Record<string, unknown>): Record<string, unknown>;
|
|
3
13
|
|
|
4
14
|
/**
|
|
5
15
|
* A HOSTED BROWSER THAT COMES BACK. A World Host session's browser is a pool
|
|
@@ -49,7 +59,15 @@ declare class SecretScrubber {
|
|
|
49
59
|
private readonly secrets;
|
|
50
60
|
constructor(secrets: readonly (string | null | undefined)[]);
|
|
51
61
|
scrub(text: string): string;
|
|
62
|
+
/** Scrub `error` and the errors it was raised from, in place: the message,
|
|
63
|
+
* the stack and every other own text property, Playwright's `log` call log
|
|
64
|
+
* included. */
|
|
65
|
+
scrubError(error: unknown): void;
|
|
52
66
|
}
|
|
67
|
+
/** Apply `scrub` to `error` and the errors it was raised from, in place: the
|
|
68
|
+
* message, the stack and every other own text property, Playwright's `log`
|
|
69
|
+
* call log included. Twin of `world_browser_reconnect.scrub_error`. */
|
|
70
|
+
declare function scrubError(error: unknown, scrub: (text: string) => string): void;
|
|
53
71
|
/** A mutating action (click, type, press, back, scroll) lost its browser.
|
|
54
72
|
* The browser was repaired and the page reopened at `restoredUrl`, but the
|
|
55
73
|
* action is NOT replayed: its input may already have reached the world.
|
|
@@ -94,1833 +112,1812 @@ declare class BrowserReconnector {
|
|
|
94
112
|
}
|
|
95
113
|
|
|
96
114
|
/**
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
*
|
|
115
|
+
* A BROWSER ON A WORLD'S UI — the computer-use half of a live session.
|
|
116
|
+
*
|
|
117
|
+
* A session answers on SURFACES. `tools` is always there (the world's own
|
|
118
|
+
* operations over the rendezvous). An api-type world may also answer on
|
|
119
|
+
* `api` (the service itself), `ui` (its dashboard, over the same state) and
|
|
120
|
+
* `browser` — a headless Chromium the platform runs NEXT TO that UI, which
|
|
121
|
+
* an agent drives through Playwright. This file is the TS client for the
|
|
122
|
+
* last two, call for call with `gatewaysdk/world_browser.py`.
|
|
123
|
+
*
|
|
124
|
+
* const s = await openSession("payments-like", "refund-dispute", {
|
|
125
|
+
* surfaces: ["ui", "browser"],
|
|
126
|
+
* });
|
|
127
|
+
* await s.ready();
|
|
128
|
+
* const b = await s.browser(); // hosted, next to the world
|
|
129
|
+
* await b.goto(); // the UI's entry page
|
|
130
|
+
* await b.click("text=Refund");
|
|
131
|
+
* const tools = computerUseToolkit(b); // the same actions as model tools
|
|
132
|
+
* await b.close();
|
|
133
|
+
*
|
|
134
|
+
* Playwright is an OPTIONAL peer: nothing here imports it until a browser is
|
|
135
|
+
* opened, so sessions that never touch a UI never load it.
|
|
136
|
+
*
|
|
137
|
+
* MODES. `hosted` connects to the session's own browser (a Playwright server
|
|
138
|
+
* the pod exposes over an authenticated websocket). `local` launches Chromium
|
|
139
|
+
* on this machine and points it at the UI — a laptop against a hosted twin,
|
|
140
|
+
* or a test. `auto` prefers hosted. Asking for a mode the session cannot
|
|
141
|
+
* serve throws `WorldSurfaceUnavailable`; there is no silent fallback to a
|
|
142
|
+
* browser other than the one the episode is judged on.
|
|
143
|
+
*
|
|
144
|
+
* OBSERVABILITY. Every action a `WorldBrowser` takes (goto, click, type,
|
|
145
|
+
* press, scroll, back) is reported to the platform as one event — what was
|
|
146
|
+
* done, whether it worked, where the page ended up, and a JPEG of the screen
|
|
147
|
+
* after — through a `BrowserActionRecorder`. Reporting is fire-and-forget
|
|
148
|
+
* and never fails the action; the platform renders it as the session's
|
|
149
|
+
* browser timeline. Text typed into secret-looking fields is redacted before
|
|
150
|
+
* it leaves the process.
|
|
151
|
+
*
|
|
152
|
+
* RECONNECT. A World Host browser on the `standard` tier can be reclaimed
|
|
153
|
+
* mid-session. When an action fails because the browser or its connection is
|
|
154
|
+
* gone, a hosted `cdp` browser asks the platform to repair it, reconnects to
|
|
155
|
+
* the same address and reopens the page it was on (see `browserReconnect.ts`).
|
|
156
|
+
* A read or a `goto` then runs once more; a click, type, press, back or scroll
|
|
157
|
+
* is NOT replayed — its input may already have reached the world — and throws
|
|
158
|
+
* `BrowserReconnected` so the agent looks at the page again. Local and
|
|
159
|
+
* `playwright`-protocol browsers never reconnect.
|
|
100
160
|
*/
|
|
101
|
-
declare const
|
|
102
|
-
type
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
* `
|
|
110
|
-
*
|
|
111
|
-
type
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
region?: [number, number, number, number];
|
|
125
|
-
direction?: "back" | "forward";
|
|
161
|
+
declare const SURFACE_KINDS: readonly ["tools", "api", "ui", "browser"];
|
|
162
|
+
type WorldSurfaceKind = (typeof SURFACE_KINDS)[number];
|
|
163
|
+
|
|
164
|
+
/** The platform's own header for a session's token, which a World Host takes on
|
|
165
|
+
* every world whatever its vendor's auth; no vendor's client sends it. */
|
|
166
|
+
declare const PLATFORM_SESSION_HEADER = "X-World-Session";
|
|
167
|
+
declare const SESSION_AUTH_MODES: readonly ["vendor", "open"];
|
|
168
|
+
/** `open`: the session asks for no credential, reached on its capability
|
|
169
|
+
* hostname alone; `vendor`: the session's token, the way the world's `[auth]`
|
|
170
|
+
* says its vendor takes a key. Unset, the world's `[auth] mode`. */
|
|
171
|
+
type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];
|
|
172
|
+
declare function assertSessionAuthMode(value: unknown): asserts value is SessionAuthMode;
|
|
173
|
+
/** Capacity behind a World Host session's browser. `standard` runs on spot
|
|
174
|
+
* capacity first (about half the price) and may be reclaimed with two
|
|
175
|
+
* minutes' notice, ending the browser but never the world; `premium` is
|
|
176
|
+
* on-demand and never spot-reclaimed. Unset, the organization's default applies. */
|
|
177
|
+
declare const BROWSER_TIERS: readonly ["standard", "premium"];
|
|
178
|
+
type BrowserTier = (typeof BROWSER_TIERS)[number];
|
|
179
|
+
/** Refuse a tier the platform does not know, before any request is sent. */
|
|
180
|
+
declare function assertBrowserTier(value: unknown): asserts value is BrowserTier;
|
|
181
|
+
declare const DEFAULT_VIEWPORT: {
|
|
182
|
+
width: number;
|
|
183
|
+
height: number;
|
|
126
184
|
};
|
|
127
|
-
declare
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
185
|
+
declare const EVENT_BATCH_SIZE = 10;
|
|
186
|
+
declare const EVENT_FLUSH_INTERVAL_MS = 1000;
|
|
187
|
+
declare const EVENT_MAX_RETRIES = 3;
|
|
188
|
+
/** What a call that lost its browser does once the browser is back: a read or
|
|
189
|
+
* a navigation runs again (`retry`); an action that may already have reached
|
|
190
|
+
* the world is not replayed, and the agent is told (`report`). */
|
|
191
|
+
type OnBrowserLoss = "retry" | "report";
|
|
192
|
+
/** The `surfaces` block of a session descriptor, as the platform sends it. */
|
|
193
|
+
type SessionSurfaces = {
|
|
194
|
+
tools: {
|
|
195
|
+
kind: "rendezvous";
|
|
196
|
+
};
|
|
197
|
+
api?: {
|
|
198
|
+
url: string;
|
|
199
|
+
/** Per-session credential of a World Host session: send it in the
|
|
200
|
+
* platform's `X-World-Session` header (`apiHeaders()`), or the way the
|
|
201
|
+
* world's `[auth]` says its vendor takes a key. Absent when the world
|
|
202
|
+
* itself answers with its declared auth (a pod or a customer-hosted twin),
|
|
203
|
+
* and for an open session, whose url is its secret. */
|
|
204
|
+
token?: string;
|
|
205
|
+
/** `open`: `url` is the session's capability hostname; send no credential. */
|
|
206
|
+
auth?: "open";
|
|
207
|
+
};
|
|
208
|
+
ui?: {
|
|
209
|
+
url: string;
|
|
210
|
+
entry: string;
|
|
211
|
+
/** Same-origin prefix the UI proxies to the world API, e.g. `/__world-api`;
|
|
212
|
+
* null when the UI only reaches the API server-side. */
|
|
213
|
+
apiPath?: string | null;
|
|
214
|
+
/** Per-session credential of a World Host UI. A browser navigation cannot
|
|
215
|
+
* carry a header, so the first page load presents it once as `?token=`
|
|
216
|
+
* and the host answers with an HttpOnly cookie. Absent for pod UIs and
|
|
217
|
+
* open sessions. */
|
|
218
|
+
token?: string;
|
|
219
|
+
auth?: "open";
|
|
220
|
+
};
|
|
221
|
+
browser?: {
|
|
222
|
+
wsUrl: string;
|
|
223
|
+
/** `cdp`: the platform's Chromium relay (any number of agents share one
|
|
224
|
+
* browser, each in its own context). `playwright`: a `run-server` endpoint. */
|
|
225
|
+
protocol: "cdp" | "playwright";
|
|
226
|
+
viewport: {
|
|
227
|
+
width: number;
|
|
228
|
+
height: number;
|
|
229
|
+
};
|
|
230
|
+
/** The capacity tier the browser runs on; present for World Host sessions. */
|
|
231
|
+
tier?: BrowserTier;
|
|
232
|
+
};
|
|
141
233
|
};
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
* provider's image limits (or the caller) ask for a smaller display,
|
|
146
|
-
* screenshots are captured downscaled and coordinates mapped back.
|
|
147
|
-
* Twin of `gatewaysdk/native_computer/display.py`.
|
|
148
|
-
*/
|
|
149
|
-
type Fits = (width: number, height: number) => boolean;
|
|
150
|
-
declare class Display {
|
|
151
|
-
readonly width: number;
|
|
152
|
-
readonly height: number;
|
|
153
|
-
readonly viewportWidth: number;
|
|
154
|
-
readonly viewportHeight: number;
|
|
155
|
-
constructor(width: number, height: number, viewportWidth: number, viewportHeight: number);
|
|
156
|
-
/** `size` when the caller names one; otherwise the largest downscale of the
|
|
157
|
-
* viewport (at most 1:1) that `fits` the provider's limits. */
|
|
158
|
-
static forViewport(viewport: {
|
|
159
|
-
width: number;
|
|
160
|
-
height: number;
|
|
161
|
-
}, size?: [number, number], fits?: Fits): Display;
|
|
162
|
-
/** A caller's display keeps the viewport's shape: screenshots are scaled
|
|
163
|
-
* uniformly, so another aspect ratio would map clicks off the image. */
|
|
164
|
-
private static sized;
|
|
165
|
-
get scaled(): boolean;
|
|
166
|
-
get scale(): number;
|
|
167
|
-
toPage(x: number, y: number): [number, number];
|
|
234
|
+
declare class WorldSurfaceUnavailable extends Error {
|
|
235
|
+
readonly surface: WorldSurfaceKind;
|
|
236
|
+
constructor(surface: WorldSurfaceKind, reason: string);
|
|
168
237
|
}
|
|
169
|
-
|
|
170
|
-
/**
|
|
171
|
-
*
|
|
172
|
-
*
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
*/
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
}
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
238
|
+
declare function surfaceKinds(s: SessionSurfaces): WorldSurfaceKind[];
|
|
239
|
+
/** The URL of `path` on a UI surface, carrying the session token when the
|
|
240
|
+
* surface has one. `path` may already have a query string; the token is
|
|
241
|
+
* appended to it. */
|
|
242
|
+
declare function uiUrl(ui: NonNullable<SessionSurfaces["ui"]>, path: string): string;
|
|
243
|
+
declare function uiEntryUrl(ui: NonNullable<SessionSurfaces["ui"]>): string;
|
|
244
|
+
/** `url` without its `token` query parameter: what may be logged or shown. */
|
|
245
|
+
declare function withoutUiToken(url: string): string;
|
|
246
|
+
/** The slice of a Playwright `Page` this module drives. */
|
|
247
|
+
type BrowserPage = {
|
|
248
|
+
url(): string;
|
|
249
|
+
goto(url: string, opts?: {
|
|
250
|
+
waitUntil?: "load";
|
|
251
|
+
}): Promise<unknown>;
|
|
252
|
+
click(selector: string, opts?: {
|
|
253
|
+
timeout?: number;
|
|
254
|
+
}): Promise<void>;
|
|
255
|
+
fill(selector: string, value: string, opts?: {
|
|
256
|
+
timeout?: number;
|
|
257
|
+
}): Promise<void>;
|
|
258
|
+
screenshot(opts?: {
|
|
259
|
+
type?: "png" | "jpeg";
|
|
260
|
+
quality?: number;
|
|
261
|
+
fullPage?: boolean;
|
|
262
|
+
}): Promise<Buffer>;
|
|
263
|
+
innerText(selector: string): Promise<string>;
|
|
264
|
+
ariaSnapshot?(opts: {
|
|
265
|
+
mode: "ai";
|
|
266
|
+
}): Promise<string>;
|
|
267
|
+
locator(selector: string): {
|
|
268
|
+
click(opts: {
|
|
269
|
+
trial: true;
|
|
198
270
|
}): Promise<void>;
|
|
199
|
-
|
|
271
|
+
evaluateAll(pageFunction: (elements: unknown[]) => unknown): Promise<unknown>;
|
|
272
|
+
evaluate(pageFunction: (element: unknown) => unknown, arg?: unknown, opts?: {
|
|
273
|
+
timeout?: number;
|
|
274
|
+
}): Promise<unknown>;
|
|
200
275
|
};
|
|
276
|
+
content(): Promise<string>;
|
|
277
|
+
goBack(opts?: {
|
|
278
|
+
waitUntil?: "load";
|
|
279
|
+
}): Promise<unknown>;
|
|
280
|
+
waitForLoadState(state?: "load"): Promise<void>;
|
|
281
|
+
waitForTimeout(ms: number): Promise<void>;
|
|
282
|
+
on(event: "request" | "requestfinished" | "requestfailed", handler: (request: unknown) => void): unknown;
|
|
283
|
+
title(): Promise<string>;
|
|
201
284
|
keyboard: {
|
|
202
|
-
down(key: string): Promise<void>;
|
|
203
|
-
up(key: string): Promise<void>;
|
|
204
285
|
press(key: string): Promise<void>;
|
|
205
|
-
type(text: string): Promise<void>;
|
|
206
286
|
};
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
}): Promise<Buffer>;
|
|
210
|
-
waitForTimeout(ms: number): Promise<void>;
|
|
211
|
-
goBack(): Promise<unknown>;
|
|
212
|
-
goForward(): Promise<unknown>;
|
|
213
|
-
evaluate(expression: string): Promise<unknown>;
|
|
214
|
-
context(): {
|
|
215
|
-
newCDPSession(page: unknown): Promise<CdpSession>;
|
|
287
|
+
mouse: {
|
|
288
|
+
wheel(dx: number, dy: number): Promise<void>;
|
|
216
289
|
};
|
|
217
290
|
};
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
291
|
+
type BrowserMode = "auto" | "hosted" | "local";
|
|
292
|
+
/** One browser action as the platform ingests it
|
|
293
|
+
* (`POST /world-sessions/{id}/browser-events`). */
|
|
294
|
+
type BrowserActionEvent = {
|
|
295
|
+
agentId: string;
|
|
296
|
+
seq: number;
|
|
297
|
+
ts: string;
|
|
298
|
+
action: string;
|
|
299
|
+
args: Record<string, unknown>;
|
|
300
|
+
ok: boolean;
|
|
301
|
+
error: string | null;
|
|
302
|
+
durationMs: number;
|
|
303
|
+
url: string | null;
|
|
304
|
+
title: string | null;
|
|
305
|
+
mode: Exclude<BrowserMode, "auto">;
|
|
306
|
+
viewport: {
|
|
222
307
|
width: number;
|
|
223
308
|
height: number;
|
|
224
309
|
};
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
scrub(text: string): string;
|
|
228
|
-
};
|
|
229
|
-
declare class Screen {
|
|
230
|
-
readonly browser: ScreenBrowser;
|
|
231
|
-
readonly display: Display;
|
|
232
|
-
cursor: Point;
|
|
233
|
-
private pixelRatio;
|
|
234
|
-
private readonly handlers;
|
|
235
|
-
constructor(browser: ScreenBrowser, display: Display);
|
|
236
|
-
/** The live page (a new object after a reconnect), as pixel-level Playwright. */
|
|
237
|
-
get page(): NativePage;
|
|
238
|
-
run(action: ComputerAction): Promise<ActionResult>;
|
|
239
|
-
/** A PNG of the viewport at the model's display size. */
|
|
240
|
-
screenshot(): Promise<Buffer>;
|
|
241
|
-
/** Whether keystrokes go to a credential field (a password input, or one
|
|
242
|
-
* named like a token, key or PIN), looking through shadow roots and
|
|
243
|
-
* same-origin frames. An unreadable page, a cross-origin frame or a focus
|
|
244
|
-
* that is not a text field (a closed shadow root's host) counts as one. */
|
|
245
|
-
focusedFieldIsSecret(): Promise<boolean>;
|
|
246
|
-
/** CDP renders a clip at the page's device pixel ratio as well as its
|
|
247
|
-
* `scale` (a Retina host doubles it), so a capture of the wrong width
|
|
248
|
-
* measures that ratio and is taken once more, corrected. */
|
|
249
|
-
private capture;
|
|
250
|
-
private cdpCapture;
|
|
251
|
-
private point;
|
|
252
|
-
private moveTo;
|
|
253
|
-
private held;
|
|
254
|
-
private zoom;
|
|
255
|
-
private click;
|
|
256
|
-
private drag;
|
|
257
|
-
private scroll;
|
|
258
|
-
private key;
|
|
259
|
-
}
|
|
260
|
-
|
|
261
|
-
declare const SPAN_PREFIX = "computer.";
|
|
262
|
-
declare class ActionTracer {
|
|
263
|
-
readonly media: MediaUploader | null;
|
|
264
|
-
private readonly warn;
|
|
265
|
-
private failures;
|
|
266
|
-
private warned;
|
|
267
|
-
constructor(media: MediaUploader | null, warn?: (message: string) => void);
|
|
268
|
-
static fromEnv(): ActionTracer;
|
|
269
|
-
/** `args` are already redacted. A failure's status goes through `scrub`:
|
|
270
|
-
* browser errors quote the session's ws URL and UI token. */
|
|
271
|
-
span(action: ComputerAction, args: Record<string, unknown>, run: () => Promise<ActionResult>, capture: () => Promise<Buffer>, scrub: (text: string) => string): Promise<ActionResult>;
|
|
272
|
-
private finish;
|
|
273
|
-
private screenshot;
|
|
274
|
-
private reference;
|
|
275
|
-
private failed;
|
|
276
|
-
}
|
|
277
|
-
|
|
278
|
-
type NativeComputerOptions = {
|
|
279
|
-
/** The pixel size the model sees; default the viewport, or the largest
|
|
280
|
-
* downscale that fits the provider's image limits. */
|
|
281
|
-
display?: [number, number];
|
|
282
|
-
/** Records one span per action with the screen after it; default uploads
|
|
283
|
-
* screenshots with the `GATEWAY_*` keys when tracing is initialized. */
|
|
284
|
-
tracer?: ActionTracer;
|
|
285
|
-
};
|
|
286
|
-
/** The major version of the `ai` package the tools are handed to. */
|
|
287
|
-
type AiSdkMajor = 6 | 7;
|
|
288
|
-
type AiSdkOptions<V extends AiSdkMajor = 6> = {
|
|
289
|
-
/** The Anthropic kinds' screenshot part. Default 6: `image-data`, which
|
|
290
|
-
* AI SDK 7 still accepts with a deprecation warning. 7: the `file` part with
|
|
291
|
-
* `{ type: "data", data }`, which AI SDK 6 does not accept. The OpenAI kinds
|
|
292
|
-
* return the provider's own `computer_screenshot` output and ignore it. */
|
|
293
|
-
version?: V;
|
|
310
|
+
/** base64 JPEG of the screen after the action; null if it could not be taken. */
|
|
311
|
+
screenshot: string | null;
|
|
294
312
|
};
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
declare
|
|
299
|
-
readonly browser: ScreenBrowser;
|
|
300
|
-
private static readonly kinds;
|
|
301
|
-
readonly display: Display;
|
|
302
|
-
readonly screen: Screen;
|
|
303
|
-
readonly tracer: ActionTracer;
|
|
304
|
-
private queue;
|
|
305
|
-
static register(provider: string, kind: Kind): void;
|
|
306
|
-
static get providers(): string[];
|
|
307
|
-
static forProvider(provider: string, browser: ScreenBrowser, options?: NativeComputerOptions): NativeComputer;
|
|
308
|
-
constructor(browser: ScreenBrowser, options?: NativeComputerOptions);
|
|
309
|
-
/** Whether a screenshot of this size is within the provider's limits. */
|
|
310
|
-
static fits(_width: number, _height: number): boolean;
|
|
311
|
-
/** The tool definition to send the model. */
|
|
312
|
-
abstract tool(): Record<string, unknown>;
|
|
313
|
-
/** One action in the provider's own shape, as a `ComputerAction`. */
|
|
314
|
-
abstract parse(raw: unknown): ComputerAction;
|
|
315
|
-
/** The options to spread into the Vercel AI SDK's provider-defined computer
|
|
316
|
-
* tool (`execute` and its companions), backed by this computer. */
|
|
317
|
-
abstract aiSdk(options?: AiSdkOptions<AiSdkMajor>): object;
|
|
318
|
-
/** Run one provider-shaped action (an OpenAI action object, or an Anthropic
|
|
319
|
-
* `{ action: "left_click", ... }` input) and return what it produced: the
|
|
320
|
-
* door for any agent framework that hands actions over one at a time. */
|
|
321
|
-
executeAction(raw: unknown): Promise<ActionResult>;
|
|
322
|
-
/** Run one action on the page: reported on the session's browser timeline
|
|
323
|
-
* and, when tracing is on, as a span with the screen after. */
|
|
324
|
-
perform(action: ComputerAction): Promise<ActionResult>;
|
|
325
|
-
performAll(actions: readonly ComputerAction[]): Promise<ActionResult[]>;
|
|
326
|
-
/** The screen as the model sees it, as a traced `screenshot` action. */
|
|
327
|
-
screenshot(): Promise<Buffer>;
|
|
328
|
-
/** Run `fn` after every earlier call made through here: the AI SDK starts a
|
|
329
|
-
* step's tool calls concurrently, but one screen takes one action at a time. */
|
|
330
|
-
protected serial<T>(fn: () => Promise<T>): Promise<T>;
|
|
331
|
-
private runOnScreen;
|
|
332
|
-
private onLoss;
|
|
333
|
-
}
|
|
334
|
-
|
|
313
|
+
/** The secret label of an open session's capability hostname in `url`
|
|
314
|
+
* (`o-<sid>-<label>[-api].<domain>`), else null: a credential, scrubbed from
|
|
315
|
+
* everything a browser records. Twin of the Python `capability_label`. */
|
|
316
|
+
declare function capabilityLabel(url: string | null | undefined): string | null;
|
|
335
317
|
/**
|
|
336
|
-
*
|
|
337
|
-
*
|
|
338
|
-
*
|
|
339
|
-
*
|
|
318
|
+
* Ships browser action events to the platform, off the action's hot path.
|
|
319
|
+
*
|
|
320
|
+
* `post` receives a batch of events (the request body's `events`). Events
|
|
321
|
+
* are numbered here, so ordering survives batching and retries — the
|
|
322
|
+
* platform dedups on `(agentId, seq)`. A batch that keeps failing is dropped
|
|
323
|
+
* with a warning: telemetry must never stall or fail the agent.
|
|
324
|
+
*
|
|
325
|
+
* Numbering is durable across recorders: `nextSeq()` hands out a position
|
|
326
|
+
* within this recorder, and the first send adds the base `resumeFrom`
|
|
327
|
+
* reports — the platform's next free seq for this agent — so an agent id
|
|
328
|
+
* reopened in a later process appends to its timeline instead of colliding
|
|
329
|
+
* with (and being deduplicated against) what it already recorded. The base
|
|
330
|
+
* is fixed once resolved, which keeps retries idempotent.
|
|
340
331
|
*/
|
|
341
|
-
declare
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
private
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
332
|
+
declare class BrowserActionRecorder {
|
|
333
|
+
private readonly post;
|
|
334
|
+
readonly agentId: string;
|
|
335
|
+
private readonly opts;
|
|
336
|
+
private seq;
|
|
337
|
+
private base;
|
|
338
|
+
private queue;
|
|
339
|
+
private timer;
|
|
340
|
+
private inflight;
|
|
341
|
+
sent: number;
|
|
342
|
+
dropped: number;
|
|
343
|
+
constructor(post: (events: BrowserActionEvent[]) => Promise<void>, agentId: string, opts?: {
|
|
344
|
+
/** The platform's next free seq for `agentId`; 0 when not given. */
|
|
345
|
+
resumeFrom?: () => Promise<number>;
|
|
346
|
+
batchSize?: number;
|
|
347
|
+
flushIntervalMs?: number;
|
|
348
|
+
maxRetries?: number;
|
|
349
|
+
sleep?: (ms: number) => Promise<void>;
|
|
350
|
+
warn?: (message: string) => void;
|
|
351
|
+
});
|
|
352
|
+
/** This recorder's next position; the wire seq is `resumeFrom() + this`. */
|
|
353
|
+
nextSeq(): number;
|
|
354
|
+
private resolveBase;
|
|
355
|
+
record(event: BrowserActionEvent): void;
|
|
356
|
+
/** Resolve once everything recorded so far has been posted (or dropped). */
|
|
357
|
+
flush(): Promise<void>;
|
|
358
|
+
close(): Promise<void>;
|
|
359
|
+
private drain;
|
|
360
|
+
private send;
|
|
354
361
|
}
|
|
355
|
-
|
|
356
362
|
/**
|
|
357
|
-
*
|
|
358
|
-
*
|
|
363
|
+
* One Playwright page on the session's UI. Thin on purpose — `page` is the
|
|
364
|
+
* real Playwright page for anything this wrapper does not cover.
|
|
359
365
|
*/
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
type ImageParts = {
|
|
368
|
-
6: {
|
|
369
|
-
type: "image-data";
|
|
370
|
-
data: string;
|
|
371
|
-
mediaType: "image/png";
|
|
372
|
-
};
|
|
373
|
-
7: {
|
|
374
|
-
type: "file";
|
|
375
|
-
mediaType: "image/png";
|
|
376
|
-
data: {
|
|
377
|
-
type: "data";
|
|
378
|
-
data: string;
|
|
379
|
-
};
|
|
380
|
-
};
|
|
381
|
-
};
|
|
382
|
-
type AiSdkImagePart<V extends AiSdkMajor = AiSdkMajor> = ImageParts[V];
|
|
383
|
-
type AiSdkModelOutput<V extends AiSdkMajor = 6> = {
|
|
384
|
-
type: "text";
|
|
385
|
-
value: string;
|
|
386
|
-
} | {
|
|
387
|
-
type: "content";
|
|
388
|
-
value: AiSdkImagePart<V>[];
|
|
389
|
-
};
|
|
390
|
-
type AnthropicContent = {
|
|
391
|
-
type: "text";
|
|
392
|
-
text: string;
|
|
393
|
-
} | {
|
|
394
|
-
type: "image";
|
|
395
|
-
source: {
|
|
396
|
-
type: "base64";
|
|
397
|
-
media_type: "image/png";
|
|
398
|
-
data: string;
|
|
366
|
+
declare class WorldBrowser {
|
|
367
|
+
readonly ui: SessionSurfaces["ui"] | undefined;
|
|
368
|
+
readonly mode: Exclude<BrowserMode, "auto">;
|
|
369
|
+
private readonly teardown;
|
|
370
|
+
readonly viewport: {
|
|
371
|
+
width: number;
|
|
372
|
+
height: number;
|
|
399
373
|
};
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
/**
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
/**
|
|
431
|
-
*
|
|
432
|
-
*
|
|
433
|
-
*
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
374
|
+
readonly recorder: BrowserActionRecorder | null;
|
|
375
|
+
private readonly reconnector;
|
|
376
|
+
/** Takes session credentials out of every error this browser records. */
|
|
377
|
+
private readonly scrubber;
|
|
378
|
+
private typed;
|
|
379
|
+
private typedText;
|
|
380
|
+
private current;
|
|
381
|
+
private inflight;
|
|
382
|
+
private lastNetwork;
|
|
383
|
+
/** Where the page last was after an action, token stripped: what a
|
|
384
|
+
* reconnect reopens. Null until the page has left `about:blank`. */
|
|
385
|
+
private lastUrl;
|
|
386
|
+
constructor(page: BrowserPage, ui: SessionSurfaces["ui"] | undefined, mode: Exclude<BrowserMode, "auto">, teardown: () => Promise<void>, viewport?: {
|
|
387
|
+
width: number;
|
|
388
|
+
height: number;
|
|
389
|
+
}, recorder?: BrowserActionRecorder | null, reconnector?: BrowserReconnector | null,
|
|
390
|
+
/** Takes session credentials out of every error this browser records. */
|
|
391
|
+
scrubber?: SecretScrubber);
|
|
392
|
+
/** The live Playwright page; a new object after a reconnect. */
|
|
393
|
+
get page(): BrowserPage;
|
|
394
|
+
get agentId(): string | null;
|
|
395
|
+
/** `text` with this session's credentials (UI token, browser address) and
|
|
396
|
+
* the credentials typed into it removed. */
|
|
397
|
+
scrub(text: string): string;
|
|
398
|
+
/** `text` with this session's credentials removed and nothing else
|
|
399
|
+
* changed: for text that is compared and never leaves the process. */
|
|
400
|
+
scrubSession(text: string): string;
|
|
401
|
+
/** Every credential typed into this browser by `type`. */
|
|
402
|
+
get typedCredentials(): string[];
|
|
403
|
+
private watchNetwork;
|
|
404
|
+
/** Run `fn` against the page. If it fails because the browser is gone,
|
|
405
|
+
* recover; then `retry` runs it ONCE more and `report` throws
|
|
406
|
+
* `BrowserReconnected` instead of replaying it. Any other error, and a
|
|
407
|
+
* second loss during the retry, propagate unchanged. */
|
|
408
|
+
private resilient;
|
|
409
|
+
private remember;
|
|
410
|
+
/** The page's URL less its token; null while it is blank. */
|
|
411
|
+
private openedUrl;
|
|
412
|
+
private recover;
|
|
413
|
+
/** Take over a new connection's page and reopen the page the agent was on
|
|
414
|
+
* (`openBrowser` owns the connection itself). A new browser has no session
|
|
415
|
+
* cookie, so a World Host UI is first loaded with its token, exactly as
|
|
416
|
+
* `goto()` loads the entry page. */
|
|
417
|
+
private adopt;
|
|
418
|
+
/** Run one action and report it: the event carries what was asked,
|
|
419
|
+
* whether it worked, and the screen after — for failures too, so a
|
|
420
|
+
* reviewer sees what the agent saw when the selector did not match. The
|
|
421
|
+
* error it throws keeps no session credential and no credential typed into
|
|
422
|
+
* this browser, which Playwright's call log would quote. */
|
|
423
|
+
act<T>(action: string, args: Record<string, unknown>, fn: () => Promise<T>, onLoss?: OnBrowserLoss): Promise<T>;
|
|
424
|
+
/** One event on the recorder, if there is one; `failure` null means ok. */
|
|
425
|
+
private report;
|
|
426
|
+
private observeForEvent;
|
|
427
|
+
/** Open a UI path (`/customers`), a full URL, or — with no argument — the
|
|
428
|
+
* UI's declared entry page. */
|
|
429
|
+
goto(pathOrUrl?: string): Promise<string>;
|
|
430
|
+
back(): Promise<string>;
|
|
431
|
+
/** Wait for the page to finish reacting to an action. `load` alone is not
|
|
432
|
+
* enough for client-rendered UIs (React et al.): a click returns before the
|
|
433
|
+
* fetch that re-renders the page, so an agent would read stale text.
|
|
434
|
+
* Playwright's `networkidle` is per navigation and resolves at once after
|
|
435
|
+
* the first one, so this tracks requests itself: done when nothing is in
|
|
436
|
+
* flight and the network has been quiet for `SETTLE_QUIET_MS`, bounded so
|
|
437
|
+
* long-polling UIs cannot hang us. */
|
|
438
|
+
settle(): Promise<void>;
|
|
439
|
+
click(selector: string, opts?: {
|
|
440
|
+
timeoutMs?: number;
|
|
441
|
+
}): Promise<void>;
|
|
442
|
+
/** Replace the field's value with `text`. `opts.credential` is whether the
|
|
443
|
+
* field takes one, when the caller already probed it; a credential is
|
|
444
|
+
* withheld from the event and from any error. */
|
|
445
|
+
type(selector: string, text: string, opts?: {
|
|
446
|
+
timeoutMs?: number;
|
|
447
|
+
credential?: boolean;
|
|
448
|
+
}): Promise<void>;
|
|
449
|
+
/** `DESCRIBE_FIELD_JS` of the element `selector` finds, or `UNREADABLE`. */
|
|
450
|
+
describeField(selector: string): Promise<string>;
|
|
451
|
+
/** Whether the field `selector` finds takes a credential; one it cannot
|
|
452
|
+
* read counts. */
|
|
453
|
+
credentialField(selector: string): Promise<boolean>;
|
|
454
|
+
/** What the field `selector` finds holds (`FIELD_VALUE_JS`), or null when
|
|
455
|
+
* it cannot be read. */
|
|
456
|
+
fieldValue(selector: string): Promise<string | null>;
|
|
457
|
+
/** Take this session's credentials out of `error` and the errors it came
|
|
458
|
+
* from, in place. */
|
|
459
|
+
scrubError(error: unknown): void;
|
|
460
|
+
press(key: string): Promise<void>;
|
|
461
|
+
scroll(dy: number): Promise<void>;
|
|
462
|
+
screenshot(fullPage?: boolean): Promise<Buffer>;
|
|
463
|
+
screenshotBase64(fullPage?: boolean): Promise<string>;
|
|
464
|
+
/** The visible text of `selector`'s element, without what any field on the
|
|
465
|
+
* page that takes a credential holds. */
|
|
466
|
+
text(selector?: string): Promise<string>;
|
|
467
|
+
/** What each field on the page that takes a credential holds: an input's
|
|
468
|
+
* or textarea's value, a select's chosen option, a contenteditable's text. */
|
|
469
|
+
credentialTexts(): Promise<string[]>;
|
|
470
|
+
/** Wait until the element `selector` finds could be clicked, without
|
|
471
|
+
* clicking it. */
|
|
472
|
+
actionable(selector: string): Promise<void>;
|
|
473
|
+
ariaSnapshot(): Promise<string>;
|
|
474
|
+
html(): Promise<string>;
|
|
475
|
+
get url(): string;
|
|
476
|
+
title(): Promise<string>;
|
|
477
|
+
close(): Promise<void>;
|
|
478
|
+
}
|
|
479
|
+
/** The Playwright entry points this module needs, so tests can inject a fake. */
|
|
480
|
+
type PlaywrightLike = {
|
|
481
|
+
chromium: {
|
|
482
|
+
connect(wsEndpoint: string): Promise<PlaywrightBrowserLike>;
|
|
483
|
+
connectOverCDP(endpointURL: string): Promise<PlaywrightBrowserLike>;
|
|
484
|
+
launch(opts?: {
|
|
485
|
+
headless?: boolean;
|
|
486
|
+
}): Promise<PlaywrightBrowserLike>;
|
|
443
487
|
};
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
488
|
+
};
|
|
489
|
+
type PlaywrightBrowserLike = {
|
|
490
|
+
newContext(opts?: {
|
|
491
|
+
viewport?: {
|
|
492
|
+
width: number;
|
|
493
|
+
height: number;
|
|
494
|
+
};
|
|
495
|
+
}): Promise<{
|
|
496
|
+
newPage(): Promise<BrowserPage>;
|
|
497
|
+
close(): Promise<void>;
|
|
498
|
+
}>;
|
|
499
|
+
close(): Promise<void>;
|
|
500
|
+
};
|
|
501
|
+
declare function resolveBrowserMode(surfaces: SessionSurfaces, mode: BrowserMode): Exclude<BrowserMode, "auto">;
|
|
502
|
+
/** Open a browser on the session's UI in `hosted`, `local` or `auto` mode. */
|
|
503
|
+
declare function openBrowser(surfaces: SessionSurfaces, opts?: {
|
|
504
|
+
mode?: BrowserMode;
|
|
505
|
+
headless?: boolean;
|
|
506
|
+
playwright?: PlaywrightLike;
|
|
507
|
+
recorder?: BrowserActionRecorder | null;
|
|
508
|
+
/** The session's repair call (`session.repairBrowser`). Given, a hosted
|
|
509
|
+
* `cdp` browser reconnects on its own when the browser is lost. */
|
|
510
|
+
repair?: () => Promise<RepairAnswer>;
|
|
511
|
+
}): Promise<WorldBrowser>;
|
|
512
|
+
|
|
513
|
+
/**
|
|
514
|
+
* The provider-neutral action vocabulary every native computer executes.
|
|
515
|
+
* Coordinates are in the MODEL's pixel space; the screen maps them to the page.
|
|
516
|
+
* Twin of `gatewaysdk/native_computer/actions.py`.
|
|
517
|
+
*/
|
|
518
|
+
declare const ACTION_NAMES: readonly ["screenshot", "zoom", "click", "move", "mouse_down", "mouse_up", "drag", "scroll", "type", "key", "hold_key", "wait", "cursor_position", "history"];
|
|
519
|
+
type ActionName = (typeof ACTION_NAMES)[number];
|
|
520
|
+
type Point = [number, number];
|
|
521
|
+
type MouseButton = "left" | "right" | "middle";
|
|
522
|
+
/** Arguments by action:
|
|
523
|
+
* `click` x?, y?, button, count, modifiers · `move` x, y, modifiers? ·
|
|
524
|
+
* `mouse_down`/`mouse_up` button · `drag` path, modifiers ·
|
|
525
|
+
* `scroll` x?, y?, dx, dy, modifiers · `type` text · `key` keys, repeat ·
|
|
526
|
+
* `hold_key` keys, seconds · `wait` seconds · `zoom` region ·
|
|
527
|
+
* `history` direction · `screenshot`/`cursor_position` none. */
|
|
528
|
+
type ActionArgs = {
|
|
529
|
+
x?: number;
|
|
530
|
+
y?: number;
|
|
531
|
+
button?: MouseButton;
|
|
532
|
+
count?: number;
|
|
533
|
+
modifiers?: string[];
|
|
534
|
+
path?: Point[];
|
|
535
|
+
dx?: number;
|
|
536
|
+
dy?: number;
|
|
537
|
+
text?: string;
|
|
538
|
+
keys?: string[];
|
|
539
|
+
repeat?: number;
|
|
540
|
+
seconds?: number;
|
|
541
|
+
region?: [number, number, number, number];
|
|
542
|
+
direction?: "back" | "forward";
|
|
543
|
+
};
|
|
544
|
+
declare class ComputerAction {
|
|
545
|
+
readonly name: ActionName;
|
|
546
|
+
readonly args: ActionArgs;
|
|
547
|
+
constructor(name: ActionName, args?: ActionArgs);
|
|
548
|
+
/** Flat arguments for the browser timeline and the trace: lists become
|
|
549
|
+
* `"x,y"` strings, and typed text is withheld when it went into a
|
|
550
|
+
* credential field. */
|
|
551
|
+
recordArgs(secretText: boolean): Record<string, unknown>;
|
|
453
552
|
}
|
|
454
|
-
/**
|
|
455
|
-
*
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
553
|
+
/** What an action gave back: a PNG (`screenshot`, `zoom`), a line of text
|
|
554
|
+
* (`cursor_position`), or neither. */
|
|
555
|
+
type ActionResult = {
|
|
556
|
+
image?: Buffer;
|
|
557
|
+
text?: string;
|
|
558
|
+
};
|
|
559
|
+
|
|
560
|
+
/**
|
|
561
|
+
* The model's pixel space versus the page's. Unscaled by default; when a
|
|
562
|
+
* provider's image limits (or the caller) ask for a smaller display,
|
|
563
|
+
* screenshots are captured downscaled and coordinates mapped back.
|
|
564
|
+
* Twin of `gatewaysdk/native_computer/display.py`.
|
|
565
|
+
*/
|
|
566
|
+
type Fits = (width: number, height: number) => boolean;
|
|
567
|
+
declare class Display {
|
|
568
|
+
readonly width: number;
|
|
569
|
+
readonly height: number;
|
|
570
|
+
readonly viewportWidth: number;
|
|
571
|
+
readonly viewportHeight: number;
|
|
572
|
+
constructor(width: number, height: number, viewportWidth: number, viewportHeight: number);
|
|
573
|
+
/** `size` when the caller names one; otherwise the largest downscale of the
|
|
574
|
+
* viewport (at most 1:1) that `fits` the provider's limits. */
|
|
575
|
+
static forViewport(viewport: {
|
|
576
|
+
width: number;
|
|
577
|
+
height: number;
|
|
578
|
+
}, size?: [number, number], fits?: Fits): Display;
|
|
579
|
+
/** A caller's display keeps the viewport's shape: screenshots are scaled
|
|
580
|
+
* uniformly, so another aspect ratio would map clicks off the image. */
|
|
581
|
+
private static sized;
|
|
582
|
+
get scaled(): boolean;
|
|
583
|
+
get scale(): number;
|
|
584
|
+
toPage(x: number, y: number): [number, number];
|
|
467
585
|
}
|
|
468
586
|
|
|
469
587
|
/**
|
|
470
|
-
*
|
|
471
|
-
*
|
|
472
|
-
*
|
|
473
|
-
*
|
|
474
|
-
* A call with `pending_safety_checks` is not executed until the caller passes
|
|
475
|
-
* them back as `acknowledged`.
|
|
476
|
-
* Docs: https://developers.openai.com/api/docs/guides/tools-computer-use
|
|
477
|
-
* Twin of `gatewaysdk/native_computer/openai.py`.
|
|
588
|
+
* Pixels and keys on a `WorldBrowser` page. Every provider's actions land here
|
|
589
|
+
* as `ComputerAction` values and run as Playwright mouse and keyboard calls.
|
|
590
|
+
* The cursor is tracked in the model's pixel space so a click without
|
|
591
|
+
* coordinates lands where the pointer is. Twin of `native_computer/screen.py`.
|
|
478
592
|
*/
|
|
479
593
|
|
|
480
|
-
type
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
594
|
+
type CdpSession = {
|
|
595
|
+
send(method: string, params: Record<string, unknown>): Promise<{
|
|
596
|
+
data: string;
|
|
597
|
+
}>;
|
|
598
|
+
detach(): Promise<void>;
|
|
484
599
|
};
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
600
|
+
/** The Playwright page surface pixel-level control needs, beyond `BrowserPage`. */
|
|
601
|
+
type NativePage = {
|
|
602
|
+
mouse: {
|
|
603
|
+
move(x: number, y: number, opts?: {
|
|
604
|
+
steps?: number;
|
|
605
|
+
}): Promise<void>;
|
|
606
|
+
click(x: number, y: number, opts?: {
|
|
607
|
+
button?: string;
|
|
608
|
+
clickCount?: number;
|
|
609
|
+
}): Promise<void>;
|
|
610
|
+
down(opts?: {
|
|
611
|
+
button?: string;
|
|
612
|
+
}): Promise<void>;
|
|
613
|
+
up(opts?: {
|
|
614
|
+
button?: string;
|
|
615
|
+
}): Promise<void>;
|
|
616
|
+
wheel(dx: number, dy: number): Promise<void>;
|
|
492
617
|
};
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
};
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
618
|
+
keyboard: {
|
|
619
|
+
down(key: string): Promise<void>;
|
|
620
|
+
up(key: string): Promise<void>;
|
|
621
|
+
press(key: string): Promise<void>;
|
|
622
|
+
type(text: string): Promise<void>;
|
|
623
|
+
};
|
|
624
|
+
screenshot(opts?: {
|
|
625
|
+
type?: "png";
|
|
626
|
+
}): Promise<Buffer>;
|
|
627
|
+
waitForTimeout(ms: number): Promise<void>;
|
|
628
|
+
goBack(): Promise<unknown>;
|
|
629
|
+
goForward(): Promise<unknown>;
|
|
630
|
+
evaluate(expression: string): Promise<unknown>;
|
|
631
|
+
context(): {
|
|
632
|
+
newCDPSession(page: unknown): Promise<CdpSession>;
|
|
503
633
|
};
|
|
504
|
-
acknowledgedSafetyChecks?: SafetyCheck[];
|
|
505
634
|
};
|
|
506
|
-
/** The
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
readonly
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
}
|
|
513
|
-
/** The GA `computer` tool (gpt-5.5, gpt-5.6-sol and the other models whose
|
|
514
|
-
* page lists computer use): send `tool()` in `tools`, pass each
|
|
515
|
-
* `computer_call` item to `execute`, and send the returned
|
|
516
|
-
* `computer_call_output` back with `previous_response_id`. */
|
|
517
|
-
declare class OpenAIComputer extends NativeComputer {
|
|
518
|
-
tool(): Record<string, unknown>;
|
|
519
|
-
owns(item: unknown): boolean;
|
|
520
|
-
parse(raw: unknown): ComputerAction;
|
|
521
|
-
static actionsOf(call: unknown): unknown[];
|
|
522
|
-
/** Run a `computer_call`'s actions and return its `computer_call_output`.
|
|
523
|
-
* Throws `PendingSafetyChecks` (before anything runs) while a check the
|
|
524
|
-
* model raised is not in `acknowledged`. */
|
|
525
|
-
execute(call: unknown, acknowledged?: readonly unknown[]): Promise<ComputerCallOutput>;
|
|
526
|
-
/** For `openai.tools.computer({ ...computer.aiSdk() })`: `execute` runs a
|
|
527
|
-
* call's `actions` and returns the screenshot output. A call with pending
|
|
528
|
-
* safety checks asks for approval first (`needsApproval`), so the AI SDK's
|
|
529
|
-
* approval flow puts them in front of a person; once approved, `execute`
|
|
530
|
-
* acknowledges them. */
|
|
531
|
-
aiSdk(): {
|
|
532
|
-
execute: (input: AiSdkComputerCall) => Promise<AiSdkComputerOutput>;
|
|
533
|
-
needsApproval: (input: AiSdkComputerCall) => boolean;
|
|
635
|
+
/** The slice of `WorldBrowser` a native computer drives. */
|
|
636
|
+
type ScreenBrowser = {
|
|
637
|
+
readonly page: BrowserPage;
|
|
638
|
+
readonly viewport: {
|
|
639
|
+
width: number;
|
|
640
|
+
height: number;
|
|
534
641
|
};
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
642
|
+
act<T>(action: string, args: Record<string, unknown>, fn: () => Promise<T>, onLoss?: "retry" | "report"): Promise<T>;
|
|
643
|
+
settle(): Promise<void>;
|
|
644
|
+
scrub(text: string): string;
|
|
645
|
+
};
|
|
646
|
+
declare class Screen {
|
|
647
|
+
readonly browser: ScreenBrowser;
|
|
648
|
+
readonly display: Display;
|
|
649
|
+
cursor: Point;
|
|
650
|
+
private pixelRatio;
|
|
651
|
+
private readonly handlers;
|
|
652
|
+
constructor(browser: ScreenBrowser, display: Display);
|
|
653
|
+
/** The live page (a new object after a reconnect), as pixel-level Playwright. */
|
|
654
|
+
get page(): NativePage;
|
|
655
|
+
run(action: ComputerAction): Promise<ActionResult>;
|
|
656
|
+
/** A PNG of the viewport at the model's display size. */
|
|
657
|
+
screenshot(): Promise<Buffer>;
|
|
658
|
+
/** Whether keystrokes go to a credential field (a password input, or one
|
|
659
|
+
* named like a token, key or PIN), looking through shadow roots and
|
|
660
|
+
* same-origin frames. An unreadable page, a cross-origin frame or a focus
|
|
661
|
+
* that is not a text field (a closed shadow root's host) counts as one. */
|
|
662
|
+
focusedFieldIsSecret(): Promise<boolean>;
|
|
663
|
+
/** CDP renders a clip at the page's device pixel ratio as well as its
|
|
664
|
+
* `scale` (a Retina host doubles it), so a capture of the wrong width
|
|
665
|
+
* measures that ratio and is taken once more, corrected. */
|
|
666
|
+
private capture;
|
|
667
|
+
private cdpCapture;
|
|
668
|
+
private point;
|
|
669
|
+
private moveTo;
|
|
670
|
+
private held;
|
|
671
|
+
private zoom;
|
|
672
|
+
private click;
|
|
673
|
+
private drag;
|
|
674
|
+
private scroll;
|
|
675
|
+
private key;
|
|
542
676
|
}
|
|
543
677
|
|
|
544
|
-
|
|
678
|
+
declare const SPAN_PREFIX = "computer.";
|
|
679
|
+
declare class ActionTracer {
|
|
680
|
+
readonly media: MediaUploader | null;
|
|
681
|
+
private readonly warn;
|
|
682
|
+
private failures;
|
|
683
|
+
private warned;
|
|
684
|
+
constructor(media: MediaUploader | null, warn?: (message: string) => void);
|
|
685
|
+
static fromEnv(): ActionTracer;
|
|
686
|
+
/** `args` are already redacted. A failure's status goes through `scrub`:
|
|
687
|
+
* browser errors quote the session's ws URL and UI token. */
|
|
688
|
+
span(action: ComputerAction, args: Record<string, unknown>, run: () => Promise<ActionResult>, capture: () => Promise<Buffer>, scrub: (text: string) => string): Promise<ActionResult>;
|
|
689
|
+
private finish;
|
|
690
|
+
private screenshot;
|
|
691
|
+
private reference;
|
|
692
|
+
private failed;
|
|
693
|
+
}
|
|
545
694
|
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
695
|
+
type NativeComputerOptions = {
|
|
696
|
+
/** The pixel size the model sees; default the viewport, or the largest
|
|
697
|
+
* downscale that fits the provider's image limits. */
|
|
698
|
+
display?: [number, number];
|
|
699
|
+
/** Records one span per action with the screen after it; default uploads
|
|
700
|
+
* screenshots with the `GATEWAY_*` keys when tracing is initialized. */
|
|
701
|
+
tracer?: ActionTracer;
|
|
553
702
|
};
|
|
554
|
-
|
|
703
|
+
/** The major version of the `ai` package the tools are handed to. */
|
|
704
|
+
type AiSdkMajor = 6 | 7;
|
|
705
|
+
type AiSdkOptions<V extends AiSdkMajor = 6> = {
|
|
706
|
+
/** The Anthropic kinds' screenshot part. Default 6: `image-data`, which
|
|
707
|
+
* AI SDK 7 still accepts with a deprecation warning. 7: the `file` part with
|
|
708
|
+
* `{ type: "data", data }`, which AI SDK 6 does not accept. The OpenAI kinds
|
|
709
|
+
* return the provider's own `computer_screenshot` output and ignore it. */
|
|
710
|
+
version?: V;
|
|
711
|
+
};
|
|
712
|
+
type Kind = new (browser: ScreenBrowser, options?: NativeComputerOptions) => NativeComputer;
|
|
713
|
+
/** `item[name]` for the first spelling that is set (`scroll_x`, `scrollX`). */
|
|
714
|
+
declare function readField(item: unknown, ...names: string[]): unknown;
|
|
715
|
+
declare abstract class NativeComputer {
|
|
716
|
+
readonly browser: ScreenBrowser;
|
|
717
|
+
private static readonly kinds;
|
|
718
|
+
readonly display: Display;
|
|
719
|
+
readonly screen: Screen;
|
|
720
|
+
readonly tracer: ActionTracer;
|
|
721
|
+
private queue;
|
|
722
|
+
static register(provider: string, kind: Kind): void;
|
|
723
|
+
static get providers(): string[];
|
|
724
|
+
static forProvider(provider: string, browser: ScreenBrowser, options?: NativeComputerOptions): NativeComputer;
|
|
725
|
+
constructor(browser: ScreenBrowser, options?: NativeComputerOptions);
|
|
726
|
+
/** Whether a screenshot of this size is within the provider's limits. */
|
|
727
|
+
static fits(_width: number, _height: number): boolean;
|
|
728
|
+
/** The tool definition to send the model. */
|
|
729
|
+
abstract tool(): Record<string, unknown>;
|
|
730
|
+
/** One action in the provider's own shape, as a `ComputerAction`. */
|
|
731
|
+
abstract parse(raw: unknown): ComputerAction;
|
|
732
|
+
/** The options to spread into the Vercel AI SDK's provider-defined computer
|
|
733
|
+
* tool (`execute` and its companions), backed by this computer. */
|
|
734
|
+
abstract aiSdk(options?: AiSdkOptions<AiSdkMajor>): object;
|
|
735
|
+
/** Run one provider-shaped action (an OpenAI action object, or an Anthropic
|
|
736
|
+
* `{ action: "left_click", ... }` input) and return what it produced: the
|
|
737
|
+
* door for any agent framework that hands actions over one at a time. */
|
|
738
|
+
executeAction(raw: unknown): Promise<ActionResult>;
|
|
739
|
+
/** Run one action on the page: reported on the session's browser timeline
|
|
740
|
+
* and, when tracing is on, as a span with the screen after. */
|
|
741
|
+
perform(action: ComputerAction): Promise<ActionResult>;
|
|
742
|
+
performAll(actions: readonly ComputerAction[]): Promise<ActionResult[]>;
|
|
743
|
+
/** The screen as the model sees it, as a traced `screenshot` action. */
|
|
744
|
+
screenshot(): Promise<Buffer>;
|
|
745
|
+
/** Run `fn` after every earlier call made through here: the AI SDK starts a
|
|
746
|
+
* step's tool calls concurrently, but one screen takes one action at a time. */
|
|
747
|
+
protected serial<T>(fn: () => Promise<T>): Promise<T>;
|
|
748
|
+
private runOnScreen;
|
|
749
|
+
private onLoss;
|
|
750
|
+
}
|
|
555
751
|
|
|
556
752
|
/**
|
|
557
|
-
*
|
|
558
|
-
*
|
|
559
|
-
*
|
|
560
|
-
*
|
|
561
|
-
* project resource: create it once, open as many sessions on it as you like
|
|
562
|
-
* with `{ task: { id } }`, and every grade attributes back to the task and
|
|
563
|
-
* its version. Updating the spec never rewrites history — it appends a
|
|
564
|
-
* version, and a session opened on `{ id, version: 2 }` keeps running v2
|
|
565
|
-
* after v3 exists.
|
|
566
|
-
*
|
|
567
|
-
* const task = await createTask({
|
|
568
|
-
* name: "refund-late-invoice",
|
|
569
|
-
* world: "acme-billing",
|
|
570
|
-
* spec: { instruction: "…", seed: {…}, grader: {…} },
|
|
571
|
-
* });
|
|
572
|
-
* const session = await openSession("acme-billing", { task: { id: task.id } });
|
|
573
|
-
*
|
|
574
|
-
* Tasks are project-scoped: another project's task id is not found (404),
|
|
575
|
-
* never forbidden. `world` pins a task to one world's slug (validated against
|
|
576
|
-
* that world's contract); null leaves it usable with any world.
|
|
753
|
+
* Key names from each provider's vocabulary, mapped once to Playwright's.
|
|
754
|
+
* Anthropic sends xdotool-style chords (`ctrl+a`, `Return`); OpenAI sends
|
|
755
|
+
* arrays of upper-case names (`["CTRL", "A"]`). Twin of
|
|
756
|
+
* `gatewaysdk/native_computer/keys.py`; `conformance/native-computer.json` pins both.
|
|
577
757
|
*/
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
/**
|
|
586
|
-
|
|
587
|
-
/**
|
|
588
|
-
|
|
589
|
-
/** What
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
createdAt: string;
|
|
593
|
-
updatedAt: string;
|
|
594
|
-
createdBy: string;
|
|
595
|
-
updatedBy: string;
|
|
596
|
-
/** On create, when the task is pinned to a world of a deprecated shape (an
|
|
597
|
-
* api bundle): what to run instead. A retired shape is refused. */
|
|
598
|
-
deprecations?: {
|
|
599
|
-
code: string;
|
|
600
|
-
message: string;
|
|
601
|
-
replacement: string;
|
|
602
|
-
}[];
|
|
603
|
-
};
|
|
604
|
-
type WorldTaskVersionSummary = {
|
|
605
|
-
version: number;
|
|
606
|
-
hash: string;
|
|
607
|
-
createdAt: string;
|
|
608
|
-
createdBy: string;
|
|
609
|
-
message: string | null;
|
|
610
|
-
};
|
|
611
|
-
type WorldTaskVerifierRow = {
|
|
612
|
-
key: string;
|
|
613
|
-
aliases: string[];
|
|
614
|
-
kind: "assertions" | "python" | "rubric";
|
|
615
|
-
description: string | null;
|
|
616
|
-
source: string | null;
|
|
617
|
-
sourceLanguage: "python" | "text" | null;
|
|
618
|
-
};
|
|
619
|
-
type WorldTaskDetail = WorldTaskSummary & {
|
|
620
|
-
versions: WorldTaskVersionSummary[];
|
|
621
|
-
};
|
|
622
|
-
type WorldTaskPage = {
|
|
623
|
-
tasks: WorldTaskSummary[];
|
|
624
|
-
meta: {
|
|
625
|
-
page: number;
|
|
626
|
-
limit: number;
|
|
627
|
-
totalItems: number;
|
|
628
|
-
totalPages: number;
|
|
629
|
-
/** Listed by world: the scan for multi-world tasks naming it filled its
|
|
630
|
-
* bound, so `totalItems` is a floor. */
|
|
631
|
-
scanTruncated?: true;
|
|
632
|
-
};
|
|
633
|
-
};
|
|
634
|
-
type WorldTaskWorldValidation = {
|
|
635
|
-
slug: string;
|
|
636
|
-
ref: string;
|
|
637
|
-
versionId: string;
|
|
638
|
-
ok: boolean;
|
|
639
|
-
checked: "entities" | "none";
|
|
640
|
-
problems: string[];
|
|
641
|
-
entities: string[] | null;
|
|
642
|
-
};
|
|
643
|
-
type WorldTaskValidation = {
|
|
644
|
-
taskId: string;
|
|
645
|
-
version: number;
|
|
646
|
-
/** The world version the task was checked against; null for a task with
|
|
647
|
-
* `worlds`, whose versions are per alias under `worlds`. */
|
|
648
|
-
versionId: string | null;
|
|
649
|
-
ok: boolean;
|
|
650
|
-
/** `entities` when the world's contract was read and every seed and check
|
|
651
|
-
* entity was matched against it; `none` when the version has no contract
|
|
652
|
-
* to check (a mock-tools world), in which case `ok` says only that the
|
|
653
|
-
* version exists and is READY; `worlds` for a multi-world task, checked
|
|
654
|
-
* alias by alias against the ref each names. */
|
|
655
|
-
checked: "entities" | "none" | "worlds";
|
|
656
|
-
/** For a multi-world task each problem is prefixed with its alias. */
|
|
657
|
-
problems: string[];
|
|
658
|
-
entities: string[] | null;
|
|
659
|
-
worlds?: Record<string, WorldTaskWorldValidation>;
|
|
660
|
-
};
|
|
661
|
-
/** Store a task. `name` defaults to `spec.name`; one of the two is needed. */
|
|
662
|
-
declare function createTask(input: {
|
|
663
|
-
spec: WorldTaskSpec;
|
|
664
|
-
name?: string;
|
|
665
|
-
world?: string | null;
|
|
666
|
-
message?: string;
|
|
667
|
-
}, options?: WorldsClientOptions): Promise<WorldTaskSummary>;
|
|
668
|
-
/** Change a task. A new `spec` becomes the next version (the old ones stay
|
|
669
|
-
* readable and openable); `name` and `world` change in place. */
|
|
670
|
-
declare function updateTask(taskId: string, input: {
|
|
671
|
-
spec?: WorldTaskSpec;
|
|
672
|
-
name?: string;
|
|
673
|
-
world?: string | null;
|
|
674
|
-
message?: string;
|
|
675
|
-
}, options?: WorldsClientOptions): Promise<WorldTaskSummary>;
|
|
676
|
-
/** The project's tasks, newest change first. `world` keeps only tasks
|
|
677
|
-
* that run against that slug (pinned to it, or naming it under an alias); `metadata` keeps tasks whose spec metadata carries
|
|
678
|
-
* every given key/value (`{ externalUserId: "u_42" }`). */
|
|
679
|
-
declare function listTasks(filter?: {
|
|
680
|
-
world?: string;
|
|
681
|
-
metadata?: Record<string, string>;
|
|
682
|
-
page?: number;
|
|
683
|
-
limit?: number;
|
|
684
|
-
}, options?: WorldsClientOptions): Promise<WorldTaskPage>;
|
|
685
|
-
/** One task with its version history; `version` reads that version's spec
|
|
686
|
-
* instead of the current one. */
|
|
687
|
-
declare function getTask(taskId: string, opts?: {
|
|
688
|
-
version?: number;
|
|
689
|
-
}, options?: WorldsClientOptions): Promise<WorldTaskDetail>;
|
|
690
|
-
/** Remove a task and every version. Sessions already opened on it keep
|
|
691
|
-
* their copy of the spec. */
|
|
692
|
-
declare function deleteTask(taskId: string, options?: WorldsClientOptions): Promise<{
|
|
693
|
-
id: string;
|
|
694
|
-
name: string;
|
|
695
|
-
}>;
|
|
696
|
-
/** Check a task against a world version without opening a session: every
|
|
697
|
-
* seed entity and every check's entity must exist in the world's contract.
|
|
698
|
-
* `slug` checks against that world's head, `versionId` against an exact
|
|
699
|
-
* version, neither against the task's own `world` pin. */
|
|
700
|
-
declare function validateTask(taskId: string, target?: {
|
|
701
|
-
version?: number;
|
|
702
|
-
slug?: string;
|
|
703
|
-
versionId?: string;
|
|
704
|
-
}, options?: WorldsClientOptions): Promise<WorldTaskValidation>;
|
|
758
|
+
declare const KEY_NAMES: Readonly<Record<string, string>>;
|
|
759
|
+
/** One provider key name as Playwright names it; an unknown name passes through. */
|
|
760
|
+
declare function playwrightKey(token: string): string;
|
|
761
|
+
/** Keys pressed together, in Playwright's names (`["Control", "a"]`). */
|
|
762
|
+
declare class KeyChord {
|
|
763
|
+
readonly keys: readonly string[];
|
|
764
|
+
private constructor();
|
|
765
|
+
/** `ctrl+shift+t` / `Return`: Anthropic's vocabulary, case kept. */
|
|
766
|
+
static fromXdotool(text: string): KeyChord;
|
|
767
|
+
/** `["CTRL", "A"]`: OpenAI's vocabulary. A lone letter is the unshifted key. */
|
|
768
|
+
static fromKeys(keys: readonly string[]): KeyChord;
|
|
769
|
+
/** What `page.keyboard.press` takes: `Control+a`. */
|
|
770
|
+
get combo(): string;
|
|
771
|
+
}
|
|
705
772
|
|
|
706
|
-
declare const modelToolName: (name: string) => string;
|
|
707
773
|
/**
|
|
708
|
-
*
|
|
709
|
-
*
|
|
710
|
-
* `crm_update_deal(id, stage=None, owner=None, amount=None)` becomes an
|
|
711
|
-
* object with `id` required and the rest optional. Types are read from the
|
|
712
|
-
* DEFAULTS the world declares — a numeric default means a number, a boolean
|
|
713
|
-
* default a boolean — because that is the only type information a signature
|
|
714
|
-
* actually carries. Everything else is a string, which is what a tool CLI
|
|
715
|
-
* receives anyway.
|
|
774
|
+
* Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool
|
|
775
|
+
* Twin of `gatewaysdk/native_computer/anthropic.py`.
|
|
716
776
|
*/
|
|
717
|
-
declare function schemaFromSignature(spec: WorldToolSpec): {
|
|
718
|
-
type: "function";
|
|
719
|
-
function: {
|
|
720
|
-
name: string;
|
|
721
|
-
description: string;
|
|
722
|
-
parameters: Record<string, unknown>;
|
|
723
|
-
};
|
|
724
|
-
};
|
|
725
777
|
|
|
726
|
-
declare const
|
|
727
|
-
|
|
728
|
-
type
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
778
|
+
declare const NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed.";
|
|
779
|
+
type Raw = Record<string, unknown>;
|
|
780
|
+
type AiSdkAnthropicOutput = {
|
|
781
|
+
type: "image";
|
|
782
|
+
data: string;
|
|
783
|
+
} | string;
|
|
784
|
+
type ImageParts = {
|
|
785
|
+
6: {
|
|
786
|
+
type: "image-data";
|
|
787
|
+
data: string;
|
|
788
|
+
mediaType: "image/png";
|
|
732
789
|
};
|
|
733
|
-
|
|
734
|
-
|
|
790
|
+
7: {
|
|
791
|
+
type: "file";
|
|
792
|
+
mediaType: "image/png";
|
|
793
|
+
data: {
|
|
794
|
+
type: "data";
|
|
795
|
+
data: string;
|
|
796
|
+
};
|
|
735
797
|
};
|
|
736
798
|
};
|
|
737
|
-
type
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
until?: string;
|
|
745
|
-
cursor?: string;
|
|
746
|
-
limit?: number;
|
|
799
|
+
type AiSdkImagePart<V extends AiSdkMajor = AiSdkMajor> = ImageParts[V];
|
|
800
|
+
type AiSdkModelOutput<V extends AiSdkMajor = 6> = {
|
|
801
|
+
type: "text";
|
|
802
|
+
value: string;
|
|
803
|
+
} | {
|
|
804
|
+
type: "content";
|
|
805
|
+
value: AiSdkImagePart<V>[];
|
|
747
806
|
};
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
* `since`/`until` as UTC instants (a date alone is its midnight, a time without a zone is UTC). Twin of
|
|
758
|
-
* `gatewaysdk.world_requests.WorldRequestQuery`; both run `conformance/world-request-cli.json`. */
|
|
759
|
-
declare class WorldRequestQuery {
|
|
760
|
-
private readonly entries;
|
|
761
|
-
private constructor();
|
|
762
|
-
static parse(filter?: WorldRequestFilter): WorldRequestQuery;
|
|
763
|
-
private static via;
|
|
764
|
-
private static status;
|
|
765
|
-
get filtered(): boolean;
|
|
766
|
-
params(): [string, string][];
|
|
767
|
-
search(): string;
|
|
768
|
-
}
|
|
769
|
-
/** A world's request ledger: every request the world received, from every session and version, through every
|
|
770
|
-
* door (`via`: api, ui, tool, webhook), kept for the world's life. Reading it records nothing. Twin of
|
|
771
|
-
* `gatewaysdk.world_requests.WorldRequestLedger`. */
|
|
772
|
-
declare class WorldRequestLedger {
|
|
773
|
-
private readonly options;
|
|
774
|
-
constructor(options?: WorldsClientOptions);
|
|
775
|
-
/** A page of the world's requests, newest first; `nextCursor` reads the page after it. Narrowed to a session
|
|
776
|
-
* whose engine records none: `WorldRequestsNotRecorded`. */
|
|
777
|
-
list(slug: string, query?: WorldRequestQuery): Promise<WorldRequestPage>;
|
|
778
|
-
/** One of the world's requests, with its headers and bodies. */
|
|
779
|
-
get(slug: string, requestId: string): Promise<WorldRequestEntry>;
|
|
780
|
-
/** A page of one session's requests, newest first; `WorldRequestsNotRecorded` when its engine records none. */
|
|
781
|
-
forSession(sessionId: string, query?: WorldRequestQuery): Promise<WorldRequestPage>;
|
|
782
|
-
}
|
|
783
|
-
|
|
784
|
-
/** One entry of a world's request ledger as a list carries it: what was asked
|
|
785
|
-
* and what came back, without its headers and bodies. */
|
|
786
|
-
type WorldRequest = {
|
|
787
|
-
id: string;
|
|
788
|
-
seq: number;
|
|
789
|
-
at: string;
|
|
790
|
-
durationMs: number | null;
|
|
791
|
-
worldSlug: string;
|
|
792
|
-
sessionId: string;
|
|
793
|
-
versionId: string;
|
|
794
|
-
via: (typeof WORLD_REQUEST_VIAS)[number] | null;
|
|
795
|
-
operation: string | null;
|
|
796
|
-
method: string | null;
|
|
797
|
-
path: string | null;
|
|
798
|
-
query: Record<string, unknown>;
|
|
799
|
-
request: {
|
|
800
|
-
bodyBytes: number | null;
|
|
801
|
-
truncated: boolean;
|
|
802
|
-
contentType: string | null;
|
|
803
|
-
};
|
|
804
|
-
response: {
|
|
805
|
-
status: number;
|
|
806
|
-
bodyBytes: number | null;
|
|
807
|
-
truncated: boolean;
|
|
808
|
-
contentType: string | null;
|
|
807
|
+
type AnthropicContent = {
|
|
808
|
+
type: "text";
|
|
809
|
+
text: string;
|
|
810
|
+
} | {
|
|
811
|
+
type: "image";
|
|
812
|
+
source: {
|
|
813
|
+
type: "base64";
|
|
814
|
+
media_type: "image/png";
|
|
815
|
+
data: string;
|
|
809
816
|
};
|
|
810
|
-
rows: number | null;
|
|
811
|
-
found: boolean | null;
|
|
812
|
-
};
|
|
813
|
-
/** One page of a ledger list, newest first, with what its scope did not record: `shed` requests kept without
|
|
814
|
-
* their headers and bodies, `lost` requests a host counted as never recorded or the platform refused, and
|
|
815
|
-
* `hostsLost` hosts lost before they stored every request, whose unsent requests no count holds; none of them on
|
|
816
|
-
* a page whose filters narrow past its world, session or version. */
|
|
817
|
-
type WorldRequestPage = {
|
|
818
|
-
requests: WorldRequest[];
|
|
819
|
-
nextCursor: string | null;
|
|
820
|
-
shed?: number;
|
|
821
|
-
lost?: number;
|
|
822
|
-
hostsLost?: number;
|
|
823
817
|
};
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
*
|
|
834
|
-
*
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
readonly
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
818
|
+
type AnthropicToolResult = {
|
|
819
|
+
type: "tool_result";
|
|
820
|
+
tool_use_id: string;
|
|
821
|
+
toolset_name?: string;
|
|
822
|
+
content: AnthropicContent[] | string;
|
|
823
|
+
is_error?: true;
|
|
824
|
+
};
|
|
825
|
+
/** `computer_toolset_20260801` for Claude 5-family models (claude-sonnet-5-5,
|
|
826
|
+
* claude-opus-5-5, ...): send `tool()` in `tools`, pass each response's
|
|
827
|
+
* `content` to `execute`, and send the returned blocks back as the next user
|
|
828
|
+
* message. */
|
|
829
|
+
declare class AnthropicComputer extends NativeComputer {
|
|
830
|
+
static readonly TOOL_TYPE: string;
|
|
831
|
+
static readonly TOOLSET = "computer";
|
|
832
|
+
static readonly BETA: string | null;
|
|
833
|
+
static readonly MAX_LONG_EDGE: number;
|
|
834
|
+
static readonly MAX_VISUAL_TOKENS = 4784;
|
|
835
|
+
static readonly PATCH_PX = 28;
|
|
836
|
+
static fits(width: number, height: number): boolean;
|
|
837
|
+
tool(): Record<string, unknown>;
|
|
838
|
+
/** Whether a content block is a call to this computer. */
|
|
839
|
+
owns(block: unknown): boolean;
|
|
840
|
+
member(block: unknown): [string, Raw];
|
|
841
|
+
parse(raw: unknown): ComputerAction;
|
|
842
|
+
/** Run every computer `tool_use` in a response's content, in order, and
|
|
843
|
+
* return one `tool_result` per block. Other blocks are skipped. */
|
|
844
|
+
execute(content: Iterable<unknown>): Promise<AnthropicToolResult[]>;
|
|
845
|
+
/** The content an `ActionResult` goes back to the model as. */
|
|
846
|
+
static content(result: ActionResult): AnthropicContent[];
|
|
847
|
+
/** For `anthropic.tools.computerToolset_20260801(computer.aiSdk({ version: 7 }))`
|
|
848
|
+
* (AI SDK 7 only), or `computer_20251124` with the legacy kind (AI SDK 6
|
|
849
|
+
* and 7): `execute` runs one action and returns `{ type: "image", data }` or
|
|
850
|
+
* text; `toModelOutput` turns that into the tool result in the part shape
|
|
851
|
+
* of `options.version`. Calls run one at a time, and once a call fails the
|
|
852
|
+
* rest of that step's calls answer as not executed. */
|
|
853
|
+
aiSdk<V extends AiSdkMajor = 6>(options?: AiSdkOptions<V>): {
|
|
854
|
+
execute: (input: unknown, options?: {
|
|
855
|
+
messages?: readonly unknown[];
|
|
856
|
+
}) => Promise<AiSdkAnthropicOutput>;
|
|
857
|
+
toModelOutput: (options: {
|
|
858
|
+
output: AiSdkAnthropicOutput;
|
|
859
|
+
}) => AiSdkModelOutput<V>;
|
|
860
|
+
};
|
|
861
|
+
static aiSdkOutput(result: ActionResult): AiSdkAnthropicOutput;
|
|
862
|
+
/** A screenshot as the image part of AI SDK `options.version`:
|
|
863
|
+
* `image-data` for 6 (the default), `file` with `{ type: "data", data }`
|
|
864
|
+
* for 7. */
|
|
865
|
+
static aiSdkModelOutput<V extends AiSdkMajor = 6>(output: AiSdkAnthropicOutput, options?: AiSdkOptions<V>): AiSdkModelOutput<V>;
|
|
866
|
+
private static imagePart;
|
|
867
|
+
private static modelOutput;
|
|
868
|
+
protected envelope(block: unknown, content: AnthropicContent[] | string, isError?: boolean): AnthropicToolResult;
|
|
869
|
+
private runBlock;
|
|
870
|
+
}
|
|
871
|
+
/** The `computer_20251124` tool (beta header `computer-use-2025-11-24`) for
|
|
872
|
+
* models before the toolset, and Claude 5.5 on Amazon Bedrock: one tool named
|
|
873
|
+
* `computer` whose input carries `action`. */
|
|
874
|
+
declare class AnthropicComputer20251124 extends AnthropicComputer {
|
|
875
|
+
static readonly TOOL_TYPE = "computer_20251124";
|
|
876
|
+
static readonly BETA = "computer-use-2025-11-24";
|
|
877
|
+
static readonly MAX_LONG_EDGE = 1568;
|
|
878
|
+
static readonly MAX_PIXELS = 1150000;
|
|
879
|
+
static fits(width: number, height: number): boolean;
|
|
880
|
+
tool(): Record<string, unknown>;
|
|
881
|
+
owns(block: unknown): boolean;
|
|
882
|
+
member(block: unknown): [string, Raw];
|
|
883
|
+
protected envelope(block: unknown, content: AnthropicContent[] | string, isError?: boolean): AnthropicToolResult;
|
|
853
884
|
}
|
|
854
885
|
|
|
855
886
|
/**
|
|
856
|
-
*
|
|
857
|
-
*
|
|
858
|
-
*
|
|
859
|
-
*
|
|
887
|
+
* OpenAI's computer use: the Responses API `computer` tool (GA), and the
|
|
888
|
+
* legacy `computer_use_preview` tool as a second kind. Each `computer_call`
|
|
889
|
+
* carries an ordered batch of `actions` (the preview carried one `action`);
|
|
890
|
+
* they run in order, then the screen goes back as a `computer_call_output`.
|
|
891
|
+
* A call with `pending_safety_checks` is not executed until the caller passes
|
|
892
|
+
* them back as `acknowledged`.
|
|
893
|
+
* Docs: https://developers.openai.com/api/docs/guides/tools-computer-use
|
|
894
|
+
* Twin of `gatewaysdk/native_computer/openai.py`.
|
|
860
895
|
*/
|
|
861
|
-
|
|
862
|
-
type
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
reason?: string;
|
|
867
|
-
/** Why this world could not grade; the task's grade is then that error. */
|
|
868
|
-
error?: string;
|
|
869
|
-
/** The task's cross-world verifiers anchored on this session, by name:
|
|
870
|
-
* each its own reward and named rewards, or `error` when it could not
|
|
871
|
-
* grade (evidence missing, verify.py failed) — null, never zero. */
|
|
872
|
-
verifiers?: Record<string, VerifierGrade>;
|
|
873
|
-
raw: unknown;
|
|
896
|
+
|
|
897
|
+
type SafetyCheck = {
|
|
898
|
+
id: string;
|
|
899
|
+
code?: string;
|
|
900
|
+
message?: string;
|
|
874
901
|
};
|
|
875
|
-
type
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
902
|
+
type ComputerCallOutput = {
|
|
903
|
+
type: "computer_call_output";
|
|
904
|
+
call_id: string;
|
|
905
|
+
output: {
|
|
906
|
+
type: "computer_screenshot";
|
|
907
|
+
image_url: string;
|
|
908
|
+
detail: "original";
|
|
909
|
+
};
|
|
910
|
+
acknowledged_safety_checks?: SafetyCheck[];
|
|
879
911
|
};
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
912
|
+
type AiSdkComputerCall = {
|
|
913
|
+
actions?: unknown[];
|
|
914
|
+
pendingSafetyChecks?: unknown[];
|
|
915
|
+
};
|
|
916
|
+
type AiSdkComputerOutput = {
|
|
917
|
+
output: {
|
|
918
|
+
type: "computer_screenshot";
|
|
919
|
+
imageUrl: string;
|
|
920
|
+
};
|
|
921
|
+
acknowledgedSafetyChecks?: SafetyCheck[];
|
|
922
|
+
};
|
|
923
|
+
/** The model flagged this call; nothing ran. Show `checks` to a person, then
|
|
924
|
+
* `execute(call, checks)` to run it anyway. */
|
|
925
|
+
declare class PendingSafetyChecks extends Error {
|
|
926
|
+
readonly callId: string;
|
|
927
|
+
readonly checks: SafetyCheck[];
|
|
928
|
+
constructor(callId: string, checks: SafetyCheck[]);
|
|
887
929
|
}
|
|
888
|
-
/**
|
|
889
|
-
*
|
|
890
|
-
*
|
|
891
|
-
*
|
|
892
|
-
declare class
|
|
893
|
-
|
|
930
|
+
/** The GA `computer` tool (gpt-5.5, gpt-5.6-sol and the other models whose
|
|
931
|
+
* page lists computer use): send `tool()` in `tools`, pass each
|
|
932
|
+
* `computer_call` item to `execute`, and send the returned
|
|
933
|
+
* `computer_call_output` back with `previous_response_id`. */
|
|
934
|
+
declare class OpenAIComputer extends NativeComputer {
|
|
935
|
+
tool(): Record<string, unknown>;
|
|
936
|
+
owns(item: unknown): boolean;
|
|
937
|
+
parse(raw: unknown): ComputerAction;
|
|
938
|
+
static actionsOf(call: unknown): unknown[];
|
|
939
|
+
/** Run a `computer_call`'s actions and return its `computer_call_output`.
|
|
940
|
+
* Throws `PendingSafetyChecks` (before anything runs) while a check the
|
|
941
|
+
* model raised is not in `acknowledged`. */
|
|
942
|
+
execute(call: unknown, acknowledged?: readonly unknown[]): Promise<ComputerCallOutput>;
|
|
943
|
+
/** For `openai.tools.computer({ ...computer.aiSdk() })`: `execute` runs a
|
|
944
|
+
* call's `actions` and returns the screenshot output. A call with pending
|
|
945
|
+
* safety checks asks for approval first (`needsApproval`), so the AI SDK's
|
|
946
|
+
* approval flow puts them in front of a person; once approved, `execute`
|
|
947
|
+
* acknowledges them. */
|
|
948
|
+
aiSdk(): {
|
|
949
|
+
execute: (input: AiSdkComputerCall) => Promise<AiSdkComputerOutput>;
|
|
950
|
+
needsApproval: (input: AiSdkComputerCall) => boolean;
|
|
951
|
+
};
|
|
952
|
+
/** The batch's actions, run after the safety checks clear; the screen after them. */
|
|
953
|
+
runCall(callId: string, rawActions: readonly unknown[], checks: readonly SafetyCheck[], acknowledged: readonly unknown[]): Promise<Buffer>;
|
|
894
954
|
}
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
* error, the way the World Host answers one that could not grade. */
|
|
900
|
-
static read(raw: unknown): Omit<GradeResult, "raw">;
|
|
901
|
-
/** A world whose grade call failed (the platform refused it, the host had
|
|
902
|
-
* lost the session): that world's error, never a score. */
|
|
903
|
-
static failedCall(error: unknown): GradeResult;
|
|
904
|
-
private static problem;
|
|
905
|
-
private static twice;
|
|
906
|
-
private static verifiersProblem;
|
|
907
|
-
private static scores;
|
|
908
|
-
private static isRecord;
|
|
909
|
-
private static objectOrAbsent;
|
|
910
|
-
private static record;
|
|
911
|
-
/** `reward`, and every numeric key under `rewards` (the host's shape) or at
|
|
912
|
-
* the top level (a bundled verifier's). */
|
|
913
|
-
private static numbers;
|
|
914
|
-
private static verifiers;
|
|
915
|
-
private static verifier;
|
|
916
|
-
private static failed;
|
|
955
|
+
/** The legacy `computer_use_preview` tool for the `computer-use-preview`
|
|
956
|
+
* model: it declares the display size and `environment: "browser"`. */
|
|
957
|
+
declare class OpenAIPreviewComputer extends OpenAIComputer {
|
|
958
|
+
tool(): Record<string, unknown>;
|
|
917
959
|
}
|
|
918
960
|
|
|
919
|
-
/**
|
|
920
|
-
|
|
921
|
-
/** The
|
|
922
|
-
*
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
* `apply` runs the world's `[redact]` policy over them first, `refuse`
|
|
929
|
-
* rejects a row carrying plaintext in a redacted field. */
|
|
930
|
-
redact?: "off" | "apply" | "refuse";
|
|
931
|
-
rows: Record<string, Record<string, unknown>[]>;
|
|
961
|
+
/** Python twin: `gatewaysdk/native_computer/`. */
|
|
962
|
+
|
|
963
|
+
/** The class each provider name builds, so a caller gets the kind's own
|
|
964
|
+
* `execute` without a cast. */
|
|
965
|
+
type NativeComputerKinds = {
|
|
966
|
+
anthropic: AnthropicComputer;
|
|
967
|
+
"anthropic-computer-20251124": AnthropicComputer20251124;
|
|
968
|
+
openai: OpenAIComputer;
|
|
969
|
+
"openai-preview": OpenAIPreviewComputer;
|
|
932
970
|
};
|
|
933
|
-
type
|
|
971
|
+
type NativeComputerProvider = keyof NativeComputerKinds;
|
|
972
|
+
|
|
934
973
|
/**
|
|
935
|
-
*
|
|
936
|
-
* of `entity` by equality (dotted paths reach into nested objects); the
|
|
937
|
-
* assertion says what must hold of the selection:
|
|
974
|
+
* STORED WORLD TASKS: a task spec kept by the project, outside any bundle.
|
|
938
975
|
*
|
|
939
|
-
*
|
|
940
|
-
*
|
|
941
|
-
*
|
|
976
|
+
* An inline task (`openSession(world, { task: { instruction, … } })`) belongs
|
|
977
|
+
* to one session. A stored task is the same spec as a named, versioned
|
|
978
|
+
* project resource: create it once, open as many sessions on it as you like
|
|
979
|
+
* with `{ task: { id } }`, and every grade attributes back to the task and
|
|
980
|
+
* its version. Updating the spec never rewrites history — it appends a
|
|
981
|
+
* version, and a session opened on `{ id, version: 2 }` keeps running v2
|
|
982
|
+
* after v3 exists.
|
|
942
983
|
*
|
|
943
|
-
*
|
|
944
|
-
*
|
|
984
|
+
* const task = await createTask({
|
|
985
|
+
* name: "refund-late-invoice",
|
|
986
|
+
* world: "acme-billing",
|
|
987
|
+
* spec: { instruction: "…", seed: {…}, grader: {…} },
|
|
988
|
+
* });
|
|
989
|
+
* const session = await openSession("acme-billing", { task: { id: task.id } });
|
|
990
|
+
*
|
|
991
|
+
* Tasks are project-scoped: another project's task id is not found (404),
|
|
992
|
+
* never forbidden. `world` pins a task to one world's slug (validated against
|
|
993
|
+
* that world's contract); null leaves it usable with any world.
|
|
945
994
|
*/
|
|
946
|
-
type
|
|
947
|
-
id?: string;
|
|
948
|
-
weight?: number;
|
|
949
|
-
entity: string;
|
|
950
|
-
where?: Record<string, WorldTaskScalar>;
|
|
951
|
-
assert?: "exists" | "absent" | "count" | "all" | "any";
|
|
952
|
-
count?: {
|
|
953
|
-
eq?: number;
|
|
954
|
-
gte?: number;
|
|
955
|
-
lte?: number;
|
|
956
|
-
};
|
|
957
|
-
field?: string;
|
|
958
|
-
op?: WorldTaskFieldOp;
|
|
959
|
-
value?: WorldTaskScalar | WorldTaskScalar[];
|
|
960
|
-
/** On `gateway_requests` or `calls`: only the requests before the first one this matches. */
|
|
961
|
-
before?: Record<string, WorldTaskScalar>;
|
|
962
|
-
/** On `gateway_requests` or `calls`: only the requests after the first one this matches. */
|
|
963
|
-
after?: Record<string, WorldTaskScalar>;
|
|
964
|
-
};
|
|
965
|
-
/** One thing a rubric judge scores in [0, 1]; `id` names its entry in
|
|
966
|
-
* `rewards`, `weight` (default 1) its share of the task's reward. */
|
|
967
|
-
type WorldTaskRubricCriterion = {
|
|
995
|
+
type WorldTaskSummary = {
|
|
968
996
|
id: string;
|
|
969
|
-
|
|
970
|
-
|
|
997
|
+
name: string;
|
|
998
|
+
world: string | null;
|
|
999
|
+
version: number;
|
|
1000
|
+
hash: string;
|
|
1001
|
+
spec: WorldTaskSpec;
|
|
1002
|
+
/** A multi-world task's aliases in spec order; empty for a single world. */
|
|
1003
|
+
aliases: string[];
|
|
1004
|
+
/** Listed by world: the aliases that world plays in this task; else empty. */
|
|
1005
|
+
aliasesHere: string[];
|
|
1006
|
+
/** What grades the task, one row per check or verifier: its reward key,
|
|
1007
|
+
* the aliases it judges, what it checks in plain words, its source. */
|
|
1008
|
+
verifiers: WorldTaskVerifierRow[];
|
|
1009
|
+
createdAt: string;
|
|
1010
|
+
updatedAt: string;
|
|
1011
|
+
createdBy: string;
|
|
1012
|
+
updatedBy: string;
|
|
1013
|
+
/** On create, when the task is pinned to a world of a deprecated shape (an
|
|
1014
|
+
* api bundle): what to run instead. A retired shape is refused. */
|
|
1015
|
+
deprecations?: {
|
|
1016
|
+
code: string;
|
|
1017
|
+
message: string;
|
|
1018
|
+
replacement: string;
|
|
1019
|
+
}[];
|
|
971
1020
|
};
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
1021
|
+
type WorldTaskVersionSummary = {
|
|
1022
|
+
version: number;
|
|
1023
|
+
hash: string;
|
|
1024
|
+
createdAt: string;
|
|
1025
|
+
createdBy: string;
|
|
1026
|
+
message: string | null;
|
|
1027
|
+
};
|
|
1028
|
+
type WorldTaskVerifierRow = {
|
|
1029
|
+
key: string;
|
|
1030
|
+
aliases: string[];
|
|
1031
|
+
kind: "assertions" | "python" | "rubric";
|
|
1032
|
+
description: string | null;
|
|
1033
|
+
source: string | null;
|
|
1034
|
+
sourceLanguage: "python" | "text" | null;
|
|
1035
|
+
};
|
|
1036
|
+
type WorldTaskDetail = WorldTaskSummary & {
|
|
1037
|
+
versions: WorldTaskVersionSummary[];
|
|
1038
|
+
};
|
|
1039
|
+
type WorldTaskPage = {
|
|
1040
|
+
tasks: WorldTaskSummary[];
|
|
1041
|
+
meta: {
|
|
1042
|
+
page: number;
|
|
1043
|
+
limit: number;
|
|
1044
|
+
totalItems: number;
|
|
1045
|
+
totalPages: number;
|
|
1046
|
+
/** Listed by world: the scan for multi-world tasks naming it filled its
|
|
1047
|
+
* bound, so `totalItems` is a floor. */
|
|
1048
|
+
scanTruncated?: true;
|
|
984
1049
|
};
|
|
985
1050
|
};
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
source: string;
|
|
995
|
-
timeoutSeconds?: number;
|
|
996
|
-
readsJournal?: boolean;
|
|
997
|
-
acceptsIncompleteJournal?: boolean;
|
|
998
|
-
} | WorldTaskRubricGrader;
|
|
999
|
-
/** A task supplied at open, for one session, instead of a bundled scenario.
|
|
1000
|
-
* `instruction` is what the agent is told; without `seed` the session starts
|
|
1001
|
-
* on the version's base data, without `grader` `grade()` answers
|
|
1002
|
-
* `reward: null`; `tools` is the allow-list of the version's tools the agent
|
|
1003
|
-
* may call in this session (unset: all of them; a call outside it is refused
|
|
1004
|
-
* and logged); `metadata` is yours (an end-user id, a ticket) and is echoed
|
|
1005
|
-
* on the session, never read. Limits: shared/domain/worldTasks.ts. */
|
|
1006
|
-
type WorldTaskSpec = {
|
|
1007
|
-
name?: string;
|
|
1008
|
-
instruction: string;
|
|
1009
|
-
seed?: WorldTaskSeed;
|
|
1010
|
-
grader?: WorldTaskGrader;
|
|
1011
|
-
tools?: string[];
|
|
1012
|
-
metadata?: Record<string, unknown>;
|
|
1013
|
-
/** A MULTI-WORLD task: one session per alias, each on its own world with
|
|
1014
|
-
* its own seed, grader and tools (the top-level three are then refused).
|
|
1015
|
-
* Brought up together by `openTask` / `gateway worlds task up`; see
|
|
1016
|
-
* worlds/taskSessions.ts. */
|
|
1017
|
-
worlds?: Record<string, {
|
|
1018
|
-
slug: string;
|
|
1019
|
-
/** One of the world's refs; default `main`. */
|
|
1020
|
-
ref?: string;
|
|
1021
|
-
seed?: WorldTaskSeed;
|
|
1022
|
-
grader?: WorldTaskGrader;
|
|
1023
|
-
tools?: string[];
|
|
1024
|
-
}>;
|
|
1025
|
-
/** CROSS-WORLD VERIFIERS: deterministic graders over several of the task's
|
|
1026
|
-
* worlds at once, each with a `scope` of aliases (two or more). One runs on
|
|
1027
|
-
* the session of the first alias in its scope, over a state where every
|
|
1028
|
-
* scoped world's rows are `<alias>.<entity>` and its calls `<alias>.calls`;
|
|
1029
|
-
* the platform gathers the other worlds' evidence when `grade()` names
|
|
1030
|
-
* them (`TaskSessions.grade` does). Rewards come back as `x.<name>`. */
|
|
1031
|
-
verifiers?: WorldTaskVerifier[];
|
|
1051
|
+
type WorldTaskWorldValidation = {
|
|
1052
|
+
slug: string;
|
|
1053
|
+
ref: string;
|
|
1054
|
+
versionId: string;
|
|
1055
|
+
ok: boolean;
|
|
1056
|
+
checked: "entities" | "none";
|
|
1057
|
+
problems: string[];
|
|
1058
|
+
entities: string[] | null;
|
|
1032
1059
|
};
|
|
1033
|
-
type
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1060
|
+
type WorldTaskValidation = {
|
|
1061
|
+
taskId: string;
|
|
1062
|
+
version: number;
|
|
1063
|
+
/** The world version the task was checked against; null for a task with
|
|
1064
|
+
* `worlds`, whose versions are per alias under `worlds`. */
|
|
1065
|
+
versionId: string | null;
|
|
1066
|
+
ok: boolean;
|
|
1067
|
+
/** `entities` when the world's contract was read and every seed and check
|
|
1068
|
+
* entity was matched against it; `none` when the version has no contract
|
|
1069
|
+
* to check (a mock-tools world), in which case `ok` says only that the
|
|
1070
|
+
* version exists and is READY; `worlds` for a multi-world task, checked
|
|
1071
|
+
* alias by alias against the ref each names. */
|
|
1072
|
+
checked: "entities" | "none" | "worlds";
|
|
1073
|
+
/** For a multi-world task each problem is prefixed with its alias. */
|
|
1074
|
+
problems: string[];
|
|
1075
|
+
entities: string[] | null;
|
|
1076
|
+
worlds?: Record<string, WorldTaskWorldValidation>;
|
|
1077
|
+
};
|
|
1078
|
+
/** Store a task. `name` defaults to `spec.name`; one of the two is needed. */
|
|
1079
|
+
declare function createTask(input: {
|
|
1080
|
+
spec: WorldTaskSpec;
|
|
1081
|
+
name?: string;
|
|
1082
|
+
world?: string | null;
|
|
1083
|
+
message?: string;
|
|
1084
|
+
}, options?: WorldsClientOptions): Promise<WorldTaskSummary>;
|
|
1085
|
+
/** Change a task. A new `spec` becomes the next version (the old ones stay
|
|
1086
|
+
* readable and openable); `name` and `world` change in place. */
|
|
1087
|
+
declare function updateTask(taskId: string, input: {
|
|
1088
|
+
spec?: WorldTaskSpec;
|
|
1089
|
+
name?: string;
|
|
1090
|
+
world?: string | null;
|
|
1091
|
+
message?: string;
|
|
1092
|
+
}, options?: WorldsClientOptions): Promise<WorldTaskSummary>;
|
|
1093
|
+
/** The project's tasks, newest change first. `world` keeps only tasks
|
|
1094
|
+
* that run against that slug (pinned to it, or naming it under an alias); `metadata` keeps tasks whose spec metadata carries
|
|
1095
|
+
* every given key/value (`{ externalUserId: "u_42" }`). */
|
|
1096
|
+
declare function listTasks(filter?: {
|
|
1097
|
+
world?: string;
|
|
1098
|
+
metadata?: Record<string, string>;
|
|
1099
|
+
page?: number;
|
|
1100
|
+
limit?: number;
|
|
1101
|
+
}, options?: WorldsClientOptions): Promise<WorldTaskPage>;
|
|
1102
|
+
/** One task with its version history; `version` reads that version's spec
|
|
1103
|
+
* instead of the current one. */
|
|
1104
|
+
declare function getTask(taskId: string, opts?: {
|
|
1105
|
+
version?: number;
|
|
1106
|
+
}, options?: WorldsClientOptions): Promise<WorldTaskDetail>;
|
|
1107
|
+
/** Remove a task and every version. Sessions already opened on it keep
|
|
1108
|
+
* their copy of the spec. */
|
|
1109
|
+
declare function deleteTask(taskId: string, options?: WorldsClientOptions): Promise<{
|
|
1047
1110
|
id: string;
|
|
1111
|
+
name: string;
|
|
1112
|
+
}>;
|
|
1113
|
+
/** Check a task against a world version without opening a session: every
|
|
1114
|
+
* seed entity and every check's entity must exist in the world's contract.
|
|
1115
|
+
* `slug` checks against that world's head, `versionId` against an exact
|
|
1116
|
+
* version, neither against the task's own `world` pin. */
|
|
1117
|
+
declare function validateTask(taskId: string, target?: {
|
|
1048
1118
|
version?: number;
|
|
1049
|
-
|
|
1050
|
-
|
|
1051
|
-
|
|
1052
|
-
type WorldTaskRef = string | WorldTaskIdRef | WorldTaskSpec;
|
|
1053
|
-
/** What a session's task is, on every session response. `hash` is the
|
|
1054
|
-
* content hash of the spec (inline or stored) — what warm reuse matches on;
|
|
1055
|
-
* `id`/`version` name the stored task the session was opened on. */
|
|
1056
|
-
type WorldSessionTask = {
|
|
1057
|
-
/** `none` is an exploratory session: opened with no task, no grader. */
|
|
1058
|
-
source: "bundled" | "inline" | "stored" | "none";
|
|
1059
|
-
name: string | null;
|
|
1060
|
-
hash: string | null;
|
|
1061
|
-
id?: string | null;
|
|
1062
|
-
version?: number | null;
|
|
1063
|
-
metadata: Record<string, unknown>;
|
|
1064
|
-
};
|
|
1119
|
+
slug?: string;
|
|
1120
|
+
versionId?: string;
|
|
1121
|
+
}, options?: WorldsClientOptions): Promise<WorldTaskValidation>;
|
|
1065
1122
|
|
|
1123
|
+
declare const modelToolName: (name: string) => string;
|
|
1066
1124
|
/**
|
|
1067
|
-
*
|
|
1068
|
-
*
|
|
1069
|
-
*
|
|
1070
|
-
*
|
|
1125
|
+
* Turn a world's Python signature into a JSON schema the model can call.
|
|
1126
|
+
*
|
|
1127
|
+
* `crm_update_deal(id, stage=None, owner=None, amount=None)` becomes an
|
|
1128
|
+
* object with `id` required and the rest optional. Types are read from the
|
|
1129
|
+
* DEFAULTS the world declares — a numeric default means a number, a boolean
|
|
1130
|
+
* default a boolean — because that is the only type information a signature
|
|
1131
|
+
* actually carries. Everything else is a string, which is what a tool CLI
|
|
1132
|
+
* receives anyway.
|
|
1071
1133
|
*/
|
|
1072
|
-
declare
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1134
|
+
declare function schemaFromSignature(spec: WorldToolSpec): {
|
|
1135
|
+
type: "function";
|
|
1136
|
+
function: {
|
|
1137
|
+
name: string;
|
|
1138
|
+
description: string;
|
|
1139
|
+
parameters: Record<string, unknown>;
|
|
1140
|
+
};
|
|
1141
|
+
};
|
|
1080
1142
|
|
|
1081
|
-
declare
|
|
1143
|
+
declare const WORLD_REQUEST_VIAS: readonly ["api", "ui", "tool", "webhook", "page"];
|
|
1144
|
+
/** One request with its exchange: the request's headers (credentials `[redacted]`) and the first 64 KB of each body, `null` for a body that is not text. */
|
|
1145
|
+
type WorldRequestEntry = Omit<WorldRequest, "request" | "response"> & {
|
|
1146
|
+
request: WorldRequest["request"] & {
|
|
1147
|
+
headers: Record<string, string>;
|
|
1148
|
+
body: string | null;
|
|
1149
|
+
};
|
|
1150
|
+
response: WorldRequest["response"] & {
|
|
1151
|
+
body: string | null;
|
|
1152
|
+
};
|
|
1153
|
+
};
|
|
1154
|
+
type WorldRequestFilter = {
|
|
1155
|
+
session?: string;
|
|
1156
|
+
version?: string;
|
|
1157
|
+
via?: string;
|
|
1158
|
+
operation?: string;
|
|
1159
|
+
status?: string;
|
|
1160
|
+
since?: string;
|
|
1161
|
+
until?: string;
|
|
1162
|
+
cursor?: string;
|
|
1163
|
+
limit?: number;
|
|
1164
|
+
};
|
|
1165
|
+
declare class WorldRequestFilterError extends Error {
|
|
1082
1166
|
}
|
|
1083
|
-
|
|
1167
|
+
/** The platform's 409 `requests_not_recorded`: the session's engine keeps no request ledger, only World Host
|
|
1168
|
+
* sessions record requests. Its message is the platform's own sentence. */
|
|
1169
|
+
declare class WorldRequestsNotRecorded extends Error {
|
|
1170
|
+
static from(error: unknown): unknown;
|
|
1171
|
+
static mapped<T>(read: Promise<T>): Promise<T>;
|
|
1084
1172
|
}
|
|
1085
|
-
/** The
|
|
1086
|
-
* `
|
|
1087
|
-
* `
|
|
1088
|
-
declare class
|
|
1089
|
-
readonly
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
1173
|
+
/** The filters of a request-ledger read, checked and put in the platform's form: `via` and `status` lower-cased,
|
|
1174
|
+
* `since`/`until` as UTC instants (a date alone is its midnight, a time without a zone is UTC). Twin of
|
|
1175
|
+
* `gatewaysdk.world_requests.WorldRequestQuery`; both run `conformance/world-request-cli.json`. */
|
|
1176
|
+
declare class WorldRequestQuery {
|
|
1177
|
+
private readonly entries;
|
|
1178
|
+
private constructor();
|
|
1179
|
+
static parse(filter?: WorldRequestFilter): WorldRequestQuery;
|
|
1180
|
+
private static via;
|
|
1181
|
+
private static status;
|
|
1182
|
+
get filtered(): boolean;
|
|
1183
|
+
params(): [string, string][];
|
|
1184
|
+
search(): string;
|
|
1185
|
+
}
|
|
1186
|
+
/** A world's request ledger: every request the world received, from every session and version, through every
|
|
1187
|
+
* door (`via`: api, ui, tool, webhook, page), kept for the world's life. Reading it records nothing. Twin of
|
|
1188
|
+
* `gatewaysdk.world_requests.WorldRequestLedger`. */
|
|
1189
|
+
declare class WorldRequestLedger {
|
|
1190
|
+
private readonly options;
|
|
1191
|
+
constructor(options?: WorldsClientOptions);
|
|
1192
|
+
/** A page of the world's requests, newest first; `nextCursor` reads the page after it. Narrowed to a session
|
|
1193
|
+
* whose engine records none: `WorldRequestsNotRecorded`. */
|
|
1194
|
+
list(slug: string, query?: WorldRequestQuery): Promise<WorldRequestPage>;
|
|
1195
|
+
/** One of the world's requests, with its headers and bodies. */
|
|
1196
|
+
get(slug: string, requestId: string): Promise<WorldRequestEntry>;
|
|
1197
|
+
/** A page of one session's requests, newest first; `WorldRequestsNotRecorded` when its engine records none. */
|
|
1198
|
+
forSession(sessionId: string, query?: WorldRequestQuery): Promise<WorldRequestPage>;
|
|
1093
1199
|
}
|
|
1094
1200
|
|
|
1095
|
-
/**
|
|
1096
|
-
*
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
* bundle and executing it locally tests your agent against a COPY — your
|
|
1100
|
-
* python, your sqlite, your machine's idea of the environment. Dispatching a
|
|
1101
|
-
* hosted run gives you the real container but runs the platform's agent
|
|
1102
|
-
* inside it, so your agent never touches the world.
|
|
1103
|
-
*
|
|
1104
|
-
* A session is both: the platform boots the task's container and holds it
|
|
1105
|
-
* warm, and every `call()` here executes inside THAT container. Your agent
|
|
1106
|
-
* stays where it is — this file is just the wire.
|
|
1107
|
-
*
|
|
1108
|
-
* const world = await openWorld("revenue-ops-sim@main");
|
|
1109
|
-
* const session = await openSession(world.slug, { task: "revops-mara-dedupe-contacts" });
|
|
1110
|
-
* await session.ready(); // wait for the container
|
|
1111
|
-
* await session.call("crm_search", { entity: "deals" });
|
|
1112
|
-
* await session.withTraceContext(() => myAgent(session)); // traced under session.sessionId
|
|
1113
|
-
* const { reward, rewards } = await session.grade();
|
|
1114
|
-
* await session.close({ keepWarm: true }); // hand it back to the pool
|
|
1115
|
-
*
|
|
1116
|
-
* The task can also be YOURS rather than the bundle's — an instruction, the
|
|
1117
|
-
* rows the session starts with and how it is graded, for one end user:
|
|
1118
|
-
*
|
|
1119
|
-
* const session = await openSession("acme-billing@main", {
|
|
1120
|
-
* task: {
|
|
1121
|
-
* instruction: "Mark invoice INV-7 as paid.",
|
|
1122
|
-
* seed: { rows: { invoices: [{ id: "INV-7", status: "open" }] } },
|
|
1123
|
-
* grader: { kind: "assertions", checks: [
|
|
1124
|
-
* { entity: "invoices", where: { id: "INV-7", status: "paid" } },
|
|
1125
|
-
* ] },
|
|
1126
|
-
* metadata: { externalUserId: "u_42" },
|
|
1127
|
-
* },
|
|
1128
|
-
* surfaces: ["api"],
|
|
1129
|
-
* });
|
|
1130
|
-
*
|
|
1131
|
-
* Every call is a row on the platform before it is an effect in a container,
|
|
1132
|
-
* so the episode is on the record — and the platform traces the session
|
|
1133
|
-
* itself, which is why these sessions show up under Sessions without the
|
|
1134
|
-
* caller instrumenting anything.
|
|
1135
|
-
*/
|
|
1136
|
-
type WorldToolSpec = {
|
|
1137
|
-
name: string;
|
|
1138
|
-
/** The world's own signature, e.g. `crm_search(q=None, entity="deals")`. */
|
|
1139
|
-
signature: string;
|
|
1140
|
-
doc: string | null;
|
|
1141
|
-
inputSchema?: Record<string, unknown>;
|
|
1142
|
-
};
|
|
1143
|
-
/** What a model needs to call a world: the schemas to advertise, and the
|
|
1144
|
-
* implementations that run them in the container. */
|
|
1145
|
-
type WorldToolkit = {
|
|
1146
|
-
/** OpenAI-shaped tool definitions, derived from the world's signatures. */
|
|
1147
|
-
schemas: {
|
|
1148
|
-
type: "function";
|
|
1149
|
-
function: {
|
|
1150
|
-
name: string;
|
|
1151
|
-
description: string;
|
|
1152
|
-
parameters: Record<string, unknown>;
|
|
1153
|
-
};
|
|
1154
|
-
}[];
|
|
1155
|
-
/** name -> implementation, each one a call into THIS session. */
|
|
1156
|
-
impls: Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
|
|
1157
|
-
specs: WorldToolSpec[];
|
|
1158
|
-
};
|
|
1159
|
-
|
|
1160
|
-
type SeedResult = {
|
|
1161
|
-
seeded: number;
|
|
1162
|
-
mode: "append" | "replace";
|
|
1163
|
-
entity_counts: Record<string, number>;
|
|
1164
|
-
};
|
|
1165
|
-
/** One row of the session's call log. */
|
|
1166
|
-
type WorldSessionCall = {
|
|
1201
|
+
/** One entry of a world's request ledger as a list carries it: what was asked
|
|
1202
|
+
* and what came back, without its headers and bodies. */
|
|
1203
|
+
type WorldRequest = {
|
|
1204
|
+
id: string;
|
|
1167
1205
|
seq: number;
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
|
|
1171
|
-
result: unknown;
|
|
1172
|
-
error: string | null;
|
|
1173
|
-
completedAt: string | null;
|
|
1174
|
-
};
|
|
1175
|
-
type WorldSessionState = {
|
|
1206
|
+
at: string;
|
|
1207
|
+
durationMs: number | null;
|
|
1208
|
+
worldSlug: string;
|
|
1176
1209
|
sessionId: string;
|
|
1177
|
-
state: string;
|
|
1178
|
-
ready: boolean;
|
|
1179
|
-
versionId: string;
|
|
1180
|
-
contentHash: string;
|
|
1181
|
-
taskName: string | null;
|
|
1182
|
-
/** Where the task came from and what it is; absent on platforms that
|
|
1183
|
-
* predate session tasks, in which case it is derived from `taskName`. */
|
|
1184
|
-
task?: WorldSessionTask;
|
|
1185
|
-
/** The task's objective — present when the session was opened (not on a
|
|
1186
|
-
* bare status read), so a client never needs the bundle on disk. */
|
|
1187
|
-
instruction?: string | null;
|
|
1188
|
-
/** The tools this task serves. */
|
|
1189
|
-
tools?: WorldToolSpec[];
|
|
1190
|
-
/** When the fleet reaps this session unless a call lands first; null for
|
|
1191
|
-
* a pinned session (never reaped). Absent on platforms that predate it. */
|
|
1192
|
-
idleExpiresAt?: string | null;
|
|
1193
|
-
pinned?: boolean;
|
|
1194
|
-
/** Where the session answers besides `tools` — see worlds/browser.ts. */
|
|
1195
|
-
surfaces?: SessionSurfaces;
|
|
1196
|
-
/** Notices about the world's shape (an api bundle is a deprecated layout;
|
|
1197
|
-
* schema worlds are the supported shape), with what to run instead. Empty
|
|
1198
|
-
* for a schema world; absent on platforms that predate the notice. */
|
|
1199
|
-
deprecations?: WorldDeprecation[];
|
|
1200
|
-
/** Why a FAILED session failed to open, when the platform named it. */
|
|
1201
|
-
failure?: {
|
|
1202
|
-
code: string | null;
|
|
1203
|
-
message: string;
|
|
1204
|
-
} | null;
|
|
1205
|
-
};
|
|
1206
|
-
/** A request the old world received has an `at` before `boundaryAt`; one the new world received, after it. */
|
|
1207
|
-
type WorldSessionRestart = {
|
|
1208
|
-
previousVersionId: string;
|
|
1209
1210
|
versionId: string;
|
|
1210
|
-
|
|
1211
|
-
|
|
1212
|
-
|
|
1211
|
+
via: (typeof WORLD_REQUEST_VIAS)[number] | null;
|
|
1212
|
+
operation: string | null;
|
|
1213
|
+
method: string | null;
|
|
1214
|
+
path: string | null;
|
|
1215
|
+
query: Record<string, unknown>;
|
|
1216
|
+
request: {
|
|
1217
|
+
bodyBytes: number | null;
|
|
1218
|
+
truncated: boolean;
|
|
1219
|
+
contentType: string | null;
|
|
1213
1220
|
};
|
|
1214
|
-
|
|
1215
|
-
|
|
1221
|
+
response: {
|
|
1222
|
+
status: number;
|
|
1223
|
+
bodyBytes: number | null;
|
|
1224
|
+
truncated: boolean;
|
|
1225
|
+
contentType: string | null;
|
|
1226
|
+
};
|
|
1227
|
+
rows: number | null;
|
|
1228
|
+
found: boolean | null;
|
|
1216
1229
|
};
|
|
1217
|
-
/** One
|
|
1218
|
-
* and
|
|
1219
|
-
*
|
|
1220
|
-
|
|
1221
|
-
|
|
1222
|
-
|
|
1223
|
-
|
|
1230
|
+
/** One page of a ledger list, newest first, with what its scope did not record: `shed` requests kept without
|
|
1231
|
+
* their headers and bodies, `lost` requests a host counted as never recorded or the platform refused, and
|
|
1232
|
+
* `hostsLost` hosts lost before they stored every request, whose unsent requests no count holds; none of them on
|
|
1233
|
+
* a page whose filters narrow past its world, session or version. */
|
|
1234
|
+
type WorldRequestPage = {
|
|
1235
|
+
requests: WorldRequest[];
|
|
1236
|
+
nextCursor: string | null;
|
|
1237
|
+
shed?: number;
|
|
1238
|
+
lost?: number;
|
|
1239
|
+
hostsLost?: number;
|
|
1224
1240
|
};
|
|
1241
|
+
/** The one line every reader shows for a page's `shed`, `lost` and `hostsLost`, none when all are 0; twin of
|
|
1242
|
+
* `worldRequestsUnrecorded` in the platform and `unrecorded` in `gatewaysdk/world_requests.py`, all pinned to
|
|
1243
|
+
* `conformance/world-request-log.json` `unrecorded`. */
|
|
1244
|
+
declare function worldRequestsUnrecorded(counts: {
|
|
1245
|
+
shed?: unknown;
|
|
1246
|
+
lost?: unknown;
|
|
1247
|
+
hostsLost?: unknown;
|
|
1248
|
+
}): string | null;
|
|
1249
|
+
/**
|
|
1250
|
+
* A session's entries in its world's request ledger: every request the world
|
|
1251
|
+
* received, through every door (`via`: api, ui, tool, webhook, page), kept for the life of
|
|
1252
|
+
* the world. Read page by page without recording anything in the session; the
|
|
1253
|
+
* platform's call ledger (`export()`) holds what it brokered — tool calls,
|
|
1254
|
+
* seeds, grades. One entry's headers and bodies are `GET
|
|
1255
|
+
* worlds/{slug}/requests/{requestId}`.
|
|
1256
|
+
*/
|
|
1257
|
+
declare class WorldRequestLog {
|
|
1258
|
+
readonly requests: WorldRequest[];
|
|
1259
|
+
readonly notRecorded: string | null;
|
|
1260
|
+
readonly unrecorded: string | null;
|
|
1261
|
+
private constructor();
|
|
1262
|
+
/** Every entry the ledger holds for the session, oldest first, and the line for what it did not record;
|
|
1263
|
+
* for a session the World Host did not serve, none, and `notRecorded` says why. */
|
|
1264
|
+
static load(session: WorldSession): Promise<WorldRequestLog>;
|
|
1265
|
+
private static pages;
|
|
1266
|
+
/** Each entry in the shape of a ledger line, `kind: "request"`, so one JSONL
|
|
1267
|
+
* file holds both: `args` what was asked, `result` what came back under the
|
|
1268
|
+
* entry's `requestId`. */
|
|
1269
|
+
asCalls(): WorldSessionCall[];
|
|
1270
|
+
}
|
|
1225
1271
|
|
|
1226
|
-
declare class WorldSession {
|
|
1227
|
-
readonly sessionId: string;
|
|
1228
|
-
private current;
|
|
1229
|
-
private readonly options;
|
|
1230
|
-
constructor(sessionId: string, current: WorldSessionState, options: WorldsClientOptions);
|
|
1231
|
-
/** The task's display name: a bundled scenario's, or the inline spec's
|
|
1232
|
-
* `name` (null when the spec was unnamed). `task` is the same. */
|
|
1233
|
-
get taskName(): string | null;
|
|
1234
|
-
get task(): string | null;
|
|
1235
|
-
/** `{idleExpiresAt, pinned}` as of the last state read: when the fleet
|
|
1236
|
-
* reaps the session (null once pinned), and whether it is pinned. */
|
|
1237
|
-
get idle(): {
|
|
1238
|
-
idleExpiresAt: string | null;
|
|
1239
|
-
pinned: boolean;
|
|
1240
|
-
};
|
|
1241
|
-
/** The platform's notices about the world this session runs on (empty
|
|
1242
|
-
* for a schema world). Printed by the CLI on stderr at open. */
|
|
1243
|
-
get deprecations(): WorldDeprecation[];
|
|
1244
|
-
/** The task this session runs: bundled scenario, stored task or inline
|
|
1245
|
-
* spec, its name, hash and the caller's metadata. */
|
|
1246
|
-
get taskInfo(): WorldSessionTask;
|
|
1247
|
-
/** What this task asks for — the bundle's instruction.md, or the inline
|
|
1248
|
-
* spec's `instruction`. */
|
|
1249
|
-
get instruction(): string | null;
|
|
1250
|
-
get versionId(): string;
|
|
1251
|
-
/** Whether the session answered ready as of the last state read (the open,
|
|
1252
|
-
* a `status()`, or the poll inside `ready()`); no request is made. */
|
|
1253
|
-
get isReady(): boolean;
|
|
1254
|
-
/** `api` / `ui` / `browser` are present exactly when the world declares
|
|
1255
|
-
* them AND the session was opened asking for them. */
|
|
1256
|
-
surfaces(): Promise<SessionSurfaces>;
|
|
1257
|
-
/** Base URL of the world's own HTTP API for this session. */
|
|
1258
|
-
api(): Promise<string>;
|
|
1259
|
-
/** Headers every request to `api()` needs: a World Host session's token in the
|
|
1260
|
-
* platform's `X-World-Session` header, which every world takes; `{}` for a pod
|
|
1261
|
-
* or hosted twin, which answers with the world's own declared auth. */
|
|
1262
|
-
apiHeaders(): Promise<Record<string, string>>;
|
|
1263
|
-
/** URL of the world's UI entry page for this session. */
|
|
1264
|
-
ui(): Promise<string>;
|
|
1265
|
-
/** A Playwright browser on this session's UI: `hosted` drives the one the
|
|
1266
|
-
* platform runs next to the world, `local` launches one here, `auto`
|
|
1267
|
-
* prefers hosted. Call `close()` when done.
|
|
1268
|
-
*
|
|
1269
|
-
* Every action is reported to the platform under `agentId` (default:
|
|
1270
|
-
* `GATEWAY_AGENT_ID` or a fresh `agent-<hex>`) so the session page shows
|
|
1271
|
-
* this agent's own timeline — several agents may share one session and
|
|
1272
|
-
* one hosted browser. `record: false` opts out. */
|
|
1273
|
-
browser(opts?: {
|
|
1274
|
-
mode?: BrowserMode;
|
|
1275
|
-
headless?: boolean;
|
|
1276
|
-
playwright?: PlaywrightLike;
|
|
1277
|
-
agentId?: string;
|
|
1278
|
-
record?: boolean;
|
|
1279
|
-
}): Promise<WorldBrowser>;
|
|
1280
|
-
/** Ask the platform to make this session's hosted browser reachable again
|
|
1281
|
-
* after its connection dropped: `healthy` (reconnect now), `replaced` (a new,
|
|
1282
|
-
* blank browser behind the same wsUrl; reconnect and reopen your page) or
|
|
1283
|
-
* `starting` (ask again in `retryAfterMs`). `browser()` does this on its
|
|
1284
|
-
* own; call it when you drive your own Playwright against `wsUrl`. */
|
|
1285
|
-
repairBrowser(): Promise<RepairAnswer>;
|
|
1286
|
-
/** The reporter `browser()` uses; exposed for a page you drive yourself. */
|
|
1287
|
-
browserRecorder(agentId?: string): BrowserActionRecorder;
|
|
1288
|
-
/** Browser actions as model tools, in the same shape as `toolkit()`. */
|
|
1289
|
-
computerUseTools(browser: WorldBrowser): WorldToolkit;
|
|
1290
|
-
/** The browser as a provider's own pixel-based computer-use tool: `anthropic`
|
|
1291
|
-
* (`computer_toolset_20260801`), `openai` (Responses `computer`),
|
|
1292
|
-
* `anthropic-computer-20251124` or `openai-preview`. See `nativeComputer/`. */
|
|
1293
|
-
nativeComputer<P extends NativeComputerProvider = "anthropic">(browser: WorldBrowser, provider?: P, options?: NativeComputerOptions): NativeComputerKinds[P];
|
|
1294
|
-
/** The session's latest platform state (one request, no waiting). */
|
|
1295
|
-
status(): Promise<WorldSessionState>;
|
|
1296
|
-
/** The world started over under the same id, URLs and token, on what its pin (or `version`, which becomes
|
|
1297
|
-
* its pin) resolves to now: base data plus the task's seed. A grade then reads only the new world's requests. */
|
|
1298
|
-
restart(opts?: {
|
|
1299
|
-
version?: string;
|
|
1300
|
-
}): Promise<WorldSessionState & {
|
|
1301
|
-
restart: WorldSessionRestart;
|
|
1302
|
-
}>;
|
|
1303
|
-
private refresh;
|
|
1304
|
-
/**
|
|
1305
|
-
* Wait until the session answers calls: a World Host holds it, or the
|
|
1306
|
-
* process inside a pod has asked the platform for work. Throws
|
|
1307
|
-
* `WorldSessionOpenFailed` (with the platform's reason) when it ended
|
|
1308
|
-
* first, and `WorldSessionTimeout` when `timeoutMs` (default ten minutes)
|
|
1309
|
-
* ran out while it was still starting.
|
|
1310
|
-
*/
|
|
1311
|
-
ready(opts?: {
|
|
1312
|
-
timeoutMs?: number;
|
|
1313
|
-
}): Promise<WorldSessionState>;
|
|
1314
|
-
/** Enqueue one interaction and wait for the container's answer. */
|
|
1315
|
-
private exchange;
|
|
1316
|
-
/**
|
|
1317
|
-
* Run one of the world's tools INSIDE the container. The arguments and the
|
|
1318
|
-
* result are the world's own contract — this layer neither validates nor
|
|
1319
|
-
* reshapes them, so a tool error reads exactly as it would in a hosted run.
|
|
1320
|
-
*/
|
|
1321
|
-
call(tool: string, args?: Record<string, unknown>, opts?: {
|
|
1322
|
-
timeoutMs?: number;
|
|
1323
|
-
}): Promise<unknown>;
|
|
1324
|
-
/**
|
|
1325
|
-
* THE WORLD'S TOOLS, READY TO HAND TO A MODEL. Schemas come from the
|
|
1326
|
-
* world's own signatures and implementations call into this session, so a
|
|
1327
|
-
* caller never writes — and never has to re-sync — a tool map of their own:
|
|
1328
|
-
*
|
|
1329
|
-
* const { schemas, impls } = await session.toolkit();
|
|
1330
|
-
* await runMyAgent(impls, schemas, session.instruction);
|
|
1331
|
-
*
|
|
1332
|
-
* A tool added to the world shows up here on the next run; a tool renamed
|
|
1333
|
-
* in the world renames here too, instead of failing at call time against a
|
|
1334
|
-
* hand-written map that still remembers the old name.
|
|
1335
|
-
*/
|
|
1336
|
-
toolkit(): Promise<WorldToolkit>;
|
|
1337
|
-
/** Run the task's grader against the container's END STATE. Graders answer
|
|
1338
|
-
* in one of two shapes: the scalar with named rewards beside it
|
|
1339
|
-
* (`{reward, check_a, check_b}`, a task's own `grade.py`), or the named
|
|
1340
|
-
* rewards nested under `rewards` (the api, mock-tools and World Host
|
|
1341
|
-
* runners). Both land in `rewards`.
|
|
1342
|
-
*
|
|
1343
|
-
* A rubric grade is finalized by the platform's judge, not the container:
|
|
1344
|
-
* the platform answers the enqueue with `pending: true`, and this waits on
|
|
1345
|
-
* the judge's budget (15 min) instead of a call's. `timeoutMs` overrides
|
|
1346
|
-
* either. `report` is the agent's own account of what it did and found,
|
|
1347
|
-
* handed to the judge as its claim beside the evidence (the state and the
|
|
1348
|
-
* calls); assertions and python graders ignore it. `worlds` names the
|
|
1349
|
-
* task's other sessions by alias (`{alias: sessionId}`): the platform
|
|
1350
|
-
* reads each one's evidence and hands it to the cross-world verifiers
|
|
1351
|
-
* anchored on this session, whose grades come back under `verifiers`. A
|
|
1352
|
-
* score that is not a number from 0 to 1 is refused by key and value
|
|
1353
|
-
* (`GradeRefused`); a verifier's is that verifier's `error`. */
|
|
1354
|
-
grade(opts?: {
|
|
1355
|
-
timeoutMs?: number;
|
|
1356
|
-
report?: string;
|
|
1357
|
-
worlds?: Record<string, string>;
|
|
1358
|
-
}): Promise<GradeResult>;
|
|
1359
|
-
/**
|
|
1360
|
-
* Put rows into the LIVE world through its contract, in one batch:
|
|
1361
|
-
* `append` (default) upserts by primary key, `replace` makes the named
|
|
1362
|
-
* entities hold exactly these rows. Atomic — a refused row leaves the
|
|
1363
|
-
* session unchanged and the error names the entity, row and field.
|
|
1364
|
-
*/
|
|
1365
|
-
seed(rows: Record<string, Record<string, unknown>[]>, opts?: {
|
|
1366
|
-
mode?: "append" | "replace";
|
|
1367
|
-
/** `apply` runs the world's `[redact]` policy over the rows first;
|
|
1368
|
-
* `refuse` rejects plaintext in a redacted field; default `off`. */
|
|
1369
|
-
redact?: "off" | "apply" | "refuse";
|
|
1370
|
-
timeoutMs?: number;
|
|
1371
|
-
}): Promise<SeedResult>;
|
|
1372
|
-
/** Every entity's rows as the world holds them now — the same dump a
|
|
1373
|
-
* grader reads. The shape is the world runtime's: a schema world answers
|
|
1374
|
-
* `{<entity>: {<key>: row}, snapshot}`, a mock-tools world
|
|
1375
|
-
* `{entities: {<entity>: [row]}}`. */
|
|
1376
|
-
state(opts?: {
|
|
1377
|
-
timeoutMs?: number;
|
|
1378
|
-
}): Promise<unknown>;
|
|
1379
|
-
/** Back to the opening state: the version's data plus the bundled
|
|
1380
|
-
* scenario's or the inline task's seed. Rows written since are gone; the
|
|
1381
|
-
* call log stays. */
|
|
1382
|
-
reset(opts?: {
|
|
1383
|
-
timeoutMs?: number;
|
|
1384
|
-
}): Promise<void>;
|
|
1385
|
-
/** One page of the session's entries in its world's request ledger, newest
|
|
1386
|
-
* first and without bodies: at most `limit` after `cursor` (the last page's
|
|
1387
|
-
* `nextCursor`). Reading it records nothing in the session. */
|
|
1388
|
-
requests(opts?: {
|
|
1389
|
-
cursor?: string;
|
|
1390
|
-
limit?: number;
|
|
1391
|
-
}): Promise<WorldRequestPage>;
|
|
1392
|
-
private page;
|
|
1393
|
-
/** The session's call log, oldest first: every tool call, seed, reset,
|
|
1394
|
-
* grade with its result — the record of the episode. */
|
|
1395
|
-
export(): Promise<WorldSessionCall[]>;
|
|
1396
|
-
/**
|
|
1397
|
-
* Promote this session's inline task into a stored task of the project
|
|
1398
|
-
* (version 1, pinned to the session's world unless `world` says otherwise),
|
|
1399
|
-
* so a task written for one end user can be reused and its grades
|
|
1400
|
-
* compared. The session then records the new task's id. A session on a
|
|
1401
|
-
* bundled task has nothing to save; one on a stored task is already saved.
|
|
1402
|
-
*/
|
|
1403
|
-
saveTask(opts?: {
|
|
1404
|
-
name?: string;
|
|
1405
|
-
world?: string | null;
|
|
1406
|
-
message?: string;
|
|
1407
|
-
}): Promise<WorldTaskSummary>;
|
|
1408
|
-
/**
|
|
1409
|
-
* End the session. `keepWarm` hands the container back to the pool instead
|
|
1410
|
-
* of tearing it down, so the next session for the same task starts warm —
|
|
1411
|
-
* the pooled instance still obeys the fleet's idle TTL and pinning.
|
|
1412
|
-
*/
|
|
1413
|
-
close(opts?: {
|
|
1414
|
-
keepWarm?: boolean;
|
|
1415
|
-
}): Promise<{
|
|
1416
|
-
state: string;
|
|
1417
|
-
}>;
|
|
1418
|
-
/**
|
|
1419
|
-
* Run `fn` as work inside this session: spans it records take `sessionId`
|
|
1420
|
-
* as their session id and carry `world_session_id` trace metadata, so the
|
|
1421
|
-
* agent's traces land in the same session as the platform's traces of this
|
|
1422
|
-
* session's tool calls. A `withSession()` block inside still wins for the
|
|
1423
|
-
* session id. No effect before `tracing.init()`. `runSessions` wraps each
|
|
1424
|
-
* agent call in it.
|
|
1425
|
-
*
|
|
1426
|
-
* ```typescript
|
|
1427
|
-
* await session.withTraceContext(() => myAgent(toolkit, session.instruction));
|
|
1428
|
-
* ```
|
|
1429
|
-
*/
|
|
1430
|
-
withTraceContext<T>(fn: () => T | Promise<T>): Promise<T>;
|
|
1431
|
-
}
|
|
1432
|
-
/**
|
|
1433
|
-
* Attach to a session that already exists — resuming after a crash, or
|
|
1434
|
-
* driving a session someone else opened (a container started by hand on a
|
|
1435
|
-
* self-hosted install, a session opened by CI and handed to a developer).
|
|
1436
|
-
*/
|
|
1437
|
-
declare function attachSession(sessionId: string, options?: WorldsClientOptions): Promise<WorldSession>;
|
|
1438
|
-
type OpenSessionOptions = {
|
|
1439
|
-
versionId?: string;
|
|
1440
|
-
reuseWarm?: boolean;
|
|
1441
|
-
/** More than `tools`: `["api"]`, `["ui"]`, `["browser"]`. The platform
|
|
1442
|
-
* refuses (HTTP 400) rather than quietly serving less than asked. */
|
|
1443
|
-
surfaces?: WorldSurfaceKind[];
|
|
1444
|
-
/** Capacity for a World Host session's browser: `standard` (spot, may be
|
|
1445
|
-
* reclaimed) or `premium` (on-demand). Unset, the organization's default. */
|
|
1446
|
-
browserTier?: BrowserTier;
|
|
1447
|
-
/** `open`: the session asks for no credential; its api and ui answer on a
|
|
1448
|
-
* capability hostname whose url is the secret. Unset, the world's
|
|
1449
|
-
* `[auth] mode`. World Host sessions only. */
|
|
1450
|
-
auth?: SessionAuthMode;
|
|
1451
|
-
options?: WorldsClientOptions;
|
|
1452
|
-
};
|
|
1453
1272
|
/**
|
|
1454
|
-
*
|
|
1455
|
-
*
|
|
1456
|
-
*
|
|
1457
|
-
*
|
|
1458
|
-
* or an inline `WorldTaskSpec` (the latter two need a host engine world — the
|
|
1459
|
-
* platform answers 400 for a pod world). Omitted, the session is EXPLORATORY:
|
|
1460
|
-
* the platform records an inline `{instruction: "exploratory session"}` with
|
|
1461
|
-
* no grader as `task.source: "none"`, and `grade()` answers
|
|
1462
|
-
* `{reward: null, reason: "no grader"}`. The older positional form
|
|
1463
|
-
* `openSession(slug, "task-name", opts)` still works.
|
|
1273
|
+
* A world's grade as the SDK reads it, by the one score rule every grader
|
|
1274
|
+
* answers by: a finite number from 0 to 1, a passed check 1, a failed one 0,
|
|
1275
|
+
* null ungraded. The World Host's twin is `gatewaysdk/environment/score.py`;
|
|
1276
|
+
* both are pinned by `gatewaysdk/fixtures/tasks/grade-vectors.json`.
|
|
1464
1277
|
*/
|
|
1465
|
-
declare
|
|
1466
|
-
|
|
1467
|
-
}): Promise<WorldSession>;
|
|
1468
|
-
declare function openSession(slugOrRef: string, task: WorldTaskRef, opts?: OpenSessionOptions): Promise<WorldSession>;
|
|
1469
|
-
type SessionRunResult = {
|
|
1470
|
-
/** The task's name, or `inline:<hash>` for an unnamed inline task. */
|
|
1471
|
-
task: string;
|
|
1472
|
-
sessionId: string;
|
|
1278
|
+
declare const messageOf: (error: unknown) => string;
|
|
1279
|
+
type GradeResult = {
|
|
1473
1280
|
reward: number | null;
|
|
1474
1281
|
rewards: Record<string, number>;
|
|
1475
|
-
/**
|
|
1282
|
+
/** Why there is no reward: `no grader` on an exploratory session. */
|
|
1283
|
+
reason?: string;
|
|
1284
|
+
/** Why this world could not grade; the task's grade is then that error. */
|
|
1476
1285
|
error?: string;
|
|
1286
|
+
/** The task's cross-world verifiers anchored on this session, by name:
|
|
1287
|
+
* each its own reward and named rewards, or `error` when it could not
|
|
1288
|
+
* grade (evidence missing, verify.py failed) — null, never zero. */
|
|
1289
|
+
verifiers?: Record<string, VerifierGrade>;
|
|
1290
|
+
raw: unknown;
|
|
1477
1291
|
};
|
|
1478
|
-
type
|
|
1479
|
-
|
|
1480
|
-
|
|
1481
|
-
|
|
1482
|
-
/** Tasks that never graded: the session did not open or become ready, the
|
|
1483
|
-
* agent threw, or grading failed. Any failure fails the run — a 0 an agent
|
|
1484
|
-
* earned and a session that never opened are not the same result. */
|
|
1485
|
-
failed: number;
|
|
1486
|
-
/** True when no task failed and `mean >= failUnder` (or no gate was set). */
|
|
1487
|
-
passed: boolean;
|
|
1292
|
+
type VerifierGrade = {
|
|
1293
|
+
reward: number | null;
|
|
1294
|
+
rewards: Record<string, number>;
|
|
1295
|
+
error?: string;
|
|
1488
1296
|
};
|
|
1489
|
-
|
|
1490
|
-
|
|
1491
|
-
|
|
1492
|
-
|
|
1493
|
-
|
|
1494
|
-
|
|
1495
|
-
|
|
1496
|
-
|
|
1497
|
-
|
|
1498
|
-
*
|
|
1499
|
-
*
|
|
1500
|
-
*
|
|
1501
|
-
|
|
1502
|
-
|
|
1503
|
-
|
|
1504
|
-
|
|
1505
|
-
|
|
1506
|
-
|
|
1507
|
-
|
|
1508
|
-
|
|
1509
|
-
|
|
1510
|
-
|
|
1511
|
-
*/
|
|
1512
|
-
|
|
1513
|
-
|
|
1514
|
-
|
|
1515
|
-
|
|
1516
|
-
|
|
1517
|
-
|
|
1518
|
-
|
|
1519
|
-
|
|
1520
|
-
|
|
1521
|
-
|
|
1522
|
-
|
|
1523
|
-
|
|
1524
|
-
|
|
1525
|
-
|
|
1526
|
-
|
|
1527
|
-
/** The task's label — see `SessionRunResult.task`. */
|
|
1528
|
-
task: string;
|
|
1529
|
-
/** The task as it was given: a bundled name, a stored ref or the
|
|
1530
|
-
* inline spec. */
|
|
1531
|
-
taskRef: WorldTaskRef;
|
|
1532
|
-
}) => Promise<unknown>;
|
|
1533
|
-
onResult?: (result: SessionRunResult) => void;
|
|
1534
|
-
options?: WorldsClientOptions;
|
|
1535
|
-
}): Promise<SessionRunReport>;
|
|
1297
|
+
declare class Score {
|
|
1298
|
+
static readonly RULE = "a score is a number from 0 to 1";
|
|
1299
|
+
static admits(value: number): boolean;
|
|
1300
|
+
/** Every number among `scores` that is not a score, as `'<key>' = <value>`
|
|
1301
|
+
* and the rule, or null when all of them are. Pairs, not a map, so that no
|
|
1302
|
+
* key hides another. */
|
|
1303
|
+
static problem(scores: Iterable<[string, unknown]>): string | null;
|
|
1304
|
+
}
|
|
1305
|
+
/** A world's grade that is never filed: it is not an object, a number in it
|
|
1306
|
+
* is not a score (a World Host older than the rule), a check is named both
|
|
1307
|
+
* beside and inside its rewards, or its rewards or verifiers are not objects
|
|
1308
|
+
* by name. */
|
|
1309
|
+
declare class GradeRefused extends Error {
|
|
1310
|
+
readonly name = "GradeRefused";
|
|
1311
|
+
}
|
|
1312
|
+
declare class GradePayload {
|
|
1313
|
+
/** A grade payload's numbers, checked: every number in it must be a score,
|
|
1314
|
+
* and its rewards and verifiers objects by name, or the grade is refused; a
|
|
1315
|
+
* cross-world verifier's grade that breaks either rule is that verifier's
|
|
1316
|
+
* error, the way the World Host answers one that could not grade. */
|
|
1317
|
+
static read(raw: unknown): Omit<GradeResult, "raw">;
|
|
1318
|
+
/** A world whose grade call failed (the platform refused it, the host had
|
|
1319
|
+
* lost the session): that world's error, never a score. */
|
|
1320
|
+
static failedCall(error: unknown): GradeResult;
|
|
1321
|
+
private static problem;
|
|
1322
|
+
private static twice;
|
|
1323
|
+
private static verifiersProblem;
|
|
1324
|
+
private static scores;
|
|
1325
|
+
private static isRecord;
|
|
1326
|
+
private static objectOrAbsent;
|
|
1327
|
+
private static record;
|
|
1328
|
+
/** `reward`, and every numeric key under `rewards` (the host's shape) or at
|
|
1329
|
+
* the top level (a bundled verifier's). */
|
|
1330
|
+
private static numbers;
|
|
1331
|
+
private static verifiers;
|
|
1332
|
+
private static verifier;
|
|
1333
|
+
private static failed;
|
|
1334
|
+
}
|
|
1536
1335
|
|
|
1336
|
+
/** A JSON scalar: what `where` filters and field predicates compare against. */
|
|
1337
|
+
type WorldTaskScalar = string | number | boolean | null;
|
|
1338
|
+
/** The rows a task starts the session with — the `seed()` contract, applied
|
|
1339
|
+
* by the host right after it clones the version's snapshot. `append`
|
|
1340
|
+
* (default) upserts by primary key onto the base data; `replace` makes the
|
|
1341
|
+
* named entities hold exactly these rows. */
|
|
1342
|
+
type WorldTaskSeed = {
|
|
1343
|
+
mode?: "append" | "replace";
|
|
1344
|
+
/** Redaction on the way in: `off` (default) stores the rows as given,
|
|
1345
|
+
* `apply` runs the world's `[redact]` policy over them first, `refuse`
|
|
1346
|
+
* rejects a row carrying plaintext in a redacted field. */
|
|
1347
|
+
redact?: "off" | "apply" | "refuse";
|
|
1348
|
+
rows: Record<string, Record<string, unknown>[]>;
|
|
1349
|
+
};
|
|
1350
|
+
type WorldTaskFieldOp = "eq" | "neq" | "in" | "gt" | "gte" | "lt" | "lte" | "contains";
|
|
1537
1351
|
/**
|
|
1538
|
-
*
|
|
1539
|
-
*
|
|
1540
|
-
*
|
|
1541
|
-
* operations over the rendezvous). An api-type world may also answer on
|
|
1542
|
-
* `api` (the service itself), `ui` (its dashboard, over the same state) and
|
|
1543
|
-
* `browser` — a headless Chromium the platform runs NEXT TO that UI, which
|
|
1544
|
-
* an agent drives through Playwright. This file is the TS client for the
|
|
1545
|
-
* last two, call for call with `gatewaysdk/world_browser.py`.
|
|
1546
|
-
*
|
|
1547
|
-
* const s = await openSession("payments-like", "refund-dispute", {
|
|
1548
|
-
* surfaces: ["ui", "browser"],
|
|
1549
|
-
* });
|
|
1550
|
-
* await s.ready();
|
|
1551
|
-
* const b = await s.browser(); // hosted, next to the world
|
|
1552
|
-
* await b.goto(); // the UI's entry page
|
|
1553
|
-
* await b.click("text=Refund");
|
|
1554
|
-
* const tools = computerUseToolkit(b); // the same actions as model tools
|
|
1555
|
-
* await b.close();
|
|
1556
|
-
*
|
|
1557
|
-
* Playwright is an OPTIONAL peer: nothing here imports it until a browser is
|
|
1558
|
-
* opened, so sessions that never touch a UI never load it.
|
|
1559
|
-
*
|
|
1560
|
-
* MODES. `hosted` connects to the session's own browser (a Playwright server
|
|
1561
|
-
* the pod exposes over an authenticated websocket). `local` launches Chromium
|
|
1562
|
-
* on this machine and points it at the UI — a laptop against a hosted twin,
|
|
1563
|
-
* or a test. `auto` prefers hosted. Asking for a mode the session cannot
|
|
1564
|
-
* serve throws `WorldSurfaceUnavailable`; there is no silent fallback to a
|
|
1565
|
-
* browser other than the one the episode is judged on.
|
|
1352
|
+
* One declarative check over the session's final rows. `where` selects rows
|
|
1353
|
+
* of `entity` by equality (dotted paths reach into nested objects); the
|
|
1354
|
+
* assertion says what must hold of the selection:
|
|
1566
1355
|
*
|
|
1567
|
-
*
|
|
1568
|
-
*
|
|
1569
|
-
*
|
|
1570
|
-
* after — through a `BrowserActionRecorder`. Reporting is fire-and-forget
|
|
1571
|
-
* and never fails the action; the platform renders it as the session's
|
|
1572
|
-
* browser timeline. Text typed into secret-looking fields is redacted before
|
|
1573
|
-
* it leaves the process.
|
|
1356
|
+
* exists (default) / absent at least one row / none
|
|
1357
|
+
* count `count` bound on how many
|
|
1358
|
+
* all / any `field op value` on every / some selected row
|
|
1574
1359
|
*
|
|
1575
|
-
*
|
|
1576
|
-
*
|
|
1577
|
-
* gone, a hosted `cdp` browser asks the platform to repair it, reconnects to
|
|
1578
|
-
* the same address and reopens the page it was on (see `browserReconnect.ts`).
|
|
1579
|
-
* A read or a `goto` then runs once more; a click, type, press, back or scroll
|
|
1580
|
-
* is NOT replayed — its input may already have reached the world — and throws
|
|
1581
|
-
* `BrowserReconnected` so the agent looks at the page again. Local and
|
|
1582
|
-
* `playwright`-protocol browsers never reconnect.
|
|
1360
|
+
* A check's `id` names its entry in `rewards`; the task's reward is the
|
|
1361
|
+
* weighted share of checks that passed.
|
|
1583
1362
|
*/
|
|
1584
|
-
|
|
1585
|
-
|
|
1586
|
-
|
|
1587
|
-
|
|
1588
|
-
|
|
1589
|
-
|
|
1590
|
-
|
|
1591
|
-
|
|
1592
|
-
|
|
1593
|
-
|
|
1594
|
-
declare function assertSessionAuthMode(value: unknown): asserts value is SessionAuthMode;
|
|
1595
|
-
/** Capacity behind a World Host session's browser. `standard` runs on spot
|
|
1596
|
-
* capacity first (about half the price) and may be reclaimed with two
|
|
1597
|
-
* minutes' notice, ending the browser but never the world; `premium` is
|
|
1598
|
-
* on-demand and never spot-reclaimed. Unset, the organization's default applies. */
|
|
1599
|
-
declare const BROWSER_TIERS: readonly ["standard", "premium"];
|
|
1600
|
-
type BrowserTier = (typeof BROWSER_TIERS)[number];
|
|
1601
|
-
/** Refuse a tier the platform does not know, before any request is sent. */
|
|
1602
|
-
declare function assertBrowserTier(value: unknown): asserts value is BrowserTier;
|
|
1603
|
-
declare const DEFAULT_VIEWPORT: {
|
|
1604
|
-
width: number;
|
|
1605
|
-
height: number;
|
|
1606
|
-
};
|
|
1607
|
-
declare const EVENT_BATCH_SIZE = 10;
|
|
1608
|
-
declare const EVENT_FLUSH_INTERVAL_MS = 1000;
|
|
1609
|
-
declare const EVENT_MAX_RETRIES = 3;
|
|
1610
|
-
declare const SECRET_KEY: RegExp;
|
|
1611
|
-
/** What a call that lost its browser does once the browser is back: a read or
|
|
1612
|
-
* a navigation runs again (`retry`); an action that may already have reached
|
|
1613
|
-
* the world is not replayed, and the agent is told (`report`). */
|
|
1614
|
-
type OnBrowserLoss = "retry" | "report";
|
|
1615
|
-
/** The `surfaces` block of a session descriptor, as the platform sends it. */
|
|
1616
|
-
type SessionSurfaces = {
|
|
1617
|
-
tools: {
|
|
1618
|
-
kind: "rendezvous";
|
|
1619
|
-
};
|
|
1620
|
-
api?: {
|
|
1621
|
-
url: string;
|
|
1622
|
-
/** Per-session credential of a World Host session: send it in the
|
|
1623
|
-
* platform's `X-World-Session` header (`apiHeaders()`), or the way the
|
|
1624
|
-
* world's `[auth]` says its vendor takes a key. Absent when the world
|
|
1625
|
-
* itself answers with its declared auth (a pod or a customer-hosted twin),
|
|
1626
|
-
* and for an open session, whose url is its secret. */
|
|
1627
|
-
token?: string;
|
|
1628
|
-
/** `open`: `url` is the session's capability hostname; send no credential. */
|
|
1629
|
-
auth?: "open";
|
|
1630
|
-
};
|
|
1631
|
-
ui?: {
|
|
1632
|
-
url: string;
|
|
1633
|
-
entry: string;
|
|
1634
|
-
/** Same-origin prefix the UI proxies to the world API, e.g. `/__world-api`;
|
|
1635
|
-
* null when the UI only reaches the API server-side. */
|
|
1636
|
-
apiPath?: string | null;
|
|
1637
|
-
/** Per-session credential of a World Host UI. A browser navigation cannot
|
|
1638
|
-
* carry a header, so the first page load presents it once as `?token=`
|
|
1639
|
-
* and the host answers with an HttpOnly cookie. Absent for pod UIs and
|
|
1640
|
-
* open sessions. */
|
|
1641
|
-
token?: string;
|
|
1642
|
-
auth?: "open";
|
|
1363
|
+
type WorldTaskCheck = {
|
|
1364
|
+
id?: string;
|
|
1365
|
+
weight?: number;
|
|
1366
|
+
entity: string;
|
|
1367
|
+
where?: Record<string, WorldTaskScalar>;
|
|
1368
|
+
assert?: "exists" | "absent" | "count" | "all" | "any";
|
|
1369
|
+
count?: {
|
|
1370
|
+
eq?: number;
|
|
1371
|
+
gte?: number;
|
|
1372
|
+
lte?: number;
|
|
1643
1373
|
};
|
|
1644
|
-
|
|
1645
|
-
|
|
1646
|
-
|
|
1647
|
-
|
|
1648
|
-
|
|
1649
|
-
|
|
1650
|
-
|
|
1651
|
-
|
|
1652
|
-
|
|
1653
|
-
|
|
1654
|
-
|
|
1374
|
+
field?: string;
|
|
1375
|
+
op?: WorldTaskFieldOp;
|
|
1376
|
+
value?: WorldTaskScalar | WorldTaskScalar[];
|
|
1377
|
+
/** On `gateway_requests` or `calls`: only the requests before the first one this matches. */
|
|
1378
|
+
before?: Record<string, WorldTaskScalar>;
|
|
1379
|
+
/** On `gateway_requests` or `calls`: only the requests after the first one this matches. */
|
|
1380
|
+
after?: Record<string, WorldTaskScalar>;
|
|
1381
|
+
};
|
|
1382
|
+
/** One thing a rubric judge scores in [0, 1]; `id` names its entry in
|
|
1383
|
+
* `rewards`, `weight` (default 1) its share of the task's reward. */
|
|
1384
|
+
type WorldTaskRubricCriterion = {
|
|
1385
|
+
id: string;
|
|
1386
|
+
description: string;
|
|
1387
|
+
weight?: number;
|
|
1388
|
+
};
|
|
1389
|
+
/** A rubric is prose: what a good outcome looks like. The platform (never the
|
|
1390
|
+
* host) has a model read the session's final state and its call log against
|
|
1391
|
+
* it; the project's default evaluation model judges unless `model` pins one.
|
|
1392
|
+
* `grade()` then resolves asynchronously — `pending: true` first, the reward
|
|
1393
|
+
* once the judge has answered. */
|
|
1394
|
+
type WorldTaskRubricGrader = {
|
|
1395
|
+
kind: "rubric";
|
|
1396
|
+
rubric: string;
|
|
1397
|
+
criteria?: WorldTaskRubricCriterion[];
|
|
1398
|
+
model?: {
|
|
1399
|
+
provider: string;
|
|
1400
|
+
model: string;
|
|
1655
1401
|
};
|
|
1656
1402
|
};
|
|
1657
|
-
|
|
1658
|
-
|
|
1659
|
-
|
|
1660
|
-
|
|
1661
|
-
|
|
1662
|
-
|
|
1663
|
-
|
|
1664
|
-
|
|
1665
|
-
|
|
1666
|
-
|
|
1667
|
-
|
|
1668
|
-
|
|
1669
|
-
|
|
1670
|
-
|
|
1671
|
-
|
|
1672
|
-
|
|
1673
|
-
|
|
1674
|
-
|
|
1675
|
-
|
|
1676
|
-
|
|
1677
|
-
|
|
1678
|
-
|
|
1679
|
-
|
|
1680
|
-
|
|
1681
|
-
|
|
1682
|
-
|
|
1683
|
-
|
|
1684
|
-
|
|
1685
|
-
|
|
1686
|
-
|
|
1687
|
-
|
|
1688
|
-
|
|
1689
|
-
|
|
1690
|
-
|
|
1691
|
-
|
|
1692
|
-
|
|
1693
|
-
|
|
1694
|
-
|
|
1695
|
-
|
|
1696
|
-
|
|
1403
|
+
/** How a task is graded: checks the host evaluates in-process, a `verify.py`
|
|
1404
|
+
* body (state JSON on stdin, last stdout line `{reward, ...}`) run through the
|
|
1405
|
+
* host's confined verifier, or a rubric judged by a model on the platform. */
|
|
1406
|
+
type WorldTaskGrader = {
|
|
1407
|
+
kind: "assertions";
|
|
1408
|
+
checks: WorldTaskCheck[];
|
|
1409
|
+
} | {
|
|
1410
|
+
kind: "python";
|
|
1411
|
+
source: string;
|
|
1412
|
+
timeoutSeconds?: number;
|
|
1413
|
+
readsJournal?: boolean;
|
|
1414
|
+
acceptsIncompleteJournal?: boolean;
|
|
1415
|
+
} | WorldTaskRubricGrader;
|
|
1416
|
+
/** A task supplied at open, for one session, instead of a bundled scenario.
|
|
1417
|
+
* `instruction` is what the agent is told; without `seed` the session starts
|
|
1418
|
+
* on the version's base data, without `grader` `grade()` answers
|
|
1419
|
+
* `reward: null`; `tools` is the allow-list of the version's tools the agent
|
|
1420
|
+
* may call in this session (unset: all of them; a call outside it is refused
|
|
1421
|
+
* and logged); `metadata` is yours (an end-user id, a ticket) and is echoed
|
|
1422
|
+
* on the session, never read. Limits: shared/domain/worldTasks.ts. */
|
|
1423
|
+
type WorldTaskSpec = {
|
|
1424
|
+
name?: string;
|
|
1425
|
+
instruction: string;
|
|
1426
|
+
seed?: WorldTaskSeed;
|
|
1427
|
+
grader?: WorldTaskGrader;
|
|
1428
|
+
tools?: string[];
|
|
1429
|
+
metadata?: Record<string, unknown>;
|
|
1430
|
+
/** A MULTI-WORLD task: one session per alias, each on its own world with
|
|
1431
|
+
* its own seed, grader and tools (the top-level three are then refused).
|
|
1432
|
+
* Brought up together by `openTask` / `gateway worlds task up`; see
|
|
1433
|
+
* worlds/taskSessions.ts. */
|
|
1434
|
+
worlds?: Record<string, {
|
|
1435
|
+
slug: string;
|
|
1436
|
+
/** One of the world's refs; default `main`. */
|
|
1437
|
+
ref?: string;
|
|
1438
|
+
seed?: WorldTaskSeed;
|
|
1439
|
+
grader?: WorldTaskGrader;
|
|
1440
|
+
tools?: string[];
|
|
1441
|
+
}>;
|
|
1442
|
+
/** CROSS-WORLD VERIFIERS: deterministic graders over several of the task's
|
|
1443
|
+
* worlds at once, each with a `scope` of aliases (two or more). One runs on
|
|
1444
|
+
* the session of the first alias in its scope, over a state where every
|
|
1445
|
+
* scoped world's rows are `<alias>.<entity>` and its calls `<alias>.calls`;
|
|
1446
|
+
* the platform gathers the other worlds' evidence when `grade()` names
|
|
1447
|
+
* them (`TaskSessions.grade` does). Rewards come back as `x.<name>`. */
|
|
1448
|
+
verifiers?: WorldTaskVerifier[];
|
|
1697
1449
|
};
|
|
1698
|
-
type
|
|
1699
|
-
|
|
1700
|
-
|
|
1701
|
-
|
|
1702
|
-
|
|
1450
|
+
type WorldTaskVerifier = {
|
|
1451
|
+
name: string;
|
|
1452
|
+
scope: string[];
|
|
1453
|
+
} & ({
|
|
1454
|
+
kind: "assertions";
|
|
1455
|
+
checks: WorldTaskCheck[];
|
|
1456
|
+
} | {
|
|
1457
|
+
kind: "python";
|
|
1458
|
+
source: string;
|
|
1459
|
+
timeoutSeconds?: number;
|
|
1460
|
+
});
|
|
1461
|
+
/** A stored task of the project (see worlds/tasks.ts), opened by id; the
|
|
1462
|
+
* session runs a copy of one version's spec — the current one by default. */
|
|
1463
|
+
type WorldTaskIdRef = {
|
|
1464
|
+
id: string;
|
|
1465
|
+
version?: number;
|
|
1466
|
+
};
|
|
1467
|
+
/** What `openSession` takes as the task: a bundled scenario's name, a
|
|
1468
|
+
* stored task's `{ id, version? }`, or an inline spec. */
|
|
1469
|
+
type WorldTaskRef = string | WorldTaskIdRef | WorldTaskSpec;
|
|
1470
|
+
/** What a session's task is, on every session response. `hash` is the
|
|
1471
|
+
* content hash of the spec (inline or stored) — what warm reuse matches on;
|
|
1472
|
+
* `id`/`version` name the stored task the session was opened on. */
|
|
1473
|
+
type WorldSessionTask = {
|
|
1474
|
+
/** `none` is an exploratory session: opened with no task, no grader. */
|
|
1475
|
+
source: "bundled" | "inline" | "stored" | "none";
|
|
1476
|
+
name: string | null;
|
|
1477
|
+
hash: string | null;
|
|
1478
|
+
id?: string | null;
|
|
1479
|
+
version?: number | null;
|
|
1480
|
+
metadata: Record<string, unknown>;
|
|
1481
|
+
};
|
|
1482
|
+
|
|
1483
|
+
type WorldToolSpec = {
|
|
1484
|
+
name: string;
|
|
1485
|
+
/** The world's own signature, e.g. `crm_search(q=None, entity="deals")`. */
|
|
1486
|
+
signature: string;
|
|
1487
|
+
doc: string | null;
|
|
1488
|
+
inputSchema?: Record<string, unknown>;
|
|
1489
|
+
};
|
|
1490
|
+
/** What a model needs to call a world: the schemas to advertise, and the
|
|
1491
|
+
* implementations that run them in the container. */
|
|
1492
|
+
type WorldToolkit = {
|
|
1493
|
+
/** OpenAI-shaped tool definitions, derived from the world's signatures. */
|
|
1494
|
+
schemas: {
|
|
1495
|
+
type: "function";
|
|
1496
|
+
function: {
|
|
1497
|
+
name: string;
|
|
1498
|
+
description: string;
|
|
1499
|
+
parameters: Record<string, unknown>;
|
|
1500
|
+
};
|
|
1501
|
+
}[];
|
|
1502
|
+
/** name -> implementation, each one a call into THIS session. */
|
|
1503
|
+
impls: Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
|
|
1504
|
+
specs: WorldToolSpec[];
|
|
1505
|
+
};
|
|
1506
|
+
type SeedResult = {
|
|
1507
|
+
seeded: number;
|
|
1508
|
+
mode: "append" | "replace";
|
|
1509
|
+
entity_counts: Record<string, number>;
|
|
1510
|
+
};
|
|
1511
|
+
/** One row of the session's call log. */
|
|
1512
|
+
type WorldSessionCall = {
|
|
1703
1513
|
seq: number;
|
|
1704
|
-
|
|
1705
|
-
|
|
1706
|
-
args:
|
|
1707
|
-
|
|
1514
|
+
kind: string;
|
|
1515
|
+
tool: string | null;
|
|
1516
|
+
args: unknown;
|
|
1517
|
+
result: unknown;
|
|
1708
1518
|
error: string | null;
|
|
1709
|
-
|
|
1710
|
-
|
|
1711
|
-
|
|
1712
|
-
|
|
1713
|
-
|
|
1714
|
-
|
|
1715
|
-
|
|
1519
|
+
completedAt: string | null;
|
|
1520
|
+
};
|
|
1521
|
+
type WorldSessionState = {
|
|
1522
|
+
sessionId: string;
|
|
1523
|
+
state: string;
|
|
1524
|
+
ready: boolean;
|
|
1525
|
+
versionId: string;
|
|
1526
|
+
contentHash: string;
|
|
1527
|
+
taskName: string | null;
|
|
1528
|
+
/** Where the task came from and what it is; absent on platforms that
|
|
1529
|
+
* predate session tasks, in which case it is derived from `taskName`. */
|
|
1530
|
+
task?: WorldSessionTask;
|
|
1531
|
+
/** The task's objective — present when the session was opened (not on a
|
|
1532
|
+
* bare status read), so a client never needs the bundle on disk. */
|
|
1533
|
+
instruction?: string | null;
|
|
1534
|
+
/** The tools this task serves. */
|
|
1535
|
+
tools?: WorldToolSpec[];
|
|
1536
|
+
/** When the fleet reaps this session unless a call lands first; null for
|
|
1537
|
+
* a pinned session (never reaped). Absent on platforms that predate it. */
|
|
1538
|
+
idleExpiresAt?: string | null;
|
|
1539
|
+
pinned?: boolean;
|
|
1540
|
+
/** Where the session answers besides `tools` — see worlds/browser.ts. */
|
|
1541
|
+
surfaces?: SessionSurfaces;
|
|
1542
|
+
/** Notices about the world's shape (an api bundle is a deprecated layout;
|
|
1543
|
+
* schema worlds are the supported shape), with what to run instead. Empty
|
|
1544
|
+
* for a schema world; absent on platforms that predate the notice. */
|
|
1545
|
+
deprecations?: WorldDeprecation[];
|
|
1546
|
+
/** Why a FAILED session failed to open, when the platform named it. */
|
|
1547
|
+
failure?: {
|
|
1548
|
+
code: string | null;
|
|
1549
|
+
message: string;
|
|
1550
|
+
} | null;
|
|
1551
|
+
/** The world state the session opened on; absent on platforms that predate it. */
|
|
1552
|
+
worldState?: WorldSessionWorldState | null;
|
|
1553
|
+
};
|
|
1554
|
+
type WorldSessionWorldState = {
|
|
1555
|
+
id: string;
|
|
1556
|
+
name: string;
|
|
1557
|
+
fingerprint: string;
|
|
1558
|
+
};
|
|
1559
|
+
/** A request the old world received has an `at` before `boundaryAt`; one the new world received, after it. */
|
|
1560
|
+
type WorldSessionRestart = {
|
|
1561
|
+
previousVersionId: string;
|
|
1562
|
+
versionId: string;
|
|
1563
|
+
pin: {
|
|
1564
|
+
ref: string | null;
|
|
1565
|
+
versionId: string | null;
|
|
1716
1566
|
};
|
|
1717
|
-
|
|
1718
|
-
|
|
1567
|
+
boundarySeq: number;
|
|
1568
|
+
boundaryAt: string;
|
|
1719
1569
|
};
|
|
1720
|
-
/**
|
|
1721
|
-
*
|
|
1722
|
-
*
|
|
1723
|
-
|
|
1724
|
-
|
|
1570
|
+
/** One notice a worlds-path answer carries: a deprecated shape or layout
|
|
1571
|
+
* and the command that replaces it. A retired shape is refused instead,
|
|
1572
|
+
* with the stable message prefix `world_kind_retired:`. */
|
|
1573
|
+
type WorldDeprecation = {
|
|
1574
|
+
code: string;
|
|
1575
|
+
message: string;
|
|
1576
|
+
replacement: string;
|
|
1577
|
+
};
|
|
1578
|
+
|
|
1725
1579
|
/**
|
|
1726
|
-
*
|
|
1727
|
-
*
|
|
1728
|
-
*
|
|
1729
|
-
*
|
|
1730
|
-
* platform dedups on `(agentId, seq)`. A batch that keeps failing is dropped
|
|
1731
|
-
* with a warning: telemetry must never stall or fail the agent.
|
|
1732
|
-
*
|
|
1733
|
-
* Numbering is durable across recorders: `nextSeq()` hands out a position
|
|
1734
|
-
* within this recorder, and the first send adds the base `resumeFrom`
|
|
1735
|
-
* reports — the platform's next free seq for this agent — so an agent id
|
|
1736
|
-
* reopened in a later process appends to its timeline instead of colliding
|
|
1737
|
-
* with (and being deduplicated against) what it already recorded. The base
|
|
1738
|
-
* is fixed once resolved, which keeps retries idempotent.
|
|
1580
|
+
* The three shapes a task reaches `openSession` in — a bundled scenario's
|
|
1581
|
+
* name, a stored task's `{ id, version? }`, an inline spec — and how each is
|
|
1582
|
+
* told apart, labelled and checked. No task at all (`undefined`) is the
|
|
1583
|
+
* fourth case, an exploratory session, and is not a ref.
|
|
1739
1584
|
*/
|
|
1740
|
-
declare
|
|
1741
|
-
|
|
1742
|
-
|
|
1743
|
-
|
|
1744
|
-
|
|
1745
|
-
|
|
1746
|
-
|
|
1747
|
-
|
|
1748
|
-
|
|
1749
|
-
|
|
1750
|
-
dropped: number;
|
|
1751
|
-
constructor(post: (events: BrowserActionEvent[]) => Promise<void>, agentId: string, opts?: {
|
|
1752
|
-
/** The platform's next free seq for `agentId`; 0 when not given. */
|
|
1753
|
-
resumeFrom?: () => Promise<number>;
|
|
1754
|
-
batchSize?: number;
|
|
1755
|
-
flushIntervalMs?: number;
|
|
1756
|
-
maxRetries?: number;
|
|
1757
|
-
sleep?: (ms: number) => Promise<void>;
|
|
1758
|
-
warn?: (message: string) => void;
|
|
1759
|
-
});
|
|
1760
|
-
/** This recorder's next position; the wire seq is `resumeFrom() + this`. */
|
|
1761
|
-
nextSeq(): number;
|
|
1762
|
-
private resolveBase;
|
|
1763
|
-
record(event: BrowserActionEvent): void;
|
|
1764
|
-
/** Resolve once everything recorded so far has been posted (or dropped). */
|
|
1765
|
-
flush(): Promise<void>;
|
|
1766
|
-
close(): Promise<void>;
|
|
1767
|
-
private drain;
|
|
1768
|
-
private send;
|
|
1585
|
+
declare const isTaskIdRef: (task: WorldTaskRef) => task is WorldTaskIdRef;
|
|
1586
|
+
declare const isTaskSpec: (task: WorldTaskRef) => task is WorldTaskSpec;
|
|
1587
|
+
/** The label a task goes by in results: its name, `inline:<hash>` for an
|
|
1588
|
+
* unnamed inline task once the platform has hashed it, or the stored task's
|
|
1589
|
+
* name (its id until the platform has answered). */
|
|
1590
|
+
declare const taskLabel: (task: WorldTaskRef, info?: WorldSessionTask | null) => string;
|
|
1591
|
+
/** A task given to `openSession` must be one of the three shapes. */
|
|
1592
|
+
declare const assertTaskRef: (task: WorldTaskRef) => void;
|
|
1593
|
+
|
|
1594
|
+
declare class WorldSessionTimeout extends Error {
|
|
1769
1595
|
}
|
|
1770
|
-
|
|
1771
|
-
* One Playwright page on the session's UI. Thin on purpose — `page` is the
|
|
1772
|
-
* real Playwright page for anything this wrapper does not cover.
|
|
1773
|
-
*/
|
|
1774
|
-
declare class WorldBrowser {
|
|
1775
|
-
readonly ui: SessionSurfaces["ui"] | undefined;
|
|
1776
|
-
readonly mode: Exclude<BrowserMode, "auto">;
|
|
1777
|
-
private readonly teardown;
|
|
1778
|
-
readonly viewport: {
|
|
1779
|
-
width: number;
|
|
1780
|
-
height: number;
|
|
1781
|
-
};
|
|
1782
|
-
readonly recorder: BrowserActionRecorder | null;
|
|
1783
|
-
private readonly reconnector;
|
|
1784
|
-
/** Takes session credentials out of every error this browser records. */
|
|
1785
|
-
private readonly scrubber;
|
|
1786
|
-
private current;
|
|
1787
|
-
private inflight;
|
|
1788
|
-
private lastNetwork;
|
|
1789
|
-
/** Where the page last was after an action, token stripped: what a
|
|
1790
|
-
* reconnect reopens. Null until the page has left `about:blank`. */
|
|
1791
|
-
private lastUrl;
|
|
1792
|
-
constructor(page: BrowserPage, ui: SessionSurfaces["ui"] | undefined, mode: Exclude<BrowserMode, "auto">, teardown: () => Promise<void>, viewport?: {
|
|
1793
|
-
width: number;
|
|
1794
|
-
height: number;
|
|
1795
|
-
}, recorder?: BrowserActionRecorder | null, reconnector?: BrowserReconnector | null,
|
|
1796
|
-
/** Takes session credentials out of every error this browser records. */
|
|
1797
|
-
scrubber?: SecretScrubber);
|
|
1798
|
-
/** The live Playwright page; a new object after a reconnect. */
|
|
1799
|
-
get page(): BrowserPage;
|
|
1800
|
-
get agentId(): string | null;
|
|
1801
|
-
/** `text` with this session's credentials (UI token, browser address) removed. */
|
|
1802
|
-
scrub(text: string): string;
|
|
1803
|
-
private watchNetwork;
|
|
1804
|
-
/** Run `fn` against the page. If it fails because the browser is gone,
|
|
1805
|
-
* recover; then `retry` runs it ONCE more and `report` throws
|
|
1806
|
-
* `BrowserReconnected` instead of replaying it. Any other error, and a
|
|
1807
|
-
* second loss during the retry, propagate unchanged. */
|
|
1808
|
-
private resilient;
|
|
1809
|
-
private remember;
|
|
1810
|
-
/** The page's URL less its token; null while it is blank. */
|
|
1811
|
-
private openedUrl;
|
|
1812
|
-
private recover;
|
|
1813
|
-
/** Take over a new connection's page and reopen the page the agent was on
|
|
1814
|
-
* (`openBrowser` owns the connection itself). A new browser has no session
|
|
1815
|
-
* cookie, so a World Host UI is first loaded with its token, exactly as
|
|
1816
|
-
* `goto()` loads the entry page. */
|
|
1817
|
-
private adopt;
|
|
1818
|
-
/** Run one action and report it: the event carries what was asked,
|
|
1819
|
-
* whether it worked, and the screen after — for failures too, so a
|
|
1820
|
-
* reviewer sees what the agent saw when the selector did not match. */
|
|
1821
|
-
act<T>(action: string, args: Record<string, unknown>, fn: () => Promise<T>, onLoss?: OnBrowserLoss): Promise<T>;
|
|
1822
|
-
/** One event on the recorder, if there is one; `failure` null means ok. */
|
|
1823
|
-
private report;
|
|
1824
|
-
private observeForEvent;
|
|
1825
|
-
/** Open a UI path (`/customers`), a full URL, or — with no argument — the
|
|
1826
|
-
* UI's declared entry page. */
|
|
1827
|
-
goto(pathOrUrl?: string): Promise<string>;
|
|
1828
|
-
back(): Promise<string>;
|
|
1829
|
-
/** Wait for the page to finish reacting to an action. `load` alone is not
|
|
1830
|
-
* enough for client-rendered UIs (React et al.): a click returns before the
|
|
1831
|
-
* fetch that re-renders the page, so an agent would read stale text.
|
|
1832
|
-
* Playwright's `networkidle` is per navigation and resolves at once after
|
|
1833
|
-
* the first one, so this tracks requests itself: done when nothing is in
|
|
1834
|
-
* flight and the network has been quiet for `SETTLE_QUIET_MS`, bounded so
|
|
1835
|
-
* long-polling UIs cannot hang us. */
|
|
1836
|
-
settle(): Promise<void>;
|
|
1837
|
-
click(selector: string): Promise<void>;
|
|
1838
|
-
type(selector: string, text: string): Promise<void>;
|
|
1839
|
-
press(key: string): Promise<void>;
|
|
1840
|
-
scroll(dy: number): Promise<void>;
|
|
1841
|
-
screenshot(fullPage?: boolean): Promise<Buffer>;
|
|
1842
|
-
screenshotBase64(fullPage?: boolean): Promise<string>;
|
|
1843
|
-
text(selector?: string): Promise<string>;
|
|
1844
|
-
html(): Promise<string>;
|
|
1845
|
-
get url(): string;
|
|
1846
|
-
title(): Promise<string>;
|
|
1847
|
-
close(): Promise<void>;
|
|
1596
|
+
declare class WorldSessionCallError extends Error {
|
|
1848
1597
|
}
|
|
1849
|
-
/** The
|
|
1850
|
-
|
|
1851
|
-
|
|
1852
|
-
|
|
1853
|
-
|
|
1854
|
-
|
|
1855
|
-
|
|
1856
|
-
|
|
1598
|
+
/** The session ended before it was ready: it FAILED to open, or was STOPPED.
|
|
1599
|
+
* `code` is the platform's when it named one; `browser_capacity` and
|
|
1600
|
+
* `host_unavailable` are worth opening again. */
|
|
1601
|
+
declare class WorldSessionOpenFailed extends WorldSessionCallError {
|
|
1602
|
+
readonly sessionId: string;
|
|
1603
|
+
readonly state: string;
|
|
1604
|
+
readonly code: string | null;
|
|
1605
|
+
constructor(sessionId: string, state: string, code: string | null, reason: string | null);
|
|
1606
|
+
}
|
|
1607
|
+
|
|
1608
|
+
declare class WorldSession {
|
|
1609
|
+
readonly sessionId: string;
|
|
1610
|
+
private current;
|
|
1611
|
+
private readonly options;
|
|
1612
|
+
constructor(sessionId: string, current: WorldSessionState, options: WorldsClientOptions);
|
|
1613
|
+
/** The task's display name: a bundled scenario's, or the inline spec's
|
|
1614
|
+
* `name` (null when the spec was unnamed). `task` is the same. */
|
|
1615
|
+
get taskName(): string | null;
|
|
1616
|
+
get task(): string | null;
|
|
1617
|
+
/** `{idleExpiresAt, pinned}` as of the last state read: when the fleet
|
|
1618
|
+
* reaps the session (null once pinned), and whether it is pinned. */
|
|
1619
|
+
get idle(): {
|
|
1620
|
+
idleExpiresAt: string | null;
|
|
1621
|
+
pinned: boolean;
|
|
1857
1622
|
};
|
|
1623
|
+
/** The platform's notices about the world this session runs on (empty
|
|
1624
|
+
* for a schema world). Printed by the CLI on stderr at open. */
|
|
1625
|
+
get deprecations(): WorldDeprecation[];
|
|
1626
|
+
/** The task this session runs: bundled scenario, stored task or inline
|
|
1627
|
+
* spec, its name, hash and the caller's metadata. */
|
|
1628
|
+
get taskInfo(): WorldSessionTask;
|
|
1629
|
+
/** What this task asks for — the bundle's instruction.md, or the inline
|
|
1630
|
+
* spec's `instruction`. */
|
|
1631
|
+
get instruction(): string | null;
|
|
1632
|
+
get versionId(): string;
|
|
1633
|
+
get worldState(): WorldSessionWorldState | null;
|
|
1634
|
+
/** Whether the session answered ready as of the last state read (the open,
|
|
1635
|
+
* a `status()`, or the poll inside `ready()`); no request is made. */
|
|
1636
|
+
get isReady(): boolean;
|
|
1637
|
+
/** `api` / `ui` / `browser` are present exactly when the world declares
|
|
1638
|
+
* them AND the session was opened asking for them. */
|
|
1639
|
+
surfaces(): Promise<SessionSurfaces>;
|
|
1640
|
+
/** Base URL of the world's own HTTP API for this session. */
|
|
1641
|
+
api(): Promise<string>;
|
|
1642
|
+
/** Headers every request to `api()` needs: a World Host session's token in the
|
|
1643
|
+
* platform's `X-World-Session` header, which every world takes; `{}` for a pod
|
|
1644
|
+
* or hosted twin, which answers with the world's own declared auth. */
|
|
1645
|
+
apiHeaders(): Promise<Record<string, string>>;
|
|
1646
|
+
/** URL of the world's UI entry page for this session. */
|
|
1647
|
+
ui(): Promise<string>;
|
|
1648
|
+
/** A Playwright browser on this session's UI: `hosted` drives the one the
|
|
1649
|
+
* platform runs next to the world, `local` launches one here, `auto`
|
|
1650
|
+
* prefers hosted. Call `close()` when done.
|
|
1651
|
+
*
|
|
1652
|
+
* Every action is reported to the platform under `agentId` (default:
|
|
1653
|
+
* `GATEWAY_AGENT_ID` or a fresh `agent-<hex>`) so the session page shows
|
|
1654
|
+
* this agent's own timeline — several agents may share one session and
|
|
1655
|
+
* one hosted browser. `record: false` opts out. */
|
|
1656
|
+
browser(opts?: {
|
|
1657
|
+
mode?: BrowserMode;
|
|
1658
|
+
headless?: boolean;
|
|
1659
|
+
playwright?: PlaywrightLike;
|
|
1660
|
+
agentId?: string;
|
|
1661
|
+
record?: boolean;
|
|
1662
|
+
}): Promise<WorldBrowser>;
|
|
1663
|
+
/** Ask the platform to make this session's hosted browser reachable again
|
|
1664
|
+
* after its connection dropped: `healthy` (reconnect now), `replaced` (a new,
|
|
1665
|
+
* blank browser behind the same wsUrl; reconnect and reopen your page) or
|
|
1666
|
+
* `starting` (ask again in `retryAfterMs`). `browser()` does this on its
|
|
1667
|
+
* own; call it when you drive your own Playwright against `wsUrl`. */
|
|
1668
|
+
repairBrowser(): Promise<RepairAnswer>;
|
|
1669
|
+
/** The reporter `browser()` uses; exposed for a page you drive yourself. */
|
|
1670
|
+
browserRecorder(agentId?: string): BrowserActionRecorder;
|
|
1671
|
+
/** Browser actions as model tools, in the same shape as `toolkit()`. */
|
|
1672
|
+
computerUseTools(browser: WorldBrowser): WorldToolkit;
|
|
1673
|
+
/** The browser as a provider's own pixel-based computer-use tool: `anthropic`
|
|
1674
|
+
* (`computer_toolset_20260801`), `openai` (Responses `computer`),
|
|
1675
|
+
* `anthropic-computer-20251124` or `openai-preview`. See `nativeComputer/`. */
|
|
1676
|
+
nativeComputer<P extends NativeComputerProvider = "anthropic">(browser: WorldBrowser, provider?: P, options?: NativeComputerOptions): NativeComputerKinds[P];
|
|
1677
|
+
/** The session's latest platform state (one request, no waiting). */
|
|
1678
|
+
status(): Promise<WorldSessionState>;
|
|
1679
|
+
/** The world started over under the same id, URLs and token, on what its pin (or `version`, which becomes
|
|
1680
|
+
* its pin) resolves to now: base data plus the task's seed. A grade then reads only the new world's requests. */
|
|
1681
|
+
restart(opts?: {
|
|
1682
|
+
version?: string;
|
|
1683
|
+
}): Promise<WorldSessionState & {
|
|
1684
|
+
restart: WorldSessionRestart;
|
|
1685
|
+
}>;
|
|
1686
|
+
private refresh;
|
|
1687
|
+
/**
|
|
1688
|
+
* Wait until the session answers calls: a World Host holds it, or the
|
|
1689
|
+
* process inside a pod has asked the platform for work. Throws
|
|
1690
|
+
* `WorldSessionOpenFailed` (with the platform's reason) when it ended
|
|
1691
|
+
* first, and `WorldSessionTimeout` when `timeoutMs` (default ten minutes)
|
|
1692
|
+
* ran out while it was still starting.
|
|
1693
|
+
*/
|
|
1694
|
+
ready(opts?: {
|
|
1695
|
+
timeoutMs?: number;
|
|
1696
|
+
}): Promise<WorldSessionState>;
|
|
1697
|
+
/** Enqueue one interaction and wait for the container's answer. */
|
|
1698
|
+
private exchange;
|
|
1699
|
+
/**
|
|
1700
|
+
* Run one of the world's tools INSIDE the container. The arguments and the
|
|
1701
|
+
* result are the world's own contract — this layer neither validates nor
|
|
1702
|
+
* reshapes them, so a tool error reads exactly as it would in a hosted run.
|
|
1703
|
+
*/
|
|
1704
|
+
call(tool: string, args?: Record<string, unknown>, opts?: {
|
|
1705
|
+
timeoutMs?: number;
|
|
1706
|
+
}): Promise<unknown>;
|
|
1707
|
+
/**
|
|
1708
|
+
* THE WORLD'S TOOLS, READY TO HAND TO A MODEL. Schemas come from the
|
|
1709
|
+
* world's own signatures and implementations call into this session, so a
|
|
1710
|
+
* caller never writes — and never has to re-sync — a tool map of their own:
|
|
1711
|
+
*
|
|
1712
|
+
* const { schemas, impls } = await session.toolkit();
|
|
1713
|
+
* await runMyAgent(impls, schemas, session.instruction);
|
|
1714
|
+
*
|
|
1715
|
+
* A tool added to the world shows up here on the next run; a tool renamed
|
|
1716
|
+
* in the world renames here too, instead of failing at call time against a
|
|
1717
|
+
* hand-written map that still remembers the old name.
|
|
1718
|
+
*/
|
|
1719
|
+
toolkit(): Promise<WorldToolkit>;
|
|
1720
|
+
/** Run the task's grader against the container's END STATE. Graders answer
|
|
1721
|
+
* in one of two shapes: the scalar with named rewards beside it
|
|
1722
|
+
* (`{reward, check_a, check_b}`, a task's own `grade.py`), or the named
|
|
1723
|
+
* rewards nested under `rewards` (the api, mock-tools and World Host
|
|
1724
|
+
* runners). Both land in `rewards`.
|
|
1725
|
+
*
|
|
1726
|
+
* A rubric grade is finalized by the platform's judge, not the container:
|
|
1727
|
+
* the platform answers the enqueue with `pending: true`, and this waits on
|
|
1728
|
+
* the judge's budget (15 min) instead of a call's. `timeoutMs` overrides
|
|
1729
|
+
* either. `report` is the agent's own account of what it did and found,
|
|
1730
|
+
* handed to the judge as its claim beside the evidence (the state and the
|
|
1731
|
+
* calls); assertions and python graders ignore it. `worlds` names the
|
|
1732
|
+
* task's other sessions by alias (`{alias: sessionId}`): the platform
|
|
1733
|
+
* reads each one's evidence and hands it to the cross-world verifiers
|
|
1734
|
+
* anchored on this session, whose grades come back under `verifiers`. A
|
|
1735
|
+
* score that is not a number from 0 to 1 is refused by key and value
|
|
1736
|
+
* (`GradeRefused`); a verifier's is that verifier's `error`. */
|
|
1737
|
+
grade(opts?: {
|
|
1738
|
+
timeoutMs?: number;
|
|
1739
|
+
report?: string;
|
|
1740
|
+
worlds?: Record<string, string>;
|
|
1741
|
+
}): Promise<GradeResult>;
|
|
1742
|
+
/**
|
|
1743
|
+
* Put rows into the LIVE world through its contract, in one batch:
|
|
1744
|
+
* `append` (default) upserts by primary key, `replace` makes the named
|
|
1745
|
+
* entities hold exactly these rows. Atomic — a refused row leaves the
|
|
1746
|
+
* session unchanged and the error names the entity, row and field.
|
|
1747
|
+
*/
|
|
1748
|
+
seed(rows: Record<string, Record<string, unknown>[]>, opts?: {
|
|
1749
|
+
mode?: "append" | "replace";
|
|
1750
|
+
/** `apply` runs the world's `[redact]` policy over the rows first;
|
|
1751
|
+
* `refuse` rejects plaintext in a redacted field; default `off`. */
|
|
1752
|
+
redact?: "off" | "apply" | "refuse";
|
|
1753
|
+
timeoutMs?: number;
|
|
1754
|
+
}): Promise<SeedResult>;
|
|
1755
|
+
/** Every entity's rows as the world holds them now — the same dump a
|
|
1756
|
+
* grader reads. The shape is the world runtime's: a schema world answers
|
|
1757
|
+
* `{<entity>: {<key>: row}, snapshot}`, a mock-tools world
|
|
1758
|
+
* `{entities: {<entity>: [row]}}`. */
|
|
1759
|
+
state(opts?: {
|
|
1760
|
+
timeoutMs?: number;
|
|
1761
|
+
}): Promise<unknown>;
|
|
1762
|
+
/** Back to the opening state: the version's data plus the bundled
|
|
1763
|
+
* scenario's or the inline task's seed. Rows written since are gone; the
|
|
1764
|
+
* call log stays. */
|
|
1765
|
+
reset(opts?: {
|
|
1766
|
+
timeoutMs?: number;
|
|
1767
|
+
}): Promise<void>;
|
|
1768
|
+
/** One page of the session's entries in its world's request ledger, newest
|
|
1769
|
+
* first and without bodies: at most `limit` after `cursor` (the last page's
|
|
1770
|
+
* `nextCursor`). Reading it records nothing in the session. */
|
|
1771
|
+
requests(opts?: {
|
|
1772
|
+
cursor?: string;
|
|
1773
|
+
limit?: number;
|
|
1774
|
+
}): Promise<WorldRequestPage>;
|
|
1775
|
+
private page;
|
|
1776
|
+
/** The session's call log, oldest first: every tool call, seed, reset,
|
|
1777
|
+
* grade with its result — the record of the episode. */
|
|
1778
|
+
export(): Promise<WorldSessionCall[]>;
|
|
1779
|
+
/**
|
|
1780
|
+
* Promote this session's inline task into a stored task of the project
|
|
1781
|
+
* (version 1, pinned to the session's world unless `world` says otherwise),
|
|
1782
|
+
* so a task written for one end user can be reused and its grades
|
|
1783
|
+
* compared. The session then records the new task's id. A session on a
|
|
1784
|
+
* bundled task has nothing to save; one on a stored task is already saved.
|
|
1785
|
+
*/
|
|
1786
|
+
saveTask(opts?: {
|
|
1787
|
+
name?: string;
|
|
1788
|
+
world?: string | null;
|
|
1789
|
+
message?: string;
|
|
1790
|
+
}): Promise<WorldTaskSummary>;
|
|
1791
|
+
/**
|
|
1792
|
+
* End the session. `keepWarm` hands the container back to the pool instead
|
|
1793
|
+
* of tearing it down, so the next session for the same task starts warm —
|
|
1794
|
+
* the pooled instance still obeys the fleet's idle TTL and pinning.
|
|
1795
|
+
*/
|
|
1796
|
+
close(opts?: {
|
|
1797
|
+
keepWarm?: boolean;
|
|
1798
|
+
}): Promise<{
|
|
1799
|
+
state: string;
|
|
1800
|
+
}>;
|
|
1801
|
+
/**
|
|
1802
|
+
* Run `fn` as work inside this session: spans it records take `sessionId`
|
|
1803
|
+
* as their session id and carry `world_session_id` trace metadata, so the
|
|
1804
|
+
* agent's traces land in the same session as the platform's traces of this
|
|
1805
|
+
* session's tool calls. A `withSession()` block inside still wins for the
|
|
1806
|
+
* session id. No effect before `tracing.init()`. `runSessions` wraps each
|
|
1807
|
+
* agent call in it.
|
|
1808
|
+
*
|
|
1809
|
+
* ```typescript
|
|
1810
|
+
* await session.withTraceContext(() => myAgent(toolkit, session.instruction));
|
|
1811
|
+
* ```
|
|
1812
|
+
*/
|
|
1813
|
+
withTraceContext<T>(fn: () => T | Promise<T>): Promise<T>;
|
|
1814
|
+
}
|
|
1815
|
+
/**
|
|
1816
|
+
* Attach to a session that already exists — resuming after a crash, or
|
|
1817
|
+
* driving a session someone else opened (a container started by hand on a
|
|
1818
|
+
* self-hosted install, a session opened by CI and handed to a developer).
|
|
1819
|
+
*/
|
|
1820
|
+
declare function attachSession(sessionId: string, options?: WorldsClientOptions): Promise<WorldSession>;
|
|
1821
|
+
type OpenSessionOptions = {
|
|
1822
|
+
versionId?: string;
|
|
1823
|
+
reuseWarm?: boolean;
|
|
1824
|
+
/** More than `tools`: `["api"]`, `["ui"]`, `["browser"]`. The platform
|
|
1825
|
+
* refuses (HTTP 400) rather than quietly serving less than asked. */
|
|
1826
|
+
surfaces?: WorldSurfaceKind[];
|
|
1827
|
+
/** Capacity for a World Host session's browser: `standard` (spot, may be
|
|
1828
|
+
* reclaimed) or `premium` (on-demand). Unset, the organization's default. */
|
|
1829
|
+
browserTier?: BrowserTier;
|
|
1830
|
+
/** `open`: the session asks for no credential; its api and ui answer on a
|
|
1831
|
+
* capability hostname whose url is the secret. Unset, the world's
|
|
1832
|
+
* `[auth] mode`. World Host sessions only. */
|
|
1833
|
+
auth?: SessionAuthMode;
|
|
1834
|
+
/** A world state of this world: the session opens on its data and knobs. World Host sessions only. */
|
|
1835
|
+
worldState?: string;
|
|
1836
|
+
options?: WorldsClientOptions;
|
|
1858
1837
|
};
|
|
1859
|
-
|
|
1860
|
-
|
|
1861
|
-
|
|
1862
|
-
|
|
1863
|
-
|
|
1864
|
-
|
|
1865
|
-
|
|
1866
|
-
|
|
1867
|
-
|
|
1868
|
-
|
|
1869
|
-
|
|
1838
|
+
/**
|
|
1839
|
+
* Open a live session on a world. Returns as soon as the platform has
|
|
1840
|
+
* accepted it — call `ready()` to wait for the container.
|
|
1841
|
+
*
|
|
1842
|
+
* `task` is a bundled scenario's name, a stored task's `{ id, version? }`
|
|
1843
|
+
* or an inline `WorldTaskSpec` (the latter two need a host engine world — the
|
|
1844
|
+
* platform answers 400 for a pod world). Omitted, the session is EXPLORATORY:
|
|
1845
|
+
* the platform records an inline `{instruction: "exploratory session"}` with
|
|
1846
|
+
* no grader as `task.source: "none"`, and `grade()` answers
|
|
1847
|
+
* `{reward: null, reason: "no grader"}`. The older positional form
|
|
1848
|
+
* `openSession(slug, "task-name", opts)` still works.
|
|
1849
|
+
*/
|
|
1850
|
+
declare function openSession(slugOrRef: string, task?: OpenSessionOptions & {
|
|
1851
|
+
task?: WorldTaskRef;
|
|
1852
|
+
}): Promise<WorldSession>;
|
|
1853
|
+
declare function openSession(slugOrRef: string, task: WorldTaskRef, opts?: OpenSessionOptions): Promise<WorldSession>;
|
|
1854
|
+
type SessionRunResult = {
|
|
1855
|
+
/** The task's name, or `inline:<hash>` for an unnamed inline task. */
|
|
1856
|
+
task: string;
|
|
1857
|
+
sessionId: string;
|
|
1858
|
+
reward: number | null;
|
|
1859
|
+
rewards: Record<string, number>;
|
|
1860
|
+
/** Set when the task threw instead of grading. */
|
|
1861
|
+
error?: string;
|
|
1862
|
+
};
|
|
1863
|
+
type SessionRunReport = {
|
|
1864
|
+
results: SessionRunResult[];
|
|
1865
|
+
/** Mean reward over every task, counting failures as 0. */
|
|
1866
|
+
mean: number;
|
|
1867
|
+
/** Tasks that never graded: the session did not open or become ready, the
|
|
1868
|
+
* agent threw, or grading failed. Any failure fails the run — a 0 an agent
|
|
1869
|
+
* earned and a session that never opened are not the same result. */
|
|
1870
|
+
failed: number;
|
|
1871
|
+
/** True when no task failed and `mean >= failUnder` (or no gate was set). */
|
|
1872
|
+
passed: boolean;
|
|
1870
1873
|
};
|
|
1871
|
-
declare function resolveBrowserMode(surfaces: SessionSurfaces, mode: BrowserMode): Exclude<BrowserMode, "auto">;
|
|
1872
|
-
/** Open a browser on the session's UI in `hosted`, `local` or `auto` mode. */
|
|
1873
|
-
declare function openBrowser(surfaces: SessionSurfaces, opts?: {
|
|
1874
|
-
mode?: BrowserMode;
|
|
1875
|
-
headless?: boolean;
|
|
1876
|
-
playwright?: PlaywrightLike;
|
|
1877
|
-
recorder?: BrowserActionRecorder | null;
|
|
1878
|
-
/** The session's repair call (`session.repairBrowser`). Given, a hosted
|
|
1879
|
-
* `cdp` browser reconnects on its own when the browser is lost. */
|
|
1880
|
-
repair?: () => Promise<RepairAnswer>;
|
|
1881
|
-
}): Promise<WorldBrowser>;
|
|
1882
|
-
declare const COMPUTER_USE_SPECS: readonly [{
|
|
1883
|
-
readonly name: "browser_goto";
|
|
1884
|
-
readonly signature: "browser_goto(path=None)";
|
|
1885
|
-
readonly doc: "Open a page of the world's UI. `path` is a UI path like /customers, a full URL, or omitted for the entry page. Returns the URL and page text.";
|
|
1886
|
-
}, {
|
|
1887
|
-
readonly name: "browser_click";
|
|
1888
|
-
readonly signature: "browser_click(selector)";
|
|
1889
|
-
readonly doc: "Click an element by Playwright selector (CSS, `text=Refund`, `role=button[name=Save]`). Returns the page text after the click.";
|
|
1890
|
-
}, {
|
|
1891
|
-
readonly name: "browser_type";
|
|
1892
|
-
readonly signature: "browser_type(selector, text)";
|
|
1893
|
-
readonly doc: "Replace the value of an input/textarea found by selector with `text`.";
|
|
1894
|
-
}, {
|
|
1895
|
-
readonly name: "browser_press";
|
|
1896
|
-
readonly signature: "browser_press(key)";
|
|
1897
|
-
readonly doc: "Press a key (Enter, Tab, Escape, ArrowDown, ...). Returns the page text after.";
|
|
1898
|
-
}, {
|
|
1899
|
-
readonly name: "browser_scroll";
|
|
1900
|
-
readonly signature: "browser_scroll(dy=600)";
|
|
1901
|
-
readonly doc: "Scroll the page vertically by `dy` pixels (negative scrolls up).";
|
|
1902
|
-
}, {
|
|
1903
|
-
readonly name: "browser_screenshot";
|
|
1904
|
-
readonly signature: "browser_screenshot(full_page=False)";
|
|
1905
|
-
readonly doc: "Take a PNG screenshot; returns {image_base64, url}.";
|
|
1906
|
-
}, {
|
|
1907
|
-
readonly name: "browser_read";
|
|
1908
|
-
readonly signature: "browser_read(selector='body')";
|
|
1909
|
-
readonly doc: "Return the visible text of an element (default: whole page) plus the URL and title.";
|
|
1910
|
-
}, {
|
|
1911
|
-
readonly name: "browser_back";
|
|
1912
|
-
readonly signature: "browser_back()";
|
|
1913
|
-
readonly doc: "Go back one page in history.";
|
|
1914
|
-
}];
|
|
1915
1874
|
/**
|
|
1916
|
-
*
|
|
1917
|
-
*
|
|
1918
|
-
*
|
|
1919
|
-
*
|
|
1875
|
+
* RUN MANY TASKS IN PARALLEL, one warm container each.
|
|
1876
|
+
*
|
|
1877
|
+
* Parallelism against live worlds is the normal case — a suite is a dozen
|
|
1878
|
+
* tasks and each needs its own container, because two agents sharing one
|
|
1879
|
+
* world state would corrupt both episodes. Every caller was writing the same
|
|
1880
|
+
* pool, the same per-task open/ready/toolkit/grade/close, and the same
|
|
1881
|
+
* "don't let one failure kill the run" logic, so it belongs here:
|
|
1882
|
+
*
|
|
1883
|
+
* const report = await runSessions({
|
|
1884
|
+
* world: "revenue-ops-sim@main",
|
|
1885
|
+
* tasks, // default: every task in the world
|
|
1886
|
+
* concurrency: 4,
|
|
1887
|
+
* failUnder: 0.7,
|
|
1888
|
+
* agent: async ({ toolkit, instruction }) =>
|
|
1889
|
+
* myAgent(toolkit.impls, toolkit.schemas, instruction),
|
|
1890
|
+
* });
|
|
1891
|
+
*
|
|
1892
|
+
* The handler gets a ready session with its toolkit already bound, and runs
|
|
1893
|
+
* inside `session.withTraceContext`; grading, closing (warm) and aggregation
|
|
1894
|
+
* are handled. A task that throws scores 0 and records why — the tasks that
|
|
1895
|
+
* passed keep their results.
|
|
1920
1896
|
*/
|
|
1921
|
-
declare function
|
|
1922
|
-
|
|
1923
|
-
|
|
1897
|
+
declare function runSessions(opts: {
|
|
1898
|
+
world: string;
|
|
1899
|
+
/** Bundled task names, stored task refs and/or inline task specs
|
|
1900
|
+
* (default: every bundled task in the world). */
|
|
1901
|
+
tasks?: WorldTaskRef[];
|
|
1902
|
+
concurrency?: number;
|
|
1903
|
+
failUnder?: number;
|
|
1904
|
+
/** Pin every session to one version (default: the world's head). */
|
|
1905
|
+
versionId?: string;
|
|
1906
|
+
/** Hand the containers back warm for the next run (default: true). */
|
|
1907
|
+
keepWarm?: boolean;
|
|
1908
|
+
agent: (ctx: {
|
|
1909
|
+
session: WorldSession;
|
|
1910
|
+
toolkit: WorldToolkit;
|
|
1911
|
+
instruction: string;
|
|
1912
|
+
/** The task's label — see `SessionRunResult.task`. */
|
|
1913
|
+
task: string;
|
|
1914
|
+
/** The task as it was given: a bundled name, a stored ref or the
|
|
1915
|
+
* inline spec. */
|
|
1916
|
+
taskRef: WorldTaskRef;
|
|
1917
|
+
}) => Promise<unknown>;
|
|
1918
|
+
onResult?: (result: SessionRunResult) => void;
|
|
1919
|
+
options?: WorldsClientOptions;
|
|
1920
|
+
}): Promise<SessionRunReport>;
|
|
1924
1921
|
|
|
1925
1922
|
/** Mirrors `WorldSessionListItemSchema` (web/features/public-api/types/world-sessions.ts). */
|
|
1926
1923
|
type WorldSessionListItem = {
|
|
@@ -2284,6 +2281,8 @@ type OpenTaskOptions = {
|
|
|
2284
2281
|
/** Browser capacity for every world the task opens: `standard` (spot, may
|
|
2285
2282
|
* be reclaimed) or `premium` (on-demand). Unset, the organization's default. */
|
|
2286
2283
|
browserTier?: BrowserTier;
|
|
2284
|
+
/** A world state per alias: that world's session opens on it. */
|
|
2285
|
+
worldStates?: Record<string, string>;
|
|
2287
2286
|
options?: WorldsClientOptions;
|
|
2288
2287
|
};
|
|
2289
2288
|
/**
|
|
@@ -2344,6 +2343,7 @@ declare class GatewayEvalsClient {
|
|
|
2344
2343
|
private readonly retry;
|
|
2345
2344
|
private readonly keyed;
|
|
2346
2345
|
constructor(options?: WorldsClientOptions, retry?: RetryPolicy);
|
|
2346
|
+
static refuseToken(options: WorldsClientOptions): void;
|
|
2347
2347
|
createEvaluation(versionId: string, opts?: CreateEvaluationOptions): Promise<string>;
|
|
2348
2348
|
pushSamples(evaluationId: string, samples: EvalSample[]): Promise<number>;
|
|
2349
2349
|
finalizeEvaluation(evaluationId: string, opts?: FinalizeEvaluationOptions): Promise<string>;
|
|
@@ -2417,6 +2417,8 @@ type RunTaskOptions = {
|
|
|
2417
2417
|
keepUp?: boolean;
|
|
2418
2418
|
reuseWarm?: boolean;
|
|
2419
2419
|
browserTier?: BrowserTier;
|
|
2420
|
+
/** A world state per alias: that world's session opens on it. */
|
|
2421
|
+
worldStates?: Record<string, string>;
|
|
2420
2422
|
/** File the rollout under this set run (`runSet` sets it). */
|
|
2421
2423
|
setRunId?: string;
|
|
2422
2424
|
options?: WorldsClientOptions;
|
|
@@ -2687,6 +2689,187 @@ type RunSetResult = {
|
|
|
2687
2689
|
/** A low or missing reward is a result, not a failure; every task runs even after one fails. */
|
|
2688
2690
|
declare function runSet(datasetId: string, agent: (run: TaskRun) => TaskRunResult | Promise<TaskRunResult>, opts: RunSetOptions): Promise<RunSetResult>;
|
|
2689
2691
|
|
|
2692
|
+
declare const COMPUTER_USE_SPECS: readonly [{
|
|
2693
|
+
readonly name: "browser_goto";
|
|
2694
|
+
readonly signature: "browser_goto(path=None)";
|
|
2695
|
+
readonly doc: "Open a page of the world's UI. `path` is a UI path like /customers, a full URL, or omitted for the entry page. Returns the URL and page text.";
|
|
2696
|
+
}, {
|
|
2697
|
+
readonly name: "browser_snapshot";
|
|
2698
|
+
readonly signature: "browser_snapshot()";
|
|
2699
|
+
readonly doc: "The page as an accessibility tree, one line per element with its role, name and [ref=e3]. To act on an element, pass `ref=e3` as the selector of browser_click or browser_type. Returns {url, title, snapshot, truncated}.";
|
|
2700
|
+
}, {
|
|
2701
|
+
readonly name: "browser_click";
|
|
2702
|
+
readonly signature: "browser_click(selector)";
|
|
2703
|
+
readonly doc: "Click an element by `ref=e3` from the last browser_snapshot, or by Playwright selector (CSS, `text=Refund`, `role=button[name=Save]`). Returns the page text after the click.";
|
|
2704
|
+
}, {
|
|
2705
|
+
readonly name: "browser_type";
|
|
2706
|
+
readonly signature: "browser_type(selector, text)";
|
|
2707
|
+
readonly doc: "Replace the value of an input/textarea, found by `ref=e3` or by selector, with `text`.";
|
|
2708
|
+
}, {
|
|
2709
|
+
readonly name: "browser_press";
|
|
2710
|
+
readonly signature: "browser_press(key)";
|
|
2711
|
+
readonly doc: "Press a key (Enter, Tab, Escape, ArrowDown, ...). Returns the page text after.";
|
|
2712
|
+
}, {
|
|
2713
|
+
readonly name: "browser_scroll";
|
|
2714
|
+
readonly signature: "browser_scroll(dy=600)";
|
|
2715
|
+
readonly doc: "Scroll the page vertically by `dy` pixels (negative scrolls up).";
|
|
2716
|
+
}, {
|
|
2717
|
+
readonly name: "browser_screenshot";
|
|
2718
|
+
readonly signature: "browser_screenshot(full_page=False)";
|
|
2719
|
+
readonly doc: "Take a PNG screenshot; returns {image_base64, url}.";
|
|
2720
|
+
}, {
|
|
2721
|
+
readonly name: "browser_read";
|
|
2722
|
+
readonly signature: "browser_read(selector='body')";
|
|
2723
|
+
readonly doc: "Return the visible text of an element (default: whole page) plus the URL and title.";
|
|
2724
|
+
}, {
|
|
2725
|
+
readonly name: "browser_back";
|
|
2726
|
+
readonly signature: "browser_back()";
|
|
2727
|
+
readonly doc: "Go back one page in history.";
|
|
2728
|
+
}];
|
|
2729
|
+
/**
|
|
2730
|
+
* A session's browser as model tools, in the `WorldToolkit` shape the world's
|
|
2731
|
+
* own tools come in, so an agent loop that dispatches `toolkit().impls`
|
|
2732
|
+
* merges these and gains a screen. Twin of `gatewaysdk/browser_tools.py`.
|
|
2733
|
+
*/
|
|
2734
|
+
declare function computerUseToolkit(browser: WorldBrowser, opts?: {
|
|
2735
|
+
maxText?: number;
|
|
2736
|
+
}): WorldToolkit;
|
|
2737
|
+
|
|
2738
|
+
declare class PageStateError extends Error {
|
|
2739
|
+
name: string;
|
|
2740
|
+
}
|
|
2741
|
+
/**
|
|
2742
|
+
* One snapshot line. Playwright writes a line's own attributes after its
|
|
2743
|
+
* name, so refs and `[disabled]` are read from the attribute run that ends
|
|
2744
|
+
* the key: a name cannot add one.
|
|
2745
|
+
*/
|
|
2746
|
+
declare class AriaLine {
|
|
2747
|
+
readonly text: string;
|
|
2748
|
+
readonly indent: number;
|
|
2749
|
+
readonly key: string;
|
|
2750
|
+
readonly attributes: string;
|
|
2751
|
+
readonly rest: string;
|
|
2752
|
+
constructor(text: string, indent: number, key?: string, attributes?: string, rest?: string);
|
|
2753
|
+
static parse(text: string): AriaLine;
|
|
2754
|
+
static parseAll(aria: string): AriaLine[];
|
|
2755
|
+
get refs(): string[];
|
|
2756
|
+
get disabled(): boolean;
|
|
2757
|
+
get editable(): boolean;
|
|
2758
|
+
/** A value line: a field's text, or the placeholder it shows. */
|
|
2759
|
+
get value(): boolean;
|
|
2760
|
+
get states(): string[];
|
|
2761
|
+
get namedLikeCredential(): boolean;
|
|
2762
|
+
/** Whether every value in and under this line is withheld. A field is,
|
|
2763
|
+
* when it is named like a credential or sits in something that is, has no
|
|
2764
|
+
* ref to probe, or `describe` reads it as a credential field. Any other
|
|
2765
|
+
* line is, when it is named like a credential and holds typed text (a
|
|
2766
|
+
* contenteditable), or has no ref to tell. */
|
|
2767
|
+
credentialField(describe: (ref: string) => Promise<string>, withinCredential: boolean): Promise<boolean>;
|
|
2768
|
+
private credentialFieldInput;
|
|
2769
|
+
/** The line as shown: `withholding` applied to its text, while its refs and
|
|
2770
|
+
* states are still read from the attribute run Playwright wrote, so a
|
|
2771
|
+
* withheld name cannot join that run. */
|
|
2772
|
+
withheldBy(withhold: (text: string) => string): AriaLine;
|
|
2773
|
+
/** The line with `withhold` applied to its name and value, its attribute
|
|
2774
|
+
* run (refs, states, levels) as Playwright wrote it. */
|
|
2775
|
+
withholding(withhold: (text: string) => string): string;
|
|
2776
|
+
/** The line with its own value replaced, keeping the key as Playwright
|
|
2777
|
+
* wrote it. */
|
|
2778
|
+
get withheld(): string;
|
|
2779
|
+
}
|
|
2780
|
+
/** A snapshot with its credential values withheld, and the refs of the lines
|
|
2781
|
+
* it withheld. */
|
|
2782
|
+
type Redaction$1 = {
|
|
2783
|
+
snapshot: string;
|
|
2784
|
+
withheld: ReadonlySet<string>;
|
|
2785
|
+
};
|
|
2786
|
+
type PageObservation = {
|
|
2787
|
+
url: string;
|
|
2788
|
+
title: string;
|
|
2789
|
+
snapshot: string;
|
|
2790
|
+
truncated: boolean;
|
|
2791
|
+
};
|
|
2792
|
+
/**
|
|
2793
|
+
* A world's page as a model reads it: Playwright's AI snapshot
|
|
2794
|
+
* (`ariaSnapshot({ mode: "ai" })`, Playwright 1.59 or newer), one line per
|
|
2795
|
+
* element, each numbered `[ref=e3]` by Playwright itself (`[ref=f1e2]` inside
|
|
2796
|
+
* a frame). A `ref=e3` selector resolves to Playwright's `aria-ref=e3`.
|
|
2797
|
+
* Playwright keeps a ref on its DOM node, and a page may reuse that node for
|
|
2798
|
+
* another record, so a ref acts only while the page reads as it did in the
|
|
2799
|
+
* snapshot the model saw (same URL and lines, with focus aside and what the
|
|
2800
|
+
* toolkit's own clicks and typing by ref left in place), checked before and after the
|
|
2801
|
+
* element is ready, and its action must start within `REF_ACT_TIMEOUT_MS`. A credential
|
|
2802
|
+
* field's value never leaves in a snapshot. Twin of
|
|
2803
|
+
* `gatewaysdk/page_state.py`; `conformance/page-state.json` pins both.
|
|
2804
|
+
*/
|
|
2805
|
+
declare class PageState {
|
|
2806
|
+
readonly url: string;
|
|
2807
|
+
readonly title: string;
|
|
2808
|
+
readonly snapshot: string;
|
|
2809
|
+
readonly refs: ReadonlySet<string>;
|
|
2810
|
+
readonly disabled: ReadonlySet<string>;
|
|
2811
|
+
readonly truncated: boolean;
|
|
2812
|
+
readonly credentials: ReadonlySet<string>;
|
|
2813
|
+
constructor(url: string, title: string, snapshot: string, refs: ReadonlySet<string>, disabled: ReadonlySet<string>, truncated: boolean, credentials?: ReadonlySet<string>);
|
|
2814
|
+
static parse(aria: string, opts: {
|
|
2815
|
+
url: string;
|
|
2816
|
+
title: string;
|
|
2817
|
+
maxChars?: number;
|
|
2818
|
+
credentials?: ReadonlySet<string>;
|
|
2819
|
+
}): PageState;
|
|
2820
|
+
static ofLines(lines: readonly AriaLine[], opts: {
|
|
2821
|
+
url: string;
|
|
2822
|
+
title: string;
|
|
2823
|
+
maxChars?: number;
|
|
2824
|
+
credentials?: ReadonlySet<string>;
|
|
2825
|
+
}): PageState;
|
|
2826
|
+
/** `aria` with credential values withheld: every value in and under a
|
|
2827
|
+
* credential field (see `AriaLine.credentialField`; `describe` is
|
|
2828
|
+
* `DESCRIBE_FIELD_JS` of a ref's element), the placeholder aside, and the
|
|
2829
|
+
* value of any line named like a credential. Names, roles and refs stay. */
|
|
2830
|
+
static redacted(aria: string, describe: (ref: string) => Promise<string>): Promise<Redaction$1>;
|
|
2831
|
+
target(ref: string): string;
|
|
2832
|
+
observation(): PageObservation;
|
|
2833
|
+
}
|
|
2834
|
+
/**
|
|
2835
|
+
* One toolkit's snapshots of one browser, and its clicks and typing. A
|
|
2836
|
+
* `ref=…` acts against the latest snapshot, and only while the page still
|
|
2837
|
+
* reads as that snapshot did, before and after the element is ready.
|
|
2838
|
+
*/
|
|
2839
|
+
declare class PageObserver {
|
|
2840
|
+
readonly browser: WorldBrowser;
|
|
2841
|
+
readonly maxChars: number;
|
|
2842
|
+
last: PageState | null;
|
|
2843
|
+
private seen;
|
|
2844
|
+
private seenUrl;
|
|
2845
|
+
private touched;
|
|
2846
|
+
private turn;
|
|
2847
|
+
constructor(browser: WorldBrowser, maxChars?: number);
|
|
2848
|
+
snapshot(): Promise<PageState>;
|
|
2849
|
+
click(selector: string): Promise<void>;
|
|
2850
|
+
type(selector: string, text: string): Promise<void>;
|
|
2851
|
+
/** One call at a time, so a tool call a model made in parallel cannot act
|
|
2852
|
+
* between another's checks and its action. */
|
|
2853
|
+
private inTurn;
|
|
2854
|
+
private takeSnapshot;
|
|
2855
|
+
/** The values of the fields the redaction withheld: a page may repeat them
|
|
2856
|
+
* in another line's name (a row or cell named from its content, a label
|
|
2857
|
+
* that wraps the field). */
|
|
2858
|
+
private withheldValues;
|
|
2859
|
+
private clickOnce;
|
|
2860
|
+
private typeOnce;
|
|
2861
|
+
private target;
|
|
2862
|
+
private ready;
|
|
2863
|
+
/** A page still rendering when it is read would refuse the model's next
|
|
2864
|
+
* ref, so the snapshot it is shown is one that read the same before and
|
|
2865
|
+
* after the page settled again. */
|
|
2866
|
+
private steady;
|
|
2867
|
+
private read;
|
|
2868
|
+
private url;
|
|
2869
|
+
private now;
|
|
2870
|
+
private still;
|
|
2871
|
+
}
|
|
2872
|
+
|
|
2690
2873
|
declare const WORLD_WEBHOOK_PAGE_MAX = 100;
|
|
2691
2874
|
type WorldWebhookSubscription = {
|
|
2692
2875
|
key: Record<string, unknown>;
|
|
@@ -2773,8 +2956,6 @@ declare class WorldWebhookForwarder {
|
|
|
2773
2956
|
private forward;
|
|
2774
2957
|
}
|
|
2775
2958
|
|
|
2776
|
-
/** One entry the archive rules dropped: a whole directory (`name/`, `files`
|
|
2777
|
-
* counted) or a single file. */
|
|
2778
2959
|
type Exclusion = {
|
|
2779
2960
|
path: string;
|
|
2780
2961
|
files: number;
|
|
@@ -2891,11 +3072,10 @@ declare function push(dir: string, opts?: {
|
|
|
2891
3072
|
* instead of 409ing against it. */
|
|
2892
3073
|
baseVersionId?: string | null;
|
|
2893
3074
|
/** Container metadata recorded on resolve — the Python CLI's --name,
|
|
2894
|
-
* --description
|
|
3075
|
+
* --description and --tag. */
|
|
2895
3076
|
name?: string;
|
|
2896
3077
|
description?: string;
|
|
2897
3078
|
tags?: string[];
|
|
2898
|
-
visibility?: string;
|
|
2899
3079
|
/** Pre-built OCI image ref for image/agentic envs (recorded on the version). */
|
|
2900
3080
|
imageRef?: string;
|
|
2901
3081
|
options?: WorldsClientOptions;
|
|
@@ -3084,16 +3264,6 @@ declare function storedForms(world: {
|
|
|
3084
3264
|
redact?: RedactPolicy | null;
|
|
3085
3265
|
}, field: string, plaintext: Plaintext, transform?: readonly string[]): Plaintext[];
|
|
3086
3266
|
|
|
3087
|
-
/**
|
|
3088
|
-
* `describeWorld(slug)` — what a world holds and how each field is stored,
|
|
3089
|
-
* from `GET /api/public/worlds/{slug}`: the entities (primary key, unique
|
|
3090
|
-
* keys, relationships, row count, fields with their `[redact]` policy) and
|
|
3091
|
-
* the `[redact]` table itself, so `storedForms(world, field, plaintext)`
|
|
3092
|
-
* can compute a lookup value without Python. The CLI twin is
|
|
3093
|
-
* `gateway worlds describe <slug>`; for a directory the CLI asks the schema
|
|
3094
|
-
* runtime instead and merges the same shape.
|
|
3095
|
-
*/
|
|
3096
|
-
|
|
3097
3267
|
type WorldField = {
|
|
3098
3268
|
name: string;
|
|
3099
3269
|
type: string | null;
|
|
@@ -3126,6 +3296,12 @@ type WorldDependency = {
|
|
|
3126
3296
|
tools: string[];
|
|
3127
3297
|
entities: WorldEntityMapping[];
|
|
3128
3298
|
};
|
|
3299
|
+
type WorldBundleMember = {
|
|
3300
|
+
alias: string;
|
|
3301
|
+
pin: string;
|
|
3302
|
+
slug: string | null;
|
|
3303
|
+
versionId: string;
|
|
3304
|
+
};
|
|
3129
3305
|
type WorldEntity = {
|
|
3130
3306
|
name: string;
|
|
3131
3307
|
primaryKey: string[];
|
|
@@ -3160,14 +3336,17 @@ type WorldDescription = {
|
|
|
3160
3336
|
/** World-to-world links from `[dependencies]`, resolved at commit, with the
|
|
3161
3337
|
* entity mappings `--across` follows. */
|
|
3162
3338
|
dependencies?: WorldDependency[];
|
|
3339
|
+
members?: WorldBundleMember[];
|
|
3163
3340
|
entities: WorldEntity[];
|
|
3164
3341
|
redact: RedactPolicy | null;
|
|
3342
|
+
/** The world's shape catalog (`conformance/world-shape-catalogs.json` pins its document); null with no data model, or when the runtime could not read it. */
|
|
3343
|
+
catalog?: Record<string, unknown> | null;
|
|
3165
3344
|
};
|
|
3166
3345
|
/** The world at `slug@ref`, described — `ref` is the one grammar shared with
|
|
3167
3346
|
* pull/checkout/sandbox (`latest` | branch | tag | semver | version id | hash
|
|
3168
3347
|
* prefix); a bare slug describes the head of `main`. An unknown ref is the
|
|
3169
3348
|
* route's 404, never the head. */
|
|
3170
|
-
declare function describeWorld(slugRef: string, options?: WorldsClientOptions): Promise<WorldDescription>;
|
|
3349
|
+
declare function describeWorld(slugRef: string, options?: WorldsClientOptions, entity?: string): Promise<WorldDescription>;
|
|
3171
3350
|
|
|
3172
3351
|
/**
|
|
3173
3352
|
* Named plaintext transforms for cross-world entity mappings.
|
|
@@ -3669,7 +3848,7 @@ declare function sessionToolObservations(sessionId: string, options?: WorldsClie
|
|
|
3669
3848
|
* The CLI sandbox: a server-side workspace opened on a READY version of a
|
|
3670
3849
|
* world (`/workspace/env` in the console agent's sandbox) — or, with
|
|
3671
3850
|
* `{ new, from }`, on a world that does not exist yet, seeded from the
|
|
3672
|
-
* `schema init` scaffold or
|
|
3851
|
+
* `schema init` scaffold or an official template and created by its first
|
|
3673
3852
|
* commit — edited and run there, and committed straight into the version
|
|
3674
3853
|
* service; the source never lands on the caller's disk. `importData` is the
|
|
3675
3854
|
* data door beside `commit`: a rows file in the sandbox tree into the platform
|
|
@@ -3909,7 +4088,7 @@ declare class WorldSandboxClient {
|
|
|
3909
4088
|
/**
|
|
3910
4089
|
* `{ slug, ref? }` opens a READY version; `{ new, from }` opens a sandbox on
|
|
3911
4090
|
* a world that does not exist yet (409 `world_exists` if the slug is taken,
|
|
3912
|
-
* 400 naming the
|
|
4091
|
+
* 400 naming the official templates if `from` is unknown). Its first commit
|
|
3913
4092
|
* creates the world on `main`.
|
|
3914
4093
|
*/
|
|
3915
4094
|
open(target: SandboxOpenTarget): Promise<SandboxOpened>;
|
|
@@ -3952,6 +4131,81 @@ declare class WorldSandboxClient {
|
|
|
3952
4131
|
}): Promise<SandboxSummary>;
|
|
3953
4132
|
}
|
|
3954
4133
|
|
|
4134
|
+
type WorldStateDoc = {
|
|
4135
|
+
id: string;
|
|
4136
|
+
name: string;
|
|
4137
|
+
kind: string;
|
|
4138
|
+
description: string | null;
|
|
4139
|
+
bindings: Record<string, string>;
|
|
4140
|
+
dataSnapshotId: string | null;
|
|
4141
|
+
createdBy: string | null;
|
|
4142
|
+
updatedBy: string | null;
|
|
4143
|
+
createdAt: string;
|
|
4144
|
+
updatedAt: string;
|
|
4145
|
+
};
|
|
4146
|
+
type WorldStateSnapshot = {
|
|
4147
|
+
id: string;
|
|
4148
|
+
sha256: string;
|
|
4149
|
+
digest: string;
|
|
4150
|
+
contractHash: string;
|
|
4151
|
+
bytes: number;
|
|
4152
|
+
rowCounts: Record<string, number>;
|
|
4153
|
+
};
|
|
4154
|
+
type WorldStateOpening = {
|
|
4155
|
+
versionId: string;
|
|
4156
|
+
source: "version" | "state" | "carried";
|
|
4157
|
+
snapshot: WorldStateSnapshot | null;
|
|
4158
|
+
bindings: Record<string, string>;
|
|
4159
|
+
fingerprint: string;
|
|
4160
|
+
};
|
|
4161
|
+
type WorldStateRefusal = {
|
|
4162
|
+
code: string;
|
|
4163
|
+
message: string;
|
|
4164
|
+
};
|
|
4165
|
+
type WorldStateList = {
|
|
4166
|
+
slug: string;
|
|
4167
|
+
containerId: string;
|
|
4168
|
+
states: WorldStateDoc[];
|
|
4169
|
+
};
|
|
4170
|
+
type WorldStateAnswer = {
|
|
4171
|
+
slug: string;
|
|
4172
|
+
state: WorldStateDoc;
|
|
4173
|
+
versionId: string | null;
|
|
4174
|
+
opens: WorldStateOpening | null;
|
|
4175
|
+
refusal: WorldStateRefusal | null;
|
|
4176
|
+
};
|
|
4177
|
+
type WorldStateDeleted = {
|
|
4178
|
+
slug: string;
|
|
4179
|
+
state: WorldStateDoc;
|
|
4180
|
+
deleted: true;
|
|
4181
|
+
runCount: number;
|
|
4182
|
+
};
|
|
4183
|
+
type WorldStatePull = {
|
|
4184
|
+
slug: string;
|
|
4185
|
+
state: WorldStateDoc;
|
|
4186
|
+
opens: WorldStateOpening;
|
|
4187
|
+
download: {
|
|
4188
|
+
url: string;
|
|
4189
|
+
expiresAt: string;
|
|
4190
|
+
} | null;
|
|
4191
|
+
};
|
|
4192
|
+
type WorldStateCreateInput = {
|
|
4193
|
+
name: string;
|
|
4194
|
+
description?: string;
|
|
4195
|
+
bindings?: Record<string, string>;
|
|
4196
|
+
fromSnapshot?: string;
|
|
4197
|
+
fromState?: string;
|
|
4198
|
+
};
|
|
4199
|
+
declare class WorldStateClient {
|
|
4200
|
+
private readonly options;
|
|
4201
|
+
constructor(options?: WorldsClientOptions);
|
|
4202
|
+
list(slug: string): Promise<WorldStateList>;
|
|
4203
|
+
show(slug: string, name: string, ref?: string): Promise<WorldStateAnswer>;
|
|
4204
|
+
create(slug: string, input: WorldStateCreateInput): Promise<WorldStateAnswer>;
|
|
4205
|
+
delete(slug: string, name: string): Promise<WorldStateDeleted>;
|
|
4206
|
+
pull(slug: string, name: string, ref?: string): Promise<WorldStatePull>;
|
|
4207
|
+
}
|
|
4208
|
+
|
|
3955
4209
|
/**
|
|
3956
4210
|
* The hosted one-task dry run: `POST /api/public/environments/{id}/dry-run`
|
|
3957
4211
|
* and the run-status read that settles it. The runner runs ONE named task of a
|
|
@@ -4078,6 +4332,7 @@ type WorldsClientOptions = {
|
|
|
4078
4332
|
host?: string;
|
|
4079
4333
|
publicKey?: string;
|
|
4080
4334
|
secretKey?: string;
|
|
4335
|
+
token?: PersonalToken;
|
|
4081
4336
|
};
|
|
4082
4337
|
type ResolvedWorldVersion = {
|
|
4083
4338
|
versionId: string;
|
|
@@ -4095,21 +4350,6 @@ type DispatchedRun = {
|
|
|
4095
4350
|
ok: boolean;
|
|
4096
4351
|
error?: string;
|
|
4097
4352
|
};
|
|
4098
|
-
/** A non-2xx platform answer: act on `status` or the stable public `code` (never the server's error class) rather than parsing the message. */
|
|
4099
|
-
declare class ApiError extends Error {
|
|
4100
|
-
readonly status: number;
|
|
4101
|
-
readonly text: string;
|
|
4102
|
-
readonly code: string | null;
|
|
4103
|
-
constructor(status: number, method: string, path: string, text: string);
|
|
4104
|
-
}
|
|
4105
|
-
/** The detail and stable code of a non-2xx body; an HTML page or a bare 5xx is named, never printed.
|
|
4106
|
-
* Python twin: `gatewaysdk.api_errors.error_detail`; both run `conformance/platform-error-bodies.json`. */
|
|
4107
|
-
declare function parseErrorBody(text: string, status?: number): {
|
|
4108
|
-
detail: string;
|
|
4109
|
-
code: string | null;
|
|
4110
|
-
};
|
|
4111
|
-
/** `<path>: <message>` per issue of a validation error; empty when it carries none. Python twin: `gatewaysdk.api_errors.invalid_fields`. */
|
|
4112
|
-
declare function invalidFields(error: unknown): string;
|
|
4113
4353
|
/** Authenticated JSON request to the platform API. `init.timeoutMs` replaces the `GATEWAY_TIMEOUT_MS` budget for a request that
|
|
4114
4354
|
* legitimately outlasts it; `init.retry` is only for a request whose repeat is harmless. */
|
|
4115
4355
|
declare function apiRequest<T>(options: WorldsClientOptions, method: PlatformMethod, path: string, body?: unknown, init?: {
|
|
@@ -4270,4 +4510,4 @@ declare function openWorld(slugRef: string, options?: WorldsClientOptions): Prom
|
|
|
4270
4510
|
/** Resolve `slug` at one READY `versionId`, with that version's task list; another world's version, a draft or an unknown id is a 404, never the head. */
|
|
4271
4511
|
declare function openWorldVersion(slug: string, versionId: string, options?: WorldsClientOptions): Promise<WorldSet>;
|
|
4272
4512
|
|
|
4273
|
-
export { ACTION_NAMES, type ActingUser, type ActionArgs, type ActionResult, ActionTracer, type AiSdkAnthropicOutput, type AiSdkComputerCall, type AiSdkComputerOutput, type AiSdkImagePart, type AiSdkMajor, type AiSdkModelOutput, type AiSdkOptions, AnthropicComputer, AnthropicComputer20251124, type AnthropicToolResult,
|
|
4513
|
+
export { ACTION_NAMES, type ActingUser, type ActionArgs, type ActionResult, ActionTracer, type AiSdkAnthropicOutput, type AiSdkComputerCall, type AiSdkComputerOutput, type AiSdkImagePart, type AiSdkMajor, type AiSdkModelOutput, type AiSdkOptions, AnthropicComputer, AnthropicComputer20251124, type AnthropicToolResult, BROWSER_GONE_PATTERNS, BROWSER_TIERS, type BrowserActionEvent, BrowserActionRecorder, type BrowserConnection, type BrowserMode, type BrowserPage, BrowserReconnected, BrowserReconnector, type BrowserTier, BrowserUnrecoverable, CALL_BODY_LIMIT_BYTES, CALL_BODY_LIMIT_LABEL, COMPUTER_USE_SPECS, type Checkout, CheckoutProvenance, ComputerAction, type ComputerCallOutput, type CreateEvaluationOptions, DEFAULT_BRANCH, DEFAULT_VIEWPORT, DRY_RUN_AGENT, DRY_RUN_KIND, DetachedPushError, type DispatchedRun, Display, type DryRunImageDecision, DryRunOutcome, type DryRunSettlement, EVENT_BATCH_SIZE, EVENT_FLUSH_INTERVAL_MS, EVENT_MAX_RETRIES, EXPLORATORY_TASK, EXPLORATORY_TASK_SOURCE, type EditSessionCloseInput, type EditSessionList, type EditSessionListQuery, type EditSessionResult, type EditSessionRollbackInput, type EditSessionSummary, type EvalSample, type FinalizeEvaluationOptions, type ForwardedDelivery, GatewayEvalsClient, GradePayload, GradeRefused, type GradeResult, type GradedJournal, HostedDryRunClient, type HostedDryRunDispatch, type HostedDryRunStatus, type HostedDryRunVerdict, IDLE_WARNING_MINUTES, type IngestExplode, type IngestFieldSpec, type IngestMapping, type IngestMode, type IngestOptions, type IngestRefusal, type IngestReport, type IngestSource, type IngestSourceReport, type IngestToolCallsOptions, type IngestToolCallsReport, KEY_NAMES, KeyChord, type ListRunsFilter, type ListSessionsFilter, type LiveTaskSession, type LocalMeta, type MigrateWorldOptions, NOT_EXECUTED, NO_GRADER_REASON, NativeComputer, type NativeComputerKinds, type NativeComputerOptions, type NativeComputerProvider, type NativePage, type ObservationConversion, type ObservationLike, OpenAIComputer, OpenAIPreviewComputer, type OpenSessionOptions, type OpenTaskOptions, PLATFORM_SESSION_HEADER, type PageObservation, PageObserver, PageState, PageStateError, type ParsedToolCall, PendingSafetyChecks, type Plaintext, PlatformMethod, type PlaywrightBrowserLike, type PlaywrightLike, PushSlugConflict, type PushSlugResolution, RECOVER_BUDGET_MS, REQUESTS_NOT_RECORDED, REQUEST_BODY_CAPTURE_BYTES, REQUEST_LOG_PAGE_MAX, type RebaseConflictPath, type RecoveryResult, type RedactMode, type RedactPolicy, type Redaction, type RegradedRollout, type RepairAnswer, type ResolvedWorldVersion, RetryPolicy, type RowsRefusal, type RunConfigInput, type RunConfigSummary, type RunProvenance, type RunReport, type RunSetOptions, type RunSetResult, type RunSummary, type RunTaskOptions, type RunTaskSummary, SANDBOX_EXEC_REPORT_MARGIN_MS, SANDBOX_EXEC_START_ATTEMPTS, SANDBOX_EXEC_TIMEOUT_MAX_S, SANDBOX_EXEC_WAIT_MS, SANDBOX_FILE_MAX_BYTES, SANDBOX_REQUEST_TIMEOUT_MS, SANDBOX_WRITE_CHUNK_BYTES, SANDBOX_WRITE_SKIPPED, SECRET_KEY, SESSION_AUTH_MODES, SESSION_STATES, SPAN_PREFIX, STATUS_WAIT_CAP_SECONDS, STRIP_PREFIX, SURFACE_KINDS, type SafetyCheck, type SandboxChanges, type SandboxCheckResult, type SandboxCommitInput, type SandboxCommitPending, type SandboxCommitResult, type SandboxExecResult, type SandboxExecRunning, type SandboxImportInput, type SandboxImportPending, type SandboxImportResult, type SandboxListFilter, type SandboxOpenExisting, type SandboxOpenNew, type SandboxOpenTarget, type SandboxOpened, type SandboxSummary, Score, Screen, type ScreenBrowser, SecretScrubber, type SeedResult, type SessionAuthMode, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type SetRunDoc, type SettleOptions, type SlugDeclaration, type SurfaceDescriptor, TOOL_CONTRACT_UNREAD, TRANSFORMS, TaskEditClient, type TaskEditCloseInput, type TaskEditCloseResult, type TaskEditRollbackInput, type TaskEditRollbackResult, type TaskEditSealed, type TaskEditStatus, type TaskEditTarget, type TaskEditTaskRef, type TaskExport, type TaskGrade, TaskGrades, type TaskManifest, type TaskManifestSession, type TaskRegrade, type TaskRegradeScope, TaskRun, type TaskRunResult, TaskSessions, type TaskSessionsResponse, type TaskTrial, type TaskTrialCheck, type TaskTrialRequest, type TaskTrialTarget, type TaskWorldRef, type TaskWorldSessionState, type ToolCallRecord, type ToolCallSink, type ToolFunctions, type Transform, VERIFIER_REWARD_PREFIX, type ValidateReport, type ValidatedRun, type VerifierGrade, WHITESPACE, WORLD_REQUEST_VIAS, WORLD_WEBHOOK_PAGE_MAX, WorldBrowser, type WorldBundleMember, WorldCallTooLarge, type WorldDependency, type WorldDeprecation, type WorldDescription, WorldEditClient, type WorldEntity, type WorldEntityMapping, type WorldField, type WorldMigrationRefusal, type WorldMigrationReport, WorldNotice, type WorldQueryAcrossOptions, type WorldQueryAcrossResult, type WorldQueryCompare, type WorldQueryCompareStatus, type WorldQueryGroup, type WorldQueryOptions, type WorldQueryResult, type WorldQuerySnapshot, type WorldQueryWhere, type WorldRelationship, type WorldRequest, type WorldRequestEntry, type WorldRequestFilter, WorldRequestFilterError, WorldRequestLedger, WorldRequestLog, type WorldRequestPage, WorldRequestQuery, WorldRequestsNotRecorded, WorldSandboxClient, WorldSession, type WorldSessionCall, WorldSessionCallError, type WorldSessionListItem, WorldSessionOpenFailed, type WorldSessionRestart, type WorldSessionState, type WorldSessionTask, WorldSessionTimeout, type WorldSessionWorldState, WorldSet, type WorldSqlOptions, type WorldSqlResult, type WorldStateAnswer, WorldStateClient, type WorldStateCreateInput, type WorldStateDeleted, type WorldStateDoc, type WorldStateList, type WorldStateOpening, type WorldStatePull, type WorldStateRefusal, type WorldStateSnapshot, type WorldSurfaceKind, WorldSurfaceUnavailable, WorldTask, type WorldTaskCheck, type WorldTaskDetail, type WorldTaskFieldOp, type WorldTaskGrader, type WorldTaskIdRef, type WorldTaskInfo, type WorldTaskPage, type WorldTaskRef, type WorldTaskRubricCriterion, type WorldTaskRubricGrader, type WorldTaskScalar, type WorldTaskSeed, type WorldTaskSpec, type WorldTaskSummary, type WorldTaskValidation, type WorldTaskVerifier, type WorldTaskVerifierRow, type WorldTaskVersionSummary, type WorldTaskWorld, type WorldTaskWorldValidation, type WorldToolSpec, type WorldToolkit, WorldToolsUnread, type WorldWebhookAnswer, type WorldWebhookDelivery, WorldWebhookForwarder, type WorldWebhookListing, type WorldWebhookPage, type WorldWebhookSubscription, type WorldsClientOptions, WriteTreeFilter, aggregateTaskGrade, apiRequest, applyTransforms, archiveMode, assertBrowserTier, assertSessionAuthMode, assertTaskRef, attachManifest, attachSession, attachTask, buildFileManifest, buildSourceTarball, capabilityLabel, captureToolCalls, carriedWarnings, checkoutIdentity, closeConnection, collectArchiveRelPaths, computeContentHash, computerUseToolkit, createRef, createTask, deleteEnvSecret, deleteTask, describeWorld, detectProvenance, extractBundle, getRun, getTask, hashForm, idleWarning, ingest, ingestToolCalls, isBrowserGone, isSandboxCommitPending, isSandboxImportPending, isTaskIdRef, isTaskManifest, isTaskSpec, listEnvSecretKeys, listRunConfigs, listRuns, listSessions, listTaskSessions, listTasks, listWebhooks, localTreeState, messageOf, migrateProjectWorlds, migrateWorld, modelToolName, openBrowser, openSession, openTask, openWorld, openWorldVersion, parseSlugRef, parseToolCallRecord, parseTransform, parseWorldTaskRefs, playwrightKey, preserveForm, propose, pull, push, pushBranch, pushSlug, pyText, queryRows, queryRowsSearch, readField, readLocalMeta, readToolCallRecords, rebaseConflicts, redactActionArgs, redactionOf, releaseConnection, resolveBrowserMode, resolvePushSlug, roundForm, rowsRefusal, runSessions, runSet, runTask, schemaFromSignature, scrubError, serializeCallBody, sessionToolObservations, setEnvSecret, shapeText, snapshotTreeHashes, sqlRows, stillStartingHint, storedForms, surfaceDescriptor, surfaceKinds, taskGradeError, taskLabel, taskRunFailure, toolCallRecordsIn, toolCallsFromObservations, uiEntryUrl, uiUrl, uncommittedPaths, updateTask, upsertRunConfig, validateTask, validateWorld, waitForRun, withoutUiToken, worldRequestsUnrecorded, writeLocalMeta };
|