@exagent/agent 0.3.5 → 0.3.7

package/src/llm/base.ts

@@ -1,264 +0,0 @@
-import type { LLMAdapter, LLMMessage, LLMResponse, LLMMetadata, LLMConfig } from '@exagent/sdk';
-import { getLogger } from '../logger.js';
-import type { LLMCallRecord } from '../diagnostics.js';
-
-/** Status codes that should be retried (transient errors) */
-const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
-
-/** Default timeout for LLM API calls in ms */
-const DEFAULT_TIMEOUT_MS = 30_000;
-
-/** Max retries for transient errors */
-const MAX_RETRIES = 3;
-
-/** Backoff delays in ms: 1s, 2s, 4s */
-const BACKOFF_DELAYS = [1000, 2000, 4000];
-
-export interface LLMUsageStats {
-  totalInputTokens: number;
-  totalOutputTokens: number;
-  totalCalls: number;
-  dailyInputTokens: number;
-  dailyOutputTokens: number;
-  dailyCalls: number;
-  lastResetDate: string; // YYYY-MM-DD UTC
-}
-
-export abstract class BaseLLMAdapter implements LLMAdapter {
-  protected config: LLMConfig;
-  private usage: LLMUsageStats = {
-    totalInputTokens: 0,
-    totalOutputTokens: 0,
-    totalCalls: 0,
-    dailyInputTokens: 0,
-    dailyOutputTokens: 0,
-    dailyCalls: 0,
-    lastResetDate: this.todayUTC(),
-  };
-
-  /** Optional daily token budget — if exceeded, chat() throws */
-  private maxDailyTokens: number | undefined;
-
-  /** Callback to send LLM call records to DiagnosticsCollector */
-  private onCallRecorded: ((record: LLMCallRecord) => void) | null = null;
-
-  constructor(config: LLMConfig) {
-    this.config = config;
-  }
-
-  /** Register a callback to receive LLM call records (wired by runtime) */
-  setCallRecordCallback(cb: (record: LLMCallRecord) => void): void {
-    this.onCallRecorded = cb;
-  }
-
-  /** Set a daily token budget. Once exceeded, chat() will throw. */
-  setMaxDailyTokens(max: number | undefined): void {
-    this.maxDailyTokens = max;
-  }
-
-  /** Get current usage statistics */
-  getUsageStats(): LLMUsageStats {
-    this.resetDailyIfNeeded();
-    return { ...this.usage };
-  }
-
-  /** Record token usage from a response (called by subclasses or externally) */
-  recordUsage(tokens: { input: number; output: number }): void {
-    this.resetDailyIfNeeded();
-    this.usage.totalInputTokens += tokens.input;
-    this.usage.totalOutputTokens += tokens.output;
-    this.usage.totalCalls++;
-    this.usage.dailyInputTokens += tokens.input;
-    this.usage.dailyOutputTokens += tokens.output;
-    this.usage.dailyCalls++;
-  }
-
-  /** Check if the daily token budget has been exceeded */
-  isDailyBudgetExceeded(): boolean {
-    if (!this.maxDailyTokens) return false;
-    this.resetDailyIfNeeded();
-    return (this.usage.dailyInputTokens + this.usage.dailyOutputTokens) >= this.maxDailyTokens;
-  }
-
-  /**
-   * Chat with retry logic and timeout.
-   * Retries up to 3 times with exponential backoff on transient errors (429, 5xx, timeout).
-   * Does not retry on 400/401/403 (client errors).
-   */
-  async chat(messages: LLMMessage[]): Promise<LLMResponse> {
-    const log = getLogger();
-    const meta = this.getMetadata();
-
-    // Check daily budget before calling
-    if (this.isDailyBudgetExceeded()) {
-      const budgetErr = `LLM daily token budget exceeded (${this.usage.dailyInputTokens + this.usage.dailyOutputTokens} / ${this.maxDailyTokens})`;
-      log.warn('llm', budgetErr, { provider: meta.provider, model: meta.model });
-      throw new Error(budgetErr);
-    }
-
-    let lastError: Error | null = null;
-    let retries = 0;
-    const callStart = Date.now();
-
-    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-      try {
-        const response = await this.chatImpl(messages);
-
-        // Track token usage
-        if (response.tokens) {
-          this.recordUsage(response.tokens);
-        }
-
-        const latencyMs = Date.now() - callStart;
-        log.info('llm', 'Call completed', {
-          provider: meta.provider,
-          model: meta.model,
-          inputTokens: response.tokens?.input ?? 0,
-          outputTokens: response.tokens?.output ?? 0,
-          latencyMs,
-          retries,
-        });
-
-        this.emitCallRecord({
-          timestamp: callStart,
-          provider: meta.provider,
-          model: meta.model,
-          inputTokens: response.tokens?.input ?? 0,
-          outputTokens: response.tokens?.output ?? 0,
-          latencyMs,
-          success: true,
-          retries,
-        });
-
-        return response;
-      } catch (err) {
-        lastError = err as Error;
-        const isRetryable = this.isRetryableError(lastError);
-
-        if (!isRetryable || attempt >= MAX_RETRIES) {
-          const latencyMs = Date.now() - callStart;
-          log.error('llm', 'Call failed', {
-            provider: meta.provider,
-            model: meta.model,
-            error: lastError.message,
-            latencyMs,
-            retries,
-            retryable: isRetryable,
-          });
-
-          this.emitCallRecord({
-            timestamp: callStart,
-            provider: meta.provider,
-            model: meta.model,
-            inputTokens: 0,
-            outputTokens: 0,
-            latencyMs,
-            success: false,
-            error: lastError.message,
-            retries,
-          });
-
-          throw lastError;
-        }
-
-        retries++;
-        const delay = BACKOFF_DELAYS[attempt] ?? 4000;
-        log.warn('llm', `Retrying after ${delay}ms (attempt ${retries}/${MAX_RETRIES})`, {
-          provider: meta.provider,
-          model: meta.model,
-          error: lastError.message,
-        });
-        await new Promise(resolve => setTimeout(resolve, delay));
-      }
-    }
-
-    throw lastError ?? new Error('LLM call failed');
-  }
-
-  private emitCallRecord(record: LLMCallRecord): void {
-    this.onCallRecorded?.(record);
-  }
-
-  /**
-   * Actual LLM call implementation — subclasses override this instead of chat().
-   * Must be implemented by each provider adapter.
-   */
-  protected abstract chatImpl(messages: LLMMessage[]): Promise<LLMResponse>;
-
-  abstract getMetadata(): LLMMetadata;
-
-  protected getTemperature(): number {
-    return this.config.temperature ?? 0.7;
-  }
-
-  protected getMaxTokens(): number {
-    return this.config.maxTokens ?? 4096;
-  }
-
-  /** Get timeout in ms for fetch calls */
-  protected getTimeoutMs(): number {
-    return DEFAULT_TIMEOUT_MS;
-  }
-
-  /**
-   * Fetch with timeout using AbortController.
-   * Wraps the standard fetch with a configurable timeout.
-   */
-  protected async fetchWithTimeout(url: string, init: RequestInit): Promise<Response> {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.getTimeoutMs());
-
-    try {
-      const response = await fetch(url, {
-        ...init,
-        signal: controller.signal,
-      });
-      return response;
-    } catch (err) {
-      if ((err as Error).name === 'AbortError') {
-        throw new Error(`LLM API request timed out after ${this.getTimeoutMs()}ms`);
-      }
-      throw err;
-    } finally {
-      clearTimeout(timeoutId);
-    }
-  }
-
-  /** Check if an error is retryable (transient) */
-  private isRetryableError(err: Error): boolean {
-    const msg = err.message;
-
-    // Timeout errors are retryable
-    if (msg.includes('timed out') || msg.includes('AbortError') || msg.includes('ECONNRESET') || msg.includes('ECONNREFUSED') || msg.includes('ETIMEDOUT')) {
-      return true;
-    }
-
-    // Check for HTTP status codes in error message
-    for (const code of RETRYABLE_STATUS_CODES) {
-      if (msg.includes(`${code}`)) {
-        return true;
-      }
-    }
-
-    // Network errors
-    if (msg.includes('network') || msg.includes('fetch failed') || msg.includes('socket hang up')) {
-      return true;
-    }
-
-    return false;
-  }
-
-  private todayUTC(): string {
-    return new Date().toISOString().slice(0, 10);
-  }
-
-  private resetDailyIfNeeded(): void {
-    const today = this.todayUTC();
-    if (this.usage.lastResetDate !== today) {
-      this.usage.dailyInputTokens = 0;
-      this.usage.dailyOutputTokens = 0;
-      this.usage.dailyCalls = 0;
-      this.usage.lastResetDate = today;
-    }
-  }
-}

