@withgateway/sdk 0.1.20 → 0.2.0

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 (130) hide show
  1. package/README.md +141 -2
  2. package/dist/cli.js +8683 -1343
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +8683 -1344
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/index.d.mts +1 -1
  7. package/dist/index.d.ts +1 -1
  8. package/dist/index.js +979 -46
  9. package/dist/index.js.map +1 -1
  10. package/dist/index.mjs +943 -38
  11. package/dist/index.mjs.map +1 -1
  12. package/dist/tracing/index.js +9 -2
  13. package/dist/tracing/index.js.map +1 -1
  14. package/dist/tracing/index.mjs +9 -2
  15. package/dist/tracing/index.mjs.map +1 -1
  16. package/dist/worlds/index.d.mts +738 -28
  17. package/dist/worlds/index.d.ts +738 -28
  18. package/dist/worlds/index.js +940 -42
  19. package/dist/worlds/index.js.map +1 -1
  20. package/dist/worlds/index.mjs +934 -36
  21. package/dist/worlds/index.mjs.map +1 -1
  22. package/package.json +9 -2
  23. package/runtime/gatewaysdk/__init__.py +0 -0
  24. package/runtime/gatewaysdk/environment/__init__.py +108 -0
  25. package/runtime/gatewaysdk/environment/_bundle.py +281 -0
  26. package/runtime/gatewaysdk/environment/_harbor.py +276 -0
  27. package/runtime/gatewaysdk/environment/_materialize.py +97 -0
  28. package/runtime/gatewaysdk/environment/_tar.py +33 -0
  29. package/runtime/gatewaysdk/environment/_world.py +346 -0
  30. package/runtime/gatewaysdk/environment/core.py +527 -0
  31. package/runtime/gatewaysdk/environment/errors.py +58 -0
  32. package/runtime/gatewaysdk/environment/runtime.py +150 -0
  33. package/runtime/gatewaysdk/environment/schema/__init__.py +35 -0
  34. package/runtime/gatewaysdk/environment/schema/__main__.py +225 -0
  35. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +116 -0
  36. package/runtime/gatewaysdk/environment/schema/_slack_scenario.py +183 -0
  37. package/runtime/gatewaysdk/environment/schema/api.py +1628 -0
  38. package/runtime/gatewaysdk/environment/schema/batch.py +755 -0
  39. package/runtime/gatewaysdk/environment/schema/compiler.py +615 -0
  40. package/runtime/gatewaysdk/environment/schema/conform.py +428 -0
  41. package/runtime/gatewaysdk/environment/schema/connector.py +777 -0
  42. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/handlers.py +17 -0
  43. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/parity.json +28 -0
  44. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/provenance.json +233 -0
  45. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/scope.toml +112 -0
  46. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/world.json +1380 -0
  47. package/runtime/gatewaysdk/environment/schema/connectors/base.json +28 -0
  48. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +18 -0
  49. package/runtime/gatewaysdk/environment/schema/connectors/custom/world.json +123 -0
  50. package/runtime/gatewaysdk/environment/schema/connectors/github/handlers.py +81 -0
  51. package/runtime/gatewaysdk/environment/schema/connectors/github/parity.json +37 -0
  52. package/runtime/gatewaysdk/environment/schema/connectors/github/provenance.json +134 -0
  53. package/runtime/gatewaysdk/environment/schema/connectors/github/scope.toml +158 -0
  54. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +5869 -0
  55. package/runtime/gatewaysdk/environment/schema/connectors/google-calendar/handlers.py +23 -0
  56. package/runtime/gatewaysdk/environment/schema/connectors/google-calendar/world.json +209 -0
  57. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/handlers.py +18 -0
  58. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/world.json +286 -0
  59. package/runtime/gatewaysdk/environment/schema/connectors/jamf/handlers.py +34 -0
  60. package/runtime/gatewaysdk/environment/schema/connectors/jamf/parity.json +49 -0
  61. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +181 -0
  62. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +128 -0
  63. package/runtime/gatewaysdk/environment/schema/connectors/jamf/world.json +2218 -0
  64. package/runtime/gatewaysdk/environment/schema/connectors/jira/handlers.py +28 -0
  65. package/runtime/gatewaysdk/environment/schema/connectors/jira/world.json +389 -0
  66. package/runtime/gatewaysdk/environment/schema/connectors/kandji/handlers.py +38 -0
  67. package/runtime/gatewaysdk/environment/schema/connectors/kandji/parity.json +29 -0
  68. package/runtime/gatewaysdk/environment/schema/connectors/kandji/provenance.json +152 -0
  69. package/runtime/gatewaysdk/environment/schema/connectors/kandji/scope.toml +120 -0
  70. package/runtime/gatewaysdk/environment/schema/connectors/kandji/world.json +765 -0
  71. package/runtime/gatewaysdk/environment/schema/connectors/linear/handlers.py +20 -0
  72. package/runtime/gatewaysdk/environment/schema/connectors/linear/world.json +363 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/fidelity.json +45 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/handlers.py +1 -0
  75. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/provenance.json +851 -0
  76. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/scope.md +231 -0
  77. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/teams-types.json +1710 -0
  78. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/world.json +858 -0
  79. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/handlers.py +32 -0
  80. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/parity.json +50 -0
  81. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/provenance.json +137 -0
  82. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/scope.toml +78 -0
  83. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/world.json +16243 -0
  84. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/handlers.py +806 -0
  85. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/parity.json +46 -0
  86. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/provenance.json +143 -0
  87. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/scope.toml +174 -0
  88. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/world.json +4695 -0
  89. package/runtime/gatewaysdk/environment/schema/connectors/slack/MODEL.md +236 -0
  90. package/runtime/gatewaysdk/environment/schema/connectors/slack/capabilities.json +1039 -0
  91. package/runtime/gatewaysdk/environment/schema/connectors/slack/handlers.py +762 -0
  92. package/runtime/gatewaysdk/environment/schema/connectors/slack/parity.json +65 -0
  93. package/runtime/gatewaysdk/environment/schema/connectors/slack/provenance.json +294 -0
  94. package/runtime/gatewaysdk/environment/schema/connectors/slack/scope.toml +44 -0
  95. package/runtime/gatewaysdk/environment/schema/connectors/slack/world.json +4993 -0
  96. package/runtime/gatewaysdk/environment/schema/connectors/workday/handlers.py +75 -0
  97. package/runtime/gatewaysdk/environment/schema/connectors/workday/parity.json +36 -0
  98. package/runtime/gatewaysdk/environment/schema/connectors/workday/provenance.json +179 -0
  99. package/runtime/gatewaysdk/environment/schema/connectors/workday/scope.toml +180 -0
  100. package/runtime/gatewaysdk/environment/schema/connectors/workday/world.json +806 -0
  101. package/runtime/gatewaysdk/environment/schema/data.py +593 -0
  102. package/runtime/gatewaysdk/environment/schema/extract.py +263 -0
  103. package/runtime/gatewaysdk/environment/schema/host.py +2407 -0
  104. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +275 -0
  105. package/runtime/gatewaysdk/environment/schema/platform.py +1272 -0
  106. package/runtime/gatewaysdk/environment/schema/scaffold.py +250 -0
  107. package/runtime/gatewaysdk/environment/schema/skill.py +118 -0
  108. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +202 -0
  109. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +331 -0
  110. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONVENTIONS.md +100 -0
  111. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +313 -0
  112. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +223 -0
  113. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +293 -0
  114. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +390 -0
  115. package/runtime/gatewaysdk/environment/schema/slack.py +757 -0
  116. package/runtime/gatewaysdk/environment/schema/snapshot.py +479 -0
  117. package/runtime/gatewaysdk/environment/schema/store.py +904 -0
  118. package/runtime/gatewaysdk/environment/schema/tasks.py +525 -0
  119. package/runtime/gatewaysdk/environment/schema/tools_world.py +322 -0
  120. package/runtime/gatewaysdk/environment/schema/validation.py +577 -0
  121. package/runtime/gatewaysdk/environment/schema/worker.py +78 -0
  122. package/runtime/gatewaysdk/environment/schema/workers.py +500 -0
  123. package/runtime/gatewaysdk/environment/schema/world_tests.py +336 -0
  124. package/skills/agents/connector-template-author.md +202 -0
  125. package/skills/connector-schema-authoring/CONNECTORS.md +331 -0
  126. package/skills/connector-schema-authoring/CONVENTIONS.md +100 -0
  127. package/skills/connector-schema-authoring/SKILL.md +313 -0
  128. package/skills/world-data-ingestion/ROWS.md +223 -0
  129. package/skills/world-data-ingestion/SKILL.md +293 -0
  130. package/skills/worlds-getting-started/SKILL.md +390 -0
