@hasna/terminal 2.3.2 → 3.1.0

package/src/providers/groq.ts

@@ -1,108 +1,9 @@
-// Groq provider — uses OpenAI-compatible API
-// Ultra-fast inference. Supports Llama, Qwen, Kimi models.
+// Groq provider — ultra-fast inference
+import { OpenAICompatibleProvider } from "./openai-compat.js";
 
-import type { LLMProvider, ProviderOptions, StreamCallbacks } from "./base.js";
-
-const GROQ_BASE_URL = "https://api.groq.com/openai/v1";
-const DEFAULT_MODEL = "openai/gpt-oss-120b";
-
-export class GroqProvider implements LLMProvider {
+export class GroqProvider extends OpenAICompatibleProvider {
   readonly name = "groq";
-  private apiKey: string;
-
-  constructor() {
-    this.apiKey = process.env.GROQ_API_KEY ?? "";
-  }
-
-  isAvailable(): boolean {
-    return !!process.env.GROQ_API_KEY;
-  }
-
-  async complete(prompt: string, options: ProviderOptions): Promise<string> {
-    const model = options.model ?? DEFAULT_MODEL;
-    const res = await fetch(`${GROQ_BASE_URL}/chat/completions`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-      },
-      body: JSON.stringify({
-        model,
-        max_tokens: options.maxTokens ?? 256,
-        messages: [
-          { role: "system", content: options.system },
-          { role: "user", content: prompt },
-        ],
-      }),
-    });
-
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`Groq API error ${res.status}: ${text}`);
-    }
-
-    const json = (await res.json()) as any;
-    return (json.choices?.[0]?.message?.content ?? "").trim();
-  }
-
-  async stream(prompt: string, options: ProviderOptions, callbacks: StreamCallbacks): Promise<string> {
-    const model = options.model ?? DEFAULT_MODEL;
-    const res = await fetch(`${GROQ_BASE_URL}/chat/completions`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-      },
-      body: JSON.stringify({
-        model,
-        max_tokens: options.maxTokens ?? 256,
-        stream: true,
-        messages: [
-          { role: "system", content: options.system },
-          { role: "user", content: prompt },
-        ],
-      }),
-    });
-
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`Groq API error ${res.status}: ${text}`);
-    }
-
-    let result = "";
-    const reader = res.body?.getReader();
-    if (!reader) throw new Error("No response body");
-
-    const decoder = new TextDecoder();
-    let buffer = "";
-
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-
-      buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split("\n");
-      buffer = lines.pop() ?? "";
-
-      for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed.startsWith("data: ")) continue;
-        const data = trimmed.slice(6);
-        if (data === "[DONE]") break;
-
-        try {
-          const parsed = JSON.parse(data) as any;
-          const delta = parsed.choices?.[0]?.delta?.content;
-          if (delta) {
-            result += delta;
-            callbacks.onToken(result.trim());
-          }
-        } catch {
-          // skip malformed chunks
-        }
-      }
-    }
-
-    return result.trim();
-  }
+  protected readonly baseUrl = "https://api.groq.com/openai/v1";
+  protected readonly defaultModel = "openai/gpt-oss-120b";
+  protected readonly apiKeyEnvVar = "GROQ_API_KEY";
 }

package/src/providers/index.ts

@@ -1,6 +1,6 @@
-// Provider auto-detection and management
+// Provider auto-detection and management — with fallback on failure
 
-import type { LLMProvider, ProviderConfig } from "./base.js";
+import type { LLMProvider, ProviderConfig, ProviderOptions, StreamCallbacks } from "./base.js";
 import { DEFAULT_PROVIDER_CONFIG } from "./base.js";
 import { AnthropicProvider } from "./anthropic.js";
 import { CerebrasProvider } from "./cerebras.js";
@@ -11,10 +11,11 @@ export type { LLMProvider, ProviderOptions, StreamCallbacks, ProviderConfig } fr
 export { DEFAULT_PROVIDER_CONFIG } from "./base.js";
 
 let _provider: LLMProvider | null = null;
