@withgateway/sdk 0.2.6 → 0.2.9

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 (110) hide show
  1. package/README.md +24 -8
  2. package/dist/cli.js +15468 -11263
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +15233 -11028
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +291 -40
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +284 -37
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +203 -47
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +198 -42
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-BaKu5ZSU.d.mts → index-C3UzD0G3.d.mts} +75 -1
  19. package/dist/{index-BaKu5ZSU.d.ts → index-C3UzD0G3.d.ts} +75 -1
  20. package/dist/{index-CLkMr6VG.d.ts → index-D-_4Ibcn.d.ts} +36 -4
  21. package/dist/{index-CdbmO4aX.d.mts → index-FfK4Nump.d.mts} +36 -4
  22. package/dist/index.d.mts +3 -3
  23. package/dist/index.d.ts +3 -3
  24. package/dist/index.js +2149 -615
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2053 -566
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/traces/index.js +268 -31
  29. package/dist/traces/index.js.map +1 -1
  30. package/dist/traces/index.mjs +262 -28
  31. package/dist/traces/index.mjs.map +1 -1
  32. package/dist/tracing/index.js +19 -11
  33. package/dist/tracing/index.js.map +1 -1
  34. package/dist/tracing/index.mjs +19 -11
  35. package/dist/tracing/index.mjs.map +1 -1
  36. package/dist/worlds/index.d.mts +886 -117
  37. package/dist/worlds/index.d.ts +886 -117
  38. package/dist/worlds/index.js +1770 -452
  39. package/dist/worlds/index.js.map +1 -1
  40. package/dist/worlds/index.mjs +1752 -434
  41. package/dist/worlds/index.mjs.map +1 -1
  42. package/package.json +14 -10
  43. package/runtime/gatewaysdk/environment/_toml.py +3 -10
  44. package/runtime/gatewaysdk/environment/_world.py +95 -28
  45. package/runtime/gatewaysdk/environment/runtime.py +10 -6
  46. package/runtime/gatewaysdk/environment/schema/__main__.py +35 -0
  47. package/runtime/gatewaysdk/environment/schema/api.py +19 -23
  48. package/runtime/gatewaysdk/environment/schema/batch.py +68 -14
  49. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +4 -2
  50. package/runtime/gatewaysdk/environment/schema/cast.py +264 -0
  51. package/runtime/gatewaysdk/environment/schema/compiler.py +35 -1
  52. package/runtime/gatewaysdk/environment/schema/conform.py +28 -10
  53. package/runtime/gatewaysdk/environment/schema/connector.py +59 -14
  54. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +38 -1
  55. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +3 -1
  56. package/runtime/gatewaysdk/environment/schema/credentials.py +20 -0
  57. package/runtime/gatewaysdk/environment/schema/csv_rows.py +117 -0
  58. package/runtime/gatewaysdk/environment/schema/cycles.py +121 -0
  59. package/runtime/gatewaysdk/environment/schema/data.py +21 -5
  60. package/runtime/gatewaysdk/environment/schema/grading.py +95 -13
  61. package/runtime/gatewaysdk/environment/schema/handler_errors.py +44 -0
  62. package/runtime/gatewaysdk/environment/schema/handler_scan.py +175 -0
  63. package/runtime/gatewaysdk/environment/schema/host.py +68 -115
  64. package/runtime/gatewaysdk/environment/schema/host_requests.py +78 -0
  65. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +12 -0
  66. package/runtime/gatewaysdk/environment/schema/ingest.py +5 -18
  67. package/runtime/gatewaysdk/environment/schema/local.py +7 -10
  68. package/runtime/gatewaysdk/environment/schema/openapi_document.py +322 -0
  69. package/runtime/gatewaysdk/environment/schema/openapi_import.py +382 -0
  70. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +441 -0
  71. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +629 -0
  72. package/runtime/gatewaysdk/environment/schema/openapi_source.py +210 -0
  73. package/runtime/gatewaysdk/environment/schema/platform.py +110 -299
  74. package/runtime/gatewaysdk/environment/schema/platform_import.py +182 -0
  75. package/runtime/gatewaysdk/environment/schema/platform_query.py +95 -0
  76. package/runtime/gatewaysdk/environment/schema/route_bindings.py +176 -0
  77. package/runtime/gatewaysdk/environment/schema/runtime.py +56 -7
  78. package/runtime/gatewaysdk/environment/schema/scaffold.py +64 -5
  79. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +70 -22
  80. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +54 -4
  81. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +27 -2
  82. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +62 -0
  83. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +91 -54
  84. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +146 -146
  85. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  86. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +30 -0
  87. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  88. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +90 -0
  89. package/runtime/gatewaysdk/environment/schema/store.py +15 -6
  90. package/runtime/gatewaysdk/environment/schema/store_contract.py +119 -0
  91. package/runtime/gatewaysdk/environment/schema/tasks.py +121 -32
  92. package/runtime/gatewaysdk/environment/schema/tools_world.py +32 -10
  93. package/runtime/gatewaysdk/environment/schema/tree_import.py +228 -0
  94. package/runtime/gatewaysdk/environment/schema/ui.py +18 -2
  95. package/runtime/gatewaysdk/environment/schema/validation.py +35 -0
  96. package/runtime/gatewaysdk/environment/schema/verbs.py +8 -2
  97. package/runtime/gatewaysdk/environment/world.py +42 -3
  98. package/runtime/gatewaysdk/environment/world_session_contract.py +57 -0
  99. package/skills/benchmarks-getting-started/SKILL.md +70 -22
  100. package/skills/connector-schema-authoring/SKILL.md +54 -4
  101. package/skills/connector-schema-authoring/connector-worlds.md +21 -7
  102. package/skills/connector-schema-authoring/world-schema.md +144 -83
  103. package/skills/hooks-getting-started/SKILL.md +27 -2
  104. package/skills/world-data-ingestion/ROWS.md +62 -0
  105. package/skills/world-data-ingestion/SKILL.md +91 -54
  106. package/skills/worlds-getting-started/SKILL.md +146 -146
  107. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  108. package/skills/worlds-getting-started/references/gotchas.md +30 -0
  109. package/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  110. package/skills/worlds-getting-started/references/openapi-import.md +90 -0
@@ -1,3 +1,95 @@
1
+ /**
2
+ * A HOSTED BROWSER THAT COMES BACK. A World Host session's browser is a pool
3
+ * pod; on the `standard` tier it runs on spot capacity and can be reclaimed
4
+ * with two minutes' notice. The browser dies, the world does not, and the
5
+ * platform can put a new browser behind the SAME `surfaces.browser.wsUrl`.
6
+ *
7
+ * `BrowserReconnector` is the client half of that repair: on a lost
8
+ * connection it asks the platform to repair (`POST .../browser-repair`),
9
+ * waits while a browser starts, reconnects to the same address and hands the
10
+ * new connection to its owner to restore the page. It knows nothing of HTTP
11
+ * or Playwright — both come in as collaborators, so tests drive it with
12
+ * fakes. Twin of `gatewaysdk/world_browser_reconnect.py`, call for call.
13
+ */
14
+ /** What the platform answers a repair with. `healthy`: the browser is alive,
15
+ * reconnect now. `replaced`: a new, blank browser; reconnect and reopen the
16
+ * page. `starting`: a browser is coming up; ask again in `retryAfterMs`. */
17
+ type RepairAnswer = {
18
+ outcome: "healthy" | "replaced" | "starting";
19
+ retryAfterMs: number | null;
20
+ };
21
+ type BrowserContextLike = Awaited<ReturnType<PlaywrightBrowserLike["newContext"]>>;
22
+ /** One live attachment to the session's browser. */
23
+ type BrowserConnection = {
24
+ browser: PlaywrightBrowserLike;
25
+ context: BrowserContextLike;
26
+ page: BrowserPage;
27
+ };
28
+ declare function closeConnection(c: BrowserConnection): Promise<void>;
29
+ /** Close a connection whose browser is already gone: it only frees the
30
+ * handle, so a failure is ignored. */
31
+ declare function releaseConnection(c: BrowserConnection): Promise<void>;
32
+ declare const RECOVER_BUDGET_MS = 90000;
33
+ /** What Playwright says when the browser or its connection is gone, as
34
+ * opposed to an action that failed on a live page. Matched case-insensitively
35
+ * against the error message; nothing else triggers a reconnect. */
36
+ declare const BROWSER_GONE_PATTERNS: readonly RegExp[];
37
+ declare function isBrowserGone(error: unknown): boolean;
38
+ /**
39
+ * Takes a session's credentials out of text that leaves the process — an
40
+ * error recorded into the browser timeline, a recovery's reason. A browser
41
+ * error quotes the URL it failed on, and those URLs carry the session: the
42
+ * hosted browser's `wsUrl` (its path is the credential), the UI's token, and
43
+ * any `?token=` a landing URL presents. Each becomes `<redacted>`.
44
+ */
45
+ declare class SecretScrubber {
46
+ private readonly secrets;
47
+ constructor(secrets: readonly (string | null | undefined)[]);
48
+ scrub(text: string): string;
49
+ }
50
+ /** A mutating action (click, type, press, back, scroll) lost its browser.
51
+ * The browser was repaired and the page reopened at `restoredUrl`, but the
52
+ * action is NOT replayed: its input may already have reached the world.
53
+ * `cause` is the error the action failed with. */
54
+ declare class BrowserReconnected extends Error {
55
+ readonly outcome: RecoveryResult["outcome"];
56
+ readonly restoredUrl: string | null;
57
+ constructor(outcome: RecoveryResult["outcome"], restoredUrl: string | null, cause: unknown);
58
+ }
59
+ /** The session's browser stayed gone for the whole budget. `cause` is the
60
+ * error the action first failed with. */
61
+ declare class BrowserUnrecoverable extends Error {
62
+ constructor(message: string, cause: unknown);
63
+ }
64
+ type RecoveryResult = {
65
+ outcome: "healthy" | "replaced";
66
+ attempts: number;
67
+ };
68
+ declare class BrowserReconnector {
69
+ private readonly repair;
70
+ private readonly connect;
71
+ private readonly sleep;
72
+ private readonly now;
73
+ private readonly scrub;
74
+ readonly budgetMs: number;
75
+ constructor(repair: () => Promise<RepairAnswer>, connect: () => Promise<BrowserConnection>, opts?: {
76
+ sleep?: (ms: number) => Promise<void>;
77
+ now?: () => number;
78
+ budgetMs?: number;
79
+ /** Takes credentials out of a reason before it is thrown. */
80
+ scrub?: (text: string) => string;
81
+ });
82
+ /**
83
+ * Repair, reconnect and `restore` until it works or the budget runs out.
84
+ * `restore` receives each new connection (the owner adopts it and reopens
85
+ * its page); a restore that fails counts as a failed reconnect, because the
86
+ * browser may have died again. A repair the platform refuses for good
87
+ * rethrows `cause` untouched.
88
+ */
89
+ recover(cause: unknown, restore: (connection: BrowserConnection) => Promise<void>): Promise<RecoveryResult>;
90
+ private attempt;
91
+ }
92
+
1
93
  /**
2
94
  * STORED WORLD TASKS: a task spec kept by the project, outside any bundle.
3
95
  *
@@ -27,6 +119,13 @@ type WorldTaskSummary = {
27
119
  version: number;
28
120
  hash: string;
29
121
  spec: WorldTaskSpec;
122
+ /** A multi-world task's aliases in spec order; empty for a single world. */
123
+ aliases: string[];
124
+ /** Listed by world: the aliases that world plays in this task; else empty. */
125
+ aliasesHere: string[];
126
+ /** What grades the task, one row per check or verifier: its reward key,
127
+ * the aliases it judges, what it checks in plain words, its source. */
128
+ verifiers: WorldTaskVerifierRow[];
30
129
  createdAt: string;
