@winspan/claude-forge 8.39.0 → 8.50.6

package/src/core/ai/provider.ts

@@ -0,0 +1,308 @@
+/**
+ * Claude AI provider — wrapper around @anthropic-ai/sdk.
+ *
+ * Adds per-request timeout (AbortController) and bounded retry with exponential
+ * backoff for transient failures (AbortError / 429 / 5xx / network errors).
+ * SDK's built-in retry is disabled (maxRetries: 0) to avoid double retry layers.
+ */
+
+import { promises as fs } from 'node:fs';
+import Anthropic from '@anthropic-ai/sdk';
+import type {
+  AIResponse,
+  CompleteOptions,
+  ImageInput,
+  SupportedImageMediaType,
+} from './types.js';
+
+/**
+ * Options for `completeWithImage`. Inherits all transport knobs from
+ * `CompleteOptions` and adds the image list.
+ */
+export interface CompleteWithImageOptions extends CompleteOptions {
+  /** One or more images to include before the text prompt. */
+  images: ImageInput[];
+}
+import { logger } from '../utils/logger.js';
+
+const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
+const DEFAULT_MAX_TOKENS = 4096;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+const MAX_BACKOFF_MS = 8_000;
+
+const SUPPORTED_IMAGE_MEDIA_TYPES: ReadonlySet<SupportedImageMediaType> = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+]);
+
+/** Sleep helper — exported via object indirection so tests can stub it. */
+export const timing = {
+  delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  },
+};
+
+/** @deprecated Use `timing.delay`; kept for backward compatibility. */
+export function delay(ms: number): Promise<void> {
+  return timing.delay(ms);
+}
+
+/**
+ * Determine whether an error from the Anthropic SDK (or network layer) is
+ * worth retrying. Covers:
+ *   - Abort (our own timeout fires an AbortController)
+ *   - 429 rate limit
+ *   - 5xx server errors
+ *   - Connection / network errors without a status code
+ */
+function isRetriable(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false;
+  const e = err as { name?: string; status?: number; code?: string };
+
+  if (e.name === 'AbortError' || e.name === 'APIUserAbortError') return true;
+  if (typeof e.status === 'number') {
+    if (e.status === 429) return true;
+    if (e.status >= 500 && e.status < 600) return true;
+    return false;
+  }
+  // No HTTP status -> typically a connection error, worth retrying.
+  if (e.name === 'APIConnectionError' || e.name === 'APIConnectionTimeoutError') return true;
+  if (e.code === 'ECONNRESET' || e.code === 'ETIMEDOUT' || e.code === 'ENOTFOUND') return true;
+  return false;
+}
+
+function computeBackoffMs(attempt: number): number {
+  return Math.min(1000 * Math.pow(2, attempt), MAX_BACKOFF_MS);
+}
+
+/** Shape required for `messages.create`'s `messages[].content` parameter. */
+type ClaudeContentBlockParam =
+  | Anthropic.TextBlockParam
+  | Anthropic.ImageBlockParam
+  | Anthropic.ToolUseBlockParam
+  | Anthropic.ToolResultBlockParam;
+
+type ClaudeUserContent = string | ClaudeContentBlockParam[];
+
+export class ClaudeProvider {
+  // Exposed for tests; production code treats it as private.
+  /** @internal */
+  client: Anthropic;
+  private model: string;
+  private callCount = 0;
+  private totalTokens = 0;
+  private totalErrors = 0;
+  private totalLatencyMs = 0;
+
+  constructor(apiKey: string, model?: string, baseUrl?: string) {
+    this.model = model || DEFAULT_MODEL;
+    this.client = new Anthropic({
+      apiKey,
+      ...(baseUrl ? { baseURL: baseUrl } : {}),
+    });
+  }
+
+  async complete(prompt: string, options?: CompleteOptions): Promise<string> {
+    const response = await this.completeWithUsage(prompt, options);
+    return response.text;
+  }
+
+  async completeWithUsage(prompt: string, options?: CompleteOptions): Promise<AIResponse> {
+    return this.runMessageRequest(prompt, options);
+  }
+
+  /**
+   * Vision-aware completion. Reads each `ImageInput` from disk, base64-encodes
+   * it, and packs the images followed by the text prompt into a single user
+   * message (Claude Vision format).
+   *
+   * Reuses the same retry/timeout pipeline as `completeWithUsage`. Validation
+   * (file existence, media type) runs before the first attempt so bad inputs
+   * fail fast and don't consume retry budget.
+   */
+  async completeWithImage(
+    prompt: string,
+    options: CompleteWithImageOptions,
+  ): Promise<string> {
+    if (!options.images || options.images.length === 0) {
+      throw new Error('completeWithImage: at least one image is required');
+    }
+
+    const imageBlocks = await Promise.all(
+      options.images.map((img) => this.encodeImageBlock(img)),
+    );
+
+    const content: ClaudeContentBlockParam[] = [
+      ...imageBlocks,
+      { type: 'text', text: prompt },
+    ];
+
+    // Strip `images` so the rest of the option bag flows through unchanged.
+    const { images: _images, ...rest } = options;
+    void _images;
+
+    const response = await this.runMessageRequest(content, rest);
+    return response.text;
+  }
+
+  /**
+   * Read an image file and turn it into an Anthropic `ImageBlockParam` with a
+   * base64 source. Validates media type and surfaces a clear error if the file
+   * is missing.
+   */
+  private async encodeImageBlock(img: ImageInput): Promise<Anthropic.ImageBlockParam> {
+    if (!SUPPORTED_IMAGE_MEDIA_TYPES.has(img.mediaType)) {
+      throw new Error(
+        `completeWithImage: unsupported media type "${img.mediaType}". ` +
+          `Supported: ${[...SUPPORTED_IMAGE_MEDIA_TYPES].join(', ')}`,
+      );
+    }
+
+    let buffer: Buffer;
+    try {
+      buffer = await fs.readFile(img.path);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw new Error(`completeWithImage: failed to read image at "${img.path}": ${reason}`);
+    }
+
+    return {
+      type: 'image',
+      source: {
+        type: 'base64',
+        media_type: img.mediaType,
+        data: buffer.toString('base64'),
+      },
+    };
+  }
+
+  /**
+   * Core request loop shared by text-only and vision completions. Accepts
+   * already-built user content (string or content blocks) and returns the
+   * unwrapped text plus usage metadata.
+   */
+  private async runMessageRequest(
+    content: ClaudeUserContent,
+    options?: CompleteOptions,
+  ): Promise<AIResponse> {
+    this.callCount++;
+    const modelUsed = options?.model || this.model;
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const externalSignal = options?.signal;
+
+    let lastErr: unknown;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      const start = Date.now();
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+      // Forward external aborts into our controller so both sources cancel
+      // the in-flight request.
+      const onExternalAbort = () => controller.abort();
+      if (externalSignal) {
+        if (externalSignal.aborted) controller.abort();
+        else externalSignal.addEventListener('abort', onExternalAbort, { once: true });
+      }
+
+      try {
+        const response = await this.client.messages.create(
+          {
+            model: modelUsed,
+            max_tokens: options?.maxTokens || DEFAULT_MAX_TOKENS,
+            ...(options?.system ? { system: options.system } : {}),
+            messages: [{ role: 'user', content }],
+          },
+          {
+            signal: controller.signal,
+            // Disable SDK-level retry; this method owns retry semantics.
+            maxRetries: 0,
+            timeout: timeoutMs,
+          },
+        );
+
+        const latency = Date.now() - start;
+        this.totalLatencyMs += latency;
+
+        const usage = response.usage;
+        this.totalTokens += (usage?.input_tokens ?? 0) + (usage?.output_tokens ?? 0);
+
+        logger.debug(
+          `[AI] ${latency}ms | ${usage?.input_tokens ?? 0}+${usage?.output_tokens ?? 0} tokens` +
+            (attempt > 0 ? ` (after ${attempt} retry)` : ''),
+        );
+
+        const textBlock = response.content.find((c) => c.type === 'text');
+        return {
+          text: textBlock?.text ?? '',
+          usage: usage
+            ? {
+                input_tokens: usage.input_tokens,
+                output_tokens: usage.output_tokens,
+              }
+            : undefined,
+          model: modelUsed,
+        };
+      } catch (err) {
+        this.totalLatencyMs += Date.now() - start;
+        lastErr = err;
+
+        // External caller aborted -> never retry, propagate immediately.
+        if (externalSignal?.aborted) {
+          this.totalErrors++;
+          throw err;
+        }
+
+        const canRetry = attempt < maxRetries && isRetriable(err);
+        if (!canRetry) {
+          this.totalErrors++;
+          logger.error(`[AI] Claude API error: ${err instanceof Error ? err.message : String(err)}`);
+          throw err;
+        }
+
+        const backoffMs = computeBackoffMs(attempt);
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.warn(
+          `[ClaudeProvider] retry ${attempt + 1}/${maxRetries} after ${backoffMs}ms (reason: ${reason})`,
+        );
+        await timing.delay(backoffMs);
+      } finally {
+        clearTimeout(timer);
+        if (externalSignal) {
+          externalSignal.removeEventListener('abort', onExternalAbort);
+        }
+      }
+    }
+
+    // Unreachable: loop either returns or throws. Included for type safety.
+    throw lastErr instanceof Error ? lastErr : new Error('ClaudeProvider: exhausted retries');
+  }
+
+  formatStats(): string {
+    if (this.callCount === 0) return 'AI calls: 0';
+    const avgMs = Math.round(this.totalLatencyMs / this.callCount);
+    return `AI calls: ${this.callCount} | errors: ${this.totalErrors} | tokens: ${this.totalTokens} | avg: ${avgMs}ms | model: ${this.model}`;
+  }
+}
+
+/**
+ * Create a ClaudeProvider, resolving API key from env if not provided
+ */
+export function createProvider(apiKey?: string, model?: string, baseUrl?: string): ClaudeProvider {
+  const key = apiKey
+    || process.env.ANTHROPIC_API_KEY
+    || process.env.ANTHROPIC_AUTH_TOKEN
+    || '';
+
+  if (!key) {
+    throw new Error(
+      'Missing Claude API key. Set ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN environment variable.',
+    );
+  }
+
+  return new ClaudeProvider(key, model, baseUrl || process.env.ANTHROPIC_BASE_URL);
+}

