@hasna/terminal 2.3.1 → 3.0.1

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/.claude/scheduled_tasks.lock

@@ -1 +0,0 @@
-{"sessionId":"c1e414c7-f1a5-4b9e-bcc4-64c451584cb8","pid":1236,"acquiredAt":1773584959902}

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,20 +0,0 @@
----
-name: Bug Report
-about: Report a bug in open-terminal
-labels: bug
----
-
-**Command:**
-`terminal exec "..."`
-
-**Expected:**
-What you expected to happen
-
-**Actual:**
-What actually happened
-
-**Environment:**
-- OS:
-- Node/Bun version:
-- open-terminal version: (`terminal --version`)
-- Provider: Cerebras / Anthropic

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,14 +0,0 @@
----
-name: Feature Request
-about: Suggest a feature for open-terminal
-labels: enhancement
----
-
-**Use case:**
-What problem does this solve?
-
-**Proposed solution:**
-How should it work?
-
-**Alternatives considered:**
-Other approaches you thought about

package/CONTRIBUTING.md

@@ -1,80 +0,0 @@
-# Contributing to open-terminal
-
-Thanks for your interest in contributing! open-terminal is an open-source smart terminal wrapper that saves AI agents 73-90% of tokens on terminal output.
-
-## Development Setup
-
-```bash
-git clone https://github.com/hasna/terminal.git
-cd terminal
-npm install
-npm run build    # TypeScript compilation
-bun test         # Run tests
-```
-
-## Architecture
-
-```
-src/
-  cli.tsx              # CLI entry point (TUI + subcommands)
-  ai.ts                # NL translation (Cerebras/Anthropic providers)
-  compression.ts       # Token compression engine
-  noise-filter.ts      # Strip noise (npm fund, progress bars, etc.)
-  command-rewriter.ts   # Auto-optimize commands before execution
-  output-processor.ts  # AI-powered output summarization
-  diff-cache.ts        # Diff-aware output caching
-  smart-display.ts     # Visual output compression for TUI
-  file-cache.ts        # Session file read cache
-  lazy-executor.ts     # Lazy execution for large results
-  expand-store.ts      # Progressive disclosure store
-  economy.ts           # Token savings tracker
-  sessions-db.ts       # SQLite session tracking
-  supervisor.ts        # Background process manager
-  snapshots.ts         # Session state snapshots
-  tree.ts              # Tree compression for file listings
-  mcp/
-    server.ts          # MCP server (20+ tools)
-    install.ts         # MCP installer for Claude/Codex/Gemini
-  providers/
-    base.ts            # LLM provider interface
-    anthropic.ts       # Anthropic provider
-    cerebras.ts        # Cerebras provider (default)
-  parsers/             # Structured output parsers
-  search/              # Smart search (file, content, semantic)
-  recipes/             # Reusable command templates
-```
-
-## How to Contribute
-
-### Adding a new parser
-Parsers detect and structure specific command output types. See `src/parsers/` for examples. Each parser needs:
-- `detect(command, output)` — returns true if this parser can handle the output
-- `parse(command, output)` — returns structured data
-
-### Adding a command rewrite rule
-See `src/command-rewriter.ts`. Add a pattern + rewrite function to the `rules` array.
-
-### Adding an MCP tool
-See `src/mcp/server.ts`. Register with `server.tool(name, description, schema, handler)`.
-
-## Running Tests
-
-```bash
-bun test                    # All tests
-bun test src/parsers/       # Parser tests only
-bun test --coverage         # With coverage
-```
-
-## Commit Convention
-
-We use conventional commits:
-- `feat:` — new feature
-- `fix:` — bug fix
-- `refactor:` — code restructuring
-- `test:` — adding tests
-- `docs:` — documentation
-- `chore:` — maintenance
-
-## License
-
-Apache 2.0 — Copyright 2026 Hasna, Inc.