@withgateway/sdk 0.4.0 → 0.9.1

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 (157) hide show
  1. package/dist/agents/index.d.mts +573 -0
  2. package/dist/agents/index.d.ts +573 -0
  3. package/dist/agents/index.js +1443 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1394 -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 +5655 -1890
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +5769 -2005
  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 +418 -120
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +418 -120
  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-DUHmS74p.d.ts → index-DIN14Lhg.d.ts} +27 -4
  24. package/dist/{index-mJhG3vZU.d.mts → index-DuB-eQ0Z.d.mts} +27 -4
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +2862 -438
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2820 -431
  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/replay/index.d.mts +1 -1
  34. package/dist/replay/index.d.ts +1 -1
  35. package/dist/replay/index.js.map +1 -1
  36. package/dist/replay/index.mjs.map +1 -1
  37. package/dist/traces/index.d.mts +3 -1
  38. package/dist/traces/index.d.ts +3 -1
  39. package/dist/traces/index.js +418 -120
  40. package/dist/traces/index.js.map +1 -1
  41. package/dist/traces/index.mjs +418 -120
  42. package/dist/traces/index.mjs.map +1 -1
  43. package/dist/tracing/index.d.mts +3 -2
  44. package/dist/tracing/index.d.ts +3 -2
  45. package/dist/tracing/index.js +257 -16
  46. package/dist/tracing/index.js.map +1 -1
  47. package/dist/tracing/index.mjs +257 -16
  48. package/dist/tracing/index.mjs.map +1 -1
  49. package/dist/transport-CpRe7zgd.d.mts +123 -0
  50. package/dist/transport-CpRe7zgd.d.ts +123 -0
  51. package/dist/worlds/index.d.mts +2086 -1749
  52. package/dist/worlds/index.d.ts +2086 -1749
  53. package/dist/worlds/index.js +1471 -269
  54. package/dist/worlds/index.js.map +1 -1
  55. package/dist/worlds/index.mjs +1466 -265
  56. package/dist/worlds/index.mjs.map +1 -1
  57. package/package.json +6 -1
  58. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  59. package/runtime/gatewaysdk/environment/_world.py +24 -1
  60. package/runtime/gatewaysdk/environment/bundle_manifest.py +243 -0
  61. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  62. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  63. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  64. package/runtime/gatewaysdk/environment/schema/api.py +27 -7
  65. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  66. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +2 -0
  67. package/runtime/gatewaysdk/environment/schema/call_capture.py +13 -1
  68. package/runtime/gatewaysdk/environment/schema/call_log.py +66 -0
  69. package/runtime/gatewaysdk/environment/schema/call_redaction.py +6 -0
  70. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  71. package/runtime/gatewaysdk/environment/schema/conform.py +32 -8
  72. package/runtime/gatewaysdk/environment/schema/connector.py +5 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  74. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  75. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +9 -19
  76. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  77. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  78. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  79. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  80. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  81. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  82. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  83. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  84. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  85. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  86. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  87. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  88. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  89. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  90. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  91. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  92. package/runtime/gatewaysdk/environment/schema/database/guard.py +2 -1
  93. package/runtime/gatewaysdk/environment/schema/handler_errors.py +27 -1
  94. package/runtime/gatewaysdk/environment/schema/host.py +74 -11
  95. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  96. package/runtime/gatewaysdk/environment/schema/host_control.py +33 -2
  97. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  98. package/runtime/gatewaysdk/environment/schema/host_requests.py +14 -0
  99. package/runtime/gatewaysdk/environment/schema/host_session.py +13 -2
  100. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  101. package/runtime/gatewaysdk/environment/schema/host_versions.py +96 -19
  102. package/runtime/gatewaysdk/environment/schema/journal.py +10 -4
  103. package/runtime/gatewaysdk/environment/schema/local.py +33 -7
  104. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  105. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  106. package/runtime/gatewaysdk/environment/schema/platform.py +33 -480
  107. package/runtime/gatewaysdk/environment/schema/platform_templates.py +332 -0
  108. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  109. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  110. package/runtime/gatewaysdk/environment/schema/runtime.py +49 -4
  111. package/runtime/gatewaysdk/environment/schema/scaffold.py +369 -218
  112. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  113. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  114. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  115. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +20 -24
  116. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +11 -11
  117. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  118. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
  119. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +40 -9
  120. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  121. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  122. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  123. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  124. package/runtime/gatewaysdk/environment/schema/snapshot.py +30 -4
  125. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  126. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  127. package/runtime/gatewaysdk/environment/schema/tools_world.py +26 -5
  128. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  129. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  130. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  131. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  132. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  133. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  134. package/runtime/gatewaysdk/environment/schema/validation.py +10 -1
  135. package/runtime/gatewaysdk/environment/schema/verbs.py +6 -0
  136. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  137. package/runtime/gatewaysdk/environment/schema/worker.py +5 -1
  138. package/runtime/gatewaysdk/environment/schema/workers.py +8 -1
  139. package/runtime/gatewaysdk/environment/schema/world_host.py +64 -18
  140. package/runtime/gatewaysdk/environment/schema/world_tests.py +74 -0
  141. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  142. package/runtime/gatewaysdk/environment/world.py +34 -43
  143. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  144. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  145. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  146. package/skills/connector-schema-authoring/SKILL.md +20 -24
  147. package/skills/connector-schema-authoring/connector-worlds.md +155 -13
  148. package/skills/connector-schema-authoring/world-schema.md +36 -29
  149. package/skills/world-data-ingestion/SKILL.md +11 -11
  150. package/skills/worlds-getting-started/SKILL.md +9 -9
  151. package/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
  152. package/skills/worlds-getting-started/references/gotchas.md +40 -9
  153. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  154. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  155. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  156. package/dist/media-BIApiPzS.d.mts +0 -102
  157. 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,1762 +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;
310
+ /** base64 JPEG of the screen after the action; null if it could not be taken. */
311
+ screenshot: string | null;
285
312
  };
286
- type Kind = new (browser: ScreenBrowser, options?: NativeComputerOptions) => NativeComputer;
287
- /** `item[name]` for the first spelling that is set (`scroll_x`, `scrollX`). */
288
- declare function readField(item: unknown, ...names: string[]): unknown;
289
- declare abstract class NativeComputer {
290
- readonly browser: ScreenBrowser;
291
- private static readonly kinds;
292
- readonly display: Display;
293
- readonly screen: Screen;
294
- readonly tracer: ActionTracer;
295
- private queue;
296
- static register(provider: string, kind: Kind): void;
297
- static get providers(): string[];
298
- static forProvider(provider: string, browser: ScreenBrowser, options?: NativeComputerOptions): NativeComputer;
299
- constructor(browser: ScreenBrowser, options?: NativeComputerOptions);
300
- /** Whether a screenshot of this size is within the provider's limits. */
301
- static fits(_width: number, _height: number): boolean;
302
- /** The tool definition to send the model. */
303
- abstract tool(): Record<string, unknown>;
304
- /** One action in the provider's own shape, as a `ComputerAction`. */
305
- abstract parse(raw: unknown): ComputerAction;
306
- /** The options to spread into the Vercel AI SDK's provider-defined computer
307
- * tool (`execute` and its companions), backed by this computer. */
308
- abstract aiSdk(): object;
309
- /** Run one provider-shaped action (an OpenAI action object, or an Anthropic
310
- * `{ action: "left_click", ... }` input) and return what it produced: the
311
- * door for any agent framework that hands actions over one at a time. */
312
- executeAction(raw: unknown): Promise<ActionResult>;
313
- /** Run one action on the page: reported on the session's browser timeline
314
- * and, when tracing is on, as a span with the screen after. */
315
- perform(action: ComputerAction): Promise<ActionResult>;
316
- performAll(actions: readonly ComputerAction[]): Promise<ActionResult[]>;
317
- /** The screen as the model sees it, as a traced `screenshot` action. */
318
- screenshot(): Promise<Buffer>;
319
- /** Run `fn` after every earlier call made through here: the AI SDK starts a
320
- * step's tool calls concurrently, but one screen takes one action at a time. */
321
- protected serial<T>(fn: () => Promise<T>): Promise<T>;
322
- private runOnScreen;
323
- private onLoss;
324
- }
325
-
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;
326
317
  /**
327
- * Key names from each provider's vocabulary, mapped once to Playwright's.
328
- * Anthropic sends xdotool-style chords (`ctrl+a`, `Return`); OpenAI sends
329
- * arrays of upper-case names (`["CTRL", "A"]`). Twin of
330
- * `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.
331
331
  */
332
- declare const KEY_NAMES: Readonly<Record<string, string>>;
333
- /** One provider key name as Playwright names it; an unknown name passes through. */
334
- declare function playwrightKey(token: string): string;
335
- /** Keys pressed together, in Playwright's names (`["Control", "a"]`). */
336
- declare class KeyChord {
337
- readonly keys: readonly string[];
338
- private constructor();
339
- /** `ctrl+shift+t` / `Return`: Anthropic's vocabulary, case kept. */
340
- static fromXdotool(text: string): KeyChord;
341
- /** `["CTRL", "A"]`: OpenAI's vocabulary. A lone letter is the unshifted key. */
342
- static fromKeys(keys: readonly string[]): KeyChord;
343
- /** What `page.keyboard.press` takes: `Control+a`. */
344
- 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;
345
361
  }
346
-
347
362
  /**
348
- * Anthropic's computer use: the `computer_toolset_20260801` toolset (GA, no
349
- * beta header) and the older `computer_20251124` tool as a second kind.
350
- * With the toolset each action is its own `tool_use` block named after the
351
- * action and marked `"toolset_name": "computer"`; a turn may carry several.
352
- * They run in order; the first failure is reported with `is_error` and every
353
- * later block in the turn is answered as not executed.
354
- * Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool
355
- * 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.
356
365
  */
357
-
358
- declare const NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed.";
359
- type Raw = Record<string, unknown>;
360
- type AiSdkAnthropicOutput = {
361
- type: "image";
362
- data: string;
363
- } | string;
364
- type AiSdkModelOutput = {
365
- type: "text";
366
- value: string;
367
- } | {
368
- type: "content";
369
- value: {
370
- type: "image-data";
371
- data: string;
372
- mediaType: "image/png";
373
- }[];
374
- };
375
- type AnthropicContent = {
376
- type: "text";
377
- text: string;
378
- } | {
379
- type: "image";
380
- source: {
381
- type: "base64";
382
- media_type: "image/png";
383
- 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;
384
373
  };
385
- };
386
- type AnthropicToolResult = {
387
- type: "tool_result";
388
- tool_use_id: string;
389
- toolset_name?: string;
390
- content: AnthropicContent[] | string;
391
- is_error?: true;
392
- };
393
- /** `computer_toolset_20260801` for Claude 5-family models (claude-sonnet-5-5,
394
- * claude-opus-5-5, ...): send `tool()` in `tools`, pass each response's
395
- * `content` to `execute`, and send the returned blocks back as the next user
396
- * message. */
397
- declare class AnthropicComputer extends NativeComputer {
398
- static readonly TOOL_TYPE: string;
399
- static readonly TOOLSET = "computer";
400
- static readonly BETA: string | null;
401
- static readonly MAX_LONG_EDGE: number;
402
- static readonly MAX_VISUAL_TOKENS = 4784;
403
- static readonly PATCH_PX = 28;
404
- static fits(width: number, height: number): boolean;
405
- tool(): Record<string, unknown>;
406
- /** Whether a content block is a call to this computer. */
407
- owns(block: unknown): boolean;
408
- member(block: unknown): [string, Raw];
409
- parse(raw: unknown): ComputerAction;
410
- /** Run every computer `tool_use` in a response's content, in order, and
411
- * return one `tool_result` per block. Other blocks are skipped. */
412
- execute(content: Iterable<unknown>): Promise<AnthropicToolResult[]>;
413
- /** The content an `ActionResult` goes back to the model as. */
414
- static content(result: ActionResult): AnthropicContent[];
415
- /** For `anthropic.tools.computerToolset_20260801({ ...computer.aiSdk() })`
416
- * (or `computer_20251124` with the legacy kind): `execute` runs one action
417
- * and returns `{ type: "image", data }` or text; `toModelOutput` turns that
418
- * into the tool result. Calls run one at a time, and once a call fails the
419
- * rest of that step's calls answer as not executed. */
420
- aiSdk(): {
421
- execute: (input: unknown, options?: {
422
- messages?: readonly unknown[];
423
- }) => Promise<AiSdkAnthropicOutput>;
424
- toModelOutput: (options: {
425
- output: AiSdkAnthropicOutput;
426
- }) => AiSdkModelOutput;
427
- };
428
- static aiSdkOutput(result: ActionResult): AiSdkAnthropicOutput;
429
- /** `image-data` is what AI SDK 6's Anthropic provider turns into an image
430
- * block; AI SDK 7 still accepts it (and converts it to a `file` part). */
431
- static aiSdkModelOutput(output: AiSdkAnthropicOutput): AiSdkModelOutput;
432
- protected envelope(block: unknown, content: AnthropicContent[] | string, isError?: boolean): AnthropicToolResult;
433
- private runBlock;
434
- }
435
- /** The `computer_20251124` tool (beta header `computer-use-2025-11-24`) for
436
- * models before the toolset, and Claude 5.5 on Amazon Bedrock: one tool named
437
- * `computer` whose input carries `action`. */
438
- declare class AnthropicComputer20251124 extends AnthropicComputer {
439
- static readonly TOOL_TYPE = "computer_20251124";
440
- static readonly BETA = "computer-use-2025-11-24";
441
- static readonly MAX_LONG_EDGE = 1568;
442
- static readonly MAX_PIXELS = 1150000;
443
- static fits(width: number, height: number): boolean;
444
- tool(): Record<string, unknown>;
445
- owns(block: unknown): boolean;
446
- member(block: unknown): [string, Raw];
447
- protected envelope(block: unknown, content: AnthropicContent[] | string, isError?: boolean): AnthropicToolResult;
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>;
448
478
  }
