@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.
package/README.md CHANGED
@@ -152,6 +152,43 @@ experiments.clearExperimentContext() // Clear context (call after each request)
152
152
  experiments.shutdown() // Cleanup (call on exit)
153
153
  ```
154
154
 
155
+ ### Scores & Success Signals
156
+
157
+ Record evaluation scores and ROI-shaped **success signals** against a project.
158
+ A success signal is a score tagged with `gateway.success.signal`, which the
159
+ platform's **Success Metrics** feature aggregates into a metric's headline
160
+ count / pass-rate (the `HOOK` metric source). The score shape is identical to
161
+ the Python SDK's `run.success()`, so signals from either SDK aggregate the same.
162
+
163
+ ```typescript
164
+ import { ScoresClient, success } from "@withgateway/sdk/scores";
165
+
166
+ // Env-based (GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY):
167
+ await success("resolved_ticket", true, { agentId: "support-triage", sessionId });
168
+ await success("handle_time_s", 42, { agentId: "support-triage", sessionId });
169
+
170
+ // Explicit keys:
171
+ const scores = new ScoresClient({ host, publicKey, secretKey });
172
+ await scores.success("resolved_ticket", true, { agentId: "support-triage", sessionId });
173
+ await scores.score("rubric", 0.9, { sessionId }); // a plain (non-signal) score
174
+ ```
175
+
176
+ A boolean `value` is recorded as a 1/0 **BOOLEAN** score (pass/fail); a number
177
+ is a **NUMERIC** score. `metricName` defaults to the signal `name`. Provide
178
+ exactly one target — `sessionId`, `traceId` (+ optional `observationId`), or
179
+ `datasetRunId`; when none is given the active OpenTelemetry trace id is used,
180
+ and if there is none the call is a fail-soft no-op. Every `score`/`success`
181
+ call is **fail-soft**: a bad key or transport failure warns and resolves, never
182
+ throwing into your run. (`postScore` is the raw variant that DOES throw.)
183
+
184
+ Under `tracing.initIsolated(...)`, the returned handle carries a `scores`
185
+ client bound to that provider's project keys:
186
+
187
+ ```typescript
188
+ const handle = tracing.initIsolated({ host, publicKey, secretKey, agent: "support-agent" });
189
+ await handle.scores.success("resolved_ticket", true, { agentId: "support-agent", sessionId });
190
+ ```
191
+
155
192
  ### Security Wrapper
156
193
 
157
194
  Use the security wrapper when you want Gateway to control tool visibility,
@@ -1,4 +1,5 @@
1
1
  import { Context, Tracer } from '@opentelemetry/api';
2
+ import { ScoresClient } from './scores/index.mjs';
2
3
  import { SpanProcessor, Span, ReadableSpan } from '@opentelemetry/sdk-trace-base';
3
4
 
4
5
  /**
@@ -186,6 +187,14 @@ interface TracingState {
186
187
  */
187
188
  interface TracingHandle {
188
189
  tracer: Tracer;
190
+ /**
191
+ * Scores/success-signal client bound to THIS provider's project keys. Emit
192
+ * ROI success signals into the same project the handle's spans export to —
193
+ * `handle.scores.success("resolved_ticket", true, { agentId, sessionId })` —
194
+ * without threading credentials through your own code. Fail-soft, like the
195
+ * rest of the client.
196
+ */
197
+ scores: ScoresClient;
189
198
  /** Force-flush pending spans for this provider only. */
190
199
  flush(): Promise<void>;
191
200
  /** Flush and shut down this provider only. */
@@ -1,4 +1,5 @@
1
1
  import { Context, Tracer } from '@opentelemetry/api';
2
+ import { ScoresClient } from './scores/index.js';
2
3
  import { SpanProcessor, Span, ReadableSpan } from '@opentelemetry/sdk-trace-base';
3
4
 
4
5
  /**
@@ -186,6 +187,14 @@ interface TracingState {
186
187
  */
187
188
  interface TracingHandle {
188
189
  tracer: Tracer;
190
+ /**
191
+ * Scores/success-signal client bound to THIS provider's project keys. Emit
192
+ * ROI success signals into the same project the handle's spans export to —
193
+ * `handle.scores.success("resolved_ticket", true, { agentId, sessionId })` —
194
+ * without threading credentials through your own code. Fail-soft, like the
195
+ * rest of the client.
196
+ */
197
+ scores: ScoresClient;
189
198
  /** Force-flush pending spans for this provider only. */
190
199
  flush(): Promise<void>;
191
200
  /** Flush and shut down this provider only. */
package/dist/index.d.mts CHANGED
@@ -6,8 +6,9 @@ export { DriftError, LocalTool, MissPolicy, REPLAY_ENVIRONMENT, RecordedToolCall
6
6
  export { GatewayAgentDescriptor, GatewaySecurity, GatewaySecurityConfig, GatewaySecurityContext, GatewaySecurityError, GatewayToolApprovalRequiredError, GatewayToolBlockedError, GatewayToolCallAuthorizeResponse, GatewayToolDescriptor, GatewayToolsetResolveResponse, SecureToolsOptions, gateway } from './security/index.mjs';
7
7
  export { DEFAULT_TIMEOUT_SECONDS, ENV_GATEWAY_HOST, ENV_GATEWAY_PUBLIC_KEY, ENV_GATEWAY_SECRET_KEY, LoadSessionOptions, SessionLoadError, SessionObservation, SessionRecording, SessionTrace, basicAuthHeader, loadSession, sessionObservationFromApi, sessions } from './sessions/index.mjs';
8
8
  export { UserEvent, UserEventOptions, UserProfile, UserProfileError, UserProfileUpdate, UsersClient, UsersClientConfig, UsersClientFromEnvConfig, users } from './users/index.mjs';
9
- import { _ as _tracingModule } from './index-CTc8iOrx.mjs';
10
- export { I as IdentifyOptions, i as identify, r as resolveUserId } from './index-CTc8iOrx.mjs';
9
+ export { AGENT_ID_KEY, SUCCESS_METRIC_NAME_KEY, SUCCESS_SIGNAL_KEY, ScoreDataType, ScoreError, ScoreOptions, ScoresClient, ScoresClientConfig, ScoresClientFromEnvConfig, SuccessOptions, currentTraceId, scores, success } from './scores/index.mjs';
10
+ import { _ as _tracingModule } from './index-B5HUQQDE.mjs';
11
+ export { I as IdentifyOptions, i as identify, r as resolveUserId } from './index-B5HUQQDE.mjs';
11
12
  import 'async_hooks';
12
13
  import '@opentelemetry/api';
13
14
  import '@opentelemetry/sdk-trace-base';
@@ -22,6 +23,18 @@ interface ToolIdentity {
22
23
  /** Source location of the defineTool call ("src/tools/checkout.ts:42"). */
23
24
  source?: string;
24
25
  }
26
+ /** Any versioned artifact an agent is built from — tools, prompts, skills,
27
+ * datasets, guardrails, configs… `content` hashes locally (off-platform);
28
+ * `ref` pins a platform-hosted artifact ("prompt/system@label:production"). */
29
+ interface ArtifactIdentity {
30
+ kind: string;
31
+ name: string;
32
+ version?: string;
33
+ contentHash?: string;
34
+ ref?: string;
35
+ source?: string;
36
+ metadata?: Record<string, string>;
37
+ }
25
38
  interface AgentBuildManifest {
26
39
  agentId: string;
27
40
  codeRef?: string;
@@ -29,6 +42,7 @@ interface AgentBuildManifest {
29
42
  tools: ToolIdentity[];
30
43
  prompts: Record<string, string>;
31
44
  skills: Record<string, string>;
45
+ artifacts: ArtifactIdentity[];
32
46
  }
33
47
  /** Deterministic JSON: object keys sorted recursively, arrays kept in order. */
34
48
  declare function canonicalJson(value: unknown): string;
@@ -61,14 +75,39 @@ declare function defineTool<T extends DefineToolInput>(tool: T): T;
61
75
  * `const SYSTEM = registerPrompt("system", "You are…")`. Returns the content
62
76
  * unchanged. Platform-served prompts don't need this — pin them by label.
63
77
  */
64
- declare function registerPrompt(name: string, content: string): string;
78
+ interface RegisterArtifactOptions {
79
+ /** Developer-declared version, e.g. "1.2" (v1: bumped manually). */
80
+ version?: string;
81
+ /** Local content — hashed into the identity (off-platform artifacts). */
82
+ content?: string;
83
+ /** Platform reference (on-platform artifacts): "prompt/system@label:production". */
84
+ ref?: string;
85
+ metadata?: Record<string, string>;
86
+ }
87
+ /**
88
+ * Version ANY artifact the agent is built from — the generic primitive
89
+ * behind registerPrompt/registerSkill. Works on- and off-platform:
90
+ *
91
+ * ```ts
92
+ * registerArtifact("guardrail", "pii-filter", { version: "2.0", content: RULES });
93
+ * registerArtifact("prompt", "planner", { ref: "planner@label:production" });
94
+ * ```
95
+ */
96
+ declare function registerArtifact(kind: string, name: string, options?: RegisterArtifactOptions): ArtifactIdentity;
97
+ declare function registerPrompt(name: string, content: string, options?: {
98
+ version?: string;
99
+ }): string;
65
100
  declare function getRegisteredTools(): ToolIdentity[];
66
101
  /**
67
102
  * Register a skill's identity — `registerSkill("triage", "1.0")` — so skills
68
103
  * are versioned in the build like tools and prompts. The version string is
69
104
  * whatever you bump (or a content hash for file-based skills).
70
105
  */
71
- declare function registerSkill(name: string, version: string): void;
106
+ declare function registerSkill(name: string, version: string, options?: {
107
+ content?: string;
108
+ ref?: string;
109
+ }): void;
110
+ declare function getRegisteredArtifacts(): ArtifactIdentity[];
72
111
  declare function getRegisteredSkills(): Record<string, string>;
73
112
  declare function getRegisteredPrompts(): Record<string, string>;
74
113
  /** Test hook. */
@@ -86,4 +125,4 @@ declare function computeBuildHash(manifest: AgentBuildManifest): string;
86
125
  */
87
126
  declare const tracing: typeof _tracingModule;
88
127
 
89
- export { type AgentBuildManifest, type DefineToolInput, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredPrompts, getRegisteredSkills, getRegisteredTools, registerPrompt, registerSkill, resetBuildRegistry, tracing };
128
+ 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
@@ -6,8 +6,9 @@ export { DriftError, LocalTool, MissPolicy, REPLAY_ENVIRONMENT, RecordedToolCall
6
6
  export { GatewayAgentDescriptor, GatewaySecurity, GatewaySecurityConfig, GatewaySecurityContext, GatewaySecurityError, GatewayToolApprovalRequiredError, GatewayToolBlockedError, GatewayToolCallAuthorizeResponse, GatewayToolDescriptor, GatewayToolsetResolveResponse, SecureToolsOptions, gateway } from './security/index.js';
7
7
  export { DEFAULT_TIMEOUT_SECONDS, ENV_GATEWAY_HOST, ENV_GATEWAY_PUBLIC_KEY, ENV_GATEWAY_SECRET_KEY, LoadSessionOptions, SessionLoadError, SessionObservation, SessionRecording, SessionTrace, basicAuthHeader, loadSession, sessionObservationFromApi, sessions } from './sessions/index.js';
8
8
  export { UserEvent, UserEventOptions, UserProfile, UserProfileError, UserProfileUpdate, UsersClient, UsersClientConfig, UsersClientFromEnvConfig, users } from './users/index.js';
9
- import { _ as _tracingModule } from './index-CTc8iOrx.js';
10
- export { I as IdentifyOptions, i as identify, r as resolveUserId } from './index-CTc8iOrx.js';
9
+ export { AGENT_ID_KEY, SUCCESS_METRIC_NAME_KEY, SUCCESS_SIGNAL_KEY, ScoreDataType, ScoreError, ScoreOptions, ScoresClient, ScoresClientConfig, ScoresClientFromEnvConfig, SuccessOptions, currentTraceId, scores, success } from './scores/index.js';
10
+ import { _ as _tracingModule } from './index-Dpo-t8iO.js';
11
+ export { I as IdentifyOptions, i as identify, r as resolveUserId } from './index-Dpo-t8iO.js';
11
12
  import 'async_hooks';
12
13
  import '@opentelemetry/api';
13
14
  import '@opentelemetry/sdk-trace-base';
@@ -22,6 +23,18 @@ interface ToolIdentity {
22
23
  /** Source location of the defineTool call ("src/tools/checkout.ts:42"). */
23
24
  source?: string;
24
25
  }
26
+ /** Any versioned artifact an agent is built from — tools, prompts, skills,
27
+ * datasets, guardrails, configs… `content` hashes locally (off-platform);
28
+ * `ref` pins a platform-hosted artifact ("prompt/system@label:production"). */
29
+ interface ArtifactIdentity {
30
+ kind: string;
31
+ name: string;
32
+ version?: string;
33
+ contentHash?: string;
34
+ ref?: string;
35
+ source?: string;
36
+ metadata?: Record<string, string>;
37
+ }
25
38
  interface AgentBuildManifest {
26
39
  agentId: string;
27
40
  codeRef?: string;
@@ -29,6 +42,7 @@ interface AgentBuildManifest {
29
42
  tools: ToolIdentity[];
30
43
  prompts: Record<string, string>;
31
44
  skills: Record<string, string>;
45
+ artifacts: ArtifactIdentity[];
32
46
  }
33
47
  /** Deterministic JSON: object keys sorted recursively, arrays kept in order. */
34
48
  declare function canonicalJson(value: unknown): string;
@@ -61,14 +75,39 @@ declare function defineTool<T extends DefineToolInput>(tool: T): T;
61
75
  * `const SYSTEM = registerPrompt("system", "You are…")`. Returns the content
62
76
  * unchanged. Platform-served prompts don't need this — pin them by label.
63
77
  */
64
- declare function registerPrompt(name: string, content: string): string;
78
+ interface RegisterArtifactOptions {
79
+ /** Developer-declared version, e.g. "1.2" (v1: bumped manually). */
80
+ version?: string;
81
+ /** Local content — hashed into the identity (off-platform artifacts). */
82
+ content?: string;
83
+ /** Platform reference (on-platform artifacts): "prompt/system@label:production". */
84
+ ref?: string;
85
+ metadata?: Record<string, string>;
86
+ }
87
+ /**
88
+ * Version ANY artifact the agent is built from — the generic primitive
89
+ * behind registerPrompt/registerSkill. Works on- and off-platform:
90
+ *
91
+ * ```ts
92
+ * registerArtifact("guardrail", "pii-filter", { version: "2.0", content: RULES });
93
+ * registerArtifact("prompt", "planner", { ref: "planner@label:production" });
94
+ * ```
95
+ */
96
+ declare function registerArtifact(kind: string, name: string, options?: RegisterArtifactOptions): ArtifactIdentity;
97
+ declare function registerPrompt(name: string, content: string, options?: {
98
+ version?: string;
99
+ }): string;
65
100
  declare function getRegisteredTools(): ToolIdentity[];
66
101
  /**
67
102
  * Register a skill's identity — `registerSkill("triage", "1.0")` — so skills
68
103
  * are versioned in the build like tools and prompts. The version string is
69
104
  * whatever you bump (or a content hash for file-based skills).
70
105
  */
71
- declare function registerSkill(name: string, version: string): void;
106
+ declare function registerSkill(name: string, version: string, options?: {
107
+ content?: string;
108
+ ref?: string;
109
+ }): void;
110
+ declare function getRegisteredArtifacts(): ArtifactIdentity[];
72
111
  declare function getRegisteredSkills(): Record<string, string>;
73
112
  declare function getRegisteredPrompts(): Record<string, string>;
74
113
  /** Test hook. */
@@ -86,4 +125,4 @@ declare function computeBuildHash(manifest: AgentBuildManifest): string;
86
125
  */
87
126
  declare const tracing: typeof _tracingModule;
88
127
 
89
- export { type AgentBuildManifest, type DefineToolInput, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredPrompts, getRegisteredSkills, getRegisteredTools, registerPrompt, registerSkill, resetBuildRegistry, tracing };
128
+ 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 };