klaus-agent 0.1.0 → 0.2.0

package/src/providers/google.ts

@@ -0,0 +1,171 @@
+// Google Gemini LLM provider
+
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import type { Content, Part, FunctionDeclaration } from "@google/generative-ai";
+import type {
+  LLMProvider,
+  LLMRequestOptions,
+  AssistantMessageEvent,
+  AssistantMessage,
+  AssistantContentBlock,
+  TokenUsage,
+  Message,
+} from "../llm/types.js";
+import { generateId } from "../utils/id.js";
+import { withRetry, RETRYABLE_PATTERNS, mapThinkingBudget } from "./shared.js";
+
+export class GeminiProvider implements LLMProvider {
+  private client: GoogleGenerativeAI;
+  private baseUrl?: string;
+
+  constructor(apiKey?: string, baseUrl?: string) {
+    this.client = new GoogleGenerativeAI(apiKey || process.env.GOOGLE_API_KEY || "");
+    this.baseUrl = baseUrl;
+  }
+
+  async *stream(options: LLMRequestOptions): AsyncIterable<AssistantMessageEvent> {
+    yield* withRetry(() => this._streamOnce(options), RETRYABLE_PATTERNS.google);
+  }
+
+  private async *_streamOnce(options: LLMRequestOptions): AsyncIterable<AssistantMessageEvent> {
+    const { model: modelId, systemPrompt, messages, tools, thinkingLevel, maxTokens, signal } = options;
+
+    const thinkingBudget = mapThinkingBudget(thinkingLevel);
+
+    const genModel = this.client.getGenerativeModel(
+      {
+        model: modelId,
+        systemInstruction: systemPrompt,
+        ...(tools?.length ? {
+          tools: [{
+            functionDeclarations: tools.map((t): FunctionDeclaration => ({
+              name: t.name,
+              description: t.description,
+              parameters: t.inputSchema as any,
+            })),
+          }],
+        } : {}),
+        generationConfig: {
+          maxOutputTokens: maxTokens ?? 8192,
+          ...(thinkingBudget ? {
+            thinkingConfig: { thinkingBudget },
+          } as any : {}),
+        },
+      },
+      this.baseUrl ? { baseUrl: this.baseUrl } : undefined,
+    );
+
+    const contents = mapMessages(messages);
+    const result = await genModel.generateContentStream({ contents }, { signal });
+
+    const contentBlocks: AssistantContentBlock[] = [];
+    let usage: TokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+
+    for await (const chunk of result.stream) {
+      const text = chunk.text?.();
+      if (text) {
+        if (contentBlocks.length === 0 || contentBlocks[contentBlocks.length - 1].type !== "text") {
+          contentBlocks.push({ type: "text", text: "" });
+        }
+        const block = contentBlocks[contentBlocks.length - 1];
+        if (block.type === "text") {
+          block.text += text;
+        }
+        yield { type: "text", text };
+      }
+
+      // Function calls (Gemini returns them complete, not streamed)
+      const fnCalls = chunk.functionCalls?.();
+      if (fnCalls) {
+        for (const fc of fnCalls) {
+          const id = generateId();
+          const input = (fc.args ?? {}) as Record<string, unknown>;
+          contentBlocks.push({ type: "tool_call", id, name: fc.name, input });
+          yield { type: "tool_call_start", id, name: fc.name };
+          yield { type: "tool_call_delta", id, input: JSON.stringify(input) };
+        }
+      }
+
+      // Usage
+      if (chunk.usageMetadata) {
+        usage = {
+          inputTokens: chunk.usageMetadata.promptTokenCount ?? 0,
+          outputTokens: chunk.usageMetadata.candidatesTokenCount ?? 0,
+          totalTokens: chunk.usageMetadata.totalTokenCount ?? 0,
+        };
+      }
+    }
+
+    const message: AssistantMessage = { role: "assistant", content: contentBlocks };
+    yield { type: "done", message, usage };
+  }
+}
+
+function mapMessages(messages: Message[]): Content[] {
+  const contents: Content[] = [];
+
+  for (const m of messages) {
+    if (m.role === "user") {
+      const parts: Part[] = [];
+      if (typeof m.content === "string") {
+        parts.push({ text: m.content });
+      } else {
+        for (const block of m.content) {
+          if (block.type === "text") {
+            parts.push({ text: block.text });
+          } else if (block.type === "image" && block.source.type === "base64") {
+            parts.push({
+              inlineData: { mimeType: block.source.mediaType, data: block.source.data },
+            });
+          }
+        }
+      }
+      contents.push({ role: "user", parts });
+    } else if (m.role === "assistant") {
+      const parts: Part[] = [];
+      for (const block of m.content) {
+        if (block.type === "text") {
+          parts.push({ text: block.text });
+        } else if (block.type === "tool_call") {
+          parts.push({
+            functionCall: { name: block.name, args: block.input },
+          });
+        } else if (block.type === "thinking") {
+          parts.push({ text: block.thinking });
+        }
+      }
+      contents.push({ role: "model", parts });
+    } else {
+      // tool_result → functionResponse
+      // Need to find the tool name from previous assistant messages
+      const toolName = findToolName(messages, m.toolCallId) ?? "unknown";
+      const responseContent = typeof m.content === "string"
+        ? m.content
+        : m.content.map((b) => b.type === "text" ? b.text : JSON.stringify(b)).join("\n");
+      contents.push({
+        role: "user",
+        parts: [{
+          functionResponse: {
+            name: toolName,
+            response: { content: responseContent },
+          },
+        }],
+      });
+    }
+  }
+
+  return contents;
+}
+
+function findToolName(messages: Message[], toolCallId: string): string | undefined {
+  for (const m of messages) {
+    if (m.role === "assistant") {
+      for (const block of m.content) {
+        if (block.type === "tool_call" && block.id === toolCallId) {
+          return block.name;
+        }
+      }
+    }
+  }
+  return undefined;
+}

