@charming_groot/providers 0.1.0

package/src/openai-provider.ts

@@ -0,0 +1,239 @@
+import OpenAI from 'openai';
+import type {
+  Message,
+  LlmResponse,
+  StreamEvent,
+  ToolDescription,
+  ToolCall,
+  ProviderConfig,
+} from '@charming_groot/core';
+import { ProviderError } from '@charming_groot/core';
+import { BaseProvider } from './base-provider.js';
+import { extractToken } from './auth/auth-resolver.js';
+import { extractThinkTag, estimateThinkingMs } from './thinking-parser.js';
+
+export class OpenAIProvider extends BaseProvider {
+  readonly providerId = 'openai';
+  private readonly client: OpenAI;
+  private readonly model: string;
+  private readonly maxTokens: number;
+  private readonly temperature: number;
+
+  constructor(config: ProviderConfig) {
+    super('openai-provider');
+    const apiKey = extractToken(config.auth);
+    this.client = new OpenAI({ apiKey, baseURL: config.baseUrl });
+    this.model = config.model;
+    this.maxTokens = config.maxTokens;
+    this.temperature = config.temperature;
+  }
+
+  async chat(
+    messages: readonly Message[],
+    tools?: readonly ToolDescription[]
+  ): Promise<LlmResponse> {
+    try {
+      const response = await this.client.chat.completions.create({
+        model: this.model,
+        max_tokens: this.maxTokens,
+        temperature: this.temperature,
+        messages: this.toOpenAIMessages(messages),
+        tools: tools && tools.length > 0 ? this.toOpenAITools(tools) : undefined,
+      });
+
+      return this.parseResponse(response);
+    } catch (error) {
+      throw new ProviderError(
+        `OpenAI API error: ${error instanceof Error ? error.message : String(error)}`,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  async *stream(
+    messages: readonly Message[],
+    tools?: readonly ToolDescription[]
+  ): AsyncIterable<StreamEvent> {
+    try {
+      const stream = await this.client.chat.completions.create({
+        model: this.model,
+        max_tokens: this.maxTokens,
+        temperature: this.temperature,
+        messages: this.toOpenAIMessages(messages),
+        tools: tools && tools.length > 0 ? this.toOpenAITools(tools) : undefined,
+        stream: true,
+      });
+
+      let content = '';
+      const toolCalls: ToolCall[] = [];
+      let inputTokens = 0;
+      let outputTokens = 0;
+
+      for await (const chunk of stream) {
+        const delta = chunk.choices[0]?.delta;
+        if (!delta) continue;
+
+        if (delta.content) {
+          content += delta.content;
+          yield { type: 'text_delta', content: delta.content };
+        }
+
+        if (delta.tool_calls) {
+          for (const tc of delta.tool_calls) {
+            if (tc.id) {
+              toolCalls.push({
+                id: tc.id,
+                name: tc.function?.name ?? '',
+                arguments: tc.function?.arguments ?? '',
+              });
+              yield {
+                type: 'tool_call_start',
+                toolCall: { id: tc.id, name: tc.function?.name },
+              };
+            } else if (tc.function?.arguments) {
+              const last = toolCalls[toolCalls.length - 1];
+              if (last) {
+                toolCalls[toolCalls.length - 1] = {
+                  ...last,
+                  arguments: last.arguments + tc.function.arguments,
+                };
+              }
+              yield { type: 'tool_call_delta', content: tc.function.arguments };
+            }
+          }
+        }
+
+        if (chunk.usage) {
+          inputTokens = chunk.usage.prompt_tokens;
+          outputTokens = chunk.usage.completion_tokens;
+        }
+
+        if (chunk.choices[0]?.finish_reason) {
+          const stopReason =
+            chunk.choices[0].finish_reason === 'tool_calls'
+              ? 'tool_use' as const
+              : chunk.choices[0].finish_reason === 'length'
+                ? 'max_tokens' as const
+                : 'end_turn' as const;
+
+          yield {
+            type: 'done',
+            response: {
+              content,
+              stopReason,
+              toolCalls,
+              usage: { inputTokens, outputTokens },
+            },
+          };
+        }
+      }
+    } catch (error) {
+      throw new ProviderError(
+        `OpenAI stream error: ${error instanceof Error ? error.message : String(error)}`,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  private toOpenAIMessages(
+    messages: readonly Message[]
+  ): OpenAI.ChatCompletionMessageParam[] {
+    const result: OpenAI.ChatCompletionMessageParam[] = [];
+
+    for (const msg of messages) {
+      if (msg.role === 'system') {
+        result.push({ role: 'system', content: msg.content });
+      } else if (msg.toolResults && msg.toolResults.length > 0) {
+        for (const tr of msg.toolResults) {
+          result.push({
+            role: 'tool',
+            tool_call_id: tr.toolCallId,
+            content: tr.content,
+          });
+        }
+      } else if (msg.role === 'assistant' && msg.toolCalls && msg.toolCalls.length > 0) {
+        result.push({
+          role: 'assistant',
+          content: msg.content || null,
+          tool_calls: msg.toolCalls.map((tc) => ({
+            id: tc.id,
+            type: 'function' as const,
+            function: { name: tc.name, arguments: tc.arguments },
+          })),
+        });
+      } else if (msg.role === 'assistant') {
+        result.push({ role: 'assistant', content: msg.content });
+      } else {
+        result.push({ role: 'user', content: msg.content });
+      }
+    }
+
+    return result;
+  }
+
+  private toOpenAITools(
+    tools: readonly ToolDescription[]
+  ): OpenAI.ChatCompletionTool[] {
+    return tools.map((tool) => ({
+      type: 'function' as const,
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: {
+          type: 'object',
+          properties: Object.fromEntries(
+            tool.parameters.map((p) => [
+              p.name,
+              { type: p.type, description: p.description },
+            ])
+          ),
+          required: tool.parameters
+            .filter((p) => p.required)
+            .map((p) => p.name),
+        },
+      },
+    }));
+  }
+
+  private parseResponse(
+    response: OpenAI.ChatCompletion
+  ): LlmResponse {
+    const choice = response.choices[0];
+    if (!choice) {
+      throw new ProviderError('No choices in OpenAI response');
+    }
+
+    const toolCalls: ToolCall[] = (choice.message.tool_calls ?? []).map((tc) => ({
+      id: tc.id,
+      name: tc.function.name,
+      arguments: tc.function.arguments,
+    }));
+
+    const stopReason =
+      choice.finish_reason === 'tool_calls'
+        ? 'tool_use' as const
+        : choice.finish_reason === 'length'
+          ? 'max_tokens' as const
+          : 'end_turn' as const;
+
+    let content = choice.message.content ?? '';
+    let thinkingMs: number | undefined;
+
+    const parsed = extractThinkTag(content);
+    if (parsed.thinkContent) {
+      content = parsed.cleanContent;
+      thinkingMs = estimateThinkingMs(parsed.thinkContent);
+    }
+
+    return {
+      content,
+      stopReason,
+      toolCalls,
+      usage: {
+        inputTokens: response.usage?.prompt_tokens ?? 0,
+        outputTokens: response.usage?.completion_tokens ?? 0,
+        thinkingMs,
+      },
+    };
+  }
+}

package/src/provider-factory.ts

@@ -0,0 +1,48 @@
+import type { ILlmProvider, ProviderConfig } from '@charming_groot/core';
+import { Registry, ProviderError } from '@charming_groot/core';
+import { ClaudeProvider } from './claude-provider.js';
+import { OpenAIProvider } from './openai-provider.js';
+import { RetryProvider } from './retry-provider.js';
+import { CircuitBreakerProvider } from './circuit-breaker.js';
+
+type ProviderConstructor = new (config: ProviderConfig) => ILlmProvider;
+
+const providerRegistry = new Registry<ProviderConstructor>('Provider');
+
+providerRegistry.register('claude', ClaudeProvider);
+providerRegistry.register('openai', OpenAIProvider);
+providerRegistry.register('vllm', OpenAIProvider);
+providerRegistry.register('ollama', OpenAIProvider);
+providerRegistry.register('custom', OpenAIProvider);
+
+/**
+ * Creates a provider wrapped with RetryProvider → CircuitBreakerProvider.
+ *
+ * Request flow:
+ *   AgentLoop → CircuitBreakerProvider → RetryProvider → actual provider
+ *
+ * CircuitBreaker is outermost so it sees already-retried failures,
+ * preventing the circuit from tripping on transient single errors.
+ */
+export function createProvider(config: ProviderConfig): ILlmProvider {
+  const Constructor = providerRegistry.tryGet(config.providerId);
+  if (!Constructor) {
+    throw new ProviderError(
+      `Unknown provider: '${config.providerId}'. Available: ${providerRegistry.getAllNames().join(', ')}`
+    );
+  }
+  const provider = new Constructor(config);
+  const withRetry = new RetryProvider(provider);
+  return new CircuitBreakerProvider(withRetry);
+}
+
+export function registerProvider(
+  id: string,
+  constructor: ProviderConstructor
+): void {
+  providerRegistry.register(id, constructor);
+}
+
+export function getProviderRegistry(): Registry<ProviderConstructor> {
+  return providerRegistry;
+}

package/src/retry-provider.ts

@@ -0,0 +1,135 @@
+import type {
+  ILlmProvider,
+  Message,
+  LlmResponse,
+  StreamEvent,
+  ToolDescription,
+  AgentLogger,
+} from '@charming_groot/core';
+import { ProviderError, createChildLogger } from '@charming_groot/core';
+
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 30000;
+
+export interface RetryConfig {
+  /** Maximum number of retry attempts (default: 3) */
+  readonly maxRetries?: number;
+  /** Base delay in ms for exponential backoff (default: 1000) */
+  readonly baseDelayMs?: number;
+  /** Maximum delay in ms (default: 30000) */
+  readonly maxDelayMs?: number;
+}
+
+function isRetryable(error: unknown): boolean {
+  if (error instanceof ProviderError) {
+    const msg = error.message.toLowerCase();
+    return (
+      msg.includes('rate limit') ||
+      msg.includes('429') ||
+      msg.includes('too many requests') ||
+      msg.includes('overloaded') ||
+      msg.includes('529') ||
+      msg.includes('timeout') ||
+      msg.includes('econnreset') ||
+      msg.includes('socket hang up') ||
+      msg.includes('503') ||
+      msg.includes('500')
+    );
+  }
+
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+    return (
+      msg.includes('econnreset') ||
+      msg.includes('etimedout') ||
+      msg.includes('socket hang up') ||
+      msg.includes('fetch failed')
+    );
+  }
+
+  return false;
+}
+
+function computeDelay(attempt: number, baseMs: number, maxMs: number): number {
+  const exponential = baseMs * Math.pow(2, attempt);
+  const jitter = Math.random() * baseMs;
+  return Math.min(exponential + jitter, maxMs);
+}
+
+/**
+ * Wraps an ILlmProvider with retry logic and exponential backoff.
+ * Retries on rate limits, transient network errors, and server errors.
+ */
+export class RetryProvider implements ILlmProvider {
+  readonly providerId: string;
+  private readonly inner: ILlmProvider;
+  private readonly maxRetries: number;
+  private readonly baseDelayMs: number;
+  private readonly maxDelayMs: number;
+  private readonly logger: AgentLogger;
+
+  constructor(provider: ILlmProvider, config?: RetryConfig) {
+    this.inner = provider;
+    this.providerId = provider.providerId;
+    this.maxRetries = config?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.baseDelayMs = config?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    this.maxDelayMs = config?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    this.logger = createChildLogger('retry-provider');
+  }
+
+  async chat(
+    messages: readonly Message[],
+    tools?: readonly ToolDescription[]
+  ): Promise<LlmResponse> {
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await this.inner.chat(messages, tools);
+      } catch (error) {
+        lastError = error;
+        if (attempt < this.maxRetries && isRetryable(error)) {
+          const delay = computeDelay(attempt, this.baseDelayMs, this.maxDelayMs);
+          this.logger.warn(
+            { attempt: attempt + 1, maxRetries: this.maxRetries, delayMs: Math.round(delay) },
+            'Retrying after transient error'
+          );
+          await new Promise(resolve => setTimeout(resolve, delay));
+          continue;
+        }
+        throw error;
+      }
+    }
+
+    throw lastError;
+  }
+
+  async *stream(
+    messages: readonly Message[],
+    tools?: readonly ToolDescription[]
+  ): AsyncIterable<StreamEvent> {
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        yield* this.inner.stream(messages, tools);
+        return;
+      } catch (error) {
+        lastError = error;
+        if (attempt < this.maxRetries && isRetryable(error)) {
+          const delay = computeDelay(attempt, this.baseDelayMs, this.maxDelayMs);
+          this.logger.warn(
+            { attempt: attempt + 1, maxRetries: this.maxRetries, delayMs: Math.round(delay) },
+            'Retrying stream after transient error'
+          );
+          await new Promise(resolve => setTimeout(resolve, delay));
+          continue;
+        }
+        throw error;
+      }
+    }
+
+    throw lastError;
+  }
+}