package/src/llm/deepseek.ts

@@ -1,48 +0,0 @@
-import type { LLMMessage, LLMResponse, LLMMetadata, LLMConfig } from '@exagent/sdk';
-import { BaseLLMAdapter } from './base.js';
-
-export class DeepSeekAdapter extends BaseLLMAdapter {
-  constructor(config: LLMConfig) {
-    super(config);
-  }
-
-  protected async chatImpl(messages: LLMMessage[]): Promise<LLMResponse> {
-    const res = await this.fetchWithTimeout('https://api.deepseek.com/chat/completions', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this.config.apiKey}`,
-      },
-      body: JSON.stringify({
-        model: this.config.model || 'deepseek-chat',
-        messages: messages.map(m => ({ role: m.role, content: m.content })),
-        temperature: this.getTemperature(),
-        max_tokens: this.getMaxTokens(),
-      }),
-    });
-
-    if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`DeepSeek API error ${res.status}: ${body}`);
-    }
-
-    const data = await res.json() as {
-      choices: { message: { content: string } }[];
-      usage?: { prompt_tokens: number; completion_tokens: number };
-    };
-
-    return {
-      content: data.choices[0]?.message?.content || '',
-      tokens: data.usage
-        ? { input: data.usage.prompt_tokens, output: data.usage.completion_tokens }
-        : undefined,
-    };
-  }
-
-  getMetadata(): LLMMetadata {
-    return {
-      provider: 'deepseek',
-      model: this.config.model || 'deepseek-chat',
-    };
-  }
-}

package/src/llm/google.ts

@@ -1,63 +0,0 @@
-import type { LLMMessage, LLMResponse, LLMMetadata, LLMConfig } from '@exagent/sdk';
-import { BaseLLMAdapter } from './base.js';
-
-export class GoogleAdapter extends BaseLLMAdapter {
-  constructor(config: LLMConfig) {
-    super(config);
-  }
-
-  protected async chatImpl(messages: LLMMessage[]): Promise<LLMResponse> {
-    const model = this.config.model || 'gemini-2.5-flash';
-    const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${this.config.apiKey}`;
-
-    const systemMessage = messages.find(m => m.role === 'system');
-    const nonSystemMessages = messages.filter(m => m.role !== 'system');
-
-    const body: Record<string, unknown> = {
-      contents: nonSystemMessages.map(m => ({
-        role: m.role === 'assistant' ? 'model' : 'user',
-        parts: [{ text: m.content }],
-      })),
-      generationConfig: {
-        temperature: this.getTemperature(),
-        maxOutputTokens: this.getMaxTokens(),
-      },
-    };
-
-    if (systemMessage) {
-      body.systemInstruction = { parts: [{ text: systemMessage.content }] };
-    }
-
-    const res = await this.fetchWithTimeout(url, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(body),
-    });
-
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`Google AI error ${res.status}: ${text}`);
-    }
-
-    const data = await res.json() as {
-      candidates: { content: { parts: { text: string }[] } }[];
-      usageMetadata?: { promptTokenCount: number; candidatesTokenCount: number };
-    };
-
-    const text = data.candidates[0]?.content?.parts[0]?.text || '';
-
-    return {
-      content: text,
-      tokens: data.usageMetadata
-        ? { input: data.usageMetadata.promptTokenCount, output: data.usageMetadata.candidatesTokenCount }
-        : undefined,
-    };
-  }
-
-  getMetadata(): LLMMetadata {
-    return {
-      provider: 'google',
-      model: this.config.model || 'gemini-2.5-flash',
-    };
-  }
-}

