@withgateway/sdk 0.2.9 → 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 (58) hide show
  1. package/README.md +5 -1
  2. package/dist/cli.js +3812 -1158
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +3796 -1142
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -0
  7. package/dist/files/index.d.ts +1 -0
  8. package/dist/files/index.js +1358 -21
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +1356 -13
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-BO2SNSgy.d.ts → index-CBqbB_0J.d.ts} +95 -46
  13. package/dist/{index-Cz8Q6Keo.d.mts → index-D-AMnAMa.d.mts} +95 -46
  14. package/dist/index.d.mts +4 -3
  15. package/dist/index.d.ts +4 -3
  16. package/dist/index.js +1942 -177
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1890 -146
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/media-CbcAfQvd.d.mts +83 -0
  21. package/dist/media-CbcAfQvd.d.ts +83 -0
  22. package/dist/traces/index.d.mts +1 -0
  23. package/dist/traces/index.d.ts +1 -0
  24. package/dist/traces/index.js +1355 -18
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +1353 -10
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -1
  29. package/dist/tracing/index.d.ts +2 -1
  30. package/dist/tracing/index.js +550 -30
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +539 -29
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +648 -80
  35. package/dist/worlds/index.d.ts +648 -80
  36. package/dist/worlds/index.js +1875 -145
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1861 -131
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/schema/api.py +43 -62
  42. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  43. package/runtime/gatewaysdk/environment/schema/grading.py +1 -5
  44. package/runtime/gatewaysdk/environment/schema/host.py +53 -90
  45. package/runtime/gatewaysdk/environment/schema/local.py +15 -7
  46. package/runtime/gatewaysdk/environment/schema/platform.py +1 -7
  47. package/runtime/gatewaysdk/environment/schema/runtime.py +9 -9
  48. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +3 -3
  49. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +2 -2
  50. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +13 -13
  51. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +2 -1
  52. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -1
  53. package/skills/connector-schema-authoring/SKILL.md +3 -3
  54. package/skills/connector-schema-authoring/connector-worlds.md +12 -5
  55. package/skills/connector-schema-authoring/world-schema.md +8 -0
  56. package/skills/world-data-ingestion/SKILL.md +2 -2
  57. package/skills/worlds-getting-started/SKILL.md +13 -13
  58. package/skills/worlds-getting-started/references/cli-mcp-map.md +2 -1