@@ -1,3 +1,115 @@
1
+ /**
2
+ * STORED WORLD TASKS: a task spec kept by the project, outside any bundle.
3
+ *
4
+ * An inline task (`openSession(world, { task: { instruction, … } })`) belongs
5
+ * to one session. A stored task is the same spec as a named, versioned
6
+ * project resource: create it once, open as many sessions on it as you like
7
+ * with `{ task: { id } }`, and every grade attributes back to the task and
8
+ * its version. Updating the spec never rewrites history — it appends a
9
+ * version, and a session opened on `{ id, version: 2 }` keeps running v2
10
+ * after v3 exists.
11
+ *
12
+ * const task = await createTask({
13
+ * name: "refund-late-invoice",
14
+ * world: "acme-billing",
15
+ * spec: { instruction: "…", seed: {…}, grader: {…} },
16
+ * });
17
+ * const session = await openSession("acme-billing", { task: { id: task.id } });
18
+ *
19
+ * Tasks are project-scoped: another project's task id is not found (404),
20
+ * never forbidden. `world` pins a task to one world's slug (validated against
21
+ * that world's contract); null leaves it usable with any world.
22
+ */
23
+ type WorldTaskSummary = {
24
+ id: string;
25
+ name: string;
26
+ world: string | null;
27
+ version: number;
28
+ hash: string;
29
+ spec: WorldTaskSpec;
30
+ createdAt: string;
31
+ updatedAt: string;
32
+ createdBy: string;
33
+ updatedBy: string;
34
+ };
35
+ type WorldTaskVersionSummary = {
36
+ version: number;
37
+ hash: string;
38
+ createdAt: string;
39
+ createdBy: string;
40
+ message: string | null;
41
+ };
42
+ type WorldTaskDetail = WorldTaskSummary & {
43
+ versions: WorldTaskVersionSummary[];
44
+ };
45
+ type WorldTaskPage = {
46
+ tasks: WorldTaskSummary[];
47
+ meta: {
48
+ page: number;
49
+ limit: number;
50
+ totalItems: number;
51
+ totalPages: number;
52
+ };
53
+ };
54
+ type WorldTaskValidation = {
55
+ taskId: string;
56
+ version: number;
57
+ /** The world version the task was checked against. */
58
+ versionId: string;
59
+ ok: boolean;
60
+ /** `entities` when the world's contract was read and every seed and check
61
+ * entity was matched against it; `none` when the version has no contract
62
+ * to check (a mock-tools world), in which case `ok` says only that the
63
+ * version exists and is READY. */
64
+ checked: "entities" | "none";
65
+ problems: string[];
66
+ entities: string[] | null;
67
+ };
68
+ /** Store a task. `name` defaults to `spec.name`; one of the two is needed. */
69
+ declare function createTask(input: {
70
+ spec: WorldTaskSpec;
71
+ name?: string;
72
+ world?: string | null;
73
+ message?: string;
74
+ }, options?: WorldsClientOptions): Promise<WorldTaskSummary>;
75
+ /** Change a task. A new `spec` becomes the next version (the old ones stay
76
+ * readable and openable); `name` and `world` change in place. */
77
+ declare function updateTask(taskId: string, input: {
78
+ spec?: WorldTaskSpec;
79
+ name?: string;
80
+ world?: string | null;
81
+ message?: string;
82
+ }, options?: WorldsClientOptions): Promise<WorldTaskSummary>;
83
+ /** The project's tasks, newest change first. `world` keeps only tasks
84
+ * pinned to that slug; `metadata` keeps tasks whose spec metadata carries
85
+ * every given key/value (`{ externalUserId: "u_42" }`). */
86
+ declare function listTasks(filter?: {
87
+ world?: string;
88
+ metadata?: Record<string, string>;
89
+ page?: number;
90
+ limit?: number;
91
+ }, options?: WorldsClientOptions): Promise<WorldTaskPage>;
92
+ /** One task with its version history; `version` reads that version's spec
93
+ * instead of the current one. */
94
+ declare function getTask(taskId: string, opts?: {
95
+ version?: number;
96
+ }, options?: WorldsClientOptions): Promise<WorldTaskDetail>;
97
+ /** Remove a task and every version. Sessions already opened on it keep
98
+ * their copy of the spec. */
99
+ declare function deleteTask(taskId: string, options?: WorldsClientOptions): Promise<{
100
+ id: string;
101
+ name: string;
102
+ }>;
103
+ /** Check a task against a world version without opening a session: every
104
+ * seed entity and every check's entity must exist in the world's contract.
105
+ * `slug` checks against that world's head, `versionId` against an exact
106
+ * version, neither against the task's own `world` pin. */
107
+ declare function validateTask(taskId: string, target?: {
108
+ version?: number;
109
+ slug?: string;
110
+ versionId?: string;
111
+ }, options?: WorldsClientOptions): Promise<WorldTaskValidation>;
112
+
1
113
  /**
2
114
  * LIVE WORLD SESSIONS from TypeScript: your agent, the platform's container.
3
115
  *
@@ -12,12 +124,27 @@
12
124
  * stays where it is — this file is just the wire.
13
125
  *
14
126
  * const world = await openWorld("revenue-ops-sim@main");
15
- * const session = await openSession(world.slug, "revops-mara-dedupe-contacts");
127
+ * const session = await openSession(world.slug, { task: "revops-mara-dedupe-contacts" });
16
128
  * await session.ready(); // wait for the container
17
129
  * await session.call("crm_search", { entity: "deals" });
18
130
  * const { reward, rewards } = await session.grade();
19
131
  * await session.close({ keepWarm: true }); // hand it back to the pool
20
132
  *
133
+ * The task can also be YOURS rather than the bundle's — an instruction, the
134
+ * rows the session starts with and how it is graded, for one end user:
135
+ *
136
+ * const session = await openSession("acme-billing@main", {
137
+ * task: {
138
+ * instruction: "Mark invoice INV-7 as paid.",
139
+ * seed: { rows: { invoices: [{ id: "INV-7", status: "open" }] } },
140
+ * grader: { kind: "assertions", checks: [
141
+ * { entity: "invoices", where: { id: "INV-7", status: "paid" } },
142
+ * ] },
143
+ * metadata: { externalUserId: "u_42" },
144
+ * },
145
+ * surfaces: ["api"],
146
+ * });
147
+ *
21
148
  * Every call is a row on the platform before it is an effect in a container,
22
149
  * so the episode is on the record — and the platform traces the session
23
150
  * itself, which is why these sessions show up under Sessions without the
@@ -28,6 +155,7 @@ type WorldToolSpec = {
28
155
  /** The world's own signature, e.g. `crm_search(q=None, entity="deals")`. */