449
-
450
- /**
451
- * OpenAI's computer use: the Responses API `computer` tool (GA), and the
452
- * legacy `computer_use_preview` tool as a second kind. Each `computer_call`
453
- * carries an ordered batch of `actions` (the preview carried one `action`);
454
- * they run in order, then the screen goes back as a `computer_call_output`.
455
- * A call with `pending_safety_checks` is not executed until the caller passes
456
- * them back as `acknowledged`.
457
- * Docs: https://developers.openai.com/api/docs/guides/tools-computer-use
458
- * Twin of `gatewaysdk/native_computer/openai.py`.
459
- */
460
-
461
- type SafetyCheck = {
462
- id: string;
463
- code?: string;
464
- message?: string;
465
- };
466
- type ComputerCallOutput = {
467
- type: "computer_call_output";
468
- call_id: string;
469
- output: {
470
- type: "computer_screenshot";
471
- image_url: string;
472
- detail: "original";
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>;
473
487
  };
474
- acknowledged_safety_checks?: SafetyCheck[];
475
- };
476
- type AiSdkComputerCall = {
477
- actions?: unknown[];
478
- pendingSafetyChecks?: unknown[];
479
488
  };
480
- type AiSdkComputerOutput = {
481
- output: {
482
- type: "computer_screenshot";
483
- imageUrl: string;
484
- };
485
- acknowledgedSafetyChecks?: SafetyCheck[];
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>;
486
500
  };
487
- /** The model flagged this call; nothing ran. Show `checks` to a person, then
488
- * `execute(call, checks)` to run it anyway. */
489
- declare class PendingSafetyChecks extends Error {
490
- readonly callId: string;
491
- readonly checks: SafetyCheck[];
492
- constructor(callId: string, checks: SafetyCheck[]);
493
- }
494
- /** The GA `computer` tool (gpt-5.5, gpt-5.6-sol and the other models whose
495
- * page lists computer use): send `tool()` in `tools`, pass each
496
- * `computer_call` item to `execute`, and send the returned
497
- * `computer_call_output` back with `previous_response_id`. */
498
- declare class OpenAIComputer extends NativeComputer {
499
- tool(): Record<string, unknown>;
500
- owns(item: unknown): boolean;
501
- parse(raw: unknown): ComputerAction;
502
- static actionsOf(call: unknown): unknown[];
503
- /** Run a `computer_call`'s actions and return its `computer_call_output`.
504
- * Throws `PendingSafetyChecks` (before anything runs) while a check the
505
- * model raised is not in `acknowledged`. */
506
- execute(call: unknown, acknowledged?: readonly unknown[]): Promise<ComputerCallOutput>;
507
- /** For `openai.tools.computer({ ...computer.aiSdk() })`: `execute` runs a
508
- * call's `actions` and returns the screenshot output. A call with pending
509
- * safety checks asks for approval first (`needsApproval`), so the AI SDK's
510
- * approval flow puts them in front of a person; once approved, `execute`
511
- * acknowledges them. */
512
- aiSdk(): {
513
- execute: (input: AiSdkComputerCall) => Promise<AiSdkComputerOutput>;
514
- needsApproval: (input: AiSdkComputerCall) => boolean;
515
- };
516
- /** The batch's actions, run after the safety checks clear; the screen after them. */
517
- runCall(callId: string, rawActions: readonly unknown[], checks: readonly SafetyCheck[], acknowledged: readonly unknown[]): Promise<Buffer>;
518
- }
519
- /** The legacy `computer_use_preview` tool for the `computer-use-preview`
520
- * model: it declares the display size and `environment: "browser"`. */
521
- declare class OpenAIPreviewComputer extends OpenAIComputer {
522
- tool(): Record<string, unknown>;
523
- }
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>;
524
512
 
525
513
  /**
526
- * Native computer use: Anthropic's and OpenAI's pixel-based computer-use
527
- * tools served by a world session's browser. Kinds: `anthropic`
528
- * (`computer_toolset_20260801`), `anthropic-computer-20251124`, `openai`
529
- * (Responses `computer`) and `openai-preview` (`computer_use_preview`).
530
- * Python twin: `gatewaysdk/native_computer/`.
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`.
531
517
  */
532
-
533
- /** The class each provider name builds, so a caller gets the kind's own
534
- * `execute` without a cast. */
535
- type NativeComputerKinds = {
536
- anthropic: AnthropicComputer;
537
- "anthropic-computer-20251124": AnthropicComputer20251124;
538
- openai: OpenAIComputer;
539
- "openai-preview": OpenAIPreviewComputer;
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>;
552
+ }
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;
540
558
  };
541
- type NativeComputerProvider = keyof NativeComputerKinds;
542
559
 
543
560
  /**
544
- * STORED WORLD TASKS: a task spec kept by the project, outside any bundle.
545
- *
546
- * An inline task (`openSession(world, { task: { instruction, … } })`) belongs
547
- * to one session. A stored task is the same spec as a named, versioned
548
- * project resource: create it once, open as many sessions on it as you like
549
- * with `{ task: { id } }`, and every grade attributes back to the task and
550
- * its version. Updating the spec never rewrites history — it appends a
551
- * version, and a session opened on `{ id, version: 2 }` keeps running v2
552
- * after v3 exists.
553
- *
554
- * const task = await createTask({
555
- * name: "refund-late-invoice",
556
- * world: "acme-billing",
557
- * spec: { instruction: "…", seed: {…}, grader: {…} },
558
- * });
559
- * const session = await openSession("acme-billing", { task: { id: task.id } });
560
- *
561
- * Tasks are project-scoped: another project's task id is not found (404),
562
- * never forbidden. `world` pins a task to one world's slug (validated against
563
- * that world's contract); null leaves it usable with any world.
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`.
564
565
  */
565
- type WorldTaskSummary = {
566
- id: string;
567
- name: string;
568
- world: string | null;
569
- version: number;
570
- hash: string;
571
- spec: WorldTaskSpec;
572
- /** A multi-world task's aliases in spec order; empty for a single world. */
573
- aliases: string[];
574
- /** Listed by world: the aliases that world plays in this task; else empty. */
575
- aliasesHere: string[];
576
- /** What grades the task, one row per check or verifier: its reward key,
577
- * the aliases it judges, what it checks in plain words, its source. */
578
- verifiers: WorldTaskVerifierRow[];
579
- createdAt: string;
580
- updatedAt: string;
581
- createdBy: string;
582
- updatedBy: string;
583
- /** On create, when the task is pinned to a world of a deprecated shape (an
584
- * api bundle): what to run instead. A retired shape is refused. */
585
- deprecations?: {
586
- code: string;
587
- message: string;
588
- replacement: string;
589
- }[];
590
- };
591
- type WorldTaskVersionSummary = {
592
- version: number;
593
- hash: string;
594
- createdAt: string;
595
- createdBy: string;
596
- message: string | null;
597
- };
598
- type WorldTaskVerifierRow = {
599
- key: string;
600
- aliases: string[];
601
- kind: "assertions" | "python" | "rubric";
602
- description: string | null;
603
- source: string | null;
604
- sourceLanguage: "python" | "text" | null;
605
- };
606
- type WorldTaskDetail = WorldTaskSummary & {
607
- versions: WorldTaskVersionSummary[];
608
- };
609
- type WorldTaskPage = {
610
- tasks: WorldTaskSummary[];
611
- meta: {
612
- page: number;
613
- limit: number;
614
- totalItems: number;
615
- totalPages: number;
616
- /** Listed by world: the scan for multi-world tasks naming it filled its
617
- * bound, so `totalItems` is a floor. */
618
- scanTruncated?: true;
619
- };
620
- };
621
- type WorldTaskWorldValidation = {
622
- slug: string;
623
- ref: string;
624
- versionId: string;
625
- ok: boolean;
626
- checked: "entities" | "none";
627
- problems: string[];
628
- entities: string[] | null;
629
- };
630
- type WorldTaskValidation = {
631
- taskId: string;
632
- version: number;
633
- /** The world version the task was checked against; null for a task with
634
- * `worlds`, whose versions are per alias under `worlds`. */
635
- versionId: string | null;
636
- ok: boolean;
637
- /** `entities` when the world's contract was read and every seed and check
638
- * entity was matched against it; `none` when the version has no contract
639
- * to check (a mock-tools world), in which case `ok` says only that the
640
- * version exists and is READY; `worlds` for a multi-world task, checked
641
- * alias by alias against the ref each names. */
642
- checked: "entities" | "none" | "worlds";
643
- /** For a multi-world task each problem is prefixed with its alias. */
644
- problems: string[];
645
- entities: string[] | null;
646
- worlds?: Record<string, WorldTaskWorldValidation>;
647
- };
648
- /** Store a task. `name` defaults to `spec.name`; one of the two is needed. */
649
- declare function createTask(input: {
650
- spec: WorldTaskSpec;
651
- name?: string;
652
- world?: string | null;
653
- message?: string;
654
- }, options?: WorldsClientOptions): Promise<WorldTaskSummary>;
655
- /** Change a task. A new `spec` becomes the next version (the old ones stay
656
- * readable and openable); `name` and `world` change in place. */
657
- declare function updateTask(taskId: string, input: {
658
- spec?: WorldTaskSpec;
659
- name?: string;
660
- world?: string | null;
661
- message?: string;
662
- }, options?: WorldsClientOptions): Promise<WorldTaskSummary>;
663
- /** The project's tasks, newest change first. `world` keeps only tasks
664
- * that run against that slug (pinned to it, or naming it under an alias); `metadata` keeps tasks whose spec metadata carries
665
- * every given key/value (`{ externalUserId: "u_42" }`). */
666
- declare function listTasks(filter?: {
667
- world?: string;
668
- metadata?: Record<string, string>;
669
- page?: number;
670
- limit?: number;
671
- }, options?: WorldsClientOptions): Promise<WorldTaskPage>;
672
- /** One task with its version history; `version` reads that version's spec
673
- * instead of the current one. */
674
- declare function getTask(taskId: string, opts?: {
675
- version?: number;
676
- }, options?: WorldsClientOptions): Promise<WorldTaskDetail>;
677
- /** Remove a task and every version. Sessions already opened on it keep
678
- * their copy of the spec. */
679
- declare function deleteTask(taskId: string, options?: WorldsClientOptions): Promise<{
680
- id: string;
681
- name: string;
682
- }>;
683
- /** Check a task against a world version without opening a session: every
684
- * seed entity and every check's entity must exist in the world's contract.
685
- * `slug` checks against that world's head, `versionId` against an exact
686
- * version, neither against the task's own `world` pin. */
687
- declare function validateTask(taskId: string, target?: {
688
- version?: number;
689
- slug?: string;
690
- versionId?: string;
691
- }, options?: WorldsClientOptions): Promise<WorldTaskValidation>;
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];
585
+ }
692
586
 
693
- declare const modelToolName: (name: string) => string;
694
587
  /**
695
- * Turn a world's Python signature into a JSON schema the model can call.
696
- *
697
- * `crm_update_deal(id, stage=None, owner=None, amount=None)` becomes an
698
- * object with `id` required and the rest optional. Types are read from the
699
- * DEFAULTS the world declares — a numeric default means a number, a boolean
700
- * default a boolean — because that is the only type information a signature
701
- * actually carries. Everything else is a string, which is what a tool CLI
702
- * receives anyway.
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`.
703
592
  */
704
- declare function schemaFromSignature(spec: WorldToolSpec): {
705
- type: "function";
706
- function: {
707
- name: string;
708
- description: string;
709
- parameters: Record<string, unknown>;
710
- };
711
- };
712
593
 
713
- /** One entry of a world's request ledger as a list carries it: what was asked
714
- * and what came back, without its headers and bodies. */
715
- type WorldRequest = {
716
- id: string;
717
- seq: number;
718
- at: string;
719
- durationMs: number | null;
720
- worldSlug: string;
721
- sessionId: string;
722
- versionId: string;
723
- via: "api" | "ui" | "tool" | null;
724
- operation: string | null;
725
- method: string | null;
726
- path: string | null;
727
- query: Record<string, unknown>;
728
- request: {
729
- bodyBytes: number | null;
730
- truncated: boolean;
731
- contentType: string | null;
594
+ type CdpSession = {
595
+ send(method: string, params: Record<string, unknown>): Promise<{
596
+ data: string;
597
+ }>;
598
+ detach(): Promise<void>;
599
+ };
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>;
732
617
  };
733
- response: {
734
- status: number;
735
- bodyBytes: number | null;
736
- truncated: boolean;
737
- contentType: string | null;
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>;
738
633
  };
739
- rows: number | null;
740
- found: boolean | null;
741
634
  };
