@moxxy/plugin-provider-anthropic 0.2.0 → 0.2.2

package/src/provider.ts

@@ -10,7 +10,8 @@ import type {
 
 type MessageStreamParams = Anthropic.Messages.MessageStreamParams;
 type MessageCountTokensParams = Anthropic.Messages.MessageCountTokensParams;
-import { estimateTextTokens, toFriendlyError } from '@moxxy/sdk';
+import { toFriendlyError } from '@moxxy/sdk';
+import type { AnthropicContentBlock } from './translate.js';
 import { toAnthropicMessages, toAnthropicTools } from './translate.js';
 
 export interface AnthropicProviderConfig {
@@ -97,6 +98,11 @@ export class AnthropicProvider implements LLMProvider {
   };
   private oauthToken?: string;
   private oauthExpiresAt?: number;
+  // Single in-flight refresh shared by concurrent callers (parallel streams /
+  // countTokens near expiry) so the refresh endpoint is hit once and the
+  // client is swapped once — a second refresh can rotate/invalidate the token
+  // and poison state on providers that rotate refresh tokens.
+  private refreshing?: Promise<void>;
 
   constructor(config: AnthropicProviderConfig = {}) {
     this.name = config.name ?? 'anthropic';
@@ -147,13 +153,24 @@ export class AnthropicProvider implements LLMProvider {
     await this.refreshOauthNow();
   }
 
-  /** Force a token refresh and rebuild the client with the new bearer. */
+  /**
+   * Force a token refresh and rebuild the client with the new bearer.
+   * Coalesces concurrent calls onto a single in-flight refresh so the endpoint
+   * is hit once and the client is swapped once.
+   */
   private async refreshOauthNow(): Promise<void> {
-    if (!this.oauth?.refresh) throw new Error('no refresh callback');
-    const next = await this.oauth.refresh();
-    this.oauthToken = next.token;
-    this.oauthExpiresAt = next.expiresAt;
-    this.client = this.makeOauthClient(next.token);
+    if (this.refreshing) return this.refreshing;
+    const refresh = this.oauth?.refresh;
+    if (!refresh) throw new Error('no refresh callback');
+    this.refreshing = (async () => {
+      const next = await refresh();
+      this.oauthToken = next.token;
+      this.oauthExpiresAt = next.expiresAt;
+      this.client = this.makeOauthClient(next.token);
+    })().finally(() => {
+      this.refreshing = undefined;
+    });
+    return this.refreshing;
   }
 
   /**
@@ -217,10 +234,11 @@ export class AnthropicProvider implements LLMProvider {
     const systemParam = this.buildSystemParam(system, cacheSystem, req.system);
     const model = req.model || this.defaultModel;
 
-    yield { type: 'message_start', model };
-
     // In OAuth mode refresh the bearer proactively when it's near expiry, so
     // we don't fire a request on a token we already knew was about to die.
+    // Done BEFORE emitting message_start so a turn that never reaches the API
+    // (proactive refresh throws) doesn't leave a dangling open message for
+    // consumers that pair message_start/message_end.
     if (this.oauth) {
       try {
         await this.ensureFreshOauth();
@@ -230,6 +248,20 @@ export class AnthropicProvider implements LLMProvider {
       }
     }
 
+    yield { type: 'message_start', model };
+
+    // Default + clamp max_tokens to the active model's output ceiling. We hold
+    // the catalog, so default to the descriptor's `maxOutputTokens` (4096 when
+    // unknown) and never forward a caller-supplied value above the ceiling —
+    // an over-ceiling request 400s server-side after the whole body is built.
+    const ceiling = this.models.find((m) => m.id === model)?.maxOutputTokens;
+    const maxTokens =
+      req.maxTokens !== undefined
+        ? ceiling !== undefined
+          ? Math.min(req.maxTokens, ceiling)
+          : req.maxTokens
+        : (ceiling ?? 4096);
+
     // NARROW cast: `messages`/`tools`/`systemParam` are our hand-rolled
     // Anthropic shapes (e.g. `media_type: string`) which the SDK narrows to
     // literal unions it can't see we never violate. The body is otherwise
@@ -237,7 +269,7 @@ export class AnthropicProvider implements LLMProvider {
     // `temperature` are checked at compile time.
     const requestBody: MessageStreamParams = {
       model,
-      max_tokens: req.maxTokens ?? 4096,
+      max_tokens: maxTokens,
       system: systemParam as MessageStreamParams['system'],
       messages: messages as MessageStreamParams['messages'],
       tools: tools as MessageStreamParams['tools'],
@@ -260,12 +292,18 @@ export class AnthropicProvider implements LLMProvider {
       if (effort) body.output_config = { effort };
     }
 
-    // A 401 always arrives before any SSE body, so in OAuth mode we can force
-    // a single refresh and replay the request with no risk of duplicate output.
+    // A genuine auth 401 arrives before any SSE body, so in OAuth mode we can
+    // force a single refresh and replay the request. But `isUnauthorized()`
+    // also matches a 401 surfaced MID-stream (token revoked during a long
+    // generation, proxy 401 on a chunk); replaying after content already
+    // streamed would duplicate text/tool calls into the same turn. Track
+    // whether the first attempt produced any output and only replay when it
+    // produced none.
+    const progress = { produced: false };
     try {
-      yield* this.streamOnce(requestBody, req.signal);
+      yield* this.streamOnce(requestBody, req.signal, progress);
     } catch (err) {
-      if (this.oauth?.refresh && isUnauthorized(err)) {
+      if (this.oauth?.refresh && isUnauthorized(err) && !progress.produced) {
         try {
           await this.refreshOauthNow();
           yield* this.streamOnce(requestBody, req.signal);
@@ -288,6 +326,11 @@ export class AnthropicProvider implements LLMProvider {
   private async *streamOnce(
     requestBody: MessageStreamParams,
     signal: AbortSignal | undefined,
+    // Set to `true` the moment this attempt yields any content event (anything
+    // past message_start). `stream()` reads it to decide whether a 401 is safe
+    // to refresh-and-replay (replaying after output already streamed would
+    // duplicate text/tool calls). Optional so the replay attempt can omit it.
+    progress?: { produced: boolean },
   ): AsyncIterable<ProviderEvent> {
     const stream = this.client.messages.stream(
       requestBody,
@@ -316,6 +359,10 @@ export class AnthropicProvider implements LLMProvider {
     // the excess-property check) against a narrower declared type.
     let usage: TokenUsage | undefined;
 
+    // Set once the stream is fully drained on the happy path; gates the
+    // finally-block teardown so we only force-abort on an early exit
+    // (abort/throw/consumer abandonment), never on a clean completion.
+    let drained = false;
     try {
       for await (const event of stream as AsyncIterable<AnthropicStreamEvent>) {
         if (signal?.aborted) {
@@ -343,6 +390,7 @@ export class AnthropicProvider implements LLMProvider {
             break;
           }
           case 'content_block_start': {
+            if (progress) progress.produced = true;
             const block = event.content_block;
             if (block && block.type === 'tool_use') {
               pendingToolUses.set(block.id, { name: block.name, partial: '' });
@@ -361,6 +409,7 @@ export class AnthropicProvider implements LLMProvider {
             break;
           }
           case 'content_block_delta': {
+            if (progress) progress.produced = true;
             const delta = event.delta;
             if (!delta) break;
             if (delta.type === 'text_delta' && typeof delta.text === 'string') {
@@ -370,7 +419,7 @@ export class AnthropicProvider implements LLMProvider {
             } else if (delta.type === 'signature_delta' && typeof delta.signature === 'string') {
               pendingThinkingSig += delta.signature;
             } else if (delta.type === 'input_json_delta' && typeof delta.partial_json === 'string') {
-              const id = idOfBlock(event, blockIndexToId);
+              const id = idOfBlock(event, blockIndexToId, pendingToolUses);
               if (id) {
                 const t = pendingToolUses.get(id);
                 if (t) {
@@ -382,40 +431,65 @@ export class AnthropicProvider implements LLMProvider {
             break;
           }
           case 'content_block_stop': {
+            if (progress) progress.produced = true;
             if (typeof event.index === 'number' && thinkingBlockIndices.has(event.index)) {
               thinkingBlockIndices.delete(event.index);
               if (pendingThinkingSig) yield { type: 'reasoning_signature', signature: pendingThinkingSig };
               pendingThinkingSig = '';
               break;
             }
-            const id = idOfBlock(event, blockIndexToId);
+            const id = idOfBlock(event, blockIndexToId, pendingToolUses);
             if (id) {
               const t = pendingToolUses.get(id);
               if (t) {
-                let parsed: unknown = {};
+                let parsed: unknown;
                 try {
                   parsed = t.partial ? JSON.parse(t.partial) : {};
                 } catch {
-                  parsed = { _rawPartial: t.partial };
+                  // A truncated/malformed tool-input stream is a real failure, not
+                  // a valid call with junk args. Surface it as an error (the loop
+                  // treats a stream-level error as authoritative) and mark the turn
+                  // `error`, instead of feeding `{ _rawPartial }` into the tool —
+                  // which erased all signal that the model's call was garbage.
+                  pendingToolUses.delete(id);
+                  pruneBlockIndex(blockIndexToId, event.index, id);
+                  stopReason = 'error';
+                  yield {
+                    type: 'error',
+                    message: `tool_use input JSON was malformed/truncated for ${id}`,
+                    retryable: false,
+                  };
+                  break;
                 }
                 yield { type: 'tool_use_end', id, input: parsed };
                 pendingToolUses.delete(id);
-                if (typeof event.index === 'number') blockIndexToId.delete(event.index);
+                pruneBlockIndex(blockIndexToId, event.index, id);
               }
             }
             break;
           }
           case 'message_delta': {
-            if (event.delta?.stop_reason) {
+            // STICKY error: once a malformed/truncated tool-input stream marked
+            // the turn `error` at content_block_stop, a trailing message_delta
+            // (which a truncated tool-use turn still reports as `tool_use`) must
+            // NOT clobber it back to a clean completion — that would re-run the
+            // junk tool. Usage numbers below still merge as usual.
+            if (event.delta?.stop_reason && stopReason !== 'error') {
               stopReason = mapStopReason(event.delta.stop_reason);
             }
             if (event.usage) {
-              // Preserve cache fields captured at message_start — the delta
-              // usage only carries the final output_tokens count.
+              // Prefer delta-reported input/cache numbers when present (some
+              // streaming modes report or correct them here), but fall back to
+              // the message_start values otherwise — mirroring the defensive
+              // `?? previous` pattern used for outputTokens.
+              const du = event.usage;
+              const cacheRead = du.cache_read_input_tokens ?? usage?.cacheReadTokens;
+              const cacheCreation = du.cache_creation_input_tokens ?? usage?.cacheCreationTokens;
               usage = {
-                ...usage,
-                inputTokens: usage?.inputTokens ?? 0,
-                outputTokens: event.usage.output_tokens ?? usage?.outputTokens ?? 0,
+                inputTokens: du.input_tokens ?? usage?.inputTokens ?? 0,
+                outputTokens: du.output_tokens ?? usage?.outputTokens ?? 0,
+                ...(cacheRead !== undefined ? { cacheReadTokens: cacheRead } : {}),
+                ...(cacheCreation !== undefined ? { cacheCreationTokens: cacheCreation } : {}),
               };
             }
             break;
@@ -424,6 +498,7 @@ export class AnthropicProvider implements LLMProvider {
             break;
         }
       }
+      drained = true;
     } catch (err) {
       // A cancel surfaces as a thrown AbortError mid-await — report it as the
       // clean terminal 'aborted' event. Every other error propagates so
@@ -433,6 +508,21 @@ export class AnthropicProvider implements LLMProvider {
         return;
       }
       throw err;
+    } finally {
+      // Guarantee socket teardown independent of whether the AbortSignal
+      // propagated into the SDK. On any early exit (abort, throw, or the
+      // consumer abandoning the generator — at which point the JS runtime
+      // runs this finally) explicitly abort the SDK stream so a half-open
+      // HTTP connection can't linger under repeated rapid cancellation.
+      if (!drained) {
+        const s = stream as unknown as { abort?: () => void; controller?: { abort?: () => void } };
+        try {
+          s.abort?.();
+          s.controller?.abort?.();
+        } catch {
+          // Best-effort cleanup — a fake/partial stream may expose neither.
+        }
+      }
     }
 
     yield { type: 'message_end', stopReason, usage };
@@ -465,15 +555,53 @@ export class AnthropicProvider implements LLMProvider {
       });
       return result.input_tokens;
     } catch {
-      const blob =
-        (systemForCount ?? '') +
-        messages.map((m) => JSON.stringify(m.content)).join('') +
-        JSON.stringify(tools ?? []);
-      return estimateTextTokens(blob);
+      // Estimate WITHOUT serializing megabytes of base64 into one mega-string:
+      // a media block's bytes have nothing to do with its token cost, and
+      // stringifying them both spikes memory on a large multimodal history and
+      // wildly inflates the estimate. Sum char-lengths of textual content and
+      // charge each media block a small fixed allowance instead.
+      let chars = systemForCount?.length ?? 0;
+      for (const m of messages) {
+        for (const block of m.content) {
+          chars += estimateBlockChars(block);
+        }
+      }
+      chars += JSON.stringify(tools ?? []).length;
+      // Mirror estimateTextTokens (≈4 chars/token) on the accumulated length
+      // without ever materializing the concatenated string.
+      return Math.ceil(chars / 4);
     }
   }
 }
 
+/** Rough per-image/-document token allowance for the offline estimate fallback. */
+const MEDIA_BLOCK_TOKENS = 1500;
+
+/**
+ * Char-length contribution of one Anthropic content block for the offline
+ * token estimate. Skips the base64 `data` of image/document blocks (charging a
+ * fixed token allowance, scaled back to chars) so a multi-MB blob never gets
+ * stringified just to be divided by 4.
+ */
+function estimateBlockChars(block: AnthropicContentBlock): number {
+  switch (block.type) {
+    case 'text':
+      return block.text.length;
+    case 'tool_use':
+      return block.name.length + JSON.stringify(block.input ?? {}).length;
+    case 'tool_result':
+      return block.content.length;
+    case 'thinking':
+      return block.thinking.length + block.signature.length;
+    case 'redacted_thinking':
+      return block.data.length;
+    case 'image':
+    case 'document':
+      // Charge a fixed allowance instead of the base64 byte length.
+      return MEDIA_BLOCK_TOKENS * 4;
+  }
+}
+
 interface AnthropicStreamEvent {
   type:
     | 'message_start'
@@ -508,25 +636,59 @@ interface AnthropicStreamEvent {
     signature?: string;
     stop_reason?: string;
   };
-  usage?: { output_tokens?: number };
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+  };
 }
 
 function idOfBlock(
   event: AnthropicStreamEvent,
   blockIndexToId: Map<number, string>,
+  pendingToolUses?: ReadonlyMap<string, unknown>,
 ): string | null {
   if (typeof event.index === 'number') {
     return blockIndexToId.get(event.index) ?? null;
   }
   // Fallback when `index` is missing (older SDKs / hand-rolled fakes): only
-  // unambiguous when exactly one tool_use is pending; otherwise refuse to
-  // guess and let the delta drop rather than misroute it.
+  // unambiguous when exactly one tool_use is pending. `pruneBlockIndex` deletes
+  // a finished block's entry on content_block_stop even in an index-less stream,
+  // so a stale entry can't linger to falsely satisfy size===1 for a later block;
+  // we still require the id to be PENDING as a belt-and-suspenders guard.
   if (blockIndexToId.size === 1) {
-    for (const id of blockIndexToId.values()) return id;
+    for (const id of blockIndexToId.values()) {
+      if (!pendingToolUses || pendingToolUses.has(id)) return id;
+    }
   }
   return null;
 }
 
+/**
+ * Remove a finished tool block's index→id mapping. Prefers the numeric index
+ * (real Anthropic streams), but falls back to deleting by VALUE (`id`) so an
+ * index-less stream doesn't leave a stale entry lingering — which would break
+ * the size===1 fallback for the next serial tool block (its deltas would route
+ * nowhere). Index-less streams therefore stay correct for strictly-serial tools.
+ */
+function pruneBlockIndex(
+  blockIndexToId: Map<number, string>,
+  index: number | undefined,
+  id: string,
+): void {
+  if (typeof index === 'number') {
+    blockIndexToId.delete(index);
+    return;
+  }
+  for (const [k, v] of blockIndexToId) {
+    if (v === id) {
+      blockIndexToId.delete(k);
+      return;
+    }
+  }
+}
+
 function mapStopReason(s: string): StopReason {
   if (s === 'tool_use') return 'tool_use';
   if (s === 'max_tokens') return 'max_tokens';

package/src/translate.test.ts

@@ -98,6 +98,58 @@ describe('toAnthropicMessages', () => {
     ]);
     expect(messages[0]!.content[0]!.cache_control).toBeUndefined();
   });
+
+  it('joins all text blocks of a multi-block system message (does not drop the rest)', () => {
+    const { system } = toAnthropicMessages([
+      {
+        role: 'system',
+        content: [
+          { type: 'text', text: 'first' },
+          { type: 'text', text: 'second' },
+        ],
+      },
+    ]);
+    expect(system).toBe('first\n\nsecond');
+  });
+
+  it('degrades an unsupported image media type to a text placeholder rather than forwarding bytes', () => {
+    const { messages } = toAnthropicMessages([
+      {
+        role: 'user',
+        content: [{ type: 'image', mediaType: 'image/tiff', data: 'AAAA' }],
+      },
+    ]);
+    const block = messages[0]!.content[0]!;
+    expect(block.type).toBe('text');
+    expect((block as { text: string }).text).toContain('image/tiff');
+  });
+
+  it('degrades an unsupported document media type to a text placeholder', () => {
+    const { messages } = toAnthropicMessages([
+      {
+        role: 'user',
+        content: [{ type: 'document', mediaType: 'application/zip', data: 'AAAA' }],
+      },
+    ]);
+    const block = messages[0]!.content[0]!;
+    expect(block.type).toBe('text');
+    expect((block as { text: string }).text).toContain('application/zip');
+  });
+
+  it('drops an unsigned/unredacted reasoning block instead of leaking it as assistant text', () => {
+    const { messages } = toAnthropicMessages([
+      {
+        role: 'assistant',
+        content: [
+          { type: 'reasoning', text: 'secret chain of thought' },
+          { type: 'text', text: 'answer' },
+        ],
+      },
+    ]);
+    // The reasoning block is dropped; only the visible answer survives.
+    expect(messages[0]!.content).toHaveLength(1);
+    expect(messages[0]!.content[0]).toMatchObject({ type: 'text', text: 'answer' });
+  });
 });
 
 describe('toAnthropicTools', () => {

package/src/translate.ts

@@ -3,6 +3,15 @@ import { zodToJsonSchema } from '@moxxy/sdk';
 
 type CacheControl = { type: 'ephemeral' };
 
+/** Media types Anthropic's Messages API accepts for `image`/`document` blocks. */
+const IMAGE_MEDIA_TYPES: ReadonlySet<string> = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+]);
+const DOCUMENT_MEDIA_TYPES: ReadonlySet<string> = new Set(['application/pdf']);
+
 export interface AnthropicMessageInput {
   role: 'user' | 'assistant';
   content: Array<AnthropicContentBlock>;
@@ -77,16 +86,22 @@ export function toAnthropicMessages(
     const wantCache = cacheIdx?.has(i) ?? false;
 
     if (msg.role === 'system') {
-      const textBlock = msg.content.find((c) => c.type === 'text');
-      if (textBlock && textBlock.type === 'text') {
-        system = system ? `${system}\n\n${textBlock.text}` : textBlock.text;
+      // Join ALL text blocks of a system message (not just the first) so a
+      // multi-block system prompt isn't silently truncated; mirrors the
+      // cross-message join below.
+      const text = msg.content
+        .filter((c): c is Extract<ContentBlock, { type: 'text' }> => c.type === 'text')
+        .map((c) => c.text)
+        .join('\n\n');
+      if (text) {
+        system = system ? `${system}\n\n${text}` : text;
       }
       return;
     }
 
     if (msg.role === 'user') {
       flushUser();
-      const content = msg.content.map(toAnthropicBlock);
+      const content = mapBlocks(msg.content);
       if (wantCache) markCache(content[content.length - 1]);
       out.push({ role: 'user', content });
       return;
@@ -94,7 +109,7 @@ export function toAnthropicMessages(
 
     if (msg.role === 'assistant') {
       flushUser();
-      const content = msg.content.map(toAnthropicBlock);
+      const content = mapBlocks(msg.content);
       if (wantCache) markCache(content[content.length - 1]);
       out.push({ role: 'assistant', content });
       return;
@@ -123,7 +138,17 @@ export function toAnthropicMessages(
   return { system, messages: out };
 }
 
-function toAnthropicBlock(block: ContentBlock): AnthropicContentBlock {
+/** Translate a message's blocks, dropping any that translate to nothing. */
+function mapBlocks(blocks: ReadonlyArray<ContentBlock>): AnthropicContentBlock[] {
+  const out: AnthropicContentBlock[] = [];
+  for (const b of blocks) {
+    const t = toAnthropicBlock(b);
+    if (t) out.push(t);
+  }
+  return out;
+}
+
+function toAnthropicBlock(block: ContentBlock): AnthropicContentBlock | null {
   switch (block.type) {
     case 'text':
       return { type: 'text', text: block.text };
@@ -137,12 +162,29 @@ function toAnthropicBlock(block: ContentBlock): AnthropicContentBlock {
         is_error: block.isError,
       };
     case 'image':
+      // Reject unsupported media types locally (degrade to a placeholder, as
+      // audio does) rather than uploading bytes that 400 deep in the SDK. A
+      // resumed session or hostile channel can supply an out-of-allow-list
+      // type; the documented Anthropic image set is png/jpeg/gif/webp.
+      if (!IMAGE_MEDIA_TYPES.has(block.mediaType)) {
+        return {
+          type: 'text',
+          text: `[image attachment dropped: ${block.mediaType} not a supported image type]`,
+        };
+      }
       return {
         type: 'image',
         source: { type: 'base64', media_type: block.mediaType, data: block.data },
       };
     case 'document':
       // Native document support (PDF). Claude reads text + figures/layout.
+      // Documented Anthropic document set is application/pdf only.
+      if (!DOCUMENT_MEDIA_TYPES.has(block.mediaType)) {
+        return {
+          type: 'text',
+          text: `[document attachment dropped: ${block.mediaType} not a supported document type]`,
+        };
+      }
       return {
         type: 'document',
         source: { type: 'base64', media_type: block.mediaType, data: block.data },
@@ -161,15 +203,19 @@ function toAnthropicBlock(block: ContentBlock): AnthropicContentBlock {
     case 'reasoning':
       // Replayed verbatim so Anthropic accepts an interleaved-thinking tool-use
       // continuation. `redacted` → the opaque encrypted blob; otherwise the
-      // signed thinking block (projection only forwards reasoning that carries a
-      // signature or encrypted blob, so the text fallback below is unreachable).
+      // signed thinking block. Drop an unsigned/unredacted reasoning block
+      // rather than degrading it to a stray assistant text block: Anthropic
+      // rejects an unsigned thinking block, and emitting it as text could leak
+      // raw reasoning into assistant output or 400 a tool-use turn. The
+      // translator stays self-consistent without depending on the upstream
+      // projection invariant (maintained in a different package).
       if (block.redacted && block.encrypted) {
         return { type: 'redacted_thinking', data: block.encrypted };
       }
       if (block.signature) {
         return { type: 'thinking', thinking: block.text, signature: block.signature };
       }
-      return { type: 'text', text: block.text };
+      return null;
   }
 }
 

package/src/validate.test.ts

@@ -40,4 +40,33 @@ describe('anthropic validateKey', () => {
     const args = create.mock.calls[0]?.[0] as Record<string, unknown>;
     expect(args.model).toBe('claude-opus-4-7');
   });
+
+  it('maps a 401 to a fixed friendly message (no raw SDK text echoed)', async () => {
+    const make = () => ({
+      messages: {
+        create: async () => {
+          throw Object.assign(new Error('GET https://proxy.internal/v1 401 x-api-key=...'), { status: 401 });
+        },
+      },
+    });
+    const res = await validateKey('sk-ant-some-long-enough-key', { client: make });
+    expect(res).toEqual({ ok: false, message: 'key was rejected' });
+  });
+
+  it('scrubs the key from a fallback (status-less) error message', async () => {
+    const key = 'sk-ant-secret-but-long-enough';
+    const make = () => ({
+      messages: {
+        create: async () => {
+          throw new Error(`request failed with key ${key}`);
+        },
+      },
+    });
+    const res = await validateKey(key, { client: make });
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.message).not.toContain(key);
+      expect(res.message).toContain('[redacted]');
+    }
+  });
 });

package/src/validate.ts

@@ -28,10 +28,29 @@ export async function validateKey(key: string, deps: ValidateKeyDeps = {}): Prom
     });
     return { ok: true };
   } catch (err) {
-    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+    return { ok: false, message: friendlyValidationError(err, key) };
   }
 }
 
+/**
+ * Map a key-validation failure to a fixed friendly string by HTTP status, never
+ * echoing raw SDK error text (which can embed request/proxy URLs or header
+ * fragments) verbatim. The fallback is truncated and any occurrence of the key
+ * is scrubbed so a reflected error can't leak it into setup UIs / logs.
+ */
+function friendlyValidationError(err: unknown, key: string): string {
+  const status = (err as { status?: unknown } | null | undefined)?.status;
+  if (typeof status === 'number') {
+    if (status === 401) return 'key was rejected';
+    if (status === 403) return 'key lacks access';
+    if (status === 429) return 'rate limited — try again shortly';
+    if (status >= 500) return 'Anthropic returned a server error';
+  }
+  const raw = err instanceof Error ? err.message : String(err);
+  const scrubbed = key ? raw.split(key).join('[redacted]') : raw;
+  return scrubbed.length > 200 ? `${scrubbed.slice(0, 200)}…` : scrubbed;
+}
+
 function defaultMaker(apiKey: string): { messages: { create: (args: Record<string, unknown>) => Promise<unknown> } } {
   return new Anthropic({ apiKey }) as unknown as {
     messages: { create: (args: Record<string, unknown>) => Promise<unknown> };