@@ -29,7 +29,7 @@ var require_package = __commonJS({
29
29
  "package.json"(exports2, module2) {
30
30
  module2.exports = {
31
31
  name: "@withgateway/sdk",
32
- version: "0.2.9",
32
+ version: "0.3.1",
33
33
  description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
34
34
  main: "./dist/index.js",
35
35
  module: "./dist/index.mjs",
@@ -232,11 +232,20 @@ var require_package = __commonJS({
232
232
  var tracing_exports = {};
233
233
  __export(tracing_exports, {
234
234
  IdentitySpanProcessor: () => IdentitySpanProcessor,
235
+ MAX_MEDIA_BYTES: () => MAX_MEDIA_BYTES,
236
+ MediaReference: () => MediaReference,
237
+ MediaUploadError: () => MediaUploadError,
238
+ MediaUploader: () => MediaUploader,
239
+ SECRET_KEYS: () => SECRET_KEYS,
235
240
  SESSION_ID_ATTRIBUTE: () => SESSION_ID_ATTRIBUTE,
241
+ SecretRedactingSpanProcessor: () => SecretRedactingSpanProcessor,
236
242
  SessionSpanProcessor: () => SessionSpanProcessor,
243
+ SpanSecrets: () => SpanSecrets,
237
244
  USER_ID_ATTRIBUTE: () => USER_ID_ATTRIBUTE,
245
+ WORLD_SESSION_ID_ATTRIBUTE: () => WORLD_SESSION_ID_ATTRIBUTE,
238
246
  flush: () => flush,
239
247
  getAmbientSessionId: () => getAmbientSessionId,
248
+ getCurrentWorldSessionId: () => getCurrentWorldSessionId,
240
249
  identify: () => identify,
241
250
  init: () => init,
242
251
  initIsolated: () => initIsolated,
@@ -249,7 +258,8 @@ __export(tracing_exports, {
249
258
  resetAmbientUser: () => resetAmbientUser,
250
259
  resolveUserId: () => resolveUserId,
251
260
  shutdown: () => shutdown,
252
- withSession: () => withSession
261
+ withSession: () => withSession,
262
+ withWorldSession: () => withWorldSession
253
263
  });
254
264
  module.exports = __toCommonJS(tracing_exports);
255
265
 
@@ -520,26 +530,267 @@ function debugLog(message, ...args) {
520
530
  }
521
531
  }
522
532
 
533
+ // src/tracing/secrets.ts
534
+ var SECRET_KEYS = /* @__PURE__ */ new Set([
535
+ "authorization_token",
536
+ "authorizationToken"
537
+ ]);
538
+ var REDACTED = "[redacted: holds a credential]";
539
+ var MIN_SECRET_LENGTH = 8;
540
+ var SpanSecrets = class {
541
+ constructor(keys = SECRET_KEYS) {
542
+ this.keys = keys;
543
+ }
544
+ keys;
545
+ isSecret(key) {
546
+ return this.keys.has(key);
547
+ }
548
+ drops(attribute) {
549
+ return this.mentions(attribute);
550
+ }
551
+ strip(value) {
552
+ if (typeof value === "string") return this.stripNested(value);
553
+ if (Array.isArray(value)) return value.map((item) => this.strip(item));
554
+ if (value === null || typeof value !== "object") return value;
555
+ return Object.fromEntries(
556
+ Object.entries(value).filter(([key]) => !this.isSecret(key)).map(([key, item]) => [key, this.strip(item)])
557
+ );
558
+ }
559
+ scrubAttribute(value) {
560
+ try {
561
+ return this.scrubbedValue(value);
562
+ } catch {
563
+ return Array.isArray(value) ? [REDACTED] : REDACTED;
564
+ }
565
+ }
566
+ scrubbedValue(value) {
567
+ if (typeof value === "string") return this.scrubbedText(value);
568
+ if (!Array.isArray(value)) return value;
569
+ const results = value.map(
570
+ (item) => typeof item === "string" ? this.cleaned(item) : { text: item, removed: /* @__PURE__ */ new Set() }
571
+ );
572
+ const removed = new Set(results.flatMap((r) => [...r.removed]));
573
+ const scrubbed = results.map((r) => r.text);
574
+ const withheld = scrubbed.some(
575
+ (item) => typeof item === "string" && this.carries(item, removed)
576
+ );
577
+ return withheld ? [REDACTED] : scrubbed;
578
+ }
579
+ scrubAttributes(attributes) {
580
+ return Object.fromEntries(
581
+ Object.entries(attributes).filter(([key]) => !this.drops(key)).map(([key, value]) => [key, this.scrubAttribute(value)])
582
+ );
583
+ }
584
+ mentions(text) {
585
+ return [...this.keys].some((key) => text.includes(key));
586
+ }
587
+ scrubbedText(text) {
588
+ const { text: cleaned, removed } = this.cleaned(text);
589
+ return this.carries(cleaned, removed) ? REDACTED : cleaned;
590
+ }
591
+ cleaned(text) {
592
+ if (!this.mentions(text)) return { text, removed: /* @__PURE__ */ new Set() };
593
+ const parsed = jsonOrUndefined(text);
594
+ if (parsed === void 0) return { text: REDACTED, removed: /* @__PURE__ */ new Set() };
595
+ return {
596
+ text: JSON.stringify(this.strip(parsed)),
597
+ removed: this.removed(parsed)
598
+ };
599
+ }
600
+ carries(text, removed) {
601
+ if (text === REDACTED || this.mentions(text)) return true;
602
+ return [...removed].some(
603
+ (value) => encodings(value).some((form) => text.includes(form))
604
+ );
605
+ }
606
+ removed(value) {
607
+ if (typeof value === "string") {
608
+ const nested = this.mentions(value) ? jsonOrUndefined(value) : void 0;
609
+ return nested === void 0 ? /* @__PURE__ */ new Set() : this.removed(nested);
610
+ }
611
+ if (Array.isArray(value)) return union(value.map((v) => this.removed(v)));
612
+ if (value === null || typeof value !== "object") return /* @__PURE__ */ new Set();
613
+ return union(
614
+ Object.entries(value).map(
615
+ ([key, item]) => this.isSecret(key) ? leaves(item) : this.removed(item)
616
+ )
617
+ );
618
+ }
619
+ stripNested(text) {
620
+ if (!this.mentions(text)) return text;
621
+ const parsed = jsonOrUndefined(text);
622
+ if (parsed === void 0) return text;
623
+ return JSON.stringify(this.strip(parsed));
624
+ }
625
+ };
626
+ function jsonOrUndefined(text) {
627
+ let parsed;
628
+ try {
629
+ parsed = JSON.parse(text);
630
+ } catch {
631
+ return void 0;
632
+ }
633
+ if (typeof parsed === "string") return parsed;
634
+ return parsed !== null && typeof parsed === "object" ? parsed : void 0;
635
+ }
636
+ function encodings(value) {
637
+ return [value, percentEncoded(value), JSON.stringify(value).slice(1, -1)];
638
+ }
639
+ function percentEncoded(value) {
640
+ try {
641
+ return encodeURIComponent(value);
642
+ } catch {
643
+ return value;
644
+ }
645
+ }
646
+ function union(sets) {
647
+ return new Set(sets.flatMap((set) => [...set]));
648
+ }
649
+ function leaves(value) {
650
+ if (typeof value === "string") {
651
+ return [...value].length >= MIN_SECRET_LENGTH ? /* @__PURE__ */ new Set([value]) : /* @__PURE__ */ new Set();
652
+ }
653
+ if (Array.isArray(value)) return union(value.map(leaves));
654
+ if (value === null || typeof value !== "object") return /* @__PURE__ */ new Set();
655
+ return union(Object.values(value).map(leaves));
656
+ }
657
+ var SPAN_SECRETS = new SpanSecrets();
658
+ function sameAttributes(before, after) {
659
+ const keys = Object.keys(before);
660
+ if (keys.length !== Object.keys(after).length) return false;
661
+ return keys.every(
662
+ (key) => before[key] === after[key] || sameArray(before[key], after[key])
663
+ );
664
+ }
665
+ function sameArray(before, after) {
666
+ if (!Array.isArray(before) || !Array.isArray(after)) return false;
667
+ return before.length === after.length && before.every((item, i) => item === after[i]);
668
+ }
669
+ var SecretRedactingSpanProcessor = class {
670
+ constructor(inner, secrets = SPAN_SECRETS) {
671
+ this.inner = inner;
672
+ this.secrets = secrets;
673
+ }
674
+ inner;
675
+ secrets;
676
+ views = /* @__PURE__ */ new WeakMap();
677
+ onStart(span, parentContext) {
678
+ this.inner.onStart(this.viewFor(span), parentContext);
679
+ }
680
+ onEnd(span) {
681
+ const view = this.viewFor(span);
682
+ try {
683
+ void [view.attributes, view.events, view.status];
684
+ } catch (error) {
685
+ console.warn(
686
+ `[gatewaysdk.tracing] Dropped span "${span.name}": could not redact it: ${error?.name}`
687
+ );
688
+ return;
689
+ }
690
+ this.inner.onEnd(view);
691
+ }
692
+ viewFor(span) {
693
+ const known = this.views.get(span);
694
+ if (known) return known;
695
+ const view = viewOf(span, {
696
+ attributes: () => this.scrubbedAttributes(span.attributes),
697
+ events: () => span.events.map((event) => this.scrubbedEvent(event)),
698
+ status: () => this.scrubbedStatus(span.status)
699
+ });
700
+ this.views.set(span, view);
701
+ return view;
702
+ }
703
+ forceFlush() {
704
+ return this.inner.forceFlush();
705
+ }
706
+ shutdown() {
707
+ return this.inner.shutdown();
708
+ }
709
+ scrubbedAttributes(attributes) {
710
+ const clean = this.secrets.scrubAttributes(attributes);
711
+ return sameAttributes(attributes, clean) ? attributes : clean;
712
+ }
713
+ scrubbedStatus(status) {
714
+ if (!status.message) return status;
715
+ const message = this.secrets.scrubAttribute(status.message);
716
+ return message === status.message ? status : { ...status, message };
717
+ }
718
+ scrubbedEvent(event) {
719
+ if (!event.attributes) return event;
720
+ const attributes = this.scrubbedAttributes(event.attributes);
721
+ if (attributes === event.attributes) return event;
722
+ return { ...event, attributes };
723
+ }
724
+ };
725
+ function scrubbedRead(reads, property) {
726
+ return typeof property === "string" && property in reads ? reads[property] : void 0;
727
+ }
728
+ function viewOf(span, reads) {
729
+ const view = new Proxy(span, {
730
+ get(target, property) {
731
+ const read = scrubbedRead(reads, property);
732
+ if (read) return read();
733
+ const value = Reflect.get(target, property, target);
734
+ if (typeof value !== "function") return value;
735
+ return (...args) => {
736
+ const result = value.apply(target, args);
737
+ return result === target ? view : result;
738
+ };
739
+ },
740
+ getOwnPropertyDescriptor(target, property) {
741
+ const descriptor = Reflect.getOwnPropertyDescriptor(target, property);
742
+ const read = scrubbedRead(reads, property);
743
+ if (!read || !descriptor || !("value" in descriptor)) return descriptor;
744
+ return { ...descriptor, value: read() };
745
+ }
746
+ });
747
+ return view;
748
+ }
749
+
523
750
  // src/tracing/session.ts
524
751
  var import_async_hooks2 = require("async_hooks");
525
752
  var SESSION_ID_ATTRIBUTE = "gateway.session.id";
526
- var currentSessionStorage = new import_async_hooks2.AsyncLocalStorage();
753
+ var WORLD_SESSION_ID_ATTRIBUTE = "gateway.trace.metadata.world_session_id";
754
+ var processStorage = (name) => {
755
+ const key = /* @__PURE__ */ Symbol.for(`@withgateway/sdk/${name}`);
756
+ const slots = globalThis;
757
+ slots[key] ??= new import_async_hooks2.AsyncLocalStorage();
758
+ return slots[key];
759
+ };
760
+ var currentSessionStorage = processStorage("session-storage");
761
+ var currentWorldSessionStorage = processStorage("world-session-storage");
527
762
  function getAmbientSessionId() {
528
763
  return currentSessionStorage.getStore();
529
764
  }
530
- function withSession(sessionId, fn) {
765
+ function getCurrentWorldSessionId() {
766
+ return currentWorldSessionStorage.getStore();
767
+ }
768
+ function runIn(storage, value, fn) {
531
769
  return new Promise((resolve, reject) => {
532
- currentSessionStorage.run(sessionId, () => {
770
+ storage.run(value, () => {
533
771
  Promise.resolve().then(fn).then(resolve, reject);
534
772
  });
535
773
  });
536
774
  }
775
+ function withSession(sessionId, fn) {
776
+ return runIn(currentSessionStorage, sessionId, fn);
777
+ }
778
+ function withWorldSession(worldSessionId, fn) {
779
+ return runIn(
780
+ currentWorldSessionStorage,
781
+ worldSessionId,
782
+ () => withSession(worldSessionId, fn)
783
+ );
784
+ }
537
785
  var SessionSpanProcessor = class {
538
786
  onStart(span, _parentContext) {
787
+ const worldSessionId = getCurrentWorldSessionId();
788
+ if (worldSessionId)
789
+ span.setAttribute(WORLD_SESSION_ID_ATTRIBUTE, worldSessionId);
539
790
  const sessionId = getAmbientSessionId();
540
- if (sessionId) {
541
- span.setAttribute(SESSION_ID_ATTRIBUTE, sessionId);
542
- }
791
+ if (!sessionId || span.attributes?.[SESSION_ID_ATTRIBUTE] !== void 0)
792
+ return;
793
+ span.setAttribute(SESSION_ID_ATTRIBUTE, sessionId);
543
794
  }
544
795
  onEnd(_span) {
545
796
  }
@@ -953,22 +1204,49 @@ async function registerBuild(params) {
953
1204
  }
954
1205
  }
955
1206
 
956
- // src/tracing/init.ts
957
- var ENV_VARS = {
1207
+ // src/tracing/prerequisites.ts
1208
+ var GATEWAY_ENV = {
958
1209
  HOST: "GATEWAY_HOST",
959
1210
  PUBLIC_KEY: "GATEWAY_PUBLIC_KEY",
960
1211
  SECRET_KEY: "GATEWAY_SECRET_KEY",
961
1212
  ENDPOINT: "GATEWAY_OTLP_ENDPOINT"
962
1213
  };
1214
+ var OPENTELEMETRY_PEERS = [
1215
+ "@opentelemetry/api",
1216
+ "@opentelemetry/exporter-trace-otlp-http",
1217
+ "@opentelemetry/resources",
1218
+ "@opentelemetry/sdk-trace-base",
1219
+ "@opentelemetry/sdk-trace-node"
1220
+ ];
1221
+ var MODULE_NOT_FOUND = /* @__PURE__ */ new Set(["MODULE_NOT_FOUND", "ERR_MODULE_NOT_FOUND"]);
1222
+ function getEnv(key) {
1223
+ const value = process.env[key];
1224
+ return value ? value : void 0;
1225
+ }
1226
+ function isGatewayConfigured() {
1227
+ return !!(getEnv(GATEWAY_ENV.HOST) && getEnv(GATEWAY_ENV.PUBLIC_KEY) && getEnv(GATEWAY_ENV.SECRET_KEY));
1228
+ }
1229
+ var OpenTelemetryMissing = class _OpenTelemetryMissing extends Error {
1230
+ constructor() {
1231
+ super(
1232
+ `OpenTelemetry packages not found. Install them with:
1233
+ npm install ${OPENTELEMETRY_PEERS.join(" ")}`
1234
+ );
1235
+ this.name = "OpenTelemetryMissing";
1236
+ }
1237
+ static explains(error) {
1238
+ if (error instanceof _OpenTelemetryMissing) return true;
1239
+ const { code, message } = error ?? {};
1240
+ return MODULE_NOT_FOUND.has(String(code)) && String(message).includes("@opentelemetry/");
1241
+ }
1242
+ };
1243
+
1244
+ // src/tracing/init.ts
963
1245
  var DEFAULT_OTLP_PATH = "/api/public/otel/v1/traces";
964
1246
  var state = {
965
1247
  initialized: false,
966
1248
  provider: null
967
1249
  };
968
- function getEnv(key) {
969
- const value = process.env[key];
970
- return value ? value : void 0;
971
- }
972
1250
  function log(message, ...args) {
973
1251
  if (state.debug) {
974
1252
  console.log(`[gatewaysdk.tracing] ${message}`, ...args);
@@ -978,10 +1256,10 @@ function warn(message, ...args) {
978
1256
  console.warn(`[gatewaysdk.tracing] ${message}`, ...args);
979
1257
  }
980
1258
  function buildProvider(config, logFn) {
981
- const host = config.host ?? getEnv(ENV_VARS.HOST);
982
- const publicKey = config.publicKey ?? getEnv(ENV_VARS.PUBLIC_KEY);
983
- const secretKey = config.secretKey ?? getEnv(ENV_VARS.SECRET_KEY);
984
- const endpoint = config.endpoint ?? getEnv(ENV_VARS.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${DEFAULT_OTLP_PATH}` : void 0);
1259
+ const host = config.host ?? getEnv(GATEWAY_ENV.HOST);
1260
+ const publicKey = config.publicKey ?? getEnv(GATEWAY_ENV.PUBLIC_KEY);
1261
+ const secretKey = config.secretKey ?? getEnv(GATEWAY_ENV.SECRET_KEY);
1262
+ const endpoint = config.endpoint ?? getEnv(GATEWAY_ENV.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${DEFAULT_OTLP_PATH}` : void 0);
985
1263
  const missing = [];
986
1264
  if (!host) missing.push("host (or GATEWAY_HOST env var)");
987
1265
  if (!publicKey) missing.push("publicKey (or GATEWAY_PUBLIC_KEY env var)");
@@ -1018,9 +1296,7 @@ function buildProvider(config, logFn) {
1018
1296
  ATTR_SERVICE_NAME = "service.name";
1019
1297
  }
1020
1298
  } catch {
1021
- throw new Error(
1022
- "OpenTelemetry packages not found. Install them with:\nnpm install @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources"
1023
- );
1299
+ throw new OpenTelemetryMissing();
1024
1300
  }
1025
1301
  const resourceAttrs = {
1026
1302
  [ATTR_SERVICE_NAME]: config.serviceName ?? "gatewaysdk-tracing"
@@ -1076,7 +1352,7 @@ function buildProvider(config, logFn) {
1076
1352
  const spanProcessors = [];
1077
1353
  if (config.customSpanProcessors) {
1078
1354
  for (const sp of config.customSpanProcessors) {
1079
- spanProcessors.push(sp);
1355
+ spanProcessors.push(new SecretRedactingSpanProcessor(sp));
1080
1356
  logFn(
1081
1357
  "Added custom span processor: %s",
1082
1358
  sp.constructor?.name ?? "unknown"
@@ -1095,7 +1371,11 @@ function buildProvider(config, logFn) {
1095
1371
  if (config.batch?.maxExportBatchSize) {
1096
1372
  batchConfig.maxExportBatchSize = config.batch.maxExportBatchSize;
1097
1373
  }
1098
- spanProcessors.push(new BatchSpanProcessor(exporter, batchConfig));
1374
+ spanProcessors.push(
1375
+ new SecretRedactingSpanProcessor(
1376
+ new BatchSpanProcessor(exporter, batchConfig)
1377
+ )
1378
+ );
1099
1379
  let provider = new NodeTracerProvider({
1100
1380
  resource: createResource(resourceAttrs)
1101
1381
  });
@@ -1222,12 +1502,6 @@ async function shutdown() {
1222
1502
  function isInitialized() {
1223
1503
  return state.initialized;
1224
1504
  }
1225
- function isGatewayConfigured() {
1226
- const host = getEnv(ENV_VARS.HOST);
1227
- const publicKey = getEnv(ENV_VARS.PUBLIC_KEY);
1228
- const secretKey = getEnv(ENV_VARS.SECRET_KEY);
1229
- return !!(host && publicKey && secretKey);
1230
- }
1231
1505
 
1232
1506
  // src/tracing/observe.ts
1233
1507
  var import_api3 = require("@opentelemetry/api");
@@ -1485,14 +1759,259 @@ async function* observeClaude(stream, options) {
1485
1759
  }
1486
1760
  }
1487
1761
  }
1762
+
1763
+ // src/tracing/media.ts
1764
+ var import_node_crypto2 = require("crypto");
1765
+
1766
+ // src/worlds/transport.ts
1767
+ var PLATFORM_TIMEOUT_ENV = "GATEWAY_TIMEOUT_MS";
1768
+ var PLATFORM_TIMEOUT_DEFAULT_MS = 12e4;
1769
+ function platformTimeoutMs(env = process.env) {
1770
+ const raw = env[PLATFORM_TIMEOUT_ENV];
1771
+ if (raw === void 0 || raw === "") return PLATFORM_TIMEOUT_DEFAULT_MS;
1772
+ const value = Number(raw);
1773
+ if (Number.isInteger(value) && value > 0) return value;
1774
+ throw new Error(`${PLATFORM_TIMEOUT_ENV} must be a positive whole number of milliseconds, not \`${raw}\`.`);
1775
+ }
1776
+ var CHECK_HOST = "Check GATEWAY_HOST (or --host) points at a running platform, then retry.";
1777
+ var RETRY = "Retry; if it repeats, check the network between here and the platform.";
1778
+ var CAUSES = {
1779
+ ECONNREFUSED: { reason: "connection refused", next: CHECK_HOST },
1780
+ ENOTFOUND: { reason: "DNS lookup failed", next: CHECK_HOST },
1781
+ EAI_AGAIN: { reason: "DNS lookup failed", next: CHECK_HOST },
1782
+ ETIMEDOUT: { reason: "connect timed out", next: CHECK_HOST },
1783
+ UND_ERR_CONNECT_TIMEOUT: { reason: "connect timed out", next: CHECK_HOST },
1784
+ EHOSTUNREACH: { reason: "host unreachable", next: CHECK_HOST },
1785
+ ENETUNREACH: { reason: "network unreachable", next: RETRY },
1786
+ ECONNRESET: { reason: "connection dropped", next: RETRY },
1787
+ UND_ERR_SOCKET: { reason: "connection dropped", next: RETRY },
1788
+ EPIPE: { reason: "connection dropped", next: RETRY }
1789
+ };
1790
+ var UNKNOWN_CAUSE = { reason: "network error", next: CHECK_HOST };
1791
+ var TransportCause = class _TransportCause {
1792
+ constructor(reason, detail, next) {
1793
+ this.reason = reason;
1794
+ this.detail = detail;
1795
+ this.next = next;
1796
+ }
1797
+ reason;
1798
+ detail;
1799
+ next;
1800
+ static timeout(timeoutMs) {
1801
+ return new _TransportCause(
1802
+ `timed out after ${timeoutMs / 1e3}s`,
1803
+ null,
1804
+ `Retry; if the platform is slow, raise ${PLATFORM_TIMEOUT_ENV} (milliseconds per request).`
1805
+ );
1806
+ }
1807
+ static of(error) {
1808
+ const cause = error instanceof Error && error.cause instanceof Error ? error.cause : void 0;
1809
+ const code = cause && "code" in cause && typeof cause.code === "string" ? cause.code : null;
1810
+ const message = cause?.message ?? (error instanceof Error ? error.message : String(error));
1811
+ const known = code && CAUSES[code] || UNKNOWN_CAUSE;
1812
+ return new _TransportCause(known.reason, code ? `${code}: ${message}` : message, known.next);
1813
+ }
1814
+ describe() {
1815
+ return this.detail === null ? this.reason : `${this.reason} (${this.detail})`;
1816
+ }
1817
+ };
1818
+ var UnreachableError = class extends Error {
1819
+ constructor(host, method, route, failure) {
1820
+ super(`${method} ${route}: no answer from ${host}: ${failure.describe()}. ${failure.next}`);
1821
+ this.host = host;
1822
+ this.method = method;
1823
+ this.route = route;
1824
+ this.failure = failure;
1825
+ this.name = "UnreachableError";
1826
+ }
1827
+ host;
1828
+ method;
1829
+ route;
1830
+ failure;
1831
+ };
1832
+ var PlatformTransport = class {
1833
+ constructor(endpoint, timeoutMs = platformTimeoutMs()) {
1834
+ this.endpoint = endpoint;
1835
+ this.timeoutMs = timeoutMs;
1836
+ }
1837
+ endpoint;
1838
+ timeoutMs;
1839
+ /** A request that legitimately takes longer (a sandbox exec, a world create) waits its own budget; every other one waits the default. */
1840
+ budget(ownMs) {
1841
+ return Math.max(ownMs ?? 0, this.timeoutMs);
1842
+ }
1843
+ async send(method, route, body, opts = {}) {
1844
+ const timeoutMs = this.budget(opts.timeoutMs);
1845
+ const payload = body === void 0 ? {} : { body: JSON.stringify(body) };
1846
+ const controller = new AbortController();
1847
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
1848
+ try {
1849
+ const res = await fetch(`${this.endpoint.host}${route}`, {
1850
+ method,
1851
+ headers: {
1852
+ "content-type": "application/json",
1853
+ accept: "application/json",
1854
+ authorization: "Basic " + Buffer.from(`${this.endpoint.publicKey}:${this.endpoint.secretKey}`).toString("base64")
1855
+ },
1856
+ ...payload,
1857
+ signal: controller.signal
1858
+ });
1859
+ return { status: res.status, ok: res.ok, text: await res.text() };
1860
+ } catch (error) {
1861
+ const cause = controller.signal.aborted ? TransportCause.timeout(timeoutMs) : TransportCause.of(error);
1862
+ throw new UnreachableError(this.endpoint.host, method, route, cause);
1863
+ } finally {
1864
+ clearTimeout(timer);
1865
+ }
1866
+ }
1867
+ };
1868
+
1869
+ // src/tracing/media.ts
1870
+ var MEDIA_PATH = "/api/public/media";
1871
+ var MAX_MEDIA_BYTES = 5 * 1024 * 1024;
1872
+ var PUT_TIMEOUT_MS = 3e4;
1873
+ var MAX_UPLOAD_ERROR = 500;
1874
+ var NETWORK_FAILURE_STATUS = 599;
1875
+ var MediaUploadError = class extends Error {
1876
+ constructor(message, status) {
1877
+ super(message);
1878
+ this.status = status;
1879
+ this.name = "MediaUploadError";
1880
+ }
1881
+ status;
1882
+ };
1883
+ var MediaReference = class {
1884
+ constructor(mediaId, contentType) {
1885
+ this.mediaId = mediaId;
1886
+ this.contentType = contentType;
1887
+ }
1888
+ mediaId;
1889
+ contentType;
1890
+ toString() {
1891
+ return `@@@langfuseMedia:type=${this.contentType}|id=${this.mediaId}|source=bytes@@@`;
1892
+ }
1893
+ };
1894
+ async function putBytes(url, data, headers) {
1895
+ const controller = new AbortController();
1896
+ const timer = setTimeout(() => controller.abort(), PUT_TIMEOUT_MS);
1897
+ try {
1898
+ const res = await fetch(url, {
1899
+ method: "PUT",
1900
+ body: new Uint8Array(data),
1901
+ headers,
1902
+ signal: controller.signal
1903
+ });
1904
+ return {
1905
+ status: res.status,
1906
+ error: res.ok ? null : (await res.text()).slice(0, MAX_UPLOAD_ERROR)
1907
+ };
1908
+ } catch (error) {
1909
+ return {
1910
+ status: NETWORK_FAILURE_STATUS,
1911
+ error: error instanceof Error ? error.name : "Error"
1912
+ };
1913
+ } finally {
1914
+ clearTimeout(timer);
1915
+ }
1916
+ }
1917
+ var MediaUploader = class _MediaUploader {
1918
+ constructor(transport, put = putBytes, maxBytes = MAX_MEDIA_BYTES) {
1919
+ this.transport = transport;
1920
+ this.put = put;
1921
+ this.maxBytes = maxBytes;
1922
+ }
1923
+ transport;
1924
+ put;
1925
+ maxBytes;
1926
+ /** The uploader for `GATEWAY_HOST` / `GATEWAY_PUBLIC_KEY` /
1927
+ * `GATEWAY_SECRET_KEY` (the keys tracing exports with); null when any is unset. */
1928
+ static fromEnv(env = process.env) {
1929
+ const host = env.GATEWAY_HOST;
1930
+ const publicKey = env.GATEWAY_PUBLIC_KEY;
1931
+ const secretKey = env.GATEWAY_SECRET_KEY;
1932
+ if (!host || !publicKey || !secretKey) return null;
1933
+ return new _MediaUploader(
1934
+ new PlatformTransport({
1935
+ host: host.replace(/\/$/, ""),
1936
+ publicKey,
1937
+ secretKey
1938
+ })
1939
+ );
1940
+ }
1941
+ /** Store `data` linked to the trace (and observation) and return its reference. */
1942
+ async upload(data, link) {
1943
+ if (data.length > this.maxBytes)
1944
+ throw new MediaUploadError(
1945
+ `media is ${data.length} bytes, over the ${this.maxBytes}-byte cap`
1946
+ );
1947
+ const sha256Hash = (0, import_node_crypto2.createHash)("sha256").update(data).digest("base64");
1948
+ const answer = await this.send("POST", MEDIA_PATH, {
1949
+ traceId: link.traceId,
1950
+ observationId: link.observationId,
1951
+ contentType: link.contentType,
1952
+ contentLength: data.length,
1953
+ sha256Hash,
1954
+ field: link.field
1955
+ });
1956
+ if (typeof answer.mediaId !== "string" || !answer.mediaId)
1957
+ throw new MediaUploadError(
1958
+ "POST /api/public/media answered without a mediaId"
1959
+ );
1960
+ const reference = new MediaReference(answer.mediaId, link.contentType);
1961
+ if (answer.uploadUrl)
1962
+ await this.store(reference, answer.uploadUrl, data, sha256Hash);
1963
+ return reference;
1964
+ }
1965
+ async store(reference, url, data, sha256Hash) {
1966
+ const started = Date.now();
1967
+ const { status, error } = await this.put(url, data, {
1968
+ "Content-Type": reference.contentType,
1969
+ "x-amz-checksum-sha256": sha256Hash,
1970
+ "x-ms-blob-type": "BlockBlob"
1971
+ });
1972
+ await this.send(
1973
+ "PATCH",
1974
+ `${MEDIA_PATH}/${encodeURIComponent(reference.mediaId)}`,
1975
+ {
1976
+ uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
1977
+ uploadHttpStatus: status,
1978
+ uploadHttpError: error,
1979
+ uploadTimeMs: Date.now() - started
1980
+ }
1981
+ );
1982
+ if (status < 200 || status >= 300)
1983
+ throw new MediaUploadError(
1984
+ `media storage refused the upload (HTTP ${status})`,
1985
+ status
1986
+ );
1987
+ }
1988
+ async send(method, route, body) {
1989
+ const reply = await this.transport.send(method, route, body);
1990
+ if (!reply.ok)
1991
+ throw new MediaUploadError(
1992
+ `${method} ${route} -> ${reply.status}`,
1993
+ reply.status
1994
+ );
1995
+ return reply.text ? JSON.parse(reply.text) : {};
1996
+ }
1997
+ };
1488
1998
  // Annotate the CommonJS export names for ESM import in node:
1489
1999
  0 && (module.exports = {
1490
2000
  IdentitySpanProcessor,
2001
+ MAX_MEDIA_BYTES,
2002
+ MediaReference,
2003
+ MediaUploadError,
2004
+ MediaUploader,
2005
+ SECRET_KEYS,
1491
2006
  SESSION_ID_ATTRIBUTE,
2007
+ SecretRedactingSpanProcessor,
1492
2008
  SessionSpanProcessor,
2009
+ SpanSecrets,
1493
2010
  USER_ID_ATTRIBUTE,
2011
+ WORLD_SESSION_ID_ATTRIBUTE,
1494
2012
  flush,
1495
2013
  getAmbientSessionId,
2014
+ getCurrentWorldSessionId,
1496
2015
  identify,
1497
2016
  init,
1498
2017
  initIsolated,
@@ -1505,6 +2024,7 @@ async function* observeClaude(stream, options) {
1505
2024
  resetAmbientUser,
1506
2025
  resolveUserId,
1507
2026
  shutdown,
1508
- withSession
2027
+ withSession,
2028
+ withWorldSession
1509
2029
  });
1510
2030
  //# sourceMappingURL=index.js.map