@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.
Files changed (150) hide show
  1. package/dist/agents/index.d.mts +581 -0
  2. package/dist/agents/index.d.ts +581 -0
  3. package/dist/agents/index.js +1473 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1424 -0
  6. package/dist/agents/index.mjs.map +1 -0
  7. package/dist/apiError-DHpfbmdx.d.mts +17 -0
  8. package/dist/apiError-DHpfbmdx.d.ts +17 -0
  9. package/dist/cli.js +11611 -6845
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +10090 -5325
  12. package/dist/cli.mjs.map +1 -1
  13. package/dist/files/index.d.mts +3 -1
  14. package/dist/files/index.d.ts +3 -1
  15. package/dist/files/index.js +371 -102
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +371 -102
  18. package/dist/files/index.mjs.map +1 -1
  19. package/dist/hooks/index.js +346 -136
  20. package/dist/hooks/index.js.map +1 -1
  21. package/dist/hooks/index.mjs +346 -136
  22. package/dist/hooks/index.mjs.map +1 -1
  23. package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
  24. package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +3177 -748
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2987 -590
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/media-CQUC7TkS.d.mts +39 -0
  32. package/dist/media-DQnBloaX.d.ts +39 -0
  33. package/dist/traces/index.d.mts +3 -1
  34. package/dist/traces/index.d.ts +3 -1
  35. package/dist/traces/index.js +371 -102
  36. package/dist/traces/index.js.map +1 -1
  37. package/dist/traces/index.mjs +371 -102
  38. package/dist/traces/index.mjs.map +1 -1
  39. package/dist/tracing/index.d.mts +3 -2
  40. package/dist/tracing/index.d.ts +3 -2
  41. package/dist/tracing/index.js +257 -16
  42. package/dist/tracing/index.js.map +1 -1
  43. package/dist/tracing/index.mjs +257 -16
  44. package/dist/tracing/index.mjs.map +1 -1
  45. package/dist/transport-CpRe7zgd.d.mts +123 -0
  46. package/dist/transport-CpRe7zgd.d.ts +123 -0
  47. package/dist/worlds/index.d.mts +1986 -1746
  48. package/dist/worlds/index.d.ts +1986 -1746
  49. package/dist/worlds/index.js +1470 -290
  50. package/dist/worlds/index.js.map +1 -1
  51. package/dist/worlds/index.mjs +1465 -286
  52. package/dist/worlds/index.mjs.map +1 -1
  53. package/package.json +6 -1
  54. package/runtime/gatewaysdk/environment/bundle_manifest.py +531 -0
  55. package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
  56. package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
  57. package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
  58. package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
  59. package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
  60. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  61. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  62. package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
  63. package/runtime/gatewaysdk/environment/schema/api.py +3 -4
  64. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  65. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
  67. package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
  68. package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
  69. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  70. package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
  71. package/runtime/gatewaysdk/environment/schema/host.py +94 -12
  72. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  73. package/runtime/gatewaysdk/environment/schema/host_control.py +35 -2
  74. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  75. package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
  76. package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
  77. package/runtime/gatewaysdk/environment/schema/host_requests.py +35 -0
  78. package/runtime/gatewaysdk/environment/schema/host_session.py +20 -2
  79. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +100 -19
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
  82. package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
  83. package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
  84. package/runtime/gatewaysdk/environment/schema/local.py +32 -7
  85. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  86. package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
  87. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  88. package/runtime/gatewaysdk/environment/schema/platform.py +80 -270
  89. package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_templates.py +420 -0
  91. package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
  92. package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
  93. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  94. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  95. package/runtime/gatewaysdk/environment/schema/runtime.py +57 -5
  96. package/runtime/gatewaysdk/environment/schema/scaffold.py +386 -219
  97. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  98. package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
  99. package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
  100. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  101. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  102. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +2 -2
  103. package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
  104. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
  105. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +8 -6
  106. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  107. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  108. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
  109. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  110. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  111. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  112. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  113. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  114. package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
  115. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  116. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  117. package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
  118. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  119. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  120. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  121. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  122. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  123. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  124. package/runtime/gatewaysdk/environment/schema/validation.py +24 -1
  125. package/runtime/gatewaysdk/environment/schema/worker.py +12 -5
  126. package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
  127. package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
  128. package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
  129. package/runtime/gatewaysdk/environment/schema/workers.py +245 -69
  130. package/runtime/gatewaysdk/environment/schema/world_host.py +96 -73
  131. package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
  132. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  133. package/runtime/gatewaysdk/environment/world.py +34 -43
  134. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  135. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  136. package/skills/connector-schema-authoring/SKILL.md +2 -2
  137. package/skills/connector-schema-authoring/connector-worlds.md +3 -2
  138. package/skills/connector-schema-authoring/world-schema.md +36 -23
  139. package/skills/factory-orchestrator/SKILL.md +147 -0
  140. package/skills/world-data-ingestion/ROWS.md +5 -1
  141. package/skills/world-data-ingestion/SKILL.md +8 -6
  142. package/skills/worlds-getting-started/SKILL.md +9 -9
  143. package/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  144. package/skills/worlds-getting-started/references/gotchas.md +6 -6
  145. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  146. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  147. package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  148. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  149. package/dist/media-BIApiPzS.d.mts +0 -102
  150. package/dist/media-BIApiPzS.d.ts +0 -102
