@providerkit/core 0.31.0 → 0.32.0

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
@@ -164,6 +164,74 @@ settings, such as a domain filter, refuses unless you mark that tool `optional`.
164
164
  The [tools guide](https://providerkit.dev/guides/tools/#hosted-tools) says which adapter runs
165
165
  what, and how each call is billed.
166
166
 
167
+ ### Chat tracing
168
+
169
+ ```ts
170
+ import { withProviderTracing } from "@providerkit/core/otel";
171
+
172
+ const traced = withProviderTracing(provider);
173
+ ```
174
+
175
+ Use `traced.createStream` just like `provider.createStream`. Install the optional
176
+ `@opentelemetry/api` peer (`^1.10.0`) to use this entry. Normal imports load no tracing code and
177
+ need no telemetry dependency. Your app supplies the tracing setup; with only the API installed,
178
+ calls still work but no spans are exported. Core installs no exporter or context manager.
179
+
180
+ Wrap the **final provider**, after the registry, fallback, key/token recovery, gate and watchdog
181
+ layers. One CLIENT span named `chat {model}` covers one consumed stream, not each hidden attempt.
182
+ It starts on the first read and ends when the iterator ends, fails or the caller's signal aborts.
183
+ A finish chunk does not end it because usage can follow. Duration includes queueing, authentication,
184
+ recovery and pauses between reads. Tracing adds no pulls, retries, timeout or abort controller.
185
+
186
+ Options are `tracer` (default: `trace.getTracer("@providerkit/core")`), `parentContext` and
187
+ `providerName` (a label, not a routing change). Without `parentContext`, the active context is
188
+ saved separately for each `createStream` call. Set it explicitly to attach a call to a saved
189
+ parent without a context manager. HTTP child spans still need your app's context manager.
190
+ Re-wrapping a wrapper made by this adapter replaces its tracing options rather than adding a
191
+ second provider span. It cannot find a traced provider hidden inside an unrelated decorator;
192
+ do not trace both individual candidates and their completed chain.
193
+
194
+ Recorded fields follow the OpenTelemetry GenAI **Development** conventions at
195
+ [revision e6658f1](https://github.com/open-telemetry/semantic-conventions-genai/tree/e6658f14c9d9ea0760825f029cb82e7673f48fab):
196
+
197
+ | Observation | Span attribute |
198
+ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
199
+ | Chat operation, requested provider/model, streaming | `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.request.stream` |
200
+ | Input and output tokens | `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens` |
201
+ | Cache reads and writes, already included in input | `gen_ai.usage.cache_read.input_tokens`, `gen_ai.usage.cache_write.input_tokens` |
202
+ | Reasoning tokens, already included in output | `gen_ai.usage.reasoning.output_tokens` |
203
+ | Reported cost, including zero | `providerkit.usage.reported_cost_usd` |
204
+ | Finish reason | `gen_ai.response.finish_reasons` |
205
+ | Selected source from `chunk.source` | `providerkit.response.provider`, `providerkit.response.model` |
206
+ | Time until this wrapper sees a chunk or activity | `providerkit.stream.first_chunk_seconds`, `providerkit.stream.first_activity_seconds` |
207
+ | Iterator outcome | `providerkit.stream.outcome`: `completed`, `closed`, `cancelled` or `error` |
208
+
209
+ The last normalized usage record wins; cumulative records are not added. No record means unknown,
210
+ not zero. Only finite, nonnegative counts are kept. These are observations, not audited bills:
211
+ some adapters fill missing vendor counts with zero, and errors, early closure or cancellation can
212
+ leave partial usage. Hidden failed attempts are not included. Selected model IDs can be configured
213
+ aliases, so they are not labelled `gen_ai.response.model`. Direct Gemini is labelled `gcp.gemini`;
214
+ gateways keep their own identity. The timing fields measure this wrapper, not standard TTFT or
215
+ server inference time.
216
+
217
+ Failures record core's low-cardinality `error.type` and an ERROR status, never the error's message,
218
+ body, stack, cause or vendor code. Successful and cancelled calls leave status UNSET. Selected
219
+ numeric hints use `http.response.status_code` and `providerkit.rate_limit.utilization`,
220
+ `reset_at_ms` and `retry_after_ms`; `providerkit.rate_limit.window` accepts only `5h`, `weekly`
221
+ or `monthly`. Existing activity and rate-limit callbacks still run. Broken instrumentation does
222
+ not replace provider results or errors and cannot replay a call.
223
+
224
+ No prompts, replies, reasoning, tool arguments/results, hosted payloads, credentials, session IDs,
225
+ headers, URLs or app context are captured. Provider and model labels are recorded, so keep private
226
+ data out of those labels. Aborting closes observation, not proof that the vendor stopped billing.
227
+ A stream abandoned without `return` or abort has no observable end. An inner watchdog timeout
228
+ may stay invisible until the next read; tracing does not read ahead to discover it.
229
+
230
+ This covers **chat only**, including hosted tools as part of the provider call. It does not create
231
+ agent tool spans or instrument speech, transcription, decisions, standalone auth, transport or
232
+ other helpers. Agent run parenting and dispatch binding are not included; combining this with
233
+ agent lifecycle tracing does not automatically attach provider spans to agent runs.
234
+
167
235
  ### Speech
168
236
 
169
237
  Text to one audio file, from its own entry point, so a chat-only app loads none of the speech code:
package/dist/otel.d.ts ADDED
@@ -0,0 +1,26 @@
1
+ import { type Context, type Tracer } from "@opentelemetry/api";
2
+ import type { Provider } from "./types.ts";
3
+ export interface ProviderTracingOptions {
4
+ /** Defaults to the host's tracer named `@providerkit/core`. No SDK is installed here. */
5
+ tracer?: Tracer;
6
+ /** Otherwise captured from the active context at each createStream call, not at setup. */
7
+ parentContext?: Context;
8
+ /** Telemetry label only. Does not change routing. Keep credentials and user data out of it. */
9
+ providerName?: string;
10
+ }
11
+ /**
12
+ * Observe chat calls without capturing their content.
13
+ *
14
+ * ```ts
15
+ * const traced = withProviderTracing(provider);
16
+ * ```
17
+ *
18
+ * Wrap the final provider, outside registry, fallback, gate and watchdog layers.
19
+ * Each consumed stream gets one CLIENT span, including queueing and consumption pauses.
20
+ * No attempts are counted and no retry, read-ahead or cancellation is added.
21
+ * Speech, transcription, decisions, standalone auth and agent runs are not covered.
22
+ * Re-wrapping an owned wrapper replaces its tracing options; hidden inner wrappers
23
+ * cannot be deduplicated. HTTP child spans require the host's context manager.
24
+ */
25
+ export declare function withProviderTracing(provider: Provider, options?: ProviderTracingOptions): Provider;
26
+ //# sourceMappingURL=otel.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"AAGA,OAAO,EAOL,KAAK,OAAO,EAEZ,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,QAAQ,EAA4C,MAAM,YAAY,CAAC;AAErF,MAAM,WAAW,sBAAsB;IACrC,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+FAA+F;IAC/F,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,sBAA2B,GACnC,QAAQ,CA+KV"}
package/dist/otel.js ADDED
@@ -0,0 +1,263 @@
1
+ // Opt-in only: the main entry and its declarations must never import this module.
2
+ // GenAI field names follow the Development conventions at
3
+ // https://github.com/open-telemetry/semantic-conventions-genai/tree/e6658f14c9d9ea0760825f029cb82e7673f48fab
4
+ import { context, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
5
+ import { classify, ProviderError } from "./errors.js";
6
+ // Own wrappers only. An SDK can bind a fresh parent without nesting another CLIENT span.
7
+ const owned = new WeakMap();
8
+ /**
9
+ * Observe chat calls without capturing their content.
10
+ *
11
+ * ```ts
12
+ * const traced = withProviderTracing(provider);
13
+ * ```
14
+ *
15
+ * Wrap the final provider, outside registry, fallback, gate and watchdog layers.
16
+ * Each consumed stream gets one CLIENT span, including queueing and consumption pauses.
17
+ * No attempts are counted and no retry, read-ahead or cancellation is added.
18
+ * Speech, transcription, decisions, standalone auth and agent runs are not covered.
19
+ * Re-wrapping an owned wrapper replaces its tracing options; hidden inner wrappers
20
+ * cannot be deduplicated. HTTP child spans require the host's context manager.
21
+ */
22
+ export function withProviderTracing(provider, options = {}) {
23
+ const inner = owned.get(provider) ?? provider;
24
+ const wrapped = {
25
+ get id() {
26
+ return inner.id;
27
+ },
28
+ get model() {
29
+ return inner.model;
30
+ },
31
+ createStream(messages, tools, opts = {}) {
32
+ const parent = options.parentContext ?? quietly(() => context.active()) ?? ROOT_CONTEXT;
33
+ let span;
34
+ let scope;
35
+ let started = false;
36
+ let ended = false;
37
+ let startTime = 0;
38
+ let firstChunk = false;
39
+ let firstActivity = false;
40
+ let usage = {};
41
+ let rate = {};
42
+ function end(outcome, error) {
43
+ if (ended)
44
+ return;
45
+ ended = true;
46
+ quietly(() => opts.signal?.removeEventListener("abort", cancelled));
47
+ quietly(() => span?.setAttributes(usage));
48
+ quietly(() => span?.setAttributes(rate));
49
+ quietly(() => span?.setAttribute("providerkit.stream.outcome", outcome));
50
+ if (outcome === "error") {
51
+ const kind = quietly(() => classify(error));
52
+ quietly(() => span?.setAttribute("error.type", kind && Object.hasOwn(ERROR_KINDS, kind) ? kind : "unknown"));
53
+ quietly(() => {
54
+ if (!(error instanceof ProviderError))
55
+ return;
56
+ span?.setAttributes(rateAttributes(error));
57
+ if (Number.isInteger(error.status) && error.status >= 100 && error.status <= 599) {
58
+ span?.setAttribute("http.response.status_code", error.status);
59
+ }
60
+ });
61
+ // Never recordException: messages, bodies and stacks can contain the prompt or key.
62
+ quietly(() => span?.setStatus({ code: SpanStatusCode.ERROR }));
63
+ }
64
+ quietly(() => span?.end());
65
+ }
66
+ function cancelled() {
67
+ end("cancelled");
68
+ }
69
+ function start() {
70
+ if (started || ended)
71
+ return;
72
+ started = true;
73
+ startTime = quietly(() => performance.now()) ?? 0;
74
+ const model = quietly(() => opts.model ?? inner.model);
75
+ const providerName = quietly(() => options.providerName ?? canonicalProvider(inner.id));
76
+ span = quietly(() => (options.tracer ?? trace.getTracer("@providerkit/core")).startSpan(model ? `chat ${model}` : "chat", {
77
+ kind: SpanKind.CLIENT,
78
+ attributes: {
79
+ "gen_ai.operation.name": "chat",
80
+ "gen_ai.provider.name": providerName,
81
+ "gen_ai.request.model": model,
82
+ "gen_ai.request.stream": true,
83
+ },
84
+ }, parent));
85
+ scope = quietly(() => (span ? trace.setSpan(parent, span) : parent));
86
+ quietly(() => {
87
+ opts.signal?.addEventListener("abort", cancelled, { once: true });
88
+ if (opts.signal?.aborted)
89
+ cancelled();
90
+ });
91
+ }
92
+ const streamOptions = {
93
+ ...opts,
94
+ onActivity() {
95
+ quietly(() => {
96
+ if (ended || !started || firstActivity)
97
+ return;
98
+ firstActivity = true;
99
+ span?.setAttribute("providerkit.stream.first_activity_seconds", (performance.now() - startTime) / 1000);
100
+ });
101
+ // Only instrumentation is guarded. A caller's exception keeps its normal behavior.
102
+ opts.onActivity?.();
103
+ },
104
+ onRateLimit(reading) {
105
+ quietly(() => {
106
+ if (!ended)
107
+ rate = rateAttributes(reading);
108
+ });
109
+ opts.onRateLimit?.(reading);
110
+ },
111
+ };
112
+ const iterator = once(() => inner.createStream(messages, tools, streamOptions)[Symbol.asyncIterator]());
113
+ async function advance(method, args) {
114
+ if (method === "next")
115
+ start();
116
+ try {
117
+ const result = await inScope(scope, async () => {
118
+ const source = iterator();
119
+ const operation = source[method];
120
+ if (operation)
121
+ return operation.apply(source, args);
122
+ if (method === "throw") {
123
+ // Match yield* when throw is absent: close first, even if return yields again.
124
+ // A cleanup failure must escape instead of the missing-method TypeError.
125
+ await source.return?.();
126
+ throw new TypeError("The iterator does not provide a 'throw' method.");
127
+ }
128
+ return { done: true, value: args[0] };
129
+ });
130
+ quietly(() => {
131
+ if (ended)
132
+ return;
133
+ if (result.done) {
134
+ end(method === "next" ? "completed" : "closed");
135
+ return;
136
+ }
137
+ const chunk = result.value;
138
+ if (!firstChunk) {
139
+ firstChunk = true;
140
+ span?.setAttribute("providerkit.stream.first_chunk_seconds", (performance.now() - startTime) / 1000);
141
+ }
142
+ if (chunk.usage)
143
+ usage = usageAttributes(chunk.usage);
144
+ if (chunk.source) {
145
+ span?.setAttribute("providerkit.response.provider", chunk.source.provider);
146
+ span?.setAttribute("providerkit.response.model", chunk.source.model);
147
+ }
148
+ if (chunk.finishReason && FINISH_REASONS.has(chunk.finishReason)) {
149
+ span?.setAttribute("gen_ai.response.finish_reasons", [chunk.finishReason]);
150
+ }
151
+ });
152
+ return result;
153
+ }
154
+ catch (error) {
155
+ end(opts.signal?.aborted || quietly(() => classify(error)) === "aborted"
156
+ ? "cancelled"
157
+ : "error", error);
158
+ throw error;
159
+ }
160
+ }
161
+ const stream = {
162
+ [Symbol.asyncIterator]() {
163
+ return this;
164
+ },
165
+ next(...args) {
166
+ return advance("next", args);
167
+ },
168
+ return(...args) {
169
+ return advance("return", args);
170
+ },
171
+ throw(...args) {
172
+ return advance("throw", args);
173
+ },
174
+ };
175
+ return stream;
176
+ },
177
+ };
178
+ owned.set(wrapped, inner);
179
+ return wrapped;
180
+ }
181
+ function quietly(operation) {
182
+ try {
183
+ return operation();
184
+ }
185
+ catch {
186
+ return undefined;
187
+ }
188
+ }
189
+ // Cache failures too: a broken context manager may call back then throw, or call
190
+ // back twice. Neither can replay a paid operation or replace its own exception.
191
+ function once(operation) {
192
+ let outcome;
193
+ return () => {
194
+ if (!outcome) {
195
+ try {
196
+ outcome = { value: operation() };
197
+ }
198
+ catch (error) {
199
+ outcome = { error };
200
+ }
201
+ }
202
+ if ("error" in outcome)
203
+ throw outcome.error;
204
+ return outcome.value;
205
+ };
206
+ }
207
+ function inScope(scope, operation) {
208
+ if (!scope)
209
+ return operation();
210
+ const invoke = once(operation);
211
+ // A manager can return a derived promise (for example, callback().finally(cleanup)).
212
+ // Handle its rejection too, but keep the provider's cached result as the only outcome.
213
+ quietly(() => Promise.resolve(context.with(scope, invoke)).catch(() => { }));
214
+ return invoke();
215
+ }
216
+ function canonicalProvider(id) {
217
+ if (id === "google" || id === "gemini")
218
+ return "gcp.gemini";
219
+ if (id === "openai-responses" || id === "chatgpt")
220
+ return "openai";
221
+ return id;
222
+ }
223
+ function number(attributes, key, value) {
224
+ if (typeof value === "number" && Number.isFinite(value) && value >= 0)
225
+ attributes[key] = value;
226
+ }
227
+ function usageAttributes(usage) {
228
+ const attributes = {};
229
+ number(attributes, "gen_ai.usage.input_tokens", usage.inputTokens);
230
+ number(attributes, "gen_ai.usage.output_tokens", usage.outputTokens);
231
+ number(attributes, "gen_ai.usage.cache_read.input_tokens", usage.cachedInputTokens);
232
+ number(attributes, "gen_ai.usage.cache_write.input_tokens", usage.cacheWriteTokens);
233
+ number(attributes, "gen_ai.usage.reasoning.output_tokens", usage.reasoningTokens);
234
+ number(attributes, "providerkit.usage.reported_cost_usd", usage.reportedCostUsd);
235
+ return attributes;
236
+ }
237
+ function rateAttributes(reading) {
238
+ const attributes = {};
239
+ number(attributes, "providerkit.rate_limit.utilization", reading.utilization);
240
+ number(attributes, "providerkit.rate_limit.reset_at_ms", reading.resetAtMs);
241
+ number(attributes, "providerkit.rate_limit.retry_after_ms", reading.retryAfterMs);
242
+ if (reading.window && WINDOWS.has(reading.window))
243
+ attributes["providerkit.rate_limit.window"] = reading.window;
244
+ return attributes;
245
+ }
246
+ const WINDOWS = new Set(["5h", "weekly", "monthly"]);
247
+ const FINISH_REASONS = new Set(["stop", "length", "tool_calls", "content_filter"]);
248
+ const ERROR_KINDS = {
249
+ aborted: true,
250
+ timeout: true,
251
+ network: true,
252
+ overload: true,
253
+ rate: true,
254
+ quota: true,
255
+ entitlement: true,
256
+ auth: true,
257
+ model: true,
258
+ context: true,
259
+ content: true,
260
+ invalid: true,
261
+ unknown: true,
262
+ };
263
+ //# sourceMappingURL=otel.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"otel.js","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@providerkit/core",
3
- "version": "0.31.0",
3
+ "version": "0.32.0",
4
4
  "description": "The layer under your agent loop: one seam for every LLM provider, plus the failure handling you only learn in production.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -14,6 +14,10 @@
14
14
  "types": "./dist/hosted.d.ts",
15
15
  "default": "./dist/hosted.js"
16
16
  },
17
+ "./otel": {
18
+ "types": "./dist/otel.d.ts",
19
+ "default": "./dist/otel.js"
20
+ },
17
21
  "./zod": {
18
22
  "types": "./dist/zod.d.ts",
19
23
  "default": "./dist/zod.js"
@@ -80,14 +84,19 @@
80
84
  "release:alpha": "bun publish --access public --tag alpha"
81
85
  },
82
86
  "peerDependencies": {
87
+ "@opentelemetry/api": "^1.10.0",
83
88
  "zod": "^4"
84
89
  },
85
90
  "peerDependenciesMeta": {
91
+ "@opentelemetry/api": {
92
+ "optional": true
93
+ },
86
94
  "zod": {
87
95
  "optional": true
88
96
  }
89
97
  },
90
98
  "devDependencies": {
99
+ "@opentelemetry/api": "^1.10.0",
91
100
  "@types/node": "^24.13.3",
92
101
  "typescript": "^7.0.2",
93
102
  "vitest": "^4.1.2",
package/src/otel.ts ADDED
@@ -0,0 +1,306 @@
1
+ // Opt-in only: the main entry and its declarations must never import this module.
2
+ // GenAI field names follow the Development conventions at
3
+ // https://github.com/open-telemetry/semantic-conventions-genai/tree/e6658f14c9d9ea0760825f029cb82e7673f48fab
4
+ import {
5
+ context,
6
+ ROOT_CONTEXT,
7
+ SpanKind,
8
+ SpanStatusCode,
9
+ trace,
10
+ type Attributes,
11
+ type Context,
12
+ type Span,
13
+ type Tracer,
14
+ } from "@opentelemetry/api";
15
+ import { classify, ProviderError, type ErrorKind } from "./errors.ts";
16
+ import type { RateLimitReset } from "./rate-limit.ts";
17
+ import type { Provider, ProviderChunk, StreamOptions, TokenUsage } from "./types.ts";
18
+
19
+ export interface ProviderTracingOptions {
20
+ /** Defaults to the host's tracer named `@providerkit/core`. No SDK is installed here. */
21
+ tracer?: Tracer;
22
+ /** Otherwise captured from the active context at each createStream call, not at setup. */
23
+ parentContext?: Context;
24
+ /** Telemetry label only. Does not change routing. Keep credentials and user data out of it. */
25
+ providerName?: string;
26
+ }
27
+
28
+ // Own wrappers only. An SDK can bind a fresh parent without nesting another CLIENT span.
29
+ const owned = new WeakMap<Provider, Provider>();
30
+
31
+ /**
32
+ * Observe chat calls without capturing their content.
33
+ *
34
+ * ```ts
35
+ * const traced = withProviderTracing(provider);
36
+ * ```
37
+ *
38
+ * Wrap the final provider, outside registry, fallback, gate and watchdog layers.
39
+ * Each consumed stream gets one CLIENT span, including queueing and consumption pauses.
40
+ * No attempts are counted and no retry, read-ahead or cancellation is added.
41
+ * Speech, transcription, decisions, standalone auth and agent runs are not covered.
42
+ * Re-wrapping an owned wrapper replaces its tracing options; hidden inner wrappers
43
+ * cannot be deduplicated. HTTP child spans require the host's context manager.
44
+ */
45
+ export function withProviderTracing(
46
+ provider: Provider,
47
+ options: ProviderTracingOptions = {},
48
+ ): Provider {
49
+ const inner = owned.get(provider) ?? provider;
50
+ const wrapped: Provider = {
51
+ get id() {
52
+ return inner.id;
53
+ },
54
+ get model() {
55
+ return inner.model;
56
+ },
57
+ createStream(messages, tools, opts = {}) {
58
+ const parent = options.parentContext ?? quietly(() => context.active()) ?? ROOT_CONTEXT;
59
+ let span: Span | undefined;
60
+ let scope: Context | undefined;
61
+ let started = false;
62
+ let ended = false;
63
+ let startTime = 0;
64
+ let firstChunk = false;
65
+ let firstActivity = false;
66
+ let usage: Attributes = {};
67
+ let rate: Attributes = {};
68
+
69
+ function end(outcome: "completed" | "closed" | "cancelled" | "error", error?: unknown) {
70
+ if (ended) return;
71
+ ended = true;
72
+ quietly(() => opts.signal?.removeEventListener("abort", cancelled));
73
+ quietly(() => span?.setAttributes(usage));
74
+ quietly(() => span?.setAttributes(rate));
75
+ quietly(() => span?.setAttribute("providerkit.stream.outcome", outcome));
76
+ if (outcome === "error") {
77
+ const kind = quietly(() => classify(error));
78
+ quietly(() =>
79
+ span?.setAttribute(
80
+ "error.type",
81
+ kind && Object.hasOwn(ERROR_KINDS, kind) ? kind : "unknown",
82
+ ),
83
+ );
84
+ quietly(() => {
85
+ if (!(error instanceof ProviderError)) return;
86
+ span?.setAttributes(rateAttributes(error));
87
+ if (Number.isInteger(error.status) && error.status! >= 100 && error.status! <= 599) {
88
+ span?.setAttribute("http.response.status_code", error.status!);
89
+ }
90
+ });
91
+ // Never recordException: messages, bodies and stacks can contain the prompt or key.
92
+ quietly(() => span?.setStatus({ code: SpanStatusCode.ERROR }));
93
+ }
94
+ quietly(() => span?.end());
95
+ }
96
+
97
+ function cancelled() {
98
+ end("cancelled");
99
+ }
100
+
101
+ function start() {
102
+ if (started || ended) return;
103
+ started = true;
104
+ startTime = quietly(() => performance.now()) ?? 0;
105
+ const model = quietly(() => opts.model ?? inner.model);
106
+ const providerName = quietly(() => options.providerName ?? canonicalProvider(inner.id));
107
+ span = quietly(() =>
108
+ (options.tracer ?? trace.getTracer("@providerkit/core")).startSpan(
109
+ model ? `chat ${model}` : "chat",
110
+ {
111
+ kind: SpanKind.CLIENT,
112
+ attributes: {
113
+ "gen_ai.operation.name": "chat",
114
+ "gen_ai.provider.name": providerName,
115
+ "gen_ai.request.model": model,
116
+ "gen_ai.request.stream": true,
117
+ },
118
+ },
119
+ parent,
120
+ ),
121
+ );
122
+ scope = quietly(() => (span ? trace.setSpan(parent, span) : parent));
123
+ quietly(() => {
124
+ opts.signal?.addEventListener("abort", cancelled, { once: true });
125
+ if (opts.signal?.aborted) cancelled();
126
+ });
127
+ }
128
+
129
+ const streamOptions: StreamOptions = {
130
+ ...opts,
131
+ onActivity() {
132
+ quietly(() => {
133
+ if (ended || !started || firstActivity) return;
134
+ firstActivity = true;
135
+ span?.setAttribute(
136
+ "providerkit.stream.first_activity_seconds",
137
+ (performance.now() - startTime) / 1000,
138
+ );
139
+ });
140
+ // Only instrumentation is guarded. A caller's exception keeps its normal behavior.
141
+ opts.onActivity?.();
142
+ },
143
+ onRateLimit(reading) {
144
+ quietly(() => {
145
+ if (!ended) rate = rateAttributes(reading);
146
+ });
147
+ opts.onRateLimit?.(reading);
148
+ },
149
+ };
150
+ const iterator = once<AsyncIterator<ProviderChunk, unknown, unknown>>(() =>
151
+ inner.createStream(messages, tools, streamOptions)[Symbol.asyncIterator](),
152
+ );
153
+
154
+ async function advance(method: "next" | "return" | "throw", args: [] | [unknown]) {
155
+ if (method === "next") start();
156
+ try {
157
+ const result = await inScope(scope, async () => {
158
+ const source = iterator();
159
+ const operation = source[method];
160
+ if (operation) return operation.apply(source, args);
161
+ if (method === "throw") {
162
+ // Match yield* when throw is absent: close first, even if return yields again.
163
+ // A cleanup failure must escape instead of the missing-method TypeError.
164
+ await source.return?.();
165
+ throw new TypeError("The iterator does not provide a 'throw' method.");
166
+ }
167
+ return { done: true as const, value: args[0] };
168
+ });
169
+ quietly(() => {
170
+ if (ended) return;
171
+ if (result.done) {
172
+ end(method === "next" ? "completed" : "closed");
173
+ return;
174
+ }
175
+ const chunk: ProviderChunk = result.value;
176
+ if (!firstChunk) {
177
+ firstChunk = true;
178
+ span?.setAttribute(
179
+ "providerkit.stream.first_chunk_seconds",
180
+ (performance.now() - startTime) / 1000,
181
+ );
182
+ }
183
+ if (chunk.usage) usage = usageAttributes(chunk.usage);
184
+ if (chunk.source) {
185
+ span?.setAttribute("providerkit.response.provider", chunk.source.provider);
186
+ span?.setAttribute("providerkit.response.model", chunk.source.model);
187
+ }
188
+ if (chunk.finishReason && FINISH_REASONS.has(chunk.finishReason)) {
189
+ span?.setAttribute("gen_ai.response.finish_reasons", [chunk.finishReason]);
190
+ }
191
+ });
192
+ return result;
193
+ } catch (error) {
194
+ end(
195
+ opts.signal?.aborted || quietly(() => classify(error)) === "aborted"
196
+ ? "cancelled"
197
+ : "error",
198
+ error,
199
+ );
200
+ throw error;
201
+ }
202
+ }
203
+
204
+ const stream: AsyncIterableIterator<ProviderChunk, unknown, unknown> = {
205
+ [Symbol.asyncIterator]() {
206
+ return this;
207
+ },
208
+ next(...args: [] | [unknown]) {
209
+ return advance("next", args);
210
+ },
211
+ return(...args: [] | [unknown]) {
212
+ return advance("return", args);
213
+ },
214
+ throw(...args: [] | [unknown]) {
215
+ return advance("throw", args);
216
+ },
217
+ };
218
+ return stream;
219
+ },
220
+ };
221
+ owned.set(wrapped, inner);
222
+ return wrapped;
223
+ }
224
+
225
+ function quietly<T>(operation: () => T): T | undefined {
226
+ try {
227
+ return operation();
228
+ } catch {
229
+ return undefined;
230
+ }
231
+ }
232
+
233
+ // Cache failures too: a broken context manager may call back then throw, or call
234
+ // back twice. Neither can replay a paid operation or replace its own exception.
235
+ function once<T>(operation: () => T): () => T {
236
+ let outcome: { value: T } | { error: unknown } | undefined;
237
+ return () => {
238
+ if (!outcome) {
239
+ try {
240
+ outcome = { value: operation() };
241
+ } catch (error) {
242
+ outcome = { error };
243
+ }
244
+ }
245
+ if ("error" in outcome) throw outcome.error;
246
+ return outcome.value;
247
+ };
248
+ }
249
+
250
+ function inScope<T>(scope: Context | undefined, operation: () => T): T {
251
+ if (!scope) return operation();
252
+ const invoke = once(operation);
253
+ // A manager can return a derived promise (for example, callback().finally(cleanup)).
254
+ // Handle its rejection too, but keep the provider's cached result as the only outcome.
255
+ quietly(() => Promise.resolve(context.with(scope, invoke)).catch(() => {}));
256
+ return invoke();
257
+ }
258
+
259
+ function canonicalProvider(id: string): string {
260
+ if (id === "google" || id === "gemini") return "gcp.gemini";
261
+ if (id === "openai-responses" || id === "chatgpt") return "openai";
262
+ return id;
263
+ }
264
+
265
+ function number(attributes: Attributes, key: string, value: number | undefined) {
266
+ if (typeof value === "number" && Number.isFinite(value) && value >= 0) attributes[key] = value;
267
+ }
268
+
269
+ function usageAttributes(usage: TokenUsage): Attributes {
270
+ const attributes: Attributes = {};
271
+ number(attributes, "gen_ai.usage.input_tokens", usage.inputTokens);
272
+ number(attributes, "gen_ai.usage.output_tokens", usage.outputTokens);
273
+ number(attributes, "gen_ai.usage.cache_read.input_tokens", usage.cachedInputTokens);
274
+ number(attributes, "gen_ai.usage.cache_write.input_tokens", usage.cacheWriteTokens);
275
+ number(attributes, "gen_ai.usage.reasoning.output_tokens", usage.reasoningTokens);
276
+ number(attributes, "providerkit.usage.reported_cost_usd", usage.reportedCostUsd);
277
+ return attributes;
278
+ }
279
+
280
+ function rateAttributes(reading: RateLimitReset): Attributes {
281
+ const attributes: Attributes = {};
282
+ number(attributes, "providerkit.rate_limit.utilization", reading.utilization);
283
+ number(attributes, "providerkit.rate_limit.reset_at_ms", reading.resetAtMs);
284
+ number(attributes, "providerkit.rate_limit.retry_after_ms", reading.retryAfterMs);
285
+ if (reading.window && WINDOWS.has(reading.window))
286
+ attributes["providerkit.rate_limit.window"] = reading.window;
287
+ return attributes;
288
+ }
289
+
290
+ const WINDOWS = new Set(["5h", "weekly", "monthly"]);
291
+ const FINISH_REASONS = new Set(["stop", "length", "tool_calls", "content_filter"]);
292
+ const ERROR_KINDS = {
293
+ aborted: true,
294
+ timeout: true,
295
+ network: true,
296
+ overload: true,
297
+ rate: true,
298
+ quota: true,
299
+ entitlement: true,
300
+ auth: true,
301
+ model: true,
302
+ context: true,
303
+ content: true,
304
+ invalid: true,
305
+ unknown: true,
306
+ } satisfies Record<ErrorKind, boolean>;