package/src/llm/groq.ts

@@ -1,48 +0,0 @@
-import type { LLMMessage, LLMResponse, LLMMetadata, LLMConfig } from '@exagent/sdk';
-import { BaseLLMAdapter } from './base.js';
-
-export class GroqAdapter extends BaseLLMAdapter {
-  constructor(config: LLMConfig) {
-    super(config);
-  }
-
-  protected async chatImpl(messages: LLMMessage[]): Promise<LLMResponse> {
-    const res = await this.fetchWithTimeout('https://api.groq.com/openai/v1/chat/completions', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this.config.apiKey}`,
-      },
-      body: JSON.stringify({
-        model: this.config.model || 'llama-3.3-70b-versatile',
-        messages: messages.map(m => ({ role: m.role, content: m.content })),
-        temperature: this.getTemperature(),
-        max_tokens: this.getMaxTokens(),
-      }),
-    });
-
-    if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`Groq API error ${res.status}: ${body}`);
-    }
-
-    const data = await res.json() as {
-      choices: { message: { content: string } }[];
-      usage?: { prompt_tokens: number; completion_tokens: number };
-    };
-
-    return {
-      content: data.choices[0]?.message?.content || '',
-      tokens: data.usage
-        ? { input: data.usage.prompt_tokens, output: data.usage.completion_tokens }
-        : undefined,
-    };
-  }
-
-  getMetadata(): LLMMetadata {
-    return {
-      provider: 'groq',
-      model: this.config.model || 'llama-3.3-70b-versatile',
-    };
-  }
-}

package/src/llm/index.ts

@@ -1,42 +0,0 @@
-import type { LLMAdapter, LLMConfig } from '@exagent/sdk';
-import { OpenAIAdapter } from './openai.js';
-import { AnthropicAdapter } from './anthropic.js';
-import { GoogleAdapter } from './google.js';
-import { DeepSeekAdapter } from './deepseek.js';
-import { MistralAdapter } from './mistral.js';
-import { GroqAdapter } from './groq.js';
-import { TogetherAdapter } from './together.js';
-import { OllamaAdapter } from './ollama.js';
-
-export function createLLMAdapter(config: LLMConfig): LLMAdapter {
-  switch (config.provider) {
-    case 'openai':
-      return new OpenAIAdapter(config);
-    case 'anthropic':
-      return new AnthropicAdapter(config);
-    case 'google':
-      return new GoogleAdapter(config);
-    case 'deepseek':
-      return new DeepSeekAdapter(config);
-    case 'mistral':
-      return new MistralAdapter(config);
-    case 'groq':
-      return new GroqAdapter(config);
-    case 'together':
-      return new TogetherAdapter(config);
-    case 'ollama':
-      return new OllamaAdapter(config);
-    default:
-      throw new Error(`Unknown LLM provider: ${config.provider}`);
-  }
-}
-
-export { BaseLLMAdapter } from './base.js';
-export { OpenAIAdapter } from './openai.js';
-export { AnthropicAdapter } from './anthropic.js';
-export { GoogleAdapter } from './google.js';
-export { DeepSeekAdapter } from './deepseek.js';
-export { MistralAdapter } from './mistral.js';
-export { GroqAdapter } from './groq.js';
-export { TogetherAdapter } from './together.js';
-export { OllamaAdapter } from './ollama.js';

package/src/llm/mistral.ts

@@ -1,48 +0,0 @@
-import type { LLMMessage, LLMResponse, LLMMetadata, LLMConfig } from '@exagent/sdk';
-import { BaseLLMAdapter } from './base.js';
-
-export class MistralAdapter extends BaseLLMAdapter {
-  constructor(config: LLMConfig) {
-    super(config);
-  }
-
-  protected async chatImpl(messages: LLMMessage[]): Promise<LLMResponse> {
-    const res = await this.fetchWithTimeout('https://api.mistral.ai/v1/chat/completions', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this.config.apiKey}`,
-      },
-      body: JSON.stringify({
-        model: this.config.model || 'mistral-large-latest',
-        messages: messages.map(m => ({ role: m.role, content: m.content })),
-        temperature: this.getTemperature(),
-        max_tokens: this.getMaxTokens(),
-      }),
-    });
-
-    if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`Mistral API error ${res.status}: ${body}`);
-    }
-
-    const data = await res.json() as {
-      choices: { message: { content: string } }[];
-      usage?: { prompt_tokens: number; completion_tokens: number };
-    };
-
-    return {
-      content: data.choices[0]?.message?.content || '',
-      tokens: data.usage
-        ? { input: data.usage.prompt_tokens, output: data.usage.completion_tokens }
-        : undefined,
-    };
-  }
-
-  getMetadata(): LLMMetadata {
-    return {
-      provider: 'mistral',
-      model: this.config.model || 'mistral-large-latest',
-    };
-  }
-}