package/src/core/ai/types.ts

@@ -0,0 +1,51 @@
+/**
+ * AI Provider types — shared type definitions for AI completions
+ */
+
+export interface TokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+}
+
+export interface AIResponse {
+  text: string;
+  usage?: TokenUsage;
+  model?: string;
+}
+
+/**
+ * Options for AI completion calls.
+ *
+ * `timeoutMs` (default 30_000) caps each individual request via AbortController.
+ * `maxRetries` (default 2) controls retry attempts for AbortError/429/5xx/network errors.
+ * `signal` lets callers abort externally (composed with internal timeout signal).
+ */
+export interface CompleteOptions {
+  system?: string;
+  maxTokens?: number;
+  model?: string;
+  timeoutMs?: number;
+  maxRetries?: number;
+  signal?: AbortSignal;
+}
+
+/**
+ * Supported media types for vision inputs. The whitelist mirrors what the
+ * Anthropic API accepts for `Base64ImageSource` (see SDK `Base64ImageSource`).
+ */
+export type SupportedImageMediaType =
+  | 'image/png'
+  | 'image/jpeg'
+  | 'image/gif'
+  | 'image/webp';
+
+/**
+ * Local image file passed to a vision-capable provider. The provider is
+ * responsible for reading and base64-encoding the file.
+ */
+export interface ImageInput {
+  /** Absolute or relative path to the image on disk. */
+  path: string;
+  /** Declared media type; must match the file contents. */
+  mediaType: SupportedImageMediaType;
+}