@@ -1,5 +1,15 @@
1
- import { i as MediaUploader, R as RetryPolicy, c as PlatformMethod } from '../media-BIApiPzS.js';
2
- export { P as PLATFORM_TIMEOUT_DEFAULT_MS, a as PLATFORM_TIMEOUT_ENV, b as PlatformEndpoint, d as PlatformReply, e as PlatformTransport, T as TransportCause, U as UnreachableError, p as platformTimeoutMs } from '../media-BIApiPzS.js';
1
+ import { R as RetryPolicy, k as PersonalToken, e as PlatformMethod } from '../transport-CpRe7zgd.js';
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.js';
3
+ export { A as ApiError, i as invalidFields, p as parseErrorBody } from '../apiError-DHpfbmdx.js';
4
+ import { d as MediaUploader } from '../media-DQnBloaX.js';
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
- * The provider-neutral action vocabulary every native computer executes.
98
- * Coordinates are in the MODEL's pixel space; the screen maps them to the page.
99
- * Twin of `gatewaysdk/native_computer/actions.py`.
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 ACTION_NAMES: readonly ["screenshot", "zoom", "click", "move", "mouse_down", "mouse_up", "drag", "scroll", "type", "key", "hold_key", "wait", "cursor_position", "history"];
102
- type ActionName = (typeof ACTION_NAMES)[number];
103
- type Point = [number, number];
104
- type MouseButton = "left" | "right" | "middle";
105
- /** Arguments by action:
106
- * `click` x?, y?, button, count, modifiers · `move` x, y, modifiers? ·
107
- * `mouse_down`/`mouse_up` button · `drag` path, modifiers ·
108
- * `scroll` x?, y?, dx, dy, modifiers · `type` text · `key` keys, repeat ·
109
- * `hold_key` keys, seconds · `wait` seconds · `zoom` region ·
110
- * `history` direction · `screenshot`/`cursor_position` none. */
111
- type ActionArgs = {
112
- x?: number;
113
- y?: number;
114
- button?: MouseButton;
115
- count?: number;
116
- modifiers?: string[];
117
- path?: Point[];
118
- dx?: number;
119
- dy?: number;
120
- text?: string;
121
- keys?: string[];
122
- repeat?: number;
123
- seconds?: number;
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 class ComputerAction {
128
- readonly name: ActionName;
129
- readonly args: ActionArgs;
130
- constructor(name: ActionName, args?: ActionArgs);
131
- /** Flat arguments for the browser timeline and the trace: lists become
132
- * `"x,y"` strings, and typed text is withheld when it went into a
133
- * credential field. */
134
- recordArgs(secretText: boolean): Record<string, unknown>;
135
- }
136
- /** What an action gave back: a PNG (`screenshot`, `zoom`), a line of text
137
- * (`cursor_position`), or neither. */
138
- type ActionResult = {
139
- image?: Buffer;
140
- text?: string;
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
- * The model's pixel space versus the page's. Unscaled by default; when a
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
- * Pixels and keys on a `WorldBrowser` page. Every provider's actions land here
172
- * as `ComputerAction` values and run as Playwright mouse and keyboard calls.
173
- * The cursor is tracked in the model's pixel space so a click without
174
- * coordinates lands where the pointer is. Twin of `native_computer/screen.py`.
175
- */
176
-
177
- type CdpSession = {
178
- send(method: string, params: Record<string, unknown>): Promise<{
179
- data: string;
180
- }>;
181
- detach(): Promise<void>;
182
- };
183
- /** The Playwright page surface pixel-level control needs, beyond `BrowserPage`. */
184
- type NativePage = {
185
- mouse: {
186
- move(x: number, y: number, opts?: {
187
- steps?: number;
188
- }): Promise<void>;
189
- click(x: number, y: number, opts?: {
190
- button?: string;
191
- clickCount?: number;
192
- }): Promise<void>;
193
- down(opts?: {
194
- button?: string;
195
- }): Promise<void>;
196
- up(opts?: {
197
- button?: string;
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
- wheel(dx: number, dy: number): Promise<void>;
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
- screenshot(opts?: {
208
- type?: "png";
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
- /** The slice of `WorldBrowser` a native computer drives. */
219
- type ScreenBrowser = {
220
- readonly page: BrowserPage;
221
- readonly viewport: {
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
- act<T>(action: string, args: Record<string, unknown>, fn: () => Promise<T>, onLoss?: "retry" | "report"): Promise<T>;
226
- settle(): Promise<void>;
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
- type Kind = new (browser: ScreenBrowser, options?: NativeComputerOptions) => NativeComputer;
296
- /** `item[name]` for the first spelling that is set (`scroll_x`, `scrollX`). */
297
- declare function readField(item: unknown, ...names: string[]): unknown;
298
- declare abstract class NativeComputer {
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
- * Key names from each provider's vocabulary, mapped once to Playwright's.
337
- * Anthropic sends xdotool-style chords (`ctrl+a`, `Return`); OpenAI sends
338
- * arrays of upper-case names (`["CTRL", "A"]`). Twin of
339
- * `gatewaysdk/native_computer/keys.py`; `conformance/native-computer.json` pins both.
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 const KEY_NAMES: Readonly<Record<string, string>>;
342
- /** One provider key name as Playwright names it; an unknown name passes through. */
343
- declare function playwrightKey(token: string): string;
344
- /** Keys pressed together, in Playwright's names (`["Control", "a"]`). */
345
- declare class KeyChord {
346
- readonly keys: readonly string[];
347
- private constructor();
348
- /** `ctrl+shift+t` / `Return`: Anthropic's vocabulary, case kept. */
349
- static fromXdotool(text: string): KeyChord;
350
- /** `["CTRL", "A"]`: OpenAI's vocabulary. A lone letter is the unshifted key. */
351
- static fromKeys(keys: readonly string[]): KeyChord;
352
- /** What `page.keyboard.press` takes: `Control+a`. */
353
- get combo(): string;
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
- * Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool
358
- * Twin of `gatewaysdk/native_computer/anthropic.py`.
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
- declare const NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed.";
362
- type Raw = Record<string, unknown>;
363
- type AiSdkAnthropicOutput = {
364
- type: "image";
365
- data: string;
366
- } | string;
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
- type AnthropicToolResult = {
402
- type: "tool_result";
403
- tool_use_id: string;
404
- toolset_name?: string;
405
- content: AnthropicContent[] | string;
406
- is_error?: true;
407
- };
408
- /** `computer_toolset_20260801` for Claude 5-family models (claude-sonnet-5-5,
409
- * claude-opus-5-5, ...): send `tool()` in `tools`, pass each response's
410
- * `content` to `execute`, and send the returned blocks back as the next user
411
- * message. */
412
- declare class AnthropicComputer extends NativeComputer {
413
- static readonly TOOL_TYPE: string;
414
- static readonly TOOLSET = "computer";
415
- static readonly BETA: string | null;
416
- static readonly MAX_LONG_EDGE: number;
417
- static readonly MAX_VISUAL_TOKENS = 4784;
418
- static readonly PATCH_PX = 28;
419
- static fits(width: number, height: number): boolean;
420
- tool(): Record<string, unknown>;
421
- /** Whether a content block is a call to this computer. */
422
- owns(block: unknown): boolean;
423
- member(block: unknown): [string, Raw];
424
- parse(raw: unknown): ComputerAction;
425
- /** Run every computer `tool_use` in a response's content, in order, and
426
- * return one `tool_result` per block. Other blocks are skipped. */
427
- execute(content: Iterable<unknown>): Promise<AnthropicToolResult[]>;
428
- /** The content an `ActionResult` goes back to the model as. */
429
- static content(result: ActionResult): AnthropicContent[];
430
- /** For `anthropic.tools.computerToolset_20260801(computer.aiSdk({ version: 7 }))`
431
- * (AI SDK 7 only), or `computer_20251124` with the legacy kind (AI SDK 6
432
- * and 7): `execute` runs one action and returns `{ type: "image", data }` or
433
- * text; `toModelOutput` turns that into the tool result in the part shape
434
- * of `options.version`. Calls run one at a time, and once a call fails the
435
- * rest of that step's calls answer as not executed. */
436
- aiSdk<V extends AiSdkMajor = 6>(options?: AiSdkOptions<V>): {
437
- execute: (input: unknown, options?: {
438
- messages?: readonly unknown[];
439
- }) => Promise<AiSdkAnthropicOutput>;
440
- toModelOutput: (options: {
441
- output: AiSdkAnthropicOutput;
442
- }) => AiSdkModelOutput<V>;
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
- static aiSdkOutput(result: ActionResult): AiSdkAnthropicOutput;
445
- /** A screenshot as the image part of AI SDK `options.version`:
446
- * `image-data` for 6 (the default), `file` with `{ type: "data", data }`
447
- * for 7. */
448
- static aiSdkModelOutput<V extends AiSdkMajor = 6>(output: AiSdkAnthropicOutput, options?: AiSdkOptions<V>): AiSdkModelOutput<V>;
449
- private static imagePart;
450
- private static modelOutput;
451
- protected envelope(block: unknown, content: AnthropicContent[] | string, isError?: boolean): AnthropicToolResult;
452
- private runBlock;
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
- /** The `computer_20251124` tool (beta header `computer-use-2025-11-24`) for
455
- * models before the toolset, and Claude 5.5 on Amazon Bedrock: one tool named
456
- * `computer` whose input carries `action`. */
457
- declare class AnthropicComputer20251124 extends AnthropicComputer {
458
- static readonly TOOL_TYPE = "computer_20251124";
459
- static readonly BETA = "computer-use-2025-11-24";
460
- static readonly MAX_LONG_EDGE = 1568;
461
- static readonly MAX_PIXELS = 1150000;
462
- static fits(width: number, height: number): boolean;
463
- tool(): Record<string, unknown>;
464
- owns(block: unknown): boolean;
465
- member(block: unknown): [string, Raw];
466
- protected envelope(block: unknown, content: AnthropicContent[] | string, isError?: boolean): AnthropicToolResult;
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
- * OpenAI's computer use: the Responses API `computer` tool (GA), and the
471
- * legacy `computer_use_preview` tool as a second kind. Each `computer_call`
472
- * carries an ordered batch of `actions` (the preview carried one `action`);
473
- * they run in order, then the screen goes back as a `computer_call_output`.
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 SafetyCheck = {
481
- id: string;
482
- code?: string;
483
- message?: string;
594
+ type CdpSession = {
595
+ send(method: string, params: Record<string, unknown>): Promise<{
596
+ data: string;
597
+ }>;
598
+ detach(): Promise<void>;
484
599
  };
485
- type ComputerCallOutput = {
486
- type: "computer_call_output";
487
- call_id: string;
488
- output: {
489
- type: "computer_screenshot";
490
- image_url: string;
491
- detail: "original";
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
- acknowledged_safety_checks?: SafetyCheck[];
494
- };
495
- type AiSdkComputerCall = {
496
- actions?: unknown[];
497
- pendingSafetyChecks?: unknown[];
498
- };
499
- type AiSdkComputerOutput = {
500
- output: {
501
- type: "computer_screenshot";
502
- imageUrl: string;
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 model flagged this call; nothing ran. Show `checks` to a person, then
507
- * `execute(call, checks)` to run it anyway. */
508
- declare class PendingSafetyChecks extends Error {
509
- readonly callId: string;
510
- readonly checks: SafetyCheck[];
511
- constructor(callId: string, checks: SafetyCheck[]);
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
- /** The batch's actions, run after the safety checks clear; the screen after them. */
536
- runCall(callId: string, rawActions: readonly unknown[], checks: readonly SafetyCheck[], acknowledged: readonly unknown[]): Promise<Buffer>;
537
- }
538
- /** The legacy `computer_use_preview` tool for the `computer-use-preview`
539
- * model: it declares the display size and `environment: "browser"`. */
540
- declare class OpenAIPreviewComputer extends OpenAIComputer {
541
- tool(): Record<string, unknown>;
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
- /** Python twin: `gatewaysdk/native_computer/`. */
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
- /** The class each provider name builds, so a caller gets the kind's own
547
- * `execute` without a cast. */
548
- type NativeComputerKinds = {
549
- anthropic: AnthropicComputer;
550
- "anthropic-computer-20251124": AnthropicComputer20251124;
551
- openai: OpenAIComputer;
552
- "openai-preview": OpenAIPreviewComputer;
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
- type NativeComputerProvider = keyof NativeComputerKinds;
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
- * STORED WORLD TASKS: a task spec kept by the project, outside any bundle.
558
- *
559
- * An inline task (`openSession(world, { task: { instruction, … } })`) belongs
560
- * to one session. A stored task is the same spec as a named, versioned
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
- type WorldTaskSummary = {
579
- id: string;
580
- name: string;
581
- world: string | null;
582
- version: number;
583
- hash: string;
584
- spec: WorldTaskSpec;
585
- /** A multi-world task's aliases in spec order; empty for a single world. */
586
- aliases: string[];
587
- /** Listed by world: the aliases that world plays in this task; else empty. */
588
- aliasesHere: string[];
589
- /** What grades the task, one row per check or verifier: its reward key,
590
- * the aliases it judges, what it checks in plain words, its source. */
591
- verifiers: WorldTaskVerifierRow[];
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
- * Turn a world's Python signature into a JSON schema the model can call.
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 WORLD_REQUEST_VIAS: readonly ["api", "ui", "tool", "webhook"];
727
- /** 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. */
728
- type WorldRequestEntry = Omit<WorldRequest, "request" | "response"> & {
729
- request: WorldRequest["request"] & {
730
- headers: Record<string, string>;
731
- body: string | null;
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
- response: WorldRequest["response"] & {
734
- body: string | null;
790
+ 7: {
791
+ type: "file";
792
+ mediaType: "image/png";
793
+ data: {
794
+ type: "data";
795
+ data: string;
796
+ };
735
797
  };
736
798
  };
737
- type WorldRequestFilter = {
738
- session?: string;
739
- version?: string;
740
- via?: string;
741
- operation?: string;
742
- status?: string;
743
- since?: string;
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
- declare class WorldRequestFilterError extends Error {
749
- }
750
- /** The platform's 409 `requests_not_recorded`: the session's engine keeps no request ledger, only World Host
751
- * sessions record requests. Its message is the platform's own sentence. */
752
- declare class WorldRequestsNotRecorded extends Error {
753
- static from(error: unknown): unknown;
754
- static mapped<T>(read: Promise<T>): Promise<T>;
755
- }
756
- /** The filters of a request-ledger read, checked and put in the platform's form: `via` and `status` lower-cased,
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
- /** The one line every reader shows for a page's `shed`, `lost` and `hostsLost`, none when all are 0; twin of
825
- * `worldRequestsUnrecorded` in the platform and `unrecorded` in `gatewaysdk/world_requests.py`, all pinned to
826
- * `conformance/world-request-log.json` `unrecorded`. */
827
- declare function worldRequestsUnrecorded(counts: {
828
- shed?: unknown;
829
- lost?: unknown;
830
- hostsLost?: unknown;
831
- }): string | null;
832
- /**
833
- * A session's entries in its world's request ledger: every request the world
834
- * received, through every door (`via`: api, ui, tool, webhook), kept for the life of
835
- * the world. Read page by page without recording anything in the session; the
836
- * platform's call ledger (`export()`) holds what it brokered — tool calls,
837
- * seeds, grades. One entry's headers and bodies are `GET
838
- * worlds/{slug}/requests/{requestId}`.
839
- */
840
- declare class WorldRequestLog {
841
- readonly requests: WorldRequest[];
842
- readonly notRecorded: string | null;
843
- readonly unrecorded: string | null;
844
- private constructor();
845
- /** Every entry the ledger holds for the session, oldest first, and the line for what it did not record;
846
- * for a session the World Host did not serve, none, and `notRecorded` says why. */
847
- static load(session: WorldSession): Promise<WorldRequestLog>;
848
- private static pages;
849
- /** Each entry in the shape of a ledger line, `kind: "request"`, so one JSONL
850
- * file holds both: `args` what was asked, `result` what came back under the
851
- * entry's `requestId`. */
852
- asCalls(): WorldSessionCall[];
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
- * A world's grade as the SDK reads it, by the one score rule every grader
857
- * answers by: a finite number from 0 to 1, a passed check 1, a failed one 0,
858
- * null ungraded. The World Host's twin is `gatewaysdk/environment/score.py`;
859
- * both are pinned by `gatewaysdk/fixtures/tasks/grade-vectors.json`.
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
- declare const messageOf: (error: unknown) => string;
862
- type GradeResult = {
863
- reward: number | null;
864
- rewards: Record<string, number>;
865
- /** Why there is no reward: `no grader` on an exploratory session. */
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 VerifierGrade = {
876
- reward: number | null;
877
- rewards: Record<string, number>;
878
- error?: string;
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
- declare class Score {
881
- static readonly RULE = "a score is a number from 0 to 1";
882
- static admits(value: number): boolean;
883
- /** Every number among `scores` that is not a score, as `'<key>' = <value>`
884
- * and the rule, or null when all of them are. Pairs, not a map, so that no
885
- * key hides another. */
886
- static problem(scores: Iterable<[string, unknown]>): string | null;
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
- /** A world's grade that is never filed: it is not an object, a number in it
889
- * is not a score (a World Host older than the rule), a check is named both
890
- * beside and inside its rewards, or its rewards or verifiers are not objects
891
- * by name. */
892
- declare class GradeRefused extends Error {
893
- readonly name = "GradeRefused";
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
- declare class GradePayload {
896
- /** A grade payload's numbers, checked: every number in it must be a score,
897
- * and its rewards and verifiers objects by name, or the grade is refused; a
898
- * cross-world verifier's grade that breaks either rule is that verifier's
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
- /** A JSON scalar: what `where` filters and field predicates compare against. */
920
- type WorldTaskScalar = string | number | boolean | null;
921
- /** The rows a task starts the session with — the `seed()` contract, applied
922
- * by the host right after it clones the version's snapshot. `append`
923
- * (default) upserts by primary key onto the base data; `replace` makes the
924
- * named entities hold exactly these rows. */
925
- type WorldTaskSeed = {
926
- mode?: "append" | "replace";
927
- /** Redaction on the way in: `off` (default) stores the rows as given,
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 WorldTaskFieldOp = "eq" | "neq" | "in" | "gt" | "gte" | "lt" | "lte" | "contains";
971
+ type NativeComputerProvider = keyof NativeComputerKinds;
972
+
934
973
  /**
935
- * One declarative check over the session's final rows. `where` selects rows
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
- * exists (default) / absent at least one row / none
940
- * count `count` bound on how many
941
- * all / any `field op value` on every / some selected row
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
- * A check's `id` names its entry in `rewards`; the task's reward is the
944
- * weighted share of checks that passed.
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 WorldTaskCheck = {
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
- description: string;
970
- weight?: number;
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
- /** A rubric is prose: what a good outcome looks like. The platform (never the
973
- * host) has a model read the session's final state and its call log against
974
- * it; the project's default evaluation model judges unless `model` pins one.
975
- * `grade()` then resolves asynchronously — `pending: true` first, the reward
976
- * once the judge has answered. */
977
- type WorldTaskRubricGrader = {
978
- kind: "rubric";
979
- rubric: string;
980
- criteria?: WorldTaskRubricCriterion[];
981
- model?: {
982
- provider: string;
983
- model: string;
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
- /** How a task is graded: checks the host evaluates in-process, a `verify.py`
987
- * body (state JSON on stdin, last stdout line `{reward, ...}`) run through the
988
- * host's confined verifier, or a rubric judged by a model on the platform. */
989
- type WorldTaskGrader = {
990
- kind: "assertions";
991
- checks: WorldTaskCheck[];
992
- } | {
993
- kind: "python";
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 WorldTaskVerifier = {
1034
- name: string;
1035
- scope: string[];
1036
- } & ({
1037
- kind: "assertions";
1038
- checks: WorldTaskCheck[];
1039
- } | {
1040
- kind: "python";
1041
- source: string;
1042
- timeoutSeconds?: number;
1043
- });
1044
- /** A stored task of the project (see worlds/tasks.ts), opened by id; the
1045
- * session runs a copy of one version's spec — the current one by default. */
1046
- type WorldTaskIdRef = {
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
- /** What `openSession` takes as the task: a bundled scenario's name, a
1051
- * stored task's `{ id, version? }`, or an inline spec. */
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
- * The three shapes a task reaches `openSession` in — a bundled scenario's
1068
- * name, a stored task's `{ id, version? }`, an inline spec — and how each is
1069
- * told apart, labelled and checked. No task at all (`undefined`) is the
1070
- * fourth case, an exploratory session, and is not a ref.
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 const isTaskIdRef: (task: WorldTaskRef) => task is WorldTaskIdRef;
1073
- declare const isTaskSpec: (task: WorldTaskRef) => task is WorldTaskSpec;
1074
- /** The label a task goes by in results: its name, `inline:<hash>` for an
1075
- * unnamed inline task once the platform has hashed it, or the stored task's
1076
- * name (its id until the platform has answered). */
1077
- declare const taskLabel: (task: WorldTaskRef, info?: WorldSessionTask | null) => string;
1078
- /** A task given to `openSession` must be one of the three shapes. */
1079
- declare const assertTaskRef: (task: WorldTaskRef) => void;
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 class WorldSessionTimeout extends Error {
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
- declare class WorldSessionCallError extends Error {
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 session ended before it was ready: it FAILED to open, or was STOPPED.
1086
- * `code` is the platform's when it named one; `browser_capacity` and
1087
- * `host_unavailable` are worth opening again. */
1088
- declare class WorldSessionOpenFailed extends WorldSessionCallError {
1089
- readonly sessionId: string;
1090
- readonly state: string;
1091
- readonly code: string | null;
1092
- constructor(sessionId: string, state: string, code: string | null, reason: string | null);
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
- * LIVE WORLD SESSIONS from TypeScript: your agent, the platform's container.
1097
- *
1098
- * The other two ways of running a world each give up something. Pulling the
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
- kind: string;
1169
- tool: string | null;
1170
- args: unknown;
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
- pin: {
1211
- ref: string | null;
1212
- versionId: string | null;
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
- boundarySeq: number;
1215
- boundaryAt: string;
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 notice a worlds-path answer carries: a deprecated shape or layout
1218
- * and the command that replaces it. A retired shape is refused instead,
1219
- * with the stable message prefix `world_kind_retired:`. */
1220
- type WorldDeprecation = {
1221
- code: string;
1222
- message: string;
1223
- replacement: string;
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
- * Open a live session on a world. Returns as soon as the platform has
1455
- * accepted it — call `ready()` to wait for the container.
1456
- *
1457
- * `task` is a bundled scenario's name, a stored task's `{ id, version? }`
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 function openSession(slugOrRef: string, task?: OpenSessionOptions & {
1466
- task?: WorldTaskRef;
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
- /** Set when the task threw instead of grading. */
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 SessionRunReport = {
1479
- results: SessionRunResult[];
1480
- /** Mean reward over every task, counting failures as 0. */
1481
- mean: number;
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
- * RUN MANY TASKS IN PARALLEL, one warm container each.
1491
- *
1492
- * Parallelism against live worlds is the normal case — a suite is a dozen
1493
- * tasks and each needs its own container, because two agents sharing one
1494
- * world state would corrupt both episodes. Every caller was writing the same
1495
- * pool, the same per-task open/ready/toolkit/grade/close, and the same
1496
- * "don't let one failure kill the run" logic, so it belongs here:
1497
- *
1498
- * const report = await runSessions({
1499
- * world: "revenue-ops-sim@main",
1500
- * tasks, // default: every task in the world
1501
- * concurrency: 4,
1502
- * failUnder: 0.7,
1503
- * agent: async ({ toolkit, instruction }) =>
1504
- * myAgent(toolkit.impls, toolkit.schemas, instruction),
1505
- * });
1506
- *
1507
- * The handler gets a ready session with its toolkit already bound, and runs
1508
- * inside `session.withTraceContext`; grading, closing (warm) and aggregation
1509
- * are handled. A task that throws scores 0 and records why — the tasks that
1510
- * passed keep their results.
1511
- */
1512
- declare function runSessions(opts: {
1513
- world: string;
1514
- /** Bundled task names, stored task refs and/or inline task specs
1515
- * (default: every bundled task in the world). */
1516
- tasks?: WorldTaskRef[];
1517
- concurrency?: number;
1518
- failUnder?: number;
1519
- /** Pin every session to one version (default: the world's head). */
1520
- versionId?: string;
1521
- /** Hand the containers back warm for the next run (default: true). */
1522
- keepWarm?: boolean;
1523
- agent: (ctx: {
1524
- session: WorldSession;
1525
- toolkit: WorldToolkit;
1526
- instruction: string;
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
- * A BROWSER ON A WORLD'S UI — the computer-use half of a live session.
1539
- *
1540
- * A session answers on SURFACES. `tools` is always there (the world's own
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
- * OBSERVABILITY. Every action a `WorldBrowser` takes (goto, click, type,
1568
- * press, scroll, back) is reported to the platform as one event — what was
1569
- * done, whether it worked, where the page ended up, and a JPEG of the screen
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
- * RECONNECT. A World Host browser on the `standard` tier can be reclaimed
1576
- * mid-session. When an action fails because the browser or its connection is
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
- declare const SURFACE_KINDS: readonly ["tools", "api", "ui", "browser"];
1585
- type WorldSurfaceKind = (typeof SURFACE_KINDS)[number];
1586
- /** The platform's own header for a session's token, which a World Host takes on
1587
- * every world whatever its vendor's auth; no vendor's client sends it. */
1588
- declare const PLATFORM_SESSION_HEADER = "X-World-Session";
1589
- declare const SESSION_AUTH_MODES: readonly ["vendor", "open"];
1590
- /** `open`: the session asks for no credential, reached on its capability
1591
- * hostname alone; `vendor`: the session's token, the way the world's `[auth]`
1592
- * says its vendor takes a key. Unset, the world's `[auth] mode`. */
1593
- type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];
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
- browser?: {
1645
- wsUrl: string;
1646
- /** `cdp`: the platform's Chromium relay (any number of agents share one
1647
- * browser, each in its own context). `playwright`: a `run-server` endpoint. */
1648
- protocol: "cdp" | "playwright";
1649
- viewport: {
1650
- width: number;
1651
- height: number;
1652
- };
1653
- /** The capacity tier the browser runs on; present for World Host sessions. */
1654
- tier?: BrowserTier;
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
- declare class WorldSurfaceUnavailable extends Error {
1658
- readonly surface: WorldSurfaceKind;
1659
- constructor(surface: WorldSurfaceKind, reason: string);
1660
- }
1661
- declare function surfaceKinds(s: SessionSurfaces): WorldSurfaceKind[];
1662
- /** The URL of `path` on a UI surface, carrying the session token when the
1663
- * surface has one. `path` may already have a query string; the token is
1664
- * appended to it. */
1665
- declare function uiUrl(ui: NonNullable<SessionSurfaces["ui"]>, path: string): string;
1666
- declare function uiEntryUrl(ui: NonNullable<SessionSurfaces["ui"]>): string;
1667
- /** `url` without its `token` query parameter: what may be logged or shown. */
1668
- declare function withoutUiToken(url: string): string;
1669
- /** The slice of a Playwright `Page` this module drives. */
1670
- type BrowserPage = {
1671
- url(): string;
1672
- goto(url: string, opts?: {
1673
- waitUntil?: "load";
1674
- }): Promise<unknown>;
1675
- click(selector: string): Promise<void>;
1676
- fill(selector: string, value: string): Promise<void>;
1677
- screenshot(opts?: {
1678
- type?: "png" | "jpeg";
1679
- quality?: number;
1680
- fullPage?: boolean;
1681
- }): Promise<Buffer>;
1682
- innerText(selector: string): Promise<string>;
1683
- content(): Promise<string>;
1684
- goBack(opts?: {
1685
- waitUntil?: "load";
1686
- }): Promise<unknown>;
1687
- waitForLoadState(state?: "load"): Promise<void>;
1688
- waitForTimeout(ms: number): Promise<void>;
1689
- on(event: "request" | "requestfinished" | "requestfailed", handler: (request: unknown) => void): unknown;
1690
- title(): Promise<string>;
1691
- keyboard: {
1692
- press(key: string): Promise<void>;
1693
- };
1694
- mouse: {
1695
- wheel(dx: number, dy: number): Promise<void>;
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 BrowserMode = "auto" | "hosted" | "local";
1699
- /** One browser action as the platform ingests it
1700
- * (`POST /world-sessions/{id}/browser-events`). */
1701
- type BrowserActionEvent = {
1702
- agentId: string;
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
- ts: string;
1705
- action: string;
1706
- args: Record<string, unknown>;
1707
- ok: boolean;
1514
+ kind: string;
1515
+ tool: string | null;
1516
+ args: unknown;
1517
+ result: unknown;
1708
1518
  error: string | null;
1709
- durationMs: number;
1710
- url: string | null;
1711
- title: string | null;
1712
- mode: Exclude<BrowserMode, "auto">;
1713
- viewport: {
1714
- width: number;
1715
- height: number;
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
- /** base64 JPEG of the screen after the action; null if it could not be taken. */
1718
- screenshot: string | null;
1567
+ boundarySeq: number;
1568
+ boundaryAt: string;
1719
1569
  };
1720
- /** The secret label of an open session's capability hostname in `url`
1721
- * (`o-<sid>-<label>[-api].<domain>`), else null: a credential, scrubbed from
1722
- * everything a browser records. Twin of the Python `capability_label`. */
1723
- declare function capabilityLabel(url: string | null | undefined): string | null;
1724
- declare function redactActionArgs(action: string, args: Record<string, unknown>): Record<string, unknown>;
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
- * Ships browser action events to the platform, off the action's hot path.
1727
- *
1728
- * `post` receives a batch of events (the request body's `events`). Events
1729
- * are numbered here, so ordering survives batching and retries — the
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 class BrowserActionRecorder {
1741
- private readonly post;
1742
- readonly agentId: string;
1743
- private readonly opts;
1744
- private seq;
1745
- private base;
1746
- private queue;
1747
- private timer;
1748
- private inflight;
1749
- sent: number;
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 Playwright entry points this module needs, so tests can inject a fake. */
1850
- type PlaywrightLike = {
1851
- chromium: {
1852
- connect(wsEndpoint: string): Promise<PlaywrightBrowserLike>;
1853
- connectOverCDP(endpointURL: string): Promise<PlaywrightBrowserLike>;
1854
- launch(opts?: {
1855
- headless?: boolean;
1856
- }): Promise<PlaywrightBrowserLike>;
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
- type PlaywrightBrowserLike = {
1860
- newContext(opts?: {
1861
- viewport?: {
1862
- width: number;
1863
- height: number;
1864
- };
1865
- }): Promise<{
1866
- newPage(): Promise<BrowserPage>;
1867
- close(): Promise<void>;
1868
- }>;
1869
- close(): Promise<void>;
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
- * The browser as model tools, in the same `WorldToolkit` shape the world's
1917
- * own tools come in — so an agent loop that already dispatches
1918
- * `toolkit().impls` merges `computerUseToolkit(b).impls` and gains a screen
1919
- * without a second dispatch path.
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 computerUseToolkit(browser: WorldBrowser, opts?: {
1922
- maxText?: number;
1923
- }): WorldToolkit;
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, --tag and --visibility. */
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 a shipped template and created by its first
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 shipped templates if `from` is unknown). Its first commit
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, ApiError, 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 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, 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, WorldSet, type WorldSqlOptions, type WorldSqlResult, 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, invalidFields, isBrowserGone, isSandboxCommitPending, isSandboxImportPending, isTaskIdRef, isTaskManifest, isTaskSpec, listEnvSecretKeys, listRunConfigs, listRuns, listSessions, listTaskSessions, listTasks, listWebhooks, localTreeState, messageOf, migrateProjectWorlds, migrateWorld, modelToolName, openBrowser, openSession, openTask, openWorld, openWorldVersion, parseErrorBody, 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, 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 };
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 };