@withgateway/sdk 0.1.11 → 0.1.12

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.
package/dist/index.d.mts CHANGED
@@ -22,6 +22,18 @@ interface ToolIdentity {
22
22
  /** Source location of the defineTool call ("src/tools/checkout.ts:42"). */
23
23
  source?: string;
24
24
  }
25
+ /** Any versioned artifact an agent is built from — tools, prompts, skills,
26
+ * datasets, guardrails, configs… `content` hashes locally (off-platform);
27
+ * `ref` pins a platform-hosted artifact ("prompt/system@label:production"). */
28
+ interface ArtifactIdentity {
29
+ kind: string;
30
+ name: string;
31
+ version?: string;
32
+ contentHash?: string;
33
+ ref?: string;
34
+ source?: string;
35
+ metadata?: Record<string, string>;
36
+ }
25
37
  interface AgentBuildManifest {
26
38
  agentId: string;
27
39
  codeRef?: string;
@@ -29,6 +41,7 @@ interface AgentBuildManifest {
29
41
  tools: ToolIdentity[];
30
42
  prompts: Record<string, string>;
31
43
  skills: Record<string, string>;
44
+ artifacts: ArtifactIdentity[];
32
45
  }
33
46
  /** Deterministic JSON: object keys sorted recursively, arrays kept in order. */
34
47
  declare function canonicalJson(value: unknown): string;
@@ -61,14 +74,39 @@ declare function defineTool<T extends DefineToolInput>(tool: T): T;
61
74
  * `const SYSTEM = registerPrompt("system", "You are…")`. Returns the content
62
75
  * unchanged. Platform-served prompts don't need this — pin them by label.
63
76
  */
64
- declare function registerPrompt(name: string, content: string): string;
77
+ interface RegisterArtifactOptions {
78
+ /** Developer-declared version, e.g. "1.2" (v1: bumped manually). */
79
+ version?: string;
80
+ /** Local content — hashed into the identity (off-platform artifacts). */
81
+ content?: string;
82
+ /** Platform reference (on-platform artifacts): "prompt/system@label:production". */
83
+ ref?: string;
84
+ metadata?: Record<string, string>;
85
+ }
86
+ /**
87
+ * Version ANY artifact the agent is built from — the generic primitive
88
+ * behind registerPrompt/registerSkill. Works on- and off-platform:
89
+ *
90
+ * ```ts
91
+ * registerArtifact("guardrail", "pii-filter", { version: "2.0", content: RULES });
92
+ * registerArtifact("prompt", "planner", { ref: "planner@label:production" });
93
+ * ```
94
+ */
95
+ declare function registerArtifact(kind: string, name: string, options?: RegisterArtifactOptions): ArtifactIdentity;
96
+ declare function registerPrompt(name: string, content: string, options?: {
97
+ version?: string;
98
+ }): string;
65
99
  declare function getRegisteredTools(): ToolIdentity[];
66
100
  /**
67
101
  * Register a skill's identity — `registerSkill("triage", "1.0")` — so skills
68
102
  * are versioned in the build like tools and prompts. The version string is
69
103
  * whatever you bump (or a content hash for file-based skills).
70
104
  */
71
- declare function registerSkill(name: string, version: string): void;
105
+ declare function registerSkill(name: string, version: string, options?: {
106
+ content?: string;
107
+ ref?: string;
108
+ }): void;
109
+ declare function getRegisteredArtifacts(): ArtifactIdentity[];
72
110
  declare function getRegisteredSkills(): Record<string, string>;
73
111
  declare function getRegisteredPrompts(): Record<string, string>;
74
112
  /** Test hook. */
@@ -86,4 +124,4 @@ declare function computeBuildHash(manifest: AgentBuildManifest): string;
86
124
  */
87
125
  declare const tracing: typeof _tracingModule;
88
126
 
89
- export { type AgentBuildManifest, type DefineToolInput, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredPrompts, getRegisteredSkills, getRegisteredTools, registerPrompt, registerSkill, resetBuildRegistry, tracing };
127
+ export { type AgentBuildManifest, type ArtifactIdentity, type DefineToolInput, type RegisterArtifactOptions, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredArtifacts, getRegisteredPrompts, getRegisteredSkills, getRegisteredTools, registerArtifact, registerPrompt, registerSkill, resetBuildRegistry, tracing };
package/dist/index.d.ts CHANGED
@@ -22,6 +22,18 @@ interface ToolIdentity {
22
22
  /** Source location of the defineTool call ("src/tools/checkout.ts:42"). */
23
23
  source?: string;
24
24
  }
25
+ /** Any versioned artifact an agent is built from — tools, prompts, skills,
26
+ * datasets, guardrails, configs… `content` hashes locally (off-platform);
27
+ * `ref` pins a platform-hosted artifact ("prompt/system@label:production"). */
28
+ interface ArtifactIdentity {
29
+ kind: string;
30
+ name: string;
31
+ version?: string;
32
+ contentHash?: string;
33
+ ref?: string;
34
+ source?: string;
35
+ metadata?: Record<string, string>;
36
+ }
25
37
  interface AgentBuildManifest {
26
38
  agentId: string;
27
39
  codeRef?: string;
@@ -29,6 +41,7 @@ interface AgentBuildManifest {
29
41
  tools: ToolIdentity[];
30
42
  prompts: Record<string, string>;
31
43
  skills: Record<string, string>;
44
+ artifacts: ArtifactIdentity[];
32
45
  }
33
46
  /** Deterministic JSON: object keys sorted recursively, arrays kept in order. */
34
47
  declare function canonicalJson(value: unknown): string;
@@ -61,14 +74,39 @@ declare function defineTool<T extends DefineToolInput>(tool: T): T;
61
74
  * `const SYSTEM = registerPrompt("system", "You are…")`. Returns the content
62
75
  * unchanged. Platform-served prompts don't need this — pin them by label.
63
76
  */
64
- declare function registerPrompt(name: string, content: string): string;
77
+ interface RegisterArtifactOptions {
78
+ /** Developer-declared version, e.g. "1.2" (v1: bumped manually). */
79
+ version?: string;
80
+ /** Local content — hashed into the identity (off-platform artifacts). */
81
+ content?: string;
82
+ /** Platform reference (on-platform artifacts): "prompt/system@label:production". */
83
+ ref?: string;
84
+ metadata?: Record<string, string>;
85
+ }
86
+ /**
87
+ * Version ANY artifact the agent is built from — the generic primitive
88
+ * behind registerPrompt/registerSkill. Works on- and off-platform:
89
+ *
90
+ * ```ts
91
+ * registerArtifact("guardrail", "pii-filter", { version: "2.0", content: RULES });
92
+ * registerArtifact("prompt", "planner", { ref: "planner@label:production" });
93
+ * ```
94
+ */
95
+ declare function registerArtifact(kind: string, name: string, options?: RegisterArtifactOptions): ArtifactIdentity;
96
+ declare function registerPrompt(name: string, content: string, options?: {
97
+ version?: string;
98
+ }): string;
65
99
  declare function getRegisteredTools(): ToolIdentity[];
66
100
  /**
67
101
  * Register a skill's identity — `registerSkill("triage", "1.0")` — so skills
68
102
  * are versioned in the build like tools and prompts. The version string is
69
103
  * whatever you bump (or a content hash for file-based skills).
70
104
  */
71
- declare function registerSkill(name: string, version: string): void;
105
+ declare function registerSkill(name: string, version: string, options?: {
106
+ content?: string;
107
+ ref?: string;
108
+ }): void;
109
+ declare function getRegisteredArtifacts(): ArtifactIdentity[];
72
110
  declare function getRegisteredSkills(): Record<string, string>;
73
111
  declare function getRegisteredPrompts(): Record<string, string>;
74
112
  /** Test hook. */
@@ -86,4 +124,4 @@ declare function computeBuildHash(manifest: AgentBuildManifest): string;
86
124
  */
87
125
  declare const tracing: typeof _tracingModule;
88
126
 
89
- export { type AgentBuildManifest, type DefineToolInput, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredPrompts, getRegisteredSkills, getRegisteredTools, registerPrompt, registerSkill, resetBuildRegistry, tracing };
127
+ export { type AgentBuildManifest, type ArtifactIdentity, type DefineToolInput, type RegisterArtifactOptions, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredArtifacts, getRegisteredPrompts, getRegisteredSkills, getRegisteredTools, registerArtifact, registerPrompt, registerSkill, resetBuildRegistry, tracing };
package/dist/index.js CHANGED
@@ -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.12",
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",
@@ -216,6 +216,7 @@ __export(src_exports, {
216
216
  experiments: () => singleton_exports,
217
217
  gateway: () => gateway,
218
218
  getExperimentContext: () => getExperimentContext,
219
+ getRegisteredArtifacts: () => getRegisteredArtifacts,
219
220
  getRegisteredPrompts: () => getRegisteredPrompts,
220
221
  getRegisteredSkills: () => getRegisteredSkills,
221
222
  getRegisteredTools: () => getRegisteredTools,
@@ -223,6 +224,7 @@ __export(src_exports, {
223
224
  loadSession: () => loadSession,
224
225
  memory: () => memory,
225
226
  personas: () => personas,
227
+ registerArtifact: () => registerArtifact,
226
228
  registerPrompt: () => registerPrompt,
227
229
  registerSkill: () => registerSkill,
228
230
  renderAgentSystem: () => renderAgentSystem,
@@ -2846,6 +2848,7 @@ function sha256(text) {
2846
2848
  var registeredTools = /* @__PURE__ */ new Map();
2847
2849
  var registeredPrompts = /* @__PURE__ */ new Map();
2848
2850
  var registeredSkills = /* @__PURE__ */ new Map();
2851
+ var registeredArtifacts = /* @__PURE__ */ new Map();
2849
2852
  function captureSource() {
2850
2853
  const stack = new Error().stack?.split("\n") ?? [];
2851
2854
  for (const line of stack.slice(1)) {
@@ -2879,9 +2882,24 @@ function defineTool(tool) {
2879
2882
  notifyRegistryChanged();
2880
2883
  return tool;
2881
2884
  }
2882
- function registerPrompt(name, content) {
2883
- registeredPrompts.set(name, sha256(content));
2885
+ function registerArtifact(kind, name, options = {}) {
2886
+ const source = captureSource();
2887
+ const identity = {
2888
+ kind,
2889
+ name,
2890
+ ...options.version !== void 0 ? { version: options.version } : {},
2891
+ ...options.content !== void 0 ? { contentHash: sha256(options.content) } : {},
2892
+ ...options.ref !== void 0 ? { ref: options.ref } : {},
2893
+ ...source ? { source } : {},
2894
+ ...options.metadata ? { metadata: options.metadata } : {}
2895
+ };
2896
+ registeredArtifacts.set(`${kind}:${name}`, identity);
2884
2897
  notifyRegistryChanged();
2898
+ return identity;
2899
+ }
2900
+ function registerPrompt(name, content, options = {}) {
2901
+ registeredPrompts.set(name, sha256(content));
2902
+ registerArtifact("prompt", name, { ...options, content });
2885
2903
  return content;
2886
2904
  }
2887
2905
  function getRegisteredTools() {
@@ -2889,9 +2907,14 @@ function getRegisteredTools() {
2889
2907
  (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
2890
2908
  );
2891
2909
  }
2892
- function registerSkill(name, version) {
2910
+ function registerSkill(name, version, options = {}) {
2893
2911
  registeredSkills.set(name, version);
2894
- notifyRegistryChanged();
2912
+ registerArtifact("skill", name, { version, ...options });
2913
+ }
2914
+ function getRegisteredArtifacts() {
2915
+ return [...registeredArtifacts.values()].sort(
2916
+ (a, b) => `${a.kind}:${a.name}` < `${b.kind}:${b.name}` ? -1 : 1
2917
+ );
2895
2918
  }
2896
2919
  function getRegisteredSkills() {
2897
2920
  return Object.fromEntries(
@@ -2911,6 +2934,7 @@ function resetBuildRegistry() {
2911
2934
  registeredTools.clear();
2912
2935
  registeredPrompts.clear();
2913
2936
  registeredSkills.clear();
2937
+ registeredArtifacts.clear();
2914
2938
  activeBuilds.length = 0;
2915
2939
  if (reRegisterTimer) clearTimeout(reRegisterTimer);
2916
2940
  reRegisterTimer = null;
@@ -2923,11 +2947,62 @@ function sdkVersion() {
2923
2947
  return "@withgateway/sdk";
2924
2948
  }
2925
2949
  }
2950
+ function paasGitContext() {
2951
+ const env = process.env;
2952
+ if (env.VERCEL_GIT_COMMIT_SHA) {
2953
+ const isGithub = (env.VERCEL_GIT_PROVIDER ?? "github") === "github";
2954
+ return {
2955
+ provider: "vercel",
2956
+ sha: env.VERCEL_GIT_COMMIT_SHA,
2957
+ repo: isGithub && env.VERCEL_GIT_REPO_OWNER && env.VERCEL_GIT_REPO_SLUG ? `${env.VERCEL_GIT_REPO_OWNER}/${env.VERCEL_GIT_REPO_SLUG}` : void 0,
2958
+ branch: env.VERCEL_GIT_COMMIT_REF,
2959
+ login: env.VERCEL_GIT_COMMIT_AUTHOR_LOGIN
2960
+ };
2961
+ }
2962
+ if (env.RENDER_GIT_COMMIT) {
2963
+ return {
2964
+ provider: "render",
2965
+ sha: env.RENDER_GIT_COMMIT,
2966
+ repo: env.RENDER_GIT_REPO_SLUG,
2967
+ // already "owner/repo"
2968
+ branch: env.RENDER_GIT_BRANCH
2969
+ };
2970
+ }
2971
+ if (env.RAILWAY_GIT_COMMIT_SHA) {
2972
+ return {
2973
+ provider: "railway",
2974
+ sha: env.RAILWAY_GIT_COMMIT_SHA,
2975
+ repo: env.RAILWAY_GIT_REPO_OWNER && env.RAILWAY_GIT_REPO_NAME ? `${env.RAILWAY_GIT_REPO_OWNER}/${env.RAILWAY_GIT_REPO_NAME}` : void 0,
2976
+ branch: env.RAILWAY_GIT_BRANCH,
2977
+ login: env.RAILWAY_GIT_AUTHOR
2978
+ };
2979
+ }
2980
+ if (env.NETLIFY && env.COMMIT_REF) {
2981
+ const repoMatch = /github\.com[/:]([^/]+\/[^/.]+)/.exec(
2982
+ env.REPOSITORY_URL ?? ""
2983
+ );
2984
+ return {
2985
+ provider: "netlify",
2986
+ sha: env.COMMIT_REF,
2987
+ repo: repoMatch?.[1],
2988
+ branch: env.BRANCH
2989
+ };
2990
+ }
2991
+ const bareSha = env.HEROKU_SLUG_COMMIT ?? env.SOURCE_VERSION ?? env.GIT_COMMIT ?? env.COMMIT_SHA;
2992
+ if (bareSha) {
2993
+ return {
2994
+ provider: env.HEROKU_SLUG_COMMIT || env.SOURCE_VERSION ? "heroku" : "generic",
2995
+ sha: bareSha
2996
+ };
2997
+ }
2998
+ return null;
2999
+ }
2926
3000
  function codeRef() {
3001
+ const paas = paasGitContext();
2927
3002
  const sha = process.env.GATEWAY_COMMIT ?? process.env.GITHUB_SHA ?? process.env.CI_COMMIT_SHA ?? // GitLab
2928
- process.env.CIRCLE_SHA1;
3003
+ process.env.CIRCLE_SHA1 ?? paas?.sha;
2929
3004
  if (!sha) return void 0;
2930
- const repo = process.env.GITHUB_REPOSITORY ?? process.env.CI_PROJECT_PATH;
3005
+ const repo = process.env.GITHUB_REPOSITORY ?? process.env.CI_PROJECT_PATH ?? paas?.repo;
2931
3006
  return repo ? `git:${repo}@${sha}` : `git:${sha}`;
2932
3007
  }
2933
3008
  function assembleManifest(agentId) {
@@ -2937,13 +3012,17 @@ function assembleManifest(agentId) {
2937
3012
  sdk: sdkVersion(),
2938
3013
  tools: getRegisteredTools(),
2939
3014
  prompts: getRegisteredPrompts(),
2940
- skills: getRegisteredSkills()
3015
+ skills: getRegisteredSkills(),
3016
+ artifacts: getRegisteredArtifacts()
2941
3017
  };
2942
3018
  }
2943
3019
  function computeBuildHash(manifest) {
2944
3020
  const identity = {
2945
3021
  ...manifest,
2946
- tools: manifest.tools.map(({ source: _source, ...tool }) => tool)
3022
+ tools: manifest.tools.map(({ source: _source, ...tool }) => tool),
3023
+ artifacts: manifest.artifacts.map(
3024
+ ({ source: _source, ...artifact }) => artifact
3025
+ )
2947
3026
  };
2948
3027
  return sha256(canonicalJson(identity));
2949
3028
  }
@@ -2956,6 +3035,14 @@ function attributionFromEnv() {
2956
3035
  if (process.env.GITHUB_REPOSITORY) attribution.repo = process.env.GITHUB_REPOSITORY;
2957
3036
  const branch = process.env.GITHUB_HEAD_REF ?? process.env.GITHUB_REF_NAME;
2958
3037
  if (branch) attribution.branch = branch;
3038
+ const paas = paasGitContext();
3039
+ if (paas) {
3040
+ if (attribution.source === "runtime") attribution.source = `paas:${paas.provider}`;
3041
+ if (!attribution.commitSha && paas.sha) attribution.commitSha = paas.sha;
3042
+ if (!attribution.repo && paas.repo) attribution.repo = paas.repo;
3043
+ if (!attribution.branch && paas.branch) attribution.branch = paas.branch;
3044
+ if (!attribution.githubLogin && paas.login) attribution.githubLogin = paas.login;
3045
+ }
2959
3046
  const ref = process.env.GITHUB_REF ?? "";
2960
3047
  const prMatch = /refs\/pull\/(\d+)\//.exec(ref);
2961
3048
  if (prMatch) attribution.prNumber = Number(prMatch[1]);
@@ -3668,6 +3755,7 @@ var tracing = {
3668
3755
  experiments,
3669
3756
  gateway,
3670
3757
  getExperimentContext,
3758
+ getRegisteredArtifacts,
3671
3759
  getRegisteredPrompts,
3672
3760
  getRegisteredSkills,
3673
3761
  getRegisteredTools,
@@ -3675,6 +3763,7 @@ var tracing = {
3675
3763
  loadSession,
3676
3764
  memory,
3677
3765
  personas,
3766
+ registerArtifact,
3678
3767
  registerPrompt,
3679
3768
  registerSkill,
3680
3769
  renderAgentSystem,