@moxxy/plugin-provider-anthropic 0.2.0

package/src/real-api.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Real-API smoke test.
+ *
+ * Drives the FULL moxxy stack — AnthropicProvider translator → loop strategy
+ * → tool execution → event log projection — using a hand-authored Anthropic
+ * stream fixture that mirrors the wire shape we'd record from a live API call.
+ *
+ * The fixture isn't generated by hitting the real API at test time; it's
+ * captured shape that exercises every translation path. To regenerate from
+ * a real run, use `apps/fixture-recorder` with MOXXY_FIXTURES=record.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import {
+  collectTurn,
+  silentLogger,
+  Session,
+  autoAllowResolver,
+} from '@moxxy/core';
+import { defineProvider, definePlugin, defineTool } from '@moxxy/sdk';
+import { defaultModePlugin } from '@moxxy/mode-default';
+import { AnthropicProvider } from './provider.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+interface AnthropicStreamFixture {
+  description: string;
+  request: unknown;
+  events: ReadonlyArray<Record<string, unknown>>;
+}
+
+/** Replays a fixture's raw Anthropic events as a fake SDK client. */
+function fakeAnthropicClient(fixture: AnthropicStreamFixture): {
+  messages: {
+    stream: () => AsyncIterable<unknown>;
+    countTokens: () => Promise<{ input_tokens: number }>;
+  };
+} {
+  return {
+    messages: {
+      stream: () =>
+        (async function* () {
+          for (const e of fixture.events) yield e;
+        })(),
+      countTokens: async () => ({ input_tokens: 0 }),
+    },
+  };
+}
+
+let tmp: string;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-realapi-'));
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+describe('real-API smoke: tool-use turn replayed end-to-end', () => {
+  it('translates raw Anthropic events through the full moxxy stack', async () => {
+    const fixturePath = path.resolve(__dirname, '..', '__fixtures__', 'tool-use-turn.json');
+    const fixture: AnthropicStreamFixture = JSON.parse(await fs.readFile(fixturePath, 'utf8'));
+
+    const upstream = new AnthropicProvider({
+      client: fakeAnthropicClient(fixture) as never,
+    });
+
+    // Need a second-turn reply for the model's summary AFTER the tool result.
+    // For this smoke we only assert on the first translation pass, so wire a
+    // shim that exits the loop on its second invocation.
+    let callCount = 0;
+    const provider = {
+      name: upstream.name,
+      models: upstream.models,
+      async *stream(req: import('@moxxy/sdk').ProviderRequest) {
+        callCount += 1;
+        if (callCount === 1) {
+          yield* upstream.stream(req);
+          return;
+        }
+        // Second call: emit a clean end_turn so the loop terminates.
+        yield { type: 'message_start' as const, model: req.model };
+        yield { type: 'text_delta' as const, delta: 'OK — greeted world.' };
+        yield { type: 'message_end' as const, stopReason: 'end_turn' as const };
+      },
+      async countTokens() {
+        return 0;
+      },
+    };
+
+    const session = new Session({
+      cwd: tmp,
+      logger: silentLogger,
+      permissionResolver: autoAllowResolver,
+    });
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'realapi-shim',
+        providers: [
+          defineProvider({
+            name: 'anthropic',
+            models: [...upstream.models],
+            createClient: () => provider,
+          }),
+        ],
+      }),
+    );
+    session.providers.setActive('anthropic');
+    session.pluginHost.registerStatic(defaultModePlugin);
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'realapi-tools',
+        tools: [
+          defineTool({
+            name: 'greet',
+            description: 'Returns a greeting for the given name.',
+            inputSchema: z.object({ name: z.string() }),
+            handler: ({ name }) => `Hello, ${name}!`,
+          }),
+        ],
+      }),
+    );
+
+    const events = await collectTurn(session, 'please greet world');
+
+    // Phase 1: AnthropicProvider correctly translated the raw stream into a
+    // tool_use event sequence with the streamed input JSON re-assembled.
+    const toolStart = events.find((e) => e.type === 'tool_call_requested');
+    if (toolStart?.type !== 'tool_call_requested') throw new Error('expected tool_call_requested');
+    expect(toolStart.name).toBe('greet');
+    expect(toolStart.input).toEqual({ name: 'world' });
+    expect(toolStart.callId).toBe('toolu_01XYZ');
+
+    // Phase 2: the tool executed and the result fed back into the loop.
+    const toolResult = events.find((e) => e.type === 'tool_result');
+    if (toolResult?.type !== 'tool_result') throw new Error('expected tool_result');
+    expect(toolResult.ok).toBe(true);
+    expect(toolResult.output).toBe('Hello, world!');
+
+    // Phase 3: model produced a final summary in the second iteration.
+    const finalAssistant = events.filter((e) => e.type === 'assistant_message').pop();
+    if (finalAssistant?.type !== 'assistant_message') throw new Error('expected assistant_message');
+    expect(finalAssistant.content).toContain('greeted');
+
+    // The translator emitted exactly one provider request (not retried).
+    const providerRequests = events.filter((e) => e.type === 'provider_request');
+    expect(providerRequests.length).toBe(2); // one per loop iteration
+  });
+});

