@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.mjs CHANGED
@@ -114,9 +114,8 @@ function parseArgs(spec, argv) {
114
114
  return { positionals, flags, given };
115
115
  }
116
116
  function looksLikeFlag(token, known) {
117
- if (token.startsWith("--")) return token.length > 2;
118
117
  if (!token.startsWith("-") || token.length < 2) return false;
119
- const name = token.slice(1).split("=")[0];
118
+ const name = token.replace(/^--?/, "").split("=")[0];
120
119
  return known.has(name);
121
120
  }
122
121
  function usageLine(path44, spec) {
@@ -241,7 +240,7 @@ var init_router = __esm({
241
240
  };
242
241
  JSON_FLAG = {
243
242
  name: "json",
244
- help: "Output is JSON (the default for this command; accepted so every read verb takes --json).",
243
+ help: "Output is JSON (the default for this command; accepted so every JSON verb takes --json).",
245
244
  boolean: true
246
245
  };
247
246
  JSON_OUTPUT_FLAG = {
@@ -281,6 +280,115 @@ var init_router = __esm({
281
280
  }
282
281
  });
283
282
 
283
+ // src/worlds/transport.ts
284
+ function platformTimeoutMs(env = process.env) {
285
+ const raw = env[PLATFORM_TIMEOUT_ENV];
286
+ if (raw === void 0 || raw === "") return PLATFORM_TIMEOUT_DEFAULT_MS;
287
+ const value = Number(raw);
288
+ if (Number.isInteger(value) && value > 0) return value;
289
+ throw new Error(`${PLATFORM_TIMEOUT_ENV} must be a positive whole number of milliseconds, not \`${raw}\`.`);
290
+ }
291
+ var PLATFORM_TIMEOUT_ENV, PLATFORM_TIMEOUT_DEFAULT_MS, CHECK_HOST, RETRY, CAUSES, UNKNOWN_CAUSE, TransportCause, UnreachableError, PlatformTransport;
292
+ var init_transport = __esm({
293
+ "src/worlds/transport.ts"() {
294
+ "use strict";
295
+ PLATFORM_TIMEOUT_ENV = "GATEWAY_TIMEOUT_MS";
296
+ PLATFORM_TIMEOUT_DEFAULT_MS = 12e4;
297
+ CHECK_HOST = "Check GATEWAY_HOST (or --host) points at a running platform, then retry.";
298
+ RETRY = "Retry; if it repeats, check the network between here and the platform.";
299
+ CAUSES = {
300
+ ECONNREFUSED: { reason: "connection refused", next: CHECK_HOST },
301
+ ENOTFOUND: { reason: "DNS lookup failed", next: CHECK_HOST },
302
+ EAI_AGAIN: { reason: "DNS lookup failed", next: CHECK_HOST },
303
+ ETIMEDOUT: { reason: "connect timed out", next: CHECK_HOST },
304
+ UND_ERR_CONNECT_TIMEOUT: { reason: "connect timed out", next: CHECK_HOST },
305
+ EHOSTUNREACH: { reason: "host unreachable", next: CHECK_HOST },
306
+ ENETUNREACH: { reason: "network unreachable", next: RETRY },
307
+ ECONNRESET: { reason: "connection dropped", next: RETRY },
308
+ UND_ERR_SOCKET: { reason: "connection dropped", next: RETRY },
309
+ EPIPE: { reason: "connection dropped", next: RETRY }
310
+ };
311
+ UNKNOWN_CAUSE = { reason: "network error", next: CHECK_HOST };
312
+ TransportCause = class _TransportCause {
313
+ constructor(reason, detail, next) {
314
+ this.reason = reason;
315
+ this.detail = detail;
316
+ this.next = next;
317
+ }
318
+ reason;
319
+ detail;
320
+ next;
321
+ static timeout(timeoutMs2) {
322
+ return new _TransportCause(
323
+ `timed out after ${timeoutMs2 / 1e3}s`,
324
+ null,
325
+ `Retry; if the platform is slow, raise ${PLATFORM_TIMEOUT_ENV} (milliseconds per request).`
326
+ );
327
+ }
328
+ static of(error) {
329
+ const cause = error instanceof Error && error.cause instanceof Error ? error.cause : void 0;
330
+ const code = cause && "code" in cause && typeof cause.code === "string" ? cause.code : null;
331
+ const message = cause?.message ?? (error instanceof Error ? error.message : String(error));
332
+ const known = code && CAUSES[code] || UNKNOWN_CAUSE;
333
+ return new _TransportCause(known.reason, code ? `${code}: ${message}` : message, known.next);
334
+ }
335
+ describe() {
336
+ return this.detail === null ? this.reason : `${this.reason} (${this.detail})`;
337
+ }
338
+ };
339
+ UnreachableError = class extends Error {
340
+ constructor(host, method, route, failure) {
341
+ super(`${method} ${route}: no answer from ${host}: ${failure.describe()}. ${failure.next}`);
342
+ this.host = host;
343
+ this.method = method;
344
+ this.route = route;
345
+ this.failure = failure;
346
+ this.name = "UnreachableError";
347
+ }
348
+ host;
349
+ method;
350
+ route;
351
+ failure;
352
+ };
353
+ PlatformTransport = class {
354
+ constructor(endpoint, timeoutMs2 = platformTimeoutMs()) {
355
+ this.endpoint = endpoint;
356
+ this.timeoutMs = timeoutMs2;
357
+ }
358
+ endpoint;
359
+ timeoutMs;
360
+ /** A request that legitimately takes longer (a sandbox exec, a world create) waits its own budget; every other one waits the default. */
361
+ budget(ownMs) {
362
+ return Math.max(ownMs ?? 0, this.timeoutMs);
363
+ }
364
+ async send(method, route, body, opts = {}) {
365
+ const timeoutMs2 = this.budget(opts.timeoutMs);
366
+ const payload = body === void 0 ? {} : { body: JSON.stringify(body) };
367
+ const controller = new AbortController();
368
+ const timer = setTimeout(() => controller.abort(), timeoutMs2);
369
+ try {
370
+ const res = await fetch(`${this.endpoint.host}${route}`, {
371
+ method,
372
+ headers: {
373
+ "content-type": "application/json",
374
+ accept: "application/json",
375
+ authorization: "Basic " + Buffer.from(`${this.endpoint.publicKey}:${this.endpoint.secretKey}`).toString("base64")
376
+ },
377
+ ...payload,
378
+ signal: controller.signal
379
+ });
380
+ return { status: res.status, ok: res.ok, text: await res.text() };
381
+ } catch (error) {
382
+ const cause = controller.signal.aborted ? TransportCause.timeout(timeoutMs2) : TransportCause.of(error);
383
+ throw new UnreachableError(this.endpoint.host, method, route, cause);
384
+ } finally {
385
+ clearTimeout(timer);
386
+ }
387
+ }
388
+ };
389
+ }
390
+ });
391
+
284
392
  // src/worlds/browserReconnect.ts
285
393
  async function closeConnection(c) {
286
394
  await c.context.close();
@@ -2672,7 +2780,7 @@ var require_package = __commonJS({
2672
2780
  "package.json"(exports, module) {
2673
2781
  module.exports = {
2674
2782
  name: "@withgateway/sdk",
2675
- version: "0.2.8",
2783
+ version: "0.2.9",
2676
2784
  description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
2677
2785
  main: "./dist/index.js",
2678
2786
  module: "./dist/index.mjs",
@@ -4777,6 +4885,34 @@ function parseSlugRef(slugRef) {
4777
4885
  if (at === -1) return { slug: slugRef };
4778
4886
  return { slug: slugRef.slice(0, at), ref: slugRef.slice(at + 1) };
4779
4887
  }
4888
+ function rebaseConflicts(error) {
4889
+ if (!(error instanceof ApiError) || error.status !== 409) return null;
4890
+ let body;
4891
+ try {
4892
+ body = JSON.parse(error.text);
4893
+ } catch {
4894
+ return null;
4895
+ }
4896
+ const conflicts = body?.conflicts;
4897
+ if (!Array.isArray(conflicts)) return null;
4898
+ return conflicts.filter(isConflictPath).map(({ path: path44, reason }) => ({ path: path44, reason }));
4899
+ }
4900
+ function isConflictPath(value) {
4901
+ const entry = value;
4902
+ return typeof entry?.path === "string" && typeof entry.reason === "string";
4903
+ }
4904
+ function uncommittedPaths(error) {
4905
+ if (!(error instanceof ApiError) || error.status !== 409 || error.code !== "sandbox_uncommitted") return null;
4906
+ let body;
4907
+ try {
4908
+ body = JSON.parse(error.text);
4909
+ } catch {
4910
+ return null;
4911
+ }
4912
+ const uncommitted = body?.uncommitted;
4913
+ if (!Array.isArray(uncommitted)) return null;
4914
+ return uncommitted.filter((p) => typeof p === "string");
4915
+ }
4780
4916
  function listQuery(filter) {
4781
4917
  const params = new URLSearchParams();
4782
4918
  if (filter.status) params.set("status", filter.status);
@@ -4785,18 +4921,25 @@ function listQuery(filter) {
4785
4921
  const qs3 = params.toString();
4786
4922
  return qs3 ? `?${qs3}` : "";
4787
4923
  }
4788
- var isSandboxImportPending, sid, WorldSandboxClient;
4924
+ var isSandboxImportPending, sid, SANDBOXES, SANDBOX_REQUEST_TIMEOUT_MS, WorldSandboxClient;
4789
4925
  var init_sandbox = __esm({
4790
4926
  "src/worlds/sandbox.ts"() {
4791
4927
  "use strict";
4792
4928
  init_worlds();
4793
4929
  isSandboxImportPending = (answer) => !("versionId" in answer);
4794
4930
  sid = encodeURIComponent;
4931
+ SANDBOXES = "/api/public/benchmark-containers/sandboxes";
4932
+ SANDBOX_REQUEST_TIMEOUT_MS = 66e4;
4795
4933
  WorldSandboxClient = class {
4796
4934
  constructor(options = {}) {
4797
4935
  this.options = options;
4798
4936
  }
4799
4937
  options;
4938
+ request(method, path44, body) {
4939
+ return apiRequest(this.options, method, path44, body, {
4940
+ timeoutMs: SANDBOX_REQUEST_TIMEOUT_MS
4941
+ });
4942
+ }
4800
4943
  /**
4801
4944
  * `{ slug, ref? }` opens a READY version; `{ new, from }` opens a sandbox on
4802
4945
  * a world that does not exist yet (409 `world_exists` if the slug is taken,
@@ -4804,42 +4947,39 @@ var init_sandbox = __esm({
4804
4947
  * creates the world on `main`.
4805
4948
  */
4806
4949
  open(target) {
4807
- return apiRequest(this.options, "POST", "/api/public/benchmark-containers/sandboxes", target);
4950
+ return this.request("POST", `${SANDBOXES}`, target);
4808
4951
  }
4809
4952
  status(sandboxId) {
4810
- return apiRequest(this.options, "GET", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}`);
4953
+ return this.request("GET", `${SANDBOXES}/${sid(sandboxId)}`);
4811
4954
  }
4812
4955
  /** The project's sandboxes, newest first — how an agent finds one it left open. */
4813
4956
  async list(filter = {}) {
4814
- const res = await apiRequest(
4815
- this.options,
4816
- "GET",
4817
- `/api/public/benchmark-containers/sandboxes${listQuery(filter)}`
4818
- );
4957
+ const res = await this.request("GET", `${SANDBOXES}${listQuery(filter)}`);
4819
4958
  return res.sandboxes;
4820
4959
  }
4821
4960
  async read(sandboxId, filePath) {
4822
- const res = await apiRequest(
4823
- this.options,
4961
+ const res = await this.request(
4824
4962
  "GET",
4825
- `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/file?path=${encodeURIComponent(filePath)}`
4963
+ `${SANDBOXES}/${sid(sandboxId)}/file?path=${encodeURIComponent(filePath)}`
4826
4964
  );
4827
4965
  return { path: res.path, size: res.size, bytes: Buffer.from(res.contentBase64, "base64") };
4828
4966
  }
4829
4967
  write(sandboxId, filePath, bytes) {
4830
- return apiRequest(this.options, "PUT", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/file`, {
4968
+ return this.request("PUT", `${SANDBOXES}/${sid(sandboxId)}/file`, {
4831
4969
  path: filePath,
4832
4970
  contentBase64: bytes.toString("base64")
4833
4971
  });
4834
4972
  }
4835
4973
  exec(sandboxId, input) {
4836
- return apiRequest(this.options, "POST", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/exec`, input);
4974
+ return this.request("POST", `${SANDBOXES}/${sid(sandboxId)}/exec`, input);
4837
4975
  }
4838
4976
  check(sandboxId) {
4839
- return apiRequest(this.options, "POST", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/check`, {});
4977
+ return this.request("POST", `${SANDBOXES}/${sid(sandboxId)}/check`, {});
4840
4978
  }
4979
+ /** With `rebase`, a moved base is replayed onto; a 409 then names the conflicting paths (`rebaseConflicts`). */
4841
4980
  commit(sandboxId, input) {
4842
- return apiRequest(this.options, "POST", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/commit`, input);
4981
+ const { rebase, ...rest } = input;
4982
+ return this.request("POST", `${SANDBOXES}/${sid(sandboxId)}/commit`, rebase ? { ...rest, rebase: true } : rest);
4843
4983
  }
4844
4984
  /**
4845
4985
  * A rows file already in the sandbox tree into the PLATFORM world the
@@ -4848,10 +4988,11 @@ var init_sandbox = __esm({
4848
4988
  * tree and never carries data.
4849
4989
  */
4850
4990
  importData(sandboxId, input) {
4851
- return apiRequest(this.options, "POST", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}/import`, input);
4991
+ return this.request("POST", `${SANDBOXES}/${sid(sandboxId)}/import`, input);
4852
4992
  }
4853
- close(sandboxId) {
4854
- return apiRequest(this.options, "DELETE", `/api/public/benchmark-containers/sandboxes/${sid(sandboxId)}`);
4993
+ /** Uncommitted work is a 409 (`uncommittedPaths`) unless `force` discards it. */
4994
+ close(sandboxId, opts = {}) {
4995
+ return this.request("DELETE", `${SANDBOXES}/${sid(sandboxId)}`, opts.force ? { force: true } : void 0);
4855
4996
  }
4856
4997
  };
4857
4998
  }
@@ -5649,7 +5790,7 @@ var init_local = __esm({
5649
5790
  "use strict";
5650
5791
  init_router();
5651
5792
  init_config();
5652
- MIN_PYTHON = [3, 11];
5793
+ MIN_PYTHON = [3, 12];
5653
5794
  DIAGNOSTIC_TAIL = 600;
5654
5795
  BRIDGE_BOOTSTRAP = `import sys,runpy,types,os
5655
5796
  root=sys.argv[1]
@@ -5668,7 +5809,6 @@ runpy.run_module('gatewaysdk.environment.schema',run_name='__main__')`;
5668
5809
  PYTHON_CANDIDATES = [
5669
5810
  "python3.13",
5670
5811
  "python3.12",
5671
- "python3.11",
5672
5812
  "python3",
5673
5813
  "python"
5674
5814
  ];
@@ -5818,45 +5958,31 @@ async function checkSchemaTreeBeforePush(dir) {
5818
5958
  async function runtime(creds, request, opts = {}) {
5819
5959
  const local = localRuntime();
5820
5960
  if (local && runsLocally(request)) {
5821
- const payload = await localBridge(request, local, opts);
5822
- const detail = detailFrom(payload);
5823
- if (detail) throw new BridgeRejected(detail);
5824
- return payload;
5961
+ const payload2 = await localBridge(request, local, opts);
5962
+ const detail2 = detailFrom(payload2);
5963
+ if (detail2) throw new BridgeRejected(detail2);
5964
+ return payload2;
5825
5965
  }
5826
5966
  if (!creds)
5827
5967
  throw new CliError(
5828
5968
  "This needs the schema runtime (the CLI bundles it) or platform credentials (`gateway auth login`). " + localRuntimeReason()
5829
5969
  );
5830
- const controller = new AbortController();
5831
- const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 18e4);
5832
5970
  const route = "/api/public/worlds/runtime";
5971
+ const res = await new PlatformTransport(creds).send("POST", route, request, {
5972
+ timeoutMs: opts.timeoutMs ?? RUNTIME_TIMEOUT_MS
5973
+ });
5974
+ let payload = null;
5833
5975
  try {
5834
- const res = await fetch(`${creds.host}${route}`, {
5835
- method: "POST",
5836
- headers: {
5837
- "content-type": "application/json",
5838
- accept: "application/json",
5839
- authorization: "Basic " + Buffer.from(`${creds.publicKey}:${creds.secretKey}`).toString("base64")
5840
- },
5841
- body: JSON.stringify(request),
5842
- signal: controller.signal
5843
- });
5844
- const text2 = await res.text();
5845
- let payload = null;
5846
- try {
5847
- payload = text2 ? JSON.parse(text2) : {};
5848
- } catch {
5849
- payload = null;
5850
- }
5851
- const detail = detailFrom(payload);
5852
- if (detail) throw new BridgeRejected(detail);
5853
- if (!res.ok)
5854
- throw new CliError(`POST ${route} (${request.command}) -> ${res.status}: ${text2.slice(0, 600)}`, 1);
5855
- if (payload === null) throw new CliError(`POST ${route} (${request.command}) returned non-JSON`, 1);
5856
- return payload;
5857
- } finally {
5858
- clearTimeout(timer);
5976
+ payload = res.text ? JSON.parse(res.text) : {};
5977
+ } catch {
5978
+ payload = null;
5859
5979
  }
5980
+ const detail = detailFrom(payload);
5981
+ if (detail) throw new BridgeRejected(detail);
5982
+ if (!res.ok)
5983
+ throw new CliError(`POST ${route} (${request.command}) -> ${res.status}: ${res.text.slice(0, 600)}`, 1);
5984
+ if (payload === null) throw new CliError(`POST ${route} (${request.command}) returned non-JSON`, 1);
5985
+ return payload;
5860
5986
  }
5861
5987
  function withoutFiles(report) {
5862
5988
  const { files: _files, ...rest } = report;
@@ -5875,13 +6001,15 @@ function sortedJson(value, indent = 2) {
5875
6001
  };
5876
6002
  return JSON.stringify(sort(value), null, indent);
5877
6003
  }
5878
- var MAX_WORLD_FILES, SKIP_DIRS, BUILD_OUTPUT, BridgeRejected, YAML_NAME;
6004
+ var MAX_WORLD_FILES, RUNTIME_TIMEOUT_MS, SKIP_DIRS, BUILD_OUTPUT, BridgeRejected, YAML_NAME;
5879
6005
  var init_client = __esm({
5880
6006
  "src/cli/runtime/client.ts"() {
5881
6007
  "use strict";
5882
6008
  init_router();
5883
6009
  init_local();
6010
+ init_transport();
5884
6011
  MAX_WORLD_FILES = 2e3;
6012
+ RUNTIME_TIMEOUT_MS = 18e4;
5885
6013
  SKIP_DIRS = /* @__PURE__ */ new Set(["__pycache__", ".git", "node_modules", ".gateway"]);
5886
6014
  BUILD_OUTPUT = /(^|\/)state\.(sqlite|json)$/;
5887
6015
  BridgeRejected = class extends CliError {
@@ -7094,8 +7222,12 @@ __export(worlds_exports, {
7094
7222
  HostedDryRunClient: () => HostedDryRunClient,
7095
7223
  IDLE_WARNING_MINUTES: () => IDLE_WARNING_MINUTES,
7096
7224
  NO_GRADER_REASON: () => NO_GRADER_REASON,
7225
+ PLATFORM_TIMEOUT_DEFAULT_MS: () => PLATFORM_TIMEOUT_DEFAULT_MS,
7226
+ PLATFORM_TIMEOUT_ENV: () => PLATFORM_TIMEOUT_ENV,
7227
+ PlatformTransport: () => PlatformTransport,
7097
7228
  PushSlugConflict: () => PushSlugConflict,
7098
7229
  RECOVER_BUDGET_MS: () => RECOVER_BUDGET_MS,
7230
+ SANDBOX_REQUEST_TIMEOUT_MS: () => SANDBOX_REQUEST_TIMEOUT_MS,
7099
7231
  SESSION_STATES: () => SESSION_STATES,
7100
7232
  STATUS_WAIT_CAP_SECONDS: () => STATUS_WAIT_CAP_SECONDS,
7101
7233
  STRIP_PREFIX: () => STRIP_PREFIX,
@@ -7104,6 +7236,8 @@ __export(worlds_exports, {
7104
7236
  TRANSFORMS: () => TRANSFORMS,
7105
7237
  TaskRun: () => TaskRun,
7106
7238
  TaskSessions: () => TaskSessions,
7239
+ TransportCause: () => TransportCause,
7240
+ UnreachableError: () => UnreachableError,
7107
7241
  VERIFIER_REWARD_PREFIX: () => VERIFIER_REWARD_PREFIX,
7108
7242
  WHITESPACE: () => WHITESPACE,
7109
7243
  WorldBrowser: () => WorldBrowser,
@@ -7171,6 +7305,7 @@ __export(worlds_exports, {
7171
7305
  parseToolCallRecord: () => parseToolCallRecord,
7172
7306
  parseTransform: () => parseTransform,
7173
7307
  parseWorldTaskRefs: () => parseWorldTaskRefs,
7308
+ platformTimeoutMs: () => platformTimeoutMs,
7174
7309
  preserveForm: () => preserveForm,
7175
7310
  propose: () => propose,
7176
7311
  pull: () => pull,
@@ -7182,6 +7317,7 @@ __export(worlds_exports, {
7182
7317
  queryRowsSearch: () => queryRowsSearch,
7183
7318
  readLocalMeta: () => readLocalMeta,
7184
7319
  readToolCallRecords: () => readToolCallRecords,
7320
+ rebaseConflicts: () => rebaseConflicts,
7185
7321
  redactActionArgs: () => redactActionArgs,
7186
7322
  redactionOf: () => redactionOf,
7187
7323
  releaseConnection: () => releaseConnection,
@@ -7204,6 +7340,7 @@ __export(worlds_exports, {
7204
7340
  toolCallsFromObservations: () => toolCallsFromObservations,
7205
7341
  uiEntryUrl: () => uiEntryUrl,
7206
7342
  uiUrl: () => uiUrl,
7343
+ uncommittedPaths: () => uncommittedPaths,
7207
7344
  updateTask: () => updateTask,
7208
7345
  upsertRunConfig: () => upsertRunConfig,
7209
7346
  validateTask: () => validateTask,
@@ -7242,19 +7379,10 @@ function parseErrorBody(text2, limit = 600) {
7242
7379
  code: stableCode
7243
7380
  };
7244
7381
  }
7245
- async function apiRequest(options, method, path44, body) {
7246
- const { host, publicKey, secretKey } = resolveEnv(options);
7247
- const res = await fetch(`${host}${path44}`, {
7248
- method,
7249
- headers: {
7250
- "content-type": "application/json",
7251
- authorization: "Basic " + Buffer.from(`${publicKey}:${secretKey}`).toString("base64")
7252
- },
7253
- ...body === void 0 ? {} : { body: JSON.stringify(body) }
7254
- });
7255
- const text2 = await res.text();
7256
- if (!res.ok) throw new ApiError(res.status, method, path44, text2);
7257
- return JSON.parse(text2);
7382
+ async function apiRequest(options, method, path44, body, init2 = {}) {
7383
+ const reply = await new PlatformTransport(resolveEnv(options)).send(method, path44, body, init2);
7384
+ if (!reply.ok) throw new ApiError(reply.status, method, path44, reply.text);
7385
+ return JSON.parse(reply.text);
7258
7386
  }
7259
7387
  async function setEnvSecret(slug, key2, value, options = {}) {
7260
7388
  return apiRequest(
@@ -7434,6 +7562,8 @@ var ApiError, WorldTask, WorldSet;
7434
7562
  var init_worlds = __esm({
7435
7563
  "src/worlds/index.ts"() {
7436
7564
  "use strict";
7565
+ init_transport();
7566
+ init_transport();
7437
7567
  init_session();
7438
7568
  init_sessionList();
7439
7569
  init_sessionContract();
@@ -7458,14 +7588,16 @@ var init_worlds = __esm({
7458
7588
  init_editSessions();
7459
7589
  init_dryRun();
7460
7590
  ApiError = class extends Error {
7461
- constructor(status, method, path44, body) {
7462
- const parsed = parseErrorBody(body);
7591
+ constructor(status, method, path44, text2) {
7592
+ const parsed = parseErrorBody(text2);
7463
7593
  super(`${method} ${path44} -> ${status}: ${parsed.detail}`);
7464
7594
  this.status = status;
7595
+ this.text = text2;
7465
7596
  this.name = "ApiError";
7466
7597
  this.code = parsed.code;
7467
7598
  }
7468
7599
  status;
7600
+ text;
7469
7601
  code;
7470
7602
  };
7471
7603
  WorldTask = class {
@@ -7548,22 +7680,29 @@ import * as fs12 from "fs";
7548
7680
  import * as os3 from "os";
7549
7681
  import * as path11 from "path";
7550
7682
  function configPath() {
7551
- return path11.join(
7552
- process.env.GATEWAY_CONFIG_DIR ?? path11.join(os3.homedir(), ".gateway"),
7553
- "config.json"
7554
- );
7683
+ return path11.join(process.env.GATEWAY_CONFIG_DIR || path11.join(os3.homedir(), ".gateway"), "config.json");
7555
7684
  }
7556
7685
  function readConfig() {
7686
+ let stored;
7557
7687
  try {
7558
- return JSON.parse(fs12.readFileSync(configPath(), "utf8"));
7688
+ stored = JSON.parse(fs12.readFileSync(configPath(), "utf8"));
7559
7689
  } catch {
7560
7690
  return {};
7561
7691
  }
7692
+ const record = stored ?? {};
7693
+ return Object.fromEntries(STORED_FIELDS.filter((f) => typeof record[f] === "string").map((f) => [f, record[f]]));
7562
7694
  }
7563
7695
  function writeConfig(config) {
7564
7696
  const file = configPath();
7565
7697
  fs12.mkdirSync(path11.dirname(file), { recursive: true, mode: 448 });
7566
- fs12.writeFileSync(file, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
7698
+ const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW = 0 } = fs12.constants;
7699
+ const fd = fs12.openSync(file, O_WRONLY | O_CREAT | O_TRUNC | O_NOFOLLOW, 384);
7700
+ try {
7701
+ fs12.fchmodSync(fd, 384);
7702
+ fs12.writeFileSync(fd, JSON.stringify(config, null, 2) + "\n");
7703
+ } finally {
7704
+ fs12.closeSync(fd);
7705
+ }
7567
7706
  }
7568
7707
  function clearConfig() {
7569
7708
  try {
@@ -7610,11 +7749,12 @@ function loadEnvFile() {
7610
7749
  }
7611
7750
  return set;
7612
7751
  }
7613
- function resolveCredentials(hostFlag) {
7752
+ function resolveCredentials(hostFlag, secretKeyFlag) {
7614
7753
  const stored = readConfig();
7615
- const host = (hostFlag ?? process.env.GATEWAY_HOST ?? stored.host ?? "").replace(/\/+$/, "");
7616
- const publicKey = process.env.GATEWAY_PUBLIC_KEY ?? stored.public_key ?? "";
7617
- const secretKey = process.env.GATEWAY_SECRET_KEY ?? process.env.GATEWAY_API_KEY ?? stored.api_key ?? "";
7754
+ const host = (hostFlag || process.env.GATEWAY_HOST || stored.host || "").replace(/\/+$/, "");
7755
+ const login = host === (stored.host ?? "").replace(/\/+$/, "") ? stored : {};
7756
+ const publicKey = process.env.GATEWAY_PUBLIC_KEY || login.public_key || "";
7757
+ const secretKey = secretKeyFlag || process.env.GATEWAY_SECRET_KEY || process.env.GATEWAY_API_KEY || login.api_key || "";
7618
7758
  if (!host)
7619
7759
  throw new CliError(
7620
7760
  "Host not configured. Pass --host, set GATEWAY_HOST, or run `gateway auth login`."
@@ -7625,50 +7765,22 @@ function resolveCredentials(hostFlag) {
7625
7765
  );
7626
7766
  return { host, publicKey, secretKey };
7627
7767
  }
7628
- function transportDetail(error, timeoutMs2) {
7629
- if (error instanceof Error && error.name === "AbortError") return `timed out after ${Math.round(timeoutMs2 / 1e3)}s`;
7630
- const cause = error instanceof Error && error.cause instanceof Error ? error.cause : void 0;
7631
- const code = cause && "code" in cause && typeof cause.code === "string" ? `${cause.code}: ` : "";
7632
- const message = cause?.message ?? (error instanceof Error ? error.message : String(error));
7633
- return `${code}${message}`;
7634
- }
7635
7768
  async function api(creds, method, route, body, init2 = {}) {
7636
- const controller = new AbortController();
7637
- const timeoutMs2 = init2.timeoutMs ?? 12e4;
7638
- const timer = setTimeout(() => controller.abort(), timeoutMs2);
7639
- let res;
7640
- try {
7641
- res = await fetch(`${creds.host}${route}`, {
7642
- method,
7643
- headers: {
7644
- "content-type": "application/json",
7645
- accept: "application/json",
7646
- authorization: "Basic " + Buffer.from(`${creds.publicKey}:${creds.secretKey}`).toString("base64")
7647
- },
7648
- ...body === void 0 ? {} : { body: JSON.stringify(body) },
7649
- signal: controller.signal
7650
- });
7651
- } catch (error) {
7652
- clearTimeout(timer);
7653
- throw new UnreachableError(creds.host, method, route, transportDetail(error, timeoutMs2));
7654
- }
7655
- try {
7656
- const text2 = await res.text();
7657
- if (!res.ok) throw new ApiError2(res.status, method, route, text2);
7658
- return text2 ? JSON.parse(text2) : {};
7659
- } finally {
7660
- clearTimeout(timer);
7661
- }
7769
+ const reply = await new PlatformTransport(creds).send(method, route, body, init2);
7770
+ if (!reply.ok) throw new ApiError2(reply.status, method, route, reply.text);
7771
+ return reply.text ? JSON.parse(reply.text) : {};
7662
7772
  }
7663
7773
  function printJson(ctx, value) {
7664
7774
  ctx.stdout(JSON.stringify(value, null, 2));
7665
7775
  }
7666
- var ENV_FILE_FORM, ApiError2, UnreachableError;
7776
+ var STORED_FIELDS, ENV_FILE_FORM, ApiError2;
7667
7777
  var init_config = __esm({
7668
7778
  "src/cli/config.ts"() {
7669
7779
  "use strict";
7670
7780
  init_router();
7671
7781
  init_worlds();
7782
+ init_transport();
7783
+ STORED_FIELDS = ["host", "public_key", "api_key"];
7672
7784
  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.";
7673
7785
  ApiError2 = class extends CliError {
7674
7786
  constructor(status, method, route, text2) {
@@ -7686,19 +7798,6 @@ var init_config = __esm({
7686
7798
  text;
7687
7799
  code;
7688
7800
  };
7689
- UnreachableError = class extends CliError {
7690
- constructor(host, method, route, detail) {
7691
- super(`${method} ${route}: no answer from ${host} (${detail}). Check the host and the network, then retry.`, 1);
7692
- this.host = host;
7693
- this.method = method;
7694
- this.route = route;
7695
- this.detail = detail;
7696
- }
7697
- host;
7698
- method;
7699
- route;
7700
- detail;
7701
- };
7702
7801
  }
7703
7802
  });
7704
7803
 
@@ -7929,29 +8028,16 @@ function browserTierFlag(args) {
7929
8028
  throw new CliError(`--browser-tier must be one of ${BROWSER_TIERS.join(", ")} (got ${tier})`);
7930
8029
  }
7931
8030
  function credentials(args) {
7932
- const creds = resolveCredentials(arg.str(args, "host"));
7933
- const apiKey = arg.str(args, "api-key");
7934
- return apiKey ? { ...creds, secretKey: apiKey } : creds;
8031
+ return resolveCredentials(arg.str(args, "host"), arg.str(args, "api-key"));
7935
8032
  }
7936
8033
  function worldsOptions(creds) {
7937
8034
  return { host: creds.host, publicKey: creds.publicKey, secretKey: creds.secretKey };
7938
8035
  }
7939
8036
  async function rawRequest(creds, method, route, body) {
7940
- const res = await fetch(`${creds.host}${route}`, {
7941
- method,
7942
- headers: {
7943
- "content-type": "application/json",
7944
- accept: "application/json",
7945
- authorization: "Basic " + Buffer.from(`${creds.publicKey}:${creds.secretKey}`).toString("base64")
7946
- },
7947
- ...body === void 0 ? {} : { body: JSON.stringify(body) }
7948
- });
7949
- const text2 = await res.text();
8037
+ const reply = await new PlatformTransport(creds).send(method, route, body);
7950
8038
  return {
7951
- status: res.status,
7952
- ok: res.ok,
7953
- text: text2,
7954
- json: () => text2 ? JSON.parse(text2) : {}
8039
+ ...reply,
8040
+ json: () => reply.text ? JSON.parse(reply.text) : {}
7955
8041
  };
7956
8042
  }
7957
8043
  function query(params) {
@@ -8011,6 +8097,7 @@ var init_shared = __esm({
8011
8097
  init_config();
8012
8098
  init_router();
8013
8099
  init_worlds();
8100
+ init_transport();
8014
8101
  HOST_FLAG = {
8015
8102
  name: "host",
8016
8103
  help: "Gateway server URL (e.g. https://withgateway.ai).",
@@ -14988,13 +15075,13 @@ function registerAuthCommands(root) {
14988
15075
  flags: [
14989
15076
  { name: "host", help: "Gateway server URL", env: "GATEWAY_HOST" },
14990
15077
  { name: "public-key", help: "Project public key (pk-lf-...)", env: "GATEWAY_PUBLIC_KEY" },
14991
- { name: "api-key", help: "Project secret key (sk-lf-...)", env: "GATEWAY_SECRET_KEY" }
15078
+ { name: "api-key", help: "Project secret key (sk-lf-...); GATEWAY_API_KEY also works", env: "GATEWAY_SECRET_KEY" }
14992
15079
  ],
14993
15080
  notes: "The Python CLI prompts for what is missing; here pass all three flags (or set the env vars).\n" + ENV_FILE_FORM,
14994
15081
  run: async (args, ctx) => {
14995
15082
  const host = arg.str(args, "host");
14996
15083
  const publicKey = arg.str(args, "public-key");
14997
- const apiKey = arg.str(args, "api-key");
15084
+ const apiKey = arg.str(args, "api-key") || process.env.GATEWAY_API_KEY;
14998
15085
  if (!host || !publicKey || !apiKey)
14999
15086
  throw new CliError("auth login needs --host, --public-key and --api-key");
15000
15087
  writeConfig({ host: host.replace(/\/+$/, ""), public_key: publicKey, api_key: apiKey });
@@ -15013,7 +15100,7 @@ function registerAuthCommands(root) {
15013
15100
  help: "Show current authentication status.",
15014
15101
  run: async (_args, ctx) => {
15015
15102
  const envHost = process.env.GATEWAY_HOST;
15016
- const envKey = process.env.GATEWAY_SECRET_KEY ?? process.env.GATEWAY_API_KEY;
15103
+ const envKey = process.env.GATEWAY_SECRET_KEY || process.env.GATEWAY_API_KEY;
15017
15104
  if (envHost || envKey) {
15018
15105
  ctx.stdout(`Host: ${envHost ?? "(not set)"} (from environment)`);
15019
15106
  ctx.stdout(`API key: ${envKey ? "configured" : "not set"} (from environment)`);
@@ -16525,6 +16612,23 @@ function assertWriteSize(bytes, filePath) {
16525
16612
  function client2(args) {
16526
16613
  return new WorldSandboxClient(worldsOptions(credentials(args)));
16527
16614
  }
16615
+ function failOnConflict(error) {
16616
+ const conflicts = rebaseConflicts(error);
16617
+ if (conflicts === null) throw error;
16618
+ const lines = conflicts.map((c) => `conflict: ${c.path} (${c.reason})`);
16619
+ throw new CliError([error.message, ...lines].join("\n"), 1);
16620
+ }
16621
+ var UNCOMMITTED_LISTED = 10;
16622
+ function failOnUncommitted(sandboxId, error) {
16623
+ const paths = uncommittedPaths(error);
16624
+ if (paths === null) throw error;
16625
+ const listed = paths.slice(0, UNCOMMITTED_LISTED);
16626
+ const more = paths.length > UNCOMMITTED_LISTED ? ", \u2026" : "";
16627
+ throw new CliError(
16628
+ `${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)`,
16629
+ 1
16630
+ );
16631
+ }
16528
16632
  function sandboxStatusFilter(value) {
16529
16633
  if (value === void 0 || value === "open" || value === "closed")
16530
16634
  return value;
@@ -16578,6 +16682,7 @@ function sandboxVerbSpecs() {
16578
16682
  specs2 = [
16579
16683
  {
16580
16684
  name: "open",
16685
+ output: "json",
16581
16686
  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.",
16582
16687
  positionals: [
16583
16688
  {
@@ -16681,6 +16786,7 @@ function sandboxVerbSpecs() {
16681
16786
  },
16682
16787
  {
16683
16788
  name: "write",
16789
+ output: "json",
16684
16790
  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`.",
16685
16791
  positionals: [
16686
16792
  SANDBOX_ID,
@@ -16750,6 +16856,7 @@ function sandboxVerbSpecs() {
16750
16856
  },
16751
16857
  {
16752
16858
  name: "check",
16859
+ output: "json",
16753
16860
  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.",
16754
16861
  positionals: [SANDBOX_ID],
16755
16862
  flags: [HOST_FLAG],
@@ -16761,6 +16868,7 @@ function sandboxVerbSpecs() {
16761
16868
  },
16762
16869
  {
16763
16870
  name: "commit",
16871
+ output: "json",
16764
16872
  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.",
16765
16873
  positionals: [SANDBOX_ID],
16766
16874
  flags: [
@@ -16774,6 +16882,11 @@ function sandboxVerbSpecs() {
16774
16882
  short: "b",
16775
16883
  help: "Branch to move (default: the branch the sandbox was opened on)."
16776
16884
  },
16885
+ {
16886
+ name: "rebase",
16887
+ boolean: true,
16888
+ 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)."
16889
+ },
16777
16890
  HOST_FLAG
16778
16891
  ],
16779
16892
  run: async (args, ctx) => {
@@ -16781,8 +16894,9 @@ function sandboxVerbSpecs() {
16781
16894
  if (!message) throw new CliError("commit needs --message");
16782
16895
  const result = await client2(args).commit(args.positionals[0], {
16783
16896
  message,
16784
- branch: arg.str(args, "branch")
16785
- });
16897
+ branch: arg.str(args, "branch"),
16898
+ rebase: arg.bool(args, "rebase")
16899
+ }).catch((error) => failOnConflict(error));
16786
16900
  printJson(ctx, {
16787
16901
  ...result,
16788
16902
  ...editSessionHint(result.slug, result.editSessionId)
@@ -16791,6 +16905,7 @@ function sandboxVerbSpecs() {
16791
16905
  },
16792
16906
  {
16793
16907
  name: "import",
16908
+ output: "json",
16794
16909
  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.",
16795
16910
  positionals: [
16796
16911
  SANDBOX_ID,
@@ -16858,11 +16973,21 @@ function sandboxVerbSpecs() {
16858
16973
  },
16859
16974
  {
16860
16975
  name: "close",
16861
- help: "Close the sandbox and release its workspace (idempotent).",
16976
+ output: "json",
16977
+ 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.",
16862
16978
  positionals: [SANDBOX_ID],
16863
- flags: [HOST_FLAG],
16979
+ flags: [
16980
+ {
16981
+ name: "force",
16982
+ boolean: true,
16983
+ help: "Close even with uncommitted work, discarding it."
16984
+ },
16985
+ HOST_FLAG
16986
+ ],
16864
16987
  run: async (args, ctx) => {
16865
- printJson(ctx, await client2(args).close(args.positionals[0]));
16988
+ const sandboxId = args.positionals[0];
16989
+ const closed = await client2(args).close(sandboxId, { force: arg.bool(args, "force") }).catch((error) => failOnUncommitted(sandboxId, error));
16990
+ printJson(ctx, closed);
16866
16991
  }
16867
16992
  }
16868
16993
  ];
@@ -18601,7 +18726,7 @@ function discoverResult(doc, where, stderr, commands) {
18601
18726
  function dryRunVerifiers(dir, plan, opts) {
18602
18727
  const commands = [];
18603
18728
  if (opts.here) {
18604
- if (!opts.python) return { executed: false, reason: "no python3 >= 3.11 found; set GATEWAY_PYTHON", commands };
18729
+ if (!opts.python) return { executed: false, reason: "no python3 >= 3.12 found; set GATEWAY_PYTHON", commands };
18605
18730
  const argv = [opts.python, ...plan.here.slice(1)];
18606
18731
  commands.push(shellLine(argv));
18607
18732
  const ran2 = spawnSync2(argv[0], argv.slice(1), { encoding: "utf8", timeout: 6e4 });
@@ -23018,6 +23143,14 @@ init_shared();
23018
23143
  var GATE_PATH = "/api/public/agent-builds/gate";
23019
23144
  var EXIT_CODES = { pass: 0, blocked: 1, untested: 2 };
23020
23145
  var TERMINAL_STATES2 = /* @__PURE__ */ new Set(["COMPLETED", "FAILED", "ERROR", "TIMEOUT", "CANCELLED"]);
23146
+ function gateCredentials(args) {
23147
+ try {
23148
+ return credentials(args);
23149
+ } catch (error) {
23150
+ if (error instanceof CliError) throw new CliError(error.message, 1);
23151
+ throw error;
23152
+ }
23153
+ }
23021
23154
  function buildQuery(opts) {
23022
23155
  const ways = [opts.build !== void 0, opts.agent !== void 0 || opts.version !== void 0, opts.commit !== void 0];
23023
23156
  if (ways.filter(Boolean).length !== 1)
@@ -23122,7 +23255,7 @@ function registerReleaseCommands(root) {
23122
23255
  HOST_FLAG,
23123
23256
  API_KEY_FLAG
23124
23257
  ],
23125
- 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",
23258
+ 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",
23126
23259
  run: async (args, ctx) => {
23127
23260
  const q = buildQuery({
23128
23261
  build: arg.str(args, "build"),
@@ -23130,7 +23263,7 @@ function registerReleaseCommands(root) {
23130
23263
  version: arg.str(args, "version"),
23131
23264
  commit: arg.str(args, "commit")
23132
23265
  });
23133
- const creds = credentials(args);
23266
+ const creds = gateCredentials(args);
23134
23267
  const asJson = arg.bool(args, "json");
23135
23268
  let result;
23136
23269
  if (arg.bool(args, "wait")) {
@@ -24736,6 +24869,7 @@ function registerSessionCommands(root) {
24736
24869
  const session = root.group("worlds", "Build, seed, serve and run worlds.").group("session", "Live world sessions with api/ui/browser surfaces.");
24737
24870
  session.command({
24738
24871
  name: "open",
24872
+ output: "json",
24739
24873
  help: "Open a live session and print where it answers.",
24740
24874
  positionals: [{ name: "slug", help: "World slug (optionally slug@ref)." }],
24741
24875
  flags: [
@@ -24771,7 +24905,9 @@ function registerSessionCommands(root) {
24771
24905
  },
24772
24906
  HOST_FLAG
24773
24907
  ],
24774
- notes: `Prints {sessionId, ready, surfaces, api.url, ui.entry, browser.wsUrl, task, idleExpiresAt, pinned} \u2014 the descriptor
24908
+ notes: `Before it waits for ready, stderr names the session (\`session <id> opening \u2014 gateway worlds session status <id>\`),
24909
+ so a wait cut short never loses the id.
24910
+ Prints {sessionId, ready, surfaces, api.url, ui.entry, browser.wsUrl, task, idleExpiresAt, pinned} \u2014 the descriptor
24775
24911
  WorldSession.surfaces parses, plus the platform's task block and when the idle TTL reaps the session (null while pinned).
24776
24912
  A World Host session's api also carries \`token\`: send it as \`Authorization: Bearer <token>\`
24777
24913
  (header only, never in the URL) on every request to api.url. The platform refuses (HTTP 400) rather than serving
@@ -24806,6 +24942,9 @@ source (bundled|stored|inline|none)/name/hash/id/version.
24806
24942
  ...idleJson(live)
24807
24943
  });
24808
24944
  if (!arg.bool(args, "no-wait")) {
24945
+ ctx.stderr(
24946
+ `session ${live.sessionId} opening \u2014 gateway worlds session status ${live.sessionId}`
24947
+ );
24809
24948
  try {
24810
24949
  await live.ready();
24811
24950
  } catch (error) {
@@ -24836,6 +24975,7 @@ source (bundled|stored|inline|none)/name/hash/id/version.
24836
24975
  });
24837
24976
  session.command({
24838
24977
  name: "reset",
24978
+ output: "json",
24839
24979
  help: "Put the world back to its opening state (base data + the task's seed); the call log stays.",
24840
24980
  positionals: [{ name: "session_id", help: "Session id." }],
24841
24981
  flags: [HOST_FLAG],
@@ -24850,6 +24990,7 @@ source (bundled|stored|inline|none)/name/hash/id/version.
24850
24990
  });
24851
24991
  session.command({
24852
24992
  name: "grade",
24993
+ output: "json",
24853
24994
  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'}.",
24854
24995
  positionals: [{ name: "session_id", help: "Session id." }],
24855
24996
  flags: [
@@ -24933,6 +25074,7 @@ source (bundled|stored|inline|none)/name/hash/id/version.
24933
25074
  });
24934
25075
  session.command({
24935
25076
  name: "browse",
25077
+ output: "json",
24936
25078
  help: "Open the session's UI in its browser surface and print what the agent would read.",
24937
25079
  positionals: [{ name: "session_id", help: "Session id." }],
24938
25080
  flags: [
@@ -24969,8 +25111,10 @@ source (bundled|stored|inline|none)/name/hash/id/version.
24969
25111
  });
24970
25112
  session.command({
24971
25113
  name: "close",
25114
+ output: "json",
24972
25115
  help: "End a session.",
24973
25116
  positionals: [{ name: "session_id", help: "Session id." }],
25117
+ 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.",
24974
25118
  flags: [
24975
25119
  {
24976
25120
  name: "keep-warm",
@@ -24990,8 +25134,29 @@ source (bundled|stored|inline|none)/name/hash/id/version.
24990
25134
  );
24991
25135
  }
24992
25136
  });
25137
+ session.command({
25138
+ name: "reopen",
25139
+ output: "json",
25140
+ help: "Reopen a closed session under the same id, URLs and token from its last checkpoint; prints what `status` prints.",
25141
+ positionals: [{ name: "session_id", help: "Session id." }],
25142
+ flags: [HOST_FLAG],
25143
+ 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).",
25144
+ run: async (args, ctx) => {
25145
+ const sessionId = args.positionals[0];
25146
+ const options = worldsOptions(credentials(args));
25147
+ const state2 = await apiRequest(
25148
+ options,
25149
+ "POST",
25150
+ `${sessionRoute(sessionId)}/reopen`
25151
+ );
25152
+ const live = new WorldSession(sessionId, state2, options);
25153
+ printJson(ctx, { ...state2, ...await surfacesJson(live), ...idleJson(live) });
25154
+ warnIdle(ctx, live);
25155
+ }
25156
+ });
24993
25157
  session.command({
24994
25158
  name: "pin",
25159
+ output: "json",
24995
25160
  help: "Pin a session so the idle reaper never closes it: its URL stays up until you close it. --off unpins.",
24996
25161
  positionals: [{ name: "session_id", help: "Session id." }],
24997
25162
  flags: [
@@ -25017,6 +25182,7 @@ source (bundled|stored|inline|none)/name/hash/id/version.
25017
25182
  });
25018
25183
  session.command({
25019
25184
  name: "seed",
25185
+ output: "json",
25020
25186
  help: "Put rows into a LIVE session's world and wait for the engine's answer.",
25021
25187
  positionals: [
25022
25188
  { name: "session_id", help: "Session id." },
@@ -25961,7 +26127,7 @@ function registerConnectorCommands2(connector) {
25961
26127
  connector.command({
25962
26128
  name: "capture",
25963
26129
  help: "Call the live connection once (following its cursor) and record every page under captures/.",
25964
- 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).",
26130
+ 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).",
25965
26131
  positionals: [
25966
26132
  { name: "path", help: "World directory holding connector.toml" }
25967
26133
  ],
@@ -26002,7 +26168,7 @@ function registerConnectorCommands2(connector) {
26002
26168
  const local = localRuntime();
26003
26169
  if (!local)
26004
26170
  throw new CliError(
26005
- `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.`
26171
+ `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.`
26006
26172
  );
26007
26173
  const argv = ["connector-capture", dir, "--op", op];
26008
26174
  for (const pair2 of arg.list(args, "arg")) argv.push("--arg", pair2);
@@ -26172,7 +26338,7 @@ function registerServeCommand(worlds) {
26172
26338
  worlds.command({
26173
26339
  name: "serve",
26174
26340
  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.",
26175
- 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.",
26341
+ 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.",
26176
26342
  positionals: [
26177
26343
  {
26178
26344
  name: "path",
@@ -26618,7 +26784,7 @@ function registerCallCommand(worlds) {
26618
26784
  { name: "close", help: "On a served session (url) or a hosted one (id): end it after the call.", boolean: true },
26619
26785
  HOST_FLAG
26620
26786
  ],
26621
- 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 + `
26787
+ 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 + `
26622
26788
  With a url (the \`url\` \`gateway worlds serve <dir> --task <id>\` prints) the call goes to THAT session over
26623
26789
  POST /__session/call, so state carries from call to call, --state/--grade read it, and --close ends it;
26624
26790
  --task and --scenario belong to the serve. This is the outside-agent path: any HTTP client does the same.
@@ -27816,7 +27982,7 @@ function registerRuntimeCommands(root) {
27816
27982
  import * as fs56 from "fs";
27817
27983
  import * as path43 from "path";
27818
27984
  function cliVersion() {
27819
- if (true) return "0.2.8";
27985
+ if (true) return "0.2.9";
27820
27986
  if (typeof __dirname !== "string") return "unknown";
27821
27987
  try {
27822
27988
  const pkg = JSON.parse(fs56.readFileSync(path43.resolve(__dirname, "../../package.json"), "utf8"));
@@ -27827,10 +27993,13 @@ function cliVersion() {
27827
27993
  }
27828
27994
 
27829
27995
  // src/cli/main.ts
27996
+ init_transport();
27830
27997
  function buildCli() {
27831
27998
  const root = new CommandGroup(
27832
27999
  "gateway",
27833
- "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."
28000
+ "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 + `
28001
+ ${PLATFORM_TIMEOUT_ENV}: milliseconds one platform request may go unanswered (default ${PLATFORM_TIMEOUT_DEFAULT_MS}).
28002
+ \`gateway --version\` prints the installed package version.`
27834
28003
  );
27835
28004
  root.version = cliVersion();
27836
28005
  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.";