@withgateway/sdk 0.3.0 → 0.3.1

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 (47) hide show
  1. package/README.md +5 -1
  2. package/dist/cli.js +1497 -712
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +1500 -715
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +34 -0
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +34 -0
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/{index-DAb-FCMg.d.ts → index-CBqbB_0J.d.ts} +2 -12
  11. package/dist/{index-D6oi1TWE.d.mts → index-D-AMnAMa.d.mts} +2 -12
  12. package/dist/index.d.mts +3 -3
  13. package/dist/index.d.ts +3 -3
  14. package/dist/index.js +173 -50
  15. package/dist/index.js.map +1 -1
  16. package/dist/index.mjs +171 -50
  17. package/dist/index.mjs.map +1 -1
  18. package/dist/traces/index.js +34 -0
  19. package/dist/traces/index.js.map +1 -1
  20. package/dist/traces/index.mjs +34 -0
  21. package/dist/traces/index.mjs.map +1 -1
  22. package/dist/tracing/index.d.mts +1 -1
  23. package/dist/tracing/index.d.ts +1 -1
  24. package/dist/tracing/index.js +39 -20
  25. package/dist/tracing/index.js.map +1 -1
  26. package/dist/tracing/index.mjs +39 -20
  27. package/dist/tracing/index.mjs.map +1 -1
  28. package/dist/worlds/index.d.mts +66 -18
  29. package/dist/worlds/index.d.ts +66 -18
  30. package/dist/worlds/index.js +171 -50
  31. package/dist/worlds/index.js.map +1 -1
  32. package/dist/worlds/index.mjs +171 -50
  33. package/dist/worlds/index.mjs.map +1 -1
  34. package/package.json +1 -1
  35. package/runtime/gatewaysdk/environment/schema/api.py +7 -8
  36. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  37. package/runtime/gatewaysdk/environment/schema/platform.py +1 -7
  38. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +3 -3
  39. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +2 -2
  40. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +6 -6
  41. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +1 -1
  42. package/skills/connector-schema-authoring/SKILL.md +3 -3
  43. package/skills/connector-schema-authoring/connector-worlds.md +12 -5
  44. package/skills/connector-schema-authoring/world-schema.md +8 -0
  45. package/skills/world-data-ingestion/SKILL.md +2 -2
  46. package/skills/worlds-getting-started/SKILL.md +6 -6
  47. package/skills/worlds-getting-started/references/cli-mcp-map.md +1 -1
@@ -3043,6 +3043,28 @@ var init_tasks = __esm({
3043
3043
  }
3044
3044
  });
3045
3045
 
3046
+ // src/worlds/surfaceDescriptor.ts
3047
+ function surfaceDescriptor(s) {
3048
+ return {
3049
+ surfaces: surfaceKinds(s),
3050
+ ...s.api ? { api: { url: s.api.url, ...s.api.token ? { token: s.api.token } : {} } } : {},
3051
+ ...s.ui ? { ui: { url: s.ui.url, entry: uiEntryUrl(s.ui), apiPath: s.ui.apiPath ?? null } } : {},
3052
+ ...s.browser ? {
3053
+ browser: {
3054
+ wsUrl: s.browser.wsUrl,
3055
+ viewport: s.browser.viewport,
3056
+ ...s.browser.tier ? { tier: s.browser.tier } : {}
3057
+ }
3058
+ } : {}
3059
+ };
3060
+ }
3061
+ var init_surfaceDescriptor = __esm({
3062
+ "src/worlds/surfaceDescriptor.ts"() {
3063
+ "use strict";
3064
+ init_browser();
3065
+ }
3066
+ });
3067
+
3046
3068
  // src/worlds/taskSessions.ts
3047
3069
  function aggregateTaskGrade(worlds) {
3048
3070
  const rewards = {};
@@ -3193,6 +3215,7 @@ var init_taskSessions = __esm({
3193
3215
  "use strict";
3194
3216
  init_worlds();
3195
3217
  init_browser();
3218
+ init_surfaceDescriptor();
3196
3219
  init_session2();
3197
3220
  TASK_SESSIONS = "/api/public/world-task-sessions";
3198
3221
  VERIFIER_REWARD_PREFIX = "x.";
@@ -3204,18 +3227,7 @@ var init_taskSessions = __esm({
3204
3227
  sessionId: state2.sessionId,
3205
3228
  ready: state2.ready,
3206
3229
  state: state2.state,
3207
- surfaces: surfaceKinds(s),
3208
- ...s.api ? {
3209
- api: { url: s.api.url, ...s.api.token ? { token: s.api.token } : {} }
3210
- } : {},
3211
- ...s.ui ? {
3212
- ui: {
3213
- url: s.ui.url,
3214
- entry: uiEntryUrl(s.ui),
3215
- apiPath: s.ui.apiPath ?? null
3216
- }
3217
- } : {},
3218
- ...s.browser ? { browser: { wsUrl: s.browser.wsUrl, viewport: s.browser.viewport } } : {}
3230
+ ...surfaceDescriptor(s)
3219
3231
  });
3220
3232
  TaskSessions = class {
3221
3233
  constructor(taskId, taskVersion, name, instruction, sessions, worlds, hash = null) {
@@ -3394,6 +3406,49 @@ var init_evals = __esm({
3394
3406
  }
3395
3407
  });
3396
3408
 
3409
+ // src/tracing/prerequisites.ts
3410
+ function getEnv(key) {
3411
+ const value = process.env[key];
3412
+ return value ? value : void 0;
3413
+ }
3414
+ function isGatewayConfigured() {
3415
+ return !!(getEnv(GATEWAY_ENV.HOST) && getEnv(GATEWAY_ENV.PUBLIC_KEY) && getEnv(GATEWAY_ENV.SECRET_KEY));
3416
+ }
3417
+ var GATEWAY_ENV, OPENTELEMETRY_PEERS, MODULE_NOT_FOUND, OpenTelemetryMissing;
3418
+ var init_prerequisites = __esm({
3419
+ "src/tracing/prerequisites.ts"() {
3420
+ "use strict";
3421
+ GATEWAY_ENV = {
3422
+ HOST: "GATEWAY_HOST",
3423
+ PUBLIC_KEY: "GATEWAY_PUBLIC_KEY",
3424
+ SECRET_KEY: "GATEWAY_SECRET_KEY",
3425
+ ENDPOINT: "GATEWAY_OTLP_ENDPOINT"
3426
+ };
3427
+ OPENTELEMETRY_PEERS = [
3428
+ "@opentelemetry/api",
3429
+ "@opentelemetry/exporter-trace-otlp-http",
3430
+ "@opentelemetry/resources",
3431
+ "@opentelemetry/sdk-trace-base",
3432
+ "@opentelemetry/sdk-trace-node"
3433
+ ];
3434
+ MODULE_NOT_FOUND = /* @__PURE__ */ new Set(["MODULE_NOT_FOUND", "ERR_MODULE_NOT_FOUND"]);
3435
+ OpenTelemetryMissing = class _OpenTelemetryMissing extends Error {
3436
+ constructor() {
3437
+ super(
3438
+ `OpenTelemetry packages not found. Install them with:
3439
+ npm install ${OPENTELEMETRY_PEERS.join(" ")}`
3440
+ );
3441
+ this.name = "OpenTelemetryMissing";
3442
+ }
3443
+ static explains(error) {
3444
+ if (error instanceof _OpenTelemetryMissing) return true;
3445
+ const { code, message } = error ?? {};
3446
+ return MODULE_NOT_FOUND.has(String(code)) && String(message).includes("@opentelemetry/");
3447
+ }
3448
+ };
3449
+ }
3450
+ });
3451
+
3397
3452
  // src/users/index.ts
3398
3453
  function parseEvent(payload) {
3399
3454
  return {
@@ -4077,7 +4132,7 @@ var require_package = __commonJS({
4077
4132
  "package.json"(exports, module) {
4078
4133
  module.exports = {
4079
4134
  name: "@withgateway/sdk",
4080
- version: "0.3.0",
4135
+ version: "0.3.1",
4081
4136
  description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
4082
4137
  main: "./dist/index.js",
4083
4138
  module: "./dist/index.mjs",
@@ -4486,10 +4541,6 @@ __export(init_exports, {
4486
4541
  isInitialized: () => isInitialized,
4487
4542
  shutdown: () => shutdown
4488
4543
  });
4489
- function getEnv(key) {
4490
- const value = process.env[key];
4491
- return value ? value : void 0;
4492
- }
4493
4544
  function log(message, ...args) {
4494
4545
  if (state.debug) {
4495
4546
  console.log(`[gatewaysdk.tracing] ${message}`, ...args);
@@ -4499,10 +4550,10 @@ function warn(message, ...args) {
4499
4550
  console.warn(`[gatewaysdk.tracing] ${message}`, ...args);
4500
4551
  }
4501
4552
  function buildProvider(config, logFn) {
4502
- const host = config.host ?? getEnv(ENV_VARS.HOST);
4503
- const publicKey = config.publicKey ?? getEnv(ENV_VARS.PUBLIC_KEY);
4504
- const secretKey = config.secretKey ?? getEnv(ENV_VARS.SECRET_KEY);
4505
- const endpoint = config.endpoint ?? getEnv(ENV_VARS.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${DEFAULT_OTLP_PATH}` : void 0);
4553
+ const host = config.host ?? getEnv(GATEWAY_ENV.HOST);
4554
+ const publicKey = config.publicKey ?? getEnv(GATEWAY_ENV.PUBLIC_KEY);
4555
+ const secretKey = config.secretKey ?? getEnv(GATEWAY_ENV.SECRET_KEY);
4556
+ const endpoint = config.endpoint ?? getEnv(GATEWAY_ENV.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${DEFAULT_OTLP_PATH}` : void 0);
4506
4557
  const missing = [];
4507
4558
  if (!host) missing.push("host (or GATEWAY_HOST env var)");
4508
4559
  if (!publicKey) missing.push("publicKey (or GATEWAY_PUBLIC_KEY env var)");
@@ -4539,9 +4590,7 @@ function buildProvider(config, logFn) {
4539
4590
  ATTR_SERVICE_NAME = "service.name";
4540
4591
  }
4541
4592
  } catch {
4542
- throw new Error(
4543
- "OpenTelemetry packages not found. Install them with:\nnpm install @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources"
4544
- );
4593
+ throw new OpenTelemetryMissing();
4545
4594
  }
4546
4595
  const resourceAttrs = {
4547
4596
  [ATTR_SERVICE_NAME]: config.serviceName ?? "gatewaysdk-tracing"
@@ -4747,13 +4796,7 @@ async function shutdown() {
4747
4796
  function isInitialized() {
4748
4797
  return state.initialized;
4749
4798
  }
4750
- function isGatewayConfigured() {
4751
- const host = getEnv(ENV_VARS.HOST);
4752
- const publicKey = getEnv(ENV_VARS.PUBLIC_KEY);
4753
- const secretKey = getEnv(ENV_VARS.SECRET_KEY);
4754
- return !!(host && publicKey && secretKey);
4755
- }
4756
- var ENV_VARS, DEFAULT_OTLP_PATH, state;
4799
+ var DEFAULT_OTLP_PATH, state;
4757
4800
  var init_init = __esm({
4758
4801
  "src/tracing/init.ts"() {
4759
4802
  "use strict";
@@ -4762,12 +4805,8 @@ var init_init = __esm({
4762
4805
  init_session();
4763
4806
  init_scores();
4764
4807
  init_build();
4765
- ENV_VARS = {
4766
- HOST: "GATEWAY_HOST",
4767
- PUBLIC_KEY: "GATEWAY_PUBLIC_KEY",
4768
- SECRET_KEY: "GATEWAY_SECRET_KEY",
4769
- ENDPOINT: "GATEWAY_OTLP_ENDPOINT"
4770
- };
4808
+ init_prerequisites();
4809
+ init_prerequisites();
4771
4810
  DEFAULT_OTLP_PATH = "/api/public/otel/v1/traces";
4772
4811
  state = {
4773
4812
  initialized: false,
@@ -4776,6 +4815,45 @@ var init_init = __esm({
4776
4815
  }
4777
4816
  });
4778
4817
 
4818
+ // src/worlds/taskTracing.ts
4819
+ var TaskTracing;
4820
+ var init_taskTracing = __esm({
4821
+ "src/worlds/taskTracing.ts"() {
4822
+ "use strict";
4823
+ init_prerequisites();
4824
+ TaskTracing = class _TaskTracing {
4825
+ constructor(load = () => Promise.resolve().then(() => (init_init(), init_exports))) {
4826
+ this.load = load;
4827
+ }
4828
+ load;
4829
+ static warned = false;
4830
+ async start(requested) {
4831
+ if (!requested || !isGatewayConfigured()) return false;
4832
+ try {
4833
+ (await this.load()).init();
4834
+ return true;
4835
+ } catch (error) {
4836
+ _TaskTracing.warnOnce(error);
4837
+ return false;
4838
+ }
4839
+ }
4840
+ static warnOnce(error) {
4841
+ if (_TaskTracing.warned) return;
4842
+ _TaskTracing.warned = true;
4843
+ console.warn(
4844
+ `[gatewaysdk.tracing] Task runs in this process are not traced. ${_TaskTracing.reason(error)}
4845
+ Pass --no-trace (trace: false) to run untraced without this warning.`
4846
+ );
4847
+ }
4848
+ static reason(error) {
4849
+ if (OpenTelemetryMissing.explains(error))
4850
+ return new OpenTelemetryMissing().message;
4851
+ return error instanceof Error ? error.message : String(error);
4852
+ }
4853
+ };
4854
+ }
4855
+ });
4856
+
4779
4857
  // src/worlds/taskRun.ts
4780
4858
  import { randomBytes } from "crypto";
4781
4859
  import * as fs from "fs";
@@ -4891,18 +4969,7 @@ async function runTask(ref, agent, opts) {
4891
4969
  const started = Date.now();
4892
4970
  try {
4893
4971
  await live.ready();
4894
- let traced = false;
4895
- if (opts.trace !== false) {
4896
- try {
4897
- const { isGatewayConfigured: isGatewayConfigured2, init: init2 } = await Promise.resolve().then(() => (init_init(), init_exports));
4898
- if (isGatewayConfigured2()) {
4899
- init2();
4900
- traced = true;
4901
- }
4902
- } catch {
4903
- traced = false;
4904
- }
4905
- }
4972
+ const traced = await new TaskTracing().start(opts.trace !== false);
4906
4973
  const taskRun = new TaskRun(
4907
4974
  runId,
4908
4975
  live.instruction ?? "",
@@ -4990,6 +5057,7 @@ var init_taskRun = __esm({
4990
5057
  init_evals();
4991
5058
  init_session2();
4992
5059
  init_taskSessions();
5060
+ init_taskTracing();
4993
5061
  TaskRun = class {
4994
5062
  constructor(runId, instruction, model, sessions, manifest) {
4995
5063
  this.runId = runId;
@@ -5193,6 +5261,52 @@ var init_setRun = __esm({
5193
5261
  }
5194
5262
  });
5195
5263
 
5264
+ // src/worlds/requestLog.ts
5265
+ var WorldRequestLog;
5266
+ var init_requestLog = __esm({
5267
+ "src/worlds/requestLog.ts"() {
5268
+ "use strict";
5269
+ WorldRequestLog = class _WorldRequestLog {
5270
+ constructor(requests) {
5271
+ this.requests = requests;
5272
+ }
5273
+ requests;
5274
+ static async read(session) {
5275
+ const state2 = await session.state();
5276
+ const calls = state2?.calls;
5277
+ if (!Array.isArray(calls)) return null;
5278
+ return new _WorldRequestLog(calls.filter((c) => typeof c === "object" && c !== null));
5279
+ }
5280
+ /** How many older requests the world no longer keeps (its log is bounded): the gap
5281
+ * before the first entry it still holds. */
5282
+ get dropped() {
5283
+ const first = Number(this.requests[0]?.seq) || 1;
5284
+ return Math.max(0, first - 1);
5285
+ }
5286
+ /** Each request in the shape of a ledger line, `kind: "request"`, so one JSONL
5287
+ * file holds both. */
5288
+ asCalls() {
5289
+ return this.requests.map((r) => ({
5290
+ seq: Number(r.seq) || 0,
5291
+ kind: "request",
5292
+ tool: r.operation ?? null,
5293
+ args: {
5294
+ method: r.method ?? null,
5295
+ path: r.path ?? null,
5296
+ args: r.args ?? null,
5297
+ query: r.query ?? null,
5298
+ body: r.body ?? null,
5299
+ via: r.via ?? null
5300
+ },
5301
+ result: { status: r.status ?? null, rows: r.rows ?? null, found: r.found ?? null },
5302
+ error: null,
5303
+ completedAt: r.at ?? null
5304
+ }));
5305
+ }
5306
+ };
5307
+ }
5308
+ });
5309
+
5196
5310
  // src/worlds/checkoutTarget.ts
5197
5311
  import * as fs2 from "fs";
5198
5312
  import * as path2 from "path";
@@ -7026,13 +7140,14 @@ async function localBridge(request, local, opts = {}) {
7026
7140
  child.stdin.end(input);
7027
7141
  });
7028
7142
  }
7029
- var MIN_PYTHON, DIAGNOSTIC_TAIL, BRIDGE_BOOTSTRAP, pythonCache, pythonProbes, PYTHON_CANDIDATES, UV_FIND;
7143
+ var MIN_PYTHON, MIN_PYTHON_LABEL, DIAGNOSTIC_TAIL, BRIDGE_BOOTSTRAP, pythonCache, pythonProbes, PYTHON_CANDIDATES, UV_FIND;
7030
7144
  var init_local = __esm({
7031
7145
  "src/cli/runtime/local.ts"() {
7032
7146
  "use strict";
7033
7147
  init_router();
7034
7148
  init_config();
7035
7149
  MIN_PYTHON = [3, 12];
7150
+ MIN_PYTHON_LABEL = MIN_PYTHON.join(".");
7036
7151
  DIAGNOSTIC_TAIL = 600;
7037
7152
  BRIDGE_BOOTSTRAP = `import sys,runpy,types,os
7038
7153
  root=sys.argv[1]
@@ -8401,6 +8516,7 @@ __export(worlds_exports, {
8401
8516
  WorldBrowser: () => WorldBrowser,
8402
8517
  WorldCallTooLarge: () => WorldCallTooLarge,
8403
8518
  WorldEditClient: () => WorldEditClient,
8519
+ WorldRequestLog: () => WorldRequestLog,
8404
8520
  WorldSandboxClient: () => WorldSandboxClient,
8405
8521
  WorldSession: () => WorldSession,
8406
8522
  WorldSessionCallError: () => WorldSessionCallError,
@@ -8494,6 +8610,7 @@ __export(worlds_exports, {
8494
8610
  shapeText: () => shapeText,
8495
8611
  snapshotTreeHashes: () => snapshotTreeHashes,
8496
8612
  storedForms: () => storedForms,
8613
+ surfaceDescriptor: () => surfaceDescriptor,
8497
8614
  surfaceKinds: () => surfaceKinds,
8498
8615
  taskLabel: () => taskLabel,
8499
8616
  toolCallRecordsIn: () => toolCallRecordsIn,
@@ -8734,6 +8851,8 @@ var init_worlds = __esm({
8734
8851
  init_checkoutProvenance();
8735
8852
  init_evals();
8736
8853
  init_browser();
8854
+ init_surfaceDescriptor();
8855
+ init_requestLog();
8737
8856
  init_browserReconnect();
8738
8857
  init_nativeComputer();
8739
8858
  init_hub();
@@ -8900,6 +9019,7 @@ export {
8900
9019
  WorldBrowser,
8901
9020
  WorldCallTooLarge,
8902
9021
  WorldEditClient,
9022
+ WorldRequestLog,
8903
9023
  WorldSandboxClient,
8904
9024
  WorldSession,
8905
9025
  WorldSessionCallError,
@@ -8993,6 +9113,7 @@ export {
8993
9113
  shapeText,
8994
9114
  snapshotTreeHashes,
8995
9115
  storedForms,
9116
+ surfaceDescriptor,
8996
9117
  surfaceKinds,
8997
9118
  taskLabel,
8998
9119
  toolCallRecordsIn,