@providerkit/core 0.30.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.
Files changed (137) hide show
  1. package/README.md +101 -5
  2. package/THIRD_PARTY_NOTICES +144 -0
  3. package/dist/auth/chatgpt-models.js.map +1 -1
  4. package/dist/auth/oauth.d.ts.map +1 -1
  5. package/dist/auth/oauth.js.map +1 -1
  6. package/dist/capability.js.map +1 -1
  7. package/dist/context.d.ts +4 -3
  8. package/dist/context.d.ts.map +1 -1
  9. package/dist/context.js +19 -5
  10. package/dist/context.js.map +1 -1
  11. package/dist/decisions.js.map +1 -1
  12. package/dist/errors.d.ts.map +1 -1
  13. package/dist/errors.js.map +1 -1
  14. package/dist/fallback.d.ts +3 -0
  15. package/dist/fallback.d.ts.map +1 -1
  16. package/dist/fallback.js +9 -5
  17. package/dist/fallback.js.map +1 -1
  18. package/dist/gate.js.map +1 -1
  19. package/dist/hosted/anthropic.d.ts +30 -0
  20. package/dist/hosted/anthropic.d.ts.map +1 -0
  21. package/dist/hosted/anthropic.js +465 -0
  22. package/dist/hosted/anthropic.js.map +1 -0
  23. package/dist/hosted/gemini.d.ts +22 -0
  24. package/dist/hosted/gemini.d.ts.map +1 -0
  25. package/dist/hosted/gemini.js +440 -0
  26. package/dist/hosted/gemini.js.map +1 -0
  27. package/dist/hosted/openai.d.ts +33 -0
  28. package/dist/hosted/openai.d.ts.map +1 -0
  29. package/dist/hosted/openai.js +107 -0
  30. package/dist/hosted/openai.js.map +1 -0
  31. package/dist/hosted/responses.d.ts +28 -0
  32. package/dist/hosted/responses.d.ts.map +1 -0
  33. package/dist/hosted/responses.js +358 -0
  34. package/dist/hosted/responses.js.map +1 -0
  35. package/dist/hosted/shared.d.ts +107 -0
  36. package/dist/hosted/shared.d.ts.map +1 -0
  37. package/dist/hosted/shared.js +264 -0
  38. package/dist/hosted/shared.js.map +1 -0
  39. package/dist/hosted/types.d.ts +191 -0
  40. package/dist/hosted/types.d.ts.map +1 -0
  41. package/dist/hosted/types.js +10 -0
  42. package/dist/hosted/types.js.map +1 -0
  43. package/dist/hosted.d.ts +33 -0
  44. package/dist/hosted.d.ts.map +1 -0
  45. package/dist/hosted.js +61 -0
  46. package/dist/hosted.js.map +1 -0
  47. package/dist/index.d.ts +8 -7
  48. package/dist/index.d.ts.map +1 -1
  49. package/dist/index.js +8 -7
  50. package/dist/index.js.map +1 -1
  51. package/dist/key-pool.d.ts.map +1 -1
  52. package/dist/key-pool.js.map +1 -1
  53. package/dist/otel.d.ts +26 -0
  54. package/dist/otel.d.ts.map +1 -0
  55. package/dist/otel.js +263 -0
  56. package/dist/otel.js.map +1 -0
  57. package/dist/presets.d.ts +2 -2
  58. package/dist/presets.d.ts.map +1 -1
  59. package/dist/providers/anthropic.d.ts +75 -1
  60. package/dist/providers/anthropic.d.ts.map +1 -1
  61. package/dist/providers/anthropic.js +207 -135
  62. package/dist/providers/anthropic.js.map +1 -1
  63. package/dist/providers/factory.d.ts +10 -0
  64. package/dist/providers/factory.d.ts.map +1 -1
  65. package/dist/providers/factory.js +31 -23
  66. package/dist/providers/factory.js.map +1 -1
  67. package/dist/providers/gemini.d.ts +123 -1
  68. package/dist/providers/gemini.d.ts.map +1 -1
  69. package/dist/providers/gemini.js +114 -54
  70. package/dist/providers/gemini.js.map +1 -1
  71. package/dist/providers/hosted-codecs.d.ts +10 -0
  72. package/dist/providers/hosted-codecs.d.ts.map +1 -0
  73. package/dist/providers/hosted-codecs.js +8 -0
  74. package/dist/providers/hosted-codecs.js.map +1 -0
  75. package/dist/providers/openai.d.ts +69 -0
  76. package/dist/providers/openai.d.ts.map +1 -1
  77. package/dist/providers/openai.js +38 -14
  78. package/dist/providers/openai.js.map +1 -1
  79. package/dist/providers/responses.d.ts +123 -0
  80. package/dist/providers/responses.d.ts.map +1 -1
  81. package/dist/providers/responses.js +57 -22
  82. package/dist/providers/responses.js.map +1 -1
  83. package/dist/providers/speech-factory.js.map +1 -1
  84. package/dist/registry.d.ts +3 -0
  85. package/dist/registry.d.ts.map +1 -1
  86. package/dist/registry.js +8 -4
  87. package/dist/registry.js.map +1 -1
  88. package/dist/retry.js.map +1 -1
  89. package/dist/speech-core.d.ts.map +1 -1
  90. package/dist/speech-core.js.map +1 -1
  91. package/dist/tools.d.ts.map +1 -1
  92. package/dist/tools.js.map +1 -1
  93. package/dist/transcription-core.d.ts.map +1 -1
  94. package/dist/transcription-core.js.map +1 -1
  95. package/dist/transport.js.map +1 -1
  96. package/dist/turn.d.ts +10 -1
  97. package/dist/turn.d.ts.map +1 -1
  98. package/dist/turn.js +53 -1
  99. package/dist/turn.js.map +1 -1
  100. package/dist/types.d.ts +51 -0
  101. package/dist/types.d.ts.map +1 -1
  102. package/dist/types.js.map +1 -1
  103. package/dist/usage.d.ts +10 -1
  104. package/dist/usage.d.ts.map +1 -1
  105. package/dist/usage.js +40 -2
  106. package/dist/usage.js.map +1 -1
  107. package/dist/watchdog.d.ts +6 -0
  108. package/dist/watchdog.d.ts.map +1 -1
  109. package/dist/watchdog.js +10 -2
  110. package/dist/watchdog.js.map +1 -1
  111. package/package.json +19 -5
  112. package/src/context.ts +21 -5
  113. package/src/fallback.ts +21 -6
  114. package/src/hosted/anthropic.ts +512 -0
  115. package/src/hosted/gemini.ts +510 -0
  116. package/src/hosted/openai.ts +137 -0
  117. package/src/hosted/responses.ts +420 -0
  118. package/src/hosted/shared.ts +341 -0
  119. package/src/hosted/types.ts +214 -0
  120. package/src/hosted.ts +101 -0
  121. package/src/index.ts +64 -7
  122. package/src/otel.ts +306 -0
  123. package/src/providers/anthropic.ts +252 -143
  124. package/src/providers/factory.ts +127 -82
  125. package/src/providers/gemini.ts +184 -60
  126. package/src/providers/hosted-codecs.ts +29 -0
  127. package/src/providers/openai.ts +52 -15
  128. package/src/providers/responses.ts +93 -24
  129. package/src/registry.ts +14 -4
  130. package/src/turn.ts +55 -1
  131. package/src/types.ts +62 -1
  132. package/src/usage.ts +32 -2
  133. package/src/watchdog.ts +12 -2
  134. package/dist/jev.d.ts +0 -123
  135. package/dist/jev.d.ts.map +0 -1
  136. package/dist/jev.js +0 -278
  137. package/dist/jev.js.map +0 -1
package/src/index.ts CHANGED
@@ -1,8 +1,22 @@
1
1
  export * from "./types.ts";
2
+ export * from "./hosted/types.ts";
2
3
  export * from "./turn.ts";
3
4
  export * from "./errors.ts";
4
5
  export * from "./retry.ts";
5
- export * from "./fallback.ts";
6
+ export {
7
+ DEFAULT_FALLBACK_COOLDOWNS,
8
+ FallbackPool,
9
+ NoAvailableProviderError,
10
+ withConfiguredFallbacks,
11
+ withFallbackProviders,
12
+ type FallbackOptions,
13
+ type FallbackSpec,
14
+ type FallbackCandidate,
15
+ type ProviderFallbackConfig,
16
+ type Cooldown,
17
+ type CooldownStore,
18
+ type FallbackProvider,
19
+ } from "./fallback.ts";
6
20
  export * from "./key-pool.ts";
7
21
  export * from "./watchdog.ts";
8
22
  export * from "./gate.ts";
@@ -31,10 +45,53 @@ export * from "./image.ts";
31
45
  export * from "./capability.ts";
32
46
  export * from "./attribution.ts";
33
47
  export * from "./presets.ts";
34
- export * from "./providers/anthropic.ts";
35
- export * from "./providers/openai.ts";
36
- export * from "./providers/responses.ts";
37
- export * from "./providers/gemini.ts";
48
+ export {
49
+ createAnthropicProvider,
50
+ toAnthropicMessages,
51
+ type AnthropicConfig,
52
+ } from "./providers/anthropic.ts";
53
+ export {
54
+ createOpenAIProvider,
55
+ toOpenAIMessages,
56
+ effortParams,
57
+ openRouterCostUsd,
58
+ openRouterHostFor,
59
+ type OpenAIConfig,
60
+ type EffortDialect,
61
+ } from "./providers/openai.ts";
62
+ export {
63
+ createResponsesProvider,
64
+ toResponsesInput,
65
+ type ResponsesConfig,
66
+ } from "./providers/responses.ts";
67
+ export {
68
+ createGeminiProvider,
69
+ toGeminiContents,
70
+ antigravityUserAgent,
71
+ antigravitySessionId,
72
+ resolveAntigravityWireModel,
73
+ type GeminiConfig,
74
+ type GeminiContent,
75
+ } from "./providers/gemini.ts";
38
76
  export * from "./providers/zai.ts";
39
- export * from "./providers/factory.ts";
40
- export * from "./registry.ts";
77
+ export {
78
+ createPresetProvider,
79
+ presetAdapter,
80
+ OPENCODE_CLI_USER_AGENT,
81
+ OPENCODE_PUBLIC_API_KEY,
82
+ isZenFreeModel,
83
+ forgeOpenCodeSessionId,
84
+ type PresetProviderConfig,
85
+ type PresetAdapterConfig,
86
+ } from "./providers/factory.ts";
87
+ export {
88
+ createRegistry,
89
+ type ConnectionCredential,
90
+ type ConnectionConfig,
91
+ type RegistryCooldownInfo,
92
+ type RegistryOptions,
93
+ type ViewOptions,
94
+ type CandidateStatus,
95
+ type ConnectionStatus,
96
+ type Registry,
97
+ } from "./registry.ts";
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>;