package/src/translate.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { defineTool } from '@moxxy/sdk';
+import { toAnthropicMessages, toAnthropicTools } from './translate.js';
+
+describe('toAnthropicMessages', () => {
+  it('hoists system messages', () => {
+    const { system, messages } = toAnthropicMessages([
+      { role: 'system', content: [{ type: 'text', text: 'you are X' }] },
+      { role: 'user', content: [{ type: 'text', text: 'hi' }] },
+    ]);
+    expect(system).toBe('you are X');
+    expect(messages).toHaveLength(1);
+    expect(messages[0].role).toBe('user');
+  });
+
+  it('translates assistant tool_use blocks', () => {
+    const { messages } = toAnthropicMessages([
+      { role: 'user', content: [{ type: 'text', text: 'do it' }] },
+      {
+        role: 'assistant',
+        content: [{ type: 'tool_use', id: 'c1', name: 'Read', input: { file_path: 'a' } }],
+      },
+    ]);
+    expect(messages[1].role).toBe('assistant');
+    expect(messages[1].content[0]).toMatchObject({ type: 'tool_use', id: 'c1', name: 'Read' });
+  });
+
+  it('translates an image block to a base64 image source', () => {
+    const { messages } = toAnthropicMessages([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'what is this?' },
+          { type: 'image', mediaType: 'image/png', data: 'AAAA' },
+        ],
+      },
+    ]);
+    expect(messages[0].content[1]).toEqual({
+      type: 'image',
+      source: { type: 'base64', media_type: 'image/png', data: 'AAAA' },
+    });
+  });
+
+  it('translates a document block to a native base64 document with title', () => {
+    const { messages } = toAnthropicMessages([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'summarize this' },
+          { type: 'document', mediaType: 'application/pdf', data: 'JVBERi0=', name: 'report.pdf' },
+        ],
+      },
+    ]);
+    expect(messages[0].content[1]).toEqual({
+      type: 'document',
+      source: { type: 'base64', media_type: 'application/pdf', data: 'JVBERi0=' },
+      title: 'report.pdf',
+    });
+  });
+
+  it('merges adjacent tool_result messages into a user message', () => {
+    const { messages } = toAnthropicMessages([
+      { role: 'user', content: [{ type: 'text', text: 'q' }] },
+      { role: 'assistant', content: [{ type: 'tool_use', id: 'c1', name: 'T', input: {} }] },
+      {
+        role: 'tool_result',
+        content: [{ type: 'tool_result', toolUseId: 'c1', content: 'ok', isError: false }],
+      },
+    ]);
+    const last = messages[messages.length - 1];
+    expect(last.role).toBe('user');
+    expect(last.content[0]).toMatchObject({
+      type: 'tool_result',
+      tool_use_id: 'c1',
+      content: 'ok',
+    });
+  });
+
+  it('places cache_control on the last block of a hinted message', () => {
+    const { messages } = toAnthropicMessages(
+      [
+        { role: 'user', content: [{ type: 'text', text: 'a' }] },
+        { role: 'assistant', content: [{ type: 'text', text: 'b' }] },
+        { role: 'user', content: [{ type: 'text', text: 'c' }] },
+      ],
+      { cacheMessageIndices: new Set([2]) },
+    );
+    const marked = messages[messages.length - 1]!.content[0]!;
+    expect(marked.cache_control).toEqual({ type: 'ephemeral' });
+    // Unhinted messages stay unmarked.
+    expect(messages[0]!.content[0]!.cache_control).toBeUndefined();
+  });
+
+  it('adds no cache_control when no hints are given', () => {
+    const { messages } = toAnthropicMessages([
+      { role: 'user', content: [{ type: 'text', text: 'a' }] },
+    ]);
+    expect(messages[0]!.content[0]!.cache_control).toBeUndefined();
+  });
+});
+
+describe('toAnthropicTools', () => {
+  it('emits name + description + json schema', () => {
+    const tool = defineTool({
+      name: 'Greet',
+      description: 'Greet someone',
+      inputSchema: z.object({ name: z.string() }),
+      handler: () => null,
+    });
+    const out = toAnthropicTools([tool]);
+    expect(out[0].name).toBe('Greet');
+    expect(out[0].description).toBe('Greet someone');
+    const schema = out[0].input_schema as Record<string, unknown>;
+    expect(schema.type).toBe('object');
+  });
+
+  it('marks the last tool with cache_control when cacheLast is set', () => {
+    const mk = (name: string) =>
+      defineTool({ name, description: name, inputSchema: z.object({}), handler: () => null });
+    const out = toAnthropicTools([mk('A'), mk('B')], { cacheLast: true });
+    expect(out[0].cache_control).toBeUndefined();
+    expect(out[1].cache_control).toEqual({ type: 'ephemeral' });
+  });
+});

