wraptc 1.0.2 → 1.0.4

package/src/core/unified/errors.ts

@@ -0,0 +1,141 @@
+/**
+ * Enhanced Error Types
+ *
+ * Provides structured error handling with categorization and suggestions.
+ */
+
+import type { ProviderErrorContext, ProviderErrorKind } from "../types";
+
+/**
+ * Enhanced provider error interface
+ */
+export interface IProviderError extends Error {
+  readonly kind: ProviderErrorKind;
+  readonly provider: string;
+  readonly context: ProviderErrorContext;
+  readonly isRetryable: boolean;
+  readonly isUserError: boolean;
+  readonly suggestedAction?: string;
+}
+
+/**
+ * Enhanced error class with helpful properties
+ */
+export class ProviderError extends Error implements IProviderError {
+  readonly kind: ProviderErrorKind;
+  readonly provider: string;
+  readonly context: ProviderErrorContext;
+
+  constructor(
+    message: string,
+    kind: ProviderErrorKind,
+    provider: string,
+    context: ProviderErrorContext = {},
+  ) {
+    super(message);
+    this.name = "ProviderError";
+    this.kind = kind;
+    this.provider = provider;
+    this.context = context;
+  }
+
+  /**
+   * Whether this error is safe to retry
+   */
+  get isRetryable(): boolean {
+    return ["TRANSIENT", "RATE_LIMIT", "TIMEOUT"].includes(this.kind);
+  }
+
+  /**
+   * Whether this error is likely due to user input
+   */
+  get isUserError(): boolean {
+    return ["BAD_REQUEST", "UNAUTHORIZED", "CONTEXT_LENGTH", "CONTENT_FILTER"].includes(this.kind);
+  }
+
+  /**
+   * Suggested action to resolve the error
+   */
+  get suggestedAction(): string | undefined {
+    const actions: Partial<Record<ProviderErrorKind, string>> = {
+      UNAUTHORIZED: "Check your API key configuration",
+      RATE_LIMIT: "Wait and retry, or switch to a different provider",
+      OUT_OF_CREDITS: "Check your quota or upgrade your plan",
+      CONTEXT_LENGTH: "Reduce the input size or use a different model",
+      CONTENT_FILTER: "Modify your prompt to comply with content policies",
+      TIMEOUT: "Try again with a shorter prompt or increase timeout",
+      BAD_REQUEST: "Check the request format and parameters",
+      NOT_FOUND: "Verify the model or endpoint exists",
+      FORBIDDEN: "Check your permissions for this operation",
+      INTERNAL: "The provider is experiencing issues, try again later",
+      TRANSIENT: "This is a temporary error, retry the request",
+    };
+    return actions[this.kind];
+  }
+
+  /**
+   * Create from an adapter error
+   */
+  static fromAdapterError(
+    err: Error & { kind?: ProviderErrorKind; adapterId?: string; context?: ProviderErrorContext },
+  ): ProviderError {
+    return new ProviderError(
+      err.message,
+      err.kind ?? "UNKNOWN",
+      err.adapterId ?? "unknown",
+      err.context ?? {},
+    );
+  }
+
+  /**
+   * Create from a generic error
+   */
+  static fromError(
+    err: Error,
+    provider: string,
+    kind: ProviderErrorKind = "UNKNOWN",
+  ): ProviderError {
+    return new ProviderError(err.message, kind, provider, {});
+  }
+}
+
+/**
+ * Error classification helper
+ */
+export function classifyErrorMessage(message: string): ProviderErrorKind {
+  const lower = message.toLowerCase();
+
+  // Check patterns in priority order
+  if (lower.includes("rate limit") || lower.includes("429") || lower.includes("too many")) {
+    return "RATE_LIMIT";
+  }
+  if (lower.includes("quota") || lower.includes("credits") || lower.includes("exceeded")) {
+    return "OUT_OF_CREDITS";
+  }
+  if (lower.includes("unauthorized") || lower.includes("401") || lower.includes("api key")) {
+    return "UNAUTHORIZED";
+  }
+  if (lower.includes("forbidden") || lower.includes("403")) {
+    return "FORBIDDEN";
+  }
+  if (lower.includes("not found") || lower.includes("404")) {
+    return "NOT_FOUND";
+  }
+  if (lower.includes("timeout") || lower.includes("timed out")) {
+    return "TIMEOUT";
+  }
+  if (lower.includes("context length") || lower.includes("too long")) {
+    return "CONTEXT_LENGTH";
+  }
+  if (lower.includes("content filter") || lower.includes("blocked")) {
+    return "CONTENT_FILTER";
+  }
+  if (lower.includes("500") || lower.includes("internal error")) {
+    return "INTERNAL";
+  }
+  if (lower.includes("bad request") || lower.includes("400")) {
+    return "BAD_REQUEST";
+  }
+
+  return "TRANSIENT";
+}

