@molecule/api-ai-anthropic 1.3.3 → 1.3.5

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
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
3
  Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
4
  Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
5
  To change this document, edit the module-level JSDoc in src/index.ts.
6
- Generated: 2026-10-01T18:20:43.990Z
6
+ Generated: 2026-10-16T00:29:26.168Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-ai-anthropic
@@ -95,20 +95,20 @@ function createProvider(config?: AnthropicConfig): AIProvider
95
95
 
96
96
  ### Constants
97
97
 
98
- #### `aiAnthropicSecretDefinitions`
98
+ #### `provider`
99
99
 
100
- Secret definitions required by the Anthropic AI bond.
100
+ The provider implementation.
101
101
 
102
102
  ```typescript
103
- const aiAnthropicSecretDefinitions: SecretDefinition[]
103
+ const provider: AIProvider
104
104
  ```
105
105
 
106
- #### `provider`
106
+ #### `aiAnthropicSecretDefinitions`
107
107
 
108
- The provider implementation.
108
+ Secret definitions required by the Anthropic AI bond.
109
109
 
110
110
  ```typescript
111
- const provider: AIProvider
111
+ const aiAnthropicSecretDefinitions: SecretDefinition[]
112
112
  ```
113
113
 
114
114
  ## Core Interface
@@ -1 +1 @@
1
- {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,UAAU,EAQX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAGrB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAqxBjD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,UAAU,CAEnE"}
1
+ {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,UAAU,EASX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAGrB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA25BjD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,UAAU,CAEnE"}
package/dist/provider.js CHANGED
@@ -7,6 +7,7 @@
7
7
  *
8
8
  * @module
9
9
  */
10
+ import { randomUUID } from 'node:crypto';
10
11
  import { getLogger } from '@molecule/api-bond';
11
12
  import { t } from '@molecule/api-i18n';
12
13
  const logger = getLogger();
@@ -179,11 +180,21 @@ class AnthropicAIProvider {
179
180
  else if (params.temperature !== undefined) {
180
181
  body.temperature = params.temperature;
181
182
  }
183
+ // Per-call correlation (see ChatParams.requestId): a header rather than the
184
+ // body's `metadata.user_id`, which is the stable per-account
185
+ // abuse-attribution value. Anthropic's `request-id` header comes back with
186
+ // the response and is recorded as the trace id.
187
+ const requestId = params.requestId ?? randomUUID();
188
+ const call = {
189
+ meta: { requestId, endpoint: `${this.baseUrl}/v1/messages` },
190
+ endUserId: params.endUserId,
191
+ };
182
192
  const headers = {
183
193
  'Content-Type': 'application/json',
184
194
  // Omitted for a keyless custom endpoint (a self-hosted / local server).
185
195
  ...(this.apiKey ? { 'x-api-key': this.apiKey } : {}),
186
196
  'anthropic-version': '2023-06-01',
197
+ 'X-Mol-Request-Id': requestId,
187
198
  };
188
199
  // Build anthropic-beta header — features that require beta flags.
189
200
  // Prompt caching is GA (no longer needs a beta flag). Interleaved thinking
@@ -211,12 +222,35 @@ class AnthropicAIProvider {
211
222
  // with the cancelled response still in `response`.
212
223
  let releasedBody = false;
213
224
  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
214
- response = await fetch(`${this.baseUrl}/v1/messages`, {
215
- method: 'POST',
216
- headers,
217
- body: JSON.stringify(body),
218
- signal,
219
- });
225
+ try {
226
+ response = await fetch(`${this.baseUrl}/v1/messages`, {
227
+ method: 'POST',
228
+ headers,
229
+ body: JSON.stringify(body),
230
+ signal,
231
+ });
232
+ }
233
+ catch (error) {
234
+ // The CALLER's own abort is theirs to see — the same exception the
235
+ // mid-stream path deliberately keeps. Everything else reaching here is
236
+ // a transport failure BEFORE any response arrived: DNS, TLS, a
237
+ // connection reset, or this bond's own 5-minute default timeout firing
238
+ // while awaiting the headers (the identical provider-owned timeout the
239
+ // mid-stream path answers with a sanitized event). A raw `TypeError:
240
+ // fetch failed` / `TimeoutError` escaping this generator carries no
241
+ // `errorKey`, so the caller's error classification never fires for that
242
+ // whole phase — answer with the sanitized event every other failure of
243
+ // this method yields.
244
+ if (params.signal?.aborted)
245
+ throw error;
246
+ logger.error('Anthropic request failed before a response arrived', { error });
247
+ yield {
248
+ type: 'error',
249
+ message: 'AI service error. Please try again.',
250
+ errorKey: 'ai.error.apiError',
251
+ };
252
+ return;
253
+ }
220
254
  releasedBody = false;
221
255
  if (response.status === 429 || response.status === 529 || response.status === 503) {
222
256
  const willRetry = attempt < MAX_RETRIES;
@@ -271,6 +305,18 @@ class AnthropicAIProvider {
271
305
  delayMs,
272
306
  });
273
307
  await new Promise((resolve) => {
308
+ // A signal that aborted BEFORE this wait began never fires another
309
+ // `abort` event — the DOM dispatches it once — so a listener
310
+ // registered now would never run and the caller would sit out the
311
+ // whole backoff (up to the 60 s Retry-After cap) before the
312
+ // `signal.aborted` check below notices. The window is real: the
313
+ // body release two statements up (`await response.body?.cancel()`)
314
+ // is an await point between the 429 arriving and this sleep. The
315
+ // liquid-d1 retry sleep carries the same pre-check.
316
+ if (signal.aborted) {
317
+ resolve();
318
+ return;
319
+ }
274
320
  const timer = setTimeout(() => {
275
321
  // The window elapsed normally: drop the abort listener. `{ once:
276
322
  // true }` only removes it when abort FIRES, so a caller signal
@@ -288,6 +334,19 @@ class AnthropicAIProvider {
288
334
  // If aborted while waiting, resolve immediately
289
335
  signal.addEventListener('abort', onAbort, { once: true });
290
336
  });
337
+ // The CALLER's own abort ends the retry and stays the caller's to
338
+ // see, exactly as it is in this method's other two phases (the
339
+ // pre-response catch rethrows it, and so does the mid-stream path:
340
+ // "rethrowing its reason is what every abort-aware consumer
341
+ // expects"). Fall through to the error path below instead and a
342
+ // CANCELLED request is answered with the DISCARDED response's
343
+ // message — "AI rate limit exceeded. Please try again shortly." — so
344
+ // a user who pressed Stop saw a rate-limit error and the caller's
345
+ // abort/retry handling never fired. Only the caller's signal is
346
+ // rethrown: this bond's own 5-minute default timeout is a deadline,
347
+ // not a cancellation, and keeps answering with the error event.
348
+ if (params.signal?.aborted)
349
+ throw params.signal.reason;
291
350
  if (signal.aborted)
292
351
  break;
293
352
  continue;
@@ -300,8 +359,24 @@ class AnthropicAIProvider {
300
359
  // throws "Body is unusable" and would replace the sanitized error event
301
360
  // with a raw TypeError that reads as a crash, not an API answer (the
302
361
  // only way a cancelled body is still `response` here is the caller's
303
- // signal aborting during the backoff sleep).
304
- const errorBody = releasedBody ? '' : await response.text();
362
+ // signal aborting during the backoff sleep). A body that dies MID-READ
363
+ // (a connection reset while the error document streams) fails the same
364
+ // way, so the read is guarded too: the status is already known, and an
365
+ // unreadable detail can only downgrade the message — it must never
366
+ // escape this generator as a raw `TypeError: terminated`, which carries
367
+ // no `errorKey` and so defeats the caller's error classification.
368
+ let errorBody = '';
369
+ if (!releasedBody) {
370
+ try {
371
+ errorBody = await response.text();
372
+ }
373
+ catch (error) {
374
+ logger.warn('Anthropic API error body could not be read', {
375
+ status: response.status,
376
+ error,
377
+ });
378
+ }
379
+ }
305
380
  let detail = `HTTP ${response.status}`;
306
381
  try {
307
382
  const parsed = JSON.parse(errorBody);
@@ -376,8 +451,13 @@ class AnthropicAIProvider {
376
451
  // HTTP-level path and the mid-stream SSE `error` path keep). The CALLER's
377
452
  // own abort is the one exception: it is the caller's act, and rethrowing
378
453
  // its reason is what every abort-aware consumer expects.
454
+ // Anthropic's own trace handle for this request, alongside the `id` of the
455
+ // message it produces (recorded by the parser).
456
+ const traceId = response.headers.get('request-id') ?? response.headers.get('x-request-id') ?? undefined;
457
+ if (traceId)
458
+ call.meta.traceId = traceId;
379
459
  try {
380
- yield* this.parseStreamingResponse(response);
460
+ yield* this.parseStreamingResponse(response, call);
381
461
  }
382
462
  catch (error) {
383
463
  if (params.signal?.aborted)
@@ -520,7 +600,7 @@ class AnthropicAIProvider {
520
600
  * @param response - The fetch Response with an SSE body stream.
521
601
  * @yields {ChatEvent} Chat events as they arrive from the SSE stream.
522
602
  */
523
- async *parseStreamingResponse(response) {
603
+ async *parseStreamingResponse(response, call) {
524
604
  const reader = response.body?.getReader();
525
605
  if (!reader) {
526
606
  yield {
@@ -552,7 +632,7 @@ class AnthropicAIProvider {
552
632
  const lines = buffer.split('\n');
553
633
  buffer = lines.pop() ?? '';
554
634
  let yielded = false;
555
- for (const event of this.processSSELines(lines, state)) {
635
+ for (const event of this.processSSELines(lines, state, call)) {
556
636
  yielded = true;
557
637
  yield event;
558
638
  // A mid-stream provider error (Anthropic sends `overloaded_error` as an
@@ -575,7 +655,7 @@ class AnthropicAIProvider {
575
655
  }
576
656
  // Flush any remaining data in the buffer after EOF
577
657
  if (buffer.trim()) {
578
- for (const event of this.processSSELines(buffer.split('\n'), state)) {
658
+ for (const event of this.processSSELines(buffer.split('\n'), state, call)) {
579
659
  yield event;
580
660
  if (event.type === 'error')
581
661
  return;
@@ -600,9 +680,24 @@ class AnthropicAIProvider {
600
680
  }
601
681
  }
602
682
  finally {
683
+ // Cancel the body whenever this generator stops before the stream is
684
+ // exhausted — a mid-stream SSE `error` event (overloaded_error) or a
685
+ // consumer that stops iterating. A live-but-unread body holds its
686
+ // connection out of the pool until GC reclaims it — the same strand the
687
+ // retry loop's body release fixes for discarded 429s. Cancel is a no-op
688
+ // on an exhausted stream, and best-effort overall: a body already
689
+ // destroyed by a caller abort or a connection reset must not turn
690
+ // cleanup into a secondary failure.
691
+ try {
692
+ await reader.cancel();
693
+ }
694
+ catch (_error) {
695
+ // Best-effort release only — the body may already be destroyed, or the
696
+ // transport may not expose cancel; the lock release below still runs.
697
+ }
603
698
  reader.releaseLock();
604
699
  }
605
- yield { type: 'done', usage: snapshotUsage(state) };
700
+ yield { type: 'done', usage: snapshotUsage(state), provider: call.meta };
606
701
  }
607
702
  /**
608
703
  * Processes an array of SSE lines from the Anthropic streaming response, yielding
@@ -612,7 +707,7 @@ class AnthropicAIProvider {
612
707
  * @param state - Mutable stream state (token counters, pending blocks).
613
708
  * @yields {ChatEvent} Chat events extracted from the SSE lines.
614
709
  */
615
- *processSSELines(lines, state) {
710
+ *processSSELines(lines, state, call) {
616
711
  for (const line of lines) {
617
712
  if (!line.startsWith('data: '))
618
713
  continue;
@@ -622,6 +717,32 @@ class AnthropicAIProvider {
622
717
  try {
623
718
  const event = JSON.parse(json);
624
719
  const eventType = event.type;
720
+ // The reply's own identity, recorded for the caller: Anthropic names the
721
+ // message it is streaming in `message_start` (and repeats it on
722
+ // `message_delta`), with the model that answered. Recorded rather than
723
+ // asserted — a proxy in front of the API may rewrite either.
724
+ const message = event.message;
725
+ if (typeof message?.id === 'string')
726
+ call.meta.responseId = message.id;
727
+ if (typeof message?.model === 'string')
728
+ call.meta.model = message.model;
729
+ // Anthropic echoes no request identity today; a proxy that does is
730
+ // checked here so another request's reply is never streamed on as ours.
731
+ const echoedRequest = typeof event.request_id === 'string'
732
+ ? event.request_id
733
+ : typeof event.requestId === 'string'
734
+ ? event.requestId
735
+ : undefined;
736
+ if (echoedRequest !== undefined && echoedRequest !== call.meta.requestId) {
737
+ logger.error('Provider echoed a different identity — this reply is not ours', {
738
+ requestId: call.meta.requestId,
739
+ echoedRequestId: echoedRequest,
740
+ responseId: call.meta.responseId,
741
+ traceId: call.meta.traceId,
742
+ });
743
+ yield { type: 'error', message: t('ai.error.apiError'), errorKey: 'ai.error.apiError' };
744
+ return;
745
+ }
625
746
  if (eventType === 'content_block_delta') {
626
747
  const delta = event.delta;
627
748
  if (delta.type === 'text_delta') {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-ai-anthropic",
3
- "version": "1.3.3",
3
+ "version": "1.3.5",
4
4
  "description": "Anthropic Claude AI provider for molecule.dev",
5
5
  "homepage": "https://www.molecule.dev/packages/api-ai-anthropic",
6
6
  "type": "module",
@@ -33,7 +33,7 @@
33
33
  "directory": "packages/api/bonds/ai/anthropic"
34
34
  },
35
35
  "devDependencies": {
36
- "@molecule/api-ai": "1.3.0",
36
+ "@molecule/api-ai": "1.3.3",
37
37
  "@molecule/api-bond": "1.0.2",
38
38
  "@types/node": "26.1.2",
39
39
  "typescript": "6.0.3",