@withgateway/sdk 0.1.11 → 0.1.13

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.
@@ -25,7 +25,7 @@ var require_package = __commonJS({
25
25
  "package.json"(exports2, module2) {
26
26
  module2.exports = {
27
27
  name: "@withgateway/sdk",
28
- version: "0.1.11",
28
+ version: "0.1.13",
29
29
  description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
30
30
  main: "./dist/index.js",
31
31
  module: "./dist/index.mjs",
@@ -80,6 +80,11 @@ var require_package = __commonJS({
80
80
  types: "./dist/users/index.d.ts",
81
81
  import: "./dist/users/index.mjs",
82
82
  require: "./dist/users/index.js"
83
+ },
84
+ "./scores": {
85
+ types: "./dist/scores/index.d.ts",
86
+ import: "./dist/scores/index.mjs",
87
+ require: "./dist/scores/index.js"
83
88
  }
84
89
  },
85
90
  files: [
@@ -450,6 +455,216 @@ function debugLog(message, ...args) {
450
455
  }
451
456
  }
452
457
 
458
+ // src/scores/index.ts
459
+ var import_api2 = require("@opentelemetry/api");
460
+ var SUCCESS_SIGNAL_KEY = "gateway.success.signal";
461
+ var SUCCESS_METRIC_NAME_KEY = "gateway.success.metricName";
462
+ var AGENT_ID_KEY = "gateway.agent.id";
463
+ var ScoreError = class extends Error {
464
+ constructor(message, options) {
465
+ super(message);
466
+ this.name = "ScoreError";
467
+ this.cause = options?.cause;
468
+ }
469
+ };
470
+ function currentTraceId() {
471
+ try {
472
+ const span = import_api2.trace.getActiveSpan();
473
+ if (!span) return void 0;
474
+ const ctx = span.spanContext();
475
+ if (!ctx || !(0, import_api2.isSpanContextValid)(ctx)) return void 0;
476
+ return ctx.traceId;
477
+ } catch {
478
+ return void 0;
479
+ }
480
+ }
481
+ var ScoresClient = class _ScoresClient {
482
+ host;
483
+ publicKey;
484
+ secretKey;
485
+ timeoutSeconds;
486
+ debug;
487
+ constructor(config) {
488
+ this.host = config.host.replace(/\/$/, "");
489
+ this.publicKey = config.publicKey;
490
+ this.secretKey = config.secretKey;
491
+ this.timeoutSeconds = config.timeoutSeconds ?? 15;
492
+ this.debug = config.debug ?? false;
493
+ }
494
+ /** Create a client from GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY. */
495
+ static fromEnv(config = {}) {
496
+ const host = config.host ?? process.env.GATEWAY_HOST;
497
+ const publicKey = config.publicKey ?? process.env.GATEWAY_PUBLIC_KEY;
498
+ const secretKey = config.secretKey ?? process.env.GATEWAY_SECRET_KEY;
499
+ const missing = [
500
+ ["host", host],
501
+ ["publicKey", publicKey],
502
+ ["secretKey", secretKey]
503
+ ].filter(([, value]) => !value).map(([name]) => name);
504
+ if (missing.length > 0) {
505
+ throw new ScoreError(
506
+ `Missing Gateway scores configuration: ${missing.join(", ")}`
507
+ );
508
+ }
509
+ return new _ScoresClient({
510
+ ...config,
511
+ host,
512
+ publicKey,
513
+ secretKey
514
+ });
515
+ }
516
+ /**
517
+ * Post a score, throwing {@link ScoreError} on any failure. Builds the exact
518
+ * `POST /api/public/scores` body the Python SDK sends: exactly one of
519
+ * `sessionId` / `traceId` (+ optional `observationId`) / `datasetRunId`.
520
+ * When no target is provided, the active OTel trace id is used; if none is
521
+ * available the call is a no-op (returns without posting), matching Python.
522
+ */
523
+ async postScore(name, value, options = {}) {
524
+ const body = this.buildScoreBody(name, value, options);
525
+ if (!body) {
526
+ this.log(
527
+ "score '%s' dropped: no sessionId, traceId or datasetRunId available",
528
+ name
529
+ );
530
+ return;
531
+ }
532
+ await this.request("POST", "/api/public/scores", body);
533
+ }
534
+ /**
535
+ * Build the score request body, or null when no target can be resolved.
536
+ * Split out so it is unit-testable and shared by score()/success().
537
+ */
538
+ buildScoreBody(name, value, options = {}) {
539
+ const traceId = options.traceId ?? currentTraceId();
540
+ const target = {};
541
+ if (options.sessionId) {
542
+ target.sessionId = options.sessionId;
543
+ } else if (options.datasetRunId) {
544
+ target.datasetRunId = options.datasetRunId;
545
+ } else if (traceId) {
546
+ target.traceId = traceId;
547
+ if (options.observationId) target.observationId = options.observationId;
548
+ } else {
549
+ return null;
550
+ }
551
+ const metadata = {
552
+ source: "gatewaysdk",
553
+ ...options.metadata ?? {}
554
+ };
555
+ return {
556
+ name,
557
+ value,
558
+ dataType: options.dataType ?? "NUMERIC",
559
+ environment: options.environment ?? "default",
560
+ ...options.comment ? { comment: options.comment } : {},
561
+ metadata,
562
+ ...target
563
+ };
564
+ }
565
+ /**
566
+ * Post a score, FAIL-SOFT: warns and resolves on any failure so a broken
567
+ * transport never throws into (or rejects out of) the caller.
568
+ */
569
+ async score(name, value, options = {}) {
570
+ try {
571
+ await this.postScore(name, value, options);
572
+ } catch (error) {
573
+ this.warn(`score '${name}' failed`, error);
574
+ }
575
+ }
576
+ /**
577
+ * Emit a SUCCESS SIGNAL that feeds a Gateway Success Metric — a score tagged
578
+ * with `gateway.success.signal` + `gateway.success.metricName` (and the agent
579
+ * identity when `agentId` is set). A boolean `value` records a 1/0 BOOLEAN
580
+ * score (pass/fail); a number records a NUMERIC score. FAIL-SOFT.
581
+ *
582
+ * The metadata shape matches the Python SDK's `Run.success()` exactly, so the
583
+ * platform's Success Metrics aggregation counts signals from either SDK
584
+ * without change.
585
+ *
586
+ * @example
587
+ * ```ts
588
+ * await scores.success("resolved_ticket", true, { agentId: "support-triage", sessionId });
589
+ * await scores.success("handle_time_s", 42, { agentId: "support-triage", sessionId });
590
+ * ```
591
+ */
592
+ async success(name, value = true, options = {}) {
593
+ const { numericValue, inferredType } = coerceSignalValue(value);
594
+ const { agentId, metricName, metadata, dataType, ...rest } = options;
595
+ const signalMetadata = {
596
+ ...metadata ?? {},
597
+ [SUCCESS_SIGNAL_KEY]: true,
598
+ [SUCCESS_METRIC_NAME_KEY]: metricName ?? name,
599
+ ...agentId ? { [AGENT_ID_KEY]: agentId } : {}
600
+ };
601
+ await this.score(name, numericValue, {
602
+ ...rest,
603
+ dataType: dataType ?? inferredType,
604
+ metadata: signalMetadata
605
+ });
606
+ }
607
+ async request(method, path, payload) {
608
+ let response;
609
+ try {
610
+ response = await fetch(`${this.host}${path}`, {
611
+ method,
612
+ headers: {
613
+ Authorization: this.authHeader(),
614
+ "Content-Type": "application/json"
615
+ },
616
+ body: JSON.stringify(payload),
617
+ signal: AbortSignal.timeout(this.timeoutSeconds * 1e3)
618
+ });
619
+ } catch (error) {
620
+ throw new ScoreError(
621
+ `${method} ${path} failed: ${error instanceof Error ? error.message : String(error)}`,
622
+ { cause: error }
623
+ );
624
+ }
625
+ const text = await response.text();
626
+ if (!response.ok) {
627
+ throw new ScoreError(
628
+ `${method} ${path} failed (${response.status}): ${text.slice(0, 500)}`
629
+ );
630
+ }
631
+ this.log("%s %s -> %s", method, path, response.status);
632
+ }
633
+ authHeader() {
634
+ return `Basic ${Buffer.from(`${this.publicKey}:${this.secretKey}`).toString(
635
+ "base64"
636
+ )}`;
637
+ }
638
+ log(message, ...args) {
639
+ if (this.debug) {
640
+ console.log(`[gateway.scores] ${message}`, ...args);
641
+ }
642
+ }
643
+ warn(message, ...args) {
644
+ console.warn(`[gateway.scores] ${message}`, ...args);
645
+ }
646
+ };
647
+ function coerceSignalValue(value) {
648
+ if (typeof value === "boolean") {
649
+ return { numericValue: value ? 1 : 0, inferredType: "BOOLEAN" };
650
+ }
651
+ return { numericValue: value, inferredType: "NUMERIC" };
652
+ }
653
+ async function success(name, value = true, options = {}) {
654
+ let client;
655
+ try {
656
+ client = ScoresClient.fromEnv();
657
+ } catch (error) {
658
+ console.warn(`[gateway.scores] success '${name}' skipped`, error);
659
+ return;
660
+ }
661
+ await client.success(name, value, options);
662
+ }
663
+ var scores = {
664
+ fromEnv: ScoresClient.fromEnv,
665
+ success
666
+ };
667
+
453
668
  // src/build/index.ts
454
669
  var import_node_crypto = require("crypto");
455
670
  function canonicalJson(value) {
@@ -468,11 +683,17 @@ function sha256(text) {
468
683
  var registeredTools = /* @__PURE__ */ new Map();
469
684
  var registeredPrompts = /* @__PURE__ */ new Map();
470
685
  var registeredSkills = /* @__PURE__ */ new Map();
686
+ var registeredArtifacts = /* @__PURE__ */ new Map();
471
687
  function getRegisteredTools() {
472
688
  return [...registeredTools.values()].sort(
473
689
  (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
474
690
  );
475
691
  }
692
+ function getRegisteredArtifacts() {
693
+ return [...registeredArtifacts.values()].sort(
694
+ (a, b) => `${a.kind}:${a.name}` < `${b.kind}:${b.name}` ? -1 : 1
695
+ );
696
+ }
476
697
  function getRegisteredSkills() {
477
698
  return Object.fromEntries(
478
699
  [...registeredSkills.entries()].sort(
@@ -495,11 +716,62 @@ function sdkVersion() {
495
716
  return "@withgateway/sdk";
496
717
  }
497
718
  }
719
+ function paasGitContext() {
720
+ const env = process.env;
721
+ if (env.VERCEL_GIT_COMMIT_SHA) {
722
+ const isGithub = (env.VERCEL_GIT_PROVIDER ?? "github") === "github";
723
+ return {
724
+ provider: "vercel",
725
+ sha: env.VERCEL_GIT_COMMIT_SHA,
726
+ repo: isGithub && env.VERCEL_GIT_REPO_OWNER && env.VERCEL_GIT_REPO_SLUG ? `${env.VERCEL_GIT_REPO_OWNER}/${env.VERCEL_GIT_REPO_SLUG}` : void 0,
727
+ branch: env.VERCEL_GIT_COMMIT_REF,
728
+ login: env.VERCEL_GIT_COMMIT_AUTHOR_LOGIN
729
+ };
730
+ }
731
+ if (env.RENDER_GIT_COMMIT) {
732
+ return {
733
+ provider: "render",
734
+ sha: env.RENDER_GIT_COMMIT,
735
+ repo: env.RENDER_GIT_REPO_SLUG,
736
+ // already "owner/repo"
737
+ branch: env.RENDER_GIT_BRANCH
738
+ };
739
+ }
740
+ if (env.RAILWAY_GIT_COMMIT_SHA) {
741
+ return {
742
+ provider: "railway",
743
+ sha: env.RAILWAY_GIT_COMMIT_SHA,
744
+ repo: env.RAILWAY_GIT_REPO_OWNER && env.RAILWAY_GIT_REPO_NAME ? `${env.RAILWAY_GIT_REPO_OWNER}/${env.RAILWAY_GIT_REPO_NAME}` : void 0,
745
+ branch: env.RAILWAY_GIT_BRANCH,
746
+ login: env.RAILWAY_GIT_AUTHOR
747
+ };
748
+ }
749
+ if (env.NETLIFY && env.COMMIT_REF) {
750
+ const repoMatch = /github\.com[/:]([^/]+\/[^/.]+)/.exec(
751
+ env.REPOSITORY_URL ?? ""
752
+ );
753
+ return {
754
+ provider: "netlify",
755
+ sha: env.COMMIT_REF,
756
+ repo: repoMatch?.[1],
757
+ branch: env.BRANCH
758
+ };
759
+ }
760
+ const bareSha = env.HEROKU_SLUG_COMMIT ?? env.SOURCE_VERSION ?? env.GIT_COMMIT ?? env.COMMIT_SHA;
761
+ if (bareSha) {
762
+ return {
763
+ provider: env.HEROKU_SLUG_COMMIT || env.SOURCE_VERSION ? "heroku" : "generic",
764
+ sha: bareSha
765
+ };
766
+ }
767
+ return null;
768
+ }
498
769
  function codeRef() {
770
+ const paas = paasGitContext();
499
771
  const sha = process.env.GATEWAY_COMMIT ?? process.env.GITHUB_SHA ?? process.env.CI_COMMIT_SHA ?? // GitLab
500
- process.env.CIRCLE_SHA1;
772
+ process.env.CIRCLE_SHA1 ?? paas?.sha;
501
773
  if (!sha) return void 0;
502
- const repo = process.env.GITHUB_REPOSITORY ?? process.env.CI_PROJECT_PATH;
774
+ const repo = process.env.GITHUB_REPOSITORY ?? process.env.CI_PROJECT_PATH ?? paas?.repo;
503
775
  return repo ? `git:${repo}@${sha}` : `git:${sha}`;
504
776
  }
505
777
  function assembleManifest(agentId) {
@@ -509,13 +781,17 @@ function assembleManifest(agentId) {
509
781
  sdk: sdkVersion(),
510
782
  tools: getRegisteredTools(),
511
783
  prompts: getRegisteredPrompts(),
512
- skills: getRegisteredSkills()
784
+ skills: getRegisteredSkills(),
785
+ artifacts: getRegisteredArtifacts()
513
786
  };
514
787
  }
515
788
  function computeBuildHash(manifest) {
516
789
  const identity = {
517
790
  ...manifest,
518
- tools: manifest.tools.map(({ source: _source, ...tool }) => tool)
791
+ tools: manifest.tools.map(({ source: _source, ...tool }) => tool),
792
+ artifacts: manifest.artifacts.map(
793
+ ({ source: _source, ...artifact }) => artifact
794
+ )
519
795
  };
520
796
  return sha256(canonicalJson(identity));
521
797
  }
@@ -528,6 +804,14 @@ function attributionFromEnv() {
528
804
  if (process.env.GITHUB_REPOSITORY) attribution.repo = process.env.GITHUB_REPOSITORY;
529
805
  const branch = process.env.GITHUB_HEAD_REF ?? process.env.GITHUB_REF_NAME;
530
806
  if (branch) attribution.branch = branch;
807
+ const paas = paasGitContext();
808
+ if (paas) {
809
+ if (attribution.source === "runtime") attribution.source = `paas:${paas.provider}`;
810
+ if (!attribution.commitSha && paas.sha) attribution.commitSha = paas.sha;
811
+ if (!attribution.repo && paas.repo) attribution.repo = paas.repo;
812
+ if (!attribution.branch && paas.branch) attribution.branch = paas.branch;
813
+ if (!attribution.githubLogin && paas.login) attribution.githubLogin = paas.login;
814
+ }
531
815
  const ref = process.env.GITHUB_REF ?? "";
532
816
  const prMatch = /refs\/pull\/(\d+)\//.exec(ref);
533
817
  if (prMatch) attribution.prNumber = Number(prMatch[1]);
@@ -785,12 +1069,19 @@ function initIsolated(config = {}) {
785
1069
  const provider = built.provider;
786
1070
  scheduleBuildRegistration(config, built);
787
1071
  const tracer = provider.getTracer("@withgateway/sdk");
1072
+ const scores2 = new ScoresClient({
1073
+ host: built.connection.host,
1074
+ publicKey: built.connection.publicKey,
1075
+ secretKey: built.connection.secretKey,
1076
+ debug: config.debug ?? false
1077
+ });
788
1078
  debugLog2(
789
1079
  "Isolated tracing provider created (service=%s)",
790
1080
  config.serviceName ?? "gatewaysdk-tracing"
791
1081
  );
792
1082
  return {
793
1083
  tracer,
1084
+ scores: scores2,
794
1085
  async flush() {
795
1086
  try {
796
1087
  await provider.forceFlush();
@@ -844,12 +1135,12 @@ function isGatewayConfigured() {
844
1135
  }
845
1136
 
846
1137
  // src/tracing/observe.ts
847
- var import_api2 = require("@opentelemetry/api");
1138
+ var import_api3 = require("@opentelemetry/api");
848
1139
  function asAttr(value) {
849
1140
  return typeof value === "string" ? value : JSON.stringify(value);
850
1141
  }
851
1142
  async function observe(name, fn, options = {}) {
852
- const tracer = options.tracer ?? import_api2.trace.getTracer("@withgateway/sdk");
1143
+ const tracer = options.tracer ?? import_api3.trace.getTracer("@withgateway/sdk");
853
1144
  const span = tracer.startSpan(name, {
854
1145
  attributes: {
855
1146
  "openinference.span.kind": options.kind ?? "AGENT",
@@ -858,18 +1149,18 @@ async function observe(name, fn, options = {}) {
858
1149
  }
859
1150
  });
860
1151
  try {
861
- const result = await import_api2.context.with(
862
- import_api2.trace.setSpan(import_api2.context.active(), span),
1152
+ const result = await import_api3.context.with(
1153
+ import_api3.trace.setSpan(import_api3.context.active(), span),
863
1154
  fn
864
1155
  );
865
1156
  if (options.captureOutput !== false && result !== void 0) {
866
1157
  span.setAttribute("output.value", asAttr(result));
867
1158
  }
868
- span.setStatus({ code: import_api2.SpanStatusCode.OK });
1159
+ span.setStatus({ code: import_api3.SpanStatusCode.OK });
869
1160
  return result;
870
1161
  } catch (error) {
871
1162
  span.setStatus({
872
- code: import_api2.SpanStatusCode.ERROR,
1163
+ code: import_api3.SpanStatusCode.ERROR,
873
1164
  message: error instanceof Error ? error.message : String(error)
874
1165
  });
875
1166
  throw error;
@@ -916,7 +1207,7 @@ function observeAnthropic(client) {
916
1207
  }
917
1208
 
918
1209
  // src/tracing/claude.ts
919
- var import_api3 = require("@opentelemetry/api");
1210
+ var import_api4 = require("@opentelemetry/api");
920
1211
  function cleanToolName(name) {
921
1212
  return name.replace(/^mcp__[^_]+__/, "");
922
1213
  }
@@ -930,7 +1221,7 @@ function toolResultText(content) {
930
1221
  }
931
1222
  var TURN_INPUT_MAX = 4e3;
932
1223
  async function* observeClaude(stream, options) {
933
- const tracer = options.tracer ?? import_api3.trace.getTracer("@withgateway/sdk");
1224
+ const tracer = options.tracer ?? import_api4.trace.getTracer("@withgateway/sdk");
934
1225
  const model = options.model ?? "claude";
935
1226
  const openTools = /* @__PURE__ */ new Map();
936
1227
  let root = null;
@@ -943,7 +1234,7 @@ async function* observeClaude(stream, options) {
943
1234
  ...options.attributes ?? {}
944
1235
  }
945
1236
  });
946
- rootCtx = import_api3.trace.setSpan(import_api3.context.active(), root);
1237
+ rootCtx = import_api4.trace.setSpan(import_api4.context.active(), root);
947
1238
  }
948
1239
  let turnRoot = null;
949
1240
  let turnCtx = null;
@@ -954,7 +1245,7 @@ async function* observeClaude(stream, options) {
954
1245
  const endTurn = () => {
955
1246
  if (!turnRoot) return;
956
1247
  if (turnText) turnRoot.setAttribute("output.value", turnText);
957
- turnRoot.setStatus({ code: import_api3.SpanStatusCode.OK });
1248
+ turnRoot.setStatus({ code: import_api4.SpanStatusCode.OK });
958
1249
  turnRoot.end();
959
1250
  turnRoot = null;
960
1251
  turnCtx = null;
@@ -976,7 +1267,7 @@ async function* observeClaude(stream, options) {
976
1267
  ...options.attributes ?? {}
977
1268
  }
978
1269
  });
979
- turnCtx = import_api3.trace.setSpan(import_api3.context.active(), turnRoot);
1270
+ turnCtx = import_api4.trace.setSpan(import_api4.context.active(), turnRoot);
980
1271
  pendingTurnInput = "";
981
1272
  }
982
1273
  const childCtx = options.perTurn ? turnCtx : rootCtx;
@@ -1038,7 +1329,7 @@ async function* observeClaude(stream, options) {
1038
1329
  const span = openTools.get(block.tool_use_id);
1039
1330
  if (span) {
1040
1331
  span.setAttribute("output.value", resultText);
1041
- span.setStatus({ code: import_api3.SpanStatusCode.OK });
1332
+ span.setStatus({ code: import_api4.SpanStatusCode.OK });
1042
1333
  span.end();
1043
1334
  openTools.delete(block.tool_use_id);
1044
1335
  }
@@ -1058,7 +1349,7 @@ async function* observeClaude(stream, options) {
1058
1349
  endTurn();
1059
1350
  } else if (root) {
1060
1351
  root.setAttribute("output.value", finalText);
1061
- root.setStatus({ code: import_api3.SpanStatusCode.OK });
1352
+ root.setStatus({ code: import_api4.SpanStatusCode.OK });
1062
1353
  root.end();
1063
1354
  }
1064
1355
  }