@withgateway/sdk 0.1.19 → 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 +8677 -1320
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +8683 -1327
  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 +1005 -55
  9. package/dist/index.js.map +1 -1
  10. package/dist/index.mjs +969 -47
  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 +966 -51
  19. package/dist/worlds/index.js.map +1 -1
  20. package/dist/worlds/index.mjs +960 -45
  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
@@ -16,6 +16,483 @@ var __export = (target, all) => {
16
16
  __defProp(target, name, { get: all[name], enumerable: true });
17
17
  };
18
18
 
19
+ // src/worlds/browser.ts
20
+ function surfaceKinds(s) {
21
+ const kinds = ["tools"];
22
+ if (s.api) kinds.push("api");
23
+ if (s.ui) kinds.push("ui");
24
+ if (s.browser) kinds.push("browser");
25
+ return kinds;
26
+ }
27
+ function uiUrl(ui, path2) {
28
+ const base = ui.url.replace(/\/+$/, "");
29
+ const rel = path2.startsWith("/") ? path2 : `/${path2}`;
30
+ if (!ui.token) return base + rel;
31
+ const [beforeHash, hash] = splitHash(rel);
32
+ const joiner = beforeHash.includes("?") ? "&" : "?";
33
+ const query = `${UI_TOKEN_QUERY}=${encodeURIComponent(ui.token)}`;
34
+ return base + beforeHash + joiner + query + hash;
35
+ }
36
+ function uiEntryUrl(ui) {
37
+ return uiUrl(ui, ui.entry || "/");
38
+ }
39
+ function withoutUiToken(url) {
40
+ const [beforeHash, hash] = splitHash(url);
41
+ const q = beforeHash.indexOf("?");
42
+ if (q < 0) return url;
43
+ const kept = beforeHash.slice(q + 1).split("&").filter((pair) => pair !== "" && pair.split("=")[0] !== UI_TOKEN_QUERY);
44
+ return beforeHash.slice(0, q) + (kept.length ? `?${kept.join("&")}` : "") + hash;
45
+ }
46
+ function splitHash(url) {
47
+ const h = url.indexOf("#");
48
+ return h < 0 ? [url, ""] : [url.slice(0, h), url.slice(h)];
49
+ }
50
+ function redactActionArgs(action, args) {
51
+ const secretField = action === "browser_type" && SECRET_KEY.test(String(args.selector ?? ""));
52
+ const out = {};
53
+ for (const [key, value] of Object.entries(args)) {
54
+ if (value === null || value === void 0) out[key] = null;
55
+ else if (typeof value === "boolean" || typeof value === "number")
56
+ out[key] = value;
57
+ else if (typeof value === "string") {
58
+ if (SECRET_KEY.test(key) || SECRET_VALUE.test(value) || secretField && key === "text")
59
+ out[key] = "[redacted]";
60
+ else
61
+ out[key] = value.length <= EVENT_MAX_STRING ? value : value.slice(0, EVENT_MAX_STRING) + "\u2026";
62
+ } else out[key] = "[omitted]";
63
+ }
64
+ return out;
65
+ }
66
+ async function loadPlaywright() {
67
+ try {
68
+ const name = "playwright";
69
+ return await import(name);
70
+ } catch (error) {
71
+ throw new Error(
72
+ "Driving a world UI needs Playwright: npm install playwright (and `npx playwright install chromium` for local mode).",
73
+ { cause: error }
74
+ );
75
+ }
76
+ }
77
+ function resolveBrowserMode(surfaces, mode) {
78
+ if (!surfaces.ui && !surfaces.browser)
79
+ throw new WorldSurfaceUnavailable(
80
+ "ui",
81
+ "open the session with surfaces: ['ui'] on a world that declares [ui]"
82
+ );
83
+ const resolved = mode === "auto" ? surfaces.browser ? "hosted" : "local" : mode;
84
+ if (resolved === "hosted" && !surfaces.browser)
85
+ throw new WorldSurfaceUnavailable(
86
+ "browser",
87
+ "open the session with surfaces: ['browser'] to get a hosted browser"
88
+ );
89
+ return resolved;
90
+ }
91
+ async function openBrowser(surfaces, opts = {}) {
92
+ const mode = resolveBrowserMode(surfaces, opts.mode ?? "auto");
93
+ const pw = opts.playwright ?? await loadPlaywright();
94
+ const viewport = surfaces.browser?.viewport ?? DEFAULT_VIEWPORT;
95
+ const browser = mode === "hosted" ? surfaces.browser.protocol === "playwright" ? await pw.chromium.connect(surfaces.browser.wsUrl) : await pw.chromium.connectOverCDP(surfaces.browser.wsUrl) : await pw.chromium.launch({ headless: opts.headless ?? true });
96
+ const context = await browser.newContext({ viewport });
97
+ const page = await context.newPage();
98
+ return new WorldBrowser(
99
+ page,
100
+ surfaces.ui,
101
+ mode,
102
+ async () => {
103
+ await context.close();
104
+ await browser.close();
105
+ },
106
+ viewport,
107
+ opts.recorder ?? null
108
+ );
109
+ }
110
+ function computerUseToolkit(browser, opts = {}) {
111
+ const maxText = opts.maxText ?? 2e4;
112
+ const observe = async (selector = "body") => {
113
+ const text = await browser.text(selector);
114
+ return {
115
+ url: browser.url,
116
+ title: await browser.title(),
117
+ text: text.slice(0, maxText),
118
+ truncated: text.length > maxText
119
+ };
120
+ };
121
+ const impls = {
122
+ browser_goto: async (a) => {
123
+ await browser.goto(typeof a.path === "string" ? a.path : void 0);
124
+ return observe();
125
+ },
126
+ browser_click: async (a) => {
127
+ await browser.click(str(a.selector, ""));
128
+ return observe();
129
+ },
130
+ browser_type: async (a) => {
131
+ await browser.type(str(a.selector, ""), String(a.text ?? ""));
132
+ return { ok: true, url: browser.url };
133
+ },
134
+ browser_press: async (a) => {
135
+ await browser.press(str(a.key, "Enter"));
136
+ return observe();
137
+ },
138
+ browser_scroll: async (a) => {
139
+ await browser.scroll(typeof a.dy === "number" ? a.dy : 600);
140
+ return { ok: true, url: browser.url };
141
+ },
142
+ browser_screenshot: async (a) => ({
143
+ image_base64: await browser.screenshotBase64(a.full_page === true),
144
+ url: browser.url
145
+ }),
146
+ browser_read: async (a) => observe(str(a.selector, "body")),
147
+ browser_back: async () => {
148
+ await browser.back();
149
+ return observe();
150
+ }
151
+ };
152
+ const specs = COMPUTER_USE_SPECS.map((s) => ({ ...s }));
153
+ return {
154
+ schemas: specs.map((spec) => schemaFromSignature(spec)),
155
+ impls,
156
+ specs
157
+ };
158
+ }
159
+ var SURFACE_KINDS, DEFAULT_VIEWPORT, SETTLE_TIMEOUT_MS, SETTLE_QUIET_MS, SETTLE_POLL_MS, EVENT_BATCH_SIZE, EVENT_FLUSH_INTERVAL_MS, EVENT_MAX_RETRIES, EVENT_SCREENSHOT_QUALITY, EVENT_MAX_STRING, SECRET_KEY, SECRET_VALUE, WorldSurfaceUnavailable, UI_TOKEN_QUERY, BrowserActionRecorder, WorldBrowser, COMPUTER_USE_SPECS, str;
160
+ var init_browser = __esm({
161
+ "src/worlds/browser.ts"() {
162
+ "use strict";
163
+ init_session();
164
+ SURFACE_KINDS = ["tools", "api", "ui", "browser"];
165
+ DEFAULT_VIEWPORT = { width: 1280, height: 800 };
166
+ SETTLE_TIMEOUT_MS = 5e3;
167
+ SETTLE_QUIET_MS = 150;
168
+ SETTLE_POLL_MS = 25;
169
+ EVENT_BATCH_SIZE = 10;
170
+ EVENT_FLUSH_INTERVAL_MS = 1e3;
171
+ EVENT_MAX_RETRIES = 3;
172
+ EVENT_SCREENSHOT_QUALITY = 60;
173
+ EVENT_MAX_STRING = 500;
174
+ SECRET_KEY = /pass(word|wd)?|secret|token|api[-_]?key|authorization|cookie|(^|[-_ #.\["'=])(otp|pin|cvv|ssn)([-_ \]"']|$)/i;
175
+ SECRET_VALUE = /^((sk|pk|ghp|xox[abp])[-_][-_A-Za-z0-9]{8,}|AKIA[0-9A-Z]{12,}|Bearer [-_.A-Za-z0-9]{8,})/;
176
+ WorldSurfaceUnavailable = class extends Error {
177
+ constructor(surface, reason) {
178
+ super(`World surface '${surface}' is unavailable: ${reason}`);
179
+ this.surface = surface;
180
+ }
181
+ };
182
+ UI_TOKEN_QUERY = "token";
183
+ BrowserActionRecorder = class {
184
+ constructor(post, agentId, opts = {}) {
185
+ this.post = post;
186
+ this.agentId = agentId;
187
+ this.opts = opts;
188
+ }
189
+ seq = 0;
190
+ base = null;
191
+ queue = [];
192
+ timer = null;
193
+ inflight = Promise.resolve();
194
+ sent = 0;
195
+ dropped = 0;
196
+ /** This recorder's next position; the wire seq is `resumeFrom() + this`. */
197
+ nextSeq() {
198
+ return this.seq++;
199
+ }
200
+ resolveBase() {
201
+ if (this.base === null) {
202
+ const resolve2 = this.opts.resumeFrom ?? (async () => 0);
203
+ this.base = resolve2().then((n) => {
204
+ if (!Number.isInteger(n) || n < 0)
205
+ throw new Error(
206
+ `browser event base seq must be a non-negative integer, got ${String(n)}`
207
+ );
208
+ return n;
209
+ });
210
+ this.base.catch(() => {
211
+ this.base = null;
212
+ });
213
+ }
214
+ return this.base;
215
+ }
216
+ record(event) {
217
+ this.queue.push(event);
218
+ if (this.queue.length >= (this.opts.batchSize ?? EVENT_BATCH_SIZE)) {
219
+ this.drain();
220
+ } else if (this.timer === null) {
221
+ this.timer = setTimeout(
222
+ () => this.drain(),
223
+ this.opts.flushIntervalMs ?? EVENT_FLUSH_INTERVAL_MS
224
+ );
225
+ if (typeof this.timer === "object" && "unref" in this.timer)
226
+ this.timer.unref();
227
+ }
228
+ }
229
+ /** Resolve once everything recorded so far has been posted (or dropped). */
230
+ async flush() {
231
+ this.drain();
232
+ await this.inflight;
233
+ }
234
+ async close() {
235
+ await this.flush();
236
+ }
237
+ drain() {
238
+ if (this.timer !== null) {
239
+ clearTimeout(this.timer);
240
+ this.timer = null;
241
+ }
242
+ if (this.queue.length === 0) return;
243
+ const batch = this.queue;
244
+ this.queue = [];
245
+ this.inflight = this.inflight.then(() => this.send(batch));
246
+ }
247
+ async send(batch) {
248
+ const retries = this.opts.maxRetries ?? EVENT_MAX_RETRIES;
249
+ const sleep2 = this.opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
250
+ for (let attempt = 0; attempt < retries; attempt++) {
251
+ try {
252
+ const base = await this.resolveBase();
253
+ await this.post(
254
+ base === 0 ? batch : batch.map((e) => ({ ...e, seq: base + e.seq }))
255
+ );
256
+ this.sent += batch.length;
257
+ return;
258
+ } catch (error) {
259
+ if (attempt + 1 === retries) {
260
+ this.dropped += batch.length;
261
+ (this.opts.warn ?? console.warn)(
262
+ `dropping ${batch.length} browser events after ${attempt + 1} attempts: ${String(error)}`
263
+ );
264
+ return;
265
+ }
266
+ await sleep2(500 * 2 ** attempt);
267
+ }
268
+ }
269
+ }
270
+ };
271
+ WorldBrowser = class {
272
+ constructor(page, ui, mode, teardown, viewport = DEFAULT_VIEWPORT, recorder = null) {
273
+ this.page = page;
274
+ this.ui = ui;
275
+ this.mode = mode;
276
+ this.teardown = teardown;
277
+ this.viewport = viewport;
278
+ this.recorder = recorder;
279
+ page.on("request", () => {
280
+ this.inflight += 1;
281
+ this.lastNetwork = Date.now();
282
+ });
283
+ const done = () => {
284
+ this.inflight = Math.max(0, this.inflight - 1);
285
+ this.lastNetwork = Date.now();
286
+ };
287
+ page.on("requestfinished", done);
288
+ page.on("requestfailed", done);
289
+ }
290
+ inflight = 0;
291
+ lastNetwork = Date.now();
292
+ get agentId() {
293
+ return this.recorder?.agentId ?? null;
294
+ }
295
+ /** Run one action and report it: the event carries what was asked,
296
+ * whether it worked, and the screen after — for failures too, so a
297
+ * reviewer sees what the agent saw when the selector did not match. */
298
+ async act(action, args, fn) {
299
+ const recorder = this.recorder;
300
+ if (!recorder) return fn();
301
+ const started = Date.now();
302
+ let ok = true;
303
+ let error = null;
304
+ try {
305
+ return await fn();
306
+ } catch (err) {
307
+ ok = false;
308
+ error = (err instanceof Error ? `${err.name}: ${err.message}` : String(err)).slice(0, 4e3);
309
+ throw err;
310
+ } finally {
311
+ recorder.record({
312
+ agentId: recorder.agentId,
313
+ seq: recorder.nextSeq(),
314
+ ts: (/* @__PURE__ */ new Date()).toISOString(),
315
+ action,
316
+ args: redactActionArgs(action, args),
317
+ ok,
318
+ error,
319
+ durationMs: Date.now() - started,
320
+ mode: this.mode,
321
+ viewport: { ...this.viewport },
322
+ ...await this.observeForEvent()
323
+ });
324
+ }
325
+ }
326
+ async observeForEvent() {
327
+ const out = {
328
+ url: null,
329
+ title: null,
330
+ screenshot: null
331
+ };
332
+ try {
333
+ out.url = this.page.url();
334
+ out.title = await this.page.title();
335
+ const jpeg = await this.page.screenshot({
336
+ type: "jpeg",
337
+ quality: EVENT_SCREENSHOT_QUALITY
338
+ });
339
+ out.screenshot = jpeg.toString("base64");
340
+ } catch {
341
+ }
342
+ return out;
343
+ }
344
+ /** Open a UI path (`/customers`), a full URL, or — with no argument — the
345
+ * UI's declared entry page. */
346
+ async goto(pathOrUrl) {
347
+ let target;
348
+ if (pathOrUrl === void 0) {
349
+ if (!this.ui)
350
+ throw new WorldSurfaceUnavailable(
351
+ "ui",
352
+ "this session has no UI to navigate to"
353
+ );
354
+ target = uiEntryUrl(this.ui);
355
+ } else if (/^https?:\/\//.test(pathOrUrl)) {
356
+ target = pathOrUrl;
357
+ } else {
358
+ if (!this.ui)
359
+ throw new WorldSurfaceUnavailable(
360
+ "ui",
361
+ "relative paths need a UI surface"
362
+ );
363
+ target = uiUrl(this.ui, pathOrUrl);
364
+ }
365
+ return this.act(
366
+ "browser_goto",
367
+ { path: pathOrUrl ?? null, url: withoutUiToken(target) },
368
+ async () => {
369
+ await this.page.goto(target, { waitUntil: "load" });
370
+ await this.settle();
371
+ return this.page.url();
372
+ }
373
+ );
374
+ }
375
+ async back() {
376
+ return this.act("browser_back", {}, async () => {
377
+ await this.page.goBack({ waitUntil: "load" });
378
+ await this.settle();
379
+ return this.page.url();
380
+ });
381
+ }
382
+ /** Wait for the page to finish reacting to an action. `load` alone is not
383
+ * enough for client-rendered UIs (React et al.): a click returns before the
384
+ * fetch that re-renders the page, so an agent would read stale text.
385
+ * Playwright's `networkidle` is per navigation and resolves at once after
386
+ * the first one, so this tracks requests itself: done when nothing is in
387
+ * flight and the network has been quiet for `SETTLE_QUIET_MS`, bounded so
388
+ * long-polling UIs cannot hang us. */
389
+ async settle() {
390
+ await this.page.waitForLoadState("load");
391
+ const deadline = Date.now() + SETTLE_TIMEOUT_MS;
392
+ while (Date.now() < deadline) {
393
+ const quiet = Date.now() - this.lastNetwork >= SETTLE_QUIET_MS;
394
+ if (this.inflight === 0 && quiet) return;
395
+ await this.page.waitForTimeout(SETTLE_POLL_MS);
396
+ }
397
+ }
398
+ async click(selector) {
399
+ await this.act("browser_click", { selector }, async () => {
400
+ await this.page.click(selector);
401
+ await this.settle();
402
+ });
403
+ }
404
+ async type(selector, text) {
405
+ await this.act(
406
+ "browser_type",
407
+ { selector, text },
408
+ () => this.page.fill(selector, text)
409
+ );
410
+ }
411
+ async press(key) {
412
+ await this.act("browser_press", { key }, async () => {
413
+ await this.page.keyboard.press(key);
414
+ await this.settle();
415
+ });
416
+ }
417
+ async scroll(dy) {
418
+ await this.act(
419
+ "browser_scroll",
420
+ { dy },
421
+ () => this.page.mouse.wheel(0, dy)
422
+ );
423
+ }
424
+ async screenshot(fullPage = false) {
425
+ return this.page.screenshot({ type: "png", fullPage });
426
+ }
427
+ async screenshotBase64(fullPage = false) {
428
+ return (await this.screenshot(fullPage)).toString("base64");
429
+ }
430
+ async text(selector = "body") {
431
+ return this.page.innerText(selector);
432
+ }
433
+ async html() {
434
+ return this.page.content();
435
+ }
436
+ get url() {
437
+ return this.page.url();
438
+ }
439
+ async title() {
440
+ return this.page.title();
441
+ }
442
+ async close() {
443
+ try {
444
+ await this.teardown();
445
+ } finally {
446
+ await this.recorder?.close();
447
+ }
448
+ }
449
+ };
450
+ COMPUTER_USE_SPECS = [
451
+ {
452
+ name: "browser_goto",
453
+ signature: "browser_goto(path=None)",
454
+ 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."
455
+ },
456
+ {
457
+ name: "browser_click",
458
+ signature: "browser_click(selector)",
459
+ doc: "Click an element by Playwright selector (CSS, `text=Refund`, `role=button[name=Save]`). Returns the page text after the click."
460
+ },
461
+ {
462
+ name: "browser_type",
463
+ signature: "browser_type(selector, text)",
464
+ doc: "Replace the value of an input/textarea found by selector with `text`."
465
+ },
466
+ {
467
+ name: "browser_press",
468
+ signature: "browser_press(key)",
469
+ doc: "Press a key (Enter, Tab, Escape, ArrowDown, ...). Returns the page text after."
470
+ },
471
+ {
472
+ name: "browser_scroll",
473
+ signature: "browser_scroll(dy=600)",
474
+ doc: "Scroll the page vertically by `dy` pixels (negative scrolls up)."
475
+ },
476
+ {
477
+ name: "browser_screenshot",
478
+ signature: "browser_screenshot(full_page=False)",
479
+ doc: "Take a PNG screenshot; returns {image_base64, url}."
480
+ },
481
+ {
482
+ name: "browser_read",
483
+ signature: "browser_read(selector='body')",
484
+ doc: "Return the visible text of an element (default: whole page) plus the URL and title."
485
+ },
486
+ {
487
+ name: "browser_back",
488
+ signature: "browser_back()",
489
+ doc: "Go back one page in history."
490
+ }
491
+ ];
492
+ str = (v, fallback) => typeof v === "string" && v.length > 0 ? v : fallback;
493
+ }
494
+ });
495
+
19
496
  // src/worlds/session.ts
20
497
  var session_exports = {};
21
498
  __export(session_exports, {
@@ -23,11 +500,24 @@ __export(session_exports, {
23
500
  WorldSessionCallError: () => WorldSessionCallError,
24
501
  WorldSessionTimeout: () => WorldSessionTimeout,
25
502
  attachSession: () => attachSession,
503
+ isTaskIdRef: () => isTaskIdRef,
504
+ isTaskSpec: () => isTaskSpec,
26
505
  openSession: () => openSession,
27
506
  runSessions: () => runSessions,
28
- schemaFromSignature: () => schemaFromSignature
507
+ schemaFromSignature: () => schemaFromSignature,
508
+ taskLabel: () => taskLabel
29
509
  });
510
+ import { randomUUID } from "crypto";
30
511
  function schemaFromSignature(spec) {
512
+ if (spec.inputSchema)
513
+ return {
514
+ type: "function",
515
+ function: {
516
+ name: modelToolName(spec.name),
517
+ description: spec.doc ?? spec.name,
518
+ parameters: spec.inputSchema
519
+ }
520
+ };
31
521
  const inside = /\(([\s\S]*)\)\s*$/.exec(spec.signature.trim())?.[1] ?? "";
32
522
  const properties = {};
33
523
  const required = [];
@@ -63,7 +553,7 @@ function schemaFromSignature(spec) {
63
553
  return {
64
554
  type: "function",
65
555
  function: {
66
- name: spec.name,
556
+ name: modelToolName(spec.name),
67
557
  description: spec.doc ?? spec.name,
68
558
  parameters: { type: "object", properties, required }
69
559
  }
@@ -77,8 +567,20 @@ async function attachSession(sessionId, options = {}) {
77
567
  );
78
568
  return new WorldSession(sessionId, state, options);
79
569
  }
80
- async function openSession(slugOrRef, task, opts = {}) {
570
+ async function openSession(slugOrRef, taskOrOpts, positionalOpts = {}) {
571
+ const { task, ...opts } = typeof taskOrOpts === "object" && "task" in taskOrOpts ? taskOrOpts : { task: taskOrOpts, ...positionalOpts };
572
+ if (task === void 0 || task === null || typeof task === "string" && !task || isTaskIdRef(task) && !task.id || isTaskSpec(task) && !task.instruction || typeof task === "object" && !isTaskIdRef(task) && !isTaskSpec(task))
573
+ throw new Error(
574
+ "openSession needs a task: a bundled task name, a stored task { id, version? } or { instruction, seed?, grader?, metadata? }"
575
+ );
81
576
  const options = opts.options ?? {};
577
+ const unknown = (opts.surfaces ?? []).filter(
578
+ (s) => !SURFACE_KINDS.includes(s)
579
+ );
580
+ if (unknown.length)
581
+ throw new Error(
582
+ `Unknown world surfaces: ${unknown.join(", ")}; choose from ${SURFACE_KINDS.join(", ")}`
583
+ );
82
584
  const at = slugOrRef.indexOf("@");
83
585
  const slug = at === -1 ? slugOrRef : slugOrRef.slice(0, at);
84
586
  const state = await apiRequest(
@@ -88,7 +590,8 @@ async function openSession(slugOrRef, task, opts = {}) {
88
590
  {
89
591
  ...opts.versionId ? { versionId: opts.versionId } : { slug },
90
592
  task,
91
- ...opts.reuseWarm === void 0 ? {} : { reuseWarm: opts.reuseWarm }
593
+ ...opts.reuseWarm === void 0 ? {} : { reuseWarm: opts.reuseWarm },
594
+ ...opts.surfaces?.length ? { surfaces: opts.surfaces } : {}
92
595
  }
93
596
  );
94
597
  return new WorldSession(state.sessionId, state, options);
@@ -109,20 +612,24 @@ async function runSessions(opts) {
109
612
  await Promise.all(
110
613
  Array.from({ length: Math.min(concurrency, tasks.length) }, async () => {
111
614
  while (next < tasks.length) {
112
- const task = tasks[next++];
615
+ const taskRef = tasks[next++];
616
+ let task = taskLabel(taskRef);
113
617
  let session = null;
114
618
  try {
115
- session = await openSession(opts.world, task, {
619
+ session = await openSession(opts.world, {
620
+ task: taskRef,
116
621
  versionId,
117
622
  options
118
623
  });
624
+ task = taskLabel(taskRef, session.taskInfo);
119
625
  await session.ready();
120
626
  const toolkit = await session.toolkit();
121
627
  await opts.agent({
122
628
  session,
123
629
  toolkit,
124
- instruction: session.instruction ?? task,
125
- task
630
+ instruction: session.instruction ?? (isTaskSpec(taskRef) ? taskRef.instruction : task),
631
+ task,
632
+ taskRef
126
633
  });
127
634
  const graded = await session.grade();
128
635
  const result = {
@@ -158,35 +665,142 @@ async function runSessions(opts) {
158
665
  passed: opts.failUnder === void 0 ? true : mean >= opts.failUnder
159
666
  };
160
667
  }
161
- var READY_TIMEOUT_MS, READY_POLL_MS, CALL_TIMEOUT_MS, CALL_POLL_MS, sleep, WorldSessionTimeout, WorldSessionCallError, WorldSession;
668
+ var isTaskIdRef, isTaskSpec, taskLabel, READY_TIMEOUT_MS, READY_POLL_MS, CALL_TIMEOUT_MS, CALL_POLL_MS, JUDGED_GRADE_TIMEOUT_MS, JUDGED_GRADE_POLL_MS, EXPORT_PAGE, sleep, modelToolName, WorldSessionTimeout, WorldSessionCallError, WorldSession;
162
669
  var init_session = __esm({
163
670
  "src/worlds/session.ts"() {
164
671
  "use strict";
165
672
  init_worlds();
673
+ init_browser();
674
+ isTaskIdRef = (task) => typeof task === "object" && task !== null && "id" in task;
675
+ isTaskSpec = (task) => typeof task === "object" && task !== null && "instruction" in task;
676
+ taskLabel = (task, info) => {
677
+ if (typeof task === "string") return task;
678
+ if (isTaskIdRef(task)) return info?.name ?? task.id;
679
+ if (task.name) return task.name;
680
+ return info?.hash ? `inline:${info.hash.slice(0, 12)}` : "inline";
681
+ };
166
682
  READY_TIMEOUT_MS = 10 * 6e4;
167
683
  READY_POLL_MS = 2e3;
168
684
  CALL_TIMEOUT_MS = 3 * 6e4;
169
685
  CALL_POLL_MS = 400;
686
+ JUDGED_GRADE_TIMEOUT_MS = 15 * 6e4;
687
+ JUDGED_GRADE_POLL_MS = 2e3;
688
+ EXPORT_PAGE = 500;
170
689
  sleep = (ms) => new Promise((r) => setTimeout(r, ms));
690
+ modelToolName = (name) => name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64) || "tool";
171
691
  WorldSessionTimeout = class extends Error {
172
692
  };
173
693
  WorldSessionCallError = class extends Error {
174
694
  };
175
695
  WorldSession = class {
176
- constructor(sessionId, state, options) {
696
+ constructor(sessionId, current, options) {
177
697
  this.sessionId = sessionId;
178
- this.state = state;
698
+ this.current = current;
179
699
  this.options = options;
180
700
  }
701
+ /** The task's display name: a bundled scenario's, or the inline spec's
702
+ * `name` (null when the spec was unnamed). Same as `taskName`. */
181
703
  get task() {
182
- return this.state.taskName;
704
+ return this.current.taskName;
705
+ }
706
+ /** The task's display name: a bundled scenario's, or the inline spec's
707
+ * `name` (null when the spec was unnamed). */
708
+ get taskName() {
709
+ return this.current.taskName;
710
+ }
711
+ /** The task this session runs: bundled scenario, stored task or inline
712
+ * spec, its name, hash and the caller's metadata. */
713
+ get taskInfo() {
714
+ return this.current.task ?? {
715
+ source: "bundled",
716
+ name: this.current.taskName,
717
+ hash: null,
718
+ metadata: {}
719
+ };
183
720
  }
184
- /** What this task asks for — the bundle's own instruction.md. */
721
+ /** What this task asks for — the bundle's instruction.md, or the inline
722
+ * spec's `instruction`. */
185
723
  get instruction() {
186
- return this.state.instruction ?? null;
724
+ return this.current.instruction ?? null;
187
725
  }
188
726
  get versionId() {
189
- return this.state.versionId;
727
+ return this.current.versionId;
728
+ }
729
+ /** Whether the session answered ready as of the last state read (the open,
730
+ * a `status()`, or the poll inside `ready()`); no request is made. */
731
+ get isReady() {
732
+ return this.current.ready;
733
+ }
734
+ /** `api` / `ui` / `browser` are present exactly when the world declares
735
+ * them AND the session was opened asking for them. */
736
+ async surfaces() {
737
+ if (!this.current.surfaces) await this.status();
738
+ return this.current.surfaces ?? { tools: { kind: "rendezvous" } };
739
+ }
740
+ /** Base URL of the world's own HTTP API for this session. */
741
+ async api() {
742
+ const { api } = await this.surfaces();
743
+ if (!api)
744
+ throw new WorldSurfaceUnavailable(
745
+ "api",
746
+ "open the session with surfaces: ['api'] on an api-type world"
747
+ );
748
+ return api.url;
749
+ }
750
+ /** Headers every request to `api()` needs. A World Host session gates its
751
+ * api surface on a per-session token; a pod or hosted twin answers with the
752
+ * world's own declared auth and this is `{}`. */
753
+ async apiHeaders() {
754
+ const { api } = await this.surfaces();
755
+ return api?.token ? { Authorization: `Bearer ${api.token}` } : {};
756
+ }
757
+ /** URL of the world's UI entry page for this session. */
758
+ async ui() {
759
+ const { ui } = await this.surfaces();
760
+ if (!ui)
761
+ throw new WorldSurfaceUnavailable(
762
+ "ui",
763
+ "open the session with surfaces: ['ui'] on a world that declares [ui]"
764
+ );
765
+ return uiEntryUrl(ui);
766
+ }
767
+ /** A Playwright browser on this session's UI: `hosted` drives the one the
768
+ * platform runs next to the world, `local` launches one here, `auto`
769
+ * prefers hosted. Call `close()` when done.
770
+ *
771
+ * Every action is reported to the platform under `agentId` (default:
772
+ * `GATEWAY_AGENT_ID` or a fresh `agent-<hex>`) so the session page shows
773
+ * this agent's own timeline — several agents may share one session and
774
+ * one hosted browser. `record: false` opts out. */
775
+ async browser(opts = {}) {
776
+ const { agentId, record = true, ...rest } = opts;
777
+ return openBrowser(await this.surfaces(), {
778
+ ...rest,
779
+ recorder: record ? this.browserRecorder(agentId) : null
780
+ });
781
+ }
782
+ /** The reporter `browser()` uses; exposed for a page you drive yourself. */
783
+ browserRecorder(agentId) {
784
+ const path2 = `/api/public/world-sessions/${encodeURIComponent(this.sessionId)}/browser-events`;
785
+ const id = agentId ?? process.env.GATEWAY_AGENT_ID ?? `agent-${randomUUID().replace(/-/g, "").slice(0, 8)}`;
786
+ return new BrowserActionRecorder(
787
+ async (events) => {
788
+ await apiRequest(this.options, "POST", path2, { events });
789
+ },
790
+ id,
791
+ {
792
+ // Continue this agent's timeline where the platform has it, so the
793
+ // same id reopened later never re-numbers from zero.
794
+ resumeFrom: async () => {
795
+ const summary = await apiRequest(this.options, "GET", path2);
796
+ return summary.agents.find((a) => a.agentId === id)?.nextSeq ?? 0;
797
+ }
798
+ }
799
+ );
800
+ }
801
+ /** Browser actions as model tools, in the same shape as `toolkit()`. */
802
+ computerUseTools(browser) {
803
+ return computerUseToolkit(browser);
190
804
  }
191
805
  /** The session's latest platform state (one request, no waiting). */
192
806
  async status() {
@@ -195,12 +809,14 @@ var init_session = __esm({
195
809
  "GET",
196
810
  `/api/public/world-sessions/${encodeURIComponent(this.sessionId)}`
197
811
  );
198
- this.state = {
199
- instruction: this.state.instruction,
200
- tools: this.state.tools,
812
+ this.current = {
813
+ instruction: this.current.instruction,
814
+ tools: this.current.tools,
815
+ surfaces: this.current.surfaces,
816
+ task: this.current.task,
201
817
  ...fresh
202
818
  };
203
- return this.state;
819
+ return this.current;
204
820
  }
205
821
  /**
206
822
  * Wait until the container is warm — meaning the process inside it has
@@ -223,14 +839,18 @@ var init_session = __esm({
223
839
  }
224
840
  }
225
841
  /** Enqueue one interaction and wait for the container's answer. */
226
- async exchange(body, timeoutMs = CALL_TIMEOUT_MS) {
227
- const { callId } = await apiRequest(
842
+ async exchange(body, timeoutMs) {
843
+ const enqueued = await apiRequest(
228
844
  this.options,
229
845
  "POST",
230
846
  `/api/public/world-sessions/${encodeURIComponent(this.sessionId)}/calls`,
231
847
  body
232
848
  );
233
- const deadline = Date.now() + timeoutMs;
849
+ const { callId } = enqueued;
850
+ const judged = enqueued.pending === true;
851
+ const budgetMs = timeoutMs ?? (judged ? JUDGED_GRADE_TIMEOUT_MS : CALL_TIMEOUT_MS);
852
+ const pollMs = judged ? JUDGED_GRADE_POLL_MS : CALL_POLL_MS;
853
+ const deadline = Date.now() + budgetMs;
234
854
  for (; ; ) {
235
855
  const call = await apiRequest(
236
856
  this.options,
@@ -243,9 +863,9 @@ var init_session = __esm({
243
863
  }
244
864
  if (Date.now() > deadline)
245
865
  throw new WorldSessionTimeout(
246
- `Call ${callId} still ${call.state} after ${Math.round(timeoutMs / 1e3)}s \u2014 the container may have died.`
866
+ judged ? `Grade ${callId} still ${call.state} after ${Math.round(budgetMs / 1e3)}s \u2014 the judge has not answered; the platform finalizes the call on its own, read it back with export().` : `Call ${callId} still ${call.state} after ${Math.round(budgetMs / 1e3)}s \u2014 the container may have died.`
247
867
  );
248
- await sleep(CALL_POLL_MS);
868
+ await sleep(pollMs);
249
869
  }
250
870
  }
251
871
  /**
@@ -269,15 +889,27 @@ var init_session = __esm({
269
889
  * hand-written map that still remembers the old name.
270
890
  */
271
891
  async toolkit() {
272
- let specs = this.state.tools;
892
+ let specs = this.current.tools;
273
893
  if (!specs) specs = (await this.status()).tools ?? [];
274
- const impls = {};
894
+ const impls = /* @__PURE__ */ Object.create(null);
275
895
  for (const spec of specs) {
276
- impls[spec.name] = (args = {}) => this.call(spec.name, args);
896
+ const alias = modelToolName(spec.name);
897
+ if (Object.hasOwn(impls, alias))
898
+ throw new WorldSessionCallError(`Model tool name collision: ${alias}`);
899
+ impls[alias] = (args = {}) => this.call(spec.name, args);
277
900
  }
278
901
  return { schemas: specs.map(schemaFromSignature), impls, specs };
279
902
  }
280
- /** Run the task's grader against the container's END STATE. */
903
+ /** Run the task's grader against the container's END STATE. Graders answer
904
+ * in one of two shapes: the scalar with named rewards beside it
905
+ * (`{reward, check_a, check_b}`, a task's own `grade.py`), or the named
906
+ * rewards nested under `rewards` (the api, mock-tools and World Host
907
+ * runners). Both land in `rewards`.
908
+ *
909
+ * A rubric grade is finalized by the platform's judge, not the container:
910
+ * the platform answers the enqueue with `pending: true`, and this waits on
911
+ * the judge's budget (15 min) instead of a call's. `timeoutMs` overrides
912
+ * either. */
281
913
  async grade(opts = {}) {
282
914
  const raw = await this.exchange(
283
915
  { kind: "grade" },
@@ -285,6 +917,12 @@ var init_session = __esm({
285
917
  );
286
918
  const record = raw && typeof raw === "object" ? raw : {};
287
919
  const rewards = {};
920
+ const nested = record.rewards;
921
+ if (nested && typeof nested === "object") {
922
+ for (const [key, value] of Object.entries(nested)) {
923
+ if (typeof value === "number") rewards[key] = value;
924
+ }
925
+ }
288
926
  for (const [key, value] of Object.entries(record)) {
289
927
  if (key !== "reward" && typeof value === "number") rewards[key] = value;
290
928
  }
@@ -294,6 +932,91 @@ var init_session = __esm({
294
932
  raw
295
933
  };
296
934
  }
935
+ /**
936
+ * Put rows into the LIVE world through its contract, in one batch:
937
+ * `append` (default) upserts by primary key, `replace` makes the named
938
+ * entities hold exactly these rows. Atomic — a refused row leaves the
939
+ * session unchanged and the error names the entity, row and field.
940
+ */
941
+ async seed(rows, opts = {}) {
942
+ const mode = opts.mode ?? "append";
943
+ return await this.exchange(
944
+ { kind: "seed", args: { mode, rows } },
945
+ opts.timeoutMs
946
+ );
947
+ }
948
+ /** Every entity's rows as the world holds them now — the same dump a
949
+ * grader reads. The shape is the world runtime's: a schema world answers
950
+ * `{<entity>: {<key>: row}, snapshot}`, a mock-tools world
951
+ * `{entities: {<entity>: [row]}}`. */
952
+ async state(opts = {}) {
953
+ return this.exchange({ kind: "state" }, opts.timeoutMs);
954
+ }
955
+ /** Back to the opening state: the version's data plus the bundled
956
+ * scenario's or the inline task's seed. Rows written since are gone; the
957
+ * call log stays. */
958
+ async reset(opts = {}) {
959
+ await this.exchange({ kind: "reset" }, opts.timeoutMs);
960
+ }
961
+ /** The session's call log, oldest first: every tool call, seed, reset,
962
+ * grade with its result — the record of the episode. */
963
+ async export() {
964
+ const calls = [];
965
+ let cursor;
966
+ do {
967
+ const params = new URLSearchParams({ limit: String(EXPORT_PAGE) });
968
+ if (cursor) params.set("cursor", cursor);
969
+ const page = await apiRequest(
970
+ this.options,
971
+ "GET",
972
+ `/api/public/world-sessions/${encodeURIComponent(this.sessionId)}/calls?${params.toString()}`
973
+ );
974
+ for (const call of page.calls) {
975
+ calls.push({
976
+ seq: Number(call.seq),
977
+ kind: String(call.kind ?? "call"),
978
+ tool: typeof call.tool === "string" ? call.tool : null,
979
+ args: call.args ?? null,
980
+ result: call.result ?? null,
981
+ error: typeof call.error === "string" ? call.error : null,
982
+ completedAt: typeof call.completedAt === "string" ? call.completedAt : null
983
+ });
984
+ }
985
+ cursor = page.nextCursor ?? void 0;
986
+ } while (cursor);
987
+ return calls;
988
+ }
989
+ /**
990
+ * Promote this session's inline task into a stored task of the project
991
+ * (version 1, pinned to the session's world unless `world` says otherwise),
992
+ * so a task written for one end user can be reused and its grades
993
+ * compared. The session then records the new task's id. A session on a
994
+ * bundled task has nothing to save; one on a stored task is already saved.
995
+ */
996
+ async saveTask(opts = {}) {
997
+ const task = await apiRequest(
998
+ this.options,
999
+ "POST",
1000
+ `/api/public/world-sessions/${encodeURIComponent(this.sessionId)}/task`,
1001
+ {
1002
+ ...opts.name !== void 0 ? { name: opts.name } : {},
1003
+ ...opts.world !== void 0 ? { world: opts.world } : {},
1004
+ ...opts.message !== void 0 ? { message: opts.message } : {}
1005
+ }
1006
+ );
1007
+ this.current = {
1008
+ ...this.current,
1009
+ taskName: task.name,
1010
+ task: {
1011
+ ...this.taskInfo,
1012
+ source: "stored",
1013
+ name: task.name,
1014
+ id: task.id,
1015
+ version: task.version
1016
+ }
1017
+ };
1018
+ return task;
1019
+ }
297
1020
  /**
298
1021
  * End the session. `keepWarm` hands the container back to the pool instead
299
1022
  * of tearing it down, so the next session for the same task starts warm —
@@ -311,6 +1034,83 @@ var init_session = __esm({
311
1034
  }
312
1035
  });
313
1036
 
1037
+ // src/worlds/tasks.ts
1038
+ async function createTask(input, options = {}) {
1039
+ return apiRequest(
1040
+ options,
1041
+ "POST",
1042
+ TASKS,
1043
+ compact({
1044
+ spec: input.spec,
1045
+ name: input.name,
1046
+ world: input.world,
1047
+ message: input.message
1048
+ })
1049
+ );
1050
+ }
1051
+ async function updateTask(taskId, input, options = {}) {
1052
+ if (input.spec === void 0 && input.name === void 0 && input.world === void 0)
1053
+ throw new Error("updateTask: nothing to update \u2014 pass spec, name or world");
1054
+ return apiRequest(
1055
+ options,
1056
+ "PATCH",
1057
+ taskRoute(taskId),
1058
+ compact({
1059
+ spec: input.spec,
1060
+ name: input.name,
1061
+ world: input.world,
1062
+ message: input.message
1063
+ })
1064
+ );
1065
+ }
1066
+ async function listTasks(filter = {}, options = {}) {
1067
+ const params = new URLSearchParams();
1068
+ if (filter.world) params.set("world", filter.world);
1069
+ if (filter.page !== void 0) params.set("page", String(filter.page));
1070
+ if (filter.limit !== void 0) params.set("limit", String(filter.limit));
1071
+ for (const [key, value] of Object.entries(filter.metadata ?? {}))
1072
+ params.set(`metadata.${key}`, value);
1073
+ const query = params.toString();
1074
+ return apiRequest(
1075
+ options,
1076
+ "GET",
1077
+ query ? `${TASKS}?${query}` : TASKS
1078
+ );
1079
+ }
1080
+ async function getTask(taskId, opts = {}, options = {}) {
1081
+ const query = opts.version === void 0 ? "" : `?version=${String(opts.version)}`;
1082
+ return apiRequest(
1083
+ options,
1084
+ "GET",
1085
+ `${taskRoute(taskId)}${query}`
1086
+ );
1087
+ }
1088
+ async function deleteTask(taskId, options = {}) {
1089
+ return apiRequest(options, "DELETE", taskRoute(taskId));
1090
+ }
1091
+ async function validateTask(taskId, target = {}, options = {}) {
1092
+ return apiRequest(
1093
+ options,
1094
+ "POST",
1095
+ `${taskRoute(taskId)}/validate`,
1096
+ compact({
1097
+ version: target.version,
1098
+ slug: target.slug,
1099
+ versionId: target.versionId
1100
+ })
1101
+ );
1102
+ }
1103
+ var TASKS, taskRoute, compact;
1104
+ var init_tasks = __esm({
1105
+ "src/worlds/tasks.ts"() {
1106
+ "use strict";
1107
+ init_worlds();
1108
+ TASKS = "/api/public/world-tasks";
1109
+ taskRoute = (id) => `${TASKS}/${encodeURIComponent(id)}`;
1110
+ compact = (body) => Object.fromEntries(Object.entries(body).filter(([, v]) => v !== void 0));
1111
+ }
1112
+ });
1113
+
314
1114
  // src/worlds/hub.ts
315
1115
  import { createHash } from "crypto";
316
1116
  import { gzipSync, gunzipSync } from "zlib";
@@ -508,7 +1308,13 @@ async function push(dir, opts = {}) {
508
1308
  options,
509
1309
  "POST",
510
1310
  "/api/public/benchmark-containers/resolve",
511
- { slug, name: pyproject.name ?? slug }
1311
+ {
1312
+ slug,
1313
+ name: opts.name ?? pyproject.name ?? slug,
1314
+ ...opts.description ? { description: opts.description } : {},
1315
+ ...opts.tags?.length ? { tags: opts.tags } : {},
1316
+ ...opts.visibility ? { visibility: opts.visibility } : {}
1317
+ }
512
1318
  );
513
1319
  const tarball = buildSourceTarball(dir);
514
1320
  const bundleSha256 = sha256b64(tarball);
@@ -524,10 +1330,11 @@ async function push(dir, opts = {}) {
524
1330
  baseVersionId,
525
1331
  ...opts.force ? { force: true } : {},
526
1332
  ...opts.message ? { changeReason: opts.message } : {},
527
- ...opts.author ? { author: opts.author } : {}
1333
+ ...opts.author ? { author: opts.author } : {},
1334
+ ...opts.imageRef ? { imageRef: opts.imageRef } : {}
528
1335
  });
529
1336
  if (version.uploadUrl) await putObject(version.uploadUrl, tarball, bundleSha256);
530
- await apiRequest(
1337
+ const final = await apiRequest(
531
1338
  options,
532
1339
  "POST",
533
1340
  `/api/public/benchmark-containers/versions/${version.versionId}/finalize`,
@@ -544,7 +1351,15 @@ async function push(dir, opts = {}) {
544
1351
  forkedFromVersionId: baseVersionId,
545
1352
  baseFiles: snapshotTreeHashes(dir)
546
1353
  });
547
- return { slug, versionId: version.versionId, contentHash, branch };
1354
+ return {
1355
+ containerId: resolve2.containerId,
1356
+ slug,
1357
+ versionId: version.versionId,
1358
+ contentHash,
1359
+ branch: final.branch ?? branch,
1360
+ state: final.state ?? null,
1361
+ alreadyUploaded: Boolean(version.alreadyUploaded)
1362
+ };
548
1363
  }
549
1364
  function extractBundle(bundle, dir) {
550
1365
  const tar = gunzipSync(bundle);
@@ -680,14 +1495,15 @@ var init_hub = __esm({
680
1495
  function fmtScore(score) {
681
1496
  return score === null ? "no score" : score.toFixed(3);
682
1497
  }
683
- function buildMarkdown(report, minScore) {
1498
+ function buildMarkdown(report, minScore, source) {
684
1499
  const lines = [];
685
1500
  lines.push(
686
1501
  `### World validation ${report.ok ? "passed" : "failed"} \u2014 \`${report.slug}@${report.branch}\``
687
1502
  );
688
1503
  lines.push("");
1504
+ const commitLink = source?.repoUrl && source?.commit ? `[\`${source.commit.slice(0, 12)}\`](${source.repoUrl}/commit/${source.commit})` : null;
689
1505
  lines.push(
690
- `Ran the pull request's own world source (version \`${report.contentHash.slice(0, 12)}\`) through run config **${report.runConfig.name}**` + (minScore !== null ? `, gating at score \u2265 ${minScore}.` : ".")
1506
+ `Ran the pull request's own world source` + (commitLink ? ` (${commitLink} on \`${report.branch}\`` : ` (`) + `${commitLink ? ", " : ""}pinned as \`${report.contentHash.slice(0, 12)}\`) through run config **${report.runConfig.name}**` + (minScore !== null ? `, gating at score \u2265 ${minScore}.` : ".")
691
1507
  );
692
1508
  lines.push("");
693
1509
  lines.push("| Model | Status | Score | Run |");
@@ -707,19 +1523,29 @@ function buildMarkdown(report, minScore) {
707
1523
  reward: sample.reward
708
1524
  }))
709
1525
  );
710
- if (taskRows.length > 0 && taskRows.length <= 40) {
1526
+ if (taskRows.length > 0) {
1527
+ const fold = taskRows.length > 12;
711
1528
  lines.push("");
712
- lines.push("<details><summary>Per-task rewards</summary>");
713
- lines.push("");
714
- lines.push("| Task | Model | Reward |");
1529
+ if (fold) {
1530
+ lines.push(
1531
+ `<details><summary>Per-scenario rewards (${taskRows.length})</summary>`
1532
+ );
1533
+ lines.push("");
1534
+ } else {
1535
+ lines.push(`**Scenarios (${taskRows.length})**`);
1536
+ lines.push("");
1537
+ }
1538
+ lines.push("| Scenario | Model | Reward |");
715
1539
  lines.push("| --- | --- | ---: |");
716
1540
  for (const row of taskRows) {
717
1541
  lines.push(
718
1542
  `| ${row.task} | \`${row.model}\` | ${row.reward === null ? "no score" : row.reward.toFixed(2)} |`
719
1543
  );
720
1544
  }
721
- lines.push("");
722
- lines.push("</details>");
1545
+ if (fold) {
1546
+ lines.push("");
1547
+ lines.push("</details>");
1548
+ }
723
1549
  }
724
1550
  return lines.join("\n");
725
1551
  }
@@ -833,7 +1659,13 @@ async function validateWorld(dir, opts) {
833
1659
  runConfig: { id: runConfig.id, name: runConfig.name },
834
1660
  runs
835
1661
  };
836
- return { ...base, markdown: buildMarkdown(base, minScore) };
1662
+ return {
1663
+ ...base,
1664
+ markdown: buildMarkdown(base, minScore, {
1665
+ repoUrl: provenance.repoUrl,
1666
+ commit: provenance.commit
1667
+ })
1668
+ };
837
1669
  }
838
1670
  var init_validate = __esm({
839
1671
  "src/worlds/validate.ts"() {
@@ -846,37 +1678,65 @@ var init_validate = __esm({
846
1678
  // src/worlds/index.ts
847
1679
  var worlds_exports = {};
848
1680
  __export(worlds_exports, {
1681
+ BrowserActionRecorder: () => BrowserActionRecorder,
1682
+ COMPUTER_USE_SPECS: () => COMPUTER_USE_SPECS,
849
1683
  DEFAULT_BRANCH: () => DEFAULT_BRANCH,
1684
+ DEFAULT_VIEWPORT: () => DEFAULT_VIEWPORT,
1685
+ EVENT_BATCH_SIZE: () => EVENT_BATCH_SIZE,
1686
+ EVENT_FLUSH_INTERVAL_MS: () => EVENT_FLUSH_INTERVAL_MS,
1687
+ EVENT_MAX_RETRIES: () => EVENT_MAX_RETRIES,
1688
+ SURFACE_KINDS: () => SURFACE_KINDS,
1689
+ WorldBrowser: () => WorldBrowser,
850
1690
  WorldSession: () => WorldSession,
851
1691
  WorldSessionCallError: () => WorldSessionCallError,
852
1692
  WorldSessionTimeout: () => WorldSessionTimeout,
853
1693
  WorldSet: () => WorldSet,
1694
+ WorldSurfaceUnavailable: () => WorldSurfaceUnavailable,
854
1695
  WorldTask: () => WorldTask,
855
1696
  apiRequest: () => apiRequest,
856
1697
  attachSession: () => attachSession,
857
1698
  buildSourceTarball: () => buildSourceTarball,
858
1699
  collectArchiveRelPaths: () => collectArchiveRelPaths,
859
1700
  computeContentHash: () => computeContentHash,
1701
+ computerUseToolkit: () => computerUseToolkit,
860
1702
  createRef: () => createRef,
1703
+ createTask: () => createTask,
861
1704
  deleteEnvSecret: () => deleteEnvSecret,
1705
+ deleteTask: () => deleteTask,
862
1706
  detectProvenance: () => detectProvenance,
863
1707
  getRun: () => getRun,
1708
+ getTask: () => getTask,
864
1709
  isIncludedInContentHash: () => isIncludedInContentHash,
1710
+ isTaskIdRef: () => isTaskIdRef,
1711
+ isTaskSpec: () => isTaskSpec,
865
1712
  listEnvSecretKeys: () => listEnvSecretKeys,
866
1713
  listRunConfigs: () => listRunConfigs,
1714
+ listTasks: () => listTasks,
867
1715
  localTreeState: () => localTreeState,
1716
+ openBrowser: () => openBrowser,
868
1717
  openSession: () => openSession,
869
1718
  openWorld: () => openWorld,
1719
+ parseWorldTaskRefs: () => parseWorldTaskRefs,
870
1720
  propose: () => propose,
871
1721
  pull: () => pull,
872
1722
  push: () => push,
873
1723
  readLocalMeta: () => readLocalMeta,
1724
+ redactActionArgs: () => redactActionArgs,
1725
+ resolveBrowserMode: () => resolveBrowserMode,
874
1726
  runSessions: () => runSessions,
875
1727
  schemaFromSignature: () => schemaFromSignature,
876
1728
  setEnvSecret: () => setEnvSecret,
877
1729
  snapshotTreeHashes: () => snapshotTreeHashes,
1730
+ surfaceKinds: () => surfaceKinds,
1731
+ taskLabel: () => taskLabel,
1732
+ uiEntryUrl: () => uiEntryUrl,
1733
+ uiUrl: () => uiUrl,
1734
+ updateTask: () => updateTask,
1735
+ upsertRunConfig: () => upsertRunConfig,
1736
+ validateTask: () => validateTask,
878
1737
  validateWorld: () => validateWorld,
879
1738
  waitForRun: () => waitForRun,
1739
+ withoutUiToken: () => withoutUiToken,
880
1740
  writeLocalMeta: () => writeLocalMeta
881
1741
  });
882
1742
  function resolveEnv(options) {
@@ -947,6 +1807,28 @@ async function listRunConfigs(options = {}) {
947
1807
  );
948
1808
  return res.runConfigs;
949
1809
  }
1810
+ async function upsertRunConfig(input, options = {}) {
1811
+ return apiRequest(
1812
+ options,
1813
+ "POST",
1814
+ "/api/public/benchmark-containers/run-configs",
1815
+ input
1816
+ );
1817
+ }
1818
+ function parseWorldTaskRefs(spec) {
1819
+ const items = (Array.isArray(spec) ? spec : spec.split(",")).map((s) => s.trim()).filter(Boolean);
1820
+ return items.map((item) => {
1821
+ const at = item.lastIndexOf("@");
1822
+ if (at < 0) return { id: item };
1823
+ const id = item.slice(0, at);
1824
+ const version = Number(item.slice(at + 1));
1825
+ if (!id || !Number.isInteger(version) || version < 1)
1826
+ throw new Error(
1827
+ `stored task ref '${item}' is not <id> or <id>@<version> (version a positive integer)`
1828
+ );
1829
+ return { id, version };
1830
+ });
1831
+ }
950
1832
  async function getRun(runId, options = {}) {
951
1833
  return apiRequest(
952
1834
  options,
@@ -1039,6 +1921,8 @@ var WorldTask, WorldSet;
1039
1921
  var init_worlds = __esm({
1040
1922
  "src/worlds/index.ts"() {
1041
1923
  init_session();
1924
+ init_tasks();
1925
+ init_browser();
1042
1926
  init_hub();
1043
1927
  init_validate();
1044
1928
  WorldTask = class {
@@ -1068,15 +1952,18 @@ var init_worlds = __esm({
1068
1952
  return hit;
1069
1953
  }
1070
1954
  /**
1071
- * Open a LIVE session against one of this world's tasks: the platform boots
1072
- * (or reuses) a warm container, and your agent calls its tools through the
1073
- * platform. See worlds/session.ts.
1955
+ * Open a LIVE session against one of this world's tasks — a bundled task's
1956
+ * name or an inline `WorldTaskSpec`: the platform boots (or reuses) a warm
1957
+ * container, and your agent calls its tools through the platform. See
1958
+ * worlds/session.ts.
1074
1959
  */
1075
1960
  async open(task, opts = {}) {
1076
1961
  const { openSession: openSession2 } = await Promise.resolve().then(() => (init_session(), session_exports));
1077
- return openSession2(this.slug, task, {
1962
+ return openSession2(this.slug, {
1963
+ task,
1078
1964
  versionId: this.version.versionId,
1079
1965
  reuseWarm: opts.reuseWarm,
1966
+ surfaces: opts.surfaces,
1080
1967
  options: this.options
1081
1968
  });
1082
1969
  }
@@ -1104,37 +1991,65 @@ var init_worlds = __esm({
1104
1991
  });
1105
1992
  init_worlds();
1106
1993
  export {
1994
+ BrowserActionRecorder,
1995
+ COMPUTER_USE_SPECS,
1107
1996
  DEFAULT_BRANCH,
1997
+ DEFAULT_VIEWPORT,
1998
+ EVENT_BATCH_SIZE,
1999
+ EVENT_FLUSH_INTERVAL_MS,
2000
+ EVENT_MAX_RETRIES,
2001
+ SURFACE_KINDS,
2002
+ WorldBrowser,
1108
2003
  WorldSession,
1109
2004
  WorldSessionCallError,
1110
2005
  WorldSessionTimeout,
1111
2006
  WorldSet,
2007
+ WorldSurfaceUnavailable,
1112
2008
  WorldTask,
1113
2009
  apiRequest,
1114
2010
  attachSession,
1115
2011
  buildSourceTarball,
1116
2012
  collectArchiveRelPaths,
1117
2013
  computeContentHash,
2014
+ computerUseToolkit,
1118
2015
  createRef,
2016
+ createTask,
1119
2017
  deleteEnvSecret,
2018
+ deleteTask,
1120
2019
  detectProvenance,
1121
2020
  getRun,
2021
+ getTask,
1122
2022
  isIncludedInContentHash,
2023
+ isTaskIdRef,
2024
+ isTaskSpec,
1123
2025
  listEnvSecretKeys,
1124
2026
  listRunConfigs,
2027
+ listTasks,
1125
2028
  localTreeState,
2029
+ openBrowser,
1126
2030
  openSession,
1127
2031
  openWorld,
2032
+ parseWorldTaskRefs,
1128
2033
  propose,
1129
2034
  pull,
1130
2035
  push,
1131
2036
  readLocalMeta,
2037
+ redactActionArgs,
2038
+ resolveBrowserMode,
1132
2039
  runSessions,
1133
2040
  schemaFromSignature,
1134
2041
  setEnvSecret,
1135
2042
  snapshotTreeHashes,
2043
+ surfaceKinds,
2044
+ taskLabel,
2045
+ uiEntryUrl,
2046
+ uiUrl,
2047
+ updateTask,
2048
+ upsertRunConfig,
2049
+ validateTask,
1136
2050
  validateWorld,
1137
2051
  waitForRun,
2052
+ withoutUiToken,
1138
2053
  writeLocalMeta
1139
2054
  };
1140
2055
  //# sourceMappingURL=index.mjs.map