+let _failedProviders: Set<string> = new Set();
 
 /** Get the active LLM provider. Auto-detects based on available API keys. */
 export function getProvider(config?: ProviderConfig): LLMProvider {
-  if (_provider) return _provider;
+  if (_provider && !_failedProviders.has(_provider.name)) return _provider;
 
   const cfg = config ?? DEFAULT_PROVIDER_CONFIG;
   _provider = resolveProvider(cfg);
@@ -24,46 +25,51 @@ export function getProvider(config?: ProviderConfig): LLMProvider {
 /** Reset the cached provider (useful when config changes). */
 export function resetProvider() {
   _provider = null;
+  _failedProviders.clear();
+}
+
+/** Get a fallback-wrapped provider that tries alternatives on failure */
+export function getProviderWithFallback(config?: ProviderConfig): LLMProvider {
+  const primary = getProvider(config);
+  return new FallbackProvider(primary);
 }
 
 function resolveProvider(config: ProviderConfig): LLMProvider {
-  if (config.provider === "cerebras") {
-    const p = new CerebrasProvider();
-    if (!p.isAvailable()) throw new Error("CEREBRAS_API_KEY not set. Run: export CEREBRAS_API_KEY=your-key");
-    return p;
+  if (config.provider !== "auto") {
+    const providers: Record<string, () => LLMProvider> = {
+      cerebras: () => new CerebrasProvider(),
+      anthropic: () => new AnthropicProvider(),
+      groq: () => new GroqProvider(),
+      xai: () => new XaiProvider(),
+    };
+    const factory = providers[config.provider];
+    if (factory) {
+      const p = factory();
+      if (!p.isAvailable()) throw new Error(`${config.provider.toUpperCase()}_API_KEY not set`);
+      return p;
+    }
   }
 
-  if (config.provider === "anthropic") {
-    const p = new AnthropicProvider();
-    if (!p.isAvailable()) throw new Error("ANTHROPIC_API_KEY not set. Run: export ANTHROPIC_API_KEY=your-key");
-    return p;
-  }
+  // auto: prefer Cerebras, then xAI, then Groq, then Anthropic — skip failed
+  const candidates: LLMProvider[] = [
+    new CerebrasProvider(),
+    new XaiProvider(),
+    new GroqProvider(),
+    new AnthropicProvider(),
+  ];
 
-  if (config.provider === "groq") {
-    const p = new GroqProvider();
-    if (!p.isAvailable()) throw new Error("GROQ_API_KEY not set. Run: export GROQ_API_KEY=your-key");
-    return p;
+  for (const p of candidates) {
+    if (p.isAvailable() && !_failedProviders.has(p.name)) return p;
   }
 
-  if (config.provider === "xai") {
-    const p = new XaiProvider();
-    if (!p.isAvailable()) throw new Error("XAI_API_KEY not set. Run: export XAI_API_KEY=your-key");
-    return p;
+  // If all failed, clear failures and try again
+  if (_failedProviders.size > 0) {
+    _failedProviders.clear();
+    for (const p of candidates) {
+      if (p.isAvailable()) return p;
+    }
   }
 
-  // auto: prefer Cerebras (qwen-235b, fast + accurate), then xAI, then Groq, then Anthropic
-  const cerebras = new CerebrasProvider();
-  if (cerebras.isAvailable()) return cerebras;
-
-  const xai = new XaiProvider();
-  if (xai.isAvailable()) return xai;
-
-  const groq = new GroqProvider();
-  if (groq.isAvailable()) return groq;
-
-  const anthropic = new AnthropicProvider();
-  if (anthropic.isAvailable()) return anthropic;
-
   throw new Error(
     "No API key found. Set one of:\n" +
     "  export CEREBRAS_API_KEY=your-key  (free, open-source)\n" +
@@ -73,6 +79,51 @@ function resolveProvider(config: ProviderConfig): LLMProvider {
   );
 }
 
+/** Provider wrapper that falls back to alternatives on API errors */
+class FallbackProvider implements LLMProvider {
+  readonly name: string;
+  private primary: LLMProvider;
+
+  constructor(primary: LLMProvider) {
+    this.primary = primary;
+    this.name = primary.name;
+  }
+
+  isAvailable(): boolean {
+    return this.primary.isAvailable();
+  }
+
+  async complete(prompt: string, options: ProviderOptions): Promise<string> {
+    try {
+      return await this.primary.complete(prompt, options);
+    } catch (err) {
+      const fallback = this.getFallback();
+      if (fallback) return fallback.complete(prompt, options);
+      throw err;
+    }
+  }
+
+  async stream(prompt: string, options: ProviderOptions, callbacks: StreamCallbacks): Promise<string> {
+    try {
+      return await this.primary.stream(prompt, options, callbacks);
+    } catch (err) {
+      const fallback = this.getFallback();
+      if (fallback) return fallback.complete(prompt, options); // fallback doesn't stream
+      throw err;
+    }
+  }
+
+  private getFallback(): LLMProvider | null {
+    _failedProviders.add(this.primary.name);
+    _provider = null; // force re-resolve
+    try {
+      const next = getProvider();
+      if (next.name !== this.primary.name) return next;
+    } catch {}
+    return null;
+  }
+}
+
 /** List available providers (for onboarding UI). */
 export function availableProviders(): { name: string; available: boolean }[] {
   return [

package/src/providers/openai-compat.ts

@@ -0,0 +1,109 @@
+// Shared base class for OpenAI-compatible providers (Cerebras, Groq, xAI)
+// Eliminates ~200 lines of duplicated streaming SSE parsing
+
+import type { LLMProvider, ProviderOptions, StreamCallbacks } from "./base.js";
+
+export abstract class OpenAICompatibleProvider implements LLMProvider {
+  abstract readonly name: string;
+  protected abstract readonly baseUrl: string;
+  protected abstract readonly defaultModel: string;
+  protected abstract readonly apiKeyEnvVar: string;
+
+  protected get apiKey(): string {
+    return process.env[this.apiKeyEnvVar] ?? "";
+  }
+
+  isAvailable(): boolean {
+    return !!process.env[this.apiKeyEnvVar];
+  }
+
+  async complete(prompt: string, options: ProviderOptions): Promise<string> {
+    const res = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: options.model ?? this.defaultModel,
+        max_tokens: options.maxTokens ?? 256,
+        temperature: options.temperature ?? 0,
+        ...(options.stop ? { stop: options.stop } : {}),
+        messages: [
+          { role: "system", content: options.system },
+          { role: "user", content: prompt },
+        ],
+      }),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`${this.name} API error ${res.status}: ${text}`);
+    }
+
+    const json = (await res.json()) as any;
+    return (json.choices?.[0]?.message?.content ?? "").trim();
+  }
+
+  async stream(prompt: string, options: ProviderOptions, callbacks: StreamCallbacks): Promise<string> {
+    const res = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: options.model ?? this.defaultModel,
+        max_tokens: options.maxTokens ?? 256,
+        temperature: options.temperature ?? 0,
+        stream: true,
+        ...(options.stop ? { stop: options.stop } : {}),
+        messages: [
+          { role: "system", content: options.system },
+          { role: "user", content: prompt },
+        ],
+      }),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`${this.name} API error ${res.status}: ${text}`);
+    }
+
+    let result = "";
+    const reader = res.body?.getReader();
+    if (!reader) throw new Error("No response body");
+
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("data: ")) continue;
+        const data = trimmed.slice(6);
+        if (data === "[DONE]") break;
+
+        try {
+          const parsed = JSON.parse(data) as any;
+          const delta = parsed.choices?.[0]?.delta?.content;
+          if (delta) {
+            result += delta;
+            callbacks.onToken(result.trim());
+          }
+        } catch {
+          // skip malformed chunks
+        }
+      }
+    }
+
+    return result.trim();
+  }
+}