742
- /** One page of a ledger list, newest first, with what its scope did not record: `shed` requests kept without
743
- * their headers and bodies, `lost` requests a host counted as never recorded or the platform refused, and
744
- * `hostsLost` hosts lost before they stored every request, whose unsent requests no count holds; none of them on
745
- * a page whose filters narrow past its world, session or version. */
746
- type WorldRequestPage = {
747
- requests: WorldRequest[];
748
- nextCursor: string | null;
749
- shed?: number;
750
- lost?: number;
751
- hostsLost?: number;
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;
641
+ };
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;
752
645
  };
753
- /** The one line every reader shows for a page's `shed`, `lost` and `hostsLost`, none when all are 0; twin of
754
- * `worldRequestsUnrecorded` in the platform and `unrecorded` in `gatewaysdk/world_requests.py`, all pinned to
755
- * `conformance/world-request-log.json` `unrecorded`. */
756
- declare function worldRequestsUnrecorded(counts: {
757
- shed?: unknown;
758
- lost?: unknown;
759
- hostsLost?: unknown;
760
- }): string | null;
761
- /**
762
- * A session's entries in its world's request ledger: every request the world
763
- * received, through every door (`via`: api, ui, tool), kept for the life of
764
- * the world. Read page by page without recording anything in the session; the
765
- * platform's call ledger (`export()`) holds what it brokered — tool calls,
766
- * seeds, grades. One entry's headers and bodies are `GET
767
- * worlds/{slug}/requests/{requestId}`.
768
- */
769
- declare class WorldRequestLog {
770
- readonly requests: WorldRequest[];
771
- readonly notRecorded: string | null;
772
- readonly unrecorded: string | null;
773
- private constructor();
774
- /** Every entry the ledger holds for the session, oldest first, and the line for what it did not record;
775
- * for a session the World Host did not serve, none, and `notRecorded` says why. */
776
- static load(session: WorldSession): Promise<WorldRequestLog>;
777
- private static pages;
778
- /** Each entry in the shape of a ledger line, `kind: "request"`, so one JSONL
779
- * file holds both: `args` what was asked, `result` what came back under the
780
- * entry's `requestId`. */
781
- asCalls(): WorldSessionCall[];
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;
782
676
  }
783
677
 
784
- /**
785
- * A world's grade as the SDK reads it, by the one score rule every grader
786
- * answers by: a finite number from 0 to 1, a passed check 1, a failed one 0,
787
- * null ungraded. The World Host's twin is `gatewaysdk/environment/score.py`;
788
- * both are pinned by `gatewaysdk/fixtures/tasks/grade-vectors.json`.
789
- */
790
- declare const messageOf: (error: unknown) => string;
791
- type GradeResult = {
792
- reward: number | null;
793
- rewards: Record<string, number>;
794
- /** Why there is no reward: `no grader` on an exploratory session. */
795
- reason?: string;
796
- /** Why this world could not grade; the task's grade is then that error. */
797
- error?: string;
798
- /** The task's cross-world verifiers anchored on this session, by name:
799
- * each its own reward and named rewards, or `error` when it could not
800
- * grade (evidence missing, verify.py failed) — null, never zero. */
801
- verifiers?: Record<string, VerifierGrade>;
802
- raw: unknown;
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
+ }
694
+
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;
803
702
  };
804
- type VerifierGrade = {
805
- reward: number | null;
806
- rewards: Record<string, number>;
807
- error?: string;
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;
808
711
  };
809
- declare class Score {
810
- static readonly RULE = "a score is a number from 0 to 1";
811
- static admits(value: number): boolean;
812
- /** Every number among `scores` that is not a score, as `'<key>' = <value>`
813
- * and the rule, or null when all of them are. Pairs, not a map, so that no
814
- * key hides another. */
815
- static problem(scores: Iterable<[string, unknown]>): string | null;
816
- }
817
- /** A world's grade that is never filed: it is not an object, a number in it
818
- * is not a score (a World Host older than the rule), a check is named both
819
- * beside and inside its rewards, or its rewards or verifiers are not objects
820
- * by name. */
821
- declare class GradeRefused extends Error {
822
- readonly name = "GradeRefused";
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;
823
750
  }
824
- declare class GradePayload {
825
- /** A grade payload's numbers, checked: every number in it must be a score,
826
- * and its rewards and verifiers objects by name, or the grade is refused; a
827
- * cross-world verifier's grade that breaks either rule is that verifier's
828
- * error, the way the World Host answers one that could not grade. */
829
- static read(raw: unknown): Omit<GradeResult, "raw">;
830
- /** A world whose grade call failed (the platform refused it, the host had
831
- * lost the session): that world's error, never a score. */
832
- static failedCall(error: unknown): GradeResult;
833
- private static problem;
834
- private static twice;
835
- private static verifiersProblem;
836
- private static scores;
837
- private static isRecord;
838
- private static objectOrAbsent;
839
- private static record;
840
- /** `reward`, and every numeric key under `rewards` (the host's shape) or at
841
- * the top level (a bundled verifier's). */
842
- private static numbers;
843
- private static verifiers;
844
- private static verifier;
845
- private static failed;
751
+
752
+ /**
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.
757
+ */
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;
846
771
  }
847
772
 
848
- /** A JSON scalar: what `where` filters and field predicates compare against. */
849
- type WorldTaskScalar = string | number | boolean | null;
850
- /** The rows a task starts the session with — the `seed()` contract, applied
851
- * by the host right after it clones the version's snapshot. `append`
852
- * (default) upserts by primary key onto the base data; `replace` makes the
853
- * named entities hold exactly these rows. */
854
- type WorldTaskSeed = {
855
- mode?: "append" | "replace";
856
- /** Redaction on the way in: `off` (default) stores the rows as given,
857
- * `apply` runs the world's `[redact]` policy over them first, `refuse`
858
- * rejects a row carrying plaintext in a redacted field. */
859
- redact?: "off" | "apply" | "refuse";
860
- rows: Record<string, Record<string, unknown>[]>;
861
- };
862
- type WorldTaskFieldOp = "eq" | "neq" | "in" | "gt" | "gte" | "lt" | "lte" | "contains";
863
773
  /**
864
- * One declarative check over the session's final rows. `where` selects rows
865
- * of `entity` by equality (dotted paths reach into nested objects); the
866
- * assertion says what must hold of the selection:
867
- *
868
- * exists (default) / absent at least one row / none
869
- * count `count` bound on how many
870
- * all / any `field op value` on every / some selected row
871
- *
872
- * A check's `id` names its entry in `rewards`; the task's reward is the
873
- * weighted share of checks that passed.
774
+ * Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool
775
+ * Twin of `gatewaysdk/native_computer/anthropic.py`.
874
776
  */
