@yeaft/webchat-agent 0.1.399 → 0.1.409

package/unify/llm/adapter.js

@@ -0,0 +1,186 @@
+/**
+ * adapter.js — LLM Adapter base class, unified types, and factory
+ *
+ * Design decision (2026-04-10): Only two adapters needed:
+ *   1. AnthropicAdapter — Anthropic Messages API
+ *   2. ChatCompletionsAdapter — OpenAI Chat Completions API (covers GPT, DeepSeek, CopilotProxy, etc.)
+ *
+ * The engine sees only unified types — it never knows which API is underneath.
+ */
+
+// ─── Unified Types ─────────────────────────────────────────────
+
+/**
+ * @typedef {Object} UnifiedToolDef
+ * @property {string} name
+ * @property {string} description
+ * @property {object} parameters — JSON Schema
+ */
+
+/**
+ * @typedef {Object} UnifiedToolCall
+ * @property {string} id
+ * @property {string} name
+ * @property {object} input — Parsed object (not JSON string)
+ */
+
+/**
+ * @typedef {Object} UnifiedToolResult
+ * @property {string} toolCallId
+ * @property {string} output
+ * @property {boolean} [isError]
+ */
+
+// ─── Unified Event Stream ──────────────────────────────────────
+
+/**
+ * @typedef {{ type: 'text_delta', text: string }} TextDeltaEvent
+ * @typedef {{ type: 'thinking_delta', text: string }} ThinkingDeltaEvent
+ * @typedef {{ type: 'tool_call', id: string, name: string, input: object }} ToolCallEvent
+ * @typedef {{ type: 'usage', inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWriteTokens?: number }} UsageEvent
+ * @typedef {{ type: 'stop', stopReason: 'end_turn' | 'tool_use' | 'max_tokens' }} StopEvent
+ * @typedef {{ type: 'error', error: Error, retryable: boolean }} ErrorEvent
+ *
+ * @typedef {TextDeltaEvent | ThinkingDeltaEvent | ToolCallEvent | UsageEvent | StopEvent | ErrorEvent} StreamEvent
+ */
+
+// ─── Unified Message Types ─────────────────────────────────────
+
+/**
+ * @typedef {{ role: 'system', content: string }} SystemMessage
+ * @typedef {{ role: 'user', content: string }} UserMessage
+ * @typedef {{ role: 'assistant', content: string, toolCalls?: UnifiedToolCall[] }} AssistantMessage
+ * @typedef {{ role: 'tool', toolCallId: string, content: string, isError?: boolean }} ToolMessage
+ *
+ * @typedef {SystemMessage | UserMessage | AssistantMessage | ToolMessage} UnifiedMessage
+ */
+
+// ─── Error Types ───────────────────────────────────────────────
+
+/** Rate limit error (429, 529) — retryable with backoff. */
+export class LLMRateLimitError extends Error {
+  constructor(message, statusCode, retryAfterMs = null) {
+    super(message);
+    this.name = 'LLMRateLimitError';
+    this.statusCode = statusCode;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/** Authentication error (401, 403) — need to re-authenticate. */
+export class LLMAuthError extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.name = 'LLMAuthError';
+    this.statusCode = statusCode;
+  }
+}
+
+/** Context too long error (413 or API-specific) — need compaction. */
+export class LLMContextError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'LLMContextError';
+  }
+}
+
+/** Server error (500, 502, 503) — retryable. */
+export class LLMServerError extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.name = 'LLMServerError';
+    this.statusCode = statusCode;
+  }
+}
+
+/** Abort error — signal was aborted. */
+export class LLMAbortError extends Error {
+  constructor() {
+    super('Request aborted');
+    this.name = 'LLMAbortError';
+  }
+}
+
+// ─── Base Class ────────────────────────────────────────────────
+
+/**
+ * LLMAdapter — Abstract base class for LLM API adapters.
+ *
+ * Subclasses implement stream() and call() to talk to a specific API,
+ * translating between the unified types and the wire format.
+ */
+export class LLMAdapter {
+  /**
+   * @param {object} config — Adapter-specific configuration
+   */
+  constructor(config = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Stream a model response with tool support (the query loop call).
+   *
+   * @param {{ model: string, system: string, messages: UnifiedMessage[], tools?: UnifiedToolDef[], maxTokens?: number, signal?: AbortSignal }} params
+   * @returns {AsyncGenerator<StreamEvent>}
+   */
+  async *stream(params) { // eslint-disable-line no-unused-vars
+    throw new Error('stream() must be implemented by subclass');
+  }
+
+  /**
+   * Make a single model call without tools (for side queries like summarization).
+   *
+   * @param {{ model: string, system: string, messages: UnifiedMessage[], maxTokens?: number, signal?: AbortSignal }} params
+   * @returns {Promise<{ text: string, usage: { inputTokens: number, outputTokens: number } }>}
+   */
+  async call(params) { // eslint-disable-line no-unused-vars
+    throw new Error('call() must be implemented by subclass');
+  }
+}
+
+// ─── Factory ───────────────────────────────────────────────────
+
+/**
+ * Create an LLM adapter based on configuration.
+ *
+ * @param {object} config — From loadConfig()
+ * @returns {Promise<LLMAdapter>}
+ */
+export async function createLLMAdapter(config) {
+  // Normalize adapter name — accept 'chat-completions' as alias for 'openai'
+  const adapter = config.adapter === 'chat-completions' ? 'openai' : config.adapter;
+
+  if (adapter === 'anthropic' || (!adapter && config.apiKey)) {
+    if (!config.apiKey) {
+      throw new Error('Anthropic adapter requires YEAFT_API_KEY');
+    }
+    const { AnthropicAdapter } = await import('./anthropic.js');
+    return new AnthropicAdapter({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl || undefined, // AnthropicAdapter has its own default
+    });
+  }
+
+  if (adapter === 'openai' || (!adapter && config.openaiApiKey)) {
+    if (!config.openaiApiKey && !config.apiKey) {
+      throw new Error('OpenAI adapter requires YEAFT_OPENAI_API_KEY (or YEAFT_API_KEY as fallback)');
+    }
+    const { ChatCompletionsAdapter } = await import('./chat-completions.js');
+    return new ChatCompletionsAdapter({
+      apiKey: config.openaiApiKey || config.apiKey,
+      baseUrl: config.baseUrl || 'https://api.openai.com/v1',
+    });
+  }
+
+  if (adapter === 'proxy' || (!adapter && config.proxyUrl)) {
+    const { ChatCompletionsAdapter } = await import('./chat-completions.js');
+    return new ChatCompletionsAdapter({
+      apiKey: 'proxy', // CopilotProxy handles auth
+      baseUrl: `${config.proxyUrl}/v1`,
+    });
+  }
+
+  throw new Error(
+    'No LLM adapter configured. Set YEAFT_API_KEY (Anthropic), YEAFT_OPENAI_API_KEY (OpenAI), or YEAFT_PROXY_URL (CopilotProxy).',
+  );
+}

package/unify/llm/anthropic.js

@@ -0,0 +1,322 @@
+/**
+ * anthropic.js — Anthropic Messages API adapter
+ *
+ * POST /v1/messages with SSE streaming.
+ * tool_use.input is already a parsed object (no JSON.parse needed).
+ * Tool definitions use `input_schema` (not `parameters`).
+ */
+
+import {
+  LLMAdapter,
+  LLMRateLimitError,
+  LLMAuthError,
+  LLMContextError,
+  LLMServerError,
+  LLMAbortError,
+} from './adapter.js';
+
+const DEFAULT_BASE_URL = 'https://api.anthropic.com';
+const API_VERSION = '2023-06-01';
+
+/**
+ * AnthropicAdapter — Talks to Anthropic Messages API.
+ */
+export class AnthropicAdapter extends LLMAdapter {
+  #apiKey;
+  #baseUrl;
+
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL }) {
+    super({ apiKey, baseUrl });
+    this.#apiKey = apiKey;
+    this.#baseUrl = baseUrl;
+  }
+
+  /**
+   * Translate UnifiedToolDef[] → Anthropic tool format.
+   * @param {import('./adapter.js').UnifiedToolDef[]} tools
+   * @returns {object[]}
+   */
+  #translateTools(tools) {
+    if (!tools || tools.length === 0) return undefined;
+    return tools.map(t => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.parameters,
+    }));
+  }
+
+  /**
+   * Translate UnifiedMessage[] → Anthropic message format.
+   * @param {import('./adapter.js').UnifiedMessage[]} messages
+   * @returns {object[]}
+   */
+  #translateMessages(messages) {
+    const result = [];
+    for (const msg of messages) {
+      if (msg.role === 'system') continue; // system goes separately
+      if (msg.role === 'user') {
+        result.push({ role: 'user', content: msg.content });
+      } else if (msg.role === 'assistant') {
+        const content = [];
+        if (msg.content) {
+          content.push({ type: 'text', text: msg.content });
+        }
+        if (msg.toolCalls) {
+          for (const tc of msg.toolCalls) {
+            content.push({
+              type: 'tool_use',
+              id: tc.id,
+              name: tc.name,
+              input: tc.input,
+            });
+          }
+        }
+        result.push({ role: 'assistant', content });
+      } else if (msg.role === 'tool') {
+        // Anthropic requires all tool_results from the same turn in a single
+        // user message. Merge consecutive tool messages into one.
+        const toolResult = {
+          type: 'tool_result',
+          tool_use_id: msg.toolCallId,
+          content: msg.content,
+          is_error: msg.isError || false,
+        };
+        const prev = result[result.length - 1];
+        if (prev && prev.role === 'user' && Array.isArray(prev.content) &&
+            prev.content.length > 0 && prev.content[0].type === 'tool_result') {
+          // Append to existing tool_result user message
+          prev.content.push(toolResult);
+        } else {
+          result.push({
+            role: 'user',
+            content: [toolResult],
+          });
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Classify HTTP errors into our typed errors.
+   * @param {number} status
+   * @param {string} body
+   */
+  #classifyError(status, body) {
+    if (status === 401 || status === 403) {
+      return new LLMAuthError(`Anthropic auth error: ${body}`, status);
+    }
+    if (status === 429) {
+      const retryAfter = null; // Could parse retry-after header
+      return new LLMRateLimitError(`Anthropic rate limit: ${body}`, status, retryAfter);
+    }
+    if (status === 529) {
+      return new LLMRateLimitError(`Anthropic overloaded: ${body}`, status);
+    }
+    if (body.includes('prompt is too long') || body.includes('max_tokens')) {
+      return new LLMContextError(`Anthropic context error: ${body}`);
+    }
+    if (status >= 500) {
+      return new LLMServerError(`Anthropic server error: ${body}`, status);
+    }
+    return new Error(`Anthropic API error ${status}: ${body}`);
+  }
+
+  /**
+   * @param {{ model: string, system: string, messages: import('./adapter.js').UnifiedMessage[], tools?: import('./adapter.js').UnifiedToolDef[], maxTokens?: number, signal?: AbortSignal }} params
+   * @returns {AsyncGenerator<import('./adapter.js').StreamEvent>}
+   */
+  async *stream({ model, system, messages, tools, maxTokens = 16384, signal }) {
+    if (signal?.aborted) throw new LLMAbortError();
+
+    const body = {
+      model,
+      max_tokens: maxTokens,
+      system,
+      messages: this.#translateMessages(messages),
+      stream: true,
+    };
+
+    const translatedTools = this.#translateTools(tools);
+    if (translatedTools) body.tools = translatedTools;
+
+    const response = await fetch(`${this.#baseUrl}/v1/messages`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': this.#apiKey,
+        'anthropic-version': API_VERSION,
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw this.#classifyError(response.status, errorBody);
+    }
+
+    // Parse SSE stream
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let currentToolCallId = null;
+    let currentToolName = null;
+    let currentToolInput = '';
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || ''; // Keep incomplete line
+
+        for (const line of lines) {
+          if (!line.startsWith('data: ')) continue;
+          const data = line.slice(6).trim();
+          if (data === '[DONE]') continue;
+
+          let event;
+          try {
+            event = JSON.parse(data);
+          } catch {
+            continue;
+          }
+
+          const type = event.type;
+
+          if (type === 'content_block_start') {
+            const block = event.content_block;
+            if (block?.type === 'tool_use') {
+              currentToolCallId = block.id;
+              currentToolName = block.name;
+              currentToolInput = '';
+            }
+          } else if (type === 'content_block_delta') {
+            const delta = event.delta;
+            if (delta?.type === 'text_delta') {
+              yield { type: 'text_delta', text: delta.text };
+            } else if (delta?.type === 'thinking_delta') {
+              yield { type: 'thinking_delta', text: delta.thinking };
+            } else if (delta?.type === 'input_json_delta') {
+              currentToolInput += delta.partial_json;
+            }
+          } else if (type === 'content_block_stop') {
+            if (currentToolCallId) {
+              let parsedInput = {};
+              try {
+                parsedInput = currentToolInput ? JSON.parse(currentToolInput) : {};
+              } catch {
+                parsedInput = {};
+              }
+              yield {
+                type: 'tool_call',
+                id: currentToolCallId,
+                name: currentToolName,
+                input: parsedInput,
+              };
+              currentToolCallId = null;
+              currentToolName = null;
+              currentToolInput = '';
+            }
+          } else if (type === 'message_delta') {
+            const stopReason = event.delta?.stop_reason;
+            if (stopReason) {
+              yield {
+                type: 'stop',
+                stopReason: this.#mapStopReason(stopReason),
+              };
+            }
+            // Usage from message_delta
+            if (event.usage) {
+              yield {
+                type: 'usage',
+                inputTokens: 0, // Only in message_start
+                outputTokens: event.usage.output_tokens || 0,
+              };
+            }
+          } else if (type === 'message_start') {
+            // Usage from message_start
+            if (event.message?.usage) {
+              yield {
+                type: 'usage',
+                inputTokens: event.message.usage.input_tokens || 0,
+                outputTokens: event.message.usage.output_tokens || 0,
+                cacheReadTokens: event.message.usage.cache_read_input_tokens || 0,
+                cacheWriteTokens: event.message.usage.cache_creation_input_tokens || 0,
+              };
+            }
+          } else if (type === 'error') {
+            yield {
+              type: 'error',
+              error: new Error(event.error?.message || 'Unknown streaming error'),
+              retryable: event.error?.type === 'overloaded_error',
+            };
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  /**
+   * Non-streaming call for side queries.
+   */
+  async call({ model, system, messages, maxTokens = 4096, signal }) {
+    if (signal?.aborted) throw new LLMAbortError();
+
+    const body = {
+      model,
+      max_tokens: maxTokens,
+      system,
+      messages: this.#translateMessages(messages),
+    };
+
+    const response = await fetch(`${this.#baseUrl}/v1/messages`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': this.#apiKey,
+        'anthropic-version': API_VERSION,
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw this.#classifyError(response.status, errorBody);
+    }
+
+    const result = await response.json();
+    const text = result.content
+      ?.filter(b => b.type === 'text')
+      .map(b => b.text)
+      .join('') || '';
+
+    return {
+      text,
+      usage: {
+        inputTokens: result.usage?.input_tokens || 0,
+        outputTokens: result.usage?.output_tokens || 0,
+      },
+    };
+  }
+
+  /**
+   * Map Anthropic stop_reason to unified format.
+   * @param {string} reason
+   * @returns {'end_turn' | 'tool_use' | 'max_tokens'}
+   */
+  #mapStopReason(reason) {
+    switch (reason) {
+      case 'end_turn': return 'end_turn';
+      case 'tool_use': return 'tool_use';
+      case 'max_tokens': return 'max_tokens';
+      default: return 'end_turn';
+    }
+  }
+}