package/src/thinking-parser.ts

@@ -0,0 +1,50 @@
+/**
+ * Parsing utilities for extended thinking / <think> blocks.
+ *
+ * Supports:
+ * - <think>...</think> tags (DeepSeek, Qwen, etc.)
+ * - Anthropic extended thinking content blocks (handled in provider)
+ *
+ * The thinkingMs is estimated from content length since the API
+ * does not provide wall-clock timing for the thinking phase.
+ */
+
+const THINK_TAG_REGEX = /^<think>([\s\S]*?)<\/think>\s*/;
+
+/** Tokens per second estimate for thinking content */
+const THINKING_TOKENS_PER_SEC = 80;
+/** Characters per token estimate */
+const CHARS_PER_TOKEN = 4;
+
+export interface ThinkTagResult {
+  /** The content inside <think> tags, or undefined if no tags found */
+  readonly thinkContent: string | undefined;
+  /** The remaining content after removing <think> tags */
+  readonly cleanContent: string;
+}
+
+/**
+ * Extract <think>...</think> block from the beginning of content.
+ * Returns the thinking content and cleaned content separately.
+ */
+export function extractThinkTag(content: string): ThinkTagResult {
+  const match = content.match(THINK_TAG_REGEX);
+  if (!match) {
+    return { thinkContent: undefined, cleanContent: content };
+  }
+  return {
+    thinkContent: match[1].trim(),
+    cleanContent: content.slice(match[0].length),
+  };
+}
+
+/**
+ * Estimate thinking duration in milliseconds from thinking content.
+ * Uses a rough tokens-per-second heuristic since APIs don't report
+ * wall-clock thinking time.
+ */
+export function estimateThinkingMs(thinkContent: string): number {
+  const estimatedTokens = Math.ceil(thinkContent.length / CHARS_PER_TOKEN);
+  const seconds = estimatedTokens / THINKING_TOKENS_PER_SEC;
+  return Math.round(seconds * 1000);
+}

