@withgateway/sdk 0.1.10 → 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,12 +22,26 @@ 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;
28
40
  sdk: string;
29
41
  tools: ToolIdentity[];
30
42
  prompts: Record<string, string>;
43
+ skills: Record<string, string>;
44
+ artifacts: ArtifactIdentity[];
31
45
  }
32
46
  /** Deterministic JSON: object keys sorted recursively, arrays kept in order. */
33
47
  declare function canonicalJson(value: unknown): string;
@@ -60,8 +74,40 @@ declare function defineTool<T extends DefineToolInput>(tool: T): T;
60
74
  * `const SYSTEM = registerPrompt("system", "You are…")`. Returns the content
61
75
  * unchanged. Platform-served prompts don't need this — pin them by label.
62
76
  */
63
- 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;
64
99
  declare function getRegisteredTools(): ToolIdentity[];
100
+ /**
101
+ * Register a skill's identity — `registerSkill("triage", "1.0")` — so skills
102
+ * are versioned in the build like tools and prompts. The version string is
103
+ * whatever you bump (or a content hash for file-based skills).
104
+ */
105
+ declare function registerSkill(name: string, version: string, options?: {
106
+ content?: string;
107
+ ref?: string;
108
+ }): void;
109
+ declare function getRegisteredArtifacts(): ArtifactIdentity[];
110
+ declare function getRegisteredSkills(): Record<string, string>;
65
111
  declare function getRegisteredPrompts(): Record<string, string>;
66
112
  /** Test hook. */
67
113
  declare function resetBuildRegistry(): void;
@@ -78,4 +124,4 @@ declare function computeBuildHash(manifest: AgentBuildManifest): string;
78
124
  */
79
125
  declare const tracing: typeof _tracingModule;
80
126
 
81
- export { type AgentBuildManifest, type DefineToolInput, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredPrompts, getRegisteredTools, registerPrompt, 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,12 +22,26 @@ 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;
28
40
  sdk: string;
29
41
  tools: ToolIdentity[];
30
42
  prompts: Record<string, string>;
43
+ skills: Record<string, string>;
44
+ artifacts: ArtifactIdentity[];
31
45
  }
32
46
  /** Deterministic JSON: object keys sorted recursively, arrays kept in order. */
33
47
  declare function canonicalJson(value: unknown): string;
@@ -60,8 +74,40 @@ declare function defineTool<T extends DefineToolInput>(tool: T): T;
60
74
  * `const SYSTEM = registerPrompt("system", "You are…")`. Returns the content
61
75
  * unchanged. Platform-served prompts don't need this — pin them by label.
62
76
  */
63
- 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;
64
99
  declare function getRegisteredTools(): ToolIdentity[];
100
+ /**
101
+ * Register a skill's identity — `registerSkill("triage", "1.0")` — so skills
102
+ * are versioned in the build like tools and prompts. The version string is
103
+ * whatever you bump (or a content hash for file-based skills).
104
+ */
105
+ declare function registerSkill(name: string, version: string, options?: {
106
+ content?: string;
107
+ ref?: string;
108
+ }): void;
109
+ declare function getRegisteredArtifacts(): ArtifactIdentity[];
110
+ declare function getRegisteredSkills(): Record<string, string>;
65
111
  declare function getRegisteredPrompts(): Record<string, string>;
66
112
  /** Test hook. */
67
113
  declare function resetBuildRegistry(): void;
@@ -78,4 +124,4 @@ declare function computeBuildHash(manifest: AgentBuildManifest): string;
78
124
  */
79
125
  declare const tracing: typeof _tracingModule;
80
126
 