package/src/core/unified/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Unified Interface Exports
+ */
+
+// Capabilities
+export {
+  Capability,
+  type CapabilityType,
+  type ICapabilities,
+  ProviderCapabilities,
+} from "./capabilities";
+
+// Output
+export {
+  type IOutput,
+  type IOutputMeta,
+  type UnifiedStreamChunk,
+  type IProviderError as IOutputError,
+  type NormalizerConfig,
+  DEFAULT_NORMALIZER_CONFIG,
+  OutputNormalizer,
+} from "./output";
+
+// Errors
+export {
+  type IProviderError,
+  ProviderError,
+  classifyErrorMessage,
+} from "./errors";

package/src/core/unified/output.ts

@@ -0,0 +1,189 @@
+/**
+ * Unified Output Types
+ *
+ * Provides a consistent output format across all providers.
+ */
+
+import type { TokenUsage } from "../types";
+
+/**
+ * Normalized output format - all providers produce this
+ */
+export interface IOutput {
+  /** The text response */
+  readonly text: string;
+
+  /** Token usage (if available) */
+  readonly usage?: TokenUsage;
+
+  /** Response metadata */
+  readonly meta: IOutputMeta;
+
+  /** Original raw output (for debugging) */
+  readonly raw?: unknown;
+}
+
+/**
+ * Output metadata
+ */
+export interface IOutputMeta {
+  readonly provider: string;
+  readonly model?: string;
+  readonly elapsedMs: number;
+  readonly finishReason?: "stop" | "length" | "content_filter" | "error";
+  readonly streamingMode?: "none" | "text" | "jsonl";
+}
+
+/**
+ * Streaming output chunk types (unified)
+ */
+export type UnifiedStreamChunk =
+  | { type: "start"; provider: string; model?: string; requestId: string }
+  | { type: "text"; content: string }
+  | { type: "json"; data: unknown }
+  | { type: "usage"; usage: TokenUsage }
+  | { type: "complete"; output: IOutput }
+  | { type: "error"; error: IProviderError };
+
+/**
+ * Provider error interface
+ */
+export interface IProviderError {
+  readonly message: string;
+  readonly kind: string;
+  readonly provider: string;
+  readonly isRetryable: boolean;
+}
+
+/**
+ * Output normalizer configuration
+ */
+export interface NormalizerConfig {
+  /** Fields to check for text in JSON output */
+  jsonTextFields: string[];
+  /** Field containing usage info */
+  jsonUsageField?: string;
+  /** Fields to check for text in JSONL streaming */
+  jsonlTextFields: string[];
+}
+
+/**
+ * Default normalizer configuration
+ */
+export const DEFAULT_NORMALIZER_CONFIG: NormalizerConfig = {
+  jsonTextFields: ["text", "response", "output", "content", "result", "message"],
+  jsonUsageField: "usage",
+  jsonlTextFields: ["text", "delta", "content"],
+};
+
+/**
+ * Output normalizer - converts raw output to unified format
+ */
+export class OutputNormalizer {
+  private config: NormalizerConfig;
+
+  constructor(config: NormalizerConfig = DEFAULT_NORMALIZER_CONFIG) {
+    this.config = config;
+  }
+
+  /**
+   * Normalize raw text output
+   */
+  normalizeText(stdout: string, meta: Partial<IOutputMeta>): IOutput {
+    return {
+      text: stdout.trim(),
+      meta: this.buildMeta(meta),
+      raw: stdout,
+    };
+  }
+
+  /**
+   * Normalize JSON output
+   */
+  normalizeJson(stdout: string, meta: Partial<IOutputMeta>): IOutput {
+    try {
+      const parsed = JSON.parse(stdout);
+      const text = this.extractTextField(parsed);
+      const usage = this.extractUsage(parsed);
+
+      return {
+        text,
+        usage,
+        meta: this.buildMeta(meta),
+        raw: parsed,
+      };
+    } catch {
+      // Fall back to text normalization if JSON parsing fails
+      return this.normalizeText(stdout, meta);
+    }
+  }
+
+  /**
+   * Normalize JSONL streaming output
+   */
+  *normalizeJsonl(lines: string[]): Generator<{ text?: string; usage?: TokenUsage }> {
+    for (const line of lines) {
+      if (!line.trim()) continue;
+
+      try {
+        const parsed = JSON.parse(line);
+        const text = this.extractTextField(parsed);
+        const usage = this.extractUsage(parsed);
+
+        if (text) yield { text };
+        if (usage) yield { usage };
+      } catch {
+        // Non-JSON line, emit as text
+        yield { text: line };
+      }
+    }
+  }
+
+  private extractTextField(obj: unknown): string {
+    if (typeof obj === "string") return obj;
+    if (typeof obj !== "object" || obj === null) return String(obj);
+
+    for (const field of this.config.jsonTextFields) {
+      const value = this.getNestedField(obj, field);
+      if (typeof value === "string") return value;
+    }
+
+    return JSON.stringify(obj);
+  }
+
+  private extractUsage(obj: unknown): TokenUsage | undefined {
+    if (typeof obj !== "object" || obj === null) return undefined;
+
+    const usageField = this.config.jsonUsageField;
+    if (usageField) {
+      const usage = this.getNestedField(obj, usageField);
+      if (usage && typeof usage === "object") {
+        return usage as TokenUsage;
+      }
+    }
+
+    return undefined;
+  }
+
+  private getNestedField(obj: unknown, path: string): unknown {
+    const parts = path.split(".");
+    let current = obj;
+
+    for (const part of parts) {
+      if (current === null || current === undefined) return undefined;
+      current = (current as Record<string, unknown>)[part];
+    }
+
+    return current;
+  }
+
+  private buildMeta(partial: Partial<IOutputMeta>): IOutputMeta {
+    return {
+      provider: partial.provider || "unknown",
+      model: partial.model,
+      elapsedMs: partial.elapsedMs || 0,
+      finishReason: partial.finishReason,
+      streamingMode: partial.streamingMode,
+    };
+  }
+}