package/src/providers/index.ts

@@ -0,0 +1,6 @@
+export { AnthropicProvider } from "./anthropic.js";
+export { OpenAIProvider } from "./openai.js";
+export { GeminiProvider } from "./google.js";
+export { MiniMaxProvider } from "./minimax.js";
+export { KimiProvider } from "./kimi.js";
+export { VolcengineProvider } from "./volcengine.js";

package/src/providers/kimi.ts

@@ -0,0 +1,12 @@
+// Kimi LLM provider (Anthropic Messages API compatible)
+
+import { AnthropicProvider } from "./anthropic.js";
+
+export class KimiProvider extends AnthropicProvider {
+  constructor(apiKey?: string, baseUrl?: string) {
+    super(
+      apiKey ?? process.env.KIMI_API_KEY,
+      baseUrl ?? "https://api.kimi.com/coding",
+    );
+  }
+}

package/src/providers/minimax.ts

@@ -0,0 +1,12 @@
+// MiniMax LLM provider (Anthropic Messages API compatible)
+
+import { AnthropicProvider } from "./anthropic.js";
+
+export class MiniMaxProvider extends AnthropicProvider {
+  constructor(apiKey?: string, baseUrl?: string) {
+    super(
+      apiKey ?? process.env.MINIMAX_API_KEY,
+      baseUrl ?? "https://api.minimaxi.com/anthropic",
+    );
+  }
+}

package/src/providers/openai.ts