package/src/core/config.ts

@@ -0,0 +1,124 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import yaml from 'js-yaml';
+import type { ForgeConfig } from './types.js';
+import { FORGE_PATHS, DEFAULTS } from './constants.js';
+
+function defaultConfig(): ForgeConfig {
+  return {
+    ai: {
+      api_key: '',
+      model: DEFAULTS.AI_MODEL,
+      provider: DEFAULTS.AI_PROVIDER,
+    },
+    storage: {
+      path: FORGE_PATHS.database(),
+      max_size_mb: DEFAULTS.STORAGE_MAX_SIZE_MB,
+    },
+    web: {
+      enabled: true,
+      port: DEFAULTS.WEB_PORT,
+    },
+    security: {
+      destructiveOps: true,
+      secretsCheck: true,
+      diffSizeCheck: true,
+      diffSizeThreshold: 300,
+    },
+  };
+}
+
+/**
+ * Legacy fields kept for one-shot auto-migration. The historical schema used
+ * `distill.{api_key,model,base_url,provider}` plus `classifier_model` /
+ * `classifier_timeout` for a deprecated classifier feature. We map any of
+ * those onto the new `ai.*` block on first load and rewrite the file.
+ */
+interface LegacyConfig {
+  distill?: {
+    api_key?: string;
+    model?: string;
+    base_url?: string;
+    provider?: string;
+    classifier_model?: string;
+    classifier_timeout?: number;
+  };
+}
+
+/**
+ * Minimal config manager — reads/writes YAML from ~/.claude-forge/config.yaml
+ */
+export class ConfigManager {
+  private config: ForgeConfig | null = null;
+  private readonly configPath: string;
+
+  constructor(configPath?: string) {
+    this.configPath = configPath ?? FORGE_PATHS.config();
+  }
+
+  /**
+   * Load config from disk, merging with defaults for missing fields.
+   * Auto-migrates legacy `distill.*` keys into `ai.*` and rewrites the file.
+   */
+  get(): ForgeConfig {
+    if (this.config) return this.config;
+
+    const defaults = defaultConfig();
+
+    if (!existsSync(this.configPath)) {
+      this.config = defaults;
+      return this.config;
+    }
+
+    try {
+      const raw = readFileSync(this.configPath, 'utf-8');
+      const parsed = yaml.load(raw) as (Partial<ForgeConfig> & LegacyConfig) | null;
+
+      if (!parsed || typeof parsed !== 'object') {
+        this.config = defaults;
+        return this.config;
+      }
+
+      const legacy = parsed.distill;
+      const aiInput = parsed.ai ?? (legacy ? {
+        api_key: legacy.api_key ?? '',
+        model: legacy.model ?? defaults.ai.model,
+        base_url: legacy.base_url,
+        provider: legacy.provider ?? defaults.ai.provider,
+      } : undefined);
+
+      this.config = {
+        ai: { ...defaults.ai, ...aiInput },
+        storage: { ...defaults.storage, ...parsed.storage },
+        web: { ...defaults.web, ...parsed.web },
+        security: { ...defaults.security!, ...parsed.security },
+      } as ForgeConfig;
+
+      // One-shot rewrite if we just upgraded a legacy file.
+      if (legacy && !parsed.ai) {
+        try {
+          this.save();
+        } catch {
+          // Non-fatal: config still works in-memory; user may not have write perms.
+        }
+      }
+
+      return this.config;
+    } catch {
+      this.config = defaults;
+      return this.config;
+    }
+  }
+
+  /**
+   * Write current config to disk
+   */
+  save(): void {
+    const dir = FORGE_PATHS.home();
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    const content = yaml.dump(this.get(), { lineWidth: 120, noRefs: true });
+    writeFileSync(this.configPath, content, 'utf-8');
+  }
+}