package/tests/auth-resolver.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { resolveAuth, extractToken } from '../src/auth/auth-resolver.js';
+
+describe('extractToken', () => {
+  it('should extract apiKey for api-key auth', () => {
+    expect(extractToken({ type: 'api-key', apiKey: 'sk-123' })).toBe('sk-123');
+  });
+
+  it('should extract accessToken for oauth auth', () => {
+    expect(extractToken({
+      type: 'oauth',
+      clientId: 'cid',
+      clientSecret: 'cs',
+      tokenUrl: 'https://auth.example.com/token',
+      accessToken: 'at-123',
+    })).toBe('at-123');
+  });
+
+  it('should return empty string for oauth without accessToken', () => {
+    expect(extractToken({
+      type: 'oauth',
+      clientId: 'cid',
+      clientSecret: 'cs',
+      tokenUrl: 'https://auth.example.com/token',
+    })).toBe('');
+  });
+
+  it('should extract accessToken for azure-ad auth', () => {
+    expect(extractToken({
+      type: 'azure-ad',
+      tenantId: 'tid',
+      clientId: 'cid',
+      accessToken: 'az-token',
+    })).toBe('az-token');
+  });
+
+  it('should extract accessKeyId for aws-iam auth', () => {
+    expect(extractToken({
+      type: 'aws-iam',
+      region: 'us-east-1',
+      accessKeyId: 'AKIA123',
+    })).toBe('AKIA123');
+  });
+
+  it('should extract accessToken for gcp auth', () => {
+    expect(extractToken({
+      type: 'gcp-service-account',
+      projectId: 'proj-1',
+      accessToken: 'gcp-token',
+    })).toBe('gcp-token');
+  });
+
+  it('should return empty string for credential-file', () => {
+    expect(extractToken({
+      type: 'credential-file',
+      filePath: '/path/to/creds.json',
+    })).toBe('');
+  });
+});
+
+describe('resolveAuth', () => {
+  it('should resolve api-key auth', async () => {
+    const result = await resolveAuth({ type: 'api-key', apiKey: 'sk-test' });
+    expect(result.type).toBe('api-key');
+    expect(result.token).toBe('sk-test');
+    expect(result.headers['Authorization']).toBe('Bearer sk-test');
+  });
+
+  it('should resolve oauth with existing accessToken', async () => {
+    const result = await resolveAuth({
+      type: 'oauth',
+      clientId: 'cid',
+      clientSecret: 'cs',
+      tokenUrl: 'https://auth.example.com/token',
+      accessToken: 'existing-token',
+    });
+    expect(result.type).toBe('oauth');
+    expect(result.token).toBe('existing-token');
+    expect(result.headers['Authorization']).toBe('Bearer existing-token');
+  });
+
+  it('should resolve azure-ad with existing accessToken', async () => {
+    const result = await resolveAuth({
+      type: 'azure-ad',
+      tenantId: 'tid',
+      clientId: 'cid',
+      accessToken: 'az-token',
+    });
+    expect(result.type).toBe('azure-ad');
+    expect(result.token).toBe('az-token');
+  });
+
+  it('should throw on azure-ad without accessToken or clientSecret', async () => {
+    await expect(resolveAuth({
+      type: 'azure-ad',
+      tenantId: 'tid',
+      clientId: 'cid',
+    })).rejects.toThrow('Azure AD auth requires either accessToken or clientSecret');
+  });
+
+  it('should resolve aws-iam with credentials', async () => {
+    const result = await resolveAuth({
+      type: 'aws-iam',
+      region: 'us-east-1',
+      accessKeyId: 'AKIA123',
+      secretAccessKey: 'secret',
+      sessionToken: 'session',
+    });
+    expect(result.type).toBe('aws-iam');
+    expect(result.headers['x-aws-access-key-id']).toBe('AKIA123');
+    expect(result.headers['x-aws-region']).toBe('us-east-1');
+    expect(result.headers['x-aws-session-token']).toBe('session');
+  });
+
+  it('should resolve aws-iam without explicit credentials', async () => {
+    const result = await resolveAuth({
+      type: 'aws-iam',
+      region: 'us-west-2',
+    });
+    expect(result.type).toBe('aws-iam');
+    expect(result.headers).toEqual({});
+  });
+
+  it('should resolve gcp with accessToken', async () => {
+    const result = await resolveAuth({
+      type: 'gcp-service-account',
+      projectId: 'proj',
+      accessToken: 'gcp-tok',
+    });
+    expect(result.type).toBe('gcp-service-account');
+    expect(result.token).toBe('gcp-tok');
+  });
+
+  it('should resolve gcp without accessToken (ADC fallback)', async () => {
+    const result = await resolveAuth({
+      type: 'gcp-service-account',
+      projectId: 'proj',
+    });
+    expect(result.type).toBe('gcp-service-account');
+    expect(result.token).toBeUndefined();
+  });
+
+  it('should resolve credential-file auth', async () => {
+    const { writeFile, mkdir, rm } = await import('node:fs/promises');
+    const { join } = await import('node:path');
+    const { tmpdir } = await import('node:os');
+
+    const dir = join(tmpdir(), 'cli-agent-test-creds');
+    const filePath = join(dir, 'creds.json');
+
+    await mkdir(dir, { recursive: true });
+    await writeFile(filePath, JSON.stringify({
+      default: { api_key: 'file-key-123' },
+      staging: { token: 'staging-tok' },
+    }));
+
+    try {
+      const result = await resolveAuth({
+        type: 'credential-file',
+        filePath,
+      });
+      expect(result.type).toBe('credential-file');
+      expect(result.token).toBe('file-key-123');
+
+      const result2 = await resolveAuth({
+        type: 'credential-file',
+        filePath,
+        profile: 'staging',
+      });
+      expect(result2.token).toBe('staging-tok');
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('should throw for missing credential file', async () => {
+    await expect(resolveAuth({
+      type: 'credential-file',
+      filePath: '/nonexistent/path/creds.json',
+    })).rejects.toThrow('Failed to read credential file');
+  });
+
+  it('should throw for missing profile in credential file', async () => {
+    const { writeFile, mkdir, rm } = await import('node:fs/promises');
+    const { join } = await import('node:path');
+    const { tmpdir } = await import('node:os');
+
+    const dir = join(tmpdir(), 'cli-agent-test-creds-2');
+    const filePath = join(dir, 'creds.json');
+
+    await mkdir(dir, { recursive: true });
+    await writeFile(filePath, JSON.stringify({ default: { api_key: 'key' } }));
+
+    try {
+      await expect(resolveAuth({
+        type: 'credential-file',
+        filePath,
+        profile: 'nonexistent',
+      })).rejects.toThrow("Profile 'nonexistent' not found");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});