@@ -0,0 +1,197 @@
+// OpenAI LLM provider
+
+import OpenAI from "openai";
+import type {
+  LLMProvider,
+  LLMRequestOptions,
+  AssistantMessageEvent,
+  AssistantMessage,
+  AssistantContentBlock,
+  TokenUsage,
+  ThinkingLevel,
+  Message,
+} from "../llm/types.js";
+import { withRetry, RETRYABLE_PATTERNS } from "./shared.js";
+
+function mapReasoningEffort(level?: ThinkingLevel): "low" | "medium" | "high" | undefined {
+  if (!level || level === "off") return undefined;
+  if (level === "minimal" || level === "low") return "low";
+  if (level === "medium") return "medium";
+  return "high";
+}
+
+export class OpenAIProvider implements LLMProvider {
+  private client: OpenAI;
+
+  constructor(apiKey?: string, baseUrl?: string) {
+    this.client = new OpenAI({
+      apiKey: apiKey || process.env.OPENAI_API_KEY,
+      ...(baseUrl ? { baseURL: baseUrl } : {}),
+    });
+  }
+
+  async *stream(options: LLMRequestOptions): AsyncIterable<AssistantMessageEvent> {
+    yield* withRetry(() => this._streamOnce(options), RETRYABLE_PATTERNS.openai);
+  }
+
+  private async *_streamOnce(options: LLMRequestOptions): AsyncIterable<AssistantMessageEvent> {
+    const { model, systemPrompt, messages, tools, thinkingLevel, maxTokens, signal } = options;
+
+    const reasoningEffort = mapReasoningEffort(thinkingLevel);
+
+    const params: OpenAI.ChatCompletionCreateParamsStreaming = {
+      model,
+      messages: [
+        { role: "system" as const, content: systemPrompt },
+        ...messages.map((m) => mapMessage(m)),
+      ],
+      stream: true,
+      stream_options: { include_usage: true },
+      max_tokens: maxTokens ?? 8192,
+      ...(tools?.length ? {
+        tools: tools.map((t) => ({
+          type: "function" as const,
+          function: { name: t.name, description: t.description, parameters: t.inputSchema },
+        })),
+      } : {}),
+      ...(reasoningEffort ? { reasoning_effort: reasoningEffort } : {}),
+    };
+
+    const contentBlocks: AssistantContentBlock[] = [];
+    const toolCalls = new Map<number, { id: string; name: string; args: string }>();
+    let usage: TokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+
+    const stream = await this.client.chat.completions.create(params, { signal });
+
+    for await (const chunk of stream) {
+      const choice = chunk.choices?.[0];
+
+      if (choice?.delta) {
+        const delta = choice.delta;
+
+        // Text
+        if (delta.content) {
+          if (contentBlocks.length === 0 || contentBlocks[contentBlocks.length - 1].type !== "text") {
+            contentBlocks.push({ type: "text", text: "" });
+          }
+          const block = contentBlocks[contentBlocks.length - 1];
+          if (block.type === "text") {
+            block.text += delta.content;
+          }
+          yield { type: "text", text: delta.content };
+        }
+
+        // Reasoning/thinking content (o1/o3 series)
+        if ((delta as any).reasoning_content) {
+          const thinking = (delta as any).reasoning_content as string;
+          if (contentBlocks.length === 0 || contentBlocks[contentBlocks.length - 1].type !== "thinking") {
+            contentBlocks.push({ type: "thinking", thinking: "" });
+          }
+          const block = contentBlocks[contentBlocks.length - 1];
+          if (block.type === "thinking") {
+            block.thinking += thinking;
+          }
+          yield { type: "thinking", thinking };
+        }
+
+        // Tool calls
+        if (delta.tool_calls) {
+          for (const tc of delta.tool_calls) {
+            const idx = tc.index;
+            if (!toolCalls.has(idx)) {
+              // New tool call
+              const id = tc.id ?? `call_${idx}`;
+              const name = tc.function?.name ?? "";
+              toolCalls.set(idx, { id, name, args: "" });
+              contentBlocks.push({ type: "tool_call", id, name, input: {} });
+              yield { type: "tool_call_start", id, name };
+            }
+            if (tc.function?.arguments) {
+              const entry = toolCalls.get(idx)!;
+              entry.args += tc.function.arguments;
+              yield { type: "tool_call_delta", id: entry.id, input: tc.function.arguments };
+            }
+          }
+        }
+      }
+
+      // Usage info (comes in the final chunk with stream_options.include_usage)
+      if (chunk.usage) {
+        usage = {
+          inputTokens: chunk.usage.prompt_tokens,
+          outputTokens: chunk.usage.completion_tokens,
+          totalTokens: chunk.usage.total_tokens,
+        };
+      }
+    }
+
+    // Finalize tool call inputs
+    for (const [, entry] of toolCalls) {
+      const block = contentBlocks.find(
+        (b) => b.type === "tool_call" && b.id === entry.id,
+      );
+      if (block && block.type === "tool_call") {
+        try {
+          block.input = JSON.parse(entry.args || "{}");
+        } catch {
+          block.input = {};
+        }
+      }
+    }
+
+    const message: AssistantMessage = { role: "assistant", content: contentBlocks };
+    yield { type: "done", message, usage };
+  }
+}
+
+function mapMessage(m: Message): OpenAI.ChatCompletionMessageParam {
+  if (m.role === "user") {
+    if (typeof m.content === "string") {
+      return { role: "user", content: m.content };
+    }
+    const parts: OpenAI.ChatCompletionContentPart[] = m.content.map((block) => {
+      if (block.type === "text") {
+        return { type: "text" as const, text: block.text };
+      }
+      if (block.type === "image") {
+        if (block.source.type === "url") {
+          return { type: "image_url" as const, image_url: { url: block.source.url } };
+        }
+        return {
+          type: "image_url" as const,
+          image_url: { url: `data:${block.source.mediaType};base64,${block.source.data}` },
+        };
+      }
+      return { type: "text" as const, text: JSON.stringify(block) };
+    });
+    return { role: "user", content: parts };
+  }
+
+  if (m.role === "assistant") {
+    let text = "";
+    const toolCalls: OpenAI.ChatCompletionMessageToolCall[] = [];
+    for (const b of m.content) {
+      if (b.type === "text") {
+        text += b.text;
+      } else if (b.type === "tool_call") {
+        toolCalls.push({
+          id: b.id,
+          type: "function" as const,
+          function: { name: b.name, arguments: JSON.stringify(b.input) },
+        });
+      }
+    }
+    return {
+      role: "assistant",
+      content: text || null,
+      ...(toolCalls.length ? { tool_calls: toolCalls } : {}),
+    };
+  }
+
+  // tool_result
+  return {
+    role: "tool",
+    tool_call_id: m.toolCallId,
+    content: typeof m.content === "string" ? m.content : m.content.map((b) => b.type === "text" ? b.text : JSON.stringify(b)).join("\n"),
+  };
+}