package/src/providers/xai.ts

@@ -1,108 +1,9 @@
-// xAI/Grok provider — uses OpenAI-compatible API
-// grok-code-fast-1 for code tasks, grok-4-fast for general queries.
+// xAI/Grok provider — code-optimized models
+import { OpenAICompatibleProvider } from "./openai-compat.js";
 
-import type { LLMProvider, ProviderOptions, StreamCallbacks } from "./base.js";
-
-const XAI_BASE_URL = "https://api.x.ai/v1";
-const DEFAULT_MODEL = "grok-code-fast-1";
-
-export class XaiProvider implements LLMProvider {
+export class XaiProvider extends OpenAICompatibleProvider {
   readonly name = "xai";
-  private apiKey: string;
-
-  constructor() {
-    this.apiKey = process.env.XAI_API_KEY ?? "";
-  }
-
-  isAvailable(): boolean {
-    return !!process.env.XAI_API_KEY;
-  }
-
-  async complete(prompt: string, options: ProviderOptions): Promise<string> {
-    const model = options.model ?? DEFAULT_MODEL;
-    const res = await fetch(`${XAI_BASE_URL}/chat/completions`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-      },
-      body: JSON.stringify({
-        model,
-        max_tokens: options.maxTokens ?? 256,
-        messages: [
-          { role: "system", content: options.system },
-          { role: "user", content: prompt },
-        ],
-      }),
-    });
-
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`xAI API error ${res.status}: ${text}`);
-    }
-
-    const json = (await res.json()) as any;
-    return (json.choices?.[0]?.message?.content ?? "").trim();
-  }
-
-  async stream(prompt: string, options: ProviderOptions, callbacks: StreamCallbacks): Promise<string> {
-    const model = options.model ?? DEFAULT_MODEL;
-    const res = await fetch(`${XAI_BASE_URL}/chat/completions`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-      },
-      body: JSON.stringify({
-        model,
-        max_tokens: options.maxTokens ?? 256,
-        stream: true,
-        messages: [
-          { role: "system", content: options.system },
-          { role: "user", content: prompt },
-        ],
-      }),
-    });
-
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`xAI API error ${res.status}: ${text}`);
-    }
-
-    let result = "";
-    const reader = res.body?.getReader();
-    if (!reader) throw new Error("No response body");
-
-    const decoder = new TextDecoder();
-    let buffer = "";
-
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-
-      buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split("\n");
-      buffer = lines.pop() ?? "";
-
-      for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed.startsWith("data: ")) continue;
-        const data = trimmed.slice(6);
-        if (data === "[DONE]") break;
-
-        try {
-          const parsed = JSON.parse(data) as any;
-          const delta = parsed.choices?.[0]?.delta?.content;
-          if (delta) {
-            result += delta;
-            callbacks.onToken(result.trim());
-          }
-        } catch {
-          // skip malformed chunks
-        }
-      }
-    }
-
-    return result.trim();
-  }
+  protected readonly baseUrl = "https://api.x.ai/v1";
+  protected readonly defaultModel = "grok-code-fast-1";
+  protected readonly apiKeyEnvVar = "XAI_API_KEY";
 }

