@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
package/dist/index.mjs CHANGED
@@ -19,6 +19,483 @@ var __export = (target, all) => {
19
19
  __defProp(target, name, { get: all[name], enumerable: true });
20
20
  };
21
21
 
22
+ // src/worlds/browser.ts
23
+ function surfaceKinds(s) {
24
+ const kinds = ["tools"];
25
+ if (s.api) kinds.push("api");
26
+ if (s.ui) kinds.push("ui");
27
+ if (s.browser) kinds.push("browser");
28
+ return kinds;
29
+ }
30
+ function uiUrl(ui, path2) {
31
+ const base = ui.url.replace(/\/+$/, "");
32
+ const rel = path2.startsWith("/") ? path2 : `/${path2}`;
33
+ if (!ui.token) return base + rel;
34
+ const [beforeHash, hash] = splitHash(rel);
35
+ const joiner = beforeHash.includes("?") ? "&" : "?";
36
+ const query = `${UI_TOKEN_QUERY}=${encodeURIComponent(ui.token)}`;
37
+ return base + beforeHash + joiner + query + hash;
38
+ }
39
+ function uiEntryUrl(ui) {
40
+ return uiUrl(ui, ui.entry || "/");
41
+ }
42
+ function withoutUiToken(url) {
43
+ const [beforeHash, hash] = splitHash(url);
44
+ const q = beforeHash.indexOf("?");
45
+ if (q < 0) return url;
46
+ const kept = beforeHash.slice(q + 1).split("&").filter((pair) => pair !== "" && pair.split("=")[0] !== UI_TOKEN_QUERY);
47
+ return beforeHash.slice(0, q) + (kept.length ? `?${kept.join("&")}` : "") + hash;
48
+ }
49
+ function splitHash(url) {
50
+ const h = url.indexOf("#");
51
+ return h < 0 ? [url, ""] : [url.slice(0, h), url.slice(h)];
52
+ }
53
+ function redactActionArgs(action, args) {
54
+ const secretField = action === "browser_type" && SECRET_KEY.test(String(args.selector ?? ""));
55
+ const out = {};
56
+ for (const [key, value] of Object.entries(args)) {
57
+ if (value === null || value === void 0) out[key] = null;
58
+ else if (typeof value === "boolean" || typeof value === "number")
59
+ out[key] = value;
60
+ else if (typeof value === "string") {
61
+ if (SECRET_KEY.test(key) || SECRET_VALUE.test(value) || secretField && key === "text")
62
+ out[key] = "[redacted]";
63
+ else
64
+ out[key] = value.length <= EVENT_MAX_STRING ? value : value.slice(0, EVENT_MAX_STRING) + "\u2026";
65
+ } else out[key] = "[omitted]";
66
+ }
67
+ return out;
68
+ }
69
+ async function loadPlaywright() {
70
+ try {
71
+ const name = "playwright";
72
+ return await import(name);
73
+ } catch (error) {
74
+ throw new Error(
75
+ "Driving a world UI needs Playwright: npm install playwright (and `npx playwright install chromium` for local mode).",
76
+ { cause: error }
77
+ );
78
+ }
79
+ }
80
+ function resolveBrowserMode(surfaces, mode) {
81
+ if (!surfaces.ui && !surfaces.browser)
82
+ throw new WorldSurfaceUnavailable(
83
+ "ui",
84
+ "open the session with surfaces: ['ui'] on a world that declares [ui]"
85
+ );
86
+ const resolved = mode === "auto" ? surfaces.browser ? "hosted" : "local" : mode;
87
+ if (resolved === "hosted" && !surfaces.browser)
88
+ throw new WorldSurfaceUnavailable(
89
+ "browser",
90
+ "open the session with surfaces: ['browser'] to get a hosted browser"
91
+ );
92
+ return resolved;
93
+ }
94
+ async function openBrowser(surfaces, opts = {}) {
95
+ const mode = resolveBrowserMode(surfaces, opts.mode ?? "auto");
96
+ const pw = opts.playwright ?? await loadPlaywright();
97
+ const viewport = surfaces.browser?.viewport ?? DEFAULT_VIEWPORT;
98
+ 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 });
99
+ const context4 = await browser.newContext({ viewport });
100
+ const page = await context4.newPage();
101
+ return new WorldBrowser(
102
+ page,
103
+ surfaces.ui,
104
+ mode,
105
+ async () => {
106
+ await context4.close();
107
+ await browser.close();
108
+ },
109
+ viewport,
110
+ opts.recorder ?? null
111
+ );
112
+ }
113
+ function computerUseToolkit(browser, opts = {}) {
114
+ const maxText = opts.maxText ?? 2e4;
115
+ const observe2 = async (selector = "body") => {
116
+ const text = await browser.text(selector);
117
+ return {
118
+ url: browser.url,
119
+ title: await browser.title(),
120
+ text: text.slice(0, maxText),
121
+ truncated: text.length > maxText
122
+ };
123
+ };
124
+ const impls = {
125
+ browser_goto: async (a) => {
126
+ await browser.goto(typeof a.path === "string" ? a.path : void 0);
127
+ return observe2();
128
+ },
129
+ browser_click: async (a) => {
130
+ await browser.click(str(a.selector, ""));
131
+ return observe2();
132
+ },
133
+ browser_type: async (a) => {
134
+ await browser.type(str(a.selector, ""), String(a.text ?? ""));
135
+ return { ok: true, url: browser.url };
136
+ },
137
+ browser_press: async (a) => {
138
+ await browser.press(str(a.key, "Enter"));
139
+ return observe2();
140
+ },
141
+ browser_scroll: async (a) => {
142
+ await browser.scroll(typeof a.dy === "number" ? a.dy : 600);
143
+ return { ok: true, url: browser.url };
144
+ },
145
+ browser_screenshot: async (a) => ({
146
+ image_base64: await browser.screenshotBase64(a.full_page === true),
147
+ url: browser.url
148
+ }),
149
+ browser_read: async (a) => observe2(str(a.selector, "body")),
150
+ browser_back: async () => {
151
+ await browser.back();
152
+ return observe2();
153
+ }
154
+ };
155
+ const specs = COMPUTER_USE_SPECS.map((s) => ({ ...s }));
156
+ return {
157
+ schemas: specs.map((spec) => schemaFromSignature(spec)),
158
+ impls,
159
+ specs
160
+ };
161
+ }
162
+ 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;
163
+ var init_browser = __esm({
164
+ "src/worlds/browser.ts"() {
165
+ "use strict";
166
+ init_session();
167
+ SURFACE_KINDS = ["tools", "api", "ui", "browser"];
168
+ DEFAULT_VIEWPORT = { width: 1280, height: 800 };
169
+ SETTLE_TIMEOUT_MS = 5e3;
170
+ SETTLE_QUIET_MS = 150;
171
+ SETTLE_POLL_MS = 25;
172
+ EVENT_BATCH_SIZE = 10;
173
+ EVENT_FLUSH_INTERVAL_MS = 1e3;
174
+ EVENT_MAX_RETRIES = 3;
175
+ EVENT_SCREENSHOT_QUALITY = 60;
176
+ EVENT_MAX_STRING = 500;
177
+ SECRET_KEY = /pass(word|wd)?|secret|token|api[-_]?key|authorization|cookie|(^|[-_ #.\["'=])(otp|pin|cvv|ssn)([-_ \]"']|$)/i;
178
+ SECRET_VALUE = /^((sk|pk|ghp|xox[abp])[-_][-_A-Za-z0-9]{8,}|AKIA[0-9A-Z]{12,}|Bearer [-_.A-Za-z0-9]{8,})/;
179
+ WorldSurfaceUnavailable = class extends Error {
180
+ constructor(surface, reason) {
181
+ super(`World surface '${surface}' is unavailable: ${reason}`);
182
+ this.surface = surface;
183
+ }
184
+ };
185
+ UI_TOKEN_QUERY = "token";
186
+ BrowserActionRecorder = class {
187
+ constructor(post, agentId, opts = {}) {
188
+ this.post = post;
189
+ this.agentId = agentId;
190
+ this.opts = opts;
191
+ }
192
+ seq = 0;
193
+ base = null;
194
+ queue = [];
195
+ timer = null;
196
+ inflight = Promise.resolve();
197
+ sent = 0;
198
+ dropped = 0;
199
+ /** This recorder's next position; the wire seq is `resumeFrom() + this`. */
200
+ nextSeq() {
201
+ return this.seq++;
202
+ }
203
+ resolveBase() {
204
+ if (this.base === null) {
205
+ const resolve2 = this.opts.resumeFrom ?? (async () => 0);
206
+ this.base = resolve2().then((n) => {
207
+ if (!Number.isInteger(n) || n < 0)
208
+ throw new Error(
209
+ `browser event base seq must be a non-negative integer, got ${String(n)}`
210
+ );
211
+ return n;
212
+ });
213
+ this.base.catch(() => {
214
+ this.base = null;
215
+ });
216
+ }
217
+ return this.base;
218
+ }
219
+ record(event) {
220
+ this.queue.push(event);
221
+ if (this.queue.length >= (this.opts.batchSize ?? EVENT_BATCH_SIZE)) {
222
+ this.drain();
223
+ } else if (this.timer === null) {
224
+ this.timer = setTimeout(
225
+ () => this.drain(),
226
+ this.opts.flushIntervalMs ?? EVENT_FLUSH_INTERVAL_MS
227
+ );
228
+ if (typeof this.timer === "object" && "unref" in this.timer)
229
+ this.timer.unref();
230
+ }
231
+ }
232
+ /** Resolve once everything recorded so far has been posted (or dropped). */
233
+ async flush() {
234
+ this.drain();
235
+ await this.inflight;
236
+ }
237
+ async close() {
238
+ await this.flush();
239
+ }
240
+ drain() {
241
+ if (this.timer !== null) {
242
+ clearTimeout(this.timer);
243
+ this.timer = null;
244
+ }
245
+ if (this.queue.length === 0) return;
246
+ const batch = this.queue;
247
+ this.queue = [];
248
+ this.inflight = this.inflight.then(() => this.send(batch));
249
+ }
250
+ async send(batch) {
251
+ const retries = this.opts.maxRetries ?? EVENT_MAX_RETRIES;
252
+ const sleep3 = this.opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
253
+ for (let attempt = 0; attempt < retries; attempt++) {
254
+ try {
255
+ const base = await this.resolveBase();
256
+ await this.post(
257
+ base === 0 ? batch : batch.map((e) => ({ ...e, seq: base + e.seq }))
258
+ );
259
+ this.sent += batch.length;
260
+ return;
261
+ } catch (error) {
262
+ if (attempt + 1 === retries) {
263
+ this.dropped += batch.length;
264
+ (this.opts.warn ?? console.warn)(
265
+ `dropping ${batch.length} browser events after ${attempt + 1} attempts: ${String(error)}`
266
+ );
267
+ return;
268
+ }
269
+ await sleep3(500 * 2 ** attempt);
270
+ }
271
+ }
272
+ }
273
+ };
274
+ WorldBrowser = class {
275
+ constructor(page, ui, mode, teardown, viewport = DEFAULT_VIEWPORT, recorder = null) {
276
+ this.page = page;
277
+ this.ui = ui;
278
+ this.mode = mode;
279
+ this.teardown = teardown;
280
+ this.viewport = viewport;
281
+ this.recorder = recorder;
282
+ page.on("request", () => {
283
+ this.inflight += 1;
284
+ this.lastNetwork = Date.now();
285
+ });
286
+ const done = () => {
287
+ this.inflight = Math.max(0, this.inflight - 1);
288
+ this.lastNetwork = Date.now();
289
+ };
290
+ page.on("requestfinished", done);
291
+ page.on("requestfailed", done);
292
+ }
293
+ inflight = 0;
294
+ lastNetwork = Date.now();
295
+ get agentId() {
296
+ return this.recorder?.agentId ?? null;
297
+ }
298
+ /** Run one action and report it: the event carries what was asked,
299
+ * whether it worked, and the screen after — for failures too, so a
300
+ * reviewer sees what the agent saw when the selector did not match. */
301
+ async act(action, args, fn) {
302
+ const recorder = this.recorder;
303
+ if (!recorder) return fn();
304
+ const started = Date.now();
305
+ let ok = true;
306
+ let error = null;
307
+ try {
308
+ return await fn();
309
+ } catch (err) {
310
+ ok = false;
311
+ error = (err instanceof Error ? `${err.name}: ${err.message}` : String(err)).slice(0, 4e3);
312
+ throw err;
313
+ } finally {
314
+ recorder.record({
315
+ agentId: recorder.agentId,
316
+ seq: recorder.nextSeq(),
317
+ ts: (/* @__PURE__ */ new Date()).toISOString(),
318
+ action,
319
+ args: redactActionArgs(action, args),
320
+ ok,
321
+ error,
322
+ durationMs: Date.now() - started,
323
+ mode: this.mode,
324
+ viewport: { ...this.viewport },
325
+ ...await this.observeForEvent()
326
+ });
327
+ }
328
+ }
329
+ async observeForEvent() {
330
+ const out = {
331
+ url: null,
332
+ title: null,
333
+ screenshot: null
334
+ };
335
+ try {
336
+ out.url = this.page.url();
337
+ out.title = await this.page.title();
338
+ const jpeg = await this.page.screenshot({
339
+ type: "jpeg",
340
+ quality: EVENT_SCREENSHOT_QUALITY
341
+ });
342
+ out.screenshot = jpeg.toString("base64");
343
+ } catch {
344
+ }
345
+ return out;
346
+ }
347
+ /** Open a UI path (`/customers`), a full URL, or — with no argument — the
348
+ * UI's declared entry page. */
349
+ async goto(pathOrUrl) {
350
+ let target;
351
+ if (pathOrUrl === void 0) {
352
+ if (!this.ui)
353
+ throw new WorldSurfaceUnavailable(
354
+ "ui",
355
+ "this session has no UI to navigate to"
356
+ );
357
+ target = uiEntryUrl(this.ui);
358
+ } else if (/^https?:\/\//.test(pathOrUrl)) {
359
+ target = pathOrUrl;
360
+ } else {
361
+ if (!this.ui)
362
+ throw new WorldSurfaceUnavailable(
363
+ "ui",
364
+ "relative paths need a UI surface"
365
+ );
366
+ target = uiUrl(this.ui, pathOrUrl);
367
+ }
368
+ return this.act(
369
+ "browser_goto",
370
+ { path: pathOrUrl ?? null, url: withoutUiToken(target) },
371
+ async () => {
372
+ await this.page.goto(target, { waitUntil: "load" });
373
+ await this.settle();
374
+ return this.page.url();
375
+ }
376
+ );
377
+ }
378
+ async back() {
379
+ return this.act("browser_back", {}, async () => {
380
+ await this.page.goBack({ waitUntil: "load" });
381
+ await this.settle();
382
+ return this.page.url();
383
+ });
384
+ }
385
+ /** Wait for the page to finish reacting to an action. `load` alone is not
386
+ * enough for client-rendered UIs (React et al.): a click returns before the
387
+ * fetch that re-renders the page, so an agent would read stale text.
388
+ * Playwright's `networkidle` is per navigation and resolves at once after
389
+ * the first one, so this tracks requests itself: done when nothing is in
390
+ * flight and the network has been quiet for `SETTLE_QUIET_MS`, bounded so
391
+ * long-polling UIs cannot hang us. */
392
+ async settle() {
393
+ await this.page.waitForLoadState("load");
394
+ const deadline = Date.now() + SETTLE_TIMEOUT_MS;
395
+ while (Date.now() < deadline) {
396
+ const quiet = Date.now() - this.lastNetwork >= SETTLE_QUIET_MS;
397
+ if (this.inflight === 0 && quiet) return;
398
+ await this.page.waitForTimeout(SETTLE_POLL_MS);
399
+ }
400
+ }
401
+ async click(selector) {
402
+ await this.act("browser_click", { selector }, async () => {
403
+ await this.page.click(selector);
404
+ await this.settle();
405
+ });
406
+ }
407
+ async type(selector, text) {
408
+ await this.act(
409
+ "browser_type",
410
+ { selector, text },
411
+ () => this.page.fill(selector, text)
412
+ );
413
+ }
414
+ async press(key) {
415
+ await this.act("browser_press", { key }, async () => {
416
+ await this.page.keyboard.press(key);
417
+ await this.settle();
418
+ });
419
+ }
420
+ async scroll(dy) {
421
+ await this.act(
422
+ "browser_scroll",
423
+ { dy },
424
+ () => this.page.mouse.wheel(0, dy)
425
+ );
426
+ }
427
+ async screenshot(fullPage = false) {
428
+ return this.page.screenshot({ type: "png", fullPage });
429
+ }
430
+ async screenshotBase64(fullPage = false) {
431
+ return (await this.screenshot(fullPage)).toString("base64");
432
+ }
433
+ async text(selector = "body") {
434
+ return this.page.innerText(selector);
435
+ }
436
+ async html() {
437
+ return this.page.content();
438
+ }
439
+ get url() {
440
+ return this.page.url();
441
+ }
442
+ async title() {
443
+ return this.page.title();
444
+ }
445
+ async close() {
446
+ try {
447
+ await this.teardown();
448
+ } finally {
449
+ await this.recorder?.close();
450
+ }
451
+ }
452
+ };
453
+ COMPUTER_USE_SPECS = [
454
+ {
455
+ name: "browser_goto",
456
+ signature: "browser_goto(path=None)",
457
+ 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."
458
+ },
459
+ {
460
+ name: "browser_click",
461
+ signature: "browser_click(selector)",
462
+ doc: "Click an element by Playwright selector (CSS, `text=Refund`, `role=button[name=Save]`). Returns the page text after the click."
463
+ },
464
+ {
465
+ name: "browser_type",
466
+ signature: "browser_type(selector, text)",
467
+ doc: "Replace the value of an input/textarea found by selector with `text`."
468
+ },
469
+ {
470
+ name: "browser_press",
471
+ signature: "browser_press(key)",
472
+ doc: "Press a key (Enter, Tab, Escape, ArrowDown, ...). Returns the page text after."
473
+ },
474
+ {
475
+ name: "browser_scroll",
476
+ signature: "browser_scroll(dy=600)",
477
+ doc: "Scroll the page vertically by `dy` pixels (negative scrolls up)."
478
+ },
479
+ {
480
+ name: "browser_screenshot",
481
+ signature: "browser_screenshot(full_page=False)",
482
+ doc: "Take a PNG screenshot; returns {image_base64, url}."
483
+ },
484
+ {
485
+ name: "browser_read",
486
+ signature: "browser_read(selector='body')",
487
+ doc: "Return the visible text of an element (default: whole page) plus the URL and title."
488
+ },
489
+ {
490
+ name: "browser_back",
491
+ signature: "browser_back()",
492
+ doc: "Go back one page in history."
493
+ }
494
+ ];
495
+ str = (v, fallback) => typeof v === "string" && v.length > 0 ? v : fallback;
496
+ }
497
+ });
498
+
22
499
  // src/worlds/session.ts
23
500
  var session_exports = {};
24
501
  __export(session_exports, {
@@ -26,11 +503,24 @@ __export(session_exports, {
26
503
  WorldSessionCallError: () => WorldSessionCallError,
27
504
  WorldSessionTimeout: () => WorldSessionTimeout,
28
505
  attachSession: () => attachSession,
506
+ isTaskIdRef: () => isTaskIdRef,
507
+ isTaskSpec: () => isTaskSpec,
29
508
  openSession: () => openSession,
30
509
  runSessions: () => runSessions,
31
- schemaFromSignature: () => schemaFromSignature
510
+ schemaFromSignature: () => schemaFromSignature,
511
+ taskLabel: () => taskLabel
32
512
  });
513
+ import { randomUUID } from "crypto";
33
514
  function schemaFromSignature(spec) {
515
+ if (spec.inputSchema)
516
+ return {
517
+ type: "function",
518
+ function: {
519
+ name: modelToolName(spec.name),
520
+ description: spec.doc ?? spec.name,
521
+ parameters: spec.inputSchema
522
+ }
523
+ };
34
524
  const inside = /\(([\s\S]*)\)\s*$/.exec(spec.signature.trim())?.[1] ?? "";
35
525
  const properties = {};
36
526
  const required = [];
@@ -66,7 +556,7 @@ function schemaFromSignature(spec) {
66
556
  return {
67
557
  type: "function",
68
558
  function: {
69
- name: spec.name,
559
+ name: modelToolName(spec.name),
70
560
  description: spec.doc ?? spec.name,
71
561
  parameters: { type: "object", properties, required }
72
562
  }
@@ -80,8 +570,20 @@ async function attachSession(sessionId, options = {}) {
80
570
  );
81
571
  return new WorldSession(sessionId, state2, options);
82
572
  }
83
- async function openSession(slugOrRef, task, opts = {}) {
573
+ async function openSession(slugOrRef, taskOrOpts, positionalOpts = {}) {
574
+ const { task, ...opts } = typeof taskOrOpts === "object" && "task" in taskOrOpts ? taskOrOpts : { task: taskOrOpts, ...positionalOpts };
575
+ 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))
576
+ throw new Error(
577
+ "openSession needs a task: a bundled task name, a stored task { id, version? } or { instruction, seed?, grader?, metadata? }"
578
+ );
84
579
  const options = opts.options ?? {};
580
+ const unknown = (opts.surfaces ?? []).filter(
581
+ (s) => !SURFACE_KINDS.includes(s)
582
+ );
583
+ if (unknown.length)
584
+ throw new Error(
585
+ `Unknown world surfaces: ${unknown.join(", ")}; choose from ${SURFACE_KINDS.join(", ")}`
586
+ );
85
587
  const at = slugOrRef.indexOf("@");
86
588
  const slug = at === -1 ? slugOrRef : slugOrRef.slice(0, at);
87
589
  const state2 = await apiRequest(
@@ -91,7 +593,8 @@ async function openSession(slugOrRef, task, opts = {}) {
91
593
  {
92
594
  ...opts.versionId ? { versionId: opts.versionId } : { slug },
93
595
  task,
94
- ...opts.reuseWarm === void 0 ? {} : { reuseWarm: opts.reuseWarm }
596
+ ...opts.reuseWarm === void 0 ? {} : { reuseWarm: opts.reuseWarm },
597
+ ...opts.surfaces?.length ? { surfaces: opts.surfaces } : {}
95
598
  }
96
599
  );
97
600
  return new WorldSession(state2.sessionId, state2, options);
@@ -112,20 +615,24 @@ async function runSessions(opts) {
112
615
  await Promise.all(
113
616
  Array.from({ length: Math.min(concurrency, tasks.length) }, async () => {
114
617
  while (next < tasks.length) {
115
- const task = tasks[next++];
618
+ const taskRef = tasks[next++];
619
+ let task = taskLabel(taskRef);
116
620
  let session = null;
117
621
  try {
118
- session = await openSession(opts.world, task, {
622
+ session = await openSession(opts.world, {
623
+ task: taskRef,
119
624
  versionId,
120
625
  options
121
626
  });
627
+ task = taskLabel(taskRef, session.taskInfo);
122
628
  await session.ready();
123
629
  const toolkit = await session.toolkit();
124
630
  await opts.agent({
125
631
  session,
126
632
  toolkit,
127
- instruction: session.instruction ?? task,
128
- task
633
+ instruction: session.instruction ?? (isTaskSpec(taskRef) ? taskRef.instruction : task),
634
+ task,
635
+ taskRef
129
636
  });
130
637
  const graded = await session.grade();
131
638
  const result = {
@@ -161,35 +668,142 @@ async function runSessions(opts) {
161
668
  passed: opts.failUnder === void 0 ? true : mean >= opts.failUnder
162
669
  };
163
670
  }
164
- var READY_TIMEOUT_MS, READY_POLL_MS, CALL_TIMEOUT_MS, CALL_POLL_MS, sleep2, WorldSessionTimeout, WorldSessionCallError, WorldSession;
671
+ 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, sleep2, modelToolName, WorldSessionTimeout, WorldSessionCallError, WorldSession;
165
672
  var init_session = __esm({
166
673
  "src/worlds/session.ts"() {
167
674
  "use strict";
168
675
  init_worlds();
676
+ init_browser();
677
+ isTaskIdRef = (task) => typeof task === "object" && task !== null && "id" in task;
678
+ isTaskSpec = (task) => typeof task === "object" && task !== null && "instruction" in task;
679
+ taskLabel = (task, info) => {
680
+ if (typeof task === "string") return task;
681
+ if (isTaskIdRef(task)) return info?.name ?? task.id;
682
+ if (task.name) return task.name;
683
+ return info?.hash ? `inline:${info.hash.slice(0, 12)}` : "inline";
684
+ };
169
685
  READY_TIMEOUT_MS = 10 * 6e4;
170
686
  READY_POLL_MS = 2e3;
171
687
  CALL_TIMEOUT_MS = 3 * 6e4;
172
688
  CALL_POLL_MS = 400;
689
+ JUDGED_GRADE_TIMEOUT_MS = 15 * 6e4;
690
+ JUDGED_GRADE_POLL_MS = 2e3;
691
+ EXPORT_PAGE = 500;
173
692
  sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
693
+ modelToolName = (name) => name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64) || "tool";
174
694
  WorldSessionTimeout = class extends Error {
175
695
  };
176
696
  WorldSessionCallError = class extends Error {
177
697
  };
178
698
  WorldSession = class {
179
- constructor(sessionId, state2, options) {
699
+ constructor(sessionId, current, options) {
180
700
  this.sessionId = sessionId;
181
- this.state = state2;
701
+ this.current = current;
182
702
  this.options = options;
183
703
  }
704
+ /** The task's display name: a bundled scenario's, or the inline spec's
705
+ * `name` (null when the spec was unnamed). Same as `taskName`. */
184
706
  get task() {
185
- return this.state.taskName;
707
+ return this.current.taskName;
708
+ }
709
+ /** The task's display name: a bundled scenario's, or the inline spec's
710
+ * `name` (null when the spec was unnamed). */
711
+ get taskName() {
712
+ return this.current.taskName;
186
713
  }
187
- /** What this task asks for — the bundle's own instruction.md. */
714
+ /** The task this session runs: bundled scenario, stored task or inline
715
+ * spec, its name, hash and the caller's metadata. */
716
+ get taskInfo() {
717
+ return this.current.task ?? {
718
+ source: "bundled",
719
+ name: this.current.taskName,
720
+ hash: null,
721
+ metadata: {}
722
+ };
723
+ }
724
+ /** What this task asks for — the bundle's instruction.md, or the inline
725
+ * spec's `instruction`. */
188
726
  get instruction() {
189
- return this.state.instruction ?? null;
727
+ return this.current.instruction ?? null;
190
728
  }
191
729
  get versionId() {
192
- return this.state.versionId;
730
+ return this.current.versionId;
731
+ }
732
+ /** Whether the session answered ready as of the last state read (the open,
733
+ * a `status()`, or the poll inside `ready()`); no request is made. */
734
+ get isReady() {
735
+ return this.current.ready;
736
+ }
737
+ /** `api` / `ui` / `browser` are present exactly when the world declares
738
+ * them AND the session was opened asking for them. */
739
+ async surfaces() {
740
+ if (!this.current.surfaces) await this.status();
741
+ return this.current.surfaces ?? { tools: { kind: "rendezvous" } };
742
+ }
743
+ /** Base URL of the world's own HTTP API for this session. */
744
+ async api() {
745
+ const { api } = await this.surfaces();
746
+ if (!api)
747
+ throw new WorldSurfaceUnavailable(
748
+ "api",
749
+ "open the session with surfaces: ['api'] on an api-type world"
750
+ );
751
+ return api.url;
752
+ }
753
+ /** Headers every request to `api()` needs. A World Host session gates its
754
+ * api surface on a per-session token; a pod or hosted twin answers with the
755
+ * world's own declared auth and this is `{}`. */
756
+ async apiHeaders() {
757
+ const { api } = await this.surfaces();
758
+ return api?.token ? { Authorization: `Bearer ${api.token}` } : {};
759
+ }
760
+ /** URL of the world's UI entry page for this session. */
761
+ async ui() {
762
+ const { ui } = await this.surfaces();
763
+ if (!ui)
764
+ throw new WorldSurfaceUnavailable(
765
+ "ui",
766
+ "open the session with surfaces: ['ui'] on a world that declares [ui]"
767
+ );
768
+ return uiEntryUrl(ui);
769
+ }
770
+ /** A Playwright browser on this session's UI: `hosted` drives the one the
771
+ * platform runs next to the world, `local` launches one here, `auto`
772
+ * prefers hosted. Call `close()` when done.
773
+ *
774
+ * Every action is reported to the platform under `agentId` (default:
775
+ * `GATEWAY_AGENT_ID` or a fresh `agent-<hex>`) so the session page shows
776
+ * this agent's own timeline — several agents may share one session and
777
+ * one hosted browser. `record: false` opts out. */
778
+ async browser(opts = {}) {
779
+ const { agentId, record = true, ...rest } = opts;
780
+ return openBrowser(await this.surfaces(), {
781
+ ...rest,
782
+ recorder: record ? this.browserRecorder(agentId) : null
783
+ });
784
+ }
785
+ /** The reporter `browser()` uses; exposed for a page you drive yourself. */
786
+ browserRecorder(agentId) {
787
+ const path2 = `/api/public/world-sessions/${encodeURIComponent(this.sessionId)}/browser-events`;
788
+ const id = agentId ?? process.env.GATEWAY_AGENT_ID ?? `agent-${randomUUID().replace(/-/g, "").slice(0, 8)}`;
789
+ return new BrowserActionRecorder(
790
+ async (events) => {
791
+ await apiRequest(this.options, "POST", path2, { events });
792
+ },
793
+ id,
794
+ {
795
+ // Continue this agent's timeline where the platform has it, so the
796
+ // same id reopened later never re-numbers from zero.
797
+ resumeFrom: async () => {
798
+ const summary = await apiRequest(this.options, "GET", path2);
799
+ return summary.agents.find((a) => a.agentId === id)?.nextSeq ?? 0;
800
+ }
801
+ }
802
+ );
803
+ }
804
+ /** Browser actions as model tools, in the same shape as `toolkit()`. */
805
+ computerUseTools(browser) {
806
+ return computerUseToolkit(browser);
193
807
  }
194
808
  /** The session's latest platform state (one request, no waiting). */
195
809
  async status() {
@@ -198,12 +812,14 @@ var init_session = __esm({
198
812
  "GET",
199
813
  `/api/public/world-sessions/${encodeURIComponent(this.sessionId)}`
200
814
  );
201
- this.state = {
202
- instruction: this.state.instruction,
203
- tools: this.state.tools,
815
+ this.current = {
816
+ instruction: this.current.instruction,
817
+ tools: this.current.tools,
818
+ surfaces: this.current.surfaces,
819
+ task: this.current.task,
204
820
  ...fresh
205
821
  };
206
- return this.state;
822
+ return this.current;
207
823
  }
208
824
  /**
209
825
  * Wait until the container is warm — meaning the process inside it has
@@ -226,14 +842,18 @@ var init_session = __esm({
226
842
  }
227
843
  }
228
844
  /** Enqueue one interaction and wait for the container's answer. */
229
- async exchange(body, timeoutMs = CALL_TIMEOUT_MS) {
230
- const { callId } = await apiRequest(
845
+ async exchange(body, timeoutMs) {
846
+ const enqueued = await apiRequest(
231
847
  this.options,
232
848
  "POST",
233
849
  `/api/public/world-sessions/${encodeURIComponent(this.sessionId)}/calls`,
234
850
  body
235
851
  );
236
- const deadline = Date.now() + timeoutMs;
852
+ const { callId } = enqueued;
853
+ const judged = enqueued.pending === true;
854
+ const budgetMs = timeoutMs ?? (judged ? JUDGED_GRADE_TIMEOUT_MS : CALL_TIMEOUT_MS);
855
+ const pollMs = judged ? JUDGED_GRADE_POLL_MS : CALL_POLL_MS;
856
+ const deadline = Date.now() + budgetMs;
237
857
  for (; ; ) {
238
858
  const call = await apiRequest(
239
859
  this.options,
@@ -246,9 +866,9 @@ var init_session = __esm({
246
866
  }
247
867
  if (Date.now() > deadline)
248
868
  throw new WorldSessionTimeout(
249
- `Call ${callId} still ${call.state} after ${Math.round(timeoutMs / 1e3)}s \u2014 the container may have died.`
869
+ 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.`
250
870
  );
251
- await sleep2(CALL_POLL_MS);
871
+ await sleep2(pollMs);
252
872
  }
253
873
  }
254
874
  /**
@@ -272,15 +892,27 @@ var init_session = __esm({
272
892
  * hand-written map that still remembers the old name.
273
893
  */
274
894
  async toolkit() {
275
- let specs = this.state.tools;
895
+ let specs = this.current.tools;
276
896
  if (!specs) specs = (await this.status()).tools ?? [];
277
- const impls = {};
897
+ const impls = /* @__PURE__ */ Object.create(null);
278
898
  for (const spec of specs) {
279
- impls[spec.name] = (args = {}) => this.call(spec.name, args);
899
+ const alias = modelToolName(spec.name);
900
+ if (Object.hasOwn(impls, alias))
901
+ throw new WorldSessionCallError(`Model tool name collision: ${alias}`);
902
+ impls[alias] = (args = {}) => this.call(spec.name, args);
280
903
  }
281
904
  return { schemas: specs.map(schemaFromSignature), impls, specs };
282
905
  }
283
- /** Run the task's grader against the container's END STATE. */
906
+ /** Run the task's grader against the container's END STATE. Graders answer
907
+ * in one of two shapes: the scalar with named rewards beside it
908
+ * (`{reward, check_a, check_b}`, a task's own `grade.py`), or the named
909
+ * rewards nested under `rewards` (the api, mock-tools and World Host
910
+ * runners). Both land in `rewards`.
911
+ *
912
+ * A rubric grade is finalized by the platform's judge, not the container:
913
+ * the platform answers the enqueue with `pending: true`, and this waits on
914
+ * the judge's budget (15 min) instead of a call's. `timeoutMs` overrides
915
+ * either. */
284
916
  async grade(opts = {}) {
285
917
  const raw = await this.exchange(
286
918
  { kind: "grade" },
@@ -288,6 +920,12 @@ var init_session = __esm({
288
920
  );
289
921
  const record = raw && typeof raw === "object" ? raw : {};
290
922
  const rewards = {};
923
+ const nested = record.rewards;
924
+ if (nested && typeof nested === "object") {
925
+ for (const [key, value] of Object.entries(nested)) {
926
+ if (typeof value === "number") rewards[key] = value;
927
+ }
928
+ }
291
929
  for (const [key, value] of Object.entries(record)) {
292
930
  if (key !== "reward" && typeof value === "number") rewards[key] = value;
293
931
  }
@@ -297,6 +935,91 @@ var init_session = __esm({
297
935
  raw
298
936
  };
299
937
  }
938
+ /**
939
+ * Put rows into the LIVE world through its contract, in one batch:
940
+ * `append` (default) upserts by primary key, `replace` makes the named
941
+ * entities hold exactly these rows. Atomic — a refused row leaves the
942
+ * session unchanged and the error names the entity, row and field.
943
+ */
944
+ async seed(rows, opts = {}) {
945
+ const mode = opts.mode ?? "append";
946
+ return await this.exchange(
947
+ { kind: "seed", args: { mode, rows } },
948
+ opts.timeoutMs
949
+ );
950
+ }
951
+ /** Every entity's rows as the world holds them now — the same dump a
952
+ * grader reads. The shape is the world runtime's: a schema world answers
953
+ * `{<entity>: {<key>: row}, snapshot}`, a mock-tools world
954
+ * `{entities: {<entity>: [row]}}`. */
955
+ async state(opts = {}) {
956
+ return this.exchange({ kind: "state" }, opts.timeoutMs);
957
+ }
958
+ /** Back to the opening state: the version's data plus the bundled
959
+ * scenario's or the inline task's seed. Rows written since are gone; the
960
+ * call log stays. */
961
+ async reset(opts = {}) {
962
+ await this.exchange({ kind: "reset" }, opts.timeoutMs);
963
+ }
964
+ /** The session's call log, oldest first: every tool call, seed, reset,
965
+ * grade with its result — the record of the episode. */
966
+ async export() {
967
+ const calls = [];
968
+ let cursor;
969
+ do {
970
+ const params = new URLSearchParams({ limit: String(EXPORT_PAGE) });
971
+ if (cursor) params.set("cursor", cursor);
972
+ const page = await apiRequest(
973
+ this.options,
974
+ "GET",
975
+ `/api/public/world-sessions/${encodeURIComponent(this.sessionId)}/calls?${params.toString()}`
976
+ );
977
+ for (const call of page.calls) {
978
+ calls.push({
979
+ seq: Number(call.seq),
980
+ kind: String(call.kind ?? "call"),
981
+ tool: typeof call.tool === "string" ? call.tool : null,
982
+ args: call.args ?? null,
983
+ result: call.result ?? null,
984
+ error: typeof call.error === "string" ? call.error : null,
985
+ completedAt: typeof call.completedAt === "string" ? call.completedAt : null
986
+ });
987
+ }
988
+ cursor = page.nextCursor ?? void 0;
989
+ } while (cursor);
990
+ return calls;
991
+ }
992
+ /**
993
+ * Promote this session's inline task into a stored task of the project
994
+ * (version 1, pinned to the session's world unless `world` says otherwise),
995
+ * so a task written for one end user can be reused and its grades
996
+ * compared. The session then records the new task's id. A session on a
997
+ * bundled task has nothing to save; one on a stored task is already saved.
998
+ */
999
+ async saveTask(opts = {}) {
1000
+ const task = await apiRequest(
1001
+ this.options,
1002
+ "POST",
1003
+ `/api/public/world-sessions/${encodeURIComponent(this.sessionId)}/task`,
1004
+ {
1005
+ ...opts.name !== void 0 ? { name: opts.name } : {},
1006
+ ...opts.world !== void 0 ? { world: opts.world } : {},
1007
+ ...opts.message !== void 0 ? { message: opts.message } : {}
1008
+ }
1009
+ );
1010
+ this.current = {
1011
+ ...this.current,
1012
+ taskName: task.name,
1013
+ task: {
1014
+ ...this.taskInfo,
1015
+ source: "stored",
1016
+ name: task.name,
1017
+ id: task.id,
1018
+ version: task.version
1019
+ }
1020
+ };
1021
+ return task;
1022
+ }
300
1023
  /**
301
1024
  * End the session. `keepWarm` hands the container back to the pool instead
302
1025
  * of tearing it down, so the next session for the same task starts warm —
@@ -314,6 +1037,83 @@ var init_session = __esm({
314
1037
  }
315
1038
  });
316
1039
 
1040
+ // src/worlds/tasks.ts
1041
+ async function createTask(input, options = {}) {
1042
+ return apiRequest(
1043
+ options,
1044
+ "POST",
1045
+ TASKS,
1046
+ compact({
1047
+ spec: input.spec,
1048
+ name: input.name,
1049
+ world: input.world,
1050
+ message: input.message
1051
+ })
1052
+ );
1053
+ }
1054
+ async function updateTask(taskId, input, options = {}) {
1055
+ if (input.spec === void 0 && input.name === void 0 && input.world === void 0)
1056
+ throw new Error("updateTask: nothing to update \u2014 pass spec, name or world");
1057
+ return apiRequest(
1058
+ options,
1059
+ "PATCH",
1060
+ taskRoute(taskId),
1061
+ compact({
1062
+ spec: input.spec,
1063
+ name: input.name,
1064
+ world: input.world,
1065
+ message: input.message
1066
+ })
1067
+ );
1068
+ }
1069
+ async function listTasks(filter = {}, options = {}) {
1070
+ const params = new URLSearchParams();
1071
+ if (filter.world) params.set("world", filter.world);
1072
+ if (filter.page !== void 0) params.set("page", String(filter.page));
1073
+ if (filter.limit !== void 0) params.set("limit", String(filter.limit));
1074
+ for (const [key, value] of Object.entries(filter.metadata ?? {}))
1075
+ params.set(`metadata.${key}`, value);
1076
+ const query = params.toString();
1077
+ return apiRequest(
1078
+ options,
1079
+ "GET",
1080
+ query ? `${TASKS}?${query}` : TASKS
1081
+ );
1082
+ }
1083
+ async function getTask(taskId, opts = {}, options = {}) {
1084
+ const query = opts.version === void 0 ? "" : `?version=${String(opts.version)}`;
1085
+ return apiRequest(
1086
+ options,
1087
+ "GET",
1088
+ `${taskRoute(taskId)}${query}`
1089
+ );
1090
+ }
1091
+ async function deleteTask(taskId, options = {}) {
1092
+ return apiRequest(options, "DELETE", taskRoute(taskId));
1093
+ }
1094
+ async function validateTask(taskId, target = {}, options = {}) {
1095
+ return apiRequest(
1096
+ options,
1097
+ "POST",
1098
+ `${taskRoute(taskId)}/validate`,
1099
+ compact({
1100
+ version: target.version,
1101
+ slug: target.slug,
1102
+ versionId: target.versionId
1103
+ })
1104
+ );
1105
+ }
1106
+ var TASKS, taskRoute, compact;
1107
+ var init_tasks = __esm({
1108
+ "src/worlds/tasks.ts"() {
1109
+ "use strict";
1110
+ init_worlds();
1111
+ TASKS = "/api/public/world-tasks";
1112
+ taskRoute = (id) => `${TASKS}/${encodeURIComponent(id)}`;
1113
+ compact = (body) => Object.fromEntries(Object.entries(body).filter(([, v]) => v !== void 0));
1114
+ }
1115
+ });
1116
+
317
1117
  // src/worlds/hub.ts
318
1118
  import { createHash as createHash2 } from "crypto";
319
1119
  import { gzipSync, gunzipSync } from "zlib";
@@ -511,7 +1311,13 @@ async function push(dir, opts = {}) {
511
1311
  options,
512
1312
  "POST",
513
1313
  "/api/public/benchmark-containers/resolve",
514
- { slug, name: pyproject.name ?? slug }
1314
+ {
1315
+ slug,
1316
+ name: opts.name ?? pyproject.name ?? slug,
1317
+ ...opts.description ? { description: opts.description } : {},
1318
+ ...opts.tags?.length ? { tags: opts.tags } : {},
1319
+ ...opts.visibility ? { visibility: opts.visibility } : {}
1320
+ }
515
1321
  );
516
1322
  const tarball = buildSourceTarball(dir);
517
1323
  const bundleSha256 = sha256b64(tarball);
@@ -527,10 +1333,11 @@ async function push(dir, opts = {}) {
527
1333
  baseVersionId,
528
1334
  ...opts.force ? { force: true } : {},
529
1335
  ...opts.message ? { changeReason: opts.message } : {},
530
- ...opts.author ? { author: opts.author } : {}
1336
+ ...opts.author ? { author: opts.author } : {},
1337
+ ...opts.imageRef ? { imageRef: opts.imageRef } : {}
531
1338
  });
532
1339
  if (version.uploadUrl) await putObject(version.uploadUrl, tarball, bundleSha256);
533
- await apiRequest(
1340
+ const final = await apiRequest(
534
1341
  options,
535
1342
  "POST",
536
1343
  `/api/public/benchmark-containers/versions/${version.versionId}/finalize`,
@@ -547,7 +1354,15 @@ async function push(dir, opts = {}) {
547
1354
  forkedFromVersionId: baseVersionId,
548
1355
  baseFiles: snapshotTreeHashes(dir)
549
1356
  });
550
- return { slug, versionId: version.versionId, contentHash, branch };
1357
+ return {
1358
+ containerId: resolve2.containerId,
1359
+ slug,
1360
+ versionId: version.versionId,
1361
+ contentHash,
1362
+ branch: final.branch ?? branch,
1363
+ state: final.state ?? null,
1364
+ alreadyUploaded: Boolean(version.alreadyUploaded)
1365
+ };
551
1366
  }
552
1367
  function extractBundle(bundle, dir) {
553
1368
  const tar = gunzipSync(bundle);
@@ -866,37 +1681,65 @@ var init_validate = __esm({
866
1681
  // src/worlds/index.ts
867
1682
  var worlds_exports = {};
868
1683
  __export(worlds_exports, {
1684
+ BrowserActionRecorder: () => BrowserActionRecorder,
1685
+ COMPUTER_USE_SPECS: () => COMPUTER_USE_SPECS,
869
1686
  DEFAULT_BRANCH: () => DEFAULT_BRANCH,
1687
+ DEFAULT_VIEWPORT: () => DEFAULT_VIEWPORT,
1688
+ EVENT_BATCH_SIZE: () => EVENT_BATCH_SIZE,
1689
+ EVENT_FLUSH_INTERVAL_MS: () => EVENT_FLUSH_INTERVAL_MS,
1690
+ EVENT_MAX_RETRIES: () => EVENT_MAX_RETRIES,
1691
+ SURFACE_KINDS: () => SURFACE_KINDS,
1692
+ WorldBrowser: () => WorldBrowser,
870
1693
  WorldSession: () => WorldSession,
871
1694
  WorldSessionCallError: () => WorldSessionCallError,
872
1695
  WorldSessionTimeout: () => WorldSessionTimeout,
873
1696
  WorldSet: () => WorldSet,
1697
+ WorldSurfaceUnavailable: () => WorldSurfaceUnavailable,
874
1698
  WorldTask: () => WorldTask,
875
1699
  apiRequest: () => apiRequest,
876
1700
  attachSession: () => attachSession,
877
1701
  buildSourceTarball: () => buildSourceTarball,
878
1702
  collectArchiveRelPaths: () => collectArchiveRelPaths,
879
1703
  computeContentHash: () => computeContentHash,
1704
+ computerUseToolkit: () => computerUseToolkit,
880
1705
  createRef: () => createRef,
1706
+ createTask: () => createTask,
881
1707
  deleteEnvSecret: () => deleteEnvSecret,
1708
+ deleteTask: () => deleteTask,
882
1709
  detectProvenance: () => detectProvenance,
883
1710
  getRun: () => getRun,
1711
+ getTask: () => getTask,
884
1712
  isIncludedInContentHash: () => isIncludedInContentHash,
1713
+ isTaskIdRef: () => isTaskIdRef,
1714
+ isTaskSpec: () => isTaskSpec,
885
1715
  listEnvSecretKeys: () => listEnvSecretKeys,
886
1716
  listRunConfigs: () => listRunConfigs,
1717
+ listTasks: () => listTasks,
887
1718
  localTreeState: () => localTreeState,
1719
+ openBrowser: () => openBrowser,
888
1720
  openSession: () => openSession,
889
1721
  openWorld: () => openWorld,
1722
+ parseWorldTaskRefs: () => parseWorldTaskRefs,
890
1723
  propose: () => propose,
891
1724
  pull: () => pull,
892
1725
  push: () => push,
893
1726
  readLocalMeta: () => readLocalMeta,
1727
+ redactActionArgs: () => redactActionArgs,
1728
+ resolveBrowserMode: () => resolveBrowserMode,
894
1729
  runSessions: () => runSessions,
895
1730
  schemaFromSignature: () => schemaFromSignature,
896
1731
  setEnvSecret: () => setEnvSecret,
897
1732
  snapshotTreeHashes: () => snapshotTreeHashes,
1733
+ surfaceKinds: () => surfaceKinds,
1734
+ taskLabel: () => taskLabel,
1735
+ uiEntryUrl: () => uiEntryUrl,
1736
+ uiUrl: () => uiUrl,
1737
+ updateTask: () => updateTask,
1738
+ upsertRunConfig: () => upsertRunConfig,
1739
+ validateTask: () => validateTask,
898
1740
  validateWorld: () => validateWorld,
899
1741
  waitForRun: () => waitForRun,
1742
+ withoutUiToken: () => withoutUiToken,
900
1743
  writeLocalMeta: () => writeLocalMeta
901
1744
  });
902
1745
  function resolveEnv(options) {
@@ -967,6 +1810,28 @@ async function listRunConfigs(options = {}) {
967
1810
  );
968
1811
  return res.runConfigs;
969
1812
  }
1813
+ async function upsertRunConfig(input, options = {}) {
1814
+ return apiRequest(
1815
+ options,
1816
+ "POST",
1817
+ "/api/public/benchmark-containers/run-configs",
1818
+ input
1819
+ );
1820
+ }
1821
+ function parseWorldTaskRefs(spec) {
1822
+ const items = (Array.isArray(spec) ? spec : spec.split(",")).map((s) => s.trim()).filter(Boolean);
1823
+ return items.map((item) => {
1824
+ const at = item.lastIndexOf("@");
1825
+ if (at < 0) return { id: item };
1826
+ const id = item.slice(0, at);
1827
+ const version = Number(item.slice(at + 1));
1828
+ if (!id || !Number.isInteger(version) || version < 1)
1829
+ throw new Error(
1830
+ `stored task ref '${item}' is not <id> or <id>@<version> (version a positive integer)`
1831
+ );
1832
+ return { id, version };
1833
+ });
1834
+ }
970
1835
  async function getRun(runId, options = {}) {
971
1836
  return apiRequest(
972
1837
  options,
@@ -1060,6 +1925,8 @@ var init_worlds = __esm({
1060
1925
  "src/worlds/index.ts"() {
1061
1926
  "use strict";
1062
1927
  init_session();
1928
+ init_tasks();
1929
+ init_browser();
1063
1930
  init_hub();
1064
1931
  init_validate();
1065
1932
  WorldTask = class {
@@ -1089,15 +1956,18 @@ var init_worlds = __esm({
1089
1956
  return hit;
1090
1957
  }
1091
1958
  /**
1092
- * Open a LIVE session against one of this world's tasks: the platform boots
1093
- * (or reuses) a warm container, and your agent calls its tools through the
1094
- * platform. See worlds/session.ts.
1959
+ * Open a LIVE session against one of this world's tasks — a bundled task's
1960
+ * name or an inline `WorldTaskSpec`: the platform boots (or reuses) a warm
1961
+ * container, and your agent calls its tools through the platform. See
1962
+ * worlds/session.ts.
1095
1963
  */
1096
1964
  async open(task, opts = {}) {
1097
1965
  const { openSession: openSession2 } = await Promise.resolve().then(() => (init_session(), session_exports));
1098
- return openSession2(this.slug, task, {
1966
+ return openSession2(this.slug, {
1967
+ task,
1099
1968
  versionId: this.version.versionId,
1100
1969
  reuseWarm: opts.reuseWarm,
1970
+ surfaces: opts.surfaces,
1101
1971
  options: this.options
1102
1972
  });
1103
1973
  }
@@ -1129,7 +1999,7 @@ var require_package = __commonJS({
1129
1999
  "package.json"(exports, module) {
1130
2000
  module.exports = {
1131
2001
  name: "@withgateway/sdk",
1132
- version: "0.1.20",
2002
+ version: "0.2.0",
1133
2003
  description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
1134
2004
  main: "./dist/index.js",
1135
2005
  module: "./dist/index.mjs",
@@ -1198,12 +2068,15 @@ var require_package = __commonJS({
1198
2068
  },
1199
2069
  files: [
1200
2070
  "dist",
2071
+ "skills",
2072
+ "runtime",
1201
2073
  "README.md"
1202
2074
  ],
1203
2075
  publishConfig: {
1204
2076
  access: "public"
1205
2077
  },
1206
2078
  scripts: {
2079
+ prebuild: "node scripts/copy-skills.mjs && node scripts/copy-runtime.mjs",
1207
2080
  build: "tsup",
1208
2081
  dev: "tsup --watch",
1209
2082
  typecheck: "tsc --noEmit",
@@ -1236,7 +2109,8 @@ var require_package = __commonJS({
1236
2109
  "@opentelemetry/exporter-trace-otlp-http": ">=0.50.0",
1237
2110
  "@opentelemetry/resources": ">=1.0.0",
1238
2111
  "@opentelemetry/sdk-trace-base": ">=1.0.0",
1239
- "@opentelemetry/sdk-trace-node": ">=1.0.0"
2112
+ "@opentelemetry/sdk-trace-node": ">=1.0.0",
2113
+ playwright: ">=1.40.0"
1240
2114
  },
1241
2115
  peerDependenciesMeta: {
1242
2116
  "@opentelemetry/api": {
@@ -1253,6 +2127,9 @@ var require_package = __commonJS({
1253
2127
  },
1254
2128
  "@opentelemetry/resources": {
1255
2129
  optional: true
2130
+ },
2131
+ playwright: {
2132
+ optional: true
1256
2133
  }
1257
2134
  },
1258
2135
  optionalDependencies: {
@@ -4983,12 +5860,18 @@ var tracing = {
4983
5860
  };
4984
5861
  export {
4985
5862
  AGENT_ID_KEY,
5863
+ BrowserActionRecorder,
5864
+ COMPUTER_USE_SPECS,
4986
5865
  DEFAULT_BRANCH,
4987
5866
  DEFAULT_TIMEOUT_SECONDS,
5867
+ DEFAULT_VIEWPORT,
4988
5868
  DriftError,
4989
5869
  ENV_GATEWAY_HOST,
4990
5870
  ENV_GATEWAY_PUBLIC_KEY,
4991
5871
  ENV_GATEWAY_SECRET_KEY,
5872
+ EVENT_BATCH_SIZE,
5873
+ EVENT_FLUSH_INTERVAL_MS,
5874
+ EVENT_MAX_RETRIES,
4992
5875
  EXPERIMENT_ATTRIBUTES,
4993
5876
  ExperimentClient,
4994
5877
  ExperimentSpanProcessor,
@@ -5015,6 +5898,7 @@ export {
5015
5898
  ReplayTask,
5016
5899
  SUCCESS_METRIC_NAME_KEY,
5017
5900
  SUCCESS_SIGNAL_KEY,
5901
+ SURFACE_KINDS,
5018
5902
  ScoreError,
5019
5903
  ScoresClient,
5020
5904
  SessionLoadError,
@@ -5025,10 +5909,12 @@ export {
5025
5909
  TraceDiff,
5026
5910
  UserProfileError,
5027
5911
  UsersClient,
5912
+ WorldBrowser,
5028
5913
  WorldSession,
5029
5914
  WorldSessionCallError,
5030
5915
  WorldSessionTimeout,
5031
5916
  WorldSet,
5917
+ WorldSurfaceUnavailable,
5032
5918
  WorldTask,
5033
5919
  addExperimentAttributes,
5034
5920
  apiRequest,
@@ -5043,11 +5929,14 @@ export {
5043
5929
  computeBuildHash,
5044
5930
  computeContentHash,
5045
5931
  computeHash,
5932
+ computerUseToolkit,
5046
5933
  context,
5047
5934
  createRef,
5935
+ createTask,
5048
5936
  currentTraceId,
5049
5937
  defineTool,
5050
5938
  deleteEnvSecret,
5939
+ deleteTask,
5051
5940
  detectProvenance,
5052
5941
  experimentContextStorage,
5053
5942
  singleton_exports as experiments,
@@ -5058,26 +5947,34 @@ export {
5058
5947
  getRegisteredSkills,
5059
5948
  getRegisteredTools,
5060
5949
  getRun,
5950
+ getTask,
5061
5951
  identify,
5062
5952
  isIncludedInContentHash,
5953
+ isTaskIdRef,
5954
+ isTaskSpec,
5063
5955
  listEnvSecretKeys,
5064
5956
  listRunConfigs,
5957
+ listTasks,
5065
5958
  loadSession,
5066
5959
  localTreeState,
5067
5960
  memory,
5961
+ openBrowser,
5068
5962
  openSession,
5069
5963
  openWorld,
5964
+ parseWorldTaskRefs,
5070
5965
  personas,
5071
5966
  propose,
5072
5967
  pull,
5073
5968
  push,
5074
5969
  readLocalMeta,
5970
+ redactActionArgs,
5075
5971
  registerArtifact,
5076
5972
  registerPrompt,
5077
5973
  registerSkill,
5078
5974
  renderAgentSystem,
5079
5975
  replay,
5080
5976
  resetBuildRegistry,
5977
+ resolveBrowserMode,
5081
5978
  resolveUserId,
5082
5979
  runSessions,
5083
5980
  runSuite,
@@ -5091,10 +5988,18 @@ export {
5091
5988
  snapshotTreeHashes,
5092
5989
  success,
5093
5990
  suite,
5991
+ surfaceKinds,
5992
+ taskLabel,
5094
5993
  tracing,
5994
+ uiEntryUrl,
5995
+ uiUrl,
5996
+ updateTask,
5997
+ upsertRunConfig,
5095
5998
  users,
5999
+ validateTask,
5096
6000
  validateWorld,
5097
6001
  waitForRun,
6002
+ withoutUiToken,
5098
6003
  writeLocalMeta
5099
6004
  };
5100
6005
  //# sourceMappingURL=index.mjs.map