package/src/translate.ts

@@ -0,0 +1,194 @@
+import type { ContentBlock, ProviderMessage, ToolDef } from '@moxxy/sdk';
+import { zodToJsonSchema } from '@moxxy/sdk';
+
+type CacheControl = { type: 'ephemeral' };
+
+export interface AnthropicMessageInput {
+  role: 'user' | 'assistant';
+  content: Array<AnthropicContentBlock>;
+}
+
+export type AnthropicContentBlock =
+  | { type: 'text'; text: string; cache_control?: CacheControl }
+  | { type: 'tool_use'; id: string; name: string; input: unknown; cache_control?: CacheControl }
+  | {
+      type: 'tool_result';
+      tool_use_id: string;
+      content: string;
+      is_error?: boolean;
+      cache_control?: CacheControl;
+    }
+  | {
+      type: 'image';
+      source: { type: 'base64'; media_type: string; data: string };
+      cache_control?: CacheControl;
+    }
+  | {
+      type: 'document';
+      source: { type: 'base64'; media_type: string; data: string };
+      title?: string;
+      cache_control?: CacheControl;
+    }
+  // Reasoning round-trip: a signed `thinking` block (replayed verbatim on the
+  // same model so Anthropic accepts an interleaved-thinking tool-use turn) or a
+  // `redacted_thinking` block carrying only the opaque encrypted blob.
+  | { type: 'thinking'; thinking: string; signature: string; cache_control?: CacheControl }
+  | { type: 'redacted_thinking'; data: string; cache_control?: CacheControl };
+
+export interface AnthropicToolDef {
+  name: string;
+  description: string;
+  input_schema: unknown;
+  cache_control?: CacheControl;
+}
+
+export interface ToAnthropicMessagesOptions {
+  /**
+   * Indices (into the input `messages` array) after which a prompt-cache
+   * breakpoint should be placed. The marker lands on the last Anthropic
+   * content block produced for that source message.
+   */
+  readonly cacheMessageIndices?: ReadonlySet<number>;
+}
+
+function markCache(block: AnthropicContentBlock | undefined): void {
+  if (block) block.cache_control = { type: 'ephemeral' };
+}
+
+export function toAnthropicMessages(
+  messages: ReadonlyArray<ProviderMessage>,
+  opts: ToAnthropicMessagesOptions = {},
+): {
+  system: string | undefined;
+  messages: AnthropicMessageInput[];
+} {
+  const cacheIdx = opts.cacheMessageIndices;
+  let system: string | undefined;
+  const out: AnthropicMessageInput[] = [];
+  let pendingUserBlocks: AnthropicContentBlock[] | null = null;
+  const flushUser = (): void => {
+    if (pendingUserBlocks) {
+      out.push({ role: 'user', content: pendingUserBlocks });
+      pendingUserBlocks = null;
+    }
+  };
+
+  messages.forEach((msg, i) => {
+    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;
+      }
+      return;
+    }
+
+    if (msg.role === 'user') {
+      flushUser();
+      const content = msg.content.map(toAnthropicBlock);
+      if (wantCache) markCache(content[content.length - 1]);
+      out.push({ role: 'user', content });
+      return;
+    }
+
+    if (msg.role === 'assistant') {
+      flushUser();
+      const content = msg.content.map(toAnthropicBlock);
+      if (wantCache) markCache(content[content.length - 1]);
+      out.push({ role: 'assistant', content });
+      return;
+    }
+
+    if (msg.role === 'tool_result') {
+      // Tool results are merged into a user message with tool_result content blocks
+      pendingUserBlocks ??= [];
+      for (const block of msg.content) {
+        if (block.type === 'tool_result') {
+          pendingUserBlocks.push({
+            type: 'tool_result',
+            tool_use_id: block.toolUseId,
+            content: block.content,
+            is_error: block.isError,
+          });
+        }
+      }
+      // Breakpoint after a tool-result source message lands on the last block
+      // appended for it. Caching up to a mid-message block is valid (it just
+      // defines the prefix boundary), so merging doesn't break this.
+      if (wantCache) markCache(pendingUserBlocks[pendingUserBlocks.length - 1]);
+    }
+  });
+  flushUser();
+  return { system, messages: out };
+}
+
+function toAnthropicBlock(block: ContentBlock): AnthropicContentBlock {
+  switch (block.type) {
+    case 'text':
+      return { type: 'text', text: block.text };
+    case 'tool_use':
+      return { type: 'tool_use', id: block.id, name: block.name, input: block.input };
+    case 'tool_result':
+      return {
+        type: 'tool_result',
+        tool_use_id: block.toolUseId,
+        content: block.content,
+        is_error: block.isError,
+      };
+    case 'image':
+      return {
+        type: 'image',
+        source: { type: 'base64', media_type: block.mediaType, data: block.data },
+      };
+    case 'document':
+      // Native document support (PDF). Claude reads text + figures/layout.
+      return {
+        type: 'document',
+        source: { type: 'base64', media_type: block.mediaType, data: block.data },
+        ...(block.name ? { title: block.name } : {}),
+      };
+    case 'audio':
+      // Anthropic's Messages API does not accept native audio yet. Channels
+      // are supposed to transcribe up-front when the active model lacks
+      // `supportsAudio`; if an audio block reaches the translator anyway
+      // (e.g. a resumed session originally captured on a different
+      // provider), degrade to a text placeholder rather than throwing.
+      return {
+        type: 'text',
+        text: `[audio attachment dropped: ${block.mediaType} not supported by this model]`,
+      };
+    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).
+      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 };
+  }
+}
+
+export interface ToAnthropicToolsOptions {
+  /** Place a cache breakpoint on the last tool, caching the whole tools array. */
+  readonly cacheLast?: boolean;
+}
+
+export function toAnthropicTools(
+  tools: ReadonlyArray<ToolDef>,
+  opts: ToAnthropicToolsOptions = {},
+): AnthropicToolDef[] {
+  const out = tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.inputJsonSchema ?? zodToJsonSchema(t.inputSchema),
+  })) as AnthropicToolDef[];
+  if (opts.cacheLast && out.length > 0) {
+    out[out.length - 1]!.cache_control = { type: 'ephemeral' };
+  }
+  return out;
+}

