@jxburros/ai-nugget 0.4.1 → 0.7.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 (187) hide show
  1. package/README.md +158 -382
  2. package/UPGRADING.md +182 -0
  3. package/dist/adapters/engines/anthropic.d.ts +7 -1
  4. package/dist/adapters/engines/anthropic.js +82 -37
  5. package/dist/adapters/engines/base.d.ts +29 -2
  6. package/dist/adapters/engines/base.js +52 -8
  7. package/dist/adapters/engines/google.d.ts +7 -1
  8. package/dist/adapters/engines/google.js +80 -29
  9. package/dist/adapters/engines/ollama.d.ts +2 -1
  10. package/dist/adapters/engines/ollama.js +57 -15
  11. package/dist/adapters/engines/openaiChat.d.ts +8 -1
  12. package/dist/adapters/engines/openaiChat.js +109 -29
  13. package/dist/adapters/profiles.d.ts +21 -1
  14. package/dist/adapters/profiles.js +12 -2
  15. package/dist/agent/loop.d.ts +45 -1
  16. package/dist/agent/loop.js +117 -12
  17. package/dist/cjs/adapters/engines/anthropic.js +326 -0
  18. package/dist/cjs/adapters/engines/base.js +147 -0
  19. package/dist/cjs/adapters/engines/google.js +291 -0
  20. package/dist/cjs/adapters/engines/ollama.js +205 -0
  21. package/dist/cjs/adapters/engines/openaiChat.js +312 -0
  22. package/dist/cjs/adapters/index.js +22 -0
  23. package/dist/cjs/adapters/profiles.js +125 -0
  24. package/dist/cjs/agent/index.js +18 -0
  25. package/dist/cjs/agent/loop.js +373 -0
  26. package/dist/cjs/agent/tools.js +51 -0
  27. package/dist/cjs/connect.js +27 -0
  28. package/dist/cjs/errors.js +110 -0
  29. package/dist/cjs/handler.js +586 -0
  30. package/dist/cjs/index.js +28 -0
  31. package/dist/cjs/json.js +121 -0
  32. package/dist/cjs/keys.js +81 -0
  33. package/dist/cjs/package.json +3 -0
  34. package/dist/cjs/policy.js +42 -0
  35. package/dist/cjs/reasoning.js +159 -0
  36. package/dist/cjs/redact.js +78 -0
  37. package/dist/cjs/tokens.js +22 -0
  38. package/dist/cjs/transport.js +172 -0
  39. package/dist/cjs/types.js +6 -0
  40. package/dist/cjs/util.js +126 -0
  41. package/dist/errors.js +25 -1
  42. package/dist/handler.d.ts +67 -1
  43. package/dist/handler.js +266 -61
  44. package/dist/index.d.ts +1 -0
  45. package/dist/index.js +1 -0
  46. package/dist/reasoning.d.ts +45 -0
  47. package/dist/reasoning.js +154 -0
  48. package/dist/redact.d.ts +18 -0
  49. package/dist/redact.js +29 -1
  50. package/dist/transport.d.ts +3 -1
  51. package/dist/transport.js +21 -1
  52. package/dist/types.d.ts +112 -2
  53. package/dist/util.d.ts +22 -0
  54. package/dist/util.js +59 -0
  55. package/nugget/VERSION.txt +2 -2
  56. package/nugget/dist/adapters/engines/anthropic.d.ts +14 -0
  57. package/nugget/dist/adapters/engines/anthropic.d.ts.map +1 -0
  58. package/nugget/dist/adapters/engines/anthropic.js +323 -0
  59. package/nugget/dist/adapters/engines/anthropic.js.map +1 -0
  60. package/nugget/dist/adapters/engines/base.d.ts +50 -0
  61. package/nugget/dist/adapters/engines/base.d.ts.map +1 -0
  62. package/nugget/dist/adapters/engines/base.js +137 -0
  63. package/nugget/dist/adapters/engines/base.js.map +1 -0
  64. package/nugget/dist/adapters/engines/google.d.ts +24 -0
  65. package/nugget/dist/adapters/engines/google.d.ts.map +1 -0
  66. package/nugget/dist/adapters/engines/google.js +288 -0
  67. package/nugget/dist/adapters/engines/google.js.map +1 -0
  68. package/nugget/dist/adapters/engines/ollama.d.ts +11 -0
  69. package/nugget/dist/adapters/engines/ollama.d.ts.map +1 -0
  70. package/nugget/dist/adapters/engines/ollama.js +202 -0
  71. package/nugget/dist/adapters/engines/ollama.js.map +1 -0
  72. package/nugget/dist/adapters/engines/openaiChat.d.ts +22 -0
  73. package/nugget/dist/adapters/engines/openaiChat.d.ts.map +1 -0
  74. package/nugget/dist/adapters/engines/openaiChat.js +308 -0
  75. package/nugget/dist/adapters/engines/openaiChat.js.map +1 -0
  76. package/nugget/dist/adapters/index.d.ts +5 -0
  77. package/nugget/dist/adapters/index.d.ts.map +1 -0
  78. package/nugget/dist/adapters/index.js +17 -0
  79. package/nugget/dist/adapters/index.js.map +1 -0
  80. package/nugget/dist/adapters/profiles.d.ts +62 -0
  81. package/nugget/dist/adapters/profiles.d.ts.map +1 -0
  82. package/nugget/dist/adapters/profiles.js +121 -0
  83. package/nugget/dist/adapters/profiles.js.map +1 -0
  84. package/nugget/dist/agent/index.d.ts +3 -0
  85. package/nugget/dist/agent/index.d.ts.map +1 -0
  86. package/nugget/dist/agent/index.js +3 -0
  87. package/nugget/dist/agent/index.js.map +1 -0
  88. package/nugget/dist/agent/loop.d.ts +114 -0
  89. package/nugget/dist/agent/loop.d.ts.map +1 -0
  90. package/nugget/dist/agent/loop.js +371 -0
  91. package/nugget/dist/agent/loop.js.map +1 -0
  92. package/nugget/dist/agent/tools.d.ts +29 -0
  93. package/nugget/dist/agent/tools.d.ts.map +1 -0
  94. package/nugget/dist/agent/tools.js +48 -0
  95. package/nugget/dist/agent/tools.js.map +1 -0
  96. package/nugget/dist/cjs/adapters/engines/anthropic.js +326 -0
  97. package/nugget/dist/cjs/adapters/engines/base.js +147 -0
  98. package/nugget/dist/cjs/adapters/engines/google.js +291 -0
  99. package/nugget/dist/cjs/adapters/engines/ollama.js +205 -0
  100. package/nugget/dist/cjs/adapters/engines/openaiChat.js +312 -0
  101. package/nugget/dist/cjs/adapters/index.js +22 -0
  102. package/nugget/dist/cjs/adapters/profiles.js +125 -0
  103. package/nugget/dist/cjs/agent/index.js +18 -0
  104. package/nugget/dist/cjs/agent/loop.js +373 -0
  105. package/nugget/dist/cjs/agent/tools.js +51 -0
  106. package/nugget/dist/cjs/connect.js +27 -0
  107. package/nugget/dist/cjs/errors.js +110 -0
  108. package/nugget/dist/cjs/handler.js +586 -0
  109. package/nugget/dist/cjs/index.js +28 -0
  110. package/nugget/dist/cjs/json.js +121 -0
  111. package/nugget/dist/cjs/keys.js +81 -0
  112. package/nugget/dist/cjs/package.json +3 -0
  113. package/nugget/dist/cjs/policy.js +42 -0
  114. package/nugget/dist/cjs/reasoning.js +159 -0
  115. package/nugget/dist/cjs/redact.js +78 -0
  116. package/nugget/dist/cjs/tokens.js +22 -0
  117. package/nugget/dist/cjs/transport.js +172 -0
  118. package/nugget/dist/cjs/types.js +6 -0
  119. package/nugget/dist/cjs/util.js +126 -0
  120. package/nugget/dist/connect.d.ts +31 -0
  121. package/nugget/dist/connect.d.ts.map +1 -0
  122. package/nugget/dist/connect.js +25 -0
  123. package/nugget/dist/connect.js.map +1 -0
  124. package/nugget/dist/errors.d.ts +22 -0
  125. package/nugget/dist/errors.d.ts.map +1 -0
  126. package/nugget/dist/errors.js +104 -0
  127. package/nugget/dist/errors.js.map +1 -0
  128. package/nugget/dist/handler.d.ts +114 -0
  129. package/nugget/dist/handler.d.ts.map +1 -0
  130. package/nugget/dist/handler.js +582 -0
  131. package/nugget/dist/handler.js.map +1 -0
  132. package/nugget/dist/index.d.ts +13 -0
  133. package/nugget/dist/index.d.ts.map +1 -0
  134. package/nugget/dist/index.js +13 -0
  135. package/nugget/dist/index.js.map +1 -0
  136. package/nugget/dist/json.d.ts +7 -0
  137. package/nugget/dist/json.d.ts.map +1 -0
  138. package/nugget/dist/json.js +114 -0
  139. package/nugget/dist/json.js.map +1 -0
  140. package/nugget/dist/keys.d.ts +7 -0
  141. package/nugget/dist/keys.d.ts.map +1 -0
  142. package/nugget/dist/keys.js +75 -0
  143. package/nugget/dist/keys.js.map +1 -0
  144. package/nugget/dist/policy.d.ts +6 -0
  145. package/nugget/dist/policy.d.ts.map +1 -0
  146. package/nugget/dist/policy.js +37 -0
  147. package/nugget/dist/policy.js.map +1 -0
  148. package/nugget/dist/reasoning.d.ts +45 -0
  149. package/nugget/dist/reasoning.d.ts.map +1 -0
  150. package/nugget/dist/reasoning.js +154 -0
  151. package/nugget/dist/reasoning.js.map +1 -0
  152. package/nugget/dist/redact.d.ts +26 -0
  153. package/nugget/dist/redact.d.ts.map +1 -0
  154. package/nugget/dist/redact.js +74 -0
  155. package/nugget/dist/redact.js.map +1 -0
  156. package/nugget/dist/tokens.d.ts +5 -0
  157. package/nugget/dist/tokens.d.ts.map +1 -0
  158. package/nugget/dist/tokens.js +18 -0
  159. package/nugget/dist/tokens.js.map +1 -0
  160. package/nugget/dist/transport.d.ts +30 -0
  161. package/nugget/dist/transport.d.ts.map +1 -0
  162. package/nugget/dist/transport.js +165 -0
  163. package/nugget/dist/transport.js.map +1 -0
  164. package/nugget/dist/types.d.ts +301 -0
  165. package/nugget/dist/types.d.ts.map +1 -0
  166. package/nugget/dist/types.js +4 -0
  167. package/nugget/dist/types.js.map +1 -0
  168. package/nugget/dist/util.d.ts +31 -0
  169. package/nugget/dist/util.d.ts.map +1 -0
  170. package/nugget/dist/util.js +114 -0
  171. package/nugget/dist/util.js.map +1 -0
  172. package/nugget/src/adapters/engines/anthropic.ts +78 -37
  173. package/nugget/src/adapters/engines/base.ts +50 -7
  174. package/nugget/src/adapters/engines/google.ts +79 -29
  175. package/nugget/src/adapters/engines/ollama.ts +56 -17
  176. package/nugget/src/adapters/engines/openaiChat.ts +104 -30
  177. package/nugget/src/adapters/profiles.ts +53 -3
  178. package/nugget/src/agent/loop.ts +156 -13
  179. package/nugget/src/errors.ts +25 -1
  180. package/nugget/src/handler.ts +308 -59
  181. package/nugget/src/index.ts +1 -0
  182. package/nugget/src/reasoning.ts +174 -0
  183. package/nugget/src/redact.ts +32 -1
  184. package/nugget/src/transport.ts +20 -1
  185. package/nugget/src/types.ts +113 -1
  186. package/nugget/src/util.ts +64 -0
  187. package/package.json +18 -5
@@ -0,0 +1,586 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.AIHandler = void 0;
4
+ exports.resetPolicyWarningForTests = resetPolicyWarningForTests;
5
+ const index_js_1 = require("./adapters/index.js");
6
+ const profiles_js_1 = require("./adapters/profiles.js");
7
+ const errors_js_1 = require("./errors.js");
8
+ const json_js_1 = require("./json.js");
9
+ const reasoning_js_1 = require("./reasoning.js");
10
+ const policy_js_1 = require("./policy.js");
11
+ const redact_js_1 = require("./redact.js");
12
+ const util_js_1 = require("./util.js");
13
+ /**
14
+ * A *startup* notice, so it fires once per process rather than once per handler
15
+ * — an app that builds a handler per request would otherwise flood its logs
16
+ * with a message that says the same thing every time.
17
+ */
18
+ let warnedNoPolicy = false;
19
+ /** Test seam: reset the once-per-process startup notice. */
20
+ function resetPolicyWarningForTests() {
21
+ warnedNoPolicy = false;
22
+ }
23
+ class AIHandler {
24
+ opts;
25
+ active = 0;
26
+ queue = [];
27
+ lastStarted = 0;
28
+ sessionRedactor = new redact_js_1.SessionRedactor();
29
+ policy;
30
+ constructor(opts) {
31
+ this.opts = opts;
32
+ this.policy = opts.policy ?? (0, policy_js_1.allowAllPolicy)();
33
+ // `allowAllPolicy()` stays the default — a library must not decide an app's
34
+ // governance — but "no policy configured" should be visible at runtime, not
35
+ // only in a README paragraph. Passing an explicit policy (including
36
+ // `allowAllPolicy()`) is the opt-out.
37
+ if (!opts.policy && !opts.silencePolicyWarning && !warnedNoPolicy) {
38
+ warnedNoPolicy = true;
39
+ globalThis.console?.warn?.('[ai-nugget] No GovernancePolicy configured — every provider/model is allowed. ' +
40
+ 'Pass `policy` (e.g. allowlistPolicy(...)), or `policy: allowAllPolicy()` / `silencePolicyWarning: true` to accept this deliberately.');
41
+ }
42
+ }
43
+ async chat(conn, req) {
44
+ let result;
45
+ for await (const event of this.stream(conn, req)) {
46
+ if (event.type === 'done')
47
+ result = event.result;
48
+ if (event.type === 'error')
49
+ throw event.error;
50
+ }
51
+ if (!result)
52
+ throw new errors_js_1.AIError('Call ended without a result', { kind: 'invalid_response', provider: conn.provider });
53
+ return result;
54
+ }
55
+ async *stream(conn, req) {
56
+ const callId = createCallId();
57
+ const startedAt = Date.now();
58
+ const adapter = (0, index_js_1.adapterFor)(conn.provider, conn.baseUrl);
59
+ const preflight = await this.preflight(callId, conn, req.model, req.metadata);
60
+ if (!preflight.ok)
61
+ return yield* this.failStream(callId, conn, req, startedAt, 1, preflight.error);
62
+ // One idempotency key per logical call, reused across every retry attempt,
63
+ // so a provider that supports it collapses a re-sent generation instead of
64
+ // billing it twice (see `supportsIdempotencyKey` in the profile table).
65
+ const resolved = withIdempotencyKey(preflight.resolved, callId);
66
+ let acquired = false;
67
+ let recorded = false;
68
+ let attempt = 0;
69
+ try {
70
+ await this.acquire(req.signal);
71
+ acquired = true;
72
+ const maxAttempts = this.opts.retry?.maxAttempts ?? 3;
73
+ let emittedStart = false;
74
+ let emittedOutput = false;
75
+ const stripInline = this.opts.stripInlineReasoning !== false;
76
+ for (;;) {
77
+ attempt += 1;
78
+ // One stripper per attempt: a retried stream starts its tag state over.
79
+ const stripper = stripInline ? (0, reasoning_js_1.createReasoningStripper)() : null;
80
+ try {
81
+ for await (const event of adapter.stream(resolved, req)) {
82
+ if (event.type === 'start') {
83
+ if (!emittedStart) {
84
+ emittedStart = true;
85
+ yield { ...event, callId };
86
+ }
87
+ continue;
88
+ }
89
+ if (event.type === 'delta' || event.type === 'tool_call')
90
+ emittedOutput = true;
91
+ if (event.type === 'delta' && stripper) {
92
+ // Inline reasoning never reaches `delta`; it rides the reasoning channel like a
93
+ // provider-native thinking field would.
94
+ const piece = stripper.push(event.text);
95
+ if (piece.reasoning)
96
+ yield { type: 'reasoning', text: piece.reasoning };
97
+ if (piece.visible)
98
+ yield { type: 'delta', text: piece.visible };
99
+ continue;
100
+ }
101
+ if (event.type === 'done') {
102
+ let result = event.result;
103
+ if (stripper) {
104
+ const tail = stripper.end();
105
+ if (tail.reasoning)
106
+ yield { type: 'reasoning', text: tail.reasoning };
107
+ if (tail.visible)
108
+ yield { type: 'delta', text: tail.visible };
109
+ if ((0, reasoning_js_1.containsReasoningBlock)(result.text)) {
110
+ result = { ...result, text: (0, reasoning_js_1.stripReasoningBlocks)(result.text) };
111
+ }
112
+ }
113
+ await this.recordSuccess(callId, conn, req, startedAt, attempt, result);
114
+ recorded = true;
115
+ yield { ...event, result };
116
+ return;
117
+ }
118
+ yield event;
119
+ }
120
+ throw new errors_js_1.AIError('Provider did not emit a done event', { kind: 'invalid_response', provider: conn.provider });
121
+ }
122
+ catch (errorValue) {
123
+ const error = (0, errors_js_1.fromUnknown)(errorValue, conn.provider);
124
+ // `emittedOutput` stops retries once any byte has reached the caller:
125
+ // never silently re-run a partially delivered answer.
126
+ if (!error.retryable || attempt >= maxAttempts || req.signal?.aborted || emittedOutput) {
127
+ recorded = true;
128
+ return yield* this.failStream(callId, conn, req, startedAt, attempt, error);
129
+ }
130
+ const delayMs = this.retryDelay(error, attempt);
131
+ yield { type: 'retry', attempt, reason: error.kind, delayMs };
132
+ try {
133
+ await (0, util_js_1.sleep)(delayMs, req.signal);
134
+ }
135
+ catch (sleepError) {
136
+ recorded = true;
137
+ return yield* this.failStream(callId, conn, req, startedAt, attempt, (0, errors_js_1.fromUnknown)(sleepError, conn.provider));
138
+ }
139
+ }
140
+ }
141
+ }
142
+ catch (errorValue) {
143
+ recorded = true;
144
+ return yield* this.failStream(callId, conn, req, startedAt, Math.max(1, attempt), (0, errors_js_1.fromUnknown)(errorValue, conn.provider));
145
+ }
146
+ finally {
147
+ if (acquired)
148
+ this.release();
149
+ if (acquired && !recorded) {
150
+ await this.recordFailure(callId, conn, req, startedAt, Math.max(1, attempt), new errors_js_1.AIError('Call canceled before completion', { kind: 'canceled', retryable: false, provider: conn.provider }));
151
+ }
152
+ }
153
+ }
154
+ /**
155
+ * The shared pre-call preamble: policy check → key resolution → `beforeCall`
156
+ * hook. Every entry point (`stream`, `embed`, `listModels`/`testConnection`)
157
+ * runs exactly this sequence, so it lives once. Failures are *returned*, not
158
+ * recorded — each caller owns its own telemetry shape (`recordFailure` for
159
+ * chat/probe, `recordEmbed` for embeddings) and records the returned error.
160
+ */
161
+ async preflight(callId, conn, model, metadata) {
162
+ const policyResult = this.policy.checkModel(conn.provider, model);
163
+ if (!policyResult.allowed) {
164
+ return { ok: false, error: new errors_js_1.AIError(policyResult.reason, { kind: 'policy_blocked', retryable: false, provider: conn.provider }) };
165
+ }
166
+ let resolved;
167
+ try {
168
+ resolved = await this.resolveConnection(conn);
169
+ }
170
+ catch (errorValue) {
171
+ // Key resolution failures (missing/locked/denied) are a recorded outcome,
172
+ // not an uncaught throw — the traceability contract covers them too.
173
+ return { ok: false, error: (0, errors_js_1.fromUnknown)(errorValue, conn.provider) };
174
+ }
175
+ try {
176
+ const info = {
177
+ callId,
178
+ connection: safeConnection(conn),
179
+ provider: conn.provider,
180
+ model,
181
+ metadata,
182
+ resolved: safeResolved(resolved),
183
+ };
184
+ if (await this.opts.hooks?.beforeCall?.(info) === 'deny') {
185
+ return { ok: false, error: new errors_js_1.AIError('Call denied by beforeCall hook', { kind: 'policy_blocked', retryable: false, provider: conn.provider }) };
186
+ }
187
+ }
188
+ catch (errorValue) {
189
+ // A throwing beforeCall hook is a recorded, redacted outcome too — not
190
+ // an uncaught throw that skips telemetry and the redaction guarantee.
191
+ return { ok: false, error: (0, errors_js_1.fromUnknown)(errorValue, conn.provider) };
192
+ }
193
+ return { ok: true, resolved };
194
+ }
195
+ /** Record a failed call and emit the single redacted `error` event for it. */
196
+ async *failStream(callId, conn, req, startedAt, attempts, error) {
197
+ await this.recordFailure(callId, conn, req, startedAt, attempts, error);
198
+ yield { type: 'error', error: this.redactedError(error) };
199
+ }
200
+ async listModels(conn) {
201
+ return this.runProbe(conn, '__listModels__', async (resolved) => {
202
+ const adapter = (0, index_js_1.adapterFor)(conn.provider, conn.baseUrl);
203
+ return adapter.listModels?.(resolved) ?? [];
204
+ });
205
+ }
206
+ async testConnection(conn) {
207
+ try {
208
+ return await this.runProbe(conn, '__testConnection__', async (resolved) => {
209
+ const adapter = (0, index_js_1.adapterFor)(conn.provider, conn.baseUrl);
210
+ const health = await adapter.health?.(resolved);
211
+ if (health) {
212
+ if (!health.ok)
213
+ throw new errors_js_1.AIError(health.detail ?? 'Connection failed', { kind: 'network', retryable: false, provider: conn.provider });
214
+ return { ok: true, message: health.detail ?? 'Connection healthy' };
215
+ }
216
+ await adapter.listModels?.(resolved);
217
+ return { ok: true, message: 'Connection healthy' };
218
+ });
219
+ }
220
+ catch (error) {
221
+ return { ok: false, message: error instanceof Error ? this.redact(error.message) : 'Connection failed' };
222
+ }
223
+ }
224
+ /**
225
+ * Warm a connection so the first real call doesn't pay cold DNS/TLS and
226
+ * (for a local daemon) process spin-up on the hot path. Runs a lightweight
227
+ * health probe and never throws — call it once at boot. Combined with a CJS
228
+ * `require` path it removes the cold-start "offline" false negative.
229
+ */
230
+ async prewarm(conn) {
231
+ try {
232
+ await this.testConnection(conn);
233
+ }
234
+ catch {
235
+ // Warm-up only: a failure here just means the first real call pays the cost.
236
+ }
237
+ }
238
+ /**
239
+ * Chat that returns typed, validated output. Requests JSON mode, extracts the
240
+ * JSON from the reply, and validates it against any Standard Schema validator
241
+ * (Zod / Valibot / ArkType). On a validation miss it performs exactly one
242
+ * corrective retry that shows the model its error, then throws
243
+ * `invalid_response` if still invalid. No schema library is bundled — the
244
+ * caller supplies the schema.
245
+ */
246
+ async chatParsed(conn, req, schema) {
247
+ const base = { ...req, responseFormat: req.responseFormat ?? { type: 'json' } };
248
+ let result = await this.chat(conn, base);
249
+ let validated = await validateWithSchema(schema, result.text);
250
+ if (validated.ok)
251
+ return { data: validated.value, result };
252
+ const retry = {
253
+ ...base,
254
+ messages: [
255
+ ...base.messages,
256
+ { role: 'assistant', content: result.text },
257
+ { role: 'user', content: `That response did not match the required schema (${validated.message}). Reply again with ONLY a valid JSON value that matches it.` },
258
+ ],
259
+ };
260
+ result = await this.chat(conn, retry);
261
+ validated = await validateWithSchema(schema, result.text);
262
+ if (validated.ok)
263
+ return { data: validated.value, result };
264
+ throw new errors_js_1.AIError(`Model output failed schema validation: ${validated.message}`, { kind: 'invalid_response', provider: conn.provider });
265
+ }
266
+ /**
267
+ * Produce embeddings through the same governed pipeline as chat: policy check,
268
+ * key resolution, `beforeCall` hook, concurrency, and exactly one redacted
269
+ * telemetry record. Throws a typed `invalid_request` error for providers whose
270
+ * adapter has no `embed` (Anthropic, Google) rather than failing silently.
271
+ */
272
+ async embed(conn, req) {
273
+ const callId = createCallId();
274
+ const startedAt = Date.now();
275
+ const inputChars = (Array.isArray(req.input) ? req.input : [req.input]).reduce((sum, text) => sum + text.length, 0);
276
+ const fail = async (error) => {
277
+ await this.recordEmbed(callId, conn, req, startedAt, { estimated: true }, inputChars, error);
278
+ throw this.redactedError(error);
279
+ };
280
+ const preflight = await this.preflight(callId, conn, req.model, req.metadata);
281
+ if (!preflight.ok)
282
+ return fail(preflight.error);
283
+ const resolved = preflight.resolved;
284
+ const adapter = (0, index_js_1.adapterFor)(conn.provider, conn.baseUrl);
285
+ if (!adapter.embed) {
286
+ return fail(new errors_js_1.AIError(`Provider ${conn.provider} does not support embeddings`, { kind: 'invalid_request', retryable: false, provider: conn.provider }));
287
+ }
288
+ await this.acquire(req.signal);
289
+ try {
290
+ const result = await adapter.embed(resolved, req);
291
+ await this.recordEmbed(callId, conn, req, startedAt, result.usage, inputChars);
292
+ return result;
293
+ }
294
+ catch (errorValue) {
295
+ return fail((0, errors_js_1.fromUnknown)(errorValue, conn.provider));
296
+ }
297
+ finally {
298
+ this.release();
299
+ }
300
+ }
301
+ async recordEmbed(callId, conn, req, startedAt, usage, inputChars, error) {
302
+ const costUsd = error ? undefined : this.opts.pricing?.({ provider: conn.provider, model: req.model, usage });
303
+ await this.record({
304
+ callId,
305
+ connectionId: conn.id,
306
+ provider: conn.provider,
307
+ model: req.model,
308
+ startedAt,
309
+ timing: { firstTokenMs: null, totalMs: Date.now() - startedAt },
310
+ usage,
311
+ finishReason: error ? (error.kind === 'canceled' ? 'canceled' : 'error') : 'stop',
312
+ ...(error ? { error: { kind: error.kind, status: error.status, message: error.message } } : {}),
313
+ attempts: 1,
314
+ metadata: { ...req.metadata, operation: '__embed__' },
315
+ promptChars: inputChars,
316
+ responseChars: 0,
317
+ ...(costUsd !== undefined ? { costUsd } : {}),
318
+ });
319
+ }
320
+ async runProbe(conn, operation, action) {
321
+ const callId = createCallId();
322
+ const startedAt = Date.now();
323
+ const req = { model: operation, messages: [], metadata: { operation } };
324
+ try {
325
+ const preflight = await this.preflight(callId, conn, operation, req.metadata);
326
+ if (!preflight.ok)
327
+ throw preflight.error;
328
+ const resolved = preflight.resolved;
329
+ await this.acquire(undefined);
330
+ try {
331
+ const value = await action(resolved);
332
+ await this.recordSuccess(callId, conn, req, startedAt, 1, {
333
+ text: '',
334
+ finishReason: 'stop',
335
+ usage: { estimated: true },
336
+ timing: { firstTokenMs: null, totalMs: Date.now() - startedAt },
337
+ model: operation,
338
+ source: { provider: conn.provider, connectionId: conn.id, baseUrl: resolved.baseUrl },
339
+ });
340
+ return value;
341
+ }
342
+ finally {
343
+ this.release();
344
+ }
345
+ }
346
+ catch (errorValue) {
347
+ const error = (0, errors_js_1.fromUnknown)(errorValue, conn.provider);
348
+ await this.recordFailure(callId, conn, req, startedAt, 1, error);
349
+ throw this.redactedError(error);
350
+ }
351
+ }
352
+ async resolveConnection(conn) {
353
+ const profile = (0, profiles_js_1.profileFor)(conn.provider, conn.baseUrl);
354
+ const baseUrl = conn.baseUrl ?? profile.defaultBaseUrl;
355
+ if (!baseUrl)
356
+ throw new errors_js_1.AIError(`Provider ${conn.provider} requires baseUrl`, { kind: 'invalid_request', retryable: false, provider: conn.provider });
357
+ const keyRef = conn.keyRef ?? { kind: 'none' };
358
+ const key = await this.opts.keySource.resolve(keyRef);
359
+ if (!key.ok) {
360
+ throw new errors_js_1.AIError(`API key unavailable: ${key.reason}`, { kind: 'key_unavailable', retryable: false, provider: conn.provider });
361
+ }
362
+ this.sessionRedactor.addSecret(key.apiKey);
363
+ return {
364
+ ...conn,
365
+ baseUrl: trimSlash(baseUrl),
366
+ apiKey: key.apiKey,
367
+ headers: (0, profiles_js_1.applyAuth)(profile, key.apiKey, conn.headers ?? {}),
368
+ };
369
+ }
370
+ async acquire(signal) {
371
+ const max = this.opts.limits?.maxConcurrent ?? Number.POSITIVE_INFINITY;
372
+ while (this.active >= max) {
373
+ await new Promise((resolve, reject) => {
374
+ let waiter;
375
+ const onAbort = () => {
376
+ const index = this.queue.indexOf(waiter);
377
+ if (index >= 0)
378
+ this.queue.splice(index, 1);
379
+ reject(new errors_js_1.AIError('Call canceled while waiting for concurrency slot', { kind: 'canceled', retryable: false }));
380
+ };
381
+ if (signal?.aborted) {
382
+ reject(new errors_js_1.AIError('Call canceled while waiting for concurrency slot', { kind: 'canceled', retryable: false }));
383
+ return;
384
+ }
385
+ signal?.addEventListener('abort', onAbort, { once: true });
386
+ waiter = { resolve, reject, signal, onAbort };
387
+ this.queue.push(waiter);
388
+ });
389
+ }
390
+ this.active += 1;
391
+ const minInterval = this.opts.limits?.minIntervalMs ?? 0;
392
+ const previousLastStarted = this.lastStarted;
393
+ const wait = Math.max(0, previousLastStarted + minInterval - Date.now());
394
+ const reserved = Date.now() + wait;
395
+ this.lastStarted = reserved;
396
+ try {
397
+ if (wait)
398
+ await (0, util_js_1.sleep)(wait, signal);
399
+ }
400
+ catch (error) {
401
+ this.release();
402
+ // Only undo our own reservation — a later caller may have already
403
+ // paced itself off `reserved` and must keep that spacing.
404
+ if (this.lastStarted === reserved)
405
+ this.lastStarted = previousLastStarted;
406
+ throw error;
407
+ }
408
+ }
409
+ release() {
410
+ this.active = Math.max(0, this.active - 1);
411
+ while (this.queue.length) {
412
+ const waiter = this.queue.shift();
413
+ waiter.signal?.removeEventListener('abort', waiter.onAbort);
414
+ if (waiter.signal?.aborted)
415
+ continue;
416
+ waiter.resolve();
417
+ break;
418
+ }
419
+ }
420
+ retryDelay(error, attempt) {
421
+ const base = this.opts.retry?.baseDelayMs ?? 250;
422
+ const max = this.opts.retry?.maxDelayMs ?? 30_000;
423
+ if (error.retryAfterMs !== undefined)
424
+ return Math.min(error.retryAfterMs, max);
425
+ const exponential = Math.min(max, base * 2 ** Math.max(0, attempt - 1));
426
+ return Math.round(exponential * (0.75 + Math.random() * 0.5));
427
+ }
428
+ async recordSuccess(callId, conn, req, startedAt, attempts, result) {
429
+ const costUsd = this.opts.pricing?.({ provider: conn.provider, model: req.model, usage: result.usage });
430
+ await this.record({
431
+ callId,
432
+ connectionId: conn.id,
433
+ provider: conn.provider,
434
+ model: req.model,
435
+ startedAt,
436
+ timing: result.timing,
437
+ usage: result.usage,
438
+ finishReason: result.finishReason,
439
+ attempts,
440
+ metadata: req.metadata,
441
+ promptChars: (0, util_js_1.promptChars)(req.messages),
442
+ responseChars: result.text.length,
443
+ ...(costUsd !== undefined ? { costUsd } : {}),
444
+ });
445
+ }
446
+ async recordFailure(callId, conn, req, startedAt, attempts, error) {
447
+ await this.record({
448
+ callId,
449
+ connectionId: conn.id,
450
+ provider: conn.provider,
451
+ model: req.model,
452
+ startedAt,
453
+ timing: { firstTokenMs: null, totalMs: Date.now() - startedAt },
454
+ usage: { estimated: true },
455
+ finishReason: error.kind === 'canceled' ? 'canceled' : 'error',
456
+ error: { kind: error.kind, status: error.status, message: error.message },
457
+ attempts,
458
+ metadata: req.metadata,
459
+ promptChars: (0, util_js_1.promptChars)(req.messages),
460
+ responseChars: 0,
461
+ });
462
+ }
463
+ async record(record) {
464
+ const redacted = redactRecord(record, (text) => this.redact(text));
465
+ try {
466
+ await this.opts.telemetry?.record(redacted);
467
+ await this.opts.hooks?.afterCall?.(redacted);
468
+ }
469
+ catch {
470
+ // Telemetry and afterCall hooks must not re-drive provider calls or turn
471
+ // an already-completed model response into a retry.
472
+ }
473
+ }
474
+ redact(text) {
475
+ return (this.opts.redactor ?? this.sessionRedactor).redact(this.sessionRedactor.redact(text));
476
+ }
477
+ redactedError(error) {
478
+ return new errors_js_1.AIError(this.redact(error.message), {
479
+ kind: error.kind,
480
+ status: error.status,
481
+ retryable: error.retryable,
482
+ provider: error.provider,
483
+ raw: error.raw === undefined ? undefined : this.redact(error.raw),
484
+ retryAfterMs: error.retryAfterMs,
485
+ cause: this.redactedCause(error.cause),
486
+ });
487
+ }
488
+ redactedCause(cause) {
489
+ if (cause instanceof Error) {
490
+ const redacted = new Error(this.redact(cause.message));
491
+ redacted.name = cause.name;
492
+ redacted.stack = undefined;
493
+ return redacted;
494
+ }
495
+ return cause;
496
+ }
497
+ }
498
+ exports.AIHandler = AIHandler;
499
+ function redactRecord(record, redact) {
500
+ return {
501
+ ...record,
502
+ error: record.error ? { ...record.error, message: redact(record.error.message) } : undefined,
503
+ metadata: redactMetadata(record.metadata, redact),
504
+ };
505
+ }
506
+ /**
507
+ * Redacts metadata by round-tripping through JSON. Metadata is an app-supplied
508
+ * passthrough and may contain values JSON cannot represent (BigInt, circular
509
+ * references, functions); redaction must never throw, so a non-serializable
510
+ * payload is replaced with a sentinel rather than crashing the telemetry path.
511
+ */
512
+ function redactMetadata(metadata, redact) {
513
+ if (!metadata)
514
+ return undefined;
515
+ try {
516
+ return JSON.parse(redact(JSON.stringify(metadata)));
517
+ }
518
+ catch {
519
+ return { redacted: true, note: 'metadata was not JSON-serializable' };
520
+ }
521
+ }
522
+ function trimSlash(value) {
523
+ return value.replace(/\/+$/, '');
524
+ }
525
+ /**
526
+ * Drops the resolved API key *and* neutralizes the auth headers built from it,
527
+ * so a `beforeCall` hook can inspect the endpoint but never the secret.
528
+ * `keyRef` is scrubbed too — a `{ kind: 'literal' }` ref carries the plaintext
529
+ * key, and hooks routinely log the whole object.
530
+ */
531
+ function safeResolved(resolved) {
532
+ const { apiKey: _apiKey, headers, ...rest } = resolved;
533
+ return { ...rest, ...safeKeyRef(resolved), headers: maskAuthHeaders(headers) };
534
+ }
535
+ /**
536
+ * The caller's own `Connection`, with any plaintext `keyRef` masked. Hooks get
537
+ * the connection so they can key off `id`/`provider`/`baseUrl`; they must never
538
+ * be handed the secret, since logging `info.connection` for audit is the
539
+ * obvious thing to do and would otherwise ship the key in clear text.
540
+ */
541
+ function safeConnection(conn) {
542
+ return { ...conn, ...safeKeyRef(conn) };
543
+ }
544
+ function safeKeyRef(conn) {
545
+ if (conn.keyRef?.kind !== 'literal')
546
+ return conn.keyRef === undefined ? {} : { keyRef: conn.keyRef };
547
+ return { keyRef: { kind: 'literal', value: REDACTED } };
548
+ }
549
+ const REDACTED = '[REDACTED]';
550
+ /** Header names whose value is derived from the API key by {@link applyAuth}. */
551
+ const AUTH_HEADERS = new Set(['authorization', 'x-api-key', 'x-goog-api-key', 'api-key']);
552
+ function maskAuthHeaders(headers) {
553
+ const masked = {};
554
+ for (const [name, value] of Object.entries(headers)) {
555
+ masked[name] = AUTH_HEADERS.has(name.toLowerCase()) ? REDACTED : value;
556
+ }
557
+ return masked;
558
+ }
559
+ /**
560
+ * Attach a per-call `Idempotency-Key` for providers that honor one, so a retry
561
+ * after a dropped connection can't be billed as a second generation. Only set
562
+ * where the profile declares support, and never overrides a caller-supplied
563
+ * header.
564
+ */
565
+ function withIdempotencyKey(resolved, callId) {
566
+ const profile = (0, profiles_js_1.profileFor)(resolved.provider, resolved.baseUrl);
567
+ if (!profile.quirks?.supportsIdempotencyKey)
568
+ return resolved;
569
+ if (Object.keys(resolved.headers).some((name) => name.toLowerCase() === 'idempotency-key'))
570
+ return resolved;
571
+ return { ...resolved, headers: { ...resolved.headers, 'idempotency-key': callId } };
572
+ }
573
+ async function validateWithSchema(schema, text) {
574
+ const value = (0, json_js_1.extractJson)(text);
575
+ if (value === null)
576
+ return { ok: false, message: 'no JSON found in model output' };
577
+ const result = await schema['~standard'].validate(value);
578
+ if (result.issues) {
579
+ const message = result.issues.map((issue) => issue.message).join('; ');
580
+ return { ok: false, message: message || 'validation failed' };
581
+ }
582
+ return { ok: true, value: result.value };
583
+ }
584
+ function createCallId() {
585
+ return globalThis.crypto?.randomUUID?.() ?? `call_${Date.now()}_${Math.random().toString(36).slice(2)}`;
586
+ }
@@ -0,0 +1,28 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
+ for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
+ };
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ __exportStar(require("./types.js"), exports);
18
+ __exportStar(require("./errors.js"), exports);
19
+ __exportStar(require("./transport.js"), exports);
20
+ __exportStar(require("./json.js"), exports);
21
+ __exportStar(require("./reasoning.js"), exports);
22
+ __exportStar(require("./tokens.js"), exports);
23
+ __exportStar(require("./keys.js"), exports);
24
+ __exportStar(require("./connect.js"), exports);
25
+ __exportStar(require("./redact.js"), exports);
26
+ __exportStar(require("./policy.js"), exports);
27
+ __exportStar(require("./handler.js"), exports);
28
+ __exportStar(require("./adapters/index.js"), exports);