package/src/providers/shared.ts

@@ -0,0 +1,60 @@
+// Shared streaming utilities for LLM providers
+
+import type { AssistantMessageEvent, ThinkingLevel } from "../llm/types.js";
+
+// Retryable error patterns common across providers
+const COMMON_RETRYABLE = ["429", "500", "503", "ECONNRESET"];
+
+export const RETRYABLE_PATTERNS: Record<string, string[]> = {
+  anthropic: [...COMMON_RETRYABLE, "rate_limit", "overloaded", "529"],
+  openai: [...COMMON_RETRYABLE, "rate_limit"],
+  google: [...COMMON_RETRYABLE],
+};
+
+export function isRetryableError(error: Error, patterns: string[]): boolean {
+  return patterns.some((p) => error.message.includes(p));
+}
+
+/**
+ * Wraps a streaming generator with exponential backoff retry logic.
+ * Only retries on connection-level failures before streaming starts.
+ */
+export async function* withRetry(
+  streamOnce: () => AsyncIterable<AssistantMessageEvent>,
+  retryablePatterns: string[],
+  maxRetries = 3,
+): AsyncIterable<AssistantMessageEvent> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (attempt > 0) {
+      const delay = Math.min(1000 * Math.pow(2, attempt - 1), 4000);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+
+    try {
+      yield* streamOnce();
+      return;
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+
+      if (!isRetryableError(lastError, retryablePatterns) || attempt === maxRetries) {
+        yield { type: "error", error: lastError };
+        return;
+      }
+    }
+  }
+}
+
+/** Maps ThinkingLevel to token budget (shared by Anthropic and Gemini). */
+export function mapThinkingBudget(level?: ThinkingLevel): number | undefined {
+  if (!level || level === "off") return undefined;
+  const budgets: Record<string, number> = {
+    minimal: 1024,
+    low: 4096,
+    medium: 10240,
+    high: 20480,
+    xhigh: 40960,
+  };
+  return budgets[level];
+}

package/src/providers/volcengine.ts

@@ -0,0 +1,12 @@
+// Volcengine (Doubao) LLM provider (OpenAI Chat Completions API compatible)
+
+import { OpenAIProvider } from "./openai.js";
+
+export class VolcengineProvider extends OpenAIProvider {
+  constructor(apiKey?: string, baseUrl?: string) {
+    super(
+      apiKey ?? process.env.VOLCENGINE_API_KEY,
+      baseUrl ?? "https://ark.cn-beijing.volces.com/api/v3",
+    );
+  }
+}