@withgateway/sdk 0.2.8 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +24 -8
  2. package/dist/cli.js +332 -163
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +332 -163
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +119 -15
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +119 -15
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/index.d.mts +1 -1
  11. package/dist/index.d.ts +1 -1
  12. package/dist/index.js +229 -120
  13. package/dist/index.js.map +1 -1
  14. package/dist/index.mjs +220 -120
  15. package/dist/index.mjs.map +1 -1
  16. package/dist/traces/index.js +119 -15
  17. package/dist/traces/index.js.map +1 -1
  18. package/dist/traces/index.mjs +119 -15
  19. package/dist/traces/index.mjs.map +1 -1
  20. package/dist/tracing/index.js +1 -1
  21. package/dist/tracing/index.js.map +1 -1
  22. package/dist/tracing/index.mjs +1 -1
  23. package/dist/tracing/index.mjs.map +1 -1
  24. package/dist/worlds/index.d.mts +78 -9
  25. package/dist/worlds/index.d.ts +78 -9
  26. package/dist/worlds/index.js +219 -119
  27. package/dist/worlds/index.js.map +1 -1
  28. package/dist/worlds/index.mjs +220 -120
  29. package/dist/worlds/index.mjs.map +1 -1
  30. package/package.json +1 -1
  31. package/runtime/gatewaysdk/environment/_toml.py +3 -10
  32. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +3 -3
  33. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -1
  34. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +11 -11
  35. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  36. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +5 -1
  37. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
  38. package/runtime/gatewaysdk/environment/schema/store.py +15 -6
  39. package/skills/benchmarks-getting-started/SKILL.md +3 -3
  40. package/skills/connector-schema-authoring/SKILL.md +1 -1
  41. package/skills/connector-schema-authoring/world-schema.md +1 -1
  42. package/skills/worlds-getting-started/SKILL.md +11 -11
  43. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  44. package/skills/worlds-getting-started/references/gotchas.md +5 -1
  45. package/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
package/dist/cli.js CHANGED
@@ -127,9 +127,8 @@ function parseArgs(spec, argv) {
127
127
  return { positionals, flags, given };
128
128
  }
129
129
  function looksLikeFlag(token, known) {
130
- if (token.startsWith("--")) return token.length > 2;
131
130
  if (!token.startsWith("-") || token.length < 2) return false;
132
- const name = token.slice(1).split("=")[0];
131
+ const name = token.replace(/^--?/, "").split("=")[0];
133
132
  return known.has(name);
134
133
  }