package/src/tokens.ts

@@ -0,0 +1,18 @@
+// Token estimation utility — shared across all modules
+// Uses content-aware heuristic: code/JSON averages ~3.3 chars/token,
+// English prose averages ~4.2 chars/token.
+
+/** Detect if content is primarily code/JSON vs English prose */
+function isCodeLike(text: string): boolean {
+  // Count structural characters common in code/JSON
+  const structural = (text.match(/[{}[\]();:=<>,"'`|&\\/@#$%^*+~!?]/g) || []).length;
+  const ratio = structural / Math.max(text.length, 1);
+  return ratio > 0.08; // >8% structural chars = code-like
+}
+
+/** Estimate token count for a string with content-aware heuristic */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  const charsPerToken = isCodeLike(text) ? 3.3 : 4.2;
+  return Math.ceil(text.length / charsPerToken);
+}

package/src/tool-profiles.ts

@@ -107,12 +107,19 @@ function loadUserProfiles(): ToolProfile[] {
   return profiles;
 }
 
-/** Get all profiles — user profiles override builtins by name */
+/** Get all profiles — user profiles override builtins by name (cached 30s) */
+let _cachedProfiles: ToolProfile[] | null = null;
+let _cachedProfilesAt = 0;
+
 export function getProfiles(): ToolProfile[] {
+  const now = Date.now();
+  if (_cachedProfiles && now - _cachedProfilesAt < 30_000) return _cachedProfiles;
   const user = loadUserProfiles();
   const userNames = new Set(user.map(p => p.name));
   const builtins = BUILTIN_PROFILES.filter(p => !userNames.has(p.name));
-  return [...user, ...builtins];
+  _cachedProfiles = [...user, ...builtins];
+  _cachedProfilesAt = now;
+  return _cachedProfiles;
 }
 
 /** Find the matching profile for a command */

package/src/compression.test.ts

@@ -1,49 +0,0 @@
-import { describe, it, expect } from "bun:test";
-import { compress, stripAnsi } from "./compression.js";
-
-describe("stripAnsi", () => {
-  it("removes ANSI escape codes", () => {
-    expect(stripAnsi("\x1b[31mred\x1b[0m")).toBe("red");
-    expect(stripAnsi("\x1b[1;32mbold green\x1b[0m")).toBe("bold green");
-  });
-
-  it("leaves clean text unchanged", () => {
-    expect(stripAnsi("hello world")).toBe("hello world");
-  });
-});
-
-describe("compress", () => {
-  it("strips ANSI by default", () => {
-    const result = compress("ls", "\x1b[32mfile.ts\x1b[0m");
-    expect(result.content).not.toContain("\x1b");
-  });
-
-  it("uses structured parser when format=json", () => {
-    const output = `total 16
--rw-r--r--  1 user staff  450 Mar 10 09:00 package.json
-drwxr-xr-x  5 user staff  160 Mar 10 09:00 src`;
-
-    const result = compress("ls -la", output, { format: "json" });
-    // Parser may skip JSON if it's larger than raw — just check it returned something
-    expect(result.content).toBeTruthy();
-    expect(result.compressedTokens).toBeGreaterThan(0);
-  });
-
-  it("respects maxTokens budget", () => {
-    const longOutput = Array.from({ length: 100 }, (_, i) => `Line ${i}: some output text here`).join("\n");
-    const result = compress("some-command", longOutput, { maxTokens: 50 });
-    expect(result.compressedTokens).toBeLessThanOrEqual(60); // allow some slack
-  });
-
-  it("deduplicates similar lines", () => {
-    const output = Array.from({ length: 20 }, (_, i) => `Compiling module ${i}...`).join("\n");
-    const result = compress("build", output);
-    expect(result.compressedTokens).toBeLessThan(result.originalTokens);
-  });
-
-  it("tracks savings on large output", () => {
-    const output = Array.from({ length: 100 }, (_, i) => `Line ${i}: some long output text here that takes tokens`).join("\n");
-    const result = compress("cmd", output, { maxTokens: 50 });
-    expect(result.compressedTokens).toBeLessThan(result.originalTokens);
-  });
-});

package/src/output-router.ts

@@ -1,56 +0,0 @@
-// Output intelligence router — auto-detect command type and optimize output
-
-import { parseOutput, estimateTokens } from "./parsers/index.js";
-import { compress, stripAnsi } from "./compression.js";
-import { recordSaving } from "./economy.js";
-
-export interface RouterResult {
-  raw: string;
-  structured?: unknown;
-  compressed?: string;
-  parser?: string;
-  tokensSaved: number;
-  format: "raw" | "json" | "compressed";
-}
-
-/** Route command output through the best optimization path */
-export function routeOutput(command: string, output: string, maxTokens?: number): RouterResult {
-  const clean = stripAnsi(output);
-  const rawTokens = estimateTokens(clean);
-
-  // Try structured parsing first
-  const parsed = parseOutput(command, clean);
-  if (parsed) {
-    const json = JSON.stringify(parsed.data);
-    const jsonTokens = estimateTokens(json);
-    const saved = rawTokens - jsonTokens;
-
-    if (saved > 0) {
-      recordSaving("structured", saved);
-      return {
-        raw: clean,
-        structured: parsed.data,
-        parser: parsed.parser,
-        tokensSaved: saved,
-        format: "json",
-      };
-    }
-  }
-
-  // Try compression if structured didn't save enough
-  if (maxTokens || rawTokens > 200) {
-    const compressed = compress(command, clean, { maxTokens, format: "text" });
-    if (compressed.tokensSaved > 0) {
-      recordSaving("compressed", compressed.tokensSaved);
-      return {
-        raw: clean,
-        compressed: compressed.content,
-        tokensSaved: compressed.tokensSaved,
-        format: "compressed",
-      };
-    }
-  }
-
-  // Return raw if no optimization helps
-  return { raw: clean, tokensSaved: 0, format: "raw" };
-}