875
- type WorldTaskCheck = {
876
- id?: string;
877
- weight?: number;
878
- entity: string;
879
- where?: Record<string, WorldTaskScalar>;
880
- assert?: "exists" | "absent" | "count" | "all" | "any";
881
- count?: {
882
- eq?: number;
883
- gte?: number;
884
- lte?: number;
777
+
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";
885
789
  };
886
- field?: string;
887
- op?: WorldTaskFieldOp;
888
- value?: WorldTaskScalar | WorldTaskScalar[];
889
- /** On `gateway_requests` or `calls`: only the requests before the first one this matches. */
890
- before?: Record<string, WorldTaskScalar>;
891
- /** On `gateway_requests` or `calls`: only the requests after the first one this matches. */
892
- after?: Record<string, WorldTaskScalar>;
893
- };
894
- /** One thing a rubric judge scores in [0, 1]; `id` names its entry in
895
- * `rewards`, `weight` (default 1) its share of the task's reward. */
896
- type WorldTaskRubricCriterion = {
897
- id: string;
898
- description: string;
899
- weight?: number;
900
- };
901
- /** A rubric is prose: what a good outcome looks like. The platform (never the
902
- * host) has a model read the session's final state and its call log against
903
- * it; the project's default evaluation model judges unless `model` pins one.
904
- * `grade()` then resolves asynchronously — `pending: true` first, the reward
905
- * once the judge has answered. */
906
- type WorldTaskRubricGrader = {
907
- kind: "rubric";
908
- rubric: string;
909
- criteria?: WorldTaskRubricCriterion[];
910
- model?: {
911
- provider: string;
912
- model: string;
790
+ 7: {
791
+ type: "file";
792
+ mediaType: "image/png";
793
+ data: {
794
+ type: "data";
795
+ data: string;
796
+ };
913
797
  };
914
798
  };
915
- /** How a task is graded: checks the host evaluates in-process, a `verify.py`
916
- * body (state JSON on stdin, last stdout line `{reward, ...}`) run through the
917
- * host's confined verifier, or a rubric judged by a model on the platform. */
918
- type WorldTaskGrader = {
919
- kind: "assertions";
920
- checks: WorldTaskCheck[];
799
+ type AiSdkImagePart<V extends AiSdkMajor = AiSdkMajor> = ImageParts[V];
800
+ type AiSdkModelOutput<V extends AiSdkMajor = 6> = {
801
+ type: "text";
802
+ value: string;
921
803
  } | {
922
- kind: "python";
923
- source: string;
924
- timeoutSeconds?: number;
925
- readsJournal?: boolean;
926
- acceptsIncompleteJournal?: boolean;
927
- } | WorldTaskRubricGrader;
928
- /** A task supplied at open, for one session, instead of a bundled scenario.
929
- * `instruction` is what the agent is told; without `seed` the session starts
930
- * on the version's base data, without `grader` `grade()` answers
931
- * `reward: null`; `tools` is the allow-list of the version's tools the agent
932
- * may call in this session (unset: all of them; a call outside it is refused
933
- * and logged); `metadata` is yours (an end-user id, a ticket) and is echoed
934
- * on the session, never read. Limits: shared/domain/worldTasks.ts. */
935
- type WorldTaskSpec = {
936
- name?: string;
937
- instruction: string;
938
- seed?: WorldTaskSeed;
939
- grader?: WorldTaskGrader;
940
- tools?: string[];
941
- metadata?: Record<string, unknown>;
942
- /** A MULTI-WORLD task: one session per alias, each on its own world with
943
- * its own seed, grader and tools (the top-level three are then refused).
944
- * Brought up together by `openTask` / `gateway worlds task up`; see
945
- * worlds/taskSessions.ts. */
946
- worlds?: Record<string, {
947
- slug: string;
948
- /** One of the world's refs; default `main`. */
949
- ref?: string;
950
- seed?: WorldTaskSeed;
951
- grader?: WorldTaskGrader;
952
- tools?: string[];
953
- }>;
954
- /** CROSS-WORLD VERIFIERS: deterministic graders over several of the task's
955
- * worlds at once, each with a `scope` of aliases (two or more). One runs on
956
- * the session of the first alias in its scope, over a state where every
957
- * scoped world's rows are `<alias>.<entity>` and its calls `<alias>.calls`;
958
- * the platform gathers the other worlds' evidence when `grade()` names
959
- * them (`TaskSessions.grade` does). Rewards come back as `x.<name>`. */
960
- verifiers?: WorldTaskVerifier[];
804
+ type: "content";
805
+ value: AiSdkImagePart<V>[];
961
806
  };
962
- type WorldTaskVerifier = {
963
- name: string;
964
- scope: string[];
965
- } & ({
966
- kind: "assertions";
967
- checks: WorldTaskCheck[];
807
+ type AnthropicContent = {
808
+ type: "text";
809
+ text: string;
968
810
  } | {
969
- kind: "python";
970
- source: string;
971
- timeoutSeconds?: number;
972
- });
973
- /** A stored task of the project (see worlds/tasks.ts), opened by id; the
974
- * session runs a copy of one version's spec — the current one by default. */
975
- type WorldTaskIdRef = {
976
- id: string;
977
- version?: number;
811
+ type: "image";
812
+ source: {
813
+ type: "base64";
814
+ media_type: "image/png";
815
+ data: string;
816
+ };
978
817
  };
979
- /** What `openSession` takes as the task: a bundled scenario's name, a
980
- * stored task's `{ id, version? }`, or an inline spec. */
981
- type WorldTaskRef = string | WorldTaskIdRef | WorldTaskSpec;
982
- /** What a session's task is, on every session response. `hash` is the
983
- * content hash of the spec (inline or stored) — what warm reuse matches on;
984
- * `id`/`version` name the stored task the session was opened on. */
985
- type WorldSessionTask = {
986
- /** `none` is an exploratory session: opened with no task, no grader. */
987
- source: "bundled" | "inline" | "stored" | "none";
988
- name: string | null;
989
- hash: string | null;
990
- id?: string | null;
991
- version?: number | null;
992
- metadata: Record<string, unknown>;
818
+ type AnthropicToolResult = {
819
+ type: "tool_result";
820
+ tool_use_id: string;
821
+ toolset_name?: string;
822
+ content: AnthropicContent[] | string;
823
+ is_error?: true;
993
824
  };
994
-
995
- /**
996
- * The three shapes a task reaches `openSession` in — a bundled scenario's
997
- * name, a stored task's `{ id, version? }`, an inline spec — and how each is
998
- * told apart, labelled and checked. No task at all (`undefined`) is the
999
- * fourth case, an exploratory session, and is not a ref.
1000
- */
1001
- declare const isTaskIdRef: (task: WorldTaskRef) => task is WorldTaskIdRef;
1002
- declare const isTaskSpec: (task: WorldTaskRef) => task is WorldTaskSpec;
1003
- /** The label a task goes by in results: its name, `inline:<hash>` for an
1004
- * unnamed inline task once the platform has hashed it, or the stored task's
1005
- * name (its id until the platform has answered). */
1006
- declare const taskLabel: (task: WorldTaskRef, info?: WorldSessionTask | null) => string;
1007
- /** A task given to `openSession` must be one of the three shapes. */
1008
- declare const assertTaskRef: (task: WorldTaskRef) => void;
1009
-
1010
- declare class WorldSessionTimeout extends Error {
1011
- }
1012
- declare class WorldSessionCallError extends Error {
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;
1013
870
  }
1014
- /** The session ended before it was ready: it FAILED to open, or was STOPPED.
1015
- * `code` is the platform's when it named one; `browser_capacity` and
1016
- * `host_unavailable` are worth opening again. */
1017
- declare class WorldSessionOpenFailed extends WorldSessionCallError {
1018
- readonly sessionId: string;
1019
- readonly state: string;
1020
- readonly code: string | null;
1021
- constructor(sessionId: string, state: string, code: string | null, reason: string | null);
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;
1022
884
  }
1023
885
 
1024
886
  /**
1025
- * LIVE WORLD SESSIONS from TypeScript: your agent, the platform's container.
1026
- *
1027
- * The other two ways of running a world each give up something. Pulling the
1028
- * bundle and executing it locally tests your agent against a COPY — your
1029
- * python, your sqlite, your machine's idea of the environment. Dispatching a
1030
- * hosted run gives you the real container but runs the platform's agent
1031
- * inside it, so your agent never touches the world.
1032
- *
1033
- * A session is both: the platform boots the task's container and holds it
1034
- * warm, and every `call()` here executes inside THAT container. Your agent
1035
- * stays where it is — this file is just the wire.
1036
- *
1037
- * const world = await openWorld("revenue-ops-sim@main");
1038
- * const session = await openSession(world.slug, { task: "revops-mara-dedupe-contacts" });
1039
- * await session.ready(); // wait for the container
1040
- * await session.call("crm_search", { entity: "deals" });
1041
- * await session.withTraceContext(() => myAgent(session)); // traced under session.sessionId
1042
- * const { reward, rewards } = await session.grade();
1043
- * await session.close({ keepWarm: true }); // hand it back to the pool
1044
- *
1045
- * The task can also be YOURS rather than the bundle's — an instruction, the
1046
- * rows the session starts with and how it is graded, for one end user:
1047
- *
1048
- * const session = await openSession("acme-billing@main", {
1049
- * task: {
1050
- * instruction: "Mark invoice INV-7 as paid.",
1051
- * seed: { rows: { invoices: [{ id: "INV-7", status: "open" }] } },
1052
- * grader: { kind: "assertions", checks: [
1053
- * { entity: "invoices", where: { id: "INV-7", status: "paid" } },
1054
- * ] },
1055
- * metadata: { externalUserId: "u_42" },
1056
- * },
1057
- * surfaces: ["api"],
1058
- * });
1059
- *
1060
- * Every call is a row on the platform before it is an effect in a container,
1061
- * so the episode is on the record — and the platform traces the session
1062
- * itself, which is why these sessions show up under Sessions without the
1063
- * caller instrumenting anything.
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`.
1064
895
  */
1065
- type WorldToolSpec = {
1066
- name: string;
1067
- /** The world's own signature, e.g. `crm_search(q=None, entity="deals")`. */
1068
- signature: string;
1069
- doc: string | null;
1070
- inputSchema?: Record<string, unknown>;
896
+
897
+ type SafetyCheck = {
898
+ id: string;
899
+ code?: string;
900
+ message?: string;
1071
901
  };
1072
- /** What a model needs to call a world: the schemas to advertise, and the
1073
- * implementations that run them in the container. */
1074
- type WorldToolkit = {
1075
- /** OpenAI-shaped tool definitions, derived from the world's signatures. */
1076
- schemas: {
1077
- type: "function";
1078
- function: {
1079
- name: string;
1080
- description: string;
1081
- parameters: Record<string, unknown>;
1082
- };
1083
- }[];
1084
- /** name -> implementation, each one a call into THIS session. */
1085
- impls: Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
1086
- specs: WorldToolSpec[];
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[];
1087
911
  };
1088
-
1089
- type SeedResult = {
1090
- seeded: number;
1091
- mode: "append" | "replace";
1092
- entity_counts: Record<string, number>;
912
+ type AiSdkComputerCall = {
913
+ actions?: unknown[];
914
+ pendingSafetyChecks?: unknown[];
1093
915
  };
1094
- /** One row of the session's call log. */
1095
- type WorldSessionCall = {
1096
- seq: number;
1097
- kind: string;
1098
- tool: string | null;
1099
- args: unknown;
1100
- result: unknown;
1101
- error: string | null;
1102
- completedAt: string | null;
916
+ type AiSdkComputerOutput = {
917
+ output: {
918
+ type: "computer_screenshot";
919
+ imageUrl: string;
920
+ };
921
+ acknowledgedSafetyChecks?: SafetyCheck[];
1103
922
  };
1104
- type WorldSessionState = {
1105
- sessionId: string;
1106
- state: string;
1107
- ready: boolean;
1108
- versionId: string;
1109
- contentHash: string;
1110
- taskName: string | null;
1111
- /** Where the task came from and what it is; absent on platforms that
1112
- * predate session tasks, in which case it is derived from `taskName`. */
1113
- task?: WorldSessionTask;
1114
- /** The task's objective — present when the session was opened (not on a
1115
- * bare status read), so a client never needs the bundle on disk. */
1116
- instruction?: string | null;
1117
- /** The tools this task serves. */
1118
- tools?: WorldToolSpec[];
1119
- /** When the fleet reaps this session unless a call lands first; null for
1120
- * a pinned session (never reaped). Absent on platforms that predate it. */
1121
- idleExpiresAt?: string | null;
1122
- pinned?: boolean;
1123
- /** Where the session answers besides `tools` — see worlds/browser.ts. */
1124
- surfaces?: SessionSurfaces;
1125
- /** Notices about the world's shape (an api bundle is a deprecated layout;
1126
- * schema worlds are the supported shape), with what to run instead. Empty
1127
- * for a schema world; absent on platforms that predate the notice. */
1128
- deprecations?: WorldDeprecation[];
1129
- /** Why a FAILED session failed to open, when the platform named it. */
1130
- failure?: {
1131
- code: string | null;
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[]);
929
+ }
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>;
954
+ }
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>;
959
+ }
960
+
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;
970
+ };
971
+ type NativeComputerProvider = keyof NativeComputerKinds;
972
+
973
+ /**
974
+ * STORED WORLD TASKS: a task spec kept by the project, outside any bundle.
975
+ *
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.
983
+ *
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.
994
+ */
995
+ type WorldTaskSummary = {
996
+ id: string;
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;
1132
1017
  message: string;
1133
- } | null;
1018
+ replacement: string;
1019
+ }[];
1134
1020
  };
1135
- /** A request the old world received has an `at` before `boundaryAt`; one the new world received, after it. */
1136
- type WorldSessionRestart = {
1137
- previousVersionId: string;
1138
- versionId: string;
1139
- pin: {
1140
- ref: string | null;
1141
- versionId: string | null;
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;
1142
1049
  };
1143
- boundarySeq: number;
1144
- boundaryAt: string;
1145
1050
  };
1146
- /** One notice a worlds-path answer carries: a deprecated shape or layout
1147
- * and the command that replaces it. A retired shape is refused instead,
1148
- * with the stable message prefix `world_kind_retired:`. */
1149
- type WorldDeprecation = {
1150
- code: string;
1151
- message: string;
1152
- replacement: string;
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;
1059
+ };
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>;
1153
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<{
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?: {
1118
+ version?: number;
1119
+ slug?: string;
1120
+ versionId?: string;
1121
+ }, options?: WorldsClientOptions): Promise<WorldTaskValidation>;
1154
1122
 
1155
- declare class WorldSession {
1156
- readonly sessionId: string;
1157
- private current;
1158
- private readonly options;
1159
- constructor(sessionId: string, current: WorldSessionState, options: WorldsClientOptions);
1160
- /** The task's display name: a bundled scenario's, or the inline spec's
1161
- * `name` (null when the spec was unnamed). `task` is the same. */
1162
- get taskName(): string | null;
1163
- get task(): string | null;
1164
- /** `{idleExpiresAt, pinned}` as of the last state read: when the fleet
1165
- * reaps the session (null once pinned), and whether it is pinned. */
1166
- get idle(): {
1167
- idleExpiresAt: string | null;
1168
- pinned: boolean;
1169
- };
1170
- /** The platform's notices about the world this session runs on (empty
1171
- * for a schema world). Printed by the CLI on stderr at open. */
1172
- get deprecations(): WorldDeprecation[];
1173
- /** The task this session runs: bundled scenario, stored task or inline
1174
- * spec, its name, hash and the caller's metadata. */
1175
- get taskInfo(): WorldSessionTask;
1176
- /** What this task asks for — the bundle's instruction.md, or the inline
1177
- * spec's `instruction`. */
1178
- get instruction(): string | null;
1179
- get versionId(): string;
1180
- /** Whether the session answered ready as of the last state read (the open,
1181
- * a `status()`, or the poll inside `ready()`); no request is made. */
1182
- get isReady(): boolean;
1183
- /** `api` / `ui` / `browser` are present exactly when the world declares
1184
- * them AND the session was opened asking for them. */
1185
- surfaces(): Promise<SessionSurfaces>;
1186
- /** Base URL of the world's own HTTP API for this session. */
1187
- api(): Promise<string>;
1188
- /** Headers every request to `api()` needs: a World Host session's token in the
1189
- * platform's `X-World-Session` header, which every world takes; `{}` for a pod
1190
- * or hosted twin, which answers with the world's own declared auth. */
1191
- apiHeaders(): Promise<Record<string, string>>;
1192
- /** URL of the world's UI entry page for this session. */
1193
- ui(): Promise<string>;
1194
- /** A Playwright browser on this session's UI: `hosted` drives the one the
1195
- * platform runs next to the world, `local` launches one here, `auto`
1196
- * prefers hosted. Call `close()` when done.
1197
- *
1198
- * Every action is reported to the platform under `agentId` (default:
1199
- * `GATEWAY_AGENT_ID` or a fresh `agent-<hex>`) so the session page shows
1200
- * this agent's own timeline — several agents may share one session and
1201
- * one hosted browser. `record: false` opts out. */
1202
- browser(opts?: {
1203
- mode?: BrowserMode;
1204
- headless?: boolean;
1205
- playwright?: PlaywrightLike;
1206
- agentId?: string;
1207
- record?: boolean;
1208
- }): Promise<WorldBrowser>;
1209
- /** Ask the platform to make this session's hosted browser reachable again
1210
- * after its connection dropped: `healthy` (reconnect now), `replaced` (a new,
1211
- * blank browser behind the same wsUrl; reconnect and reopen your page) or
1212
- * `starting` (ask again in `retryAfterMs`). `browser()` does this on its
1213
- * own; call it when you drive your own Playwright against `wsUrl`. */
1214
- repairBrowser(): Promise<RepairAnswer>;
1215
- /** The reporter `browser()` uses; exposed for a page you drive yourself. */
1216
- browserRecorder(agentId?: string): BrowserActionRecorder;
1217
- /** Browser actions as model tools, in the same shape as `toolkit()`. */
1218
- computerUseTools(browser: WorldBrowser): WorldToolkit;
1219
- /** The browser as a provider's own pixel-based computer-use tool: `anthropic`
1220
- * (`computer_toolset_20260801`), `openai` (Responses `computer`),
1221
- * `anthropic-computer-20251124` or `openai-preview`. See `nativeComputer/`. */
1222
- nativeComputer<P extends NativeComputerProvider = "anthropic">(browser: WorldBrowser, provider?: P, options?: NativeComputerOptions): NativeComputerKinds[P];
1223
- /** The session's latest platform state (one request, no waiting). */
1224
- status(): Promise<WorldSessionState>;
1225
- /** The world started over under the same id, URLs and token, on what its pin (or `version`, which becomes
1226
- * its pin) resolves to now: base data plus the task's seed. A grade then reads only the new world's requests. */
1227
- restart(opts?: {
1228
- version?: string;
1229
- }): Promise<WorldSessionState & {
1230
- restart: WorldSessionRestart;
1231
- }>;
1232
- private refresh;
1233
- /**
1234
- * Wait until the session answers calls: a World Host holds it, or the
1235
- * process inside a pod has asked the platform for work. Throws
1236
- * `WorldSessionOpenFailed` (with the platform's reason) when it ended
1237
- * first, and `WorldSessionTimeout` when `timeoutMs` (default ten minutes)
1238
- * ran out while it was still starting.
1239
- */
1240
- ready(opts?: {
1241
- timeoutMs?: number;
1242
- }): Promise<WorldSessionState>;
1243
- /** Enqueue one interaction and wait for the container's answer. */
1244
- private exchange;
1245
- /**
1246
- * Run one of the world's tools INSIDE the container. The arguments and the
1247
- * result are the world's own contract — this layer neither validates nor
1248
- * reshapes them, so a tool error reads exactly as it would in a hosted run.
1249
- */
1250
- call(tool: string, args?: Record<string, unknown>, opts?: {
1251
- timeoutMs?: number;
1252
- }): Promise<unknown>;
1253
- /**
1254
- * THE WORLD'S TOOLS, READY TO HAND TO A MODEL. Schemas come from the
1255
- * world's own signatures and implementations call into this session, so a
1256
- * caller never writes — and never has to re-sync — a tool map of their own:
1257
- *
1258
- * const { schemas, impls } = await session.toolkit();
1259
- * await runMyAgent(impls, schemas, session.instruction);
1260
- *
1261
- * A tool added to the world shows up here on the next run; a tool renamed
1262
- * in the world renames here too, instead of failing at call time against a
1263
- * hand-written map that still remembers the old name.
1264
- */
1265
- toolkit(): Promise<WorldToolkit>;
1266
- /** Run the task's grader against the container's END STATE. Graders answer
1267
- * in one of two shapes: the scalar with named rewards beside it
1268
- * (`{reward, check_a, check_b}`, a task's own `grade.py`), or the named
1269
- * rewards nested under `rewards` (the api, mock-tools and World Host
1270
- * runners). Both land in `rewards`.
1271
- *
1272
- * A rubric grade is finalized by the platform's judge, not the container:
1273
- * the platform answers the enqueue with `pending: true`, and this waits on
1274
- * the judge's budget (15 min) instead of a call's. `timeoutMs` overrides
1275
- * either. `report` is the agent's own account of what it did and found,
1276
- * handed to the judge as its claim beside the evidence (the state and the
1277
- * calls); assertions and python graders ignore it. `worlds` names the
1278
- * task's other sessions by alias (`{alias: sessionId}`): the platform
1279
- * reads each one's evidence and hands it to the cross-world verifiers
1280
- * anchored on this session, whose grades come back under `verifiers`. A
1281
- * score that is not a number from 0 to 1 is refused by key and value
1282
- * (`GradeRefused`); a verifier's is that verifier's `error`. */
1283
- grade(opts?: {
1284
- timeoutMs?: number;
1285
- report?: string;
1286
- worlds?: Record<string, string>;
1287
- }): Promise<GradeResult>;
1288
- /**
1289
- * Put rows into the LIVE world through its contract, in one batch:
1290
- * `append` (default) upserts by primary key, `replace` makes the named
1291
- * entities hold exactly these rows. Atomic — a refused row leaves the
1292
- * session unchanged and the error names the entity, row and field.
1293
- */
1294
- seed(rows: Record<string, Record<string, unknown>[]>, opts?: {
1295
- mode?: "append" | "replace";
1296
- /** `apply` runs the world's `[redact]` policy over the rows first;
1297
- * `refuse` rejects plaintext in a redacted field; default `off`. */
1298
- redact?: "off" | "apply" | "refuse";
1299
- timeoutMs?: number;
1300
- }): Promise<SeedResult>;
1301
- /** Every entity's rows as the world holds them now — the same dump a
1302
- * grader reads. The shape is the world runtime's: a schema world answers
1303
- * `{<entity>: {<key>: row}, snapshot}`, a mock-tools world
1304
- * `{entities: {<entity>: [row]}}`. */
1305
- state(opts?: {
1306
- timeoutMs?: number;
1307
- }): Promise<unknown>;
1308
- /** Back to the opening state: the version's data plus the bundled
1309
- * scenario's or the inline task's seed. Rows written since are gone; the
1310
- * call log stays. */
1311
- reset(opts?: {
1312
- timeoutMs?: number;
1313
- }): Promise<void>;
1314
- /** One page of the session's entries in its world's request ledger, newest
1315
- * first and without bodies: at most `limit` after `cursor` (the last page's
1316
- * `nextCursor`). Reading it records nothing in the session. */
1317
- requests(opts?: {
1318
- cursor?: string;
1319
- limit?: number;
1320
- }): Promise<WorldRequestPage>;
1321
- private page;
1322
- /** The session's call log, oldest first: every tool call, seed, reset,
1323
- * grade with its result — the record of the episode. */
1324
- export(): Promise<WorldSessionCall[]>;
1325
- /**
1326
- * Promote this session's inline task into a stored task of the project
1327
- * (version 1, pinned to the session's world unless `world` says otherwise),
1328
- * so a task written for one end user can be reused and its grades
1329
- * compared. The session then records the new task's id. A session on a
1330
- * bundled task has nothing to save; one on a stored task is already saved.
1331
- */
1332
- saveTask(opts?: {
1333
- name?: string;
1334
- world?: string | null;
1335
- message?: string;
1336
- }): Promise<WorldTaskSummary>;
1337
- /**
1338
- * End the session. `keepWarm` hands the container back to the pool instead
1339
- * of tearing it down, so the next session for the same task starts warm —
1340
- * the pooled instance still obeys the fleet's idle TTL and pinning.
1341
- */
1342
- close(opts?: {
1343
- keepWarm?: boolean;
1344
- }): Promise<{
1345
- state: string;
1346
- }>;
1347
- /**
1348
- * Run `fn` as work inside this session: spans it records take `sessionId`
1349
- * as their session id and carry `world_session_id` trace metadata, so the
1350
- * agent's traces land in the same session as the platform's traces of this
1351
- * session's tool calls. A `withSession()` block inside still wins for the
1352
- * session id. No effect before `tracing.init()`. `runSessions` wraps each
1353
- * agent call in it.
1354
- *
1355
- * ```typescript
1356
- * await session.withTraceContext(() => myAgent(toolkit, session.instruction));
1357
- * ```
1358
- */
1359
- withTraceContext<T>(fn: () => T | Promise<T>): Promise<T>;
1360
- }
1361
- /**
1362
- * Attach to a session that already exists — resuming after a crash, or
1363
- * driving a session someone else opened (a container started by hand on a
1364
- * self-hosted install, a session opened by CI and handed to a developer).
1365
- */
1366
- declare function attachSession(sessionId: string, options?: WorldsClientOptions): Promise<WorldSession>;
1367
- type OpenSessionOptions = {
1368
- versionId?: string;
1369
- reuseWarm?: boolean;
1370
- /** More than `tools`: `["api"]`, `["ui"]`, `["browser"]`. The platform
1371
- * refuses (HTTP 400) rather than quietly serving less than asked. */
1372
- surfaces?: WorldSurfaceKind[];
1373
- /** Capacity for a World Host session's browser: `standard` (spot, may be
1374
- * reclaimed) or `premium` (on-demand). Unset, the organization's default. */
1375
- browserTier?: BrowserTier;
1376
- /** `open`: the session asks for no credential; its api and ui answer on a
1377
- * capability hostname whose url is the secret. Unset, the world's
1378
- * `[auth] mode`. World Host sessions only. */
1379
- auth?: SessionAuthMode;
1380
- options?: WorldsClientOptions;
1381
- };
1123
+ declare const modelToolName: (name: string) => string;
1382
1124
  /**
1383
- * Open a live session on a world. Returns as soon as the platform has
1384
- * accepted it — call `ready()` to wait for the container.
1125
+ * Turn a world's Python signature into a JSON schema the model can call.
1385
1126
  *
1386
- * `task` is a bundled scenario's name, a stored task's `{ id, version? }`
1387
- * or an inline `WorldTaskSpec` (the latter two need a host engine world — the
1388
- * platform answers 400 for a pod world). Omitted, the session is EXPLORATORY:
1389
- * the platform records an inline `{instruction: "exploratory session"}` with
1390
- * no grader as `task.source: "none"`, and `grade()` answers
1391
- * `{reward: null, reason: "no grader"}`. The older positional form
1392
- * `openSession(slug, "task-name", opts)` still works.
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.
1393
1133
  */
1394
- declare function openSession(slugOrRef: string, task?: OpenSessionOptions & {
1395
- task?: WorldTaskRef;
1396
- }): Promise<WorldSession>;
1397
- declare function openSession(slugOrRef: string, task: WorldTaskRef, opts?: OpenSessionOptions): Promise<WorldSession>;
1398
- type SessionRunResult = {
1399
- /** The task's name, or `inline:<hash>` for an unnamed inline task. */
1400
- task: string;
1401
- sessionId: string;
1402
- reward: number | null;
1403
- rewards: Record<string, number>;
1404
- /** Set when the task threw instead of grading. */
1405
- error?: string;
1134
+ declare function schemaFromSignature(spec: WorldToolSpec): {
1135
+ type: "function";
1136
+ function: {
1137
+ name: string;
1138
+ description: string;
1139
+ parameters: Record<string, unknown>;
1140
+ };
1406
1141
  };
1407
- type SessionRunReport = {
1408
- results: SessionRunResult[];
1409
- /** Mean reward over every task, counting failures as 0. */
1410
- mean: number;
1411
- /** Tasks that never graded: the session did not open or become ready, the
1412
- * agent threw, or grading failed. Any failure fails the run — a 0 an agent
1413
- * earned and a session that never opened are not the same result. */
1414
- failed: number;
1415
- /** True when no task failed and `mean >= failUnder` (or no gate was set). */
1416
- passed: boolean;
1417
- };
1418
- /**
1419
- * RUN MANY TASKS IN PARALLEL, one warm container each.
1420
- *
1421
- * Parallelism against live worlds is the normal case — a suite is a dozen
1422
- * tasks and each needs its own container, because two agents sharing one
1423
- * world state would corrupt both episodes. Every caller was writing the same
1424
- * pool, the same per-task open/ready/toolkit/grade/close, and the same
1425
- * "don't let one failure kill the run" logic, so it belongs here:
1426
- *
1427
- * const report = await runSessions({
1428
- * world: "revenue-ops-sim@main",
1429
- * tasks, // default: every task in the world
1430
- * concurrency: 4,
1431
- * failUnder: 0.7,
1432
- * agent: async ({ toolkit, instruction }) =>
1433
- * myAgent(toolkit.impls, toolkit.schemas, instruction),
1434
- * });
1435
- *
1436
- * The handler gets a ready session with its toolkit already bound, and runs
1437
- * inside `session.withTraceContext`; grading, closing (warm) and aggregation
1438
- * are handled. A task that throws scores 0 and records why — the tasks that
1439
- * passed keep their results.
1440
- */
1441
- declare function runSessions(opts: {
1442
- world: string;
1443
- /** Bundled task names, stored task refs and/or inline task specs
1444
- * (default: every bundled task in the world). */
1445
- tasks?: WorldTaskRef[];
1446
- concurrency?: number;
1447
- failUnder?: number;
1448
- /** Pin every session to one version (default: the world's head). */
1449
- versionId?: string;
1450
- /** Hand the containers back warm for the next run (default: true). */
1451
- keepWarm?: boolean;
1452
- agent: (ctx: {
1453
- session: WorldSession;
1454
- toolkit: WorldToolkit;
1455
- instruction: string;
1456
- /** The task's label — see `SessionRunResult.task`. */
1457
- task: string;
1458
- /** The task as it was given: a bundled name, a stored ref or the
1459
- * inline spec. */
1460
- taskRef: WorldTaskRef;
1461
- }) => Promise<unknown>;
1462
- onResult?: (result: SessionRunResult) => void;
1463
- options?: WorldsClientOptions;
1464
- }): Promise<SessionRunReport>;
1465
1142
 
1466
- /**
1467
- * A BROWSER ON A WORLD'S UI — the computer-use half of a live session.
1468
- *
1469
- * A session answers on SURFACES. `tools` is always there (the world's own
1470
- * operations over the rendezvous). An api-type world may also answer on
1471
- * `api` (the service itself), `ui` (its dashboard, over the same state) and
1472
- * `browser` — a headless Chromium the platform runs NEXT TO that UI, which
1473
- * an agent drives through Playwright. This file is the TS client for the
1474
- * last two, call for call with `gatewaysdk/world_browser.py`.
1475
- *
1476
- * const s = await openSession("payments-like", "refund-dispute", {
1477
- * surfaces: ["ui", "browser"],
1478
- * });
1479
- * await s.ready();
1480
- * const b = await s.browser(); // hosted, next to the world
1481
- * await b.goto(); // the UI's entry page
1482
- * await b.click("text=Refund");
1483
- * const tools = computerUseToolkit(b); // the same actions as model tools
1484
- * await b.close();
1485
- *
1486
- * Playwright is an OPTIONAL peer: nothing here imports it until a browser is
1487
- * opened, so sessions that never touch a UI never load it.
1488
- *
1489
- * MODES. `hosted` connects to the session's own browser (a Playwright server
1490
- * the pod exposes over an authenticated websocket). `local` launches Chromium
1491
- * on this machine and points it at the UI — a laptop against a hosted twin,
1492
- * or a test. `auto` prefers hosted. Asking for a mode the session cannot
1493
- * serve throws `WorldSurfaceUnavailable`; there is no silent fallback to a
1494
- * browser other than the one the episode is judged on.
1495
- *
1496
- * OBSERVABILITY. Every action a `WorldBrowser` takes (goto, click, type,
1497
- * press, scroll, back) is reported to the platform as one event — what was
1498
- * done, whether it worked, where the page ended up, and a JPEG of the screen
1499
- * after — through a `BrowserActionRecorder`. Reporting is fire-and-forget
1500
- * and never fails the action; the platform renders it as the session's
1501
- * browser timeline. Text typed into secret-looking fields is redacted before
1502
- * it leaves the process.
1503
- *
1504
- * RECONNECT. A World Host browser on the `standard` tier can be reclaimed
1505
- * mid-session. When an action fails because the browser or its connection is
1506
- * gone, a hosted `cdp` browser asks the platform to repair it, reconnects to
1507
- * the same address and reopens the page it was on (see `browserReconnect.ts`).
1508
- * A read or a `goto` then runs once more; a click, type, press, back or scroll
1509
- * is NOT replayed — its input may already have reached the world — and throws
1510
- * `BrowserReconnected` so the agent looks at the page again. Local and
1511
- * `playwright`-protocol browsers never reconnect.
1512
- */
1513
- declare const SURFACE_KINDS: readonly ["tools", "api", "ui", "browser"];
1514
- type WorldSurfaceKind = (typeof SURFACE_KINDS)[number];
1515
- /** The platform's own header for a session's token, which a World Host takes on
1516
- * every world whatever its vendor's auth; no vendor's client sends it. */
1517
- declare const PLATFORM_SESSION_HEADER = "X-World-Session";
1518
- declare const SESSION_AUTH_MODES: readonly ["vendor", "open"];
1519
- /** `open`: the session asks for no credential, reached on its capability
1520
- * hostname alone; `vendor`: the session's token, the way the world's `[auth]`
1521
- * says its vendor takes a key. Unset, the world's `[auth] mode`. */
1522
- type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];
1523
- declare function assertSessionAuthMode(value: unknown): asserts value is SessionAuthMode;
1524
- /** Capacity behind a World Host session's browser. `standard` runs on spot
1525
- * capacity first (about half the price) and may be reclaimed with two
1526
- * minutes' notice, ending the browser but never the world; `premium` is
1527
- * on-demand and never spot-reclaimed. Unset, the organization's default applies. */
1528
- declare const BROWSER_TIERS: readonly ["standard", "premium"];
1529
- type BrowserTier = (typeof BROWSER_TIERS)[number];
1530
- /** Refuse a tier the platform does not know, before any request is sent. */
1531
- declare function assertBrowserTier(value: unknown): asserts value is BrowserTier;
1532
- declare const DEFAULT_VIEWPORT: {
1533
- width: number;
1534
- height: number;
1535
- };
1536
- declare const EVENT_BATCH_SIZE = 10;
1537
- declare const EVENT_FLUSH_INTERVAL_MS = 1000;
1538
- declare const EVENT_MAX_RETRIES = 3;
1539
- declare const SECRET_KEY: RegExp;
1540
- /** What a call that lost its browser does once the browser is back: a read or
1541
- * a navigation runs again (`retry`); an action that may already have reached
1542
- * the world is not replayed, and the agent is told (`report`). */
1543
- type OnBrowserLoss = "retry" | "report";
1544
- /** The `surfaces` block of a session descriptor, as the platform sends it. */
1545
- type SessionSurfaces = {
1546
- tools: {
1547
- kind: "rendezvous";
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;
1548
1149
  };
1549
- api?: {
1550
- url: string;
1551
- /** Per-session credential of a World Host session: send it in the
1552
- * platform's `X-World-Session` header (`apiHeaders()`), or the way the
1553
- * world's `[auth]` says its vendor takes a key. Absent when the world
1554
- * itself answers with its declared auth (a pod or a customer-hosted twin),
1555
- * and for an open session, whose url is its secret. */
1556
- token?: string;
1557
- /** `open`: `url` is the session's capability hostname; send no credential. */
1558
- auth?: "open";
1150
+ response: WorldRequest["response"] & {
1151
+ body: string | null;
1559
1152
  };
1560
- ui?: {
1561
- url: string;
1562
- entry: string;
1563
- /** Same-origin prefix the UI proxies to the world API, e.g. `/__world-api`;
1564
- * null when the UI only reaches the API server-side. */
1565
- apiPath?: string | null;
1566
- /** Per-session credential of a World Host UI. A browser navigation cannot
1567
- * carry a header, so the first page load presents it once as `?token=`
1568
- * and the host answers with an HttpOnly cookie. Absent for pod UIs and
1569
- * open sessions. */
1570
- token?: string;
1571
- auth?: "open";
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 {
1166
+ }
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>;
1172
+ }
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>;
1199
+ }
1200
+
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;
1205
+ seq: number;
1206
+ at: string;
1207
+ durationMs: number | null;
1208
+ worldSlug: string;
1209
+ sessionId: string;
1210
+ versionId: string;
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;
1572
1220
  };
1573
- browser?: {
1574
- wsUrl: string;
1575
- /** `cdp`: the platform's Chromium relay (any number of agents share one
1576
- * browser, each in its own context). `playwright`: a `run-server` endpoint. */
1577
- protocol: "cdp" | "playwright";
1578
- viewport: {
1579
- width: number;
1580
- height: number;
1581
- };
1582
- /** The capacity tier the browser runs on; present for World Host sessions. */
1583
- tier?: BrowserTier;
1221
+ response: {
1222
+ status: number;
1223
+ bodyBytes: number | null;
1224
+ truncated: boolean;
1225
+ contentType: string | null;
1584
1226
  };
1227
+ rows: number | null;
1228
+ found: boolean | null;
1585
1229
  };
1586
- declare class WorldSurfaceUnavailable extends Error {
1587
- readonly surface: WorldSurfaceKind;
1588
- constructor(surface: WorldSurfaceKind, reason: string);
1589
- }
1590
- declare function surfaceKinds(s: SessionSurfaces): WorldSurfaceKind[];
1591
- /** The URL of `path` on a UI surface, carrying the session token when the
1592
- * surface has one. `path` may already have a query string; the token is
1593
- * appended to it. */
1594
- declare function uiUrl(ui: NonNullable<SessionSurfaces["ui"]>, path: string): string;
1595
- declare function uiEntryUrl(ui: NonNullable<SessionSurfaces["ui"]>): string;
1596
- /** `url` without its `token` query parameter: what may be logged or shown. */
1597
- declare function withoutUiToken(url: string): string;
1598
- /** The slice of a Playwright `Page` this module drives. */
1599
- type BrowserPage = {
1600
- url(): string;
1601
- goto(url: string, opts?: {
1602
- waitUntil?: "load";
1603
- }): Promise<unknown>;
1604
- click(selector: string): Promise<void>;
1605
- fill(selector: string, value: string): Promise<void>;
1606
- screenshot(opts?: {
1607
- type?: "png" | "jpeg";
1608
- quality?: number;
1609
- fullPage?: boolean;
1610
- }): Promise<Buffer>;
1611
- innerText(selector: string): Promise<string>;
1612
- content(): Promise<string>;
1613
- goBack(opts?: {
1614
- waitUntil?: "load";
1615
- }): Promise<unknown>;
1616
- waitForLoadState(state?: "load"): Promise<void>;
1617
- waitForTimeout(ms: number): Promise<void>;
1618
- on(event: "request" | "requestfinished" | "requestfailed", handler: (request: unknown) => void): unknown;
1619
- title(): Promise<string>;
1620
- keyboard: {
1621
- press(key: string): Promise<void>;
1622
- };
1623
- mouse: {
1624
- wheel(dx: number, dy: number): Promise<void>;
1625
- };
1626
- };
1627
- type BrowserMode = "auto" | "hosted" | "local";
1628
- /** One browser action as the platform ingests it
1629
- * (`POST /world-sessions/{id}/browser-events`). */
1630
- type BrowserActionEvent = {
1631
- agentId: string;
1632
- seq: number;
1633
- ts: string;
1634
- action: string;
1635
- args: Record<string, unknown>;
1636
- ok: boolean;
1637
- error: string | null;
1638
- durationMs: number;
1639
- url: string | null;
1640
- title: string | null;
1641
- mode: Exclude<BrowserMode, "auto">;
1642
- viewport: {
1643
- width: number;
1644
- height: number;
1645
- };
1646
- /** base64 JPEG of the screen after the action; null if it could not be taken. */
1647
- screenshot: string | null;
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;
1648
1240
  };
1649
- /** The secret label of an open session's capability hostname in `url`
1650
- * (`o-<sid>-<label>[-api].<domain>`), else null: a credential, scrubbed from
1651
- * everything a browser records. Twin of the Python `capability_label`. */
1652
- declare function capabilityLabel(url: string | null | undefined): string | null;
1653
- declare function redactActionArgs(action: string, args: Record<string, unknown>): Record<string, unknown>;
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;
1654
1249
  /**
1655
- * Ships browser action events to the platform, off the action's hot path.
1656
- *
1657
- * `post` receives a batch of events (the request body's `events`). Events
1658
- * are numbered here, so ordering survives batching and retries — the
1659
- * platform dedups on `(agentId, seq)`. A batch that keeps failing is dropped
1660
- * with a warning: telemetry must never stall or fail the agent.
1661
- *
1662
- * Numbering is durable across recorders: `nextSeq()` hands out a position
1663
- * within this recorder, and the first send adds the base `resumeFrom`
1664
- * reports — the platform's next free seq for this agent — so an agent id
1665
- * reopened in a later process appends to its timeline instead of colliding
1666
- * with (and being deduplicated against) what it already recorded. The base
1667
- * is fixed once resolved, which keeps retries idempotent.
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}`.
1668
1256
  */
1669
- declare class BrowserActionRecorder {
1670
- private readonly post;
1671
- readonly agentId: string;
1672
- private readonly opts;
1673
- private seq;
1674
- private base;
1675
- private queue;
1676
- private timer;
1677
- private inflight;
1678
- sent: number;
1679
- dropped: number;
1680
- constructor(post: (events: BrowserActionEvent[]) => Promise<void>, agentId: string, opts?: {
1681
- /** The platform's next free seq for `agentId`; 0 when not given. */
1682
- resumeFrom?: () => Promise<number>;
1683
- batchSize?: number;
1684
- flushIntervalMs?: number;
1685
- maxRetries?: number;
1686
- sleep?: (ms: number) => Promise<void>;
1687
- warn?: (message: string) => void;
1688
- });
1689
- /** This recorder's next position; the wire seq is `resumeFrom() + this`. */
1690
- nextSeq(): number;
1691
- private resolveBase;
1692
- record(event: BrowserActionEvent): void;
1693
- /** Resolve once everything recorded so far has been posted (or dropped). */
1694
- flush(): Promise<void>;
1695
- close(): Promise<void>;
1696
- private drain;
1697
- private send;
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[];
1698
1270
  }
1271
+
1699
1272
  /**
1700
- * One Playwright page on the session's UI. Thin on purpose — `page` is the
1701
- * real Playwright page for anything this wrapper does not cover.
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`.
1702
1277
  */
1703
- declare class WorldBrowser {
1704
- readonly ui: SessionSurfaces["ui"] | undefined;
1705
- readonly mode: Exclude<BrowserMode, "auto">;
1706
- private readonly teardown;
1707
- readonly viewport: {
1708
- width: number;
1709
- height: number;
1710
- };
1711
- readonly recorder: BrowserActionRecorder | null;
1712
- private readonly reconnector;
1713
- /** Takes session credentials out of every error this browser records. */
1714
- private readonly scrubber;
1715
- private current;
1716
- private inflight;
1717
- private lastNetwork;
1718
- /** Where the page last was after an action, token stripped: what a
1719
- * reconnect reopens. Null until the page has left `about:blank`. */
1720
- private lastUrl;
1721
- constructor(page: BrowserPage, ui: SessionSurfaces["ui"] | undefined, mode: Exclude<BrowserMode, "auto">, teardown: () => Promise<void>, viewport?: {
1722
- width: number;
1723
- height: number;
1724
- }, recorder?: BrowserActionRecorder | null, reconnector?: BrowserReconnector | null,
1725
- /** Takes session credentials out of every error this browser records. */
1726
- scrubber?: SecretScrubber);
1727
- /** The live Playwright page; a new object after a reconnect. */
1728
- get page(): BrowserPage;
1729
- get agentId(): string | null;
1730
- /** `text` with this session's credentials (UI token, browser address) removed. */
1731
- scrub(text: string): string;
1732
- private watchNetwork;
1733
- /** Run `fn` against the page. If it fails because the browser is gone,
1734
- * recover; then `retry` runs it ONCE more and `report` throws
1735
- * `BrowserReconnected` instead of replaying it. Any other error, and a
1736
- * second loss during the retry, propagate unchanged. */
1737
- private resilient;
1738
- private remember;
1739
- /** The page's URL less its token; null while it is blank. */
1740
- private openedUrl;
1741
- private recover;
1742
- /** Take over a new connection's page and reopen the page the agent was on
1743
- * (`openBrowser` owns the connection itself). A new browser has no session
1744
- * cookie, so a World Host UI is first loaded with its token, exactly as
1745
- * `goto()` loads the entry page. */
1746
- private adopt;
1747
- /** Run one action and report it: the event carries what was asked,
1748
- * whether it worked, and the screen after — for failures too, so a
1749
- * reviewer sees what the agent saw when the selector did not match. */
1750
- act<T>(action: string, args: Record<string, unknown>, fn: () => Promise<T>, onLoss?: OnBrowserLoss): Promise<T>;
1751
- /** One event on the recorder, if there is one; `failure` null means ok. */
1752
- private report;
1753
- private observeForEvent;
1754
- /** Open a UI path (`/customers`), a full URL, or — with no argument — the
1755
- * UI's declared entry page. */
1756
- goto(pathOrUrl?: string): Promise<string>;
1757
- back(): Promise<string>;
1758
- /** Wait for the page to finish reacting to an action. `load` alone is not
1759
- * enough for client-rendered UIs (React et al.): a click returns before the
1760
- * fetch that re-renders the page, so an agent would read stale text.
1761
- * Playwright's `networkidle` is per navigation and resolves at once after
1762
- * the first one, so this tracks requests itself: done when nothing is in
1763
- * flight and the network has been quiet for `SETTLE_QUIET_MS`, bounded so
1764
- * long-polling UIs cannot hang us. */
1765
- settle(): Promise<void>;
1766
- click(selector: string): Promise<void>;
1767
- type(selector: string, text: string): Promise<void>;
1768
- press(key: string): Promise<void>;
1769
- scroll(dy: number): Promise<void>;
1770
- screenshot(fullPage?: boolean): Promise<Buffer>;
1771
- screenshotBase64(fullPage?: boolean): Promise<string>;
1772
- text(selector?: string): Promise<string>;
1773
- html(): Promise<string>;
1774
- get url(): string;
1775
- title(): Promise<string>;
1776
- close(): Promise<void>;
1777
- }
1778
- /** The Playwright entry points this module needs, so tests can inject a fake. */
1779
- type PlaywrightLike = {
1780
- chromium: {
1781
- connect(wsEndpoint: string): Promise<PlaywrightBrowserLike>;
1782
- connectOverCDP(endpointURL: string): Promise<PlaywrightBrowserLike>;
1783
- launch(opts?: {
1784
- headless?: boolean;
1785
- }): Promise<PlaywrightBrowserLike>;
1786
- };
1278
+ declare const messageOf: (error: unknown) => string;
1279
+ type GradeResult = {
1280
+ reward: number | null;
1281
+ rewards: Record<string, number>;
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. */
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;
1787
1291
  };
1788
- type PlaywrightBrowserLike = {
1789
- newContext(opts?: {
1790
- viewport?: {
1791
- width: number;
1792
- height: number;
1793
- };
1794
- }): Promise<{
1795
- newPage(): Promise<BrowserPage>;
1796
- close(): Promise<void>;
1797
- }>;
1798
- close(): Promise<void>;
1292
+ type VerifierGrade = {
1293
+ reward: number | null;
1294
+ rewards: Record<string, number>;
1295
+ error?: string;
1296
+ };
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
+ }
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";
1351
+ /**
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:
1355
+ *
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
1359
+ *
1360
+ * A check's `id` names its entry in `rewards`; the task's reward is the
1361
+ * weighted share of checks that passed.
1362
+ */
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;
1373
+ };
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;
1401
+ };
1402
+ };
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[];
1449
+ };
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 = {
1513
+ seq: number;
1514
+ kind: string;
1515
+ tool: string | null;
1516
+ args: unknown;
1517
+ result: unknown;
1518
+ error: string | null;
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;
1566
+ };
1567
+ boundarySeq: number;
1568
+ boundaryAt: string;
1569
+ };
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
+
1579
+ /**
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.
1584
+ */
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 {
1595
+ }
1596
+ declare class WorldSessionCallError extends Error {
1597
+ }
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;
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;
1799
1837
  };