package/src/core/wrap-terminalcoder.ts

@@ -0,0 +1,245 @@
+import { ConfigLoader } from "./config";
+import { ProviderFactory, RequestDeduplicator } from "./provider-factory";
+import { CodexProvider } from "./providers/codex";
+import { CustomProvider } from "./providers/custom";
+import { GeminiProvider } from "./providers/gemini";
+import type { Provider } from "./providers/index";
+import { OpenCodeProvider } from "./providers/opencode";
+import { QwenCodeProvider } from "./providers/qwen-code";
+import { Router } from "./router";
+import { StateManager } from "./state";
+import type { CodingEvent, CodingRequest, CodingResponse, Config } from "./types";
+
+export interface WrapTerminalCoderConfig {
+  configPath?: string;
+  /** Preload providers at startup (default: false for lazy loading) */
+  preloadProviders?: boolean;
+  /** Enable request deduplication (default: true) */
+  deduplicateRequests?: boolean;
+}
+
+export class WrapTerminalCoder {
+  private configLoader: ConfigLoader;
+  private config: Config;
+  private stateManager: StateManager;
+  private router: Router;
+  private providerFactory: ProviderFactory;
+  private deduplicator: RequestDeduplicator | null;
+
+  private constructor(
+    configLoader: ConfigLoader,
+    config: Config,
+    stateManager: StateManager,
+    router: Router,
+    providerFactory: ProviderFactory,
+    deduplicator: RequestDeduplicator | null,
+  ) {
+    this.configLoader = configLoader;
+    this.config = config;
+    this.stateManager = stateManager;
+    this.router = router;
+    this.providerFactory = providerFactory;
+    this.deduplicator = deduplicator;
+  }
+
+  static async create(config: WrapTerminalCoderConfig = {}): Promise<WrapTerminalCoder> {
+    // Load configuration
+    const configLoader = new ConfigLoader({
+      projectConfigPath: config.configPath,
+    });
+    const loadedConfig = await configLoader.loadConfig();
+
+    // Initialize state manager
+    const stateManager = new StateManager();
+    await stateManager.initialize();
+
+    // Create provider factory with lazy loading
+    const providerFactory = new ProviderFactory(loadedConfig);
+
+    // Register known provider constructors
+    providerFactory.registerProvider("gemini", (id, cfg) => new GeminiProvider(cfg));
+    providerFactory.registerProvider("qwen-code", (id, cfg) => new QwenCodeProvider(cfg));
+    providerFactory.registerProvider("codex", (id, cfg) => new CodexProvider(cfg));
+    providerFactory.registerProvider("opencode", (id, cfg) => new OpenCodeProvider(cfg));
+    providerFactory.registerCustomProvider((id, cfg) => new CustomProvider(id, cfg));
+
+    // Create request deduplicator
+    const deduplicator = config.deduplicateRequests !== false ? new RequestDeduplicator() : null;
+
+    // Optionally preload providers (legacy behavior)
+    let providers: Map<string, Provider>;
+    if (config.preloadProviders) {
+      const providerIds = Object.keys(loadedConfig.providers);
+      await providerFactory.preloadProviders(providerIds);
+      providers = providerFactory.getCachedProviders();
+    } else {
+      // Create a lazy-loading proxy map for the router
+      providers = new LazyProviderMap(providerFactory, Object.keys(loadedConfig.providers));
+    }
+
+    // Create router
+    const router = new Router(providers, {
+      config: loadedConfig,
+      stateManager,
+    });
+
+    return new WrapTerminalCoder(
+      configLoader,
+      loadedConfig,
+      stateManager,
+      router,
+      providerFactory,
+      deduplicator,
+    );
+  }
+
+  async route(request: CodingRequest): Promise<CodingResponse> {
+    return await this.router.route(request);
+  }
+
+  async *routeStream(request: CodingRequest): AsyncGenerator<CodingResponse> {
+    yield* this.router.routeStream(request);
+  }
+
+  async getProviderInfo(): Promise<any[]> {
+    const providerInfo = [];
+    const providerIds = Object.keys(this.config.providers);
+
+    for (const id of providerIds) {
+      const state = await this.stateManager.getProviderState(id);
+      const isAvailable = await this.providerFactory.isProviderAvailable(id);
+      providerInfo.push({
+        id,
+        displayName: this.getProviderDisplayName(id),
+        requestsToday: state.requestsToday,
+        outOfCreditsUntil: state.outOfCreditsUntil,
+        available: isAvailable,
+      });
+    }
+
+    return providerInfo;
+  }
+
+  /**
+   * Get available provider IDs (those with valid binaries)
+   */
+  async getAvailableProviders(): Promise<string[]> {
+    return this.providerFactory.getAvailableProviderIds();
+  }
+
+  getRouter(): Router {
+    return this.router;
+  }
+
+  getStateManager(): StateManager {
+    return this.stateManager;
+  }
+
+  getConfig(): Config {
+    return this.config;
+  }
+
+  getProviderFactory(): ProviderFactory {
+    return this.providerFactory;
+  }
+
+  private getProviderDisplayName(id: string): string {
+    const displayNames: Record<string, string> = {
+      gemini: "Gemini CLI",
+      "qwen-code": "Qwen Code CLI",
+      codex: "Codex CLI",
+      opencode: "OpenCode Agent",
+    };
+    return displayNames[id] || id;
+  }
+}
+
+/**
+ * LazyProviderMap - A Map-like object that lazily loads providers
+ *
+ * This allows the Router to work with providers without loading them all upfront.
+ * Providers are loaded on first access via get().
+ */
+class LazyProviderMap implements Map<string, Provider> {
+  private factory: ProviderFactory;
+  private knownIds: Set<string>;
+  private cache: Map<string, Provider> = new Map();
+
+  constructor(factory: ProviderFactory, providerIds: string[]) {
+    this.factory = factory;
+    this.knownIds = new Set(providerIds);
+  }
+
+  get(key: string): Provider | undefined {
+    // Return from cache if available
+    if (this.cache.has(key)) {
+      return this.cache.get(key);
+    }
+
+    // For lazy loading, we need to handle async loading synchronously
+    // The Router will need to be updated to handle async provider loading
+    // For now, return undefined and let the Router handle missing providers
+    return undefined;
+  }
+
+  has(key: string): boolean {
+    return this.knownIds.has(key) || this.cache.has(key);
+  }
+
+  set(key: string, value: Provider): this {
+    this.cache.set(key, value);
+    this.knownIds.add(key);
+    return this;
+  }
+
+  delete(key: string): boolean {
+    this.knownIds.delete(key);
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.knownIds.clear();
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.knownIds.size;
+  }
+
+  keys(): IterableIterator<string> {
+    return this.knownIds.values();
+  }
+
+  values(): IterableIterator<Provider> {
+    return this.cache.values();
+  }
+
+  entries(): IterableIterator<[string, Provider]> {
+    return this.cache.entries();
+  }
+
+  forEach(callbackfn: (value: Provider, key: string, map: Map<string, Provider>) => void): void {
+    this.cache.forEach(callbackfn);
+  }
+
+  [Symbol.iterator](): IterableIterator<[string, Provider]> {
+    return this.cache[Symbol.iterator]();
+  }
+
+  [Symbol.toStringTag] = "LazyProviderMap";
+
+  /**
+   * Async method to get a provider (loads if not cached)
+   */
+  async getAsync(key: string): Promise<Provider | null> {
+    if (this.cache.has(key)) {
+      return this.cache.get(key)!;
+    }
+
+    const provider = await this.factory.getProvider(key);
+    if (provider) {
+      this.cache.set(key, provider);
+    }
+    return provider;
+  }
+}