29
156
  signature: string;
30
157
  doc: string | null;
158
+ inputSchema?: Record<string, unknown>;
31
159
  };
32
160
  /** What a model needs to call a world: the schemas to advertise, and the
33
161
  * implementations that run them in the container. */
@@ -45,6 +173,132 @@ type WorldToolkit = {
45
173
  impls: Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
46
174
  specs: WorldToolSpec[];
47
175
  };
176
+ /** A JSON scalar: what `where` filters and field predicates compare against. */
177
+ type WorldTaskScalar = string | number | boolean | null;
178
+ /** The rows a task starts the session with — the `seed()` contract, applied
179
+ * by the host right after it clones the version's snapshot. `append`
180
+ * (default) upserts by primary key onto the base data; `replace` makes the
181
+ * named entities hold exactly these rows. */
182
+ type WorldTaskSeed = {
183
+ mode?: "append" | "replace";
184
+ rows: Record<string, Record<string, unknown>[]>;
185
+ };
186
+ type WorldTaskFieldOp = "eq" | "neq" | "in" | "gt" | "gte" | "lt" | "lte" | "contains";
187
+ /**
188
+ * One declarative check over the session's final rows. `where` selects rows
189
+ * of `entity` by equality (dotted paths reach into nested objects); the
190
+ * assertion says what must hold of the selection:
191
+ *
192
+ * exists (default) / absent at least one row / none
193
+ * count `count` bound on how many
194
+ * all / any `field op value` on every / some selected row
195
+ *
196
+ * A check's `id` names its entry in `rewards`; the task's reward is the
197
+ * weighted share of checks that passed.
198
+ */
199
+ type WorldTaskCheck = {
200
+ id?: string;
201
+ weight?: number;
202
+ entity: string;
203
+ where?: Record<string, WorldTaskScalar>;
204
+ assert?: "exists" | "absent" | "count" | "all" | "any";
205
+ count?: {
206
+ eq?: number;
207
+ gte?: number;
208
+ lte?: number;
209
+ };
210
+ field?: string;
211
+ op?: WorldTaskFieldOp;
212
+ value?: WorldTaskScalar | WorldTaskScalar[];
213
+ };
214
+ /** One thing a rubric judge scores in [0, 1]; `id` names its entry in
215
+ * `rewards`, `weight` (default 1) its share of the task's reward. */
216
+ type WorldTaskRubricCriterion = {
217
+ id: string;
218
+ description: string;
219
+ weight?: number;
220
+ };
221
+ /** A rubric is prose: what a good outcome looks like. The platform (never the
222
+ * host) has a model read the session's final state and its call log against
223
+ * it; the project's default evaluation model judges unless `model` pins one.
224
+ * `grade()` then resolves asynchronously — `pending: true` first, the reward
225
+ * once the judge has answered. */
226
+ type WorldTaskRubricGrader = {
227
+ kind: "rubric";
228
+ rubric: string;
229
+ criteria?: WorldTaskRubricCriterion[];
230
+ model?: {
231
+ provider: string;
232
+ model: string;
233
+ };
234
+ };
235
+ /** How a task is graded: checks the host evaluates in-process, a `verify.py`
236
+ * body (state JSON on stdin, last stdout line `{reward, ...}`) run through the
237
+ * host's confined verifier, or a rubric judged by a model on the platform. */
238
+ type WorldTaskGrader = {
239
+ kind: "assertions";
240
+ checks: WorldTaskCheck[];
241
+ } | {
242
+ kind: "python";
243
+ source: string;
244
+ timeoutSeconds?: number;
245
+ } | WorldTaskRubricGrader;
246
+ /** A task supplied at open, for one session, instead of a bundled scenario.
247
+ * `instruction` is what the agent is told; without `seed` the session starts
248
+ * on the version's base data, without `grader` `grade()` answers
249
+ * `reward: null`; `tools` is the allow-list of the version's tools the agent
250
+ * may call in this session (unset: all of them; a call outside it is refused
251
+ * and logged); `metadata` is yours (an end-user id, a ticket) and is echoed
252
+ * on the session, never read. Limits: shared/domain/worldTasks.ts. */
253
+ type WorldTaskSpec = {
254
+ name?: string;
255
+ instruction: string;
256
+ seed?: WorldTaskSeed;
257
+ grader?: WorldTaskGrader;
258
+ tools?: string[];
259
+ metadata?: Record<string, unknown>;
260
+ };
261
+ /** A stored task of the project (see worlds/tasks.ts), opened by id; the
262
+ * session runs a copy of one version's spec — the current one by default. */
263
+ type WorldTaskIdRef = {
264
+ id: string;
265
+ version?: number;
266
+ };
267
+ /** What `openSession` takes as the task: a bundled scenario's name, a
268
+ * stored task's `{ id, version? }`, or an inline spec. */
269
+ type WorldTaskRef = string | WorldTaskIdRef | WorldTaskSpec;
270
+ /** What a session's task is, on every session response. `hash` is the
271
+ * content hash of the spec (inline or stored) — what warm reuse matches on;
272
+ * `id`/`version` name the stored task the session was opened on. */
273
+ type WorldSessionTask = {
274
+ source: "bundled" | "inline" | "stored";
275
+ name: string | null;
276
+ hash: string | null;
277
+ id?: string | null;
278
+ version?: number | null;
279
+ metadata: Record<string, unknown>;
280
+ };
281
+ declare const isTaskIdRef: (task: WorldTaskRef) => task is WorldTaskIdRef;
282
+ declare const isTaskSpec: (task: WorldTaskRef) => task is WorldTaskSpec;
283
+ /** The label a task goes by in results: its name, `inline:<hash>` for an
284
+ * unnamed inline task once the platform has hashed it, or the stored task's
285
+ * name (its id until the platform has answered). */
286
+ declare const taskLabel: (task: WorldTaskRef, info?: WorldSessionTask | null) => string;
287
+ type SeedResult = {
288
+ seeded: number;
289
+ mode: "append" | "replace";
290
+ entity_counts: Record<string, number>;
291
+ };
292
+ /** One row of the session's call log. */
293
+ type WorldSessionCall = {
294
+ seq: number;
295
+ kind: string;
296
+ tool: string | null;
297
+ args: unknown;
298
+ result: unknown;
299
+ error: string | null;
300
+ completedAt: string | null;
301
+ };
48
302
  type WorldSessionState = {
49
303
  sessionId: string;
50
304
  state: string;
@@ -52,11 +306,16 @@ type WorldSessionState = {
52
306
  versionId: string;
53
307
  contentHash: string;
54
308
  taskName: string | null;
309
+ /** Where the task came from and what it is; absent on platforms that
310
+ * predate session tasks, in which case it is derived from `taskName`. */
311
+ task?: WorldSessionTask;
55
312
  /** The task's objective — present when the session was opened (not on a
56
313
  * bare status read), so a client never needs the bundle on disk. */
57
314
  instruction?: string | null;
58
315
  /** The tools this task serves. */
59
316
  tools?: WorldToolSpec[];
317
+ /** Where the session answers besides `tools` — see worlds/browser.ts. */
318
+ surfaces?: SessionSurfaces;
60
319
  };
61
320
  type GradeResult = {
62
321
  reward: number | null;
@@ -87,13 +346,55 @@ declare class WorldSessionCallError extends Error {
87
346
  }
88
347
  declare class WorldSession {
89
348
  readonly sessionId: string;
90
- private state;
349
+ private current;
91
350
  private readonly options;
92
- constructor(sessionId: string, state: WorldSessionState, options: WorldsClientOptions);
351
+ constructor(sessionId: string, current: WorldSessionState, options: WorldsClientOptions);
352
+ /** The task's display name: a bundled scenario's, or the inline spec's
353
+ * `name` (null when the spec was unnamed). Same as `taskName`. */
93
354
  get task(): string | null;
94
- /** What this task asks for — the bundle's own instruction.md. */
355
+ /** The task's display name: a bundled scenario's, or the inline spec's
356
+ * `name` (null when the spec was unnamed). */
357
+ get taskName(): string | null;
358
+ /** The task this session runs: bundled scenario, stored task or inline
359
+ * spec, its name, hash and the caller's metadata. */
360
+ get taskInfo(): WorldSessionTask;
361
+ /** What this task asks for — the bundle's instruction.md, or the inline
362
+ * spec's `instruction`. */
95
363
  get instruction(): string | null;
96
364
  get versionId(): string;
365
+ /** Whether the session answered ready as of the last state read (the open,
366
+ * a `status()`, or the poll inside `ready()`); no request is made. */
367
+ get isReady(): boolean;
368
+ /** `api` / `ui` / `browser` are present exactly when the world declares
369
+ * them AND the session was opened asking for them. */
370
+ surfaces(): Promise<SessionSurfaces>;
371
+ /** Base URL of the world's own HTTP API for this session. */
372
+ api(): Promise<string>;
373
+ /** Headers every request to `api()` needs. A World Host session gates its
374
+ * api surface on a per-session token; a pod or hosted twin answers with the
375
+ * world's own declared auth and this is `{}`. */
376
+ apiHeaders(): Promise<Record<string, string>>;
377
+ /** URL of the world's UI entry page for this session. */
378
+ ui(): Promise<string>;
379
+ /** A Playwright browser on this session's UI: `hosted` drives the one the
380
+ * platform runs next to the world, `local` launches one here, `auto`
381
+ * prefers hosted. Call `close()` when done.
382
+ *
383
+ * Every action is reported to the platform under `agentId` (default:
384
+ * `GATEWAY_AGENT_ID` or a fresh `agent-<hex>`) so the session page shows
385
+ * this agent's own timeline — several agents may share one session and
386
+ * one hosted browser. `record: false` opts out. */
387
+ browser(opts?: {
388
+ mode?: BrowserMode;
389
+ headless?: boolean;
390
+ playwright?: PlaywrightLike;
391
+ agentId?: string;
392
+ record?: boolean;
393
+ }): Promise<WorldBrowser>;
394
+ /** The reporter `browser()` uses; exposed for a page you drive yourself. */
395
+ browserRecorder(agentId?: string): BrowserActionRecorder;
396
+ /** Browser actions as model tools, in the same shape as `toolkit()`. */
397
+ computerUseTools(browser: WorldBrowser): WorldToolkit;
97
398
  /** The session's latest platform state (one request, no waiting). */
98
399
  status(): Promise<WorldSessionState>;
99
400
  /**
@@ -126,10 +427,57 @@ declare class WorldSession {
126
427
  * hand-written map that still remembers the old name.
127
428
  */
128
429
  toolkit(): Promise<WorldToolkit>;
129
- /** Run the task's grader against the container's END STATE. */
430
+ /** Run the task's grader against the container's END STATE. Graders answer
431
+ * in one of two shapes: the scalar with named rewards beside it
432
+ * (`{reward, check_a, check_b}`, a task's own `grade.py`), or the named
433
+ * rewards nested under `rewards` (the api, mock-tools and World Host
434
+ * runners). Both land in `rewards`.
435
+ *
436
+ * A rubric grade is finalized by the platform's judge, not the container:
437
+ * the platform answers the enqueue with `pending: true`, and this waits on
438
+ * the judge's budget (15 min) instead of a call's. `timeoutMs` overrides
439
+ * either. */
130
440
  grade(opts?: {
131
441
  timeoutMs?: number;
132
442
  }): Promise<GradeResult>;
443
+ /**
444
+ * Put rows into the LIVE world through its contract, in one batch:
445
+ * `append` (default) upserts by primary key, `replace` makes the named
446
+ * entities hold exactly these rows. Atomic — a refused row leaves the
447
+ * session unchanged and the error names the entity, row and field.
448
+ */
449
+ seed(rows: Record<string, Record<string, unknown>[]>, opts?: {
450
+ mode?: "append" | "replace";
451
+ timeoutMs?: number;
452
+ }): Promise<SeedResult>;
453
+ /** Every entity's rows as the world holds them now — the same dump a
454
+ * grader reads. The shape is the world runtime's: a schema world answers
455
+ * `{<entity>: {<key>: row}, snapshot}`, a mock-tools world
456
+ * `{entities: {<entity>: [row]}}`. */
457
+ state(opts?: {
458
+ timeoutMs?: number;
459
+ }): Promise<unknown>;
460
+ /** Back to the opening state: the version's data plus the bundled
461
+ * scenario's or the inline task's seed. Rows written since are gone; the
462
+ * call log stays. */
463
+ reset(opts?: {
464
+ timeoutMs?: number;
465
+ }): Promise<void>;
466
+ /** The session's call log, oldest first: every tool call, seed, reset,
467
+ * grade with its result — the record of the episode. */
468
+ export(): Promise<WorldSessionCall[]>;
469
+ /**
470
+ * Promote this session's inline task into a stored task of the project
471
+ * (version 1, pinned to the session's world unless `world` says otherwise),
472
+ * so a task written for one end user can be reused and its grades
473
+ * compared. The session then records the new task's id. A session on a
474
+ * bundled task has nothing to save; one on a stored task is already saved.
475
+ */
476
+ saveTask(opts?: {
477
+ name?: string;
478
+ world?: string | null;
479
+ message?: string;
480
+ }): Promise<WorldTaskSummary>;
133
481
  /**
134
482
  * End the session. `keepWarm` hands the container back to the pool instead
135
483
  * of tearing it down, so the next session for the same task starts warm —
@@ -147,16 +495,29 @@ declare class WorldSession {
147
495
  * self-hosted install, a session opened by CI and handed to a developer).
148
496
  */
149
497
  declare function attachSession(sessionId: string, options?: WorldsClientOptions): Promise<WorldSession>;
498
+ type OpenSessionOptions = {
499
+ versionId?: string;
500
+ reuseWarm?: boolean;
501
+ /** More than `tools`: `["api"]`, `["ui"]`, `["browser"]`. The platform
502
+ * refuses (HTTP 400) rather than quietly serving less than asked. */
503
+ surfaces?: WorldSurfaceKind[];
504
+ options?: WorldsClientOptions;
505
+ };
150
506
  /**
151
507
  * Open a live session against one task of a world. Returns as soon as the
152
508
  * platform has accepted it — call `ready()` to wait for the container.
509
+ *
510
+ * `task` is a bundled scenario's name, a stored task's `{ id, version? }`
511
+ * or an inline `WorldTaskSpec` (the latter two need a host engine world — the
512
+ * platform answers 400 for a pod world). The older positional form
513
+ * `openSession(slug, "task-name", opts)` still works.
153
514
  */
154
- declare function openSession(slugOrRef: string, task: string, opts?: {
155
- versionId?: string;
156
- reuseWarm?: boolean;
157
- options?: WorldsClientOptions;
515
+ declare function openSession(slugOrRef: string, task: OpenSessionOptions & {
516
+ task: WorldTaskRef;
158
517
  }): Promise<WorldSession>;
518
+ declare function openSession(slugOrRef: string, task: WorldTaskRef, opts?: OpenSessionOptions): Promise<WorldSession>;
159
519
  type SessionRunResult = {
520
+ /** The task's name, or `inline:<hash>` for an unnamed inline task. */
160
521
  task: string;
161
522
  sessionId: string;
162
523
  reward: number | null;
@@ -195,7 +556,9 @@ type SessionRunReport = {
195
556
  */
196
557
  declare function runSessions(opts: {
197
558
  world: string;
198
- tasks?: string[];
559
+ /** Bundled task names, stored task refs and/or inline task specs
560
+ * (default: every bundled task in the world). */
561
+ tasks?: WorldTaskRef[];
199
562
  concurrency?: number;
200
563
  failUnder?: number;
201
564
  /** Pin every session to one version (default: the world's head). */
@@ -206,12 +569,334 @@ declare function runSessions(opts: {
206
569
  session: WorldSession;
207
570
  toolkit: WorldToolkit;
208
571
  instruction: string;
572
+ /** The task's label — see `SessionRunResult.task`. */
209
573
  task: string;
574
+ /** The task as it was given: a bundled name, a stored ref or the
575
+ * inline spec. */
576
+ taskRef: WorldTaskRef;
210
577
  }) => Promise<unknown>;
211
578
  onResult?: (result: SessionRunResult) => void;
212
579
  options?: WorldsClientOptions;
213
580
  }): Promise<SessionRunReport>;
214
581
 
582
+ /**
583
+ * A BROWSER ON A WORLD'S UI — the computer-use half of a live session.
584
+ *
585
+ * A session answers on SURFACES. `tools` is always there (the world's own
586
+ * operations over the rendezvous). An api-type world may also answer on
587
+ * `api` (the service itself), `ui` (its dashboard, over the same state) and
588
+ * `browser` — a headless Chromium the platform runs NEXT TO that UI, which
589
+ * an agent drives through Playwright. This file is the TS client for the
590
+ * last two, call for call with `gatewaysdk/world_browser.py`.
591
+ *
592
+ * const s = await openSession("payments-like", "refund-dispute", {
593
+ * surfaces: ["ui", "browser"],
594
+ * });
595
+ * await s.ready();
596
+ * const b = await s.browser(); // hosted, next to the world
597
+ * await b.goto(); // the UI's entry page
598
+ * await b.click("text=Refund");
599
+ * const tools = computerUseToolkit(b); // the same actions as model tools
600
+ * await b.close();
601
+ *
602
+ * Playwright is an OPTIONAL peer: nothing here imports it until a browser is
603
+ * opened, so sessions that never touch a UI never load it.
604
+ *
605
+ * MODES. `hosted` connects to the session's own browser (a Playwright server
606
+ * the pod exposes over an authenticated websocket). `local` launches Chromium
607
+ * on this machine and points it at the UI — a laptop against a hosted twin,
608
+ * or a test. `auto` prefers hosted. Asking for a mode the session cannot
609
+ * serve throws `WorldSurfaceUnavailable`; there is no silent fallback to a
610
+ * browser other than the one the episode is judged on.
611
+ *
612
+ * OBSERVABILITY. Every action a `WorldBrowser` takes (goto, click, type,
613
+ * press, scroll, back) is reported to the platform as one event — what was
614
+ * done, whether it worked, where the page ended up, and a JPEG of the screen
615
+ * after — through a `BrowserActionRecorder`. Reporting is fire-and-forget
616
+ * and never fails the action; the platform renders it as the session's
617
+ * browser timeline. Text typed into secret-looking fields is redacted before
618
+ * it leaves the process.
619
+ */
620
+ declare const SURFACE_KINDS: readonly ["tools", "api", "ui", "browser"];
621
+ type WorldSurfaceKind = (typeof SURFACE_KINDS)[number];
622
+ declare const DEFAULT_VIEWPORT: {
623
+ width: number;
624
+ height: number;
625
+ };
626
+ declare const EVENT_BATCH_SIZE = 10;
627
+ declare const EVENT_FLUSH_INTERVAL_MS = 1000;
628
+ declare const EVENT_MAX_RETRIES = 3;
629
+ /** The `surfaces` block of a session descriptor, as the platform sends it. */
630
+ type SessionSurfaces = {
631
+ tools: {
632
+ kind: "rendezvous";
633
+ };
634
+ api?: {
635
+ url: string;
636
+ /** Per-session credential of a World Host session: send it as
637
+ * `Authorization: Bearer <token>` (the header only; a token in the URL is
638
+ * refused). Absent when the world
639
+ * itself answers with its declared auth (a pod or a customer-hosted twin). */
640
+ token?: string;
641
+ };
642
+ ui?: {
643
+ url: string;
644
+ entry: string;
645
+ /** Same-origin prefix the UI proxies to the world API, e.g. `/__world-api`;
646
+ * null when the UI only reaches the API server-side. */
647
+ apiPath?: string | null;
648
+ /** Per-session credential of a World Host UI. A browser navigation cannot
649
+ * carry a header, so the first page load presents it once as `?token=`
650
+ * and the host answers with an HttpOnly cookie. Absent for pod UIs. */
651
+ token?: string;
652
+ };
653
+ browser?: {
654
+ wsUrl: string;
655
+ /** `cdp`: the platform's Chromium relay (any number of agents share one
656
+ * browser, each in its own context). `playwright`: a `run-server` endpoint. */
657
+ protocol: "cdp" | "playwright";
658
+ viewport: {
659
+ width: number;
660
+ height: number;
661
+ };
662
+ };
663
+ };
664
+ declare class WorldSurfaceUnavailable extends Error {
665
+ readonly surface: WorldSurfaceKind;
666
+ constructor(surface: WorldSurfaceKind, reason: string);
667
+ }
668
+ declare function surfaceKinds(s: SessionSurfaces): WorldSurfaceKind[];
669
+ /** The URL of `path` on a UI surface, carrying the session token when the
670
+ * surface has one. `path` may already have a query string; the token is
671
+ * appended to it. */
672
+ declare function uiUrl(ui: NonNullable<SessionSurfaces["ui"]>, path: string): string;
673
+ declare function uiEntryUrl(ui: NonNullable<SessionSurfaces["ui"]>): string;
674
+ /** `url` without its `token` query parameter: what may be logged or shown. */
675
+ declare function withoutUiToken(url: string): string;
676
+ /** The slice of a Playwright `Page` this module drives. */
677
+ type BrowserPage = {
678
+ url(): string;
679
+ goto(url: string, opts?: {
680
+ waitUntil?: "load";
681
+ }): Promise<unknown>;
682
+ click(selector: string): Promise<void>;
683
+ fill(selector: string, value: string): Promise<void>;
684
+ screenshot(opts?: {
685
+ type?: "png" | "jpeg";
686
+ quality?: number;
687
+ fullPage?: boolean;
688
+ }): Promise<Buffer>;
689
+ innerText(selector: string): Promise<string>;
690
+ content(): Promise<string>;
691
+ goBack(opts?: {
692
+ waitUntil?: "load";
693
+ }): Promise<unknown>;
694
+ waitForLoadState(state?: "load"): Promise<void>;
695
+ waitForTimeout(ms: number): Promise<void>;
696
+ on(event: "request" | "requestfinished" | "requestfailed", handler: (request: unknown) => void): unknown;
697
+ title(): Promise<string>;
698
+ keyboard: {
699
+ press(key: string): Promise<void>;
700
+ };
701
+ mouse: {
702
+ wheel(dx: number, dy: number): Promise<void>;
703
+ };
704
+ };
705
+ type BrowserMode = "auto" | "hosted" | "local";
706
+ /** One browser action as the platform ingests it
707
+ * (`POST /world-sessions/{id}/browser-events`). */
708
+ type BrowserActionEvent = {
709
+ agentId: string;
710
+ seq: number;
711
+ ts: string;
712
+ action: string;
713
+ args: Record<string, unknown>;
714
+ ok: boolean;
715
+ error: string | null;
716
+ durationMs: number;
717
+ url: string | null;
718
+ title: string | null;
719
+ mode: Exclude<BrowserMode, "auto">;
720
+ viewport: {
721
+ width: number;
722
+ height: number;
723
+ };
724
+ /** base64 JPEG of the screen after the action; null if it could not be taken. */
725
+ screenshot: string | null;
726
+ };
727
+ /** What of an action's arguments may leave the process. Selectors, paths
728
+ * and keys are what a reviewer needs; anything keyed like a credential, or
729
+ * typed into a field whose selector names one, or shaped like a known key,
730
+ * is replaced. Strings are capped, nested values dropped. */
731
+ declare function redactActionArgs(action: string, args: Record<string, unknown>): Record<string, unknown>;
732
+ /**
733
+ * Ships browser action events to the platform, off the action's hot path.
734
+ *
735
+ * `post` receives a batch of events (the request body's `events`). Events
736
+ * are numbered here, so ordering survives batching and retries — the
737
+ * platform dedups on `(agentId, seq)`. A batch that keeps failing is dropped
738
+ * with a warning: telemetry must never stall or fail the agent.
739
+ *
740
+ * Numbering is durable across recorders: `nextSeq()` hands out a position
741
+ * within this recorder, and the first send adds the base `resumeFrom`
742
+ * reports — the platform's next free seq for this agent — so an agent id
743
+ * reopened in a later process appends to its timeline instead of colliding
744
+ * with (and being deduplicated against) what it already recorded. The base
745
+ * is fixed once resolved, which keeps retries idempotent.
746
+ */
747
+ declare class BrowserActionRecorder {
748
+ private readonly post;
749
+ readonly agentId: string;
750
+ private readonly opts;
751
+ private seq;
752
+ private base;
753
+ private queue;
754
+ private timer;
755
+ private inflight;
756
+ sent: number;
757
+ dropped: number;
758
+ constructor(post: (events: BrowserActionEvent[]) => Promise<void>, agentId: string, opts?: {
759
+ /** The platform's next free seq for `agentId`; 0 when not given. */
760
+ resumeFrom?: () => Promise<number>;
761
+ batchSize?: number;
762
+ flushIntervalMs?: number;
763
+ maxRetries?: number;
764
+ sleep?: (ms: number) => Promise<void>;
765
+ warn?: (message: string) => void;
766
+ });
767
+ /** This recorder's next position; the wire seq is `resumeFrom() + this`. */
768
+ nextSeq(): number;
769
+ private resolveBase;
770
+ record(event: BrowserActionEvent): void;
771
+ /** Resolve once everything recorded so far has been posted (or dropped). */
772
+ flush(): Promise<void>;
773
+ close(): Promise<void>;
774
+ private drain;
775
+ private send;
776
+ }
777
+ /**
778
+ * One Playwright page on the session's UI. Thin on purpose — `page` is the
779
+ * real Playwright page for anything this wrapper does not cover.
780
+ */
781
+ declare class WorldBrowser {
782
+ readonly page: BrowserPage;
783
+ readonly ui: SessionSurfaces["ui"] | undefined;
784
+ readonly mode: Exclude<BrowserMode, "auto">;
785
+ private readonly teardown;
786
+ readonly viewport: {
787
+ width: number;
788
+ height: number;
789
+ };
790
+ readonly recorder: BrowserActionRecorder | null;
791
+ constructor(page: BrowserPage, ui: SessionSurfaces["ui"] | undefined, mode: Exclude<BrowserMode, "auto">, teardown: () => Promise<void>, viewport?: {
792
+ width: number;
793
+ height: number;
794
+ }, recorder?: BrowserActionRecorder | null);
795
+ private inflight;
796
+ private lastNetwork;
797
+ get agentId(): string | null;
798
+ /** Run one action and report it: the event carries what was asked,
799
+ * whether it worked, and the screen after — for failures too, so a
800
+ * reviewer sees what the agent saw when the selector did not match. */
801
+ private act;
802
+ private observeForEvent;
803
+ /** Open a UI path (`/customers`), a full URL, or — with no argument — the
804
+ * UI's declared entry page. */
805
+ goto(pathOrUrl?: string): Promise<string>;
806
+ back(): Promise<string>;
807
+ /** Wait for the page to finish reacting to an action. `load` alone is not
808
+ * enough for client-rendered UIs (React et al.): a click returns before the
809
+ * fetch that re-renders the page, so an agent would read stale text.
810
+ * Playwright's `networkidle` is per navigation and resolves at once after
811
+ * the first one, so this tracks requests itself: done when nothing is in
812
+ * flight and the network has been quiet for `SETTLE_QUIET_MS`, bounded so
813
+ * long-polling UIs cannot hang us. */
814
+ private settle;
815
+ click(selector: string): Promise<void>;
816
+ type(selector: string, text: string): Promise<void>;
817
+ press(key: string): Promise<void>;
818
+ scroll(dy: number): Promise<void>;
819
+ screenshot(fullPage?: boolean): Promise<Buffer>;
820
+ screenshotBase64(fullPage?: boolean): Promise<string>;
821
+ text(selector?: string): Promise<string>;
822
+ html(): Promise<string>;
823
+ get url(): string;
824
+ title(): Promise<string>;
825
+ close(): Promise<void>;
826
+ }
827
+ /** The Playwright entry points this module needs, so tests can inject a fake. */
828
+ type PlaywrightLike = {
829
+ chromium: {
830
+ connect(wsEndpoint: string): Promise<PlaywrightBrowserLike>;
831
+ connectOverCDP(endpointURL: string): Promise<PlaywrightBrowserLike>;
832
+ launch(opts?: {
833
+ headless?: boolean;
834
+ }): Promise<PlaywrightBrowserLike>;
835
+ };
836
+ };
837
+ type PlaywrightBrowserLike = {
838
+ newContext(opts?: {
839
+ viewport?: {
840
+ width: number;
841
+ height: number;
842
+ };
843
+ }): Promise<{
844
+ newPage(): Promise<BrowserPage>;
845
+ close(): Promise<void>;
846
+ }>;
847
+ close(): Promise<void>;
848
+ };
849
+ declare function resolveBrowserMode(surfaces: SessionSurfaces, mode: BrowserMode): Exclude<BrowserMode, "auto">;
850
+ /** Open a browser on the session's UI in `hosted`, `local` or `auto` mode. */
851
+ declare function openBrowser(surfaces: SessionSurfaces, opts?: {
852
+ mode?: BrowserMode;
853
+ headless?: boolean;
854
+ playwright?: PlaywrightLike;
855
+ recorder?: BrowserActionRecorder | null;
856
+ }): Promise<WorldBrowser>;
857
+ declare const COMPUTER_USE_SPECS: readonly [{
858
+ readonly name: "browser_goto";
859
+ readonly signature: "browser_goto(path=None)";
860
+ 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.";
861
+ }, {
862
+ readonly name: "browser_click";
863
+ readonly signature: "browser_click(selector)";
864
+ readonly doc: "Click an element by Playwright selector (CSS, `text=Refund`, `role=button[name=Save]`). Returns the page text after the click.";
865
+ }, {
866
+ readonly name: "browser_type";
867
+ readonly signature: "browser_type(selector, text)";
868
+ readonly doc: "Replace the value of an input/textarea found by selector with `text`.";
869
+ }, {
870
+ readonly name: "browser_press";
871
+ readonly signature: "browser_press(key)";
872
+ readonly doc: "Press a key (Enter, Tab, Escape, ArrowDown, ...). Returns the page text after.";
873
+ }, {
874
+ readonly name: "browser_scroll";
875
+ readonly signature: "browser_scroll(dy=600)";
876
+ readonly doc: "Scroll the page vertically by `dy` pixels (negative scrolls up).";
877
+ }, {
878
+ readonly name: "browser_screenshot";
879
+ readonly signature: "browser_screenshot(full_page=False)";
880
+ readonly doc: "Take a PNG screenshot; returns {image_base64, url}.";
881
+ }, {
882
+ readonly name: "browser_read";
883
+ readonly signature: "browser_read(selector='body')";
884
+ readonly doc: "Return the visible text of an element (default: whole page) plus the URL and title.";
885
+ }, {
886
+ readonly name: "browser_back";
887
+ readonly signature: "browser_back()";
888
+ readonly doc: "Go back one page in history.";
889
+ }];
890
+ /**
891
+ * The browser as model tools, in the same `WorldToolkit` shape the world's
892
+ * own tools come in — so an agent loop that already dispatches
893
+ * `toolkit().impls` merges `computerUseToolkit(b).impls` and gains a screen
894
+ * without a second dispatch path.
895
+ */
896
+ declare function computerUseToolkit(browser: WorldBrowser, opts?: {
897
+ maxText?: number;
898
+ }): WorldToolkit;
899
+
215
900
  /**
216
901
  * The working-dir half of the TS CLI: push / pull / checkout / status /
217
902
  * branch / tag / propose — a faithful port of the Python client
@@ -265,12 +950,23 @@ declare function push(dir: string, opts?: {
265
950
  * branch tip, so re-validating a PR replaces its own previous push
266
951
  * instead of 409ing against it. */
267
952
  baseVersionId?: string | null;
953
+ /** Container metadata recorded on resolve — the Python CLI's --name,
954
+ * --description, --tag and --visibility. */
955
+ name?: string;
956
+ description?: string;
957
+ tags?: string[];
958
+ visibility?: string;
959
+ /** Pre-built OCI image ref for image/agentic envs (recorded on the version). */
960
+ imageRef?: string;
268
961
  options?: WorldsClientOptions;
269
962
  }): Promise<{
963
+ containerId: string;
270
964
  slug: string;
271
965
  versionId: string;
272
966
  contentHash: string;
273
967
  branch: string;
968
+ state: string | null;
969
+ alreadyUploaded: boolean;
274
970
  }>;
275
971
  declare function pull(slugRef: string, target?: string, options?: WorldsClientOptions): Promise<{
276
972
  slug: string;
@@ -345,18 +1041,6 @@ declare function validateWorld(dir: string, opts: {
345
1041
  options?: WorldsClientOptions;
346
1042
  }): Promise<ValidateReport>;
347
1043
 
348
- /**
349
- * Worlds from TypeScript: identity, tasks, and HOSTED execution.
350
- *
351
- * The same three-level model as the Python SDK — WorldSet → Task — with one
352
- * deliberate difference: a world's tools are Python modules, so TypeScript
353
- * does not materialize task environments in-process. What a TS agent
354
- * codebase needs is exactly what this module provides: resolve a world ref
355
- * to its pinned version, read its task list, and dispatch HOSTED runs
356
- * (parallelism included) that execute the world server-side and file graded,
357
- * version-pinned rollouts. Local in-process execution stays a Python
358
- * capability by design, not by omission.
359
- */
360
1044
  type WorldsClientOptions = {
361
1045
  host?: string;
362
1046
  publicKey?: string;
@@ -380,7 +1064,7 @@ type DispatchedRun = {
380
1064
  };
381
1065
  /** Authenticated JSON request against the platform API — the primitive the
382
1066
  * worlds helpers and the TS CLI share. */
383
- declare function apiRequest<T>(options: WorldsClientOptions, method: "GET" | "POST" | "PUT" | "DELETE", path: string, body?: unknown): Promise<T>;
1067
+ declare function apiRequest<T>(options: WorldsClientOptions, method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", path: string, body?: unknown): Promise<T>;
384
1068
  /** Set (or rotate) one environment secret — write-only: no API returns it. */
385
1069
  declare function setEnvSecret(slug: string, key: string, value: string, options?: WorldsClientOptions): Promise<{
386
1070
  key: string;
@@ -404,6 +1088,30 @@ type RunConfigSummary = {
404
1088
  };
405
1089
  /** Run configs in the project. CI resolves by NAME and dispatches by id. */
406
1090
  declare function listRunConfigs(options?: WorldsClientOptions): Promise<RunConfigSummary[]>;
1091
+ /** What a run config selects for the runner to work through. A config runs
1092
+ * EITHER the bundle's own scenarios (`taskNames`, `taskSetDatasetId`) OR the
1093
+ * project's stored tasks (`worldTasks`, api worlds only) — never both. A
1094
+ * stored task ref without `version` runs the task's current version at
1095
+ * dispatch time; with it, that version forever. */
1096
+ type RunConfigInput = {
1097
+ id?: string;
1098
+ name: string;
1099
+ models: string[];
1100
+ parallelism?: number;
1101
+ numExamples?: number;
1102
+ rolloutsPerExample?: number;
1103
+ timeoutMinutes?: number;
1104
+ agent?: string;
1105
+ taskSetDatasetId?: string | null;
1106
+ taskNames?: string[];
1107
+ worldTasks?: WorldTaskIdRef[];
1108
+ autoRunOnPush?: boolean;
1109
+ };
1110
+ /** Create a run config, or update the one named by `id`. */
1111
+ declare function upsertRunConfig(input: RunConfigInput, options?: WorldsClientOptions): Promise<RunConfigSummary>;
1112
+ /** `id[@version]` items (comma-separated or an array) → stored task refs;
1113
+ * the spelling `bench run-configs create --world-tasks` takes. */
1114
+ declare function parseWorldTaskRefs(spec: string | string[]): WorldTaskIdRef[];
407
1115
  type RunReport = {
408
1116
  id: string;
409
1117
  status: string;
@@ -481,12 +1189,14 @@ declare class WorldSet {
481
1189
  constructor(slugRef: string, slug: string, ref: string | null, version: ResolvedWorldVersion, tasks: WorldTask[], options: WorldsClientOptions);
482
1190
  task(variant: string): WorldTask;
483
1191
  /**
484
- * Open a LIVE session against one of this world's tasks: the platform boots
485
- * (or reuses) a warm container, and your agent calls its tools through the
486
- * platform. See worlds/session.ts.
1192
+ * Open a LIVE session against one of this world's tasks — a bundled task's
1193
+ * name or an inline `WorldTaskSpec`: the platform boots (or reuses) a warm
1194
+ * container, and your agent calls its tools through the platform. See
1195
+ * worlds/session.ts.
487
1196
  */
488
- open(task: string, opts?: {
1197
+ open(task: WorldTaskRef, opts?: {
489
1198
  reuseWarm?: boolean;
1199
+ surfaces?: WorldSurfaceKind[];
490
1200
  }): Promise<WorldSession>;
491
1201
  /**
492
1202
  * Start a HOSTED run of a run config against this world — the platform
@@ -510,4 +1220,4 @@ declare class WorldSet {
510
1220
  */
511
1221
  declare function openWorld(slugRef: string, options?: WorldsClientOptions): Promise<WorldSet>;
512
1222
 
513
- export { DEFAULT_BRANCH, type DispatchedRun, type GradeResult, type LocalMeta, type ResolvedWorldVersion, type RunConfigSummary, type RunProvenance, type RunReport, type SessionRunReport, type SessionRunResult, type ValidateReport, type ValidatedRun, WorldSession, WorldSessionCallError, type WorldSessionState, WorldSessionTimeout, WorldSet, WorldTask, type WorldTaskInfo, type WorldToolSpec, type WorldToolkit, type WorldsClientOptions, apiRequest, attachSession, buildSourceTarball, collectArchiveRelPaths, computeContentHash, createRef, deleteEnvSecret, detectProvenance, getRun, isIncludedInContentHash, listEnvSecretKeys, listRunConfigs, localTreeState, openSession, openWorld, propose, pull, push, readLocalMeta, runSessions, schemaFromSignature, setEnvSecret, snapshotTreeHashes, validateWorld, waitForRun, writeLocalMeta };
1223
+ export { type BrowserActionEvent, BrowserActionRecorder, type BrowserMode, type BrowserPage, COMPUTER_USE_SPECS, DEFAULT_BRANCH, DEFAULT_VIEWPORT, type DispatchedRun, EVENT_BATCH_SIZE, EVENT_FLUSH_INTERVAL_MS, EVENT_MAX_RETRIES, type GradeResult, type LocalMeta, type OpenSessionOptions, type PlaywrightBrowserLike, type PlaywrightLike, type ResolvedWorldVersion, type RunConfigInput, type RunConfigSummary, type RunProvenance, type RunReport, SURFACE_KINDS, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type ValidateReport, type ValidatedRun, WorldBrowser, 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 WorldToolSpec, type WorldToolkit, type WorldsClientOptions, apiRequest, attachSession, buildSourceTarball, collectArchiveRelPaths, computeContentHash, computerUseToolkit, createRef, createTask, deleteEnvSecret, deleteTask, detectProvenance, getRun, getTask, isIncludedInContentHash, isTaskIdRef, isTaskSpec, listEnvSecretKeys, listRunConfigs, listTasks, localTreeState, openBrowser, openSession, openWorld, parseWorldTaskRefs, propose, pull, push, readLocalMeta, redactActionArgs, resolveBrowserMode, runSessions, schemaFromSignature, setEnvSecret, snapshotTreeHashes, surfaceKinds, taskLabel, uiEntryUrl, uiUrl, updateTask, upsertRunConfig, validateTask, validateWorld, waitForRun, withoutUiToken, writeLocalMeta };