@molecule/api-ai-anthropic 1.0.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/LICENSE ADDED
@@ -0,0 +1,115 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work.
38
+
39
+ "Derivative Works" shall mean any work, whether in Source or Object
40
+ form, that is based on (or derived from) the Work and for which the
41
+ editorial revisions, annotations, elaborations, or other modifications
42
+ represent, as a whole, an original work of authorship.
43
+
44
+ "Contribution" shall mean any work of authorship, including the
45
+ original version of the Work and any modifications or additions
46
+ to that Work, that is intentionally submitted to the Licensor for
47
+ inclusion in the Work by the copyright owner or by an individual or
48
+ Legal Entity authorized to submit on behalf of the copyright owner.
49
+
50
+ "Contributor" shall mean Licensor and any individual or Legal Entity
51
+ on behalf of whom a Contribution has been received by the Licensor and
52
+ subsequently incorporated within the Work.
53
+
54
+ 2. Grant of Copyright License. Subject to the terms and conditions of
55
+ this License, each Contributor hereby grants to You a perpetual,
56
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
57
+ copyright license to reproduce, prepare Derivative Works of,
58
+ publicly display, publicly perform, sublicense, and distribute the
59
+ Work and such Derivative Works in Source or Object form.
60
+
61
+ 3. Grant of Patent License. Subject to the terms and conditions of
62
+ this License, each Contributor hereby grants to You a perpetual,
63
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
64
+ patent license to make, have made, use, offer to sell, sell, import,
65
+ and otherwise transfer the Work.
66
+
67
+ 4. Redistribution. You may reproduce and distribute copies of the
68
+ Work or Derivative Works thereof in any medium, with or without
69
+ modifications, and in Source or Object form, provided that You
70
+ meet the following conditions:
71
+
72
+ (a) You must give any other recipients of the Work or
73
+ Derivative Works a copy of this License; and
74
+
75
+ (b) You must cause any modified files to carry prominent notices
76
+ stating that You changed the files; and
77
+
78
+ (c) You must retain, in the Source form of any Derivative Works
79
+ that You distribute, all copyright, patent, trademark, and
80
+ attribution notices from the Source form of the Work,
81
+ excluding those notices that do not pertain to any part of
82
+ the Derivative Works; and
83
+
84
+ (d) If the Work includes a "NOTICE" text file as part of its
85
+ distribution, then any Derivative Works that You distribute must
86
+ include a readable copy of the attribution notices contained
87
+ within such NOTICE file.
88
+
89
+ 5. Submission of Contributions.
90
+
91
+ 6. Trademarks. This License does not grant permission to use the trade
92
+ names, trademarks, service marks, or product names of the Licensor.
93
+
94
+ 7. Disclaimer of Warranty. Unless required by applicable law or
95
+ agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
96
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
97
+
98
+ 8. Limitation of Liability. In no event and under no legal theory shall
99
+ any Contributor be liable to You for damages.
100
+
101
+ 9. Accepting Warranty or Additional Liability.
102
+
103
+ Copyright 2026 Molecule Dev, Inc.
104
+
105
+ Licensed under the Apache License, Version 2.0 (the "License");
106
+ you may not use this file except in compliance with the License.
107
+ You may obtain a copy of the License at
108
+
109
+ http://www.apache.org/licenses/LICENSE-2.0
110
+
111
+ Unless required by applicable law or agreed to in writing, software
112
+ distributed under the License is distributed on an "AS IS" BASIS,
113
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
114
+ See the License for the specific language governing permissions and
115
+ limitations under the License.
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=browser-guard.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Browser guard — `@molecule/api-ai-anthropic` is SERVER-ONLY.
3
+ *
4
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
5
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
6
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
7
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
8
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
9
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
10
+ */
11
+ const g = globalThis;
12
+ if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
13
+ throw new Error('@molecule/api-ai-anthropic is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
14
+ 'from server code (a server route/function or your API), or dynamic-import it inside ' +
15
+ 'the server handler — never from components or shared client modules, and never ' +
16
+ 'polyfill Buffer/process to silence this.');
17
+ }
18
+ export {};
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Anthropic ai-anthropic provider for molecule.dev.
3
+ *
4
+ * @remarks
5
+ * Bond this as an AI provider (see `@molecule/api-ai` for the `chat()` streaming loop and the
6
+ * key-server-side / never-blindly-trust-model-output rules). Config: `ANTHROPIC_API_KEY`
7
+ * (SERVER-side only — never shipped to the browser) plus an optional default model id. Drive it
8
+ * through the core `chat()` / `requireProvider()`, NOT the Anthropic SDK directly, so the app
9
+ * stays provider-agnostic and can swap models/providers by changing only the bond.
10
+ *
11
+ * **Missing `ANTHROPIC_API_KEY` fails fast**: the provider throws naming the exact env var on
12
+ * first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
13
+ * not at bond/module-load time) — it never silently sends an empty key and surfaces only as a
14
+ * generic 401 later.
15
+ *
16
+ * **Error message disambiguation**: a non-OK response yields a sanitized `error` ChatEvent
17
+ * (never a throw). A permanently-invalid request — a plain 400 that ISN'T a context-length
18
+ * error (bad param, malformed tool schema) — gets its own non-retryable message ("AI request
19
+ * was invalid — check the model and request parameters.") distinct from the generic "AI service
20
+ * error. Please try again." used for retryable failures; don't retry a plain 400 as if it might
21
+ * succeed on a second attempt.
22
+ *
23
+ * @module
24
+ */
25
+ export * from './browser-guard.js';
26
+ export * from './provider.js';
27
+ export * from './secrets.js';
28
+ export * from './types.js';
29
+ import type { AIProvider } from '@molecule/api-ai';
30
+ /**
31
+ * The provider implementation.
32
+ */
33
+ export declare const provider: AIProvider;
34
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAMlD;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,UAUrB,CAAA"}
package/dist/index.js ADDED
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Anthropic ai-anthropic provider for molecule.dev.
3
+ *
4
+ * @remarks
5
+ * Bond this as an AI provider (see `@molecule/api-ai` for the `chat()` streaming loop and the
6
+ * key-server-side / never-blindly-trust-model-output rules). Config: `ANTHROPIC_API_KEY`
7
+ * (SERVER-side only — never shipped to the browser) plus an optional default model id. Drive it
8
+ * through the core `chat()` / `requireProvider()`, NOT the Anthropic SDK directly, so the app
9
+ * stays provider-agnostic and can swap models/providers by changing only the bond.
10
+ *
11
+ * **Missing `ANTHROPIC_API_KEY` fails fast**: the provider throws naming the exact env var on
12
+ * first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
13
+ * not at bond/module-load time) — it never silently sends an empty key and surfaces only as a
14
+ * generic 401 later.
15
+ *
16
+ * **Error message disambiguation**: a non-OK response yields a sanitized `error` ChatEvent
17
+ * (never a throw). A permanently-invalid request — a plain 400 that ISN'T a context-length
18
+ * error (bad param, malformed tool schema) — gets its own non-retryable message ("AI request
19
+ * was invalid — check the model and request parameters.") distinct from the generic "AI service
20
+ * error. Please try again." used for retryable failures; don't retry a plain 400 as if it might
21
+ * succeed on a second attempt.
22
+ *
23
+ * @module
24
+ */
25
+ export * from './browser-guard.js';
26
+ export * from './provider.js';
27
+ export * from './secrets.js';
28
+ export * from './types.js';
29
+ import { createProvider } from './provider.js';
30
+ /** Lazily-initialized provider singleton. Defers creation until first use so that env vars / secrets are resolved. */
31
+ let _provider = null;
32
+ /**
33
+ * The provider implementation.
34
+ */
35
+ export const provider = new Proxy({}, {
36
+ get(_, prop, receiver) {
37
+ if (!_provider)
38
+ _provider = createProvider();
39
+ return Reflect.get(_provider, prop, receiver);
40
+ },
41
+ // set trap: methods run with `this` bound to the proxy — without it, instance-state writes land on the dummy target and are lost (see api-push-notifications-web-push)
42
+ set(_, prop, value) {
43
+ if (!_provider)
44
+ _provider = createProvider();
45
+ return Reflect.set(_provider, prop, value);
46
+ },
47
+ });
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Anthropic Claude implementation of AIProvider.
3
+ *
4
+ * Talks to the Anthropic Messages API (`POST {baseUrl}/v1/messages`) directly
5
+ * over `fetch` — no `@anthropic-ai/sdk` dependency — parsing the SSE stream
6
+ * into `ChatEvent`s (text, thinking, tool use, usage snapshots, done).
7
+ *
8
+ * @module
9
+ */
10
+ import type { AIProvider } from '@molecule/api-ai';
11
+ import './secrets.js';
12
+ import type { AnthropicConfig } from './types.js';
13
+ /**
14
+ * Creates an Anthropic Claude AI provider instance.
15
+ *
16
+ * @param config - Anthropic-specific configuration (API key, model, max tokens, base URL).
17
+ * @returns An `AIProvider` backed by the Anthropic Messages API.
18
+ */
19
+ export declare function createProvider(config?: AnthropicConfig): AIProvider;
20
+ //# sourceMappingURL=provider.d.ts.map
@@ -0,0 +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;AAErB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA6pBjD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,UAAU,CAEnE"}
@@ -0,0 +1,651 @@
1
+ /**
2
+ * Anthropic Claude implementation of AIProvider.
3
+ *
4
+ * Talks to the Anthropic Messages API (`POST {baseUrl}/v1/messages`) directly
5
+ * over `fetch` — no `@anthropic-ai/sdk` dependency — parsing the SSE stream
6
+ * into `ChatEvent`s (text, thinking, tool use, usage snapshots, done).
7
+ *
8
+ * @module
9
+ */
10
+ import { getLogger } from '@molecule/api-bond';
11
+ import { t } from '@molecule/api-i18n';
12
+ const logger = getLogger();
13
+ // Side-effect import: registers this bond's secret definitions so the
14
+ // runtime registry is populated even when provider.js is imported directly
15
+ // (not through the package barrel).
16
+ import './secrets.js';
17
+ /**
18
+ * Builds a `TokenUsage` from the stream state's provider-reported counters —
19
+ * shared by the mid-stream `usage` snapshots and the terminal `done` event so
20
+ * the two can never diverge.
21
+ *
22
+ * @param state - The streaming parser state.
23
+ * @returns The usage counters accumulated so far.
24
+ */
25
+ function snapshotUsage(state) {
26
+ return {
27
+ inputTokens: state.inputTokens,
28
+ outputTokens: state.outputTokens,
29
+ ...(state.cacheCreationInputTokens
30
+ ? { cacheCreationInputTokens: state.cacheCreationInputTokens }
31
+ : {}),
32
+ ...(state.cacheReadInputTokens ? { cacheReadInputTokens: state.cacheReadInputTokens } : {}),
33
+ ...(state.speed ? { speed: state.speed } : {}),
34
+ };
35
+ }
36
+ /**
37
+ * Narrows the provider-reported speed tier to the TokenUsage union.
38
+ *
39
+ * The wire field varies: fast-mode docs name `usage.speed`, while the live API
40
+ * reports `usage.service_tier` ("standard" observed on streaming
41
+ * `message_start`, verified 2026-07-31) — read both, `speed` first.
42
+ *
43
+ * @param usage - The raw Anthropic usage object.
44
+ * @returns The narrowed speed, or null when absent/unrecognized.
45
+ */
46
+ function parseSpeed(usage) {
47
+ const raw = usage?.speed ?? usage?.service_tier;
48
+ return raw === 'fast' || raw === 'standard' ? raw : null;
49
+ }
50
+ /**
51
+ * Anthropic Claude AI provider that implements the `AIProvider` interface
52
+ * using Anthropic's Messages API with support for streaming, tool use,
53
+ * and system prompts.
54
+ */
55
+ class AnthropicAIProvider {
56
+ name = 'anthropic';
57
+ apiKey;
58
+ defaultModel;
59
+ maxTokens;
60
+ baseUrl;
61
+ onRateLimit;
62
+ constructor(config = {}) {
63
+ this.apiKey = config.apiKey ?? process.env.ANTHROPIC_API_KEY ?? '';
64
+ this.defaultModel = config.defaultModel ?? 'claude-opus-5';
65
+ this.maxTokens = config.maxTokens ?? 4096;
66
+ this.baseUrl = config.baseUrl ?? process.env.ANTHROPIC_BASE_URL ?? 'https://api.anthropic.com';
67
+ this.onRateLimit = config.onRateLimit;
68
+ // Fail fast with an actionable local error rather than a cryptic 401 on the
69
+ // first request. The default `provider` export constructs lazily on first
70
+ // use (see index.ts), so this surfaces the moment the provider is actually
71
+ // used, not at bond/module-load time.
72
+ if (!this.apiKey) {
73
+ throw new Error('ANTHROPIC_API_KEY is not set. Add it to your environment to use the Anthropic Claude AI provider.');
74
+ }
75
+ }
76
+ /**
77
+ * Sends a chat request and yields streamed events (text chunks, tool use, done/error).
78
+ *
79
+ * @param params - Chat parameters including messages, model, system prompt, and tools.
80
+ * @yields {ChatEvent} Chat events including text chunks, tool use requests, done signals, and errors.
81
+ */
82
+ async *chat(params) {
83
+ const model = params.model ?? this.defaultModel;
84
+ const maxTokens = params.maxTokens ?? this.maxTokens;
85
+ const formattedMessages = this.formatMessages(params.messages);
86
+ const body = {
87
+ model,
88
+ max_tokens: maxTokens,
89
+ messages: formattedMessages,
90
+ };
91
+ // Enable automatic prompt caching at the request level. The API places
92
+ // the cache breakpoint on the last cacheable block and advances it as the
93
+ // conversation grows — no manual breakpoint management needed for messages.
94
+ // Explicit breakpoints on system + tools below provide additional stable
95
+ // cache points (tools/system rarely change, so they cache independently).
96
+ if (params.cacheControl) {
97
+ body.cache_control = params.cacheControl;
98
+ }
99
+ if (params.system) {
100
+ if (params.cacheControl) {
101
+ body.system = [{ type: 'text', text: params.system, cache_control: params.cacheControl }];
102
+ }
103
+ else {
104
+ body.system = params.system;
105
+ }
106
+ }
107
+ // Merge custom tools (with input_schema) and server tools (provider-native, e.g. web_search)
108
+ const customTools = params.tools?.length ? this.formatTools(params.tools) : [];
109
+ const serverTools = (params.serverTools ?? []).map((st) => ({ ...st }));
110
+ const allTools = [...customTools, ...serverTools];
111
+ if (allTools.length > 0) {
112
+ if (params.cacheControl) {
113
+ // Place cache breakpoint on the last tool so tools + system are cached together
114
+ allTools[allTools.length - 1] = {
115
+ ...allTools[allTools.length - 1],
116
+ cache_control: params.cacheControl,
117
+ };
118
+ }
119
+ body.tools = allTools;
120
+ if (params.toolChoice === 'required') {
121
+ body.tool_choice = { type: 'any' };
122
+ }
123
+ else if (typeof params.toolChoice === 'object' && params.toolChoice?.type === 'tool') {
124
+ body.tool_choice = { type: 'tool', name: params.toolChoice.name };
125
+ }
126
+ }
127
+ if (params.stream !== false)
128
+ body.stream = true;
129
+ // Abuse attribution (see ChatParams.endUserId). Anthropic scopes enforcement
130
+ // by `metadata.user_id`, so sending it means an abusive tenant can be actioned
131
+ // individually instead of the organization's key — which serves every tenant.
132
+ // The value is the caller's opaque hash; this bond never derives or logs it.
133
+ if (params.endUserId)
134
+ body.metadata = { user_id: params.endUserId };
135
+ // Fast mode (research preview): `speed: "fast"` as a top-level body param +
136
+ // the fast-mode beta flag (added to the anthropic-beta header below). The
137
+ // response's `usage.speed` reports what actually ran and is passed through
138
+ // to TokenUsage.speed so metering prices the served tier. NOTE: switching
139
+ // speed invalidates the prompt cache, so callers should keep speed stable
140
+ // within a conversation.
141
+ if (params.speed === 'fast')
142
+ body.speed = 'fast';
143
+ // Thinking requires temperature=1 (default); skip any explicit temperature override.
144
+ //
145
+ // Two thinking paths, keyed off the caller-resolved native effort value:
146
+ // - `effort` present (Fable 5, Opus 4.8/4.6, Sonnet 5 / 4.6, per the model
147
+ // catalog): adaptive thinking + output_config.effort. Manual
148
+ // `budget_tokens` is REJECTED with a 400 on Fable 5 / Opus 4.8 / Sonnet 5
149
+ // and deprecated on the 4.6 family, so this path is load-bearing.
150
+ // Adaptive thinking auto-enables interleaved thinking — no beta header.
151
+ // - `effort` absent (Claude Haiku 4.5 and older models): legacy manual
152
+ // extended thinking with `budget_tokens` + the interleaved-thinking beta.
153
+ const nativeEffort = params.thinking?.effort;
154
+ if (params.thinking && nativeEffort) {
155
+ body.thinking = { type: 'adaptive' };
156
+ body.output_config = { effort: nativeEffort };
157
+ }
158
+ else if (params.thinking) {
159
+ body.thinking = { type: 'enabled', budget_tokens: params.thinking.budgetTokens };
160
+ }
161
+ else if (params.temperature !== undefined) {
162
+ body.temperature = params.temperature;
163
+ }
164
+ const headers = {
165
+ 'Content-Type': 'application/json',
166
+ 'x-api-key': this.apiKey,
167
+ 'anthropic-version': '2023-06-01',
168
+ };
169
+ // Build anthropic-beta header — features that require beta flags.
170
+ // Prompt caching is GA (no longer needs a beta flag). Interleaved thinking
171
+ // needs its beta flag only on the legacy budget_tokens path — adaptive
172
+ // thinking interleaves automatically.
173
+ const betaFeatures = [];
174
+ if (params.thinking && !nativeEffort)
175
+ betaFeatures.push('interleaved-thinking-2025-05-14');
176
+ if (params.speed === 'fast')
177
+ betaFeatures.push('fast-mode-2026-02-01');
178
+ if (betaFeatures.length > 0) {
179
+ headers['anthropic-beta'] = betaFeatures.join(',');
180
+ }
181
+ // Default timeout of 5 minutes to prevent hung connections.
182
+ // Caller can override via params.signal for custom timeouts.
183
+ const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
184
+ const signal = params.signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
185
+ // Retry with exponential backoff for rate limits (429) and overloaded (529/503)
186
+ const MAX_RETRIES = 3;
187
+ let response = null;
188
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
189
+ response = await fetch(`${this.baseUrl}/v1/messages`, {
190
+ method: 'POST',
191
+ headers,
192
+ body: JSON.stringify(body),
193
+ signal,
194
+ });
195
+ if (response.status === 429 || response.status === 529 || response.status === 503) {
196
+ const willRetry = attempt < MAX_RETRIES;
197
+ // Use Retry-After header if provided, otherwise exponential backoff.
198
+ // Retry-After is equally-valid as delta-seconds ('30') or an
199
+ // HTTP-date ('Wed, 21 Oct ... GMT'); parseInt on the date form
200
+ // yields NaN, which previously produced setTimeout(resolve, NaN) —
201
+ // fires ~immediately, degrading the backoff to rapid-fire retries
202
+ // against an already rate-limiting API. Guard the parse and fall
203
+ // back to exponential backoff for any non-finite/negative value.
204
+ const retryAfter = response.headers.get('retry-after');
205
+ const parsedRetryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : NaN;
206
+ const hasRetryAfter = Number.isFinite(parsedRetryAfterSeconds) && parsedRetryAfterSeconds >= 0;
207
+ // Additive jitter (<500ms): concurrent callers rejected together must
208
+ // not sleep identical delays and re-arrive as the same burst.
209
+ const delayMs = willRetry
210
+ ? (hasRetryAfter
211
+ ? Math.min(parsedRetryAfterSeconds * 1000, 60_000)
212
+ : Math.min(1000 * 2 ** attempt, 30_000)) + Math.floor(Math.random() * 500)
213
+ : 0;
214
+ try {
215
+ this.onRateLimit?.({
216
+ provider: this.name,
217
+ model,
218
+ status: response.status,
219
+ attempt: attempt + 1,
220
+ willRetry,
221
+ retryInMs: delayMs,
222
+ ...(hasRetryAfter ? { retryAfterSeconds: parsedRetryAfterSeconds } : {}),
223
+ });
224
+ }
225
+ catch (error) {
226
+ // Host-app telemetry; its failure must never break the request.
227
+ logger.warn('onRateLimit callback threw', { error });
228
+ }
229
+ if (willRetry) {
230
+ logger.warn('Anthropic API rate limited, retrying', {
231
+ status: response.status,
232
+ attempt: attempt + 1,
233
+ delayMs,
234
+ });
235
+ await new Promise((resolve) => {
236
+ const timer = setTimeout(resolve, delayMs);
237
+ // If aborted while waiting, resolve immediately
238
+ signal.addEventListener('abort', () => {
239
+ clearTimeout(timer);
240
+ resolve();
241
+ }, { once: true });
242
+ });
243
+ if (signal.aborted)
244
+ break;
245
+ continue;
246
+ }
247
+ }
248
+ break;
249
+ }
250
+ if (!response.ok) {
251
+ const errorBody = await response.text();
252
+ let detail = `HTTP ${response.status}`;
253
+ try {
254
+ const parsed = JSON.parse(errorBody);
255
+ if (parsed.error?.message)
256
+ detail = parsed.error.message;
257
+ }
258
+ catch (_error) {
259
+ // Best-effort: if the error body isn't valid JSON, use it as plain text
260
+ if (errorBody.length > 0 && errorBody.length < 200)
261
+ detail = errorBody;
262
+ }
263
+ // Log full detail server-side for debugging
264
+ logger.error('Anthropic API error', { status: response.status, detail });
265
+ // Return sanitized but actionable error to client
266
+ const clientMessage = response.status === 429
267
+ ? 'AI rate limit exceeded. Please try again shortly.'
268
+ : response.status === 401
269
+ ? 'AI service configuration error.'
270
+ : response.status === 400 &&
271
+ /prompt is too long|too many tokens|token.*limit|context.*length/i.test(detail)
272
+ ? "Conversation too long for the model's context window. Use /compact to free space, or start a new conversation."
273
+ : response.status === 400
274
+ ? // A permanently-invalid request (bad param, e.g. temperature on a
275
+ // model that rejects sampling params, a malformed tool schema)
276
+ // is NOT retryable — distinguish it from the generic fallback so
277
+ // a caller (or an executor retrying blindly) doesn't loop on a
278
+ // request that can never succeed.
279
+ 'AI request was invalid — check the model and request parameters.'
280
+ : response.status === 529 || response.status === 503
281
+ ? 'AI service is temporarily overloaded. Please try again in a moment.'
282
+ : 'AI service error. Please try again.';
283
+ yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' };
284
+ return;
285
+ }
286
+ if (params.stream === false) {
287
+ // Non-streaming: parse full response
288
+ const data = (await response.json());
289
+ yield* this.parseNonStreamingResponse(data);
290
+ return;
291
+ }
292
+ // Streaming: parse SSE events
293
+ yield* this.parseStreamingResponse(response);
294
+ }
295
+ /**
296
+ * Converts internal `ChatMessage` objects to the Anthropic API message format,
297
+ * filtering out system messages (handled separately via the `system` parameter).
298
+ * Maps generic `ContentBlock` attachment types to Anthropic's native format.
299
+ * @param messages - The chat messages to format.
300
+ * @returns The formatted messages array for the Anthropic API.
301
+ */
302
+ formatMessages(messages) {
303
+ return messages
304
+ .filter((m) => m.role !== 'system')
305
+ .map((m) => ({
306
+ role: m.role,
307
+ content: typeof m.content === 'string'
308
+ ? m.content
309
+ : m.content.map((block) => this.formatBlock(block)),
310
+ }));
311
+ }
312
+ /**
313
+ * Maps a generic `ContentBlock` to the Anthropic API content block format.
314
+ * @param block - The content block to format.
315
+ * @returns The Anthropic-native block representation.
316
+ */
317
+ formatBlock(block) {
318
+ switch (block.type) {
319
+ case 'text':
320
+ return { type: 'text', text: block.text };
321
+ case 'image':
322
+ return {
323
+ type: 'image',
324
+ source: { type: 'base64', media_type: block.mediaType, data: block.data },
325
+ };
326
+ case 'document':
327
+ return {
328
+ type: 'document',
329
+ source: { type: 'base64', media_type: block.mediaType, data: block.data },
330
+ };
331
+ case 'audio':
332
+ return {
333
+ type: 'text',
334
+ text: `[Audio attachment (${block.mediaType}) — not supported by this provider]`,
335
+ };
336
+ case 'video':
337
+ return {
338
+ type: 'text',
339
+ text: `[Video attachment (${block.mediaType}) — not supported by this provider]`,
340
+ };
341
+ case 'tool_use':
342
+ return { type: 'tool_use', id: block.id, name: block.name, input: block.input };
343
+ case 'tool_result':
344
+ return { type: 'tool_result', tool_use_id: block.tool_use_id, content: block.content };
345
+ default:
346
+ return block;
347
+ }
348
+ }
349
+ /**
350
+ * Converts internal `AITool` definitions to the Anthropic API tool format
351
+ * with `name`, `description`, and `input_schema` fields.
352
+ * @param tools - The AI tool definitions to format.
353
+ * @returns The formatted tools array for the Anthropic API.
354
+ */
355
+ formatTools(tools) {
356
+ return tools.map((t) => ({
357
+ name: t.name,
358
+ description: t.description,
359
+ input_schema: t.parameters,
360
+ }));
361
+ }
362
+ /**
363
+ * Parses a non-streaming Anthropic API response into `ChatEvent` objects.
364
+ * @param data - The raw API response data to parse.
365
+ * @yields {ChatEvent} Chat events parsed from the response content blocks and usage data.
366
+ */
367
+ *parseNonStreamingResponse(data) {
368
+ const content = data.content;
369
+ if (content) {
370
+ for (const block of content) {
371
+ if (block.type === 'text') {
372
+ yield { type: 'text', content: block.text };
373
+ }
374
+ else if (block.type === 'tool_use') {
375
+ yield {
376
+ type: 'tool_use',
377
+ id: block.id,
378
+ name: block.name,
379
+ input: block.input,
380
+ };
381
+ }
382
+ else if (block.type === 'thinking') {
383
+ // The streaming path yields 'thinking' events via thinking_delta;
384
+ // a non-streaming response (params.stream === false) carries the
385
+ // same content as a single 'thinking' block that was previously
386
+ // silently dropped here — callers using stream:false with thinking
387
+ // enabled lost the thinking output with no signal it ever existed.
388
+ yield { type: 'thinking', content: block.thinking };
389
+ }
390
+ }
391
+ }
392
+ const usage = data.usage;
393
+ const servedSpeed = parseSpeed(usage);
394
+ yield {
395
+ type: 'done',
396
+ usage: {
397
+ inputTokens: usage?.input_tokens ?? 0,
398
+ outputTokens: usage?.output_tokens ?? 0,
399
+ ...(usage?.cache_creation_input_tokens
400
+ ? { cacheCreationInputTokens: usage.cache_creation_input_tokens }
401
+ : {}),
402
+ ...(usage?.cache_read_input_tokens
403
+ ? { cacheReadInputTokens: usage.cache_read_input_tokens }
404
+ : {}),
405
+ ...(servedSpeed ? { speed: servedSpeed } : {}),
406
+ },
407
+ };
408
+ }
409
+ /**
410
+ * Parses a streaming SSE response from the Anthropic API, yielding
411
+ * `ChatEvent` objects as they arrive (text deltas, tool use, done with usage).
412
+ * @param response - The fetch Response with an SSE body stream.
413
+ * @yields {ChatEvent} Chat events as they arrive from the SSE stream.
414
+ */
415
+ async *parseStreamingResponse(response) {
416
+ const reader = response.body?.getReader();
417
+ if (!reader) {
418
+ yield {
419
+ type: 'error',
420
+ message: t('ai.error.noResponseBody'),
421
+ errorKey: 'ai.error.noResponseBody',
422
+ };
423
+ return;
424
+ }
425
+ const decoder = new TextDecoder();
426
+ let buffer = '';
427
+ const state = {
428
+ inputTokens: 0,
429
+ outputTokens: 0,
430
+ cacheCreationInputTokens: 0,
431
+ cacheReadInputTokens: 0,
432
+ speed: null,
433
+ pendingTool: null,
434
+ pendingThinking: null,
435
+ };
436
+ try {
437
+ while (true) {
438
+ const { done, value } = await reader.read();
439
+ if (done)
440
+ break;
441
+ buffer += decoder.decode(value, { stream: true });
442
+ const lines = buffer.split('\n');
443
+ buffer = lines.pop() ?? '';
444
+ let yielded = false;
445
+ for (const event of this.processSSELines(lines, state)) {
446
+ yielded = true;
447
+ yield event;
448
+ // A mid-stream provider error (Anthropic sends `overloaded_error` as an
449
+ // SSE `error` event AFTER a 200 OK during high load) means the turn was
450
+ // truncated. Stop here and do NOT fall through to the trailing `done` —
451
+ // a `done` reports the truncated turn to the consumer as a successful
452
+ // completion, so the caller's overload/retry recovery never fires.
453
+ // Mirrors the HTTP-level error path (yield error; return).
454
+ if (event.type === 'error')
455
+ return;
456
+ }
457
+ // We received data from the API but it produced no ChatEvent — e.g. a
458
+ // `ping` or an empty/keepalive event. (Tool-input chunks now yield a
459
+ // `tool_input_delta` instead of falling through here, so a large
460
+ // streaming tool input keeps the UI live rather than going silent.) The
461
+ // connection is still alive, so signal liveness to reset the consumer's
462
+ // inter-event stream timeout, which would otherwise false-fire.
463
+ if (!yielded)
464
+ yield { type: 'keep_alive' };
465
+ }
466
+ // Flush any remaining data in the buffer after EOF
467
+ if (buffer.trim()) {
468
+ for (const event of this.processSSELines(buffer.split('\n'), state)) {
469
+ yield event;
470
+ if (event.type === 'error')
471
+ return;
472
+ }
473
+ }
474
+ // Emit any tool call still pending after stream ends (safety net for missing content_block_stop)
475
+ if (state.pendingTool) {
476
+ let input = {};
477
+ try {
478
+ input = JSON.parse(state.pendingTool.inputJson);
479
+ }
480
+ catch (_error) {
481
+ // Best-effort: malformed JSON from a truncated stream yields an empty input object
482
+ }
483
+ yield {
484
+ type: 'tool_use',
485
+ id: state.pendingTool.id,
486
+ name: state.pendingTool.name,
487
+ input,
488
+ };
489
+ state.pendingTool = null;
490
+ }
491
+ }
492
+ finally {
493
+ reader.releaseLock();
494
+ }
495
+ yield { type: 'done', usage: snapshotUsage(state) };
496
+ }
497
+ /**
498
+ * Processes an array of SSE lines from the Anthropic streaming response, yielding
499
+ * ChatEvent objects for text deltas, thinking, tool use, and usage updates.
500
+ *
501
+ * @param lines - Raw SSE lines to process.
502
+ * @param state - Mutable stream state (token counters, pending blocks).
503
+ * @yields {ChatEvent} Chat events extracted from the SSE lines.
504
+ */
505
+ *processSSELines(lines, state) {
506
+ for (const line of lines) {
507
+ if (!line.startsWith('data: '))
508
+ continue;
509
+ const json = line.slice(6).trim();
510
+ if (json === '[DONE]')
511
+ continue;
512
+ try {
513
+ const event = JSON.parse(json);
514
+ const eventType = event.type;
515
+ if (eventType === 'content_block_delta') {
516
+ const delta = event.delta;
517
+ if (delta.type === 'text_delta') {
518
+ yield { type: 'text', content: delta.text };
519
+ }
520
+ else if (delta.type === 'input_json_delta' && state.pendingTool) {
521
+ const chunk = delta.partial_json;
522
+ state.pendingTool.inputJson += chunk;
523
+ // Emit the chunk's char count as real progress (re-arms the
524
+ // consumer's stream timeout and drives the live token counter)
525
+ // instead of letting it fall through to a silent keep_alive — the
526
+ // root cause of the dead loading indicator while a large tool input
527
+ // streams in. Just the count, not the content (the consumer
528
+ // coalesces these and only needs the magnitude).
529
+ yield {
530
+ type: 'tool_input_delta',
531
+ id: state.pendingTool.id,
532
+ chars: chunk.length,
533
+ // Raw partial-JSON chunk — server-side only; the handler accumulates
534
+ // it to extract short display fields (e.g. file path) for the live
535
+ // tool-card label before the args finish streaming.
536
+ text: chunk,
537
+ };
538
+ }
539
+ else if (delta.type === 'thinking_delta' && state.pendingThinking !== null) {
540
+ const chunk = delta.thinking;
541
+ state.pendingThinking += chunk;
542
+ yield { type: 'thinking', content: chunk };
543
+ }
544
+ }
545
+ else if (eventType === 'content_block_start') {
546
+ const block = event.content_block;
547
+ if (block.type === 'tool_use') {
548
+ state.pendingTool = {
549
+ id: block.id,
550
+ name: block.name,
551
+ inputJson: '',
552
+ };
553
+ // Surface the tool start immediately (id + name) so the client shows
554
+ // activity before the full input finishes streaming.
555
+ yield { type: 'tool_use_start', id: block.id, name: block.name };
556
+ }
557
+ else if (block.type === 'thinking') {
558
+ state.pendingThinking = '';
559
+ }
560
+ }
561
+ else if (eventType === 'content_block_stop') {
562
+ // Emit completed tool_use with accumulated input
563
+ if (state.pendingTool) {
564
+ let input = {};
565
+ try {
566
+ input = JSON.parse(state.pendingTool.inputJson);
567
+ }
568
+ catch (_error) {
569
+ // Best-effort: malformed accumulated JSON falls back to empty input object
570
+ }
571
+ yield {
572
+ type: 'tool_use',
573
+ id: state.pendingTool.id,
574
+ name: state.pendingTool.name,
575
+ input,
576
+ };
577
+ state.pendingTool = null;
578
+ }
579
+ // Thinking block complete — deltas were already yielded incrementally
580
+ if (state.pendingThinking !== null) {
581
+ state.pendingThinking = null;
582
+ }
583
+ }
584
+ else if (eventType === 'message_delta') {
585
+ const usage = event.usage;
586
+ if (usage?.output_tokens) {
587
+ state.outputTokens = usage.output_tokens;
588
+ // Metering snapshot (latest wins): if the stream is cut after this
589
+ // point, the consumer books these provider-reported counts instead
590
+ // of dropping the turn (see the ChatEvent 'usage' contract).
591
+ yield { type: 'usage', usage: snapshotUsage(state) };
592
+ }
593
+ }
594
+ else if (eventType === 'message_start') {
595
+ const message = event.message;
596
+ const usage = message?.usage;
597
+ const servedSpeed = parseSpeed(usage);
598
+ if (servedSpeed)
599
+ state.speed = servedSpeed;
600
+ if (usage?.input_tokens)
601
+ state.inputTokens = usage.input_tokens;
602
+ if (usage?.cache_creation_input_tokens)
603
+ state.cacheCreationInputTokens = usage.cache_creation_input_tokens;
604
+ if (usage?.cache_read_input_tokens)
605
+ state.cacheReadInputTokens = usage.cache_read_input_tokens;
606
+ // message_start carries the FULL input-side counts (fresh + cache read
607
+ // + cache write) before any output streams — for long-context agentic
608
+ // turns this is the bulk of the turn's cost. Snapshot it immediately so
609
+ // an abort mid-generation still meters the input the provider bills.
610
+ if (usage) {
611
+ yield { type: 'usage', usage: snapshotUsage(state) };
612
+ }
613
+ }
614
+ else if (eventType === 'error') {
615
+ // Anthropic can emit an `error` SSE event MID-STREAM (after a 200 OK) —
616
+ // most commonly `overloaded_error` during high load, the streaming
617
+ // analogue of an HTTP 529. It matches no content branch above, so
618
+ // without this it was silently dropped and the stream fell through to a
619
+ // misleading `done` — a truncated turn reported as a successful
620
+ // completion. Surface it as a real `error` event (mapped to the same
621
+ // actionable messages as the HTTP-level path) so the consumer's overload
622
+ // handling fires instead. Also satisfies the no-silent-swallow rule.
623
+ const streamError = event.error;
624
+ const errorType = streamError?.type ?? '';
625
+ logger.error('Anthropic streaming error event', {
626
+ errorType,
627
+ message: streamError?.message,
628
+ });
629
+ const clientMessage = errorType === 'overloaded_error'
630
+ ? 'AI service is temporarily overloaded. Please try again in a moment.'
631
+ : errorType === 'rate_limit_error'
632
+ ? 'AI rate limit exceeded. Please try again shortly.'
633
+ : 'AI service error. Please try again.';
634
+ yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' };
635
+ }
636
+ }
637
+ catch (error) {
638
+ logger.debug('Skipping malformed SSE JSON line', { json, error });
639
+ }
640
+ }
641
+ }
642
+ }
643
+ /**
644
+ * Creates an Anthropic Claude AI provider instance.
645
+ *
646
+ * @param config - Anthropic-specific configuration (API key, model, max tokens, base URL).
647
+ * @returns An `AIProvider` backed by the Anthropic Messages API.
648
+ */
649
+ export function createProvider(config) {
650
+ return new AnthropicAIProvider(config);
651
+ }
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Anthropic secret definitions — self-registered at import time so the
3
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
4
+ * configuration reports and actionable "not configured" errors.
5
+ *
6
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
7
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
8
+ * packages sharing a key register byte-identical definitions and
9
+ * registration order never matters.
10
+ *
11
+ * @module
12
+ */
13
+ import type { SecretDefinition } from '@molecule/api-secrets';
14
+ /** Secret definitions required by the Anthropic AI bond. */
15
+ export declare const aiAnthropicSecretDefinitions: SecretDefinition[];
16
+ //# sourceMappingURL=secrets.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D,4DAA4D;AAC5D,eAAO,MAAM,4BAA4B,EAAE,gBAAgB,EAS1D,CAAA"}
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Anthropic secret definitions — self-registered at import time so the
3
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
4
+ * configuration reports and actionable "not configured" errors.
5
+ *
6
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
7
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
8
+ * packages sharing a key register byte-identical definitions and
9
+ * registration order never matters.
10
+ *
11
+ * @module
12
+ */
13
+ import { registerSecrets } from '@molecule/api-secrets';
14
+ /** Secret definitions required by the Anthropic AI bond. */
15
+ export const aiAnthropicSecretDefinitions = [
16
+ {
17
+ key: 'ANTHROPIC_API_KEY',
18
+ description: 'Anthropic API key — Create a key in the Anthropic Console under Settings → API keys.',
19
+ helpUrl: 'https://console.anthropic.com/settings/keys',
20
+ required: true,
21
+ example: 'sk-ant-api03-...',
22
+ },
23
+ ];
24
+ registerSecrets(aiAnthropicSecretDefinitions);
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Anthropic Claude AI provider configuration.
3
+ *
4
+ * @module
5
+ */
6
+ import type { AiRateLimitCallback } from '@molecule/api-ai';
7
+ /**
8
+ * Configuration for anthropic.
9
+ */
10
+ export interface AnthropicConfig {
11
+ /** API key. Defaults to ANTHROPIC_API_KEY env var. */
12
+ apiKey?: string;
13
+ /** Default model. Defaults to 'claude-opus-5'. */
14
+ defaultModel?: string;
15
+ /** Maximum tokens for completions. */
16
+ maxTokens?: number;
17
+ /** Base URL override (for proxies). */
18
+ baseUrl?: string;
19
+ /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
20
+ onRateLimit?: AiRateLimitCallback;
21
+ }
22
+ /**
23
+ * Process Env interface.
24
+ */
25
+ export interface ProcessEnv {
26
+ ANTHROPIC_API_KEY: string;
27
+ /** Base URL override (for credential brokers / gateways). */
28
+ ANTHROPIC_BASE_URL?: string;
29
+ }
30
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wFAAwF;IACxF,WAAW,CAAC,EAAE,mBAAmB,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iBAAiB,EAAE,MAAM,CAAA;IACzB,6DAA6D;IAC7D,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B"}
package/dist/types.js ADDED
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Anthropic Claude AI provider configuration.
3
+ *
4
+ * @module
5
+ */
6
+ export {};
package/package.json ADDED
@@ -0,0 +1,46 @@
1
+ {
2
+ "name": "@molecule/api-ai-anthropic",
3
+ "version": "1.0.0",
4
+ "description": "Anthropic Claude AI provider for molecule.dev",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "scripts": {
9
+ "build": "tsc",
10
+ "test": "vitest run",
11
+ "test:watch": "vitest"
12
+ },
13
+ "exports": {
14
+ ".": {
15
+ "types": "./dist/index.d.ts",
16
+ "import": "./dist/index.js"
17
+ }
18
+ },
19
+ "files": [
20
+ "dist"
21
+ ],
22
+ "keywords": [
23
+ "molecule",
24
+ "ai",
25
+ "anthropic"
26
+ ],
27
+ "license": "Apache-2.0",
28
+ "devDependencies": {
29
+ "@molecule/api-ai": "1.0.0",
30
+ "@molecule/api-bond": "1.0.0",
31
+ "@types/node": "26.1.2",
32
+ "typescript": "6.0.3",
33
+ "vitest": "4.1.10"
34
+ },
35
+ "peerDependencies": {
36
+ "@molecule/api-ai": "^1.0.0",
37
+ "@molecule/api-bond": "^1.0.0",
38
+ "@molecule/api-i18n": "^1.0.0",
39
+ "@molecule/api-secrets": "^1.0.0"
40
+ },
41
+ "peerDependenciesMeta": {
42
+ "@molecule/api-ai": {
43
+ "optional": true
44
+ }
45
+ }
46
+ }