Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

11.2 KB
Raw Blame
// Claude (claude.ai) adapter. Parses the streamed response into a ChatTurn.
//
// claude.ai streams Server-Sent Events whose `data:` payloads are Anthropic
// streaming objects keyed by `type`:
//   message_start { message: { model, usage:{input_tokens, cache_creation_input_tokens, cache_read_input_tokens,
//                   cache_creation?:{ephemeral_5m_input_tokens, ephemeral_1h_input_tokens}} } }
//   content_block_start { index, content_block:{ type:'text'|'tool_use', id?, name? } }
//   content_block_delta { index, delta:{ type:'text_delta', text } | { type:'input_json_delta', partial_json } }
//   content_block_stop { index }
//   message_delta { delta:{ stop_reason }, usage:{ output_tokens, ...possibly the input counts again } }
//   message_stop
// A legacy shape ({ completion: "…delta" }) is also tolerated.
//
// claude.ai adds blocks of its own: `tool_result` (content_block_start carrying
// tool_use_id and the whole result as `content`, for tools it runs server side),
// `thinking` with thinking_summary_delta, and citation deltas on text blocks,
// plus `ping` and `message_limit` events. As of October 2026 it sends no
// `usage` at all. The request body is {prompt, model, ...}, sent gzip-compressed;
// the interceptor decompresses it (src/interceptor/request-body.ts).
//
// The exact claude.ai envelope must be confirmed against recorded live traffic
// (the live-smoke drift alarm exists for exactly this); the parser is written
// defensively so minor wrapping differences degrade gracefully.

import type { ChatTurn, Msg, ToolCall } from '../shared/types.js';
import { registerAdapter, type SiteAdapter, type TurnParser } from './adapter.js';
import { SSEParser } from './sse.js';
import { turnId } from '../shared/ids.js';

class ClaudeParser implements TurnParser {
  private sse = new SSEParser();
  private sessionId = '';
  private model?: string;
  private promptText = '';
  private inputMessages: Msg[] = [];
  private responseText = '';
  private inputTokens?: number;
  private outputTokens?: number;
  private cacheCreationInputTokens?: number;
  private cacheCreation1hInputTokens?: number;
  private cacheReadInputTokens?: number;
  private startedAt = Date.now();
  private completedAt?: number;
  private reqId: string;
  /** Stable per-turn id from message_start; used for turnId so ids don't collide
   *  across service-worker restarts (which reset the reqId counter). */
  private messageId = '';
  // tool_use blocks keyed by content-block index.
  private blocks = new Map<number, { type: string; tool?: ToolCall; argBuf: string }>();

  constructor(reqId: string) {
    this.reqId = reqId;
  }

  onRequest(url: string, _method: string, body: string | null): void {
    this.sessionId = conversationIdFromUrl(url) ?? this.sessionId;
    if (!body) return;
    try {
      const parsed = JSON.parse(body);
      const { text, messages } = extractPrompt(parsed);
      this.promptText = text;
      this.inputMessages = messages;
      if (typeof parsed?.model === 'string') this.model = parsed.model;
      if (typeof parsed?.conversation_id === 'string' && !this.sessionId)
        this.sessionId = parsed.conversation_id;
    } catch {
      // Non-JSON body — leave prompt empty; DOM fallback may fill it later.
    }
  }

  onChunk(chunk: string): void {
    for (const evt of this.sse.push(chunk)) this.handle(evt.data);
  }

  onDone(): void {
    for (const evt of this.sse.flush()) this.handle(evt.data);
    if (this.completedAt == null) this.completedAt = undefined; // stayed partial
  }

  private handle(data: string): void {
    if (!data || data === '[DONE]') return;
    let obj: any;
    try {
      obj = JSON.parse(data);
    } catch {
      return;
    }

    // Legacy delta shape.
    if (typeof obj.completion === 'string' && obj.type == null) {
      this.responseText += obj.completion;
      if (obj.stop_reason) this.completedAt = Date.now();
      return;
    }

    switch (obj.type) {
      case 'message_start': {
        const m = obj.message ?? {};
        if (typeof m.model === 'string') this.model = m.model;
        // The completion/message id is a per-turn id — capture it for turnId,
        // but never use it as the conversation/session id (that comes only from
        // the URL/request body; using message.id would mis-correlate turns).
        if (typeof m.uuid === 'string') this.messageId = m.uuid;
        else if (typeof m.id === 'string') this.messageId = m.id;
        this.readUsage(m.usage);
        break;
      }
      case 'content_block_start': {
        const cb = obj.content_block ?? {};
        const entry = { type: cb.type ?? 'text', argBuf: '' } as {
          type: string;
          tool?: ToolCall;
          argBuf: string;
        };
        if (cb.type === 'tool_use') {
          entry.tool = { id: String(cb.id ?? ''), name: String(cb.name ?? '') };
        } else if (cb.type === 'tool_result') {
          // claude.ai runs its tools (web search, weather, connectors) server
          // side and streams each result whole, as its own block naming the
          // tool_use it answers.
          const call = this.toolCall(cb.tool_use_id);
          if (call && cb.content !== undefined) call.result = cb.content;
        }
        this.blocks.set(obj.index ?? this.blocks.size, entry);
        break;
      }
      case 'content_block_delta': {
        const d = obj.delta ?? {};
        if (d.type === 'text_delta' && typeof d.text === 'string') {
          this.responseText += d.text;
        } else if (d.type === 'input_json_delta' && typeof d.partial_json === 'string') {
          const entry = this.blocks.get(obj.index);
          if (entry) entry.argBuf += d.partial_json;
        }
        break;
      }
      case 'message_delta': {
        // output_tokens is read only here. message_start carries a placeholder
        // of 1 rather than a count, so reading it there would report 1 output
        // token for any stream that aborts before message_delta -- worse than
        // the honest "unknown" that leaving it undefined gives.
        if (typeof obj.usage?.output_tokens === 'number') this.outputTokens = obj.usage.output_tokens;
        this.readUsage(obj.usage);
        break;
      }
      case 'message_stop': {
        this.completedAt = Date.now();
        break;
      }
    }
  }