1800
- declare function resolveBrowserMode(surfaces: SessionSurfaces, mode: BrowserMode): Exclude<BrowserMode, "auto">;
1801
- /** Open a browser on the session's UI in `hosted`, `local` or `auto` mode. */
1802
- declare function openBrowser(surfaces: SessionSurfaces, opts?: {
1803
- mode?: BrowserMode;
1804
- headless?: boolean;
1805
- playwright?: PlaywrightLike;
1806
- recorder?: BrowserActionRecorder | null;
1807
- /** The session's repair call (`session.repairBrowser`). Given, a hosted
1808
- * `cdp` browser reconnects on its own when the browser is lost. */
1809
- repair?: () => Promise<RepairAnswer>;
1810
- }): Promise<WorldBrowser>;
1811
- declare const COMPUTER_USE_SPECS: readonly [{
1812
- readonly name: "browser_goto";
1813
- readonly signature: "browser_goto(path=None)";
1814
- 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.";
1815
- }, {
1816
- readonly name: "browser_click";
1817
- readonly signature: "browser_click(selector)";
1818
- readonly doc: "Click an element by Playwright selector (CSS, `text=Refund`, `role=button[name=Save]`). Returns the page text after the click.";
1819
- }, {
1820
- readonly name: "browser_type";
1821
- readonly signature: "browser_type(selector, text)";
1822
- readonly doc: "Replace the value of an input/textarea found by selector with `text`.";
1823
- }, {
1824
- readonly name: "browser_press";
1825
- readonly signature: "browser_press(key)";
1826
- readonly doc: "Press a key (Enter, Tab, Escape, ArrowDown, ...). Returns the page text after.";
1827
- }, {
1828
- readonly name: "browser_scroll";
1829
- readonly signature: "browser_scroll(dy=600)";
1830
- readonly doc: "Scroll the page vertically by `dy` pixels (negative scrolls up).";
1831
- }, {
1832
- readonly name: "browser_screenshot";
1833
- readonly signature: "browser_screenshot(full_page=False)";
1834
- readonly doc: "Take a PNG screenshot; returns {image_base64, url}.";
1835
- }, {
1836
- readonly name: "browser_read";
1837
- readonly signature: "browser_read(selector='body')";
1838
- readonly doc: "Return the visible text of an element (default: whole page) plus the URL and title.";
1839
- }, {
1840
- readonly name: "browser_back";
1841
- readonly signature: "browser_back()";
1842
- readonly doc: "Go back one page in history.";
1843
- }];
1844
1838
  /**
1845
- * The browser as model tools, in the same `WorldToolkit` shape the world's
1846
- * own tools come in — so an agent loop that already dispatches
1847
- * `toolkit().impls` merges `computerUseToolkit(b).impls` and gains a screen
1848
- * without a second dispatch path.
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
1849
  */
1850
- declare function computerUseToolkit(browser: WorldBrowser, opts?: {
1851
- maxText?: number;
1852
- }): WorldToolkit;
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;
1873
+ };
1874
+ /**
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.
1896
+ */
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>;
1853
1921
 
1854
1922
  /** Mirrors `WorldSessionListItemSchema` (web/features/public-api/types/world-sessions.ts). */
1855
1923
  type WorldSessionListItem = {
@@ -2213,6 +2281,8 @@ type OpenTaskOptions = {
2213
2281
  /** Browser capacity for every world the task opens: `standard` (spot, may
2214
2282
  * be reclaimed) or `premium` (on-demand). Unset, the organization's default. */
2215
2283
  browserTier?: BrowserTier;
2284
+ /** A world state per alias: that world's session opens on it. */
2285
+ worldStates?: Record<string, string>;
2216
2286
  options?: WorldsClientOptions;
2217
2287
  };
2218
2288
  /**
@@ -2273,6 +2343,7 @@ declare class GatewayEvalsClient {
2273
2343
  private readonly retry;
2274
2344
  private readonly keyed;
2275
2345
  constructor(options?: WorldsClientOptions, retry?: RetryPolicy);
2346
+ static refuseToken(options: WorldsClientOptions): void;
2276
2347
  createEvaluation(versionId: string, opts?: CreateEvaluationOptions): Promise<string>;
2277
2348
  pushSamples(evaluationId: string, samples: EvalSample[]): Promise<number>;
2278
2349
  finalizeEvaluation(evaluationId: string, opts?: FinalizeEvaluationOptions): Promise<string>;
@@ -2346,6 +2417,8 @@ type RunTaskOptions = {
2346
2417
  keepUp?: boolean;
2347
2418
  reuseWarm?: boolean;
2348
2419
  browserTier?: BrowserTier;
2420
+ /** A world state per alias: that world's session opens on it. */
2421
+ worldStates?: Record<string, string>;
2349
2422
  /** File the rollout under this set run (`runSet` sets it). */
2350
2423
  setRunId?: string;
2351
2424
  options?: WorldsClientOptions;
@@ -2616,66 +2689,273 @@ type RunSetResult = {
2616
2689
  /** A low or missing reward is a result, not a failure; every task runs even after one fails. */
2617
2690
  declare function runSet(datasetId: string, agent: (run: TaskRun) => TaskRunResult | Promise<TaskRunResult>, opts: RunSetOptions): Promise<RunSetResult>;
2618
2691
 
2619
- declare const WORLD_REQUEST_VIAS: readonly ["api", "ui", "tool"];
2620
- /** 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. */
2621
- type WorldRequestEntry = Omit<WorldRequest, "request" | "response"> & {
2622
- request: WorldRequest["request"] & {
2623
- headers: Record<string, string>;
2624
- body: string | null;
2625
- };
2626
- response: WorldRequest["response"] & {
2627
- body: string | null;
2628
- };
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>;
2629
2785
  };
2630
- type WorldRequestFilter = {
2631
- session?: string;
2632
- version?: string;
2633
- via?: string;
2634
- operation?: string;
2635
- status?: string;
2636
- since?: string;
2637
- until?: string;
2638
- cursor?: string;
2639
- limit?: number;
2786
+ type PageObservation = {
2787
+ url: string;
2788
+ title: string;
2789
+ snapshot: string;
2790
+ truncated: boolean;
2640
2791
  };
2641
- declare class WorldRequestFilterError extends Error {
2642
- }
2643
- /** The platform's 409 `requests_not_recorded`: the session's engine keeps no request ledger, only World Host
2644
- * sessions record requests. Its message is the platform's own sentence. */
2645
- declare class WorldRequestsNotRecorded extends Error {
2646
- static from(error: unknown): unknown;
2647
- static mapped<T>(read: Promise<T>): Promise<T>;
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;
2648
2833
  }
2649
- /** The filters of a request-ledger read, checked and put in the platform's form: `via` and `status` lower-cased,
2650
- * `since`/`until` as UTC instants (a date alone is its midnight, a time without a zone is UTC). Twin of
2651
- * `gatewaysdk.world_requests.WorldRequestQuery`; both run `conformance/world-request-cli.json`. */
2652
- declare class WorldRequestQuery {
2653
- private readonly entries;
2654
- private constructor();
2655
- static parse(filter?: WorldRequestFilter): WorldRequestQuery;
2656
- private static via;
2657
- private static status;
2658
- get filtered(): boolean;
2659
- params(): [string, string][];
2660
- search(): string;
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;
2661
2871
  }
2662
- /** A world's request ledger: every request the world received, from every session and version, through every
2663
- * door (`via`: api, ui, tool), kept for the world's life. Reading it records nothing. Twin of
2664
- * `gatewaysdk.world_requests.WorldRequestLedger`. */
2665
- declare class WorldRequestLedger {
2872
+
2873
+ declare const WORLD_WEBHOOK_PAGE_MAX = 100;
2874
+ type WorldWebhookSubscription = {
2875
+ key: Record<string, unknown>;
2876
+ url: string | null;
2877
+ events: string[];
2878
+ scope: Record<string, string[]>;
2879
+ enabled: boolean;
2880
+ /** Deliveries this subscription was sent since the session's feed began. */
2881
+ sent: number;
2882
+ };
2883
+ type WorldWebhookDelivery = {
2884
+ seq: number;
2885
+ id: string;
2886
+ eventId: string;
2887
+ eventType: string;
2888
+ subscription: Record<string, unknown>;
2889
+ url: string;
2890
+ headers: Record<string, string>;
2891
+ payload: string;
2892
+ at: number;
2893
+ };
2894
+ type WorldWebhookPage = {
2895
+ declared: boolean;
2896
+ subscriptions: WorldWebhookSubscription[];
2897
+ truncated: boolean;
2898
+ epoch: string;
2899
+ reset: boolean;
2900
+ deliveries: WorldWebhookDelivery[];
2901
+ next: number;
2902
+ more: boolean;
2903
+ missed: number;
2904
+ answered: number;
2905
+ };
2906
+ /** A page as the read key sees it: which event went to which subscription and when. */
2907
+ type WorldWebhookListing = Omit<WorldWebhookPage, "deliveries"> & {
2908
+ deliveries: Pick<WorldWebhookDelivery, "seq" | "id" | "eventType" | "subscription" | "at">[];
2909
+ };
2910
+ type WorldWebhookAnswer = {
2911
+ id: string;
2912
+ status: number;
2913
+ durationMs: number;
2914
+ error: string | null;
2915
+ };
2916
+ type ForwardedDelivery = {
2917
+ delivery: WorldWebhookDelivery;
2918
+ answer: WorldWebhookAnswer;
2919
+ };
2920
+ /** The webhooks a World Host session's world declares and has sent, without their signed headers. */
2921
+ declare function listWebhooks(options: WorldsClientOptions, sessionId: string, page?: {
2922
+ after?: number;
2923
+ limit?: number;
2924
+ epoch?: string;
2925
+ tail?: boolean;
2926
+ }): Promise<WorldWebhookListing>;
2927
+ /**
2928
+ * The forward lane: polls a session's deliveries (secret key), replays each to `forwardTo` exactly as signed,
2929
+ * so a receiver on this machine verifies it as it would the vendor's, and hands each receiver's answer back
2930
+ * on the next poll, where the world's request ledger keeps it beside the delivery.
2931
+ */
2932
+ declare class WorldWebhookForwarder {
2666
2933
  private readonly options;
2667
- constructor(options?: WorldsClientOptions);
2668
- /** A page of the world's requests, newest first; `nextCursor` reads the page after it. Narrowed to a session
2669
- * whose engine records none: `WorldRequestsNotRecorded`. */
2670
- list(slug: string, query?: WorldRequestQuery): Promise<WorldRequestPage>;
2671
- /** One of the world's requests, with its headers and bodies. */
2672
- get(slug: string, requestId: string): Promise<WorldRequestEntry>;
2673
- /** A page of one session's requests, newest first; `WorldRequestsNotRecorded` when its engine records none. */
2674
- forSession(sessionId: string, query?: WorldRequestQuery): Promise<WorldRequestPage>;
2934
+ private readonly sessionId;
2935
+ private readonly forwardTo;
2936
+ private after;
2937
+ private epoch;
2938
+ private answers;
2939
+ private readonly send;
2940
+ constructor(options: WorldsClientOptions, sessionId: string, forwardTo: string, opts?: {
2941
+ fetch?: typeof fetch;
2942
+ });
2943
+ get cursor(): number;
2944
+ /** Where forwarding begins: the deliveries the session still holds (`replay`), or only those it sends from now. */
2945
+ start(replay: boolean): Promise<WorldWebhookPage | null>;
2946
+ /** One poll: the answers held so far sent, the next page forwarded. A poll that fails keeps its answers for the next. */
2947
+ round(): Promise<{
2948
+ page: WorldWebhookPage;
2949
+ forwarded: ForwardedDelivery[];
2950
+ }>;
2951
+ /** Sends the answers still held; the cursor stays, so a delivery this poll returns is forwarded by the next round. */
2952
+ settle(): Promise<number>;
2953
+ private follow;
2954
+ private withAnswers;
2955
+ private poll;
2956
+ private forward;
2675
2957
  }
2676
2958
 
2677
- /** One entry the archive rules dropped: a whole directory (`name/`, `files`
2678
- * counted) or a single file. */
2679
2959
  type Exclusion = {
2680
2960
  path: string;
2681
2961
  files: number;
@@ -2792,11 +3072,10 @@ declare function push(dir: string, opts?: {
2792
3072
  * instead of 409ing against it. */
2793
3073
  baseVersionId?: string | null;
2794
3074
  /** Container metadata recorded on resolve — the Python CLI's --name,
2795
- * --description, --tag and --visibility. */
3075
+ * --description and --tag. */
2796
3076
  name?: string;
2797
3077
  description?: string;
2798
3078
  tags?: string[];
2799
- visibility?: string;
2800
3079
  /** Pre-built OCI image ref for image/agentic envs (recorded on the version). */
2801
3080
  imageRef?: string;
2802
3081
  options?: WorldsClientOptions;
@@ -2985,16 +3264,6 @@ declare function storedForms(world: {
2985
3264
  redact?: RedactPolicy | null;
2986
3265
  }, field: string, plaintext: Plaintext, transform?: readonly string[]): Plaintext[];
2987
3266
 
2988
- /**
2989
- * `describeWorld(slug)` — what a world holds and how each field is stored,
2990
- * from `GET /api/public/worlds/{slug}`: the entities (primary key, unique
2991
- * keys, relationships, row count, fields with their `[redact]` policy) and
2992
- * the `[redact]` table itself, so `storedForms(world, field, plaintext)`
2993
- * can compute a lookup value without Python. The CLI twin is
2994
- * `gateway worlds describe <slug>`; for a directory the CLI asks the schema
2995
- * runtime instead and merges the same shape.
2996
- */
2997
-
2998
3267
  type WorldField = {
2999
3268
  name: string;
3000
3269
  type: string | null;
@@ -3027,6 +3296,12 @@ type WorldDependency = {
3027
3296
  tools: string[];
3028
3297
  entities: WorldEntityMapping[];
3029
3298
  };
3299
+ type WorldBundleMember = {
3300
+ alias: string;
3301
+ pin: string;
3302
+ slug: string | null;
3303
+ versionId: string;
3304
+ };
3030
3305
  type WorldEntity = {
3031
3306
  name: string;
3032
3307
  primaryKey: string[];
@@ -3061,6 +3336,7 @@ type WorldDescription = {
3061
3336
  /** World-to-world links from `[dependencies]`, resolved at commit, with the
3062
3337
  * entity mappings `--across` follows. */
3063
3338
  dependencies?: WorldDependency[];
3339
+ members?: WorldBundleMember[];
3064
3340
  entities: WorldEntity[];
3065
3341
  redact: RedactPolicy | null;
3066
3342
  };
@@ -3570,7 +3846,7 @@ declare function sessionToolObservations(sessionId: string, options?: WorldsClie
3570
3846
  * The CLI sandbox: a server-side workspace opened on a READY version of a
3571
3847
  * world (`/workspace/env` in the console agent's sandbox) — or, with
3572
3848
  * `{ new, from }`, on a world that does not exist yet, seeded from the
3573
- * `schema init` scaffold or a shipped template and created by its first
3849
+ * `schema init` scaffold or an official template and created by its first
3574
3850
  * commit — edited and run there, and committed straight into the version
3575
3851
  * service; the source never lands on the caller's disk. `importData` is the
3576
3852
  * data door beside `commit`: a rows file in the sandbox tree into the platform
@@ -3810,7 +4086,7 @@ declare class WorldSandboxClient {
3810
4086
  /**
3811
4087
  * `{ slug, ref? }` opens a READY version; `{ new, from }` opens a sandbox on
3812
4088
  * a world that does not exist yet (409 `world_exists` if the slug is taken,
3813
- * 400 naming the shipped templates if `from` is unknown). Its first commit
4089
+ * 400 naming the official templates if `from` is unknown). Its first commit
3814
4090
  * creates the world on `main`.
3815
4091
  */
3816
4092
  open(target: SandboxOpenTarget): Promise<SandboxOpened>;
@@ -3853,6 +4129,81 @@ declare class WorldSandboxClient {
3853
4129
  }): Promise<SandboxSummary>;
3854
4130
  }
3855
4131
 
4132
+ type WorldStateDoc = {
4133
+ id: string;
4134
+ name: string;
4135
+ kind: string;
4136
+ description: string | null;
4137
+ bindings: Record<string, string>;
4138
+ dataSnapshotId: string | null;
4139
+ createdBy: string | null;
4140
+ updatedBy: string | null;
4141
+ createdAt: string;
4142
+ updatedAt: string;
4143
+ };
4144
+ type WorldStateSnapshot = {
4145
+ id: string;
4146
+ sha256: string;
4147
+ digest: string;
4148
+ contractHash: string;
4149
+ bytes: number;
4150
+ rowCounts: Record<string, number>;
4151
+ };
4152
+ type WorldStateOpening = {
4153
+ versionId: string;
4154
+ source: "version" | "state" | "carried";
4155
+ snapshot: WorldStateSnapshot | null;
4156
+ bindings: Record<string, string>;
4157
+ fingerprint: string;
4158
+ };
4159
+ type WorldStateRefusal = {
4160
+ code: string;
4161
+ message: string;
4162
+ };
4163
+ type WorldStateList = {
4164
+ slug: string;
4165
+ containerId: string;
4166
+ states: WorldStateDoc[];
4167
+ };
4168
+ type WorldStateAnswer = {
4169
+ slug: string;
4170
+ state: WorldStateDoc;
4171
+ versionId: string | null;
4172
+ opens: WorldStateOpening | null;
4173
+ refusal: WorldStateRefusal | null;
4174
+ };
4175
+ type WorldStateDeleted = {
4176
+ slug: string;
4177
+ state: WorldStateDoc;
4178
+ deleted: true;
4179
+ runCount: number;
4180
+ };
4181
+ type WorldStatePull = {
4182
+ slug: string;
4183
+ state: WorldStateDoc;
4184
+ opens: WorldStateOpening;
4185
+ download: {
4186
+ url: string;
4187
+ expiresAt: string;
4188
+ } | null;
4189
+ };
4190
+ type WorldStateCreateInput = {
4191
+ name: string;
4192
+ description?: string;
4193
+ bindings?: Record<string, string>;
4194
+ fromSnapshot?: string;
4195
+ fromState?: string;
4196
+ };
4197
+ declare class WorldStateClient {
4198
+ private readonly options;
4199
+ constructor(options?: WorldsClientOptions);
4200
+ list(slug: string): Promise<WorldStateList>;
4201
+ show(slug: string, name: string, ref?: string): Promise<WorldStateAnswer>;
4202
+ create(slug: string, input: WorldStateCreateInput): Promise<WorldStateAnswer>;
4203
+ delete(slug: string, name: string): Promise<WorldStateDeleted>;
4204
+ pull(slug: string, name: string, ref?: string): Promise<WorldStatePull>;
4205
+ }
4206
+
3856
4207
  /**
3857
4208
  * The hosted one-task dry run: `POST /api/public/environments/{id}/dry-run`
3858
4209
  * and the run-status read that settles it. The runner runs ONE named task of a
@@ -3979,6 +4330,7 @@ type WorldsClientOptions = {
3979
4330
  host?: string;
3980
4331
  publicKey?: string;
3981
4332
  secretKey?: string;
4333
+ token?: PersonalToken;
3982
4334
  };
3983
4335
  type ResolvedWorldVersion = {
3984
4336
  versionId: string;
@@ -3996,21 +4348,6 @@ type DispatchedRun = {
3996
4348
  ok: boolean;
3997
4349
  error?: string;
3998
4350
  };
3999
- /** A non-2xx platform answer: act on `status` or the stable public `code` (never the server's error class) rather than parsing the message. */
4000
- declare class ApiError extends Error {
4001
- readonly status: number;
4002
- readonly text: string;
4003
- readonly code: string | null;
4004
- constructor(status: number, method: string, path: string, text: string);
4005
- }
4006
- /** The detail and stable code of a non-2xx body; an HTML page or a bare 5xx is named, never printed.
4007
- * Python twin: `gatewaysdk.api_errors.error_detail`; both run `conformance/platform-error-bodies.json`. */
4008
- declare function parseErrorBody(text: string, status?: number): {
4009
- detail: string;
4010
- code: string | null;
4011
- };
4012
- /** `<path>: <message>` per issue of a validation error; empty when it carries none. Python twin: `gatewaysdk.api_errors.invalid_fields`. */
4013
- declare function invalidFields(error: unknown): string;
4014
4351
  /** Authenticated JSON request to the platform API. `init.timeoutMs` replaces the `GATEWAY_TIMEOUT_MS` budget for a request that
4015
4352
  * legitimately outlasts it; `init.retry` is only for a request whose repeat is harmless. */
4016
4353
  declare function apiRequest<T>(options: WorldsClientOptions, method: PlatformMethod, path: string, body?: unknown, init?: {
@@ -4171,4 +4508,4 @@ declare function openWorld(slugRef: string, options?: WorldsClientOptions): Prom
4171
4508
  /** 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. */
4172
4509
  declare function openWorldVersion(slug: string, versionId: string, options?: WorldsClientOptions): Promise<WorldSet>;
4173
4510
 
4174
- export { ACTION_NAMES, type ActingUser, type ActionArgs, type ActionResult, ActionTracer, type AiSdkAnthropicOutput, type AiSdkComputerCall, type AiSdkComputerOutput, type AiSdkModelOutput, 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, 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, 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 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, 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 };
4511
+ 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 };