31
130
  updatedAt: string;
32
131
  createdBy: string;
@@ -46,6 +145,14 @@ type WorldTaskVersionSummary = {
46
145
  createdBy: string;
47
146
  message: string | null;
48
147
  };
148
+ type WorldTaskVerifierRow = {
149
+ key: string;
150
+ aliases: string[];
151
+ kind: "assertions" | "python" | "rubric";
152
+ description: string | null;
153
+ source: string | null;
154
+ sourceLanguage: "python" | "text" | null;
155
+ };
49
156
  type WorldTaskDetail = WorldTaskSummary & {
50
157
  versions: WorldTaskVersionSummary[];
51
158
  };
@@ -56,6 +163,9 @@ type WorldTaskPage = {
56
163
  limit: number;
57
164
  totalItems: number;
58
165
  totalPages: number;
166
+ /** Listed by world: the scan for multi-world tasks naming it filled its
167
+ * bound, so `totalItems` is a floor. */
168
+ scanTruncated?: true;
59
169
  };
60
170
  };
61
171
  type WorldTaskWorldValidation = {
@@ -101,7 +211,7 @@ declare function updateTask(taskId: string, input: {
101
211
  message?: string;
102
212
  }, options?: WorldsClientOptions): Promise<WorldTaskSummary>;
103
213
  /** The project's tasks, newest change first. `world` keeps only tasks
104
- * pinned to that slug; `metadata` keeps tasks whose spec metadata carries
214
+ * that run against that slug (pinned to it, or naming it under an alias); `metadata` keeps tasks whose spec metadata carries
105
215
  * every given key/value (`{ externalUserId: "u_42" }`). */
106
216
  declare function listTasks(filter?: {
107
217
  world?: string;
@@ -130,6 +240,21 @@ declare function validateTask(taskId: string, target?: {
130
240
  versionId?: string;
131
241
  }, options?: WorldsClientOptions): Promise<WorldTaskValidation>;
132
242
 
243
+ /**
244
+ * The three shapes a task reaches `openSession` in — a bundled scenario's
245
+ * name, a stored task's `{ id, version? }`, an inline spec — and how each is
246
+ * told apart, labelled and checked. No task at all (`undefined`) is the
247
+ * fourth case, an exploratory session, and is not a ref.
248
+ */
249
+ declare const isTaskIdRef: (task: WorldTaskRef) => task is WorldTaskIdRef;
250
+ declare const isTaskSpec: (task: WorldTaskRef) => task is WorldTaskSpec;
251
+ /** The label a task goes by in results: its name, `inline:<hash>` for an
252
+ * unnamed inline task once the platform has hashed it, or the stored task's
253
+ * name (its id until the platform has answered). */
254
+ declare const taskLabel: (task: WorldTaskRef, info?: WorldSessionTask | null) => string;
255
+ /** A task given to `openSession` must be one of the three shapes. */
256
+ declare const assertTaskRef: (task: WorldTaskRef) => void;
257
+
133
258
  /**
134
259
  * LIVE WORLD SESSIONS from TypeScript: your agent, the platform's container.
135
260
  *
@@ -293,7 +418,25 @@ type WorldTaskSpec = {
293
418
  grader?: WorldTaskGrader;
294
419
  tools?: string[];
295
420
  }>;
296
- };
421
+ /** CROSS-WORLD VERIFIERS: deterministic graders over several of the task's
422
+ * worlds at once, each with a `scope` of aliases (two or more). One runs on
423
+ * the session of the first alias in its scope, over a state where every
424
+ * scoped world's rows are `<alias>.<entity>` and its calls `<alias>.calls`;
425
+ * the platform gathers the other worlds' evidence when `grade()` names
426
+ * them (`TaskSessions.grade` does). Rewards come back as `x.<name>`. */
427
+ verifiers?: WorldTaskVerifier[];
428
+ };
429
+ type WorldTaskVerifier = {
430
+ name: string;
431
+ scope: string[];
432
+ } & ({
433
+ kind: "assertions";
434
+ checks: WorldTaskCheck[];
435
+ } | {
436
+ kind: "python";
437
+ source: string;
438
+ timeoutSeconds?: number;
439
+ });
297
440
  /** A stored task of the project (see worlds/tasks.ts), opened by id; the
298
441
  * session runs a copy of one version's spec — the current one by default. */
299
442
  type WorldTaskIdRef = {
@@ -307,19 +450,14 @@ type WorldTaskRef = string | WorldTaskIdRef | WorldTaskSpec;
307
450
  * content hash of the spec (inline or stored) — what warm reuse matches on;
308
451
  * `id`/`version` name the stored task the session was opened on. */
309
452
  type WorldSessionTask = {
310
- source: "bundled" | "inline" | "stored";
453
+ /** `none` is an exploratory session: opened with no task, no grader. */
454
+ source: "bundled" | "inline" | "stored" | "none";
311
455
  name: string | null;
312
456
  hash: string | null;
313
457
  id?: string | null;
314
458
  version?: number | null;
315
459
  metadata: Record<string, unknown>;
316
460
  };
317
- declare const isTaskIdRef: (task: WorldTaskRef) => task is WorldTaskIdRef;
318
- declare const isTaskSpec: (task: WorldTaskRef) => task is WorldTaskSpec;
319
- /** The label a task goes by in results: its name, `inline:<hash>` for an
320
- * unnamed inline task once the platform has hashed it, or the stored task's
321
- * name (its id until the platform has answered). */
322
- declare const taskLabel: (task: WorldTaskRef, info?: WorldSessionTask | null) => string;
323
461
  type SeedResult = {
324
462
  seeded: number;
325
463
  mode: "append" | "replace";
@@ -350,6 +488,10 @@ type WorldSessionState = {
350
488
  instruction?: string | null;
351
489
  /** The tools this task serves. */
352
490
  tools?: WorldToolSpec[];
491
+ /** When the fleet reaps this session unless a call lands first; null for
492
+ * a pinned session (never reaped). Absent on platforms that predate it. */
493
+ idleExpiresAt?: string | null;
494
+ pinned?: boolean;
353
495
  /** Where the session answers besides `tools` — see worlds/browser.ts. */
354
496
  surfaces?: SessionSurfaces;
355
497
  /** Notices about the world's shape (an api bundle is a deprecated layout;
@@ -368,8 +510,19 @@ type WorldDeprecation = {
368
510
  type GradeResult = {
369
511
  reward: number | null;
370
512
  rewards: Record<string, number>;
513
+ /** Why there is no reward: `no grader` on an exploratory session. */
514
+ reason?: string;
515
+ /** The task's cross-world verifiers anchored on this session, by name:
516
+ * each its own reward and named rewards, or `error` when it could not
517
+ * grade (evidence missing, verify.py failed) — null, never zero. */
518
+ verifiers?: Record<string, VerifierGrade>;
371
519
  raw: unknown;
372
520
  };
521
+ type VerifierGrade = {
522
+ reward: number | null;
523
+ rewards: Record<string, number>;
524
+ error?: string;
525
+ };
373
526
  declare const modelToolName: (name: string) => string;
374
527
  /**
375
528
  * Turn a world's Python signature into a JSON schema the model can call.
@@ -399,11 +552,15 @@ declare class WorldSession {
399
552
  private readonly options;
400
553
  constructor(sessionId: string, current: WorldSessionState, options: WorldsClientOptions);
401
554
  /** The task's display name: a bundled scenario's, or the inline spec's
402
- * `name` (null when the spec was unnamed). Same as `taskName`. */
403
- get task(): string | null;
404
- /** The task's display name: a bundled scenario's, or the inline spec's
405
- * `name` (null when the spec was unnamed). */
555
+ * `name` (null when the spec was unnamed). `task` is the same. */
406
556
  get taskName(): string | null;
557
+ get task(): string | null;
558
+ /** `{idleExpiresAt, pinned}` as of the last state read: when the fleet
559
+ * reaps the session (null once pinned), and whether it is pinned. */
560
+ get idle(): {
561
+ idleExpiresAt: string | null;
562
+ pinned: boolean;
563
+ };
407
564
  /** The platform's notices about the world this session runs on (empty
408
565
  * for a schema world). Printed by the CLI on stderr at open. */
409
566
  get deprecations(): WorldDeprecation[];
@@ -443,6 +600,12 @@ declare class WorldSession {
443
600
  agentId?: string;
444
601
  record?: boolean;
445
602
  }): Promise<WorldBrowser>;
603
+ /** Ask the platform to make this session's hosted browser reachable again
604
+ * after its connection dropped: `healthy` (reconnect now), `replaced` (a new,
605
+ * blank browser behind the same wsUrl; reconnect and reopen your page) or
606
+ * `starting` (ask again in `retryAfterMs`). `browser()` does this on its
607
+ * own; call it when you drive your own Playwright against `wsUrl`. */
608
+ repairBrowser(): Promise<RepairAnswer>;
446
609
  /** The reporter `browser()` uses; exposed for a page you drive yourself. */
447
610
  browserRecorder(agentId?: string): BrowserActionRecorder;
448
611
  /** Browser actions as model tools, in the same shape as `toolkit()`. */
@@ -490,10 +653,14 @@ declare class WorldSession {
490
653
  * the judge's budget (15 min) instead of a call's. `timeoutMs` overrides
491
654
  * either. `report` is the agent's own account of what it did and found,
492
655
  * handed to the judge as its claim beside the evidence (the state and the
493
- * calls); assertions and python graders ignore it. */
656
+ * calls); assertions and python graders ignore it. `worlds` names the
657
+ * task's other sessions by alias (`{alias: sessionId}`): the platform
658
+ * reads each one's evidence and hands it to the cross-world verifiers
659
+ * anchored on this session, whose grades come back under `verifiers`. */
494
660
  grade(opts?: {
495
661
  timeoutMs?: number;
496
662
  report?: string;
663
+ worlds?: Record<string, string>;
497
664
  }): Promise<GradeResult>;
498
665
  /**
499
666
  * Put rows into the LIVE world through its contract, in one batch:
@@ -559,19 +726,25 @@ type OpenSessionOptions = {
559
726
  /** More than `tools`: `["api"]`, `["ui"]`, `["browser"]`. The platform
560
727
  * refuses (HTTP 400) rather than quietly serving less than asked. */
561
728
  surfaces?: WorldSurfaceKind[];
729
+ /** Capacity for a World Host session's browser: `standard` (spot, may be
730
+ * reclaimed) or `premium` (on-demand). Unset, the organization's default. */
731
+ browserTier?: BrowserTier;
562
732
  options?: WorldsClientOptions;
563
733
  };
564
734
  /**
565
- * Open a live session against one task of a world. Returns as soon as the
566
- * platform has accepted it — call `ready()` to wait for the container.
735
+ * Open a live session on a world. Returns as soon as the platform has
736
+ * accepted it — call `ready()` to wait for the container.
567
737
  *
568
738
  * `task` is a bundled scenario's name, a stored task's `{ id, version? }`
569
739
  * or an inline `WorldTaskSpec` (the latter two need a host engine world — the
570
- * platform answers 400 for a pod world). The older positional form
740
+ * platform answers 400 for a pod world). Omitted, the session is EXPLORATORY:
741
+ * the platform records an inline `{instruction: "exploratory session"}` with
742
+ * no grader as `task.source: "none"`, and `grade()` answers
743
+ * `{reward: null, reason: "no grader"}`. The older positional form
571
744
  * `openSession(slug, "task-name", opts)` still works.
572
745
  */
573
- declare function openSession(slugOrRef: string, task: OpenSessionOptions & {
574
- task: WorldTaskRef;
746
+ declare function openSession(slugOrRef: string, task?: OpenSessionOptions & {
747
+ task?: WorldTaskRef;
575
748
  }): Promise<WorldSession>;
576
749
  declare function openSession(slugOrRef: string, task: WorldTaskRef, opts?: OpenSessionOptions): Promise<WorldSession>;
577
750
  type SessionRunResult = {
@@ -678,9 +851,26 @@ declare function runSessions(opts: {
678
851
  * and never fails the action; the platform renders it as the session's
679
852
  * browser timeline. Text typed into secret-looking fields is redacted before
680
853
  * it leaves the process.
854
+ *
855
+ * RECONNECT. A World Host browser on the `standard` tier can be reclaimed
856
+ * mid-session. When an action fails because the browser or its connection is
857
+ * gone, a hosted `cdp` browser asks the platform to repair it, reconnects to
858
+ * the same address and reopens the page it was on (see `browserReconnect.ts`).
859
+ * A read or a `goto` then runs once more; a click, type, press, back or scroll
860
+ * is NOT replayed — its input may already have reached the world — and throws
861
+ * `BrowserReconnected` so the agent looks at the page again. Local and
862
+ * `playwright`-protocol browsers never reconnect.
681
863
  */
682
864
  declare const SURFACE_KINDS: readonly ["tools", "api", "ui", "browser"];
683
865
  type WorldSurfaceKind = (typeof SURFACE_KINDS)[number];
866
+ /** Capacity behind a World Host session's browser. `standard` runs on spot
867
+ * capacity first (about half the price) and may be reclaimed with two
868
+ * minutes' notice, ending the browser but never the world; `premium` is
869
+ * on-demand and never spot-reclaimed. Unset, the organization's default applies. */
870
+ declare const BROWSER_TIERS: readonly ["standard", "premium"];
871
+ type BrowserTier = (typeof BROWSER_TIERS)[number];
872
+ /** Refuse a tier the platform does not know, before any request is sent. */
873
+ declare function assertBrowserTier(value: unknown): asserts value is BrowserTier;
684
874
  declare const DEFAULT_VIEWPORT: {
685
875
  width: number;
686
876
  height: number;
@@ -721,6 +911,8 @@ type SessionSurfaces = {
721
911
  width: number;
722
912
  height: number;
723
913
  };
914
+ /** The capacity tier the browser runs on; present for World Host sessions. */
915
+ tier?: BrowserTier;
724
916
  };
725
917
  };
726
918
  declare class WorldSurfaceUnavailable extends Error {
@@ -841,7 +1033,6 @@ declare class BrowserActionRecorder {
841
1033
  * real Playwright page for anything this wrapper does not cover.
842
1034
  */
843
1035
  declare class WorldBrowser {
844
- readonly page: BrowserPage;
845
1036
  readonly ui: SessionSurfaces["ui"] | undefined;
846
1037
  readonly mode: Exclude<BrowserMode, "auto">;
847
1038
  private readonly teardown;
@@ -850,17 +1041,45 @@ declare class WorldBrowser {
850
1041
  height: number;
851
1042
  };
852
1043
  readonly recorder: BrowserActionRecorder | null;
1044
+ private readonly reconnector;
1045
+ /** Takes session credentials out of every error this browser records. */
1046
+ private readonly scrubber;
1047
+ private current;
1048
+ private inflight;
1049
+ private lastNetwork;
1050
+ /** Where the page last was after an action, token stripped: what a
1051
+ * reconnect reopens. Null until the page has left `about:blank`. */
1052
+ private lastUrl;
853
1053
  constructor(page: BrowserPage, ui: SessionSurfaces["ui"] | undefined, mode: Exclude<BrowserMode, "auto">, teardown: () => Promise<void>, viewport?: {
854
1054
  width: number;
855
1055
  height: number;
856
- }, recorder?: BrowserActionRecorder | null);
857
- private inflight;
858
- private lastNetwork;
1056
+ }, recorder?: BrowserActionRecorder | null, reconnector?: BrowserReconnector | null,
1057
+ /** Takes session credentials out of every error this browser records. */
1058
+ scrubber?: SecretScrubber);
1059
+ /** The live Playwright page; a new object after a reconnect. */
1060
+ get page(): BrowserPage;
859
1061
  get agentId(): string | null;
1062
+ private watchNetwork;
1063
+ /** Run `fn` against the page. If it fails because the browser is gone,
1064
+ * recover; then `retry` runs it ONCE more and `report` throws
1065
+ * `BrowserReconnected` instead of replaying it. Any other error, and a
1066
+ * second loss during the retry, propagate unchanged. */
1067
+ private resilient;
1068
+ private remember;
1069
+ /** The page's URL less its token; null while it is blank. */
1070
+ private openedUrl;
1071
+ private recover;
1072
+ /** Take over a new connection's page and reopen the page the agent was on
1073
+ * (`openBrowser` owns the connection itself). A new browser has no session
1074
+ * cookie, so a World Host UI is first loaded with its token, exactly as
1075
+ * `goto()` loads the entry page. */
1076
+ private adopt;
860
1077
  /** Run one action and report it: the event carries what was asked,
861
1078
  * whether it worked, and the screen after — for failures too, so a
862
1079
  * reviewer sees what the agent saw when the selector did not match. */
863
1080
  private act;
1081
+ /** One event on the recorder, if there is one; `failure` null means ok. */
1082
+ private report;
864
1083
  private observeForEvent;
865
1084
  /** Open a UI path (`/customers`), a full URL, or — with no argument — the
866
1085
  * UI's declared entry page. */
@@ -915,6 +1134,9 @@ declare function openBrowser(surfaces: SessionSurfaces, opts?: {
915
1134
  headless?: boolean;
916
1135
  playwright?: PlaywrightLike;
917
1136
  recorder?: BrowserActionRecorder | null;
1137
+ /** The session's repair call (`session.repairBrowser`). Given, a hosted
1138
+ * `cdp` browser reconnects on its own when the browser is lost. */
1139
+ repair?: () => Promise<RepairAnswer>;
918
1140
  }): Promise<WorldBrowser>;
919
1141
  declare const COMPUTER_USE_SPECS: readonly [{
920
1142
  readonly name: "browser_goto";
@@ -959,6 +1181,127 @@ declare function computerUseToolkit(browser: WorldBrowser, opts?: {
959
1181
  maxText?: number;
960
1182
  }): WorldToolkit;
961
1183
 
1184
+ declare const PLATFORM_TIMEOUT_ENV = "GATEWAY_TIMEOUT_MS";
1185
+ /** How long one platform request may go unanswered before it is abandoned; `GATEWAY_TIMEOUT_MS` overrides it. */
1186
+ declare const PLATFORM_TIMEOUT_DEFAULT_MS = 120000;
1187
+ type PlatformEndpoint = {
1188
+ host: string;
1189
+ publicKey: string;
1190
+ secretKey: string;
1191
+ };
1192
+ type PlatformMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
1193
+ type PlatformReply = {
1194
+ status: number;
1195
+ ok: boolean;
1196
+ text: string;
1197
+ };
1198
+ /** The request budget in force: `GATEWAY_TIMEOUT_MS` when set, else the default. */
1199
+ declare function platformTimeoutMs(env?: NodeJS.ProcessEnv): number;
1200
+ /** Why a request got no answer, from the socket-level error undici hides under `fetch failed`. */
1201
+ declare class TransportCause {
1202
+ readonly reason: string;
1203
+ readonly detail: string | null;
1204
+ readonly next: string;
1205
+ private constructor();
1206
+ static timeout(timeoutMs: number): TransportCause;
1207
+ static of(error: unknown): TransportCause;
1208
+ describe(): string;
1209
+ }
1210
+ /** A platform request that never got an answer: one line naming the request, the host, the cause and the next step. */
1211
+ declare class UnreachableError extends Error {
1212
+ readonly host: string;
1213
+ readonly method: string;
1214
+ readonly route: string;
1215
+ readonly failure: TransportCause;
1216
+ constructor(host: string, method: string, route: string, failure: TransportCause);
1217
+ }
1218
+ /** The one door every CLI and SDK request to the platform goes through: Basic auth with the project key, a per-request timeout, and a transport failure turned into an `UnreachableError`. */
1219
+ declare class PlatformTransport {
1220
+ private readonly endpoint;
1221
+ private readonly timeoutMs;
1222
+ constructor(endpoint: PlatformEndpoint, timeoutMs?: number);
1223
+ /** A request that legitimately takes longer (a sandbox exec, a world create) waits its own budget; every other one waits the default. */
1224
+ budget(ownMs?: number): number;
1225
+ send(method: PlatformMethod, route: string, body?: unknown, opts?: {
1226
+ timeoutMs?: number;
1227
+ }): Promise<PlatformReply>;
1228
+ }
1229
+
1230
+ /** Mirrors `WorldSessionListItemSchema` (web/features/public-api/types/world-sessions.ts). */
1231
+ type WorldSessionListItem = {
1232
+ sessionId: string;
1233
+ slug: string;
1234
+ containerId: string;
1235
+ state: string;
1236
+ ready: boolean;
1237
+ versionId: string;
1238
+ contentHash: string;
1239
+ taskName: string | null;
1240
+ engine: string;
1241
+ pinned: boolean;
1242
+ surfaces: string[];
1243
+ createdAt: string;
1244
+ lastUsedAt: string;
1245
+ };
1246
+ /** A World Host session's states (`SessionState` in shared `worldSessions.ts`). */
1247
+ declare const SESSION_STATES: readonly ["PROVISIONING", "RUNNING", "IDLE", "STOPPING", "STOPPED", "FAILED", "LOST"];
1248
+ type ListSessionsFilter = {
1249
+ /** One of SESSION_STATES. */
1250
+ state?: string;
1251
+ slug?: string;
1252
+ limit?: number;
1253
+ };
1254
+ /** The project's live sessions, newest first — the ones an agent can attach to. */
1255
+ declare function listSessions(filter?: ListSessionsFilter, options?: WorldsClientOptions): Promise<WorldSessionListItem[]>;
1256
+
1257
+ /**
1258
+ * THE NUMBERS AND WORDS A WORLD SESSION PROMISES — the TypeScript SDK twin.
1259
+ *
1260
+ * The platform declares them once in
1261
+ * `gateway/packages/shared/src/server/services/worldSessionContract.ts`; this
1262
+ * module and `gatewaysdk/environment/world_session_contract.py` repeat them, and each is
1263
+ * pinned to `conformance/world-sessions.json` by a test, so the route, the
1264
+ * World Host and the two CLIs cannot drift apart.
1265
+ */
1266
+ /** The largest body `POST world-sessions/{id}/calls` accepts. The SDK
1267
+ * measures the serialized body against the byte count and refuses before
1268
+ * sending; the label is what help and the refusal name. */
1269
+ declare const CALL_BODY_LIMIT_BYTES: number;
1270
+ declare const CALL_BODY_LIMIT_LABEL = "4mb";
1271
+ /** `session status` warns once an unpinned session has less than this left. */
1272
+ declare const IDLE_WARNING_MINUTES = 5;
1273
+ /** The task an exploratory session runs on when the caller names none, and
1274
+ * the `task.source` the platform reports for it. */
1275
+ declare const EXPLORATORY_TASK: Readonly<{
1276
+ instruction: "exploratory session";
1277
+ }>;
1278
+ declare const EXPLORATORY_TASK_SOURCE = "none";
1279
+ /** What a session that has no grader answers `grade` with, beside
1280
+ * `reward: null`. */
1281
+ declare const NO_GRADER_REASON = "no grader";
1282
+ /** The call's body exceeds the platform's limit: nothing was sent. `limit`
1283
+ * is the label the route enforces (`4mb`), `size` the body's bytes. */
1284
+ declare class WorldCallTooLarge extends Error {
1285
+ readonly size: number;
1286
+ readonly limitBytes: number;
1287
+ readonly limit: string;
1288
+ readonly code = "payload_too_large";
1289
+ constructor(size: number, limitBytes?: number, limit?: string);
1290
+ /** The structured refusal the CLIs print. */
1291
+ toJSON(): {
1292
+ status: "error";
1293
+ code: "payload_too_large";
1294
+ limit: string;
1295
+ size: number;
1296
+ };
1297
+ }
1298
+ /** Measure a call body the way the route will and refuse an oversized one
1299
+ * before it leaves the machine. Returns the serialized body. */
1300
+ declare function serializeCallBody(body: unknown): string;
1301
+ /** The line `session status` prints when an unpinned session has under
1302
+ * `IDLE_WARNING_MINUTES` left, else null. `now` is for tests. */
1303
+ declare function idleWarning(idleExpiresAt: string | null | undefined, now?: Date): string | null;
1304
+
962
1305
  /** The per-world entry of a `WorldTaskSpec.worlds` table. */
963
1306
  type WorldTaskWorld = {
964
1307
  slug: string;
@@ -1027,18 +1370,25 @@ type LiveTaskSession = {
1027
1370
  taskVersion: number | null;
1028
1371
  createdAt: string;
1029
1372
  };
1030
- /** The task's grade: every world's own `GradeResult` under its alias, and
1031
- * the aggregate. `reward` is the mean of the worlds' numeric rewards — null
1032
- * when no world answered one (no grader anywhere, or a judge still
1033
- * pending); a world with no reward is listed under `ungraded`, never
1034
- * counted as 0. `rewards` flattens each world's named rewards as
1035
- * `<alias>.<key>` beside `<alias>` for the world's own reward. */
1373
+ /** The task's grade: every world's own `GradeResult` under its alias, the
1374
+ * task's cross-world verifiers by name (lifted from the world each is
1375
+ * anchored on), and the aggregate. `reward` is the mean of the worlds' and
1376
+ * verifiers' numeric rewards — null when none answered one (no grader
1377
+ * anywhere, or a judge still pending); a world or verifier with no reward
1378
+ * is listed under `ungraded` (a verifier as `x.<name>`), never counted as
1379
+ * 0. `rewards` flattens each world's named rewards as `<alias>.<key>`
1380
+ * beside `<alias>` for the world's own reward, and a verifier's as
1381
+ * `x.<name>` / `x.<name>.<key>`. */
1036
1382
  type TaskGrade = {
1037
1383
  reward: number | null;
1038
1384
  rewards: Record<string, number>;
1039
1385
  worlds: Record<string, GradeResult>;
1040
1386
  ungraded: string[];
1387
+ verifiers: Record<string, VerifierGrade>;
1041
1388
  };
1389
+ /** A cross-world verifier's rewards flatten under `x.<name>`; no alias
1390
+ * starts with `x.`. */
1391
+ declare const VERIFIER_REWARD_PREFIX = "x.";
1042
1392
  /** Every world's call log, keyed by alias. */
1043
1393
  type TaskExport = Record<string, WorldSessionCall[]>;
1044
1394
  /** Combine per-world grades into the task's. Pure, so the CLI and the tests
@@ -1094,11 +1444,15 @@ declare class TaskSessions {
1094
1444
  manifest(): Promise<TaskManifest>;
1095
1445
  /** Grade every world and aggregate — see `TaskGrade`. One `report` (the
1096
1446
  * agent's own account of the whole investigation) goes to every world's
1097
- * judge; a world graded by assertions or python ignores it. */
1447
+ * judge; a world graded by assertions or python ignores it. Each grade
1448
+ * names the task's other sessions by alias, so the cross-world verifiers
1449
+ * anchored on that world can read them. */
1098
1450
  grade(opts?: {
1099
1451
  timeoutMs?: number;
1100
1452
  report?: string;
1101
1453
  }): Promise<TaskGrade>;
1454
+ /** The task's other sessions by alias: what a grade names. */
1455
+ private otherSessions;
1102
1456
  /** Every world's call log, keyed by alias. */
1103
1457
  export(): Promise<TaskExport>;
1104
1458
  /** Close every world. Closes are attempted for all of them even when one
@@ -1116,6 +1470,9 @@ type OpenTaskOptions = {
1116
1470
  * fewer surfaces than asked, and then nothing is up. */
1117
1471
  surfaces?: WorldSurfaceKind[];
1118
1472
  reuseWarm?: boolean;
1473
+ /** Browser capacity for every world the task opens: `standard` (spot, may
1474
+ * be reclaimed) or `premium` (on-demand). Unset, the organization's default. */
1475
+ browserTier?: BrowserTier;
1119
1476
  options?: WorldsClientOptions;
1120
1477
  };
1121
1478
  /**
@@ -1144,26 +1501,6 @@ declare function attachManifest(manifest: TaskManifest, options?: WorldsClientOp
1144
1501
  * rather than a task spec. */
1145
1502
  declare function isTaskManifest(value: unknown): value is TaskManifest;
1146
1503
 
1147
- /**
1148
- * RUN A TASK END TO END: open, agent, grade, file, close.
1149
- *
1150
- * `runTask` is `gateway worlds task run` in one call: bring every world of a
1151
- * task up, hand the agent a small `TaskRun` (its sessions, a merged
1152
- * toolkit, a place to record notes), grade every world with the agent's own
1153
- * report, file one rollout the same way the Python SDK's `World.run` does
1154
- * for a single in-process world, and close everything down — a run
1155
- * directory on disk is the paper trail (`manifest.json`, `grades.json`,
1156
- * `report.md`, `run.json`). Mirrors `gatewaysdk.world_tasks.run_task`.
1157
- *
1158
- * const summary = await runTask("wt_1", async (run) => {
1159
- * const { url, token } = await run.api("spycloud");
1160
- * // ... call the agent, using run.sessions / run.toolkit() ...
1161
- * return "found and locked the account";
1162
- * }, { model: "claude-sonnet-4-5" });
1163
- */
1164
- /** What the agent callable given to `runTask` is called with: the run's
1165
- * identity, every world's live session, and a place to leave notes that
1166
- * land in the run's `run.json`. */
1167
1504
  declare class TaskRun {
1168
1505
  readonly runId: string;
1169
1506
  readonly instruction: string;
@@ -1172,27 +1509,19 @@ declare class TaskRun {
1172
1509
  readonly manifest: TaskManifest;
1173
1510
  readonly notes: Record<string, unknown>;
1174
1511
  constructor(runId: string, instruction: string, model: string, sessions: Record<string, WorldSession>, manifest: TaskManifest);
1175
- /** The alias's session, or a clear error naming the aliases there are. */
1176
1512
  session(alias: string): WorldSession;
1177
- /** `alias`'s HTTP API. Raises the same error the session itself would
1178
- * when it was not opened with `surfaces: ["api"]`. */
1513
+ /** Raises when the session was not opened with `surfaces: ["api"]`. */
1179
1514
  api(alias: string): Promise<{
1180
1515
  url: string;
1181
1516
  token?: string;
1182
1517
  }>;
1183
- /** Every world's tools merged into one toolkit, each name prefixed
1184
- * `<alias>.<tool>` so a model can tell which world a call goes to. A
1185
- * world that exposes no tools contributes nothing — there is nothing to
1186
- * merge. */
1518
+ /** Each tool is prefixed `<alias>.<tool>` so a model can tell which world a call goes to. */
1187
1519
  toolkit(): Promise<WorldToolkit>;
1188
- /** Log arbitrary notes into this run's `run.json` (merged; a later call
1189
- * overrides a key an earlier one set). */
1520
+ /** Merged into `run.json` under `notes`; a later call overrides an earlier key. */
1190
1521
  record(notes: Record<string, unknown>): void;
1191
1522
  }
1192
1523
  type RunTaskOptions = {
1193
- /** Model label recorded on the filed run. */
1194
1524
  model: string;
1195
- /** Asked of every world besides tools: api, ui, browser. */
1196
1525
  surfaces?: WorldSurfaceKind[];
1197
1526
  /** Directory the run's own `<runId>/` folder is created under. Default `"runs"`. */
1198
1527
  outDir?: string;
@@ -1203,9 +1532,11 @@ type RunTaskOptions = {
1203
1532
  /** Leave every session up instead of closing it when the run ends. Default `false`. */
1204
1533
  keepUp?: boolean;
1205
1534
  reuseWarm?: boolean;
1535
+ browserTier?: BrowserTier;
1536
+ /** File the rollout under this set run (`runSet` sets it). */
1537
+ setRunId?: string;
1206
1538
  options?: WorldsClientOptions;
1207
1539
  };
1208
- /** What `runTask` returns and writes to `<runDir>/run.json`. */
1209
1540
  type RunTaskSummary = {
1210
1541
  runId: string;
1211
1542
  taskId: string | null;
@@ -1227,33 +1558,99 @@ type RunTaskSummary = {
1227
1558
  evaluationId?: string;
1228
1559
  [extra: string]: unknown;
1229
1560
  };
1230
- /** The report an agent callable may return: a string, or an object with an
1231
- * optional string `report` key (any other keys are kept in `run.json` as-is),
1232
- * or nothing. Anything else is an agent error — a number, a bigint or an
1233
- * array is never stringified into a graded completion. */
1234
1561
  type TaskRunResult = string | {
1235
1562
  report?: unknown;
1236
1563
  [key: string]: unknown;
1237
1564
  } | null | undefined;
1238
- /**
1239
- * Open every world of a task, run `agent` once against all of them, grade
1240
- * with its report, file one rollout and close — the engine behind `gateway
1241
- * worlds task run`. `agent` is called as `agent(taskRun)` with a `TaskRun`;
1242
- * its return value becomes the report handed to every world's grader.
1243
- *
1244
- * Every step has a flag and a default, nothing implicit: tracing runs when
1245
- * `GATEWAY_*` credentials are configured unless `trace: false`; filing
1246
- * happens unless `file: false`; every session closes unless `keepUp: true`
1247
- * — even when the agent throws, so grading and filing still happen with the
1248
- * error recorded (`run.json.agentError`, the filed evaluation's status
1249
- * FAILED).
1250
- *
1251
- * Writes `<outDir>/<runId>/{manifest,grades,run}.json` (and `report.md`
1252
- * when the agent gave one).
1253
- */
1565
+ /** Mirrors `gatewaysdk.world_tasks.run_task`. Sessions close unless `keepUp: true`, even when the agent throws, so grading and filing
1566
+ * still happen with the error recorded. */
1254
1567
  declare function runTask(ref: string | WorldTaskIdRef | WorldTaskSpec, agent: (run: TaskRun) => TaskRunResult | Promise<TaskRunResult>, opts: RunTaskOptions): Promise<RunTaskSummary>;
1255
1568
 
1256
- /** One rollout, in the platform's sample shape. */
1569
+ type Checkout = {
1570
+ branch?: string;
1571
+ commit?: string;
1572
+ repoUrl?: string;
1573
+ pr?: {
1574
+ number: number;
1575
+ url: string;
1576
+ title?: string;
1577
+ };
1578
+ };
1579
+ type Env = Record<string, string | undefined>;
1580
+ /** Labels for the reader, never used to authorize. The PR comes from `GATEWAY_PR_URL`
1581
+ * (+ `GATEWAY_PR_TITLE`), else GitHub Actions' `GITHUB_REF=refs/pull/<n>/merge`. */
1582
+ declare class CheckoutProvenance {
1583
+ private readonly cwd;
1584
+ private readonly env;
1585
+ constructor(cwd: string, env: Env);
1586
+ static read(cwd?: string, env?: Env): Checkout;
1587
+ checkout(): Checkout;
1588
+ /** Security: credentials are stripped; scp-style `git@host:org/repo` has none and is kept. */
1589
+ static withoutCredentials(url: string): string;
1590
+ private withPr;
1591
+ private pullRequest;
1592
+ private git;
1593
+ }
1594
+
1595
+ type SetRunDoc = {
1596
+ id: string;
1597
+ status: "running" | "completed" | "failed";
1598
+ model: string | null;
1599
+ source: string | null;
1600
+ taskSetDatasetId: string | null;
1601
+ actor: {
1602
+ kind: string;
1603
+ id: string;
1604
+ name?: string;
1605
+ } | null;
1606
+ git: Checkout | null;
1607
+ progress: {
1608
+ done: number;
1609
+ planned: number;
1610
+ };
1611
+ score: {
1612
+ mean: number | null;
1613
+ gradedTasks: number;
1614
+ ungradedTasks: number;
1615
+ };
1616
+ tasks: Array<{
1617
+ worldTaskId: string;
1618
+ datasetItemId: string;
1619
+ name: string;
1620
+ evaluationId: string | null;
1621
+ sampleId: string | null;
1622
+ status: "pending" | "completed" | "failed";
1623
+ reward: number | null;
1624
+ checks: Array<{
1625
+ key: string;
1626
+ outcome: "passed" | "failed" | "ungraded";
1627
+ value: number | null;
1628
+ }>;
1629
+ }>;
1630
+ };
1631
+ type RunSetOptions = {
1632
+ model: string;
1633
+ /** Default `"sdk"`; the CLI passes `"cli"`. */
1634
+ source?: "cli" | "sdk";
1635
+ /** Default: read from the working directory; `null` records none. */
1636
+ git?: Checkout | null;
1637
+ surfaces?: WorldSurfaceKind[];
1638
+ browserTier?: BrowserTier;
1639
+ outDir?: string;
1640
+ trace?: boolean;
1641
+ onTask?: (summary: RunTaskSummary) => void;
1642
+ options?: WorldsClientOptions;
1643
+ };
1644
+ /** `failed`: an agent raised, a task could not run, or the platform stored the run as anything but completed. */
1645
+ type RunSetResult = {
1646
+ setRun: SetRunDoc;
1647
+ tasks: RunTaskSummary[];
1648
+ failed: boolean;
1649
+ closedAsRequested: boolean;
1650
+ };
1651
+ /** A low or missing reward is a result, not a failure; every task runs even after one fails. */
1652
+ declare function runSet(datasetId: string, agent: (run: TaskRun) => TaskRunResult | Promise<TaskRunResult>, opts: RunSetOptions): Promise<RunSetResult>;
1653
+
1257
1654
  type EvalSample = {
1258
1655
  exampleId: string;
1259
1656
  task?: string;
@@ -1268,6 +1665,8 @@ type EvalSample = {
1268
1665
  };
1269
1666
  type CreateEvaluationOptions = {
1270
1667
  model?: string;
1668
+ /** A set run to file under; the platform refuses a run that does not admit this result. */
1669
+ runId?: string;
1271
1670
  rolloutsPerExample?: number;
1272
1671
  metadata?: Record<string, unknown>;
1273
1672
  };
@@ -1278,14 +1677,21 @@ type FinalizeEvaluationOptions = {
1278
1677
  declare class GatewayEvalsClient {
1279
1678
  private readonly options;
1280
1679
  constructor(options?: WorldsClientOptions);
1281
- /** Anchor a new evaluation to `versionId`; returns its id. */
1282
1680
  createEvaluation(versionId: string, opts?: CreateEvaluationOptions): Promise<string>;
1283
- /** Push one batch of samples; returns how many the platform inserted. */
1284
1681
  pushSamples(evaluationId: string, samples: EvalSample[]): Promise<number>;
1285
- /** Close the evaluation out; returns its final status. */
1286
1682
  finalizeEvaluation(evaluationId: string, opts?: FinalizeEvaluationOptions): Promise<string>;
1287
1683
  }
1288
1684
 
1685
+ /** One entry the archive rules dropped: a whole directory (`name/`, `files`
1686
+ * counted) or a single file. */
1687
+ type Exclusion = {
1688
+ path: string;
1689
+ files: number;
1690
+ };
1691
+
1692
+ /** The only mode detail a world keeps: executable or not. */
1693
+ declare function archiveMode(mode: number): number;
1694
+
1289
1695
  /**
1290
1696
  * The working-dir half of the TS CLI: push / pull / checkout / status /
1291
1697
  * branch / tag / propose — a faithful port of the Python client
@@ -1306,13 +1712,16 @@ declare const DEFAULT_BRANCH = "main";
1306
1712
  * (`WorldDir.archivePaths`). Throws on a root .gitignore (see the header). */
1307
1713
  declare function collectArchiveRelPaths(dir: string): string[];
1308
1714
  declare function computeContentHash(dir: string): string;
1309
- declare function archiveMode(mode: number): number;
1715
+
1310
1716
  /** A deterministic .tar.gz of the source files (node's gzip stamps no mtime,
1311
1717
  * matching the Python's mtime=0 gzip). */
1312
1718
  declare function buildSourceTarball(dir: string): Buffer;
1313
1719
  type LocalMeta = Record<string, unknown> & {
1314
1720
  slug?: string;
1721
+ /** Branch the checkout tracks; absent on a tag (detached) checkout. */
1315
1722
  branch?: string;
1723
+ /** Tag the checkout was taken from: immutable, so `push` refuses to move it. */
1724
+ tag?: string;
1316
1725
  versionId?: string;
1317
1726
  contentHash?: string;
1318
1727
  baseFiles?: Record<string, string>;
@@ -1373,6 +1782,14 @@ declare function buildFileManifest(dir: string): {
1373
1782
  size: number;
1374
1783
  sha256: string;
1375
1784
  }[];
1785
+ /** The refusal `push` raises from a tag checkout: tags never move, so the
1786
+ * push needs a branch named explicitly. */
1787
+ declare class DetachedPushError extends Error {
1788
+ constructor(dir: string, tag: string);
1789
+ }
1790
+ /** The branch a push of `dir` moves: an explicit --branch, else the tracked
1791
+ * branch, else main — never a tag. */
1792
+ declare function pushBranch(dir: string, localMeta: LocalMeta, explicit: string | undefined): string;
1376
1793
  declare function push(dir: string, opts?: {
1377
1794
  slug?: string;
1378
1795
  branch?: string;
@@ -1401,10 +1818,29 @@ declare function push(dir: string, opts?: {
1401
1818
  branch: string;
1402
1819
  state: string | null;
1403
1820
  alreadyUploaded: boolean;
1821
+ /** The edit session the push joined (`gateway worlds edit close <slug>` moves main); null when the platform landed it on main directly. */
1822
+ editSessionId: string | null;
1823
+ /** Files the archive rules kept (what the hash, manifest and tarball cover). */
1824
+ filesKept: number;
1825
+ /** What the archive rules left out, so nothing disappears silently. */
1826
+ excluded: Exclusion[];
1404
1827
  }>;
1405
- /** Extract a downloaded bundle into `dir` (paths sanitized, executable bit kept). */
1828
+ /** Extract a downloaded bundle into `dir` (paths confined, executable bit
1829
+ * kept; every name encoding the platform's writers emit — see ./tar.ts). */
1406
1830
  declare function extractBundle(bundle: Buffer, dir: string): number;
1407
- declare function pull(slugRef: string, target?: string, options?: WorldsClientOptions): Promise<{
1831
+ /** What a checkout tracks after a pull: the branch that answered the ref, or
1832
+ * the tag it was taken from (detached). Older servers name neither: latest
1833
+ * and semver/hash pins land on main; any other ref was a branch. */
1834
+ declare function checkoutIdentity(ref: string, resolved: {
1835
+ branch?: string | null;
1836
+ tag?: string | null;
1837
+ }): {
1838
+ branch?: string;
1839
+ tag?: string;
1840
+ };
1841
+ declare function pull(slugRef: string, target?: string, options?: WorldsClientOptions, opts?: {
1842
+ force?: boolean;
1843
+ }): Promise<{
1408
1844
  slug: string;
1409
1845
  dir: string;
1410
1846
  versionId: string;
@@ -1636,9 +2072,11 @@ type WorldDescription = {
1636
2072
  entities: WorldEntity[];
1637
2073
  redact: RedactPolicy | null;
1638
2074
  };
1639
- /** The world's head version, described. The route reads the head only, so a
1640
- * `slug@ref` is refused rather than silently served as the head. */
1641
- declare function describeWorld(slug: string, options?: WorldsClientOptions): Promise<WorldDescription>;
2075
+ /** The world at `slug@ref`, described — `ref` is the one grammar shared with
2076
+ * pull/checkout/sandbox (`latest` | branch | tag | semver | version id | hash
2077
+ * prefix); a bare slug describes the head of `main`. An unknown ref is the
2078
+ * route's 404, never the head. */
2079
+ declare function describeWorld(slugRef: string, options?: WorldsClientOptions): Promise<WorldDescription>;
1642
2080
 
1643
2081
  /**
1644
2082
  * Named plaintext transforms for cross-world entity mappings.
@@ -2142,29 +2580,44 @@ declare function sessionToolObservations(sessionId: string, options?: WorldsClie
2142
2580
 
2143
2581
  /**
2144
2582
  * The CLI sandbox: a server-side workspace opened on a READY version of a
2145
- * world (`/workspace/env` in the console agent's sandbox), edited and run
2146
- * there, and committed straight into the version service — the source
2147
- * never lands on the caller's disk. One client under both `gateway worlds
2148
- * sandbox …` and `gateway bench sandbox …`; the Python twin is
2149
- * `gatewaysdk.benchmark_hub.sandbox.WorldSandboxClient`.
2583
+ * world (`/workspace/env` in the console agent's sandbox) — or, with
2584
+ * `{ new, from }`, on a world that does not exist yet, seeded from the
2585
+ * `schema init` scaffold or a shipped template and created by its first
2586
+ * commit — edited and run there, and committed straight into the version
2587
+ * service; the source never lands on the caller's disk. `importData` is the
2588
+ * data door beside `commit`: a rows file in the sandbox tree into the platform
2589
+ * world's data ledger, read out by the platform (no credential enters the
2590
+ * sandbox, nothing passes through this machine). One client under
2591
+ * both `gateway worlds sandbox …` and `gateway bench sandbox …`; the
2592
+ * Python twin is `gatewaysdk.benchmark_hub.sandbox.WorldSandboxClient`.
2150
2593
  */
2151
2594
  /** Mirrors `SandboxSummaryResponse` (web/features/public-api/types/world-sandboxes.ts). */
2152
2595
  type SandboxSummary = {
2153
2596
  sandboxId: string;
2154
2597
  slug: string;
2155
- containerId: string;
2156
- /** The version the next commit is validated against; advances on commit. */
2157
- baseVersionId: string;
2598
+ /** null while a new-world sandbox awaits its first commit. */
2599
+ containerId: string | null;
2600
+ /** The version the next commit is validated against; advances on commit. null before the first commit of a new world. */
2601
+ baseVersionId: string | null;
2602
+ /** Set on a new-world sandbox until its first commit creates the world. */
2603
+ pendingSlug: string | null;
2158
2604
  status: "open" | "closed";
2159
2605
  lastCommitVersionId: string | null;
2160
2606
  createdAt: string;
2161
2607
  };
2162
2608
  type SandboxOpened = SandboxSummary & {
2163
- baseContentHash: string;
2609
+ /** null for a new-world sandbox (no base). */
2610
+ baseContentHash: string | null;
2164
2611
  branch: string;
2165
2612
  dataSnapshotId: string | null;
2166
2613
  fileCount: number;
2167
2614
  workdir: string;
2615
+ /** The `gateway` CLI `exec` finds on PATH (the platform's version, staged runtime digest); null when the image cannot host it — `warnings` says why. */
2616
+ cli: {
2617
+ version: string;
2618
+ digest: string;
2619
+ } | null;
2620
+ warnings: string[];
2168
2621
  };
2169
2622
  type SandboxExecResult = {
2170
2623
  exitCode: number;
@@ -2173,6 +2626,8 @@ type SandboxExecResult = {
2173
2626
  timedOut: boolean;
2174
2627
  truncated: boolean;
2175
2628
  durationMs: number;
2629
+ /** Why `gateway`/`sqlite3` were not on PATH for this command; empty when the runtime is staged. */
2630
+ warnings: string[];
2176
2631
  };
2177
2632
  type SandboxChanges = {
2178
2633
  added: string[];
@@ -2185,30 +2640,118 @@ type SandboxCheckResult = {
2185
2640
  noChange: boolean;
2186
2641
  fileCount: number;
2187
2642
  changes: SandboxChanges;
2643
+ /** Working-tree paths left out of the version: `.gatewayignore`, default scratch, credential-shaped files, links. */
2644
+ ignored: string[];
2645
+ /** Why a listed path was held back (credential-shaped, a link, unhashed by the gate); paths only. */
2188
2646
  warnings: string[];
2189
2647
  error: string | null;
2190
2648
  };
2191
2649
  type SandboxCommitResult = {
2650
+ /** The world the commit landed on. */
2651
+ slug: string;
2192
2652
  versionId: string;
2193
2653
  contentHash: string;
2194
2654
  branch: string;
2195
2655
  deduped: boolean;
2196
2656
  noChange: boolean;
2197
2657
  changes: SandboxChanges;
2658
+ ignored: string[];
2659
+ /** The same warnings `check` gives, so a commit never hides what it left out. */
2660
+ warnings: string[];
2661
+ /** The API key's edit session the commit joined; `gateway worlds edit close <slug>` moves main. */
2662
+ editSessionId?: string;
2198
2663
  };
2199
- /** `slug` or `slug@ref` → the open body; a bare slug opens the latest READY version. */
2200
- declare function parseSlugRef(slugRef: string): {
2664
+ /** Mirrors `PostSandboxImportBody`. */
2665
+ type SandboxImportInput = {
2666
+ /** A .json/.jsonl/.ndjson/.csv/.tsv (optionally .gz) relative to the world root. */
2667
+ path: string;
2668
+ entity?: string;
2669
+ /** One character (a real tab for TSV); defaults by extension. */
2670
+ delimiter?: string;
2671
+ mode?: "append" | "replace";
2672
+ merge?: "upsert" | "fill";
2673
+ redact?: "off" | "apply" | "refuse";
2674
+ atomic?: boolean;
2675
+ dryRun?: boolean;
2676
+ message?: string;
2677
+ };
2678
+ /** Mirrors `PostSandboxImportResponse` (201). */
2679
+ type SandboxImportResult = {
2680
+ containerId: string;
2681
+ slug: string;
2682
+ batchId: string | null;
2683
+ state: string;
2684
+ versionId: string | null;
2685
+ baseVersionId: string;
2686
+ contentHash: string | null;
2687
+ deduped: boolean;
2688
+ entityCounts: Record<string, number>;
2689
+ kind: string | null;
2690
+ dryRun: boolean;
2691
+ refusalCount: number;
2692
+ rowCount: number;
2693
+ chunkCount: number;
2694
+ /** `sandbox:<id>/<path>`. */
2695
+ source: string;
2696
+ };
2697
+ /** Mirrors `PostSandboxImportPendingResponse` (202): poll `worlds data batches`. */
2698
+ type SandboxImportPending = {
2699
+ batchId: string;
2700
+ state: string;
2701
+ rowCount: number;
2702
+ chunkCount: number;
2703
+ source: string;
2704
+ };
2705
+ declare const isSandboxImportPending: (answer: SandboxImportResult | SandboxImportPending) => answer is SandboxImportPending;
2706
+ /** Mirrors `PostSandboxOpenBody`: an existing world at a ref, or a new world seeded from a template. */
2707
+ type SandboxOpenExisting = {
2201
2708
  slug: string;
2202
2709
  ref?: string;
2203
2710
  };
2711
+ type SandboxOpenNew = {
2712
+ new: string;
2713
+ from: string;
2714
+ };
2715
+ type SandboxOpenTarget = SandboxOpenExisting | SandboxOpenNew;
2716
+ /** `slug` or `slug@ref` → the open body; a bare slug opens the latest READY version. */
2717
+ declare function parseSlugRef(slugRef: string): SandboxOpenExisting;
2718
+ /** One sandbox request may run the platform's longest exec (600 s) plus the answer; the Python twin waits the same 660 s. */
2719
+ declare const SANDBOX_REQUEST_TIMEOUT_MS = 660000;
2720
+ /** Mirrors `PostSandboxCommitBody`: `rebase` replays the sandbox's edits onto the branch head when the base moved. */
2721
+ type SandboxCommitInput = {
2722
+ message: string;
2723
+ branch?: string;
2724
+ rebase?: boolean;
2725
+ };
2726
+ /** One path a rebase refused, as the 409 body's `conflicts[]` names it. */
2727
+ type RebaseConflictPath = {
2728
+ path: string;
2729
+ reason: string;
2730
+ };
2731
+ /** A 409 from `commit --rebase`: the paths both sides changed and why each was refused. Null for any other failure. */
2732
+ declare function rebaseConflicts(error: unknown): RebaseConflictPath[] | null;
2733
+ /** A 409 `sandbox_uncommitted` from `close`: the paths a commit would keep. Null for any other failure. */
2734
+ declare function uncommittedPaths(error: unknown): string[] | null;
2735
+ /** `sandbox list` narrows: status, world, count (newest first). */
2736
+ type SandboxListFilter = {
2737
+ status?: "open" | "closed";
2738
+ slug?: string;
2739
+ limit?: number;
2740
+ };
2204
2741
  declare class WorldSandboxClient {
2205
2742
  private readonly options;
2206
2743
  constructor(options?: WorldsClientOptions);
2207
- open(target: {
2208
- slug: string;
2209
- ref?: string;
2210
- }): Promise<SandboxOpened>;
2744
+ private request;
2745
+ /**
2746
+ * `{ slug, ref? }` opens a READY version; `{ new, from }` opens a sandbox on
2747
+ * a world that does not exist yet (409 `world_exists` if the slug is taken,
2748
+ * 400 naming the shipped templates if `from` is unknown). Its first commit
2749
+ * creates the world on `main`.
2750
+ */
2751
+ open(target: SandboxOpenTarget): Promise<SandboxOpened>;
2211
2752
  status(sandboxId: string): Promise<SandboxSummary>;
2753
+ /** The project's sandboxes, newest first — how an agent finds one it left open. */
2754
+ list(filter?: SandboxListFilter): Promise<SandboxSummary[]>;
2212
2755
  read(sandboxId: string, filePath: string): Promise<{
2213
2756
  path: string;
2214
2757
  size: number;
@@ -2224,11 +2767,196 @@ declare class WorldSandboxClient {
2224
2767
  timeoutMs?: number;
2225
2768
  }): Promise<SandboxExecResult>;
2226
2769
  check(sandboxId: string): Promise<SandboxCheckResult>;
2227
- commit(sandboxId: string, input: {
2228
- message: string;
2229
- branch?: string;
2230
- }): Promise<SandboxCommitResult>;
2231
- close(sandboxId: string): Promise<SandboxSummary>;
2770
+ /** With `rebase`, a moved base is replayed onto; a 409 then names the conflicting paths (`rebaseConflicts`). */
2771
+ commit(sandboxId: string, input: SandboxCommitInput): Promise<SandboxCommitResult>;
2772
+ /**
2773
+ * A rows file already in the sandbox tree into the PLATFORM world the
2774
+ * sandbox was opened on (201 with the version, 202 with the batch to poll,
2775
+ * 400 naming a refused row). Not `commit`: a commit versions the source
2776
+ * tree and never carries data.
2777
+ */
2778
+ importData(sandboxId: string, input: SandboxImportInput): Promise<SandboxImportResult | SandboxImportPending>;
2779
+ /** Uncommitted work is a 409 (`uncommittedPaths`) unless `force` discards it. */
2780
+ close(sandboxId: string, opts?: {
2781
+ force?: boolean;
2782
+ }): Promise<SandboxSummary>;
2783
+ }
2784
+
2785
+ /**
2786
+ * Edit sessions: the version control unit for a world. Every write this
2787
+ * credential makes to a world (push, sandbox commit, data import, MCP, the
2788
+ * console editor) joins ONE open session per world per credential and lands
2789
+ * on that session's private branch; `close` seals the session into a version
2790
+ * on `main`, and a session nobody touches for an hour seals itself. Sessions
2791
+ * replace product-level proposals/PRs: `rollback` undoes a sealed session
2792
+ * (source + data together) as a new, itself-reversible session.
2793
+ *
2794
+ * One client under both `gateway worlds edit …` and `gateway bench edit …`;
2795
+ * the Python twin is `gatewaysdk.benchmark_hub.edit_sessions.WorldEditClient`.
2796
+ */
2797
+ /** Mirrors `WorldEditSessionSchema` (web/features/public-api/types/world-edits.ts). */
2798
+ type EditSessionSummary = {
2799
+ id: string;
2800
+ containerId: string;
2801
+ /** `apikey:<id>` for CLI/sandbox/MCP, `user:<id>` for the console, `agent:<id>` for the platform agent. */
2802
+ actor: string;
2803
+ door: string;
2804
+ status: "open" | "sealing" | "sealed" | "conflict" | "expired" | "discarded" | string;
2805
+ baseVersionId: string | null;
2806
+ tipVersionId: string | null;
2807
+ sealedVersionId: string | null;
2808
+ editCount: number;
2809
+ startedAt: string;
2810
+ lastEditAt: string;
2811
+ expiresAt: string;
2812
+ closedAt: string | null;
2813
+ closeReason: string | null;
2814
+ conflictPaths: string[] | null;
2815
+ rollbackOfId: string | null;
2816
+ message: string | null;
2817
+ };
2818
+ type EditSessionList = {
2819
+ slug: string;
2820
+ containerId: string;
2821
+ /** This credential's open session, or null. */
2822
+ current: EditSessionSummary | null;
2823
+ sessions: EditSessionSummary[];
2824
+ };
2825
+ /** What close/discard/rollback return. */
2826
+ type EditSessionResult = {
2827
+ slug: string;
2828
+ session: EditSessionSummary;
2829
+ };
2830
+ type EditSessionListQuery = {
2831
+ status?: string;
2832
+ limit?: number;
2833
+ };
2834
+ type EditSessionCloseInput = {
2835
+ sessionId?: string;
2836
+ force?: boolean;
2837
+ message?: string;
2838
+ };
2839
+ type EditSessionRollbackInput = {
2840
+ sessionId: string;
2841
+ force?: boolean;
2842
+ message?: string;
2843
+ };
2844
+ declare class WorldEditClient {
2845
+ private readonly options;
2846
+ constructor(options?: WorldsClientOptions);
2847
+ /** The credential's current session and the world's newest-first sessions. */
2848
+ list(slug: string, query?: EditSessionListQuery): Promise<EditSessionList>;
2849
+ /** Seal a session into a version on main (the credential's current one when `sessionId` is omitted). */
2850
+ close(slug: string, input?: EditSessionCloseInput): Promise<EditSessionResult>;
2851
+ /** Drop the session's private branch without making a version. */
2852
+ discard(slug: string, input?: {
2853
+ sessionId?: string;
2854
+ }): Promise<EditSessionResult>;
2855
+ /** Undo a sealed session (source and data) as a new sealed session. */
2856
+ rollback(slug: string, input: EditSessionRollbackInput): Promise<EditSessionResult>;
2857
+ }
2858
+
2859
+ /**
2860
+ * The hosted one-task dry run: `POST /api/public/environments/{id}/dry-run`
2861
+ * and the run-status read that settles it. The runner runs ONE named task of a
2862
+ * harbor tree through harbor's `oracle` (the task's own `solution/solve.sh`)
2863
+ * with the real image rule (`[environment] docker_image` → pull, never build;
2864
+ * else build the Dockerfile). No model, no model key. The run is marked
2865
+ * `kind: "dry-run"` and never counts as a benchmark result.
2866
+ *
2867
+ * The caps are the server's: one task, one example, one rollout, the oracle.
2868
+ * The body carries the task name and, optionally, a pinned versionId; a body
2869
+ * that tries to widen the run (models, task lists, rollouts) is a 400.
2870
+ */
2871
+ declare const DRY_RUN_KIND: "dry-run";
2872
+ declare const DRY_RUN_AGENT: "oracle";
2873
+ type HostedDryRunDispatch = {
2874
+ runId: string;
2875
+ versionId: string;
2876
+ versionLabel: string;
2877
+ containerSlug: string;
2878
+ task: string;
2879
+ kind: typeof DRY_RUN_KIND;
2880
+ agent: typeof DRY_RUN_AGENT;
2881
+ evidence: false;
2882
+ where: "hosted";
2883
+ };
2884
+ /** The image decision the runner took — the SAME rule a real run applies. */
2885
+ type DryRunImageDecision = {
2886
+ source: "prebuilt" | "dockerfile";
2887
+ ref: string | null;
2888
+ };
2889
+ /** What the runner reported about the one trial (the Python twin is `benchmark_hub.dry_run.DryRunSettlement`). */
2890
+ type DryRunSettlement = {
2891
+ task: string;
2892
+ agent: typeof DRY_RUN_AGENT;
2893
+ image: DryRunImageDecision | null;
2894
+ command: string | null;
2895
+ reward: number | null;
2896
+ rewardFile: {
2897
+ name: string;
2898
+ content: unknown;
2899
+ } | null;
2900
+ exitCode: number | null;
2901
+ errorTail: string | null;
2902
+ };
2903
+ type HostedDryRunStatus = {
2904
+ kind: typeof DRY_RUN_KIND;
2905
+ evidence: false;
2906
+ where: "hosted";
2907
+ agent: typeof DRY_RUN_AGENT;
2908
+ task: string | null;
2909
+ evaluationId: string | null;
2910
+ url: string | null;
2911
+ settlement: DryRunSettlement | null;
2912
+ };
2913
+ /** The run-status answer (`GET …/environments/runs/{runId}`) as a dry run reads it. */
2914
+ type HostedDryRunVerdict = {
2915
+ status: string;
2916
+ settled: boolean;
2917
+ progress: {
2918
+ harvested: number;
2919
+ planned: number | null;
2920
+ startedAt: string | null;
2921
+ completedAt: string | null;
2922
+ elapsedSeconds: number | null;
2923
+ } | null;
2924
+ dryRun: HostedDryRunStatus | null;
2925
+ };
2926
+ /** The server blocks a status read for at most this long; longer waits poll. */
2927
+ declare const STATUS_WAIT_CAP_SECONDS = 50;
2928
+ type SettleOptions = {
2929
+ /** Give up (return the last verdict, unsettled) after this long. */
2930
+ timeoutSeconds: number;
2931
+ /** Called once per unsettled poll with the verdict so far. */
2932
+ onProgress?: (verdict: HostedDryRunVerdict) => void;
2933
+ /** Injected for tests: the clock and the pause between empty polls. */
2934
+ now?: () => number;
2935
+ sleep?: (ms: number) => Promise<void>;
2936
+ };
2937
+ /** The client a `gateway benchmarks dry-run --hosted` is built on. */
2938
+ declare class HostedDryRunClient {
2939
+ private readonly options;
2940
+ constructor(options?: WorldsClientOptions);
2941
+ /** Dispatch ONE oracle job for `task` on `containerId` (a container id, not a slug); pins `versionId` when given. */
2942
+ dispatch(target: {
2943
+ containerId: string;
2944
+ task: string;
2945
+ versionId?: string;
2946
+ }): Promise<HostedDryRunDispatch>;
2947
+ /** One status read, blocking server-side for up to `waitSeconds` (capped). */
2948
+ status(runId: string, waitSeconds?: number): Promise<HostedDryRunVerdict>;
2949
+ /** Poll until the run settles or `timeoutSeconds` pass; the last verdict either way. */
2950
+ settle(runId: string, opts: SettleOptions): Promise<HostedDryRunVerdict>;
2951
+ }
2952
+ /** The one exit-code decision, shared by the CLI twins: 0 only when the oracle scored exactly 1.0. */
2953
+ declare class DryRunOutcome {
2954
+ readonly verdict: HostedDryRunVerdict;
2955
+ constructor(verdict: HostedDryRunVerdict);
2956
+ get settlement(): DryRunSettlement | null;
2957
+ /** Why the dry run did not pass, or null when it did. */
2958
+ reason(): string | null;
2959
+ passed(): boolean;
2232
2960
  }
2233
2961
 
2234
2962
  type WorldsClientOptions = {
@@ -2253,14 +2981,27 @@ type DispatchedRun = {
2253
2981
  error?: string;
2254
2982
  };
2255
2983
  /** A platform answer outside 2xx, its status kept so a caller can act on one
2256
- * code (a 409 on a name already taken) instead of parsing the message. */
2984
+ * code (a 409 on a name already taken) instead of parsing the message. A JSON
2985
+ * body renders as `<message> (<code>)` — the stable public `code`, never the
2986
+ * server's error class name. */
2257
2987
  declare class ApiError extends Error {
2258
2988
  readonly status: number;
2259
- constructor(status: number, method: string, path: string, body: string);
2989
+ readonly text: string;
2990
+ readonly code: string | null;
2991
+ constructor(status: number, method: string, path: string, text: string);
2260
2992
  }
2993
+ /** What a client shows for one non-2xx body and the stable code it carries.
2994
+ * Python twin: `gatewaysdk.api_errors.error_detail`. */
2995
+ declare function parseErrorBody(text: string, limit?: number): {
2996
+ detail: string;
2997
+ code: string | null;
2998
+ };
2261
2999
  /** Authenticated JSON request against the platform API — the primitive the
2262
- * worlds helpers and the TS CLI share. */
2263
- declare function apiRequest<T>(options: WorldsClientOptions, method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", path: string, body?: unknown): Promise<T>;
3000
+ * worlds helpers and the TS CLI share. `init.timeoutMs` is the request's own
3001
+ * budget when it legitimately outlasts `GATEWAY_TIMEOUT_MS`. */
3002
+ declare function apiRequest<T>(options: WorldsClientOptions, method: PlatformMethod, path: string, body?: unknown, init?: {
3003
+ timeoutMs?: number;
3004
+ }): Promise<T>;
2264
3005
  /** Set (or rotate) one environment secret — write-only: no API returns it. */
2265
3006
  declare function setEnvSecret(slug: string, key: string, value: string, options?: WorldsClientOptions): Promise<{
2266
3007
  key: string;
@@ -2336,6 +3077,33 @@ type RunReport = {
2336
3077
  /** The read half of dispatch: status, score, per-shard evaluations, and
2337
3078
  * per-task rewards — everything a CI gate needs. */
2338
3079
  declare function getRun(runId: string, options?: WorldsClientOptions): Promise<RunReport>;
3080
+ /** One run as `bench runs list` prints it (GET /benchmark-containers/runs):
3081
+ * the gate's view — no logs, samples or links; `getRun` has those. */
3082
+ type RunSummary = {
3083
+ id: string;
3084
+ status: string;
3085
+ terminal: boolean;
3086
+ score: number | null;
3087
+ summary: string | null;
3088
+ createdAt: string;
3089
+ completedAt: string | null;
3090
+ model: string | null;
3091
+ versionId: string | null;
3092
+ versionLabel: string | null;
3093
+ runConfigId: string | null;
3094
+ runConfigName: string | null;
3095
+ parallelism: number;
3096
+ exitCode: number | null;
3097
+ };
3098
+ type ListRunsFilter = {
3099
+ /** Only runs of this world/benchmark; a slug the project lacks lists nothing. */
3100
+ slug?: string;
3101
+ /** Case-insensitive run status (RUNNING, completed, …). */
3102
+ status?: string;
3103
+ limit?: number;
3104
+ };
3105
+ /** The project's runs, newest first. */
3106
+ declare function listRuns(filter?: ListRunsFilter, options?: WorldsClientOptions): Promise<RunSummary[]>;
2339
3107
  /** Poll a run to terminal (default every 20s, up to `timeoutMinutes`). */
2340
3108
  declare function waitForRun(runId: string, opts?: {
2341
3109
  timeoutMinutes?: number;
@@ -2393,6 +3161,7 @@ declare class WorldSet {
2393
3161
  open(task: WorldTaskRef, opts?: {
2394
3162
  reuseWarm?: boolean;
2395
3163
  surfaces?: WorldSurfaceKind[];
3164
+ browserTier?: BrowserTier;
2396
3165
  }): Promise<WorldSession>;
2397
3166
  /**
2398
3167
  * Start a HOSTED run of a run config against this world — the platform
@@ -2423,4 +3192,4 @@ declare function openWorld(slugRef: string, options?: WorldsClientOptions): Prom
2423
3192
  */
2424
3193
  declare function openWorldVersion(slug: string, versionId: string, options?: WorldsClientOptions): Promise<WorldSet>;
2425
3194
 
2426
- export { ApiError, type BrowserActionEvent, BrowserActionRecorder, type BrowserMode, type BrowserPage, COMPUTER_USE_SPECS, type CreateEvaluationOptions, DEFAULT_BRANCH, DEFAULT_VIEWPORT, type DispatchedRun, EVENT_BATCH_SIZE, EVENT_FLUSH_INTERVAL_MS, EVENT_MAX_RETRIES, type EvalSample, type FinalizeEvaluationOptions, GatewayEvalsClient, type GradeResult, type IngestExplode, type IngestFieldSpec, type IngestMapping, type IngestMode, type IngestOptions, type IngestRefusal, type IngestReport, type IngestSource, type IngestSourceReport, type IngestToolCallsOptions, type IngestToolCallsReport, type LiveTaskSession, type LocalMeta, type MigrateWorldOptions, type ObservationConversion, type ObservationLike, type OpenSessionOptions, type OpenTaskOptions, type ParsedToolCall, type Plaintext, type PlaywrightBrowserLike, type PlaywrightLike, PushSlugConflict, type PushSlugResolution, type RedactMode, type RedactPolicy, type Redaction, type ResolvedWorldVersion, type RunConfigInput, type RunConfigSummary, type RunProvenance, type RunReport, type RunTaskOptions, type RunTaskSummary, STRIP_PREFIX, SURFACE_KINDS, type SandboxChanges, type SandboxCheckResult, type SandboxCommitResult, type SandboxExecResult, type SandboxOpened, type SandboxSummary, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type SlugDeclaration, TRANSFORMS, type TaskExport, type TaskGrade, type TaskManifest, type TaskManifestSession, TaskRun, type TaskRunResult, TaskSessions, type TaskSessionsResponse, type TaskWorldSessionState, type ToolCallRecord, type ToolCallSink, type ToolFunctions, type Transform, type ValidateReport, type ValidatedRun, WHITESPACE, WorldBrowser, type WorldDependency, type WorldDeprecation, type WorldDescription, type WorldEntity, type WorldEntityMapping, type WorldField, type WorldMigrationRefusal, type WorldMigrationReport, type WorldQueryAcrossOptions, type WorldQueryAcrossResult, type WorldQueryCompare, type WorldQueryCompareStatus, type WorldQueryGroup, type WorldQueryOptions, type WorldQueryResult, type WorldQuerySnapshot, type WorldQueryWhere, type WorldRelationship, WorldSandboxClient, WorldSession, type WorldSessionCall, WorldSessionCallError, type WorldSessionState, type WorldSessionTask, WorldSessionTimeout, WorldSet, 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 WorldTaskVersionSummary, type WorldTaskWorld, type WorldTaskWorldValidation, type WorldToolSpec, type WorldToolkit, type WorldsClientOptions, aggregateTaskGrade, apiRequest, applyTransforms, archiveMode, attachManifest, attachSession, attachTask, buildFileManifest, buildSourceTarball, captureToolCalls, collectArchiveRelPaths, computeContentHash, computerUseToolkit, createRef, createTask, deleteEnvSecret, deleteTask, describeWorld, detectProvenance, extractBundle, getRun, getTask, hashForm, ingest, ingestToolCalls, isTaskIdRef, isTaskManifest, isTaskSpec, listEnvSecretKeys, listRunConfigs, listTaskSessions, listTasks, localTreeState, migrateProjectWorlds, migrateWorld, modelToolName, openBrowser, openSession, openTask, openWorld, openWorldVersion, parseSlugRef, parseToolCallRecord, parseTransform, parseWorldTaskRefs, preserveForm, propose, pull, push, pushSlug, pyText, queryRows, queryRowsSearch, readLocalMeta, readToolCallRecords, redactActionArgs, redactionOf, resolveBrowserMode, resolvePushSlug, roundForm, runSessions, runTask, schemaFromSignature, sessionToolObservations, setEnvSecret, shapeText, snapshotTreeHashes, storedForms, surfaceKinds, taskLabel, toolCallRecordsIn, toolCallsFromObservations, uiEntryUrl, uiUrl, updateTask, upsertRunConfig, validateTask, validateWorld, waitForRun, withoutUiToken, writeLocalMeta };
3195
+ export { 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, type CreateEvaluationOptions, DEFAULT_BRANCH, DEFAULT_VIEWPORT, DRY_RUN_AGENT, DRY_RUN_KIND, DetachedPushError, type DispatchedRun, 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, type GradeResult, 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, type ListRunsFilter, type ListSessionsFilter, type LiveTaskSession, type LocalMeta, type MigrateWorldOptions, NO_GRADER_REASON, type ObservationConversion, type ObservationLike, type OpenSessionOptions, type OpenTaskOptions, PLATFORM_TIMEOUT_DEFAULT_MS, PLATFORM_TIMEOUT_ENV, type ParsedToolCall, type Plaintext, type PlatformEndpoint, type PlatformMethod, type PlatformReply, PlatformTransport, type PlaywrightBrowserLike, type PlaywrightLike, PushSlugConflict, type PushSlugResolution, RECOVER_BUDGET_MS, type RebaseConflictPath, type RecoveryResult, type RedactMode, type RedactPolicy, type Redaction, type RepairAnswer, type ResolvedWorldVersion, type RunConfigInput, type RunConfigSummary, type RunProvenance, type RunReport, type RunSetOptions, type RunSetResult, type RunSummary, type RunTaskOptions, type RunTaskSummary, SANDBOX_REQUEST_TIMEOUT_MS, SESSION_STATES, STATUS_WAIT_CAP_SECONDS, STRIP_PREFIX, SURFACE_KINDS, type SandboxChanges, type SandboxCheckResult, type SandboxCommitInput, type SandboxCommitResult, type SandboxExecResult, type SandboxImportInput, type SandboxImportPending, type SandboxImportResult, type SandboxListFilter, type SandboxOpenExisting, type SandboxOpenNew, type SandboxOpenTarget, type SandboxOpened, type SandboxSummary, SecretScrubber, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type SetRunDoc, type SettleOptions, type SlugDeclaration, TRANSFORMS, type TaskExport, type TaskGrade, type TaskManifest, type TaskManifestSession, TaskRun, type TaskRunResult, TaskSessions, type TaskSessionsResponse, type TaskWorldSessionState, type ToolCallRecord, type ToolCallSink, type ToolFunctions, type Transform, TransportCause, UnreachableError, VERIFIER_REWARD_PREFIX, type ValidateReport, type ValidatedRun, type VerifierGrade, WHITESPACE, WorldBrowser, WorldCallTooLarge, type WorldDependency, type WorldDeprecation, type WorldDescription, WorldEditClient, type WorldEntity, type WorldEntityMapping, type WorldField, type WorldMigrationRefusal, type WorldMigrationReport, type WorldQueryAcrossOptions, type WorldQueryAcrossResult, type WorldQueryCompare, type WorldQueryCompareStatus, type WorldQueryGroup, type WorldQueryOptions, type WorldQueryResult, type WorldQuerySnapshot, type WorldQueryWhere, type WorldRelationship, WorldSandboxClient, WorldSession, type WorldSessionCall, WorldSessionCallError, type WorldSessionListItem, type WorldSessionState, type WorldSessionTask, WorldSessionTimeout, WorldSet, 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, type WorldsClientOptions, aggregateTaskGrade, apiRequest, applyTransforms, archiveMode, assertBrowserTier, assertTaskRef, attachManifest, attachSession, attachTask, buildFileManifest, buildSourceTarball, captureToolCalls, checkoutIdentity, closeConnection, collectArchiveRelPaths, computeContentHash, computerUseToolkit, createRef, createTask, deleteEnvSecret, deleteTask, describeWorld, detectProvenance, extractBundle, getRun, getTask, hashForm, idleWarning, ingest, ingestToolCalls, isBrowserGone, isSandboxImportPending, isTaskIdRef, isTaskManifest, isTaskSpec, listEnvSecretKeys, listRunConfigs, listRuns, listSessions, listTaskSessions, listTasks, localTreeState, migrateProjectWorlds, migrateWorld, modelToolName, openBrowser, openSession, openTask, openWorld, openWorldVersion, parseErrorBody, parseSlugRef, parseToolCallRecord, parseTransform, parseWorldTaskRefs, platformTimeoutMs, preserveForm, propose, pull, push, pushBranch, pushSlug, pyText, queryRows, queryRowsSearch, readLocalMeta, readToolCallRecords, rebaseConflicts, redactActionArgs, redactionOf, releaseConnection, resolveBrowserMode, resolvePushSlug, roundForm, runSessions, runSet, runTask, schemaFromSignature, serializeCallBody, sessionToolObservations, setEnvSecret, shapeText, snapshotTreeHashes, storedForms, surfaceKinds, taskLabel, toolCallRecordsIn, toolCallsFromObservations, uiEntryUrl, uiUrl, uncommittedPaths, updateTask, upsertRunConfig, validateTask, validateWorld, waitForRun, withoutUiToken, writeLocalMeta };