@build-astron-co/nimbus 0.2.0 → 0.4.0

package/src/llm/providers/anthropic.ts

@@ -104,22 +104,45 @@ export class AnthropicProvider extends BaseProvider {
     }
   }
 
+  /** H4: Format a rate limit error with actionable guidance. */
+  private formatRateLimitError(error: unknown): Error {
+    const retryAfter = (error as { headers?: Record<string, string> })?.headers?.['retry-after'];
+    const waitMsg = retryAfter ? `Wait ${retryAfter}s and retry` : 'Wait ~60 seconds and retry';
+    return new Error(
+      `Rate limit reached. Options:\n` +
+      `  • ${waitMsg}\n` +
+      `  • Switch to a faster model: /model claude-haiku-4-5\n` +
+      `  • Check usage: https://console.anthropic.com/settings/usage`
+    );
+  }
+
+  /** H4: Return true if the error is an Anthropic rate limit (429). */
+  private isRateLimitError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') return false;
+    const e = error as { status?: number; error?: { type?: string } };
+    return e.status === 429 || e.error?.type === 'rate_limit_error';
+  }
+
   async completeWithTools(request: ToolCompletionRequest): Promise<LLMResponse> {
     const systemPrompt = this.extractSystemPrompt(request.messages);
     const messages = this.convertMessages(this.filterSystemMessages(request.messages));
 
     const toolChoice = this.convertToolChoice(request.toolChoice);
-    const response = await this.client.messages.create({
-      model: request.model || this.defaultModel,
-      max_tokens: request.maxTokens || 4096,
-      messages,
-      system: systemPrompt,
-      ...(request.toolChoice !== 'none' && { tools: this.convertTools(request.tools) }),
-      ...(toolChoice && { tool_choice: toolChoice }),
-      temperature: request.temperature,
-    });
-
-    return this.convertResponse(response);
+    try {
+      const response = await this.client.messages.create({
+        model: request.model || this.defaultModel,
+        max_tokens: request.maxTokens || 4096,
+        messages,
+        system: systemPrompt,
+        ...(request.toolChoice !== 'none' && { tools: this.convertTools(request.tools) }),
+        ...(toolChoice && { tool_choice: toolChoice }),
+        temperature: request.temperature,
+      });
+      return this.convertResponse(response);
+    } catch (error) {
+      if (this.isRateLimitError(error)) throw this.formatRateLimitError(error);
+      throw error;
+    }
   }
 
   async *streamWithTools(request: ToolCompletionRequest): AsyncIterable<StreamChunk> {
@@ -127,15 +150,21 @@ export class AnthropicProvider extends BaseProvider {
     const messages = this.convertMessages(this.filterSystemMessages(request.messages));
 
     const toolChoice = this.convertToolChoice(request.toolChoice);
-    const stream = await this.client.messages.stream({
-      model: request.model || this.defaultModel,
-      max_tokens: request.maxTokens || 4096,
-      messages,
-      system: systemPrompt,
-      ...(request.toolChoice !== 'none' && { tools: this.convertTools(request.tools) }),
-      ...(toolChoice && { tool_choice: toolChoice }),
-      temperature: request.temperature,
-    });
+    let stream: Awaited<ReturnType<typeof this.client.messages.stream>>;
+    try {
+      stream = await this.client.messages.stream({
+        model: request.model || this.defaultModel,
+        max_tokens: request.maxTokens || 4096,
+        messages,
+        system: systemPrompt,
+        ...(request.toolChoice !== 'none' && { tools: this.convertTools(request.tools) }),
+        ...(toolChoice && { tool_choice: toolChoice }),
+        temperature: request.temperature,
+      });
+    } catch (error) {
+      if (this.isRateLimitError(error)) throw this.formatRateLimitError(error);
+      throw error;
+    }
 
     let usage: StreamChunk['usage'] | undefined;
     let inputTokensFromStart = 0; // Captured from message_start event
@@ -165,7 +194,7 @@ export class AnthropicProvider extends BaseProvider {
           yield { done: false, toolCallStart: { id: currentToolId, name: currentToolName } };
         }
       } else if (event.type === 'content_block_delta') {
-        if (event.delta.type === 'text_delta') {
+        if (event.delta.type === 'text_delta' && event.delta.text) {
           yield { content: event.delta.text, done: false };
         } else if ((event.delta as any).type === 'input_json_delta') {
           const existing = toolCallAccumulator.get(toolCallIndex);

package/src/llm/router.ts

@@ -143,8 +143,8 @@ export class LLMRouter {
       isConfigured = bridge.isProviderConfigured;
       getApiKey = bridge.getProviderApiKey;
     } catch (err) {
-      // Auth-bridge unavailable (e.g., test environment) — fall back to env-only
-      logger.warn(
+      // Auth-bridge unavailable (open-source build) — fall back to env-only
+      logger.debug(
         'Auth-bridge unavailable, using environment variables only:',
         err instanceof Error ? err.message : String(err)
       );
@@ -479,17 +479,15 @@ export class LLMRouter {
         }
         try {
           let lastUsage: StreamChunk['usage'] | undefined;
-          const bufferedChunks: StreamChunk[] = [];
+          // Yield each chunk immediately (no buffering) for real-time streaming UX.
           for await (const chunk of p.streamWithTools(request)) {
-            bufferedChunks.push(chunk);
             if (chunk.usage) {
               lastUsage = chunk.usage;
             }
-          }
-          self.circuitBreaker.recordSuccess(p.name);
-          for (const chunk of bufferedChunks) {
             yield chunk;
           }
+          // Record success after the `done: true` chunk has been received and yielded.
+          self.circuitBreaker.recordSuccess(p.name);
           if (lastUsage) {
             const model = request.model || defaultModel;
             const cost = calculateCost(
@@ -1033,3 +1031,74 @@ export class LLMRouter {
     request.maxTokens = Math.min(request.maxTokens || 4096, maxTokens);
   }
 }
+
+// ---------------------------------------------------------------------------
+// Gap 6: List authenticated providers for /model command
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the names of providers that have valid credentials configured.
+ * Checks both environment variables and the auth store.
+ */
+export function listAuthenticatedProviders(): string[] {
+  const authenticated: string[] = [];
+  if (process.env.ANTHROPIC_API_KEY) authenticated.push('anthropic');
+  if (process.env.OPENAI_API_KEY) authenticated.push('openai');
+  if (process.env.GOOGLE_API_KEY || process.env.GOOGLE_GENERATIVE_AI_API_KEY) authenticated.push('google');
+  if (process.env.GROQ_API_KEY) authenticated.push('groq');
+  if (process.env.OPENROUTER_API_KEY) authenticated.push('openrouter');
+  if (process.env.AWS_ACCESS_KEY_ID || process.env.AWS_PROFILE) authenticated.push('bedrock');
+  return authenticated;
+}
+
+// ---------------------------------------------------------------------------
+// Gap 18: Multi-model routing based on task complexity
+// ---------------------------------------------------------------------------
+
+/** Complexity tiers for automatic model selection. */
+export type TaskComplexity = 'simple' | 'moderate' | 'complex';
+
+/**
+ * Classify a user message as simple, moderate, or complex.
+ *
+ * - **simple**: short status/list/describe queries (<200 chars, no code generation)
+ * - **complex**: long messages, code generation, architectural reasoning
+ * - **moderate**: everything else
+ */
+export function classifyTaskComplexity(message: string): TaskComplexity {
+  const lower = message.toLowerCase().trim();
+
+  // Simple: short status/list queries
+  if (
+    message.length < 200 &&
+    /^(list|show|get|check|status|what is|what are|describe|which|where|who|ping|echo)\b/.test(lower)
+  ) {
+    return 'simple';
+  }
+
+  // Complex: long messages or keywords that imply heavy reasoning
+  if (
+    message.length > 500 ||
+    /\b(implement|design|architect|refactor|migrate|rewrite|build|create|scaffold|generate|optimize|debug|diagnose|analyze)\b/.test(lower)
+  ) {
+    return 'complex';
+  }
+
+  return 'moderate';
+}
+
+/**
+ * Select the appropriate model string for a given complexity level.
+ * If `preferredModel` is provided it always wins (user override).
+ */
+export function routeModel(complexity: TaskComplexity, preferredModel?: string): string {
+  if (preferredModel) return preferredModel;
+  switch (complexity) {
+    case 'simple':
+      return 'anthropic/claude-haiku-4-5-20251001';
+    case 'complex':
+      return 'anthropic/claude-opus-4-6';
+    default:
+      return 'anthropic/claude-sonnet-4-20250514';
+  }
+}

package/src/lsp/languages.ts

@@ -114,3 +114,6 @@ export function getLanguageForFile(filePath: string): LanguageConfig | undefined
 export function getLanguagePriority(): LanguageConfig[] {
   return [...LANGUAGE_CONFIGS];
 }
+
+/** Language IDs relevant for DevOps workflows. */
+export const DEVOPS_LANGUAGE_IDS = ['terraform', 'yaml', 'docker'] as const;

package/src/lsp/manager.ts

@@ -9,6 +9,7 @@
 import { readFile } from 'node:fs/promises';
 import { exec } from 'node:child_process';
 import { promisify } from 'node:util';
+import { EventEmitter } from 'node:events';
 import { LSPClient, type Diagnostic } from './client';
 import { getLanguageForFile, LANGUAGE_CONFIGS, type LanguageConfig } from './languages';
 
@@ -26,16 +27,21 @@ export interface LSPStatus {
   available: boolean;
 }
 
-export class LSPManager {
+export class LSPManager extends EventEmitter {
   private clients = new Map<string, LSPClient>();
-  private idleTimers = new Map<string, Timer>();
+  private idleTimers = new Map<string, ReturnType<typeof setTimeout>>();
   private rootUri: string;
   private availabilityCache = new Map<string, boolean>();
   private fileVersions = new Map<string, number>();
   private enabled: boolean = true;
+  private enabledLanguages?: readonly string[];
+  /** C4: Track languages already reported as unavailable to avoid duplicate events. */
+  private failedLSPs = new Set<string>();
 
-  constructor(rootUri?: string) {
+  constructor(rootUri?: string, options?: { enabledLanguages?: readonly string[] }) {
+    super();
     this.rootUri = rootUri ?? process.cwd();
+    this.enabledLanguages = options?.enabledLanguages;
   }
 
   /** Enable or disable LSP integration. */
@@ -60,6 +66,11 @@ export class LSPManager {
       return;
     }
 
+    // Skip non-enabled language servers if a filter is set
+    if (this.enabledLanguages && !this.enabledLanguages.includes(config.id)) {
+      return;
+    }
+
     // Ensure the client is running
     const client = await this.ensureClient(config);
     if (!client) {
@@ -201,6 +212,11 @@ export class LSPManager {
     // Check if the binary is available
     const available = await this.isAvailable(config);
     if (!available) {
+      // C4: Emit once per language so the TUI can surface a diagnostic message
+      if (!this.failedLSPs.has(config.id)) {
+        this.failedLSPs.add(config.id);
+        this.emit('lsp-unavailable', config.name ?? config.id, config.command);
+      }
       return null;
     }
 
@@ -264,9 +280,9 @@ export class LSPManager {
 let lspManagerInstance: LSPManager | null = null;
 
 /** Get or create the singleton LSP manager. */
-export function getLSPManager(rootUri?: string): LSPManager {
+export function getLSPManager(rootUri?: string, options?: { enabledLanguages?: readonly string[] }): LSPManager {
   if (!lspManagerInstance) {
-    lspManagerInstance = new LSPManager(rootUri);
+    lspManagerInstance = new LSPManager(rootUri, options);
   }
   return lspManagerInstance;
 }

package/src/nimbus.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 /**
  * Nimbus CLI — Main Entry Point
  *
@@ -97,7 +97,16 @@ process.on('uncaughtException', error => {
 });
 
 async function main() {
-  const args = process.argv.slice(2);
+  let args = process.argv.slice(2);
+
+  // G11: Global --project / --cwd flag: change working directory before command dispatch
+  const cwdFlagIdx = args.findIndex(a => a === '--project' || a === '--cwd');
+  if (cwdFlagIdx !== -1 && args[cwdFlagIdx + 1]) {
+    const { resolve } = await import('node:path');
+    const targetDir = resolve(args[cwdFlagIdx + 1]);
+    process.chdir(targetDir);
+    args.splice(cwdFlagIdx, 2);
+  }
 
   // Handle --version and -v before anything else (no init needed)
   if (args[0] === '--version' || args[0] === '-v') {
@@ -105,6 +114,22 @@ async function main() {
     process.exit(0);
   }
 
+  // Handle --completion-install / completion <shell> — print shell completion script
+  if (args[0] === '--completion-install' || args[0] === 'completion') {
+    const shell = args[1] ?? 'bash';
+    const { join } = await import('node:path');
+    const { readFileSync } = await import('node:fs');
+    const { fileURLToPath } = await import('node:url');
+    const dir = join(fileURLToPath(import.meta.url), '../../completions');
+    try {
+      process.stdout.write(readFileSync(join(dir, `nimbus.${shell}`), 'utf-8'));
+    } catch {
+      console.error(`No completion script for shell: ${shell}. Available: bash, zsh, fish`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
   // Show help when explicitly requested — handles both `nimbus --help`
   // and subcommand-level help like `nimbus chat --help` or `nimbus tf -h`.
   if (args.includes('--help') || args.includes('-h')) {
@@ -167,6 +192,14 @@ async function main() {
       }
     }
 
+    // Resolve aliases before dispatching (L2)
+    try {
+      const { resolveAlias } = await import('./commands/alias');
+      args = resolveAlias(args);
+    } catch {
+      /* alias file not found — ignore */
+    }
+
     // Import and run CLI command router
     const { runCommand } = await import('./cli');
     await runCommand(args);
@@ -185,23 +218,9 @@ async function main() {
     }
   } catch (error: any) {
     const msg = error.message || String(error);
-    if (msg.includes('bun:sqlite') || msg.includes('bun:')) {
-      console.error(
-        'Error: Nimbus requires the Bun runtime (for bun:sqlite and other built-in APIs).'
-      );
-      console.error('');
-      console.error('If you have Bun installed, run:');
-      console.error('  bun src/nimbus.ts');
-      console.error('');
-      console.error('To install Bun:');
-      console.error('  curl -fsSL https://bun.sh/install | bash');
-      console.error('');
-      console.error('Or install the pre-built binary (no Bun required):');
-      console.error('  brew install the-ai-project-co/tap/nimbus');
-      console.error('  # or download from GitHub Releases');
-    } else if (error.code === 'MODULE_NOT_FOUND') {
+    if (error.code === 'MODULE_NOT_FOUND') {
       console.error(`Error: Missing module — ${msg}`);
-      console.error('Run "bun install" to install dependencies.');
+      console.error('Run "npm install" to install dependencies.');
     } else {
       console.error(`Error: ${msg}`);
     }

package/src/sessions/manager.ts

@@ -13,6 +13,16 @@ import type { Database } from '../compat/sqlite';
 import type { SessionRecord, SessionStatus, SessionEvent, SessionFileEdit } from './types';
 import type { LLMMessage } from '../llm/types';
 
+/** Infra context persisted per session (terraform workspace, kubectl context, etc.) */
+export interface SessionInfraContext {
+  terraformWorkspace?: string;
+  kubectlContext?: string;
+  awsProfile?: string;
+  awsRegion?: string;
+  gcpProject?: string;
+  azureSubscription?: string;
+}
+
 /** Singleton session manager instance. */
 let instance: SessionManager | null = null;
 
@@ -22,8 +32,17 @@ export class SessionManager {
   private fileEdits: Map<string, SessionFileEdit[]> = new Map();
   private eventListeners: Array<(event: SessionEvent) => void> = [];
 
-  constructor(db?: Database) {
+  /** Pending conversation writes accumulated before the next debounced flush. */
+  private pendingConversationFlush: Map<string, {
+    messages: LLMMessage[];
+    stats?: Partial<Pick<SessionRecord, 'tokenCount' | 'costUSD' | 'snapshotCount' | 'mode' | 'model'>>;
+  }> = new Map();
+  private _flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private readonly flushDebounceMs: number;
+
+  constructor(db?: Database, options?: { flushDebounceMs?: number }) {
     this.db = db || getDb();
+    this.flushDebounceMs = options?.flushDebounceMs ?? 5000;
     this.ensureTable();
   }
 
@@ -214,6 +233,11 @@ export class SessionManager {
     this.emit({ type: 'destroyed', sessionId, timestamp: new Date() });
   }
 
+  /** M2: Rename a session (update its display name). */
+  rename(sessionId: string, name: string): void {
+    this.db.prepare('UPDATE sessions SET name = ? WHERE id = ?').run(name, sessionId);
+  }
+
   /** Update session metadata (tokens, cost, mode, etc.). */
   updateSession(
     sessionId: string,
@@ -275,6 +299,67 @@ export class SessionManager {
     }
   }
 
+  /**
+   * Atomically save conversation messages AND update session stats.
+   * Writes are debounced (default 5s) and batched for performance.
+   * Use `flushAll()` for immediate persistence (shutdown / completion).
+   */
+  saveConversationAndStats(
+    sessionId: string,
+    messages: LLMMessage[],
+    stats: Partial<Pick<SessionRecord, 'tokenCount' | 'costUSD' | 'snapshotCount' | 'mode' | 'model'>>
+  ): void {
+    // Accumulate into the pending flush map (latest write wins per session)
+    const existing = this.pendingConversationFlush.get(sessionId);
+    this.pendingConversationFlush.set(sessionId, {
+      messages,
+      stats: existing?.stats ? { ...existing.stats, ...stats } : stats,
+    });
+    this._scheduleFlush();
+  }
+
+  /** Schedule a debounced flush (no-op if already scheduled). */
+  private _scheduleFlush(): void {
+    if (this._flushTimer !== null) return;
+    if (this.flushDebounceMs === 0) {
+      // Immediate flush path (used in tests)
+      this._flushNow();
+      return;
+    }
+    this._flushTimer = setTimeout(() => {
+      this._flushTimer = null;
+      this._flushNow();
+    }, this.flushDebounceMs);
+  }
+
+  /** Write all pending conversation entries to SQLite. */
+  private _flushNow(): void {
+    if (this.pendingConversationFlush.size === 0) return;
+    const pending = this.pendingConversationFlush;
+    this.pendingConversationFlush = new Map();
+    const txn = this.db.transaction(() => {
+      for (const [sessionId, { messages, stats }] of pending) {
+        this.saveConversation(sessionId, messages);
+        if (stats && Object.keys(stats).length > 0) {
+          this.updateSession(sessionId, stats);
+        }
+      }
+    });
+    txn();
+  }
+
+  /**
+   * Flush all pending conversation writes immediately.
+   * Must be called on clean shutdown and session completion.
+   */
+  flushAll(): void {
+    if (this._flushTimer !== null) {
+      clearTimeout(this._flushTimer);
+      this._flushTimer = null;
+    }
+    this._flushNow();
+  }
+
   /** Load conversation messages for a session. Returns empty array if not found. */
   loadConversation(sessionId: string): LLMMessage[] {
     const row: any = this.db
@@ -321,6 +406,28 @@ export class SessionManager {
     return conflicts;
   }
 
+  /** Persist infra context (terraform workspace, kubectl context, etc.) for a session. */
+  setInfraContext(sessionId: string, ctx: SessionInfraContext): void {
+    const row: any = this.db.prepare('SELECT metadata FROM sessions WHERE id = ?').get(sessionId);
+    const existing = row?.metadata ? JSON.parse(row.metadata) : {};
+    const updated = { ...existing, infraContext: ctx };
+    this.db
+      .prepare("UPDATE sessions SET metadata = ?, updated_at = datetime('now') WHERE id = ?")
+      .run(JSON.stringify(updated), sessionId);
+  }
+
+  /** Retrieve infra context for a session. Returns null if not set. */
+  getInfraContext(sessionId: string): SessionInfraContext | null {
+    const row: any = this.db.prepare('SELECT metadata FROM sessions WHERE id = ?').get(sessionId);
+    if (!row?.metadata) return null;
+    try {
+      const meta = JSON.parse(row.metadata);
+      return meta.infraContext ?? null;
+    } catch {
+      return null;
+    }
+  }
+
   /** Listen for session events. */
   onEvent(listener: (event: SessionEvent) => void): () => void {
     this.eventListeners.push(listener);

package/src/sharing/sync.ts

@@ -18,6 +18,7 @@ import type { LLMMessage } from '../llm/types';
 export const _deps = {
   getConversation: undefined as ((id: string) => any) | undefined,
   getSessionManager: undefined as (() => { get: (id: string) => any }) | undefined,
+  getDb: undefined as (() => any) | undefined,
 };
 
 function getConversation(id: string) {
@@ -60,6 +61,9 @@ export interface SharedSession {
  * Lazily import the DB to avoid circular dependency.
  */
 function getDb() {
+  if (_deps.getDb) {
+    return _deps.getDb();
+  }
   try {
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     const { getDb: _getDb } = require('../state/db');

package/src/sharing/viewer.ts

@@ -95,3 +95,69 @@ function escapeHtml(text: string): string {
     .replace(/"/g, '"')
     .replace(/'/g, ''');
 }
+
+// ---------------------------------------------------------------------------
+// Gap 4: Runbook / Session Export
+// ---------------------------------------------------------------------------
+
+export interface RunbookMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  timestamp?: Date;
+}
+
+export interface RunbookSession {
+  id?: string;
+  model?: string;
+  mode?: string;
+  costUSD?: number;
+  tokenCount?: number;
+}
+
+/**
+ * Format a chat session as a Markdown runbook for team documentation.
+ *
+ * Produces a self-contained `.md` file with:
+ * - Session metadata header (model, date, mode, cost)
+ * - Each user message as a `## User` section
+ * - Each assistant message as an `## Agent` section
+ * - Tool calls as collapsible `<details>` blocks
+ * - System messages skipped (they are implementation details)
+ */
+export function formatSessionAsRunbook(
+  messages: RunbookMessage[],
+  session?: RunbookSession
+): string {
+  const date = new Date().toISOString().slice(0, 19).replace('T', ' ');
+  const lines: string[] = [
+    '# Nimbus Session Runbook',
+    '',
+    '| Field | Value |',
+    '|-------|-------|',
+    `| Date | ${date} |`,
+    `| Model | ${session?.model ?? 'default'} |`,
+    `| Mode | ${session?.mode ?? 'build'} |`,
+    `| Tokens | ${session?.tokenCount?.toLocaleString() ?? 'N/A'} |`,
+    `| Cost | $${session?.costUSD?.toFixed(4) ?? '0.0000'} |`,
+    '',
+    '---',
+    '',
+  ];
+
+  for (const msg of messages) {
+    if (msg.role === 'system') continue;
+
+    const heading = msg.role === 'user' ? '## User' : '## Agent';
+    lines.push(heading);
+    lines.push('');
+
+    // Preserve code blocks; escape HTML outside them
+    const content = msg.content.trim();
+    lines.push(content);
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/tools/file-ops.ts

@@ -127,6 +127,28 @@ export class FileSystemOperations {
     const resolvedPath = this.resolvePath(filePath);
     logger.info(`Reading file: ${resolvedPath}`);
 
+    // Guard against large files that would overflow the context window.
+    // Warn and truncate at 500 KB — enough for most source files.
+    const MAX_READ_BYTES = 500 * 1024;
+    const stat = await fs.stat(resolvedPath);
+    if (stat.size > MAX_READ_BYTES) {
+      const buffer = Buffer.alloc(MAX_READ_BYTES);
+      const fd = await fs.open(resolvedPath, 'r');
+      let bytesRead = 0;
+      try {
+        const result = await fd.read(buffer, 0, MAX_READ_BYTES, 0);
+        bytesRead = result.bytesRead;
+      } finally {
+        await fd.close();
+      }
+      const truncated = buffer.slice(0, bytesRead).toString(encoding);
+      return (
+        truncated +
+        `\n\n[File truncated: ${(stat.size / 1024).toFixed(1)} KB total, showing first ${(bytesRead / 1024).toFixed(0)} KB. ` +
+        `Use line range parameters to read specific sections.]`
+      );
+    }
+
     const content = await fs.readFile(resolvedPath, encoding);
     return content;
   }