@charming_groot/providers 0.1.0

package/src/auth/auth-resolver.ts

@@ -0,0 +1,261 @@
+import type { AuthConfig, ResolvedCredential } from '@charming_groot/core';
+import { ProviderError } from '@charming_groot/core';
+
+/**
+ * Synchronously extract a token/apiKey from an AuthConfig.
+ * For auth types that require async token exchange (OAuth client_credentials, Azure AD),
+ * the caller should use resolveAuth() first and pass the accessToken.
+ */
+export function extractToken(auth: AuthConfig): string {
+  switch (auth.type) {
+    case 'no-auth':
+      return 'no-auth';
+    case 'api-key':
+      return auth.apiKey;
+    case 'oauth':
+      return auth.accessToken ?? '';
+    case 'azure-ad':
+      return auth.accessToken ?? '';
+    case 'aws-iam':
+      return auth.accessKeyId ?? '';
+    case 'gcp-service-account':
+      return auth.accessToken ?? '';
+    case 'credential-file':
+      return '';
+  }
+}
+
+export async function resolveAuth(auth: AuthConfig): Promise<ResolvedCredential> {
+  switch (auth.type) {
+    case 'no-auth':
+      return { type: 'no-auth', headers: {}, token: undefined };
+    case 'api-key':
+      return resolveApiKey(auth);
+    case 'oauth':
+      return resolveOAuth(auth);
+    case 'azure-ad':
+      return resolveAzureAd(auth);
+    case 'aws-iam':
+      return resolveAwsIam(auth);
+    case 'gcp-service-account':
+      return resolveGcp(auth);
+    case 'credential-file':
+      return resolveCredentialFile(auth);
+    default:
+      throw new ProviderError(`Unsupported auth type: ${(auth as AuthConfig).type}`);
+  }
+}
+
+function resolveApiKey(auth: { type: 'api-key'; apiKey: string }): ResolvedCredential {
+  return {
+    type: 'api-key',
+    headers: { Authorization: `Bearer ${auth.apiKey}` },
+    token: auth.apiKey,
+  };
+}
+
+async function resolveOAuth(auth: {
+  type: 'oauth';
+  clientId: string;
+  clientSecret: string;
+  tokenUrl: string;
+  scopes?: readonly string[];
+  accessToken?: string;
+  refreshToken?: string;
+}): Promise<ResolvedCredential> {
+  // If we already have a valid access token, use it
+  if (auth.accessToken) {
+    return {
+      type: 'oauth',
+      headers: { Authorization: `Bearer ${auth.accessToken}` },
+      token: auth.accessToken,
+    };
+  }
+
+  // Client credentials flow
+  const params = new URLSearchParams({
+    grant_type: auth.refreshToken ? 'refresh_token' : 'client_credentials',
+    client_id: auth.clientId,
+    client_secret: auth.clientSecret,
+  });
+
+  if (auth.refreshToken) {
+    params.set('refresh_token', auth.refreshToken);
+  }
+  if (auth.scopes && auth.scopes.length > 0) {
+    params.set('scope', auth.scopes.join(' '));
+  }
+
+  const response = await fetch(auth.tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: params.toString(),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new ProviderError(`OAuth token request failed (${response.status}): ${body}`);
+  }
+
+  const data = await response.json() as { access_token: string; expires_in?: number };
+  const expiresAt = data.expires_in
+    ? new Date(Date.now() + data.expires_in * 1000)
+    : undefined;
+
+  return {
+    type: 'oauth',
+    headers: { Authorization: `Bearer ${data.access_token}` },
+    token: data.access_token,
+    expiresAt,
+  };
+}
+
+async function resolveAzureAd(auth: {
+  type: 'azure-ad';
+  tenantId: string;
+  clientId: string;
+  clientSecret?: string;
+  accessToken?: string;
+}): Promise<ResolvedCredential> {
+  if (auth.accessToken) {
+    return {
+      type: 'azure-ad',
+      headers: { Authorization: `Bearer ${auth.accessToken}` },
+      token: auth.accessToken,
+    };
+  }
+
+  if (!auth.clientSecret) {
+    throw new ProviderError('Azure AD auth requires either accessToken or clientSecret');
+  }
+
+  const tokenUrl = `https://login.microsoftonline.com/${auth.tenantId}/oauth2/v2.0/token`;
+  const params = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: auth.clientId,
+    client_secret: auth.clientSecret,
+    scope: 'https://cognitiveservices.azure.com/.default',
+  });
+
+  const response = await fetch(tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: params.toString(),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new ProviderError(`Azure AD token request failed (${response.status}): ${body}`);
+  }
+
+  const data = await response.json() as { access_token: string; expires_in?: number };
+  const expiresAt = data.expires_in
+    ? new Date(Date.now() + data.expires_in * 1000)
+    : undefined;
+
+  return {
+    type: 'azure-ad',
+    headers: {
+      Authorization: `Bearer ${data.access_token}`,
+      'api-key': data.access_token,
+    },
+    token: data.access_token,
+    expiresAt,
+  };
+}
+
+async function resolveAwsIam(auth: {
+  type: 'aws-iam';
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  sessionToken?: string;
+  region: string;
+  profile?: string;
+}): Promise<ResolvedCredential> {
+  // If explicit credentials provided, use them directly
+  // Real AWS Bedrock signing would use AWS SDK's SigV4
+  // This provides the credential structure for consumers to use
+  const headers: Record<string, string> = {};
+
+  if (auth.accessKeyId && auth.secretAccessKey) {
+    headers['x-aws-access-key-id'] = auth.accessKeyId;
+    headers['x-aws-region'] = auth.region;
+    if (auth.sessionToken) {
+      headers['x-aws-session-token'] = auth.sessionToken;
+    }
+  }
+
+  return {
+    type: 'aws-iam',
+    headers,
+    token: auth.accessKeyId,
+  };
+}
+
+async function resolveGcp(auth: {
+  type: 'gcp-service-account';
+  projectId: string;
+  keyFilePath?: string;
+  accessToken?: string;
+}): Promise<ResolvedCredential> {
+  if (auth.accessToken) {
+    return {
+      type: 'gcp-service-account',
+      headers: { Authorization: `Bearer ${auth.accessToken}` },
+      token: auth.accessToken,
+    };
+  }
+
+  // When keyFilePath is provided, consumers should use Google Auth Library
+  // This returns a placeholder that signals ADC should be used
+  return {
+    type: 'gcp-service-account',
+    headers: {},
+    token: undefined,
+  };
+}
+
+async function resolveCredentialFile(auth: {
+  type: 'credential-file';
+  filePath: string;
+  profile?: string;
+}): Promise<ResolvedCredential> {
+  const { readFile } = await import('node:fs/promises');
+  let content: string;
+
+  try {
+    content = await readFile(auth.filePath, 'utf-8');
+  } catch (error) {
+    throw new ProviderError(
+      `Failed to read credential file: ${auth.filePath}`,
+      error instanceof Error ? error : undefined
+    );
+  }
+
+  try {
+    const credentials = JSON.parse(content) as Record<string, Record<string, string>>;
+    const profile = auth.profile ?? 'default';
+    const entry = credentials[profile];
+
+    if (!entry) {
+      throw new ProviderError(`Profile '${profile}' not found in credential file`);
+    }
+
+    const apiKey = entry['api_key'] ?? entry['apiKey'] ?? entry['token'];
+    if (!apiKey) {
+      throw new ProviderError(`No api_key/apiKey/token found in profile '${profile}'`);
+    }
+
+    return {
+      type: 'credential-file',
+      headers: { Authorization: `Bearer ${apiKey}` },
+      token: apiKey,
+    };
+  } catch (error) {
+    if (error instanceof ProviderError) throw error;
+    throw new ProviderError(
+      `Failed to parse credential file: ${auth.filePath}`,
+      error instanceof Error ? error : undefined
+    );
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1 @@
+export { resolveAuth, extractToken } from './auth-resolver.js';

package/src/base-provider.ts

@@ -0,0 +1,28 @@
+import type {
+  ILlmProvider,
+  Message,
+  LlmResponse,
+  StreamEvent,
+  ToolDescription,
+} from '@charming_groot/core';
+import { createChildLogger } from '@charming_groot/core';
+import type { AgentLogger } from '@charming_groot/core';
+
+export abstract class BaseProvider implements ILlmProvider {
+  abstract readonly providerId: string;
+  protected readonly logger: AgentLogger;
+
+  constructor(loggerName: string) {
+    this.logger = createChildLogger(loggerName);
+  }
+
+  abstract chat(
+    messages: readonly Message[],
+    tools?: readonly ToolDescription[]
+  ): Promise<LlmResponse>;
+
+  abstract stream(
+    messages: readonly Message[],
+    tools?: readonly ToolDescription[]
+  ): AsyncIterable<StreamEvent>;
+}

package/src/circuit-breaker.ts

@@ -0,0 +1,157 @@
+import type {
+  ILlmProvider,
+  Message,
+  LlmResponse,
+  StreamEvent,
+  ToolDescription,
+  AgentLogger,
+} from '@charming_groot/core';
+import { ProviderError, createChildLogger } from '@charming_groot/core';
+
+export interface CircuitBreakerConfig {
+  /** Consecutive failures before opening the circuit (default: 5) */
+  failureThreshold?: number;
+  /** Consecutive successes in HALF_OPEN to close the circuit (default: 2) */
+  successThreshold?: number;
+  /** Ms to stay OPEN before allowing a probe request (default: 60_000) */
+  openTimeoutMs?: number;
+}
+
+type State = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+/**
+ * Circuit breaker wrapping an ILlmProvider.
+ *
+ * CLOSED  → normal operation, counts failures
+ * OPEN    → rejects immediately, waits openTimeoutMs then probes
+ * HALF_OPEN → allows one request; success → CLOSED, failure → OPEN
+ *
+ * Wrap inside RetryProvider for best results:
+ *   createProvider() → RetryProvider → CircuitBreakerProvider
+ */
+export class CircuitBreakerProvider implements ILlmProvider {
+  readonly providerId: string;
+
+  private readonly inner: ILlmProvider;
+  private readonly failureThreshold: number;
+  private readonly successThreshold: number;
+  private readonly openTimeoutMs: number;
+  private readonly logger: AgentLogger;
+
+  private state: State = 'CLOSED';
+  private failureCount  = 0;
+  private successCount  = 0;
+  private openedAt      = 0;
+
+  constructor(provider: ILlmProvider, config?: CircuitBreakerConfig) {
+    this.inner            = provider;
+    this.providerId       = provider.providerId;
+    this.failureThreshold = config?.failureThreshold ?? 5;
+    this.successThreshold = config?.successThreshold ?? 2;
+    this.openTimeoutMs    = config?.openTimeoutMs    ?? 60_000;
+    this.logger           = createChildLogger('circuit-breaker');
+  }
+
+  get currentState(): State {
+    return this.state;
+  }
+
+  async chat(
+    messages: readonly Message[],
+    tools?: readonly ToolDescription[]
+  ): Promise<LlmResponse> {
+    this.guardOrThrow();
+    try {
+      const result = await this.inner.chat(messages, tools);
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure(error);
+      throw error;
+    }
+  }
+
+  async *stream(
+    messages: readonly Message[],
+    tools?: readonly ToolDescription[]
+  ): AsyncIterable<StreamEvent> {
+    this.guardOrThrow();
+    try {
+      yield* this.inner.stream(messages, tools);
+      this.onSuccess();
+    } catch (error) {
+      this.onFailure(error);
+      throw error;
+    }
+  }
+
+  // ── Internal state machine ───────────────────────────────────────────────
+
+  private guardOrThrow(): void {
+    if (this.state === 'CLOSED' || this.state === 'HALF_OPEN') return;
+
+    // OPEN: check if timeout has elapsed
+    const elapsed = Date.now() - this.openedAt;
+    if (elapsed >= this.openTimeoutMs) {
+      this.transitionTo('HALF_OPEN');
+      return; // allow this probe request through
+    }
+
+    const remaining = Math.ceil((this.openTimeoutMs - elapsed) / 1000);
+    throw new ProviderError(
+      `Circuit breaker OPEN for provider '${this.providerId}' — retry in ${remaining}s`
+    );
+  }
+
+  private onSuccess(): void {
+    if (this.state === 'HALF_OPEN') {
+      this.successCount++;
+      if (this.successCount >= this.successThreshold) {
+        this.transitionTo('CLOSED');
+      }
+    } else {
+      this.failureCount = 0; // reset on any success in CLOSED
+    }
+  }
+
+  private onFailure(error: unknown): void {
+    const msg = error instanceof Error ? error.message : String(error);
+    this.logger.warn({ state: this.state, error: msg }, 'Circuit breaker recorded failure');
+
+    if (this.state === 'HALF_OPEN') {
+      // Probe failed → back to OPEN
+      this.transitionTo('OPEN');
+      return;
+    }
+
+    this.failureCount++;
+    if (this.failureCount >= this.failureThreshold) {
+      this.transitionTo('OPEN');
+    }
+  }
+
+  private transitionTo(next: State): void {
+    const prev = this.state;
+    this.state = next;
+
+    if (next === 'OPEN') {
+      this.openedAt     = Date.now();
+      this.successCount = 0;
+      this.logger.error(
+        { failureCount: this.failureCount, openTimeoutMs: this.openTimeoutMs },
+        `Circuit breaker OPENED for provider '${this.providerId}'`
+      );
+    } else if (next === 'HALF_OPEN') {
+      this.successCount = 0;
+      this.logger.warn({}, `Circuit breaker HALF_OPEN — probing provider '${this.providerId}'`);
+    } else {
+      this.failureCount = 0;
+      this.logger.info({}, `Circuit breaker CLOSED for provider '${this.providerId}'`);
+    }
+
+    if (prev !== next) {
+      // Allow external inspection of state transitions
+      this.logger.debug({ from: prev, to: next }, 'Circuit breaker state transition');
+    }
+  }
+}

package/src/claude-provider.ts

@@ -0,0 +1,215 @@
+import Anthropic from '@anthropic-ai/sdk';
+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';
+
+interface AnthropicToolParam {
+  name: string;
+  description: string;
+  input_schema: {
+    type: 'object';
+    properties: Record<string, { type: string; description: string }>;
+    required: string[];
+  };
+}
+
+export class ClaudeProvider extends BaseProvider {
+  readonly providerId = 'claude';
+  private readonly client: Anthropic;
+  private readonly model: string;
+  private readonly maxTokens: number;
+
+  constructor(config: ProviderConfig) {
+    super('claude-provider');
+    const apiKey = extractToken(config.auth);
+    this.client = new Anthropic({ apiKey, baseURL: config.baseUrl });
+    this.model = config.model;
+    this.maxTokens = config.maxTokens;
+  }
+
+  async chat(
+    messages: readonly Message[],
+    tools?: readonly ToolDescription[]
+  ): Promise<LlmResponse> {
+    try {
+      const systemMsg = messages.find((m) => m.role === 'system');
+      const nonSystemMsgs = messages.filter((m) => m.role !== 'system');
+
+      const response = await this.client.messages.create({
+        model: this.model,
+        max_tokens: this.maxTokens,
+        system: systemMsg?.content,
+        messages: this.toAnthropicMessages(nonSystemMsgs),
+        tools: tools ? this.toAnthropicTools(tools) : undefined,
+      });
+
+      return this.parseResponse(response);
+    } catch (error) {
+      throw new ProviderError(
+        `Claude 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 systemMsg = messages.find((m) => m.role === 'system');
+      const nonSystemMsgs = messages.filter((m) => m.role !== 'system');
+
+      const stream = this.client.messages.stream({
+        model: this.model,
+        max_tokens: this.maxTokens,
+        system: systemMsg?.content,
+        messages: this.toAnthropicMessages(nonSystemMsgs),
+        tools: tools ? this.toAnthropicTools(tools) : undefined,
+      });
+
+      for await (const event of stream) {
+        if (event.type === 'content_block_delta') {
+          const delta = event.delta as { type: string; text?: string; partial_json?: string };
+          if (delta.type === 'text_delta' && delta.text) {
+            yield { type: 'text_delta', content: delta.text };
+          } else if (delta.type === 'input_json_delta' && delta.partial_json) {
+            yield { type: 'tool_call_delta', content: delta.partial_json };
+          }
+        } else if (event.type === 'content_block_start') {
+          const block = event.content_block as { type: string; id?: string; name?: string };
+          if (block.type === 'tool_use') {
+            yield {
+              type: 'tool_call_start',
+              toolCall: { id: block.id, name: block.name },
+            };
+          }
+        } else if (event.type === 'message_stop') {
+          const finalMessage = await stream.finalMessage();
+          yield { type: 'done', response: this.parseResponse(finalMessage) };
+        }
+      }
+    } catch (error) {
+      throw new ProviderError(
+        `Claude stream error: ${error instanceof Error ? error.message : String(error)}`,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  private toAnthropicMessages(
+    messages: readonly Message[]
+  ): Anthropic.MessageParam[] {
+    return messages.map((msg) => {
+      if (msg.toolResults && msg.toolResults.length > 0) {
+        return {
+          role: 'user' as const,
+          content: msg.toolResults.map((tr) => ({
+            type: 'tool_result' as const,
+            tool_use_id: tr.toolCallId,
+            content: tr.content,
+          })),
+        };
+      }
+
+      if (msg.toolCalls && msg.toolCalls.length > 0) {
+        const content: Anthropic.ContentBlockParam[] = [];
+        if (msg.content) {
+          content.push({ type: 'text', text: msg.content });
+        }
+        for (const tc of msg.toolCalls) {
+          content.push({
+            type: 'tool_use',
+            id: tc.id,
+            name: tc.name,
+            input: JSON.parse(tc.arguments),
+          });
+        }
+        return { role: 'assistant' as const, content };
+      }
+
+      return {
+        role: msg.role as 'user' | 'assistant',
+        content: msg.content,
+      };
+    });
+  }
+
+  private toAnthropicTools(tools: readonly ToolDescription[]): AnthropicToolParam[] {
+    return tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      input_schema: {
+        type: 'object' as const,
+        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: Anthropic.Message): LlmResponse {
+    let content = '';
+    const toolCalls: ToolCall[] = [];
+    let thinkingMs: number | undefined;
+
+    for (const block of response.content) {
+      if (block.type === 'thinking') {
+        // Anthropic extended thinking block — estimate duration from token count
+        // (no direct timing from API, but the block existing means thinking occurred)
+        const thinkingBlock = block as { type: 'thinking'; thinking: string };
+        thinkingMs = estimateThinkingMs(thinkingBlock.thinking);
+      } else if (block.type === 'text') {
+        content += block.text;
+      } else if (block.type === 'tool_use') {
+        toolCalls.push({
+          id: block.id,
+          name: block.name,
+          arguments: JSON.stringify(block.input),
+        });
+      }
+    }
+
+    // Fallback: parse <think>...</think> tags from text content (DeepSeek, etc.)
+    const parsed = extractThinkTag(content);
+    if (parsed.thinkContent) {
+      content = parsed.cleanContent;
+      if (!thinkingMs) {
+        thinkingMs = estimateThinkingMs(parsed.thinkContent);
+      }
+    }
+
+    const stopReason =
+      response.stop_reason === 'tool_use'
+        ? 'tool_use' as const
+        : response.stop_reason === 'max_tokens'
+          ? 'max_tokens' as const
+          : 'end_turn' as const;
+
+    return {
+      content,
+      stopReason,
+      toolCalls,
+      usage: {
+        inputTokens: response.usage.input_tokens,
+        outputTokens: response.usage.output_tokens,
+        thinkingMs,
+      },
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { BaseProvider } from './base-provider.js';
+export { ClaudeProvider } from './claude-provider.js';
+export { OpenAIProvider } from './openai-provider.js';
+export {
+  createProvider,
+  registerProvider,
+  getProviderRegistry,
+} from './provider-factory.js';
+export { RetryProvider, type RetryConfig } from './retry-provider.js';
+export { CircuitBreakerProvider, type CircuitBreakerConfig } from './circuit-breaker.js';
+export { resolveAuth, extractToken } from './auth/index.js';
+export { extractThinkTag, estimateThinkingMs } from './thinking-parser.js';
+export type { ThinkTagResult } from './thinking-parser.js';