81
- export { type AgentBuildManifest, type DefineToolInput, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredPrompts, getRegisteredTools, registerPrompt, 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.10",
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,13 +216,17 @@ __export(src_exports, {
216
216
  experiments: () => singleton_exports,
217
217
  gateway: () => gateway,
218
218
  getExperimentContext: () => getExperimentContext,
219
+ getRegisteredArtifacts: () => getRegisteredArtifacts,
219
220
  getRegisteredPrompts: () => getRegisteredPrompts,
221
+ getRegisteredSkills: () => getRegisteredSkills,
220
222
  getRegisteredTools: () => getRegisteredTools,
221
223
  identify: () => identify,
222
224
  loadSession: () => loadSession,
223
225
  memory: () => memory,
224
226
  personas: () => personas,
227
+ registerArtifact: () => registerArtifact,
225
228
  registerPrompt: () => registerPrompt,
229
+ registerSkill: () => registerSkill,
226
230
  renderAgentSystem: () => renderAgentSystem,
227
231
  replay: () => replay,
228
232
  resetBuildRegistry: () => resetBuildRegistry,
@@ -2843,6 +2847,8 @@ function sha256(text) {
2843
2847
  }
2844
2848
  var registeredTools = /* @__PURE__ */ new Map();
2845
2849
  var registeredPrompts = /* @__PURE__ */ new Map();
2850
+ var registeredSkills = /* @__PURE__ */ new Map();
2851
+ var registeredArtifacts = /* @__PURE__ */ new Map();
2846
2852
  function captureSource() {
2847
2853
  const stack = new Error().stack?.split("\n") ?? [];
2848
2854
  for (const line of stack.slice(1)) {
@@ -2873,10 +2879,27 @@ function defineTool(tool) {
2873
2879
  ...source ? { source } : {}
2874
2880
  };
2875
2881
  registeredTools.set(tool.name, identity);
2882
+ notifyRegistryChanged();
2876
2883
  return tool;
2877
2884
  }
2878
- function registerPrompt(name, 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);
2897
+ notifyRegistryChanged();
2898
+ return identity;
2899
+ }
2900
+ function registerPrompt(name, content, options = {}) {
2879
2901
  registeredPrompts.set(name, sha256(content));
2902
+ registerArtifact("prompt", name, { ...options, content });
2880
2903
  return content;
2881
2904
  }
2882
2905
  function getRegisteredTools() {
@@ -2884,6 +2907,22 @@ function getRegisteredTools() {
2884
2907
  (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
2885
2908
  );
2886
2909
  }
2910
+ function registerSkill(name, version, options = {}) {
2911
+ registeredSkills.set(name, version);
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
+ );
2918
+ }
2919
+ function getRegisteredSkills() {
2920
+ return Object.fromEntries(
2921
+ [...registeredSkills.entries()].sort(
2922
+ ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
2923
+ )
2924
+ );
2925
+ }
2887
2926
  function getRegisteredPrompts() {
2888
2927
  return Object.fromEntries(
2889
2928
  [...registeredPrompts.entries()].sort(
@@ -2894,6 +2933,11 @@ function getRegisteredPrompts() {
2894
2933
  function resetBuildRegistry() {
2895
2934
  registeredTools.clear();
2896
2935
  registeredPrompts.clear();
2936
+ registeredSkills.clear();
2937
+ registeredArtifacts.clear();
2938
+ activeBuilds.length = 0;
2939
+ if (reRegisterTimer) clearTimeout(reRegisterTimer);
2940
+ reRegisterTimer = null;
2897
2941
  }
2898
2942
  function sdkVersion() {
2899
2943
  try {
@@ -2903,11 +2947,62 @@ function sdkVersion() {
2903
2947
  return "@withgateway/sdk";
2904
2948
  }
2905
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
+ }
2906
3000
  function codeRef() {
3001
+ const paas = paasGitContext();
2907
3002
  const sha = process.env.GATEWAY_COMMIT ?? process.env.GITHUB_SHA ?? process.env.CI_COMMIT_SHA ?? // GitLab
2908
- process.env.CIRCLE_SHA1;
3003
+ process.env.CIRCLE_SHA1 ?? paas?.sha;
2909
3004
  if (!sha) return void 0;
2910
- 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;
2911
3006
  return repo ? `git:${repo}@${sha}` : `git:${sha}`;
2912
3007
  }
2913
3008
  function assembleManifest(agentId) {
@@ -2916,13 +3011,18 @@ function assembleManifest(agentId) {
2916
3011
  ...codeRef() ? { codeRef: codeRef() } : {},
2917
3012
  sdk: sdkVersion(),
2918
3013
  tools: getRegisteredTools(),
2919
- prompts: getRegisteredPrompts()
3014
+ prompts: getRegisteredPrompts(),
3015
+ skills: getRegisteredSkills(),
3016
+ artifacts: getRegisteredArtifacts()
2920
3017
  };
2921
3018
  }
2922
3019
  function computeBuildHash(manifest) {
2923
3020
  const identity = {
2924
3021
  ...manifest,
2925
- 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
+ )
2926
3026
  };
2927
3027
  return sha256(canonicalJson(identity));
2928
3028
  }
@@ -2935,6 +3035,14 @@ function attributionFromEnv() {
2935
3035
  if (process.env.GITHUB_REPOSITORY) attribution.repo = process.env.GITHUB_REPOSITORY;
2936
3036
  const branch = process.env.GITHUB_HEAD_REF ?? process.env.GITHUB_REF_NAME;
2937
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
+ }
2938
3046
  const ref = process.env.GITHUB_REF ?? "";
2939
3047
  const prMatch = /refs\/pull\/(\d+)\//.exec(ref);
2940
3048
  if (prMatch) attribution.prNumber = Number(prMatch[1]);
@@ -2949,6 +3057,31 @@ function attributionFromEnv() {
2949
3057
  }
2950
3058
  return attribution;
2951
3059
  }
3060
+ var activeBuilds = [];
3061
+ var reRegisterTimer = null;
3062
+ var RE_REGISTER_DEBOUNCE_MS = 3e3;
3063
+ function trackActiveBuild(context4) {
3064
+ activeBuilds.push(context4);
3065
+ }
3066
+ function notifyRegistryChanged() {
3067
+ if (activeBuilds.length === 0) return;
3068
+ if (reRegisterTimer) clearTimeout(reRegisterTimer);
3069
+ reRegisterTimer = setTimeout(() => {
3070
+ reRegisterTimer = null;
3071
+ for (const context4 of activeBuilds) {
3072
+ const manifest = assembleManifest(context4.agentId);
3073
+ const buildHash = computeBuildHash(manifest);
3074
+ if (buildHash === context4.lastRegisteredHash) continue;
3075
+ context4.lastRegisteredHash = buildHash;
3076
+ void registerBuild({ ...context4, manifest, buildHash }).catch(() => {
3077
+ context4.lastRegisteredHash = void 0;
3078
+ });
3079
+ }
3080
+ }, RE_REGISTER_DEBOUNCE_MS);
3081
+ if (typeof reRegisterTimer === "object" && "unref" in reRegisterTimer) {
3082
+ reRegisterTimer.unref();
3083
+ }
3084
+ }
2952
3085
  async function registerBuild(params) {
2953
3086
  const auth = Buffer.from(`${params.publicKey}:${params.secretKey}`).toString(
2954
3087
  "base64"
@@ -3229,6 +3362,14 @@ function scheduleBuildRegistration(config, built) {
3229
3362
  return;
3230
3363
  }
3231
3364
  const { manifest, buildHash } = built.buildInfo;
3365
+ trackActiveBuild({
3366
+ host: built.connection.host,
3367
+ publicKey: built.connection.publicKey,
3368
+ secretKey: built.connection.secretKey,
3369
+ agentId: config.agent,
3370
+ version: config.version,
3371
+ lastRegisteredHash: buildHash
3372
+ });
3232
3373
  void registerBuild({
3233
3374
  host: built.connection.host,
3234
3375
  publicKey: built.connection.publicKey,
@@ -3614,13 +3755,17 @@ var tracing = {
3614
3755
  experiments,
3615
3756
  gateway,
3616
3757
  getExperimentContext,
3758
+ getRegisteredArtifacts,
3617
3759
  getRegisteredPrompts,
3760
+ getRegisteredSkills,
3618
3761
  getRegisteredTools,
3619
3762
  identify,
3620
3763
  loadSession,
3621
3764
  memory,
3622
3765
  personas,
3766
+ registerArtifact,
3623
3767
  registerPrompt,
3768
+ registerSkill,
3624
3769
  renderAgentSystem,
3625
3770
  replay,
3626
3771
  resetBuildRegistry,