package/src/core/constants.ts

@@ -0,0 +1,45 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Forge home directory and derived paths
+ */
+export const FORGE_HOME = join(homedir(), '.claude-forge');
+
+export const FORGE_PATHS = {
+  home: () => FORGE_HOME,
+  config: () => join(FORGE_HOME, 'config.yaml'),
+  database: () => join(FORGE_HOME, 'data.db'),
+  logs: () => join(FORGE_HOME, 'logs'),
+} as const;
+
+/**
+ * Time constants in milliseconds
+ */
+export const TIME = {
+  SECOND: 1_000,
+  MINUTE: 60_000,
+  HOUR: 3_600_000,
+  DAY: 86_400_000,
+  WEEK: 604_800_000,
+} as const;
+
+/**
+ * Database defaults
+ */
+export const DATABASE = {
+  DEFAULT_PATH: FORGE_PATHS.database(),
+  WAL_MODE: 'wal',
+  BUSY_TIMEOUT: 5_000,
+  CACHE_SIZE: -2_000, // 2MB
+} as const;
+
+/**
+ * Default config values
+ */
+export const DEFAULTS = {
+  AI_MODEL: 'claude-sonnet-4-6',
+  AI_PROVIDER: 'anthropic',
+  STORAGE_MAX_SIZE_MB: 500,
+  WEB_PORT: 3456,
+} as const;