package/src/llm/ollama.ts

@@ -1,52 +0,0 @@
-import type { LLMMessage, LLMResponse, LLMMetadata, LLMConfig } from '@exagent/sdk';
-import { BaseLLMAdapter } from './base.js';
-
-export class OllamaAdapter extends BaseLLMAdapter {
-  private endpoint: string;
-
-  constructor(config: LLMConfig) {
-    super(config);
-    this.endpoint = config.endpoint || 'http://localhost:11434';
-  }
-
-  protected async chatImpl(messages: LLMMessage[]): Promise<LLMResponse> {
-    const res = await this.fetchWithTimeout(`${this.endpoint}/api/chat`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        model: this.config.model || 'llama3.3',
-        messages: messages.map(m => ({ role: m.role, content: m.content })),
-        stream: false,
-        options: {
-          temperature: this.getTemperature(),
-          num_predict: this.getMaxTokens(),
-        },
-      }),
-    });
-
-    if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`Ollama error ${res.status}: ${body}`);
-    }
-
-    const data = await res.json() as {
-      message: { content: string };
-      prompt_eval_count?: number;
-      eval_count?: number;
-    };
-
-    return {
-      content: data.message?.content || '',
-      tokens: data.prompt_eval_count
-        ? { input: data.prompt_eval_count, output: data.eval_count || 0 }
-        : undefined,
-    };
-  }
-
-  getMetadata(): LLMMetadata {
-    return {
-      provider: 'ollama',
-      model: this.config.model || 'llama3.3',
-    };
-  }
-}

package/src/llm/openai.ts

@@ -1,51 +0,0 @@
-import type { LLMMessage, LLMResponse, LLMMetadata, LLMConfig } from '@exagent/sdk';
-import { BaseLLMAdapter } from './base.js';
-
-export class OpenAIAdapter extends BaseLLMAdapter {
-  private endpoint: string;
-
-  constructor(config: LLMConfig) {
-    super(config);
-    this.endpoint = config.endpoint || 'https://api.openai.com/v1';
-  }
-
-  protected async chatImpl(messages: LLMMessage[]): Promise<LLMResponse> {
-    const res = await this.fetchWithTimeout(`${this.endpoint}/chat/completions`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this.config.apiKey}`,
-      },
-      body: JSON.stringify({
-        model: this.config.model || 'gpt-4o',
-        messages: messages.map(m => ({ role: m.role, content: m.content })),
-        temperature: this.getTemperature(),
-        max_tokens: this.getMaxTokens(),
-      }),
-    });
-
-    if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`OpenAI API error ${res.status}: ${body}`);
-    }
-
-    const data = await res.json() as {
-      choices: { message: { content: string } }[];
-      usage?: { prompt_tokens: number; completion_tokens: number };
-    };
-
-    return {
-      content: data.choices[0]?.message?.content || '',
-      tokens: data.usage
-        ? { input: data.usage.prompt_tokens, output: data.usage.completion_tokens }
-        : undefined,
-    };
-  }
-
-  getMetadata(): LLMMetadata {
-    return {
-      provider: 'openai',
-      model: this.config.model || 'gpt-4o',
-    };
-  }
-}

package/src/llm/together.ts

@@ -1,48 +0,0 @@
-import type { LLMMessage, LLMResponse, LLMMetadata, LLMConfig } from '@exagent/sdk';
-import { BaseLLMAdapter } from './base.js';
-
-export class TogetherAdapter extends BaseLLMAdapter {
-  constructor(config: LLMConfig) {
-    super(config);
-  }
-
-  protected async chatImpl(messages: LLMMessage[]): Promise<LLMResponse> {
-    const res = await this.fetchWithTimeout('https://api.together.xyz/v1/chat/completions', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this.config.apiKey}`,
-      },
-      body: JSON.stringify({
-        model: this.config.model || 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
-        messages: messages.map(m => ({ role: m.role, content: m.content })),
-        temperature: this.getTemperature(),
-        max_tokens: this.getMaxTokens(),
-      }),
-    });
-
-    if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`Together API error ${res.status}: ${body}`);
-    }
-
-    const data = await res.json() as {
-      choices: { message: { content: string } }[];
-      usage?: { prompt_tokens: number; completion_tokens: number };
-    };
-
-    return {
-      content: data.choices[0]?.message?.content || '',
-      tokens: data.usage
-        ? { input: data.usage.prompt_tokens, output: data.usage.completion_tokens }
-        : undefined,
-    };
-  }
-
-  getMetadata(): LLMMetadata {
-    return {
-      provider: 'together',
-      model: this.config.model || 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
-    };
-  }
-}