135
134
  function usageLine(path44, spec) {
@@ -254,7 +253,7 @@ var init_router = __esm({
254
253
  };
255
254
  JSON_FLAG = {
256
255
  name: "json",
257
- help: "Output is JSON (the default for this command; accepted so every read verb takes --json).",
256
+ help: "Output is JSON (the default for this command; accepted so every JSON verb takes --json).",
258
257
  boolean: true
259
258
  };
260
259
  JSON_OUTPUT_FLAG = {
@@ -294,6 +293,115 @@ var init_router = __esm({
294
293
  }
295
294
  });
296
295
 
296
+ // src/worlds/transport.ts
297
+ function platformTimeoutMs(env = process.env) {
298
+ const raw = env[PLATFORM_TIMEOUT_ENV];
299
+ if (raw === void 0 || raw === "") return PLATFORM_TIMEOUT_DEFAULT_MS;
300
+ const value = Number(raw);
301
+ if (Number.isInteger(value) && value > 0) return value;
302
+ throw new Error(`${PLATFORM_TIMEOUT_ENV} must be a positive whole number of milliseconds, not \`${raw}\`.`);
303
+ }
304
+ var PLATFORM_TIMEOUT_ENV, PLATFORM_TIMEOUT_DEFAULT_MS, CHECK_HOST, RETRY, CAUSES, UNKNOWN_CAUSE, TransportCause, UnreachableError, PlatformTransport;
305
+ var init_transport = __esm({
306
+ "src/worlds/transport.ts"() {
307
+ "use strict";
308
+ PLATFORM_TIMEOUT_ENV = "GATEWAY_TIMEOUT_MS";
309
+ PLATFORM_TIMEOUT_DEFAULT_MS = 12e4;
310
+ CHECK_HOST = "Check GATEWAY_HOST (or --host) points at a running platform, then retry.";
311
+ RETRY = "Retry; if it repeats, check the network between here and the platform.";
312
+ CAUSES = {
313
+ ECONNREFUSED: { reason: "connection refused", next: CHECK_HOST },
314
+ ENOTFOUND: { reason: "DNS lookup failed", next: CHECK_HOST },
315
+ EAI_AGAIN: { reason: "DNS lookup failed", next: CHECK_HOST },
316
+ ETIMEDOUT: { reason: "connect timed out", next: CHECK_HOST },
317
+ UND_ERR_CONNECT_TIMEOUT: { reason: "connect timed out", next: CHECK_HOST },
318
+ EHOSTUNREACH: { reason: "host unreachable", next: CHECK_HOST },
319
+ ENETUNREACH: { reason: "network unreachable", next: RETRY },
320
+ ECONNRESET: { reason: "connection dropped", next: RETRY },
321
+ UND_ERR_SOCKET: { reason: "connection dropped", next: RETRY },
322
+ EPIPE: { reason: "connection dropped", next: RETRY }
323
+ };
324
+ UNKNOWN_CAUSE = { reason: "network error", next: CHECK_HOST };
325
+ TransportCause = class _TransportCause {
326
+ constructor(reason, detail, next) {
327
+ this.reason = reason;
328
+ this.detail = detail;
329
+ this.next = next;
330
+ }
331
+ reason;
332
+ detail;
333
+ next;
334
+ static timeout(timeoutMs2) {
335
+ return new _TransportCause(
336
+ `timed out after ${timeoutMs2 / 1e3}s`,
337
+ null,
338
+ `Retry; if the platform is slow, raise ${PLATFORM_TIMEOUT_ENV} (milliseconds per request).`
339
+ );
340
+ }
341
+ static of(error) {
342
+ const cause = error instanceof Error && error.cause instanceof Error ? error.cause : void 0;
343
+ const code = cause && "code" in cause && typeof cause.code === "string" ? cause.code : null;
344
+ const message = cause?.message ?? (error instanceof Error ? error.message : String(error));
345
+ const known = code && CAUSES[code] || UNKNOWN_CAUSE;
346
+ return new _TransportCause(known.reason, code ? `${code}: ${message}` : message, known.next);
347
+ }
348
+ describe() {
349
+ return this.detail === null ? this.reason : `${this.reason} (${this.detail})`;
350
+ }
351
+ };
352
+ UnreachableError = class extends Error {
353
+ constructor(host, method, route, failure) {
354
+ super(`${method} ${route}: no answer from ${host}: ${failure.describe()}. ${failure.next}`);
355
+ this.host = host;
356
+ this.method = method;
357
+ this.route = route;
358
+ this.failure = failure;
359
+ this.name = "UnreachableError";
360
+ }
361
+ host;
362
+ method;
363
+ route;
364
+ failure;
365
+ };
366
+ PlatformTransport = class {
367
+ constructor(endpoint, timeoutMs2 = platformTimeoutMs()) {
368
+ this.endpoint = endpoint;
369
+ this.timeoutMs = timeoutMs2;
370
+ }
371
+ endpoint;
372
+ timeoutMs;
373
+ /** A request that legitimately takes longer (a sandbox exec, a world create) waits its own budget; every other one waits the default. */
374
+ budget(ownMs) {
375
+ return Math.max(ownMs ?? 0, this.timeoutMs);
376
+ }
377
+ async send(method, route, body, opts = {}) {
378
+ const timeoutMs2 = this.budget(opts.timeoutMs);
379
+ const payload = body === void 0 ? {} : { body: JSON.stringify(body) };
380
+ const controller = new AbortController();
381
+ const timer = setTimeout(() => controller.abort(), timeoutMs2);
382
+ try {
383
+ const res = await fetch(`${this.endpoint.host}${route}`, {
384
+ method,
385
+ headers: {
386
+ "content-type": "application/json",
387
+ accept: "application/json",
388
+ authorization: "Basic " + Buffer.from(`${this.endpoint.publicKey}:${this.endpoint.secretKey}`).toString("base64")
389
+ },
390
+ ...payload,
391
+ signal: controller.signal
392
+ });
393
+ return { status: res.status, ok: res.ok, text: await res.text() };
394
+ } catch (error) {
395
+ const cause = controller.signal.aborted ? TransportCause.timeout(timeoutMs2) : TransportCause.of(error);
396
+ throw new UnreachableError(this.endpoint.host, method, route, cause);
397
+ } finally {
398
+ clearTimeout(timer);
399
+ }
400
+ }
401
+ };
402
+ }
403
+ });
404
+
297
405
  // src/worlds/browserReconnect.ts
298
406
  async function closeConnection(c) {
299
407
  await c.context.close();
@@ -2685,7 +2793,7 @@ var require_package = __commonJS({
2685
2793
  "package.json"(exports2, module2) {
2686
2794
  module2.exports = {
2687
2795
  name: "@withgateway/sdk",
2688
- version: "0.2.8",
2796
+ version: "0.2.9",
2689
2797
  description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
2690
2798
  main: "./dist/index.js",
2691
2799
  module: "./dist/index.mjs",
@@ -4790,6 +4898,34 @@ function parseSlugRef(slugRef) {
4790
4898
  if (at === -1) return { slug: slugRef };
4791
4899
  return { slug: slugRef.slice(0, at), ref: slugRef.slice(at + 1) };
4792
4900
  }
4901
+ function rebaseConflicts(error) {
4902
+ if (!(error instanceof ApiError) || error.status !== 409) return null;
4903
+ let body;
4904
+ try {
4905
+ body = JSON.parse(error.text);
4906
+ } catch {
4907
+ return null;
4908
+ }
4909
+ const conflicts = body?.conflicts;
4910
+ if (!Array.isArray(conflicts)) return null;
4911
+ return conflicts.filter(isConflictPath).map(({ path: path44, reason }) => ({ path: path44, reason }));
4912
+ }
4913
+ function isConflictPath(value) {
4914
+ const entry = value;
4915
+ return typeof entry?.path === "string" && typeof entry.reason === "string";
4916
+ }
4917
+ function uncommittedPaths(error) {
4918
+ if (!(error instanceof ApiError) || error.status !== 409 || error.code !== "sandbox_uncommitted") return null;
4919
+ let body;
4920
+ try {
4921
+ body = JSON.parse(error.text);
4922
+ } catch {
4923
+ return null;
4924
+ }
4925
+ const uncommitted = body?.uncommitted;
4926
+ if (!Array.isArray(uncommitted)) return null;
4927
+ return uncommitted.filter((p) => typeof p === "string");
4928
+ }
4793
4929
  function listQuery(filter) {
4794
4930
  const params = new URLSearchParams();
4795
4931
  if (filter.status) params.set("status", filter.status);
@@ -4798,18 +4934,25 @@ function listQuery(filter) {
4798
4934
  const qs3 = params.toString();
4799
4935
  return qs3 ? `?${qs3}` : "";
4800
4936
  }
4801
- var isSandboxImportPending, sid, WorldSandboxClient;
4937
+ var isSandboxImportPending, sid, SANDBOXES, SANDBOX_REQUEST_TIMEOUT_MS, WorldSandboxClient;
4802
4938
  var init_sandbox = __esm({
4803
4939
  "src/worlds/sandbox.ts"() {
4804
4940
  "use strict";
4805
4941
  init_worlds();
4806
4942
  isSandboxImportPending = (answer) => !("versionId" in answer);
4807
4943
  sid = encodeURIComponent;
4944
+ SANDBOXES = "/api/public/benchmark-containers/sandboxes";
4945
+ SANDBOX_REQUEST_TIMEOUT_MS = 66e4;
4808
4946
  WorldSandboxClient = class {
4809
4947
  constructor(options = {}) {
4810
4948
  this.options = options;
4811
4949
  }
4812
4950
  options;
4951
+ request(method, path44, body) {
4952
+ return apiRequest(this.options, method, path44, body, {
4953
+ timeoutMs: SANDBOX_REQUEST_TIMEOUT_MS
4954
+ });
4955
+ }
4813
4956
  /**
4814
4957
  * `{ slug, ref? }` opens a READY version; `{ new, from }` opens a sandbox on
4815
4958
  * a world that does not exist yet (409 `world_exists` if the slug is taken,
@@ -4817,42 +4960,39 @@ var init_sandbox = __esm({
4817
4960
  * creates the world on `main`.
4818
4961
  */
4819
4962
  open(target) {
4820
- return apiRequest(this.options, "POST", "/api/public/benchmark-containers/sandboxes", target);
4963
+ return this.request("POST", `${SANDBOXES}`, target);
4821
4964
  }
4822
4965
  status(sandboxId) {
4823
- return apiRequest(this.options, "GET", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}`);
4966
+ return this.request("GET", `${SANDBOXES}/${sid(sandboxId)}`);
4824
4967
  }
4825
4968
  /** The project's sandboxes, newest first — how an agent finds one it left open. */
4826
4969
  async list(filter = {}) {
4827
- const res = await apiRequest(
4828
- this.options,
4829
- "GET",
4830
- `/api/public/benchmark-containers/sandboxes${listQuery(filter)}`
4831
- );
4970
+ const res = await this.request("GET", `${SANDBOXES}${listQuery(filter)}`);
4832
4971
  return res.sandboxes;
4833
4972
  }
4834
4973
  async read(sandboxId, filePath) {
4835
- const res = await apiRequest(
4836
- this.options,
4974
+ const res = await this.request(
4837
4975
  "GET",
4838
- `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/file?path=${encodeURIComponent(filePath)}`
4976
+ `${SANDBOXES}/${sid(sandboxId)}/file?path=${encodeURIComponent(filePath)}`
4839
4977
  );
4840
4978
  return { path: res.path, size: res.size, bytes: Buffer.from(res.contentBase64, "base64") };
4841
4979
  }
4842
4980
  write(sandboxId, filePath, bytes) {
4843
- return apiRequest(this.options, "PUT", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/file`, {
4981
+ return this.request("PUT", `${SANDBOXES}/${sid(sandboxId)}/file`, {
4844
4982
  path: filePath,
4845
4983
  contentBase64: bytes.toString("base64")
4846
4984
  });
4847
4985
  }
4848
4986
  exec(sandboxId, input) {
4849
- return apiRequest(this.options, "POST", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/exec`, input);
4987
+ return this.request("POST", `${SANDBOXES}/${sid(sandboxId)}/exec`, input);
4850
4988
  }
4851
4989
  check(sandboxId) {
4852
- return apiRequest(this.options, "POST", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/check`, {});
4990
+ return this.request("POST", `${SANDBOXES}/${sid(sandboxId)}/check`, {});
4853
4991
  }
4992
+ /** With `rebase`, a moved base is replayed onto; a 409 then names the conflicting paths (`rebaseConflicts`). */
4854
4993
  commit(sandboxId, input) {
4855
- return apiRequest(this.options, "POST", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/commit`, input);
4994
+ const { rebase, ...rest } = input;
4995
+ return this.request("POST", `${SANDBOXES}/${sid(sandboxId)}/commit`, rebase ? { ...rest, rebase: true } : rest);
4856
4996
  }
4857
4997
  /**
4858
4998
  * A rows file already in the sandbox tree into the PLATFORM world the
@@ -4861,10 +5001,11 @@ var init_sandbox = __esm({
4861
5001
  * tree and never carries data.
4862
5002
  */
4863
5003
  importData(sandboxId, input) {
4864
- return apiRequest(this.options, "POST", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/import`, input);
5004
+ return this.request("POST", `${SANDBOXES}/${sid(sandboxId)}/import`, input);
4865
5005
  }
4866
- close(sandboxId) {
4867
- return apiRequest(this.options, "DELETE", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}`);
5006
+ /** Uncommitted work is a 409 (`uncommittedPaths`) unless `force` discards it. */
5007
+ close(sandboxId, opts = {}) {
5008
+ return this.request("DELETE", `${SANDBOXES}/${sid(sandboxId)}`, opts.force ? { force: true } : void 0);
4868
5009
  }
4869
5010
  };
4870
5011
  }
@@ -5662,7 +5803,7 @@ var init_local = __esm({
5662
5803
  path6 = __toESM(require("path"));
5663
5804
  init_router();
5664
5805
  init_config();
5665
- MIN_PYTHON = [3, 11];
5806
+ MIN_PYTHON = [3, 12];
5666
5807
  DIAGNOSTIC_TAIL = 600;
5667
5808
  BRIDGE_BOOTSTRAP = `import sys,runpy,types,os
5668
5809
  root=sys.argv[1]
@@ -5681,7 +5822,6 @@ runpy.run_module('gatewaysdk.environment.schema',run_name='__main__')`;
5681
5822
  PYTHON_CANDIDATES = [
5682
5823
  "python3.13",
5683
5824
  "python3.12",
5684
- "python3.11",
5685
5825
  "python3",
5686
5826
  "python"
5687
5827
  ];
@@ -5829,45 +5969,31 @@ async function checkSchemaTreeBeforePush(dir) {
5829
5969
  async function runtime(creds, request, opts = {}) {
5830
5970
  const local = localRuntime();
5831
5971
  if (local && runsLocally(request)) {
5832
- const payload = await localBridge(request, local, opts);
5833
- const detail = detailFrom(payload);
5834
- if (detail) throw new BridgeRejected(detail);
5835
- return payload;
5972
+ const payload2 = await localBridge(request, local, opts);
5973
+ const detail2 = detailFrom(payload2);
5974
+ if (detail2) throw new BridgeRejected(detail2);
5975
+ return payload2;
5836
5976
  }
5837
5977
  if (!creds)
5838
5978
  throw new CliError(
5839
5979
  "This needs the schema runtime (the CLI bundles it) or platform credentials (`gateway auth login`). " + localRuntimeReason()
5840
5980
  );
5841
- const controller = new AbortController();
5842
- const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 18e4);
5843
5981
  const route = "/api/public/worlds/runtime";
5982
+ const res = await new PlatformTransport(creds).send("POST", route, request, {
5983
+ timeoutMs: opts.timeoutMs ?? RUNTIME_TIMEOUT_MS
5984
+ });
5985
+ let payload = null;
5844
5986
  try {
5845
- const res = await fetch(`${creds.host}${route}`, {
5846
- method: "POST",
5847
- headers: {
5848
- "content-type": "application/json",
5849
- accept: "application/json",
5850
- authorization: "Basic " + Buffer.from(`${creds.publicKey}:${creds.secretKey}`).toString("base64")
5851
- },
5852
- body: JSON.stringify(request),
5853
- signal: controller.signal
5854
- });
5855
- const text2 = await res.text();
5856
- let payload = null;
5857
- try {
5858
- payload = text2 ? JSON.parse(text2) : {};
5859
- } catch {
5860
- payload = null;
5861
- }
5862
- const detail = detailFrom(payload);
5863
- if (detail) throw new BridgeRejected(detail);
5864
- if (!res.ok)
5865
- throw new CliError(`POST ${route} (${request.command}) -> ${res.status}: ${text2.slice(0, 600)}`, 1);
5866
- if (payload === null) throw new CliError(`POST ${route} (${request.command}) returned non-JSON`, 1);
5867
- return payload;
5868
- } finally {
5869
- clearTimeout(timer);
5987
+ payload = res.text ? JSON.parse(res.text) : {};
5988
+ } catch {
5989
+ payload = null;
5870
5990
  }
5991
+ const detail = detailFrom(payload);
5992
+ if (detail) throw new BridgeRejected(detail);
5993
+ if (!res.ok)
5994
+ throw new CliError(`POST ${route} (${request.command}) -> ${res.status}: ${res.text.slice(0, 600)}`, 1);
5995
+ if (payload === null) throw new CliError(`POST ${route} (${request.command}) returned non-JSON`, 1);
5996
+ return payload;
5871
5997
  }
5872
5998
  function withoutFiles(report) {
5873
5999
  const { files: _files, ...rest } = report;
@@ -5886,7 +6012,7 @@ function sortedJson(value, indent = 2) {
5886
6012
  };
5887
6013
  return JSON.stringify(sort(value), null, indent);
5888
6014
  }
5889
- var fs7, path7, MAX_WORLD_FILES, SKIP_DIRS, BUILD_OUTPUT, BridgeRejected, YAML_NAME;
6015
+ var fs7, path7, MAX_WORLD_FILES, RUNTIME_TIMEOUT_MS, SKIP_DIRS, BUILD_OUTPUT, BridgeRejected, YAML_NAME;
5890
6016
  var init_client = __esm({
5891
6017
  "src/cli/runtime/client.ts"() {
5892
6018
  "use strict";
@@ -5894,7 +6020,9 @@ var init_client = __esm({
5894
6020
  path7 = __toESM(require("path"));
5895
6021
  init_router();
5896
6022
  init_local();
6023
+ init_transport();
5897
6024
  MAX_WORLD_FILES = 2e3;
6025
+ RUNTIME_TIMEOUT_MS = 18e4;
5898
6026
  SKIP_DIRS = /* @__PURE__ */ new Set(["__pycache__", ".git", "node_modules", ".gateway"]);
5899
6027
  BUILD_OUTPUT = /(^|\/)state\.(sqlite|json)$/;
5900
6028
  BridgeRejected = class extends CliError {
@@ -7108,8 +7236,12 @@ __export(worlds_exports, {
7108
7236
  HostedDryRunClient: () => HostedDryRunClient,
7109
7237
  IDLE_WARNING_MINUTES: () => IDLE_WARNING_MINUTES,
7110
7238
  NO_GRADER_REASON: () => NO_GRADER_REASON,
7239
+ PLATFORM_TIMEOUT_DEFAULT_MS: () => PLATFORM_TIMEOUT_DEFAULT_MS,
7240
+ PLATFORM_TIMEOUT_ENV: () => PLATFORM_TIMEOUT_ENV,
7241
+ PlatformTransport: () => PlatformTransport,
7111
7242
  PushSlugConflict: () => PushSlugConflict,
7112
7243
  RECOVER_BUDGET_MS: () => RECOVER_BUDGET_MS,
7244
+ SANDBOX_REQUEST_TIMEOUT_MS: () => SANDBOX_REQUEST_TIMEOUT_MS,
7113
7245
  SESSION_STATES: () => SESSION_STATES,
7114
7246
  STATUS_WAIT_CAP_SECONDS: () => STATUS_WAIT_CAP_SECONDS,
7115
7247
  STRIP_PREFIX: () => STRIP_PREFIX,
@@ -7118,6 +7250,8 @@ __export(worlds_exports, {
7118
7250
  TRANSFORMS: () => TRANSFORMS,
7119
7251
  TaskRun: () => TaskRun,
7120
7252
  TaskSessions: () => TaskSessions,
7253
+ TransportCause: () => TransportCause,
7254
+ UnreachableError: () => UnreachableError,
7121
7255
  VERIFIER_REWARD_PREFIX: () => VERIFIER_REWARD_PREFIX,
7122
7256
  WHITESPACE: () => WHITESPACE,
7123
7257
  WorldBrowser: () => WorldBrowser,
@@ -7185,6 +7319,7 @@ __export(worlds_exports, {
7185
7319
  parseToolCallRecord: () => parseToolCallRecord,
7186
7320
  parseTransform: () => parseTransform,
7187
7321
  parseWorldTaskRefs: () => parseWorldTaskRefs,
7322
+ platformTimeoutMs: () => platformTimeoutMs,
7188
7323
  preserveForm: () => preserveForm,
7189
7324
  propose: () => propose,
7190
7325
  pull: () => pull,
@@ -7196,6 +7331,7 @@ __export(worlds_exports, {
7196
7331
  queryRowsSearch: () => queryRowsSearch,
7197
7332
  readLocalMeta: () => readLocalMeta,
7198
7333
  readToolCallRecords: () => readToolCallRecords,
7334
+ rebaseConflicts: () => rebaseConflicts,
7199
7335
  redactActionArgs: () => redactActionArgs,
7200
7336
  redactionOf: () => redactionOf,
7201
7337
  releaseConnection: () => releaseConnection,
@@ -7218,6 +7354,7 @@ __export(worlds_exports, {
7218
7354
  toolCallsFromObservations: () => toolCallsFromObservations,
7219
7355
  uiEntryUrl: () => uiEntryUrl,
7220
7356
  uiUrl: () => uiUrl,
7357
+ uncommittedPaths: () => uncommittedPaths,
7221
7358
  updateTask: () => updateTask,
7222
7359
  upsertRunConfig: () => upsertRunConfig,
7223
7360
  validateTask: () => validateTask,
@@ -7256,19 +7393,10 @@ function parseErrorBody(text2, limit = 600) {
7256
7393
  code: stableCode
7257
7394
  };
7258
7395
  }
7259
- async function apiRequest(options, method, path44, body) {
7260
- const { host, publicKey, secretKey } = resolveEnv(options);
7261
- const res = await fetch(`${host}${path44}`, {
7262
- method,
7263
- headers: {
7264
- "content-type": "application/json",
7265
- authorization: "Basic " + Buffer.from(`${publicKey}:${secretKey}`).toString("base64")
7266
- },
7267
- ...body === void 0 ? {} : { body: JSON.stringify(body) }
7268
- });
7269
- const text2 = await res.text();
7270
- if (!res.ok) throw new ApiError(res.status, method, path44, text2);
7271
- return JSON.parse(text2);
7396
+ async function apiRequest(options, method, path44, body, init2 = {}) {
7397
+ const reply = await new PlatformTransport(resolveEnv(options)).send(method, path44, body, init2);
7398
+ if (!reply.ok) throw new ApiError(reply.status, method, path44, reply.text);
7399
+ return JSON.parse(reply.text);
7272
7400
  }
7273
7401
  async function setEnvSecret(slug, key2, value, options = {}) {
7274
7402
  return apiRequest(
@@ -7448,6 +7576,8 @@ var ApiError, WorldTask, WorldSet;
7448
7576
  var init_worlds = __esm({
7449
7577
  "src/worlds/index.ts"() {
7450
7578
  "use strict";
7579
+ init_transport();
7580
+ init_transport();
7451
7581
  init_session();
7452
7582
  init_sessionList();
7453
7583
  init_sessionContract();
@@ -7472,14 +7602,16 @@ var init_worlds = __esm({
7472
7602
  init_editSessions();
7473
7603
  init_dryRun();
7474
7604
  ApiError = class extends Error {
7475
- constructor(status, method, path44, body) {
7476
- const parsed = parseErrorBody(body);
7605
+ constructor(status, method, path44, text2) {
7606
+ const parsed = parseErrorBody(text2);
7477
7607
  super(`${method} ${path44} -> ${status}: ${parsed.detail}`);
7478
7608
  this.status = status;
7609
+ this.text = text2;
7479
7610
  this.name = "ApiError";
7480
7611
  this.code = parsed.code;
7481
7612
  }
7482
7613
  status;
7614
+ text;
7483
7615
  code;
7484
7616
  };
7485
7617
  WorldTask = class {
@@ -7559,22 +7691,29 @@ var init_worlds = __esm({
7559
7691
 
7560
7692
  // src/cli/config.ts
7561
7693
  function configPath() {
7562
- return path11.join(
7563
- process.env.GATEWAY_CONFIG_DIR ?? path11.join(os3.homedir(), ".gateway"),
7564
- "config.json"
7565
- );
7694
+ return path11.join(process.env.GATEWAY_CONFIG_DIR || path11.join(os3.homedir(), ".gateway"), "config.json");
7566
7695
  }
7567
7696
  function readConfig() {
7697
+ let stored;
7568
7698
  try {
7569
- return JSON.parse(fs12.readFileSync(configPath(), "utf8"));
7699
+ stored = JSON.parse(fs12.readFileSync(configPath(), "utf8"));
7570
7700
  } catch {
7571
7701
  return {};
7572
7702
  }
7703
+ const record = stored ?? {};
7704
+ return Object.fromEntries(STORED_FIELDS.filter((f) => typeof record[f] === "string").map((f) => [f, record[f]]));
7573
7705
  }
7574
7706
  function writeConfig(config) {
7575
7707
  const file = configPath();
7576
7708
  fs12.mkdirSync(path11.dirname(file), { recursive: true, mode: 448 });
7577
- fs12.writeFileSync(file, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
7709
+ const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW = 0 } = fs12.constants;
7710
+ const fd = fs12.openSync(file, O_WRONLY | O_CREAT | O_TRUNC | O_NOFOLLOW, 384);
7711
+ try {
7712
+ fs12.fchmodSync(fd, 384);
7713
+ fs12.writeFileSync(fd, JSON.stringify(config, null, 2) + "\n");
7714
+ } finally {
7715
+ fs12.closeSync(fd);
7716
+ }
7578
7717
  }
7579
7718
  function clearConfig() {
7580
7719
  try {
@@ -7621,11 +7760,12 @@ function loadEnvFile() {
7621
7760
  }
7622
7761
  return set;
7623
7762
  }
7624
- function resolveCredentials(hostFlag) {
7763
+ function resolveCredentials(hostFlag, secretKeyFlag) {
7625
7764
  const stored = readConfig();
7626
- const host = (hostFlag ?? process.env.GATEWAY_HOST ?? stored.host ?? "").replace(/\/+$/, "");
7627
- const publicKey = process.env.GATEWAY_PUBLIC_KEY ?? stored.public_key ?? "";
7628
- const secretKey = process.env.GATEWAY_SECRET_KEY ?? process.env.GATEWAY_API_KEY ?? stored.api_key ?? "";
7765
+ const host = (hostFlag || process.env.GATEWAY_HOST || stored.host || "").replace(/\/+$/, "");
7766
+ const login = host === (stored.host ?? "").replace(/\/+$/, "") ? stored : {};
7767
+ const publicKey = process.env.GATEWAY_PUBLIC_KEY || login.public_key || "";
7768
+ const secretKey = secretKeyFlag || process.env.GATEWAY_SECRET_KEY || process.env.GATEWAY_API_KEY || login.api_key || "";
7629
7769
  if (!host)
7630
7770
  throw new CliError(
7631
7771
  "Host not configured. Pass --host, set GATEWAY_HOST, or run `gateway auth login`."
@@ -7636,45 +7776,15 @@ function resolveCredentials(hostFlag) {
7636
7776
  );
7637
7777
  return { host, publicKey, secretKey };
7638
7778
  }
7639
- function transportDetail(error, timeoutMs2) {
7640
- if (error instanceof Error && error.name === "AbortError") return `timed out after ${Math.round(timeoutMs2 / 1e3)}s`;
7641
- const cause = error instanceof Error && error.cause instanceof Error ? error.cause : void 0;
7642
- const code = cause && "code" in cause && typeof cause.code === "string" ? `${cause.code}: ` : "";
7643
- const message = cause?.message ?? (error instanceof Error ? error.message : String(error));
7644
- return `${code}${message}`;
7645
- }
7646
7779
  async function api(creds, method, route, body, init2 = {}) {
7647
- const controller = new AbortController();
7648
- const timeoutMs2 = init2.timeoutMs ?? 12e4;
7649
- const timer = setTimeout(() => controller.abort(), timeoutMs2);
7650
- let res;
7651
- try {
7652
- res = await fetch(`${creds.host}${route}`, {
7653
- method,
7654
- headers: {
7655
- "content-type": "application/json",
7656
- accept: "application/json",
7657
- authorization: "Basic " + Buffer.from(`${creds.publicKey}:${creds.secretKey}`).toString("base64")
7658
- },
7659
- ...body === void 0 ? {} : { body: JSON.stringify(body) },
7660
- signal: controller.signal
7661
- });
7662
- } catch (error) {
7663
- clearTimeout(timer);
7664
- throw new UnreachableError(creds.host, method, route, transportDetail(error, timeoutMs2));
7665
- }
7666
- try {
7667
- const text2 = await res.text();
7668
- if (!res.ok) throw new ApiError2(res.status, method, route, text2);
7669
- return text2 ? JSON.parse(text2) : {};
7670
- } finally {
7671
- clearTimeout(timer);
7672
- }
7780
+ const reply = await new PlatformTransport(creds).send(method, route, body, init2);
7781
+ if (!reply.ok) throw new ApiError2(reply.status, method, route, reply.text);
7782
+ return reply.text ? JSON.parse(reply.text) : {};
7673
7783
  }
7674
7784
  function printJson(ctx, value) {
7675
7785
  ctx.stdout(JSON.stringify(value, null, 2));
7676
7786
  }
7677
- var fs12, os3, path11, ENV_FILE_FORM, ApiError2, UnreachableError;
7787
+ var fs12, os3, path11, STORED_FIELDS, ENV_FILE_FORM, ApiError2;
7678
7788
  var init_config = __esm({
7679
7789
  "src/cli/config.ts"() {
7680
7790
  "use strict";
@@ -7683,6 +7793,8 @@ var init_config = __esm({
7683
7793
  path11 = __toESM(require("path"));
7684
7794
  init_router();
7685
7795
  init_worlds();
7796
+ init_transport();
7797
+ STORED_FIELDS = ["host", "public_key", "api_key"];
7686
7798
  ENV_FILE_FORM = "GATEWAY_ENV_FILE=path loads a KEY=value file first: `KEY = value`, quoted values, `export KEY=value` and `#` comments are all accepted; the shell's environment wins.";
7687
7799
  ApiError2 = class extends CliError {
7688
7800
  constructor(status, method, route, text2) {
@@ -7700,19 +7812,6 @@ var init_config = __esm({
7700
7812
  text;
7701
7813
  code;
7702
7814
  };
7703
- UnreachableError = class extends CliError {
7704
- constructor(host, method, route, detail) {
7705
- super(`${method} ${route}: no answer from ${host} (${detail}). Check the host and the network, then retry.`, 1);
7706
- this.host = host;
7707
- this.method = method;
7708
- this.route = route;
7709
- this.detail = detail;
7710
- }
7711
- host;
7712
- method;
7713
- route;
7714
- detail;
7715
- };
7716
7815
  }
7717
7816
  });
7718
7817
 
@@ -7942,29 +8041,16 @@ function browserTierFlag(args) {
7942
8041
  throw new CliError(`--browser-tier must be one of ${BROWSER_TIERS.join(", ")} (got ${tier})`);
7943
8042
  }
7944
8043
  function credentials(args) {
7945
- const creds = resolveCredentials(arg.str(args, "host"));
7946
- const apiKey = arg.str(args, "api-key");
7947
- return apiKey ? { ...creds, secretKey: apiKey } : creds;
8044
+ return resolveCredentials(arg.str(args, "host"), arg.str(args, "api-key"));
7948
8045
  }
7949
8046
  function worldsOptions(creds) {
7950
8047
  return { host: creds.host, publicKey: creds.publicKey, secretKey: creds.secretKey };
7951
8048
  }
7952
8049
  async function rawRequest(creds, method, route, body) {
7953
- const res = await fetch(`${creds.host}${route}`, {
7954
- method,
7955
- headers: {
7956
- "content-type": "application/json",
7957
- accept: "application/json",
7958
- authorization: "Basic " + Buffer.from(`${creds.publicKey}:${creds.secretKey}`).toString("base64")
7959
- },
7960
- ...body === void 0 ? {} : { body: JSON.stringify(body) }
7961
- });
7962
- const text2 = await res.text();
8050
+ const reply = await new PlatformTransport(creds).send(method, route, body);
7963
8051
  return {
7964
- status: res.status,
7965
- ok: res.ok,
7966
- text: text2,
7967
- json: () => text2 ? JSON.parse(text2) : {}
8052
+ ...reply,
8053
+ json: () => reply.text ? JSON.parse(reply.text) : {}
7968
8054
  };
7969
8055
  }
7970
8056
  function query(params) {
@@ -8025,6 +8111,7 @@ var init_shared = __esm({
8025
8111
  init_config();
8026
8112
  init_router();
8027
8113
  init_worlds();
8114
+ init_transport();
8028
8115
  HOST_FLAG = {
8029
8116
  name: "host",
8030
8117
  help: "Gateway server URL (e.g. https://withgateway.ai).",
@@ -15002,13 +15089,13 @@ function registerAuthCommands(root) {
15002
15089
  flags: [
15003
15090
  { name: "host", help: "Gateway server URL", env: "GATEWAY_HOST" },
15004
15091
  { name: "public-key", help: "Project public key (pk-lf-...)", env: "GATEWAY_PUBLIC_KEY" },
15005
- { name: "api-key", help: "Project secret key (sk-lf-...)", env: "GATEWAY_SECRET_KEY" }
15092
+ { name: "api-key", help: "Project secret key (sk-lf-...); GATEWAY_API_KEY also works", env: "GATEWAY_SECRET_KEY" }
15006
15093
  ],
15007
15094
  notes: "The Python CLI prompts for what is missing; here pass all three flags (or set the env vars).\n" + ENV_FILE_FORM,
15008
15095
  run: async (args, ctx) => {
15009
15096
  const host = arg.str(args, "host");
15010
15097
  const publicKey = arg.str(args, "public-key");
15011
- const apiKey = arg.str(args, "api-key");
15098
+ const apiKey = arg.str(args, "api-key") || process.env.GATEWAY_API_KEY;
15012
15099
  if (!host || !publicKey || !apiKey)
15013
15100
  throw new CliError("auth login needs --host, --public-key and --api-key");
15014
15101
  writeConfig({ host: host.replace(/\/+$/, ""), public_key: publicKey, api_key: apiKey });
@@ -15027,7 +15114,7 @@ function registerAuthCommands(root) {
15027
15114
  help: "Show current authentication status.",
15028
15115
  run: async (_args, ctx) => {
15029
15116
  const envHost = process.env.GATEWAY_HOST;
15030
- const envKey = process.env.GATEWAY_SECRET_KEY ?? process.env.GATEWAY_API_KEY;
15117
+ const envKey = process.env.GATEWAY_SECRET_KEY || process.env.GATEWAY_API_KEY;
15031
15118
  if (envHost || envKey) {
15032
15119
  ctx.stdout(`Host: ${envHost ?? "(not set)"} (from environment)`);
15033
15120
  ctx.stdout(`API key: ${envKey ? "configured" : "not set"} (from environment)`);
@@ -16539,6 +16626,23 @@ function assertWriteSize(bytes, filePath) {
16539
16626
  function client2(args) {
16540
16627
  return new WorldSandboxClient(worldsOptions(credentials(args)));
16541
16628
  }
16629
+ function failOnConflict(error) {
16630
+ const conflicts = rebaseConflicts(error);
16631
+ if (conflicts === null) throw error;
16632
+ const lines = conflicts.map((c) => `conflict: ${c.path} (${c.reason})`);
16633
+ throw new CliError([error.message, ...lines].join("\n"), 1);
16634
+ }
16635
+ var UNCOMMITTED_LISTED = 10;
16636
+ function failOnUncommitted(sandboxId, error) {
16637
+ const paths = uncommittedPaths(error);
16638
+ if (paths === null) throw error;
16639
+ const listed = paths.slice(0, UNCOMMITTED_LISTED);
16640
+ const more = paths.length > UNCOMMITTED_LISTED ? ", \u2026" : "";
16641
+ throw new CliError(
16642
+ `${paths.length} uncommitted file(s) (${listed.join(", ")}${more}): commit them (gateway worlds sandbox commit ${sandboxId} -m "<why>") or discard them (gateway worlds sandbox close ${sandboxId} --force)`,
16643
+ 1
16644
+ );
16645
+ }
16542
16646
  function sandboxStatusFilter(value) {
16543
16647
  if (value === void 0 || value === "open" || value === "closed")
16544
16648
  return value;
@@ -16592,6 +16696,7 @@ function sandboxVerbSpecs() {
16592
16696
  specs2 = [
16593
16697
  {
16594
16698
  name: "open",
16699
+ output: "json",
16595
16700
  help: "Open a sandbox on a READY version (source only; the data snapshot stays a pointer), or with --new on a world that does not exist yet. Prints `cli` (the platform's gateway CLI staged for `exec`) or a warning when the image cannot host it.",
16596
16701
  positionals: [
16597
16702
  {
@@ -16695,6 +16800,7 @@ function sandboxVerbSpecs() {
16695
16800
  },
16696
16801
  {
16697
16802
  name: "write",
16803
+ output: "json",
16698
16804
  help: "Write a file (up to 256 KB) into the sandbox tree from a local file, --content, or stdin; larger data goes through `worlds data import`.",
16699
16805
  positionals: [
16700
16806
  SANDBOX_ID,
@@ -16764,6 +16870,7 @@ function sandboxVerbSpecs() {
16764
16870
  },
16765
16871
  {
16766
16872
  name: "check",
16873
+ output: "json",
16767
16874
  help: "Run the push gate on the sandbox tree without committing; exit 1 when it would be refused. Scratch (.gatewayignore + defaults), credential-shaped files (.env, *.pem, id_rsa...) and links are listed as `ignored`, not checked; `warnings` names each held-back path.",
16768
16875
  positionals: [SANDBOX_ID],
16769
16876
  flags: [HOST_FLAG],
@@ -16775,6 +16882,7 @@ function sandboxVerbSpecs() {
16775
16882
  },
16776
16883
  {
16777
16884
  name: "commit",
16885
+ output: "json",
16778
16886
  help: "Commit the sandbox tree as a new version on the base's branch (or --branch); on a new-world sandbox the first commit creates the world on main. Scratch (.gatewayignore + defaults), credential-shaped files and links stay out of the version; `warnings` names what was held back.",
16779
16887
  positionals: [SANDBOX_ID],
16780
16888
  flags: [
@@ -16788,6 +16896,11 @@ function sandboxVerbSpecs() {
16788
16896
  short: "b",
16789
16897
  help: "Branch to move (default: the branch the sandbox was opened on)."
16790
16898
  },
16899
+ {
16900
+ name: "rebase",
16901
+ boolean: true,
16902
+ help: "When the branch moved since the sandbox opened, replay these edits onto its head instead of refusing; a path changed on both sides is a conflict (exit 1, each path on stderr)."
16903
+ },
16791
16904
  HOST_FLAG
16792
16905
  ],
16793
16906
  run: async (args, ctx) => {
@@ -16795,8 +16908,9 @@ function sandboxVerbSpecs() {
16795
16908
  if (!message) throw new CliError("commit needs --message");
16796
16909
  const result = await client2(args).commit(args.positionals[0], {
16797
16910
  message,
16798
- branch: arg.str(args, "branch")
16799
- });
16911
+ branch: arg.str(args, "branch"),
16912
+ rebase: arg.bool(args, "rebase")
16913
+ }).catch((error) => failOnConflict(error));
16800
16914
  printJson(ctx, {
16801
16915
  ...result,
16802
16916
  ...editSessionHint(result.slug, result.editSessionId)
@@ -16805,6 +16919,7 @@ function sandboxVerbSpecs() {
16805
16919
  },
16806
16920
  {
16807
16921
  name: "import",
16922
+ output: "json",
16808
16923
  help: "Import a rows file already in the sandbox tree (curl'ed there, or generated by a script) into the PLATFORM world the sandbox was opened on. The platform reads the file out of the sandbox and streams it through the world-data ledger; no credential enters the sandbox and nothing passes through this machine. Not `commit`, which versions the source tree only.",
16809
16924
  positionals: [
16810
16925
  SANDBOX_ID,
@@ -16872,11 +16987,21 @@ function sandboxVerbSpecs() {
16872
16987
  },
16873
16988
  {
16874
16989
  name: "close",
16875
- help: "Close the sandbox and release its workspace (idempotent).",
16990
+ output: "json",
16991
+ help: "Close the sandbox and release its workspace (idempotent). Refused while the tree holds uncommitted work (exit 1, the paths on stderr); --force discards it.",
16876
16992
  positionals: [SANDBOX_ID],
16877
- flags: [HOST_FLAG],
16993
+ flags: [
16994
+ {
16995
+ name: "force",
16996
+ boolean: true,
16997
+ help: "Close even with uncommitted work, discarding it."
16998
+ },
16999
+ HOST_FLAG
17000
+ ],
16878
17001
  run: async (args, ctx) => {
16879
- printJson(ctx, await client2(args).close(args.positionals[0]));
17002
+ const sandboxId = args.positionals[0];
17003
+ const closed = await client2(args).close(sandboxId, { force: arg.bool(args, "force") }).catch((error) => failOnUncommitted(sandboxId, error));
17004
+ printJson(ctx, closed);
16880
17005
  }
16881
17006
  }
16882
17007
  ];
@@ -18615,7 +18740,7 @@ function discoverResult(doc, where, stderr, commands) {
18615
18740
  function dryRunVerifiers(dir, plan, opts) {
18616
18741
  const commands = [];
18617
18742
  if (opts.here) {
18618
- if (!opts.python) return { executed: false, reason: "no python3 >= 3.11 found; set GATEWAY_PYTHON", commands };
18743
+ if (!opts.python) return { executed: false, reason: "no python3 >= 3.12 found; set GATEWAY_PYTHON", commands };
18619
18744
  const argv = [opts.python, ...plan.here.slice(1)];
18620
18745
  commands.push(shellLine(argv));
18621
18746
  const ran2 = (0, import_node_child_process5.spawnSync)(argv[0], argv.slice(1), { encoding: "utf8", timeout: 6e4 });
@@ -23032,6 +23157,14 @@ init_shared();
23032
23157
  var GATE_PATH = "/api/public/agent-builds/gate";
23033
23158
  var EXIT_CODES = { pass: 0, blocked: 1, untested: 2 };
23034
23159
  var TERMINAL_STATES2 = /* @__PURE__ */ new Set(["COMPLETED", "FAILED", "ERROR", "TIMEOUT", "CANCELLED"]);
23160
+ function gateCredentials(args) {
23161
+ try {
23162
+ return credentials(args);
23163
+ } catch (error) {
23164
+ if (error instanceof CliError) throw new CliError(error.message, 1);
23165
+ throw error;
23166
+ }
23167
+ }
23035
23168
  function buildQuery(opts) {
23036
23169
  const ways = [opts.build !== void 0, opts.agent !== void 0 || opts.version !== void 0, opts.commit !== void 0];
23037
23170
  if (ways.filter(Boolean).length !== 1)
@@ -23136,7 +23269,7 @@ function registerReleaseCommands(root) {
23136
23269
  HOST_FLAG,
23137
23270
  API_KEY_FLAG
23138
23271
  ],
23139
- notes: "Exit codes:\n 0 pass the gate is open on the build's latest run\n 1 blocked the latest run failed the project's rule (reasons printed)\n 2 untested no run recorded this build, or its latest run is still going",
23272
+ notes: "Exit codes:\n 0 pass the gate is open on the build's latest run\n 1 blocked the latest run failed the project's rule (reasons printed), or no credentials\n 2 untested no run recorded this build, or its latest run is still going",
23140
23273
  run: async (args, ctx) => {
23141
23274
  const q = buildQuery({
23142
23275
  build: arg.str(args, "build"),
@@ -23144,7 +23277,7 @@ function registerReleaseCommands(root) {
23144
23277
  version: arg.str(args, "version"),
23145
23278
  commit: arg.str(args, "commit")
23146
23279
  });
23147
- const creds = credentials(args);
23280
+ const creds = gateCredentials(args);
23148
23281
  const asJson = arg.bool(args, "json");
23149
23282
  let result;
23150
23283
  if (arg.bool(args, "wait")) {
@@ -24750,6 +24883,7 @@ function registerSessionCommands(root) {
24750
24883
  const session = root.group("worlds", "Build, seed, serve and run worlds.").group("session", "Live world sessions with api/ui/browser surfaces.");
24751
24884
  session.command({
24752
24885
  name: "open",
24886
+ output: "json",
24753
24887
  help: "Open a live session and print where it answers.",
24754
24888
  positionals: [{ name: "slug", help: "World slug (optionally slug@ref)." }],
24755
24889
  flags: [
@@ -24785,7 +24919,9 @@ function registerSessionCommands(root) {
24785
24919
  },
24786
24920
  HOST_FLAG
24787
24921
  ],
24788
- notes: `Prints {sessionId, ready, surfaces, api.url, ui.entry, browser.wsUrl, task, idleExpiresAt, pinned} \u2014 the descriptor
24922
+ notes: `Before it waits for ready, stderr names the session (\`session <id> opening \u2014 gateway worlds session status <id>\`),
24923
+ so a wait cut short never loses the id.
24924
+ Prints {sessionId, ready, surfaces, api.url, ui.entry, browser.wsUrl, task, idleExpiresAt, pinned} \u2014 the descriptor
24789
24925
  WorldSession.surfaces parses, plus the platform's task block and when the idle TTL reaps the session (null while pinned).
24790
24926
  A World Host session's api also carries \`token\`: send it as \`Authorization: Bearer <token>\`
24791
24927
  (header only, never in the URL) on every request to api.url. The platform refuses (HTTP 400) rather than serving
@@ -24820,6 +24956,9 @@ source (bundled|stored|inline|none)/name/hash/id/version.
24820
24956
  ...idleJson(live)
24821
24957
  });
24822
24958
  if (!arg.bool(args, "no-wait")) {
24959
+ ctx.stderr(
24960
+ `session ${live.sessionId} opening \u2014 gateway worlds session status ${live.sessionId}`
24961
+ );
24823
24962
  try {
24824
24963
  await live.ready();
24825
24964
  } catch (error) {
@@ -24850,6 +24989,7 @@ source (bundled|stored|inline|none)/name/hash/id/version.
24850
24989
  });
24851
24990
  session.command({
24852
24991
  name: "reset",
24992
+ output: "json",
24853
24993
  help: "Put the world back to its opening state (base data + the task's seed); the call log stays.",
24854
24994
  positionals: [{ name: "session_id", help: "Session id." }],
24855
24995
  flags: [HOST_FLAG],
@@ -24864,6 +25004,7 @@ source (bundled|stored|inline|none)/name/hash/id/version.
24864
25004
  });
24865
25005
  session.command({
24866
25006
  name: "grade",
25007
+ output: "json",
24867
25008
  help: "Run the session's task grader against the world's current state and print {reward, rewards, verifiers?, raw}; an exploratory session (no grader) answers {reward: null, reason: 'no grader'}.",
24868
25009
  positionals: [{ name: "session_id", help: "Session id." }],
24869
25010
  flags: [
@@ -24947,6 +25088,7 @@ source (bundled|stored|inline|none)/name/hash/id/version.
24947
25088
  });
24948
25089
  session.command({
24949
25090
  name: "browse",
25091
+ output: "json",
24950
25092
  help: "Open the session's UI in its browser surface and print what the agent would read.",
24951
25093
  positionals: [{ name: "session_id", help: "Session id." }],
24952
25094
  flags: [
@@ -24983,8 +25125,10 @@ source (bundled|stored|inline|none)/name/hash/id/version.
24983
25125
  });
24984
25126
  session.command({
24985
25127
  name: "close",
25128
+ output: "json",
24986
25129
  help: "End a session.",
24987
25130
  positionals: [{ name: "session_id", help: "Session id." }],
25131
+ notes: "A LOST session the fleet is reopening on another host is refused with 409 `session_reopen_in_progress`\n(exit 1): retry once it runs again, and the close reaches its new host.",
24988
25132
  flags: [
24989
25133
  {
24990
25134
  name: "keep-warm",
@@ -25004,8 +25148,29 @@ source (bundled|stored|inline|none)/name/hash/id/version.
25004
25148
  );
25005
25149
  }
25006
25150
  });
25151
+ session.command({
25152
+ name: "reopen",
25153
+ output: "json",
25154
+ help: "Reopen a closed session under the same id, URLs and token from its last checkpoint; prints what `status` prints.",
25155
+ positionals: [{ name: "session_id", help: "Session id." }],
25156
+ flags: [HOST_FLAG],
25157
+ notes: "The checkpoint is the fleet's last export of the session, taken while it ran (a close takes none), so\nwork after that export is not in it. Exit 1 on 409 `session_not_closed` (it still runs),\n`session_no_checkpoint` (never exported: open a new session), `session_reopen_in_progress` (retry)\nor `session_version_unavailable` (the world version's bundle is gone: open a new session).",
25158
+ run: async (args, ctx) => {
25159
+ const sessionId = args.positionals[0];
25160
+ const options = worldsOptions(credentials(args));
25161
+ const state2 = await apiRequest(
25162
+ options,
25163
+ "POST",
25164
+ `${sessionRoute(sessionId)}/reopen`
25165
+ );
25166
+ const live = new WorldSession(sessionId, state2, options);
25167
+ printJson(ctx, { ...state2, ...await surfacesJson(live), ...idleJson(live) });
25168
+ warnIdle(ctx, live);
25169
+ }
25170
+ });
25007
25171
  session.command({
25008
25172
  name: "pin",
25173
+ output: "json",
25009
25174
  help: "Pin a session so the idle reaper never closes it: its URL stays up until you close it. --off unpins.",
25010
25175
  positionals: [{ name: "session_id", help: "Session id." }],
25011
25176
  flags: [
@@ -25031,6 +25196,7 @@ source (bundled|stored|inline|none)/name/hash/id/version.
25031
25196
  });
25032
25197
  session.command({
25033
25198
  name: "seed",
25199
+ output: "json",
25034
25200
  help: "Put rows into a LIVE session's world and wait for the engine's answer.",
25035
25201
  positionals: [
25036
25202
  { name: "session_id", help: "Session id." },
@@ -25975,7 +26141,7 @@ function registerConnectorCommands2(connector) {
25975
26141
  connector.command({
25976
26142
  name: "capture",
25977
26143
  help: "Call the live connection once (following its cursor) and record every page under captures/.",
25978
- notes: "The platform makes the calls (--remote) \u2014 from the pod whose IP the vendor allow-listed, with the\ncredential held as the environment's secret (`gateway secret set`) \u2014 and the redacted pages land in\ncaptures/ here, ready for `connector ingest`. A local capture runs the vendor call from this machine\nand runs on this machine when a python3 >= 3.11 is installed (the CLI bundles the runtime).",
26144
+ notes: "The platform makes the calls (--remote) \u2014 from the pod whose IP the vendor allow-listed, with the\ncredential held as the environment's secret (`gateway secret set`) \u2014 and the redacted pages land in\ncaptures/ here, ready for `connector ingest`. A local capture runs the vendor call from this machine\nand runs on this machine when a python3 >= 3.12 is installed (the CLI bundles the runtime).",
25979
26145
  positionals: [
25980
26146
  { name: "path", help: "World directory holding connector.toml" }
25981
26147
  ],
@@ -26016,7 +26182,7 @@ function registerConnectorCommands2(connector) {
26016
26182
  const local = localRuntime();
26017
26183
  if (!local)
26018
26184
  throw new CliError(
26019
- `local capture runs the vendor call from this machine and needs python3 >= 3.11 (the CLI bundles the runtime). ${localRuntimeReason()} Or use --remote to capture from the platform.`
26185
+ `local capture runs the vendor call from this machine and needs python3 >= 3.12 (the CLI bundles the runtime). ${localRuntimeReason()} Or use --remote to capture from the platform.`
26020
26186
  );
26021
26187
  const argv = ["connector-capture", dir, "--op", op];
26022
26188
  for (const pair2 of arg.list(args, "arg")) argv.push("--arg", pair2);
@@ -26186,7 +26352,7 @@ function registerServeCommand(worlds) {
26186
26352
  worlds.command({
26187
26353
  name: "serve",
26188
26354
  help: "Serve one session of the world here (bundled runtime + python3): its tools over HTTP, the vendor routes when it has them, its ui on its own port when it declares one; or open a hosted api session when no Python is installed.",
26189
- notes: "With a python3 >= 3.11 on this machine the CLI serves the world here from its bundled runtime\n(the same files the platform runs), on --port, in the foreground, as ONE session with state that\nlasts until you stop it or a client closes it. Every schema world gets the session verbs (loopback,\nno credential), the surface an outside agent acts on:\n GET /__session/task {task, prompt, tools, verifiers, worlds: {alias: [verifiers]}}\n GET /__session/tools what it serves: the tools and the connector.toml operations (a dependency's tools as alias.tool)\n POST /__session/call {tool, args} -> {status, body}, as a hosted session answers; an operation by name too\n GET /__session/state rows per entity (a dependency's under worlds.<alias>)\n POST /__session/grade {reward, rewards}: the root's verifiers by name, a dependency's as alias/name\n POST /__session/seed {rows: {entity: [row, ...]}, mode?: append|replace} (a dependency's entity as alias.entity; a\n bare {entity: [row, ...]} is taken as rows); POST /__session/reset back to the start\n POST /__session/close end the session; this command returns\n--task <id> opens the session on one of the world's tasks: its prompt is in the banner and at\n/__session/task, its verifiers grade, and each dependency starts in the scenario its link's `task`\nnames. `gateway worlds call <url> <tool> [--grade] [--close]` acts on the session from another shell.\nA world with a connector.toml serves its vendor routes beside them, and with `[ui]` its page on its own\nport (--ui-port, default the port after --port) at /, the layout the host serves it in, so a frontend\nbuilt for the root works unchanged; the same page is at /__ui/ on --port. The page's api_path calls are\nanswered with the pin; the bare routes still need it. `[dependencies]` entries with\na `path` open beside the root. A --port another process holds is refused by name (its pid when lsof\ncan see it): this serve never answers from another server. The runtime closes when the process that\nstarted it is gone, so a killed CLI leaves no server on the port. Without a python3 it does what `gateway worlds session open <slug>\n--task <scenario> --surface api --no-wait` does: the platform serves the world's vendor API for one\nsession, and the session id + api url are printed. Close it with `gateway worlds session close <id>`.\nGATEWAY_RUNTIME=platform forces the hosted path.",
26355
+ notes: "With a python3 >= 3.12 on this machine the CLI serves the world here from its bundled runtime\n(the same files the platform runs), on --port, in the foreground, as ONE session with state that\nlasts until you stop it or a client closes it. Every schema world gets the session verbs (loopback,\nno credential), the surface an outside agent acts on:\n GET /__session/task {task, prompt, tools, verifiers, worlds: {alias: [verifiers]}}\n GET /__session/tools what it serves: the tools and the connector.toml operations (a dependency's tools as alias.tool)\n POST /__session/call {tool, args} -> {status, body}, as a hosted session answers; an operation by name too\n GET /__session/state rows per entity (a dependency's under worlds.<alias>)\n POST /__session/grade {reward, rewards}: the root's verifiers by name, a dependency's as alias/name\n POST /__session/seed {rows: {entity: [row, ...]}, mode?: append|replace} (a dependency's entity as alias.entity; a\n bare {entity: [row, ...]} is taken as rows); POST /__session/reset back to the start\n POST /__session/close end the session; this command returns\n--task <id> opens the session on one of the world's tasks: its prompt is in the banner and at\n/__session/task, its verifiers grade, and each dependency starts in the scenario its link's `task`\nnames. `gateway worlds call <url> <tool> [--grade] [--close]` acts on the session from another shell.\nA world with a connector.toml serves its vendor routes beside them, and with `[ui]` its page on its own\nport (--ui-port, default the port after --port) at /, the layout the host serves it in, so a frontend\nbuilt for the root works unchanged; the same page is at /__ui/ on --port. The page's api_path calls are\nanswered with the pin; the bare routes still need it. `[dependencies]` entries with\na `path` open beside the root. A --port another process holds is refused by name (its pid when lsof\ncan see it): this serve never answers from another server. The runtime closes when the process that\nstarted it is gone, so a killed CLI leaves no server on the port. Without a python3 it does what `gateway worlds session open <slug>\n--task <scenario> --surface api --no-wait` does: the platform serves the world's vendor API for one\nsession, and the session id + api url are printed. Close it with `gateway worlds session close <id>`.\nGATEWAY_RUNTIME=platform forces the hosted path.",
26190
26356
  positionals: [
26191
26357
  {
26192
26358
  name: "path",
@@ -26632,7 +26798,7 @@ function registerCallCommand(worlds) {
26632
26798
  { name: "close", help: "On a served session (url) or a hosted one (id): end it after the call.", boolean: true },
26633
26799
  HOST_FLAG
26634
26800
  ],
26635
- notes: 'The world is opened in place, so `[dependencies]` entries with a `path` open beside it and their tools\nanswer as alias.tool; a pin without a path is refused here (add path = "../<dir>"). The world\'s handlers\nrun on this machine through the bundled runtime (a python3 >= 3.11); the platform never runs them for you.\nExit 0 when the tool answered 2xx, 1 otherwise: a refused call (unknown tool, arguments off the schema, a\ntool outside --task\'s allow-list) prints the refusal. A handler\'s own bug (an AttributeError, TypeError or\nNameError \u2014 say store.upsert, which does not exist) is a 400 {error: "handler", detail, handler}; anything\nelse the handler raises is a 500 {error: "engine", detail, handler}. Never a bare exception string.\n' + STORE_API_NOTE + `
26801
+ notes: 'The world is opened in place, so `[dependencies]` entries with a `path` open beside it and their tools\nanswer as alias.tool; a pin without a path is refused here (add path = "../<dir>"). The world\'s handlers\nrun on this machine through the bundled runtime (a python3 >= 3.12); the platform never runs them for you.\nExit 0 when the tool answered 2xx, 1 otherwise: a refused call (unknown tool, arguments off the schema, a\ntool outside --task\'s allow-list) prints the refusal. A handler\'s own bug (an AttributeError, TypeError or\nNameError \u2014 say store.upsert, which does not exist) is a 400 {error: "handler", detail, handler}; anything\nelse the handler raises is a 500 {error: "engine", detail, handler}. Never a bare exception string.\n' + STORE_API_NOTE + `
26636
26802
  With a url (the \`url\` \`gateway worlds serve <dir> --task <id>\` prints) the call goes to THAT session over
26637
26803
  POST /__session/call, so state carries from call to call, --state/--grade read it, and --close ends it;
26638
26804
  --task and --scenario belong to the serve. This is the outside-agent path: any HTTP client does the same.
@@ -27830,7 +27996,7 @@ function registerRuntimeCommands(root) {
27830
27996
  var fs56 = __toESM(require("fs"));
27831
27997
  var path43 = __toESM(require("path"));
27832
27998
  function cliVersion() {
27833
- if (true) return "0.2.8";
27999
+ if (true) return "0.2.9";
27834
28000
  if (typeof __dirname !== "string") return "unknown";
27835
28001
  try {
27836
28002
  const pkg = JSON.parse(fs56.readFileSync(path43.resolve(__dirname, "../../package.json"), "utf8"));
@@ -27841,10 +28007,13 @@ function cliVersion() {
27841
28007
  }
27842
28008
 
27843
28009
  // src/cli/main.ts
28010
+ init_transport();
27844
28011
  function buildCli() {
27845
28012
  const root = new CommandGroup(
27846
28013
  "gateway",
27847
- "Gateway: worlds, benchmarks, connectors, sessions, runs and releases from the terminal.\n\n Credentials: --host or GATEWAY_HOST, plus GATEWAY_PUBLIC_KEY and GATEWAY_SECRET_KEY,\n or `gateway auth login`. " + ENV_FILE_FORM + "\n `gateway --version` prints the installed package version."
28014
+ "Gateway: worlds, benchmarks, connectors, sessions, runs and releases from the terminal.\n\n Credentials: --host or GATEWAY_HOST, plus GATEWAY_PUBLIC_KEY and GATEWAY_SECRET_KEY,\n or `gateway auth login`. " + ENV_FILE_FORM + `
28015
+ ${PLATFORM_TIMEOUT_ENV}: milliseconds one platform request may go unanswered (default ${PLATFORM_TIMEOUT_DEFAULT_MS}).
28016
+ \`gateway --version\` prints the installed package version.`
27848
28017
  );
27849
28018
  root.version = cliVersion();
27850
28019
  root.notes = "Start here: `gateway worlds --help` (a mock world of a vendor) or `gateway benchmarks --help` (a benchmark:\na world with tasks, or a harbor / verifiers container benchmark). Packaged guides for an agent:\n`gateway skill search <words>` finds one by topic,\n`gateway worlds skill worlds-getting-started` / `benchmarks-getting-started` prints it.";