  private toolCall(id: unknown): ToolCall | undefined {
    if (typeof id !== 'string' || id === '') return undefined;
    for (const entry of this.blocks.values()) if (entry.tool?.id === id) return entry.tool;
    return undefined;
  }

  /** Merge the input-side counts of an Anthropic `usage` object into the turn.
   *
   *  Read from both `message_start` and `message_delta` because which of the two
   *  carries them has moved between API versions: they have always been on
   *  `message_start`, and newer streams repeat them on `message_delta`. Each
   *  field is taken independently and only when numeric, so a payload carrying
   *  one of them never clears the others.
   *
   *  The three input counts are disjoint in Anthropic's usage object --
   *  `input_tokens` excludes both cached reads and cache writes -- which is
   *  already the disjointness `gen_ai.usage` requires, so nothing is subtracted
   *  here the way the Codex turn span needs.
   *
   *  output_tokens is deliberately not read here; see the message_delta case. */
  private readUsage(u: any): void {
    if (!u) return;
    if (typeof u.input_tokens === 'number') this.inputTokens = u.input_tokens;
    if (typeof u.cache_creation_input_tokens === 'number')
      this.cacheCreationInputTokens = u.cache_creation_input_tokens;
    // cache_creation breaks the writes down by TTL. Only the one-hour part is
    // kept: it is billed at 2x input against 1.25x for five-minute writes, and
    // the five-minute part is the remainder.
    if (typeof u.cache_creation?.ephemeral_1h_input_tokens === 'number')
      this.cacheCreation1hInputTokens = u.cache_creation.ephemeral_1h_input_tokens;
    if (typeof u.cache_read_input_tokens === 'number')
      this.cacheReadInputTokens = u.cache_read_input_tokens;
  }

  getTurn(): ChatTurn | null {
    if (!this.responseText && this.blocks.size === 0 && !this.promptText) return null;
    const toolCalls: ToolCall[] = [];
    for (const entry of this.blocks.values()) {
      if (entry.tool) {
        let args: unknown = entry.argBuf;
        try {
          args = entry.argBuf ? JSON.parse(entry.argBuf) : undefined;
        } catch {
          /* keep raw string */
        }
        toolCalls.push({ ...entry.tool, arguments: args });
      }
    }
    // Session id comes only from the conversation id (URL/body). If truly
    // absent, use a clearly-synthetic per-stream id — never the message id.
    const sessionId = this.sessionId || `claude-unknown-${this.reqId}`;
    // Turn key prefers the stable assistant message id; falls back to the
    // interceptor's per-page reqId only when message_start was never seen.
    const turnKey = this.messageId || `r${this.reqId}`;
    return {
      site: 'claude_web',
      sessionId,
      turnId: turnId(sessionId, turnKey),
      requestModel: this.model,
      responseModel: this.model,
      promptText: this.promptText,
      inputMessages: this.inputMessages,
      outputMessages: [{ role: 'assistant', text: this.responseText }],
      responseText: this.responseText,
      toolCalls,
      usage: {
        inputTokens: this.inputTokens,
        outputTokens: this.outputTokens,
        cacheCreationInputTokens: this.cacheCreationInputTokens,
        cacheCreation1hInputTokens: this.cacheCreation1hInputTokens,
        cacheReadInputTokens: this.cacheReadInputTokens,
      },
      startedAt: this.startedAt,
      completedAt: this.completedAt,
      captureMode: 'sse',
    };
  }
}

function conversationIdFromUrl(url: string): string | undefined {
  const m = url.match(/chat_conversations\/([0-9a-f-]{16,})/i);
  return m?.[1];
}

/** Pull prompt text + input messages from a variety of request-body shapes. */
function extractPrompt(body: any): { text: string; messages: Msg[] } {
  const messages: Msg[] = [];
  let text = '';
  if (typeof body?.prompt === 'string') {
    // A retry_completion (regenerate) sends an empty prompt: no new message.
    text = body.prompt;
    if (text) messages.push({ role: 'user', text });
  } else if (Array.isArray(body?.messages)) {
    for (const m of body.messages) {
      const t = coerceContent(m?.content);
      messages.push({ role: normalizeRole(m?.role), text: t });
      if (m?.role === 'user') text = t;
    }
  }
  return { text, messages };
}

function coerceContent(content: unknown): string {
  if (typeof content === 'string') return content;
  if (Array.isArray(content)) {
    return content
      .map((p: any) => (typeof p === 'string' ? p : typeof p?.text === 'string' ? p.text : ''))
      .join('');
  }
  return '';
}

function normalizeRole(role: unknown): Msg['role'] {
  return role === 'assistant' || role === 'system' || role === 'tool' ? role : 'user';
}

export const claudeAdapter: SiteAdapter = {
  name: 'claude_web',
  matchesHost: (host) => host === 'claude.ai' || host.endsWith('.claude.ai'),
  matchesRequest: (url, method) =>
    /chat_conversations\/.+\/(completion|retry_completion)/.test(url) &&
    method.toUpperCase() === 'POST',
  createParser: (reqId) => new ClaudeParser(reqId),
};

registerAdapter(claudeAdapter);