package/src/validate.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it, vi } from 'vitest';
+import { validateKey } from './validate.js';
+
+describe('anthropic validateKey', () => {
+  it('rejects empty/short keys without any network call', async () => {
+    const make = vi.fn();
+    const res = await validateKey('', { client: make as never });
+    expect(res).toEqual({ ok: false, message: 'key looks too short' });
+    expect(make).not.toHaveBeenCalled();
+  });
+
+  it('success path issues a 1-token messages.create', async () => {
+    const create = vi.fn().mockResolvedValue({});
+    const make = vi.fn().mockReturnValue({ messages: { create } });
+    const res = await validateKey('sk-ant-very-long-test-key', { client: make });
+    expect(res).toEqual({ ok: true });
+    expect(make).toHaveBeenCalledWith('sk-ant-very-long-test-key');
+    expect(create).toHaveBeenCalledOnce();
+    const args = create.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(args.max_tokens).toBe(1);
+  });
+
+  it('SDK throw → ok:false with the underlying message', async () => {
+    const make = () => ({
+      messages: {
+        create: async () => {
+          throw new Error('401 invalid api key');
+        },
+      },
+    });
+    const res = await validateKey('sk-ant-bad-but-long-enough', { client: make });
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.message).toContain('401');
+  });
+
+  it('respects model override', async () => {
+    const create = vi.fn().mockResolvedValue({});
+    const make = () => ({ messages: { create } });
+    await validateKey('sk-ant-key-of-reasonable-length', { client: make, model: 'claude-opus-4-7' });
+    const args = create.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(args.model).toBe('claude-opus-4-7');
+  });
+});

package/src/validate.ts

@@ -0,0 +1,39 @@
+import Anthropic from '@anthropic-ai/sdk';
+
+export type ValidationResult = { ok: true } | { ok: false; message: string };
+
+export interface ValidateKeyDeps {
+  /** Inject the Anthropic SDK constructor for tests. */
+  readonly client?: (apiKey: string) => {
+    messages: { create: (args: Record<string, unknown>) => Promise<unknown> };
+  };
+  readonly model?: string;
+}
+
+/**
+ * "Is this key accepted by Anthropic?" Issues a 1-token completion — effectively
+ * free. Returns ok or a useful error message.
+ */
+export async function validateKey(key: string, deps: ValidateKeyDeps = {}): Promise<ValidationResult> {
+  if (!key || key.trim().length < 8) {
+    return { ok: false, message: 'key looks too short' };
+  }
+  const make = deps.client ?? defaultMaker;
+  try {
+    const client = make(key);
+    await client.messages.create({
+      model: deps.model ?? 'claude-haiku-4-5-20251001',
+      max_tokens: 1,
+      messages: [{ role: 'user', content: 'ping' }],
+    });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+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> };
+  };
+}