@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
package/dist/index.mjs CHANGED
@@ -3465,6 +3465,28 @@ var init_tasks = __esm({
3465
3465
  }
3466
3466
  });
3467
3467
 
3468
+ // src/worlds/surfaceDescriptor.ts
3469
+ function surfaceDescriptor(s) {
3470
+ return {
3471
+ surfaces: surfaceKinds(s),
3472
+ ...s.api ? { api: { url: s.api.url, ...s.api.token ? { token: s.api.token } : {} } } : {},
3473
+ ...s.ui ? { ui: { url: s.ui.url, entry: uiEntryUrl(s.ui), apiPath: s.ui.apiPath ?? null } } : {},
3474
+ ...s.browser ? {
3475
+ browser: {
3476
+ wsUrl: s.browser.wsUrl,
3477
+ viewport: s.browser.viewport,
3478
+ ...s.browser.tier ? { tier: s.browser.tier } : {}
3479
+ }
3480
+ } : {}
3481
+ };
3482
+ }
3483
+ var init_surfaceDescriptor = __esm({
3484
+ "src/worlds/surfaceDescriptor.ts"() {
3485
+ "use strict";
3486
+ init_browser();
3487
+ }
3488
+ });
3489
+
3468
3490
  // src/worlds/taskSessions.ts
3469
3491
  function aggregateTaskGrade(worlds) {
3470
3492
  const rewards = {};
@@ -3615,6 +3637,7 @@ var init_taskSessions = __esm({
3615
3637
  "use strict";
3616
3638
  init_worlds();
3617
3639
  init_browser();
3640
+ init_surfaceDescriptor();
3618
3641
  init_session2();
3619
3642
  TASK_SESSIONS = "/api/public/world-task-sessions";
3620
3643
  VERIFIER_REWARD_PREFIX = "x.";
@@ -3626,18 +3649,7 @@ var init_taskSessions = __esm({
3626
3649
  sessionId: state2.sessionId,
3627
3650
  ready: state2.ready,
3628
3651
  state: state2.state,
3629
- surfaces: surfaceKinds(s),
3630
- ...s.api ? {
3631
- api: { url: s.api.url, ...s.api.token ? { token: s.api.token } : {} }
3632
- } : {},
3633
- ...s.ui ? {
3634
- ui: {
3635
- url: s.ui.url,
3636
- entry: uiEntryUrl(s.ui),
3637
- apiPath: s.ui.apiPath ?? null
3638
- }
3639
- } : {},
3640
- ...s.browser ? { browser: { wsUrl: s.browser.wsUrl, viewport: s.browser.viewport } } : {}
3652
+ ...surfaceDescriptor(s)
3641
3653
  });
3642
3654
  TaskSessions = class {
3643
3655
  constructor(taskId, taskVersion, name, instruction, sessions2, worlds, hash = null) {
@@ -3816,6 +3828,49 @@ var init_evals = __esm({
3816
3828
  }
3817
3829
  });
3818
3830
 
3831
+ // src/tracing/prerequisites.ts
3832
+ function getEnv(key2) {
3833
+ const value = process.env[key2];
3834
+ return value ? value : void 0;
3835
+ }
3836
+ function isGatewayConfigured() {
3837
+ return !!(getEnv(GATEWAY_ENV.HOST) && getEnv(GATEWAY_ENV.PUBLIC_KEY) && getEnv(GATEWAY_ENV.SECRET_KEY));
3838
+ }
3839
+ var GATEWAY_ENV, OPENTELEMETRY_PEERS, MODULE_NOT_FOUND, OpenTelemetryMissing;
3840
+ var init_prerequisites = __esm({
3841
+ "src/tracing/prerequisites.ts"() {
3842
+ "use strict";
3843
+ GATEWAY_ENV = {
3844
+ HOST: "GATEWAY_HOST",
3845
+ PUBLIC_KEY: "GATEWAY_PUBLIC_KEY",
3846
+ SECRET_KEY: "GATEWAY_SECRET_KEY",
3847
+ ENDPOINT: "GATEWAY_OTLP_ENDPOINT"
3848
+ };
3849
+ OPENTELEMETRY_PEERS = [
3850
+ "@opentelemetry/api",
3851
+ "@opentelemetry/exporter-trace-otlp-http",
3852
+ "@opentelemetry/resources",
3853
+ "@opentelemetry/sdk-trace-base",
3854
+ "@opentelemetry/sdk-trace-node"
3855
+ ];
3856
+ MODULE_NOT_FOUND = /* @__PURE__ */ new Set(["MODULE_NOT_FOUND", "ERR_MODULE_NOT_FOUND"]);
3857
+ OpenTelemetryMissing = class _OpenTelemetryMissing extends Error {
3858
+ constructor() {
3859
+ super(
3860
+ `OpenTelemetry packages not found. Install them with:
3861
+ npm install ${OPENTELEMETRY_PEERS.join(" ")}`
3862
+ );
3863
+ this.name = "OpenTelemetryMissing";
3864
+ }
3865
+ static explains(error) {
3866
+ if (error instanceof _OpenTelemetryMissing) return true;
3867
+ const { code, message } = error ?? {};
3868
+ return MODULE_NOT_FOUND.has(String(code)) && String(message).includes("@opentelemetry/");
3869
+ }
3870
+ };
3871
+ }
3872
+ });
3873
+
3819
3874
  // src/tracing/identity.ts
3820
3875
  import { AsyncLocalStorage as AsyncLocalStorage3 } from "async_hooks";
3821
3876
  import { isSpanContextValid as isSpanContextValid2, trace as trace2 } from "@opentelemetry/api";
@@ -4116,7 +4171,7 @@ var require_package = __commonJS({
4116
4171
  "package.json"(exports, module) {
4117
4172
  module.exports = {
4118
4173
  name: "@withgateway/sdk",
4119
- version: "0.3.0",
4174
+ version: "0.3.1",
4120
4175
  description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
4121
4176
  main: "./dist/index.js",
4122
4177
  module: "./dist/index.mjs",
@@ -4612,10 +4667,6 @@ __export(init_exports, {
4612
4667
  isInitialized: () => isInitialized,
4613
4668
  shutdown: () => shutdown2
4614
4669
  });
4615
- function getEnv(key2) {
4616
- const value = process.env[key2];
4617
- return value ? value : void 0;
4618
- }
4619
4670
  function log(message, ...args) {
4620
4671
  if (state.debug) {
4621
4672
  console.log(`[gatewaysdk.tracing] ${message}`, ...args);
@@ -4625,10 +4676,10 @@ function warn(message, ...args) {
4625
4676
  console.warn(`[gatewaysdk.tracing] ${message}`, ...args);
4626
4677
  }
4627
4678
  function buildProvider(config, logFn) {
4628
- const host = config.host ?? getEnv(ENV_VARS.HOST);
4629
- const publicKey = config.publicKey ?? getEnv(ENV_VARS.PUBLIC_KEY);
4630
- const secretKey = config.secretKey ?? getEnv(ENV_VARS.SECRET_KEY);
4631
- const endpoint = config.endpoint ?? getEnv(ENV_VARS.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${DEFAULT_OTLP_PATH}` : void 0);
4679
+ const host = config.host ?? getEnv(GATEWAY_ENV.HOST);
4680
+ const publicKey = config.publicKey ?? getEnv(GATEWAY_ENV.PUBLIC_KEY);
4681
+ const secretKey = config.secretKey ?? getEnv(GATEWAY_ENV.SECRET_KEY);
4682
+ const endpoint = config.endpoint ?? getEnv(GATEWAY_ENV.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${DEFAULT_OTLP_PATH}` : void 0);
4632
4683
  const missing = [];
4633
4684
  if (!host) missing.push("host (or GATEWAY_HOST env var)");
4634
4685
  if (!publicKey) missing.push("publicKey (or GATEWAY_PUBLIC_KEY env var)");
@@ -4665,9 +4716,7 @@ function buildProvider(config, logFn) {
4665
4716
  ATTR_SERVICE_NAME = "service.name";
4666
4717
  }
4667
4718
  } catch {
4668
- throw new Error(
4669
- "OpenTelemetry packages not found. Install them with:\nnpm install @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources"
4670
- );
4719
+ throw new OpenTelemetryMissing();
4671
4720
  }
4672
4721
  const resourceAttrs = {
4673
4722
  [ATTR_SERVICE_NAME]: config.serviceName ?? "gatewaysdk-tracing"
@@ -4873,13 +4922,7 @@ async function shutdown2() {
4873
4922
  function isInitialized() {
4874
4923
  return state.initialized;
4875
4924
  }
4876
- function isGatewayConfigured() {
4877
- const host = getEnv(ENV_VARS.HOST);
4878
- const publicKey = getEnv(ENV_VARS.PUBLIC_KEY);
4879
- const secretKey = getEnv(ENV_VARS.SECRET_KEY);
4880
- return !!(host && publicKey && secretKey);
4881
- }
4882
- var ENV_VARS, DEFAULT_OTLP_PATH, state;
4925
+ var DEFAULT_OTLP_PATH, state;
4883
4926
  var init_init = __esm({
4884
4927
  "src/tracing/init.ts"() {
4885
4928
  "use strict";
@@ -4888,12 +4931,8 @@ var init_init = __esm({
4888
4931
  init_session();
4889
4932
  init_scores();
4890
4933
  init_build();
4891
- ENV_VARS = {
4892
- HOST: "GATEWAY_HOST",
4893
- PUBLIC_KEY: "GATEWAY_PUBLIC_KEY",
4894
- SECRET_KEY: "GATEWAY_SECRET_KEY",
4895
- ENDPOINT: "GATEWAY_OTLP_ENDPOINT"
4896
- };
4934
+ init_prerequisites();
4935
+ init_prerequisites();
4897
4936
  DEFAULT_OTLP_PATH = "/api/public/otel/v1/traces";
4898
4937
  state = {
4899
4938
  initialized: false,
@@ -4902,6 +4941,45 @@ var init_init = __esm({
4902
4941
  }
4903
4942
  });
4904
4943
 
4944
+ // src/worlds/taskTracing.ts
4945
+ var TaskTracing;
4946
+ var init_taskTracing = __esm({
4947
+ "src/worlds/taskTracing.ts"() {
4948
+ "use strict";
4949
+ init_prerequisites();
4950
+ TaskTracing = class _TaskTracing {
4951
+ constructor(load = () => Promise.resolve().then(() => (init_init(), init_exports))) {
4952
+ this.load = load;
4953
+ }
4954
+ load;
4955
+ static warned = false;
4956
+ async start(requested) {
4957
+ if (!requested || !isGatewayConfigured()) return false;
4958
+ try {
4959
+ (await this.load()).init();
4960
+ return true;
4961
+ } catch (error) {
4962
+ _TaskTracing.warnOnce(error);
4963
+ return false;
4964
+ }
4965
+ }
4966
+ static warnOnce(error) {
4967
+ if (_TaskTracing.warned) return;
4968
+ _TaskTracing.warned = true;
4969
+ console.warn(
4970
+ `[gatewaysdk.tracing] Task runs in this process are not traced. ${_TaskTracing.reason(error)}
4971
+ Pass --no-trace (trace: false) to run untraced without this warning.`
4972
+ );
4973
+ }
4974
+ static reason(error) {
4975
+ if (OpenTelemetryMissing.explains(error))
4976
+ return new OpenTelemetryMissing().message;
4977
+ return error instanceof Error ? error.message : String(error);
4978
+ }
4979
+ };
4980
+ }
4981
+ });
4982
+
4905
4983
  // src/worlds/taskRun.ts
4906
4984
  import { randomBytes } from "crypto";
4907
4985
  import * as fs from "fs";
@@ -5017,18 +5095,7 @@ async function runTask(ref, agent, opts) {
5017
5095
  const started = Date.now();
5018
5096
  try {
5019
5097
  await live.ready();
5020
- let traced = false;
5021
- if (opts.trace !== false) {
5022
- try {
5023
- const { isGatewayConfigured: isGatewayConfigured2, init: init3 } = await Promise.resolve().then(() => (init_init(), init_exports));
5024
- if (isGatewayConfigured2()) {
5025
- init3();
5026
- traced = true;
5027
- }
5028
- } catch {
5029
- traced = false;
5030
- }
5031
- }
5098
+ const traced = await new TaskTracing().start(opts.trace !== false);
5032
5099
  const taskRun = new TaskRun(
5033
5100
  runId,
5034
5101
  live.instruction ?? "",
@@ -5116,6 +5183,7 @@ var init_taskRun = __esm({
5116
5183
  init_evals();
5117
5184
  init_session2();
5118
5185
  init_taskSessions();
5186
+ init_taskTracing();
5119
5187
  TaskRun = class {
5120
5188
  constructor(runId, instruction, model, sessions2, manifest) {
5121
5189
  this.runId = runId;
@@ -5319,6 +5387,52 @@ var init_setRun = __esm({
5319
5387
  }
5320
5388
  });
5321
5389
 
5390
+ // src/worlds/requestLog.ts
5391
+ var WorldRequestLog;
5392
+ var init_requestLog = __esm({
5393
+ "src/worlds/requestLog.ts"() {
5394
+ "use strict";
5395
+ WorldRequestLog = class _WorldRequestLog {
5396
+ constructor(requests) {
5397
+ this.requests = requests;
5398
+ }
5399
+ requests;
5400
+ static async read(session) {
5401
+ const state2 = await session.state();
5402
+ const calls = state2?.calls;
5403
+ if (!Array.isArray(calls)) return null;
5404
+ return new _WorldRequestLog(calls.filter((c) => typeof c === "object" && c !== null));
5405
+ }
5406
+ /** How many older requests the world no longer keeps (its log is bounded): the gap
5407
+ * before the first entry it still holds. */
5408
+ get dropped() {
5409
+ const first = Number(this.requests[0]?.seq) || 1;
5410
+ return Math.max(0, first - 1);
5411
+ }
5412
+ /** Each request in the shape of a ledger line, `kind: "request"`, so one JSONL
5413
+ * file holds both. */
5414
+ asCalls() {
5415
+ return this.requests.map((r) => ({
5416
+ seq: Number(r.seq) || 0,
5417
+ kind: "request",
5418
+ tool: r.operation ?? null,
5419
+ args: {
5420
+ method: r.method ?? null,
5421
+ path: r.path ?? null,
5422
+ args: r.args ?? null,
5423
+ query: r.query ?? null,
5424
+ body: r.body ?? null,
5425
+ via: r.via ?? null
5426
+ },
5427
+ result: { status: r.status ?? null, rows: r.rows ?? null, found: r.found ?? null },
5428
+ error: null,
5429
+ completedAt: r.at ?? null
5430
+ }));
5431
+ }
5432
+ };
5433
+ }
5434
+ });
5435
+
5322
5436
  // src/worlds/checkoutTarget.ts
5323
5437
  import * as fs2 from "fs";
5324
5438
  import * as path2 from "path";
@@ -7152,13 +7266,14 @@ async function localBridge(request, local, opts = {}) {
7152
7266
  child.stdin.end(input);
7153
7267
  });
7154
7268
  }
7155
- var MIN_PYTHON, DIAGNOSTIC_TAIL, BRIDGE_BOOTSTRAP, pythonCache, pythonProbes, PYTHON_CANDIDATES, UV_FIND;
7269
+ var MIN_PYTHON, MIN_PYTHON_LABEL, DIAGNOSTIC_TAIL, BRIDGE_BOOTSTRAP, pythonCache, pythonProbes, PYTHON_CANDIDATES, UV_FIND;
7156
7270
  var init_local = __esm({
7157
7271
  "src/cli/runtime/local.ts"() {
7158
7272
  "use strict";
7159
7273
  init_router();
7160
7274
  init_config();
7161
7275
  MIN_PYTHON = [3, 12];
7276
+ MIN_PYTHON_LABEL = MIN_PYTHON.join(".");
7162
7277
  DIAGNOSTIC_TAIL = 600;
7163
7278
  BRIDGE_BOOTSTRAP = `import sys,runpy,types,os
7164
7279
  root=sys.argv[1]
@@ -8527,6 +8642,7 @@ __export(worlds_exports, {
8527
8642
  WorldBrowser: () => WorldBrowser,
8528
8643
  WorldCallTooLarge: () => WorldCallTooLarge,
8529
8644
  WorldEditClient: () => WorldEditClient,
8645
+ WorldRequestLog: () => WorldRequestLog,
8530
8646
  WorldSandboxClient: () => WorldSandboxClient,
8531
8647
  WorldSession: () => WorldSession,
8532
8648
  WorldSessionCallError: () => WorldSessionCallError,
@@ -8620,6 +8736,7 @@ __export(worlds_exports, {
8620
8736
  shapeText: () => shapeText,
8621
8737
  snapshotTreeHashes: () => snapshotTreeHashes,
8622
8738
  storedForms: () => storedForms,
8739
+ surfaceDescriptor: () => surfaceDescriptor,
8623
8740
  surfaceKinds: () => surfaceKinds,
8624
8741
  taskLabel: () => taskLabel,
8625
8742
  toolCallRecordsIn: () => toolCallRecordsIn,
@@ -8861,6 +8978,8 @@ var init_worlds = __esm({
8861
8978
  init_checkoutProvenance();
8862
8979
  init_evals();
8863
8980
  init_browser();
8981
+ init_surfaceDescriptor();
8982
+ init_requestLog();
8864
8983
  init_browserReconnect();
8865
8984
  init_nativeComputer();
8866
8985
  init_hub();
@@ -16741,6 +16860,7 @@ export {
16741
16860
  WorldBrowser,
16742
16861
  WorldCallTooLarge,
16743
16862
  WorldEditClient,
16863
+ WorldRequestLog,
16744
16864
  WorldSandboxClient,
16745
16865
  WorldSession,
16746
16866
  WorldSessionCallError,
@@ -16874,6 +16994,7 @@ export {
16874
16994
  storedForms,
16875
16995
  success,
16876
16996
  suite,
16997
+ surfaceDescriptor,
16877
16998
  surfaceKinds,
16878
16999
  taskLabel,
16879
17000
  toolCallRecordsIn,