@build-astron-co/nimbus 0.2.0 → 0.4.0

package/dist/src/hooks/engine.js

@@ -0,0 +1,317 @@
+/**
+ * Hook Execution Engine
+ *
+ * Executes user-defined hooks before and after tool invocations.
+ * Hook scripts receive JSON context on stdin and communicate results
+ * via exit codes:
+ *
+ *   - Exit 0  = allow (proceed with the tool call)
+ *   - Exit 2  = block (prevent the tool call; stderr/stdout used as message)
+ *   - Other   = error (proceed but log a warning)
+ *
+ * Hooks are killed after their configured timeout (default 30 seconds).
+ */
+import { spawn } from 'node:child_process';
+import { loadHooksConfig, DEFAULT_HOOK_TIMEOUT, } from './config';
+// ---------------------------------------------------------------------------
+// HookEngine
+// ---------------------------------------------------------------------------
+/**
+ * Core engine that loads hook configuration and executes matching hooks.
+ *
+ * @example
+ * ```ts
+ * const engine = new HookEngine('/path/to/project');
+ *
+ * const results = await engine.executeHooks('PreToolUse', {
+ *   tool: 'edit_file',
+ *   input: { path: 'main.tf' },
+ *   sessionId: 'abc-123',
+ *   agent: 'build',
+ *   timestamp: new Date().toISOString(),
+ * });
+ *
+ * if (results.some(r => !r.allowed)) {
+ *   console.log('Tool call blocked by hook');
+ * }
+ * ```
+ */
+export class HookEngine {
+    config = null;
+    /**
+     * Create a new HookEngine, optionally loading config immediately.
+     *
+     * @param projectDir - If provided, loads `.nimbus/hooks.yaml` from this directory
+     */
+    constructor(projectDir) {
+        if (projectDir) {
+            this.loadConfig(projectDir);
+        }
+    }
+    /**
+     * Load (or reload) hooks configuration from disk.
+     *
+     * @param projectDir - Absolute path to the project root
+     */
+    loadConfig(projectDir) {
+        this.config = loadHooksConfig(projectDir);
+    }
+    /**
+     * Check whether any hooks are registered for the given event and tool name.
+     *
+     * @param event    - Hook lifecycle event
+     * @param toolName - Name of the tool being invoked
+     * @returns `true` if at least one hook matches
+     */
+    hasHooks(event, toolName) {
+        return this.getMatchingHooks(event, toolName).length > 0;
+    }
+    /**
+     * Return all hook definitions whose `match` pattern matches the tool name.
+     *
+     * @param event    - Hook lifecycle event
+     * @param toolName - Name of the tool being invoked
+     * @returns Array of matching hook definitions (may be empty)
+     */
+    getMatchingHooks(event, toolName) {
+        if (!this.config) {
+            return [];
+        }
+        const hooks = this.config.hooks[event];
+        if (!hooks || hooks.length === 0) {
+            return [];
+        }
+        return hooks.filter(hook => {
+            try {
+                const regex = new RegExp(hook.match);
+                return regex.test(toolName);
+            }
+            catch {
+                // Invalid regex -- skip silently (was validated at load time,
+                // but be defensive)
+                return false;
+            }
+        });
+    }
+    /**
+     * Execute all hooks matching the given event and tool name.
+     *
+     * Hooks are executed sequentially in definition order. For `PreToolUse`
+     * events, if **any** hook returns exit code 2 the tool call is blocked
+     * (but remaining hooks still execute for auditing purposes).
+     *
+     * @param event   - Hook lifecycle event
+     * @param context - Context object passed to each hook via stdin
+     * @returns Array of results, one per matching hook
+     */
+    async executeHooks(event, context) {
+        const hooks = this.getMatchingHooks(event, context.tool);
+        if (hooks.length === 0) {
+            return [];
+        }
+        const results = [];
+        for (const hook of hooks) {
+            const result = await this.executeHook(hook, context);
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Execute a single hook definition.
+     *
+     * The hook command is spawned as a child process using `spawn` with
+     * `shell: true` and `detached: true` so that the entire process group
+     * can be killed on timeout. The JSON-serialised `HookContext` is
+     * written to the process's stdin.
+     *
+     * Exit code semantics:
+     *   - 0:     allowed (proceed)
+     *   - 2:     blocked (do not proceed; message taken from stderr then stdout)
+     *   - other: treated as an error; tool call is still allowed but a
+     *            warning should be logged by the caller
+     *
+     * @param hook    - Hook definition to execute
+     * @param context - Context to pass via stdin
+     * @returns Execution result
+     */
+    async executeHook(hook, context) {
+        const timeout = hook.timeout ?? DEFAULT_HOOK_TIMEOUT;
+        const startTime = Date.now();
+        return new Promise(resolve => {
+            let child;
+            let timedOut = false;
+            let resolved = false;
+            // eslint-disable-next-line prefer-const
+            let timer;
+            /**
+             * Resolve exactly once, clearing the timeout timer.
+             */
+            const resolveOnce = (result) => {
+                if (resolved) {
+                    return;
+                }
+                resolved = true;
+                if (timer) {
+                    clearTimeout(timer);
+                }
+                resolve(result);
+            };
+            try {
+                child = spawn(hook.command, {
+                    shell: true,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                    detached: true, // Creates a process group for clean cleanup
+                    env: {
+                        ...process.env,
+                        NIMBUS_HOOK_EVENT: context.tool,
+                        NIMBUS_HOOK_AGENT: context.agent,
+                        NIMBUS_HOOK_SESSION: context.sessionId,
+                    },
+                });
+            }
+            catch (spawnError) {
+                const duration = Date.now() - startTime;
+                resolveOnce({
+                    allowed: true,
+                    message: `Failed to spawn hook command "${hook.command}": ${spawnError instanceof Error ? spawnError.message : String(spawnError)}`,
+                    exitCode: 1,
+                    duration,
+                });
+                return;
+            }
+            // Write context JSON to stdin
+            if (child.stdin) {
+                child.stdin.on('error', () => { });
+                try {
+                    child.stdin.write(JSON.stringify(context));
+                    child.stdin.end();
+                }
+                catch {
+                    // stdin may already be closed -- ignore
+                }
+            }
+            // Collect stdout and stderr
+            let stdout = '';
+            let stderr = '';
+            child.stdout?.on('data', (data) => {
+                stdout += String(data);
+            });
+            child.stderr?.on('data', (data) => {
+                stderr += String(data);
+            });
+            // Timeout handler -- kill the entire process group
+            timer = setTimeout(() => {
+                timedOut = true;
+                try {
+                    // Negative PID kills the entire process group
+                    if (child.pid) {
+                        process.kill(-child.pid, 'SIGKILL');
+                    }
+                }
+                catch {
+                    // Process group may already have exited
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch {
+                        // Already dead
+                    }
+                }
+            }, timeout);
+            child.on('close', (code) => {
+                const duration = Date.now() - startTime;
+                const exitCode = code ?? 1;
+                if (timedOut) {
+                    resolveOnce({
+                        allowed: true,
+                        message: `Hook "${hook.command}" timed out after ${timeout}ms`,
+                        exitCode: 1,
+                        duration,
+                    });
+                    return;
+                }
+                if (exitCode === 0) {
+                    // Allowed
+                    resolveOnce({
+                        allowed: true,
+                        message: stderr.trim() || stdout.trim() || undefined,
+                        exitCode: 0,
+                        duration,
+                    });
+                }
+                else if (exitCode === 2) {
+                    // Blocked
+                    const message = stderr.trim() || stdout.trim() || 'Blocked by hook';
+                    resolveOnce({
+                        allowed: false,
+                        message,
+                        exitCode: 2,
+                        duration,
+                    });
+                }
+                else {
+                    // Error -- allow but surface the message
+                    const message = stderr.trim() || stdout.trim() || `Hook "${hook.command}" exited with code ${exitCode}`;
+                    resolveOnce({
+                        allowed: true,
+                        message,
+                        exitCode,
+                        duration,
+                    });
+                }
+            });
+            child.on('error', (err) => {
+                const duration = Date.now() - startTime;
+                resolveOnce({
+                    allowed: true,
+                    message: `Hook "${hook.command}" error: ${err.message}`,
+                    exitCode: 1,
+                    duration,
+                });
+            });
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Convenience Functions
+// ---------------------------------------------------------------------------
+/**
+ * Run all `PreToolUse` hooks and return an aggregate allow/block decision.
+ *
+ * If **any** hook returns `allowed: false` (exit code 2), the overall result
+ * is blocked and the first blocking message is returned.
+ *
+ * @param engine  - Configured HookEngine instance
+ * @param context - Hook context for the current tool invocation
+ * @returns Object indicating whether the tool call should proceed
+ */
+export async function runPreToolHooks(engine, context) {
+    const results = await engine.executeHooks('PreToolUse', context);
+    for (const result of results) {
+        if (!result.allowed) {
+            return { allowed: false, message: result.message };
+        }
+    }
+    return { allowed: true };
+}
+/**
+ * Run all `PostToolUse` hooks. Results are intentionally discarded since
+ * post-tool hooks are informational/side-effect-only (e.g. auto-formatting,
+ * logging).
+ *
+ * @param engine  - Configured HookEngine instance
+ * @param context - Hook context including `result` from the tool execution
+ */
+export async function runPostToolHooks(engine, context) {
+    await engine.executeHooks('PostToolUse', context);
+}
+/**
+ * Run all `PermissionRequest` hooks. These are fire-and-forget audit hooks
+ * that are invoked when a permission escalation is requested.
+ *
+ * @param engine  - Configured HookEngine instance
+ * @param context - Hook context for the permission request
+ */
+export async function runPermissionHooks(engine, context) {
+    await engine.executeHooks('PermissionRequest', context);
+}

package/dist/src/hooks/index.js

@@ -0,0 +1,2 @@
+export { HookEngine, runPreToolHooks, runPostToolHooks, runPermissionHooks } from './engine';
+export { loadHooksConfig, validateHookDefinition } from './config';

package/dist/src/llm/auth-bridge.js

@@ -0,0 +1,157 @@
+/**
+ * Auth Bridge - API Key Resolution from ~/.nimbus/auth.json
+ *
+ * Provides synchronous API key and base URL resolution for LLM provider constructors.
+ * Uses fs.readFileSync for constructor compatibility (constructors can't be async).
+ * Implements caching to avoid repeated file reads.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+/**
+ * Cache for auth file to avoid repeated reads
+ */
+let authFileCache = null;
+let cacheTimestamp = 0;
+const CACHE_TTL_MS = 5000; // 5 second cache TTL
+/**
+ * Get the path to the auth file
+ */
+function getAuthFilePath() {
+    return path.join(os.homedir(), '.nimbus', 'auth.json');
+}
+/**
+ * Load auth file synchronously with caching
+ */
+function loadAuthFile() {
+    const now = Date.now();
+    // Return cached version if still valid
+    if (authFileCache && now - cacheTimestamp < CACHE_TTL_MS) {
+        return authFileCache;
+    }
+    const authPath = getAuthFilePath();
+    try {
+        if (!fs.existsSync(authPath)) {
+            return null;
+        }
+        const content = fs.readFileSync(authPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        // Update cache
+        authFileCache = parsed;
+        cacheTimestamp = now;
+        return parsed;
+    }
+    catch {
+        // File doesn't exist or is invalid
+        return null;
+    }
+}
+/**
+ * Get API key for a provider
+ *
+ * Resolution order:
+ * 1. auth.json provider credential
+ * 2. Environment variable (fallback)
+ *
+ * @param providerName - The provider name
+ * @returns API key or undefined
+ */
+export function getProviderApiKey(providerName) {
+    // Try auth.json first
+    const authFile = loadAuthFile();
+    const credential = authFile?.providers?.[providerName];
+    if (credential?.apiKey) {
+        return credential.apiKey;
+    }
+    // Fall back to environment variables
+    const envVarMap = {
+        anthropic: process.env.ANTHROPIC_API_KEY,
+        openai: process.env.OPENAI_API_KEY,
+        google: process.env.GOOGLE_API_KEY,
+        openrouter: process.env.OPENROUTER_API_KEY,
+        ollama: undefined,
+        groq: process.env.GROQ_API_KEY,
+        together: process.env.TOGETHER_API_KEY,
+        deepseek: process.env.DEEPSEEK_API_KEY,
+        fireworks: process.env.FIREWORKS_API_KEY,
+        perplexity: process.env.PERPLEXITY_API_KEY,
+    };
+    return envVarMap[providerName];
+}
+/**
+ * Get base URL for a provider
+ *
+ * Resolution order:
+ * 1. auth.json provider credential
+ * 2. Environment variable (fallback)
+ * 3. Default value
+ *
+ * @param providerName - The provider name
+ * @returns Base URL or undefined
+ */
+export function getProviderBaseUrl(providerName) {
+    // Try auth.json first
+    const authFile = loadAuthFile();
+    const credential = authFile?.providers?.[providerName];
+    if (credential?.baseUrl) {
+        return credential.baseUrl;
+    }
+    // Fall back to environment variables for Ollama
+    if (providerName === 'ollama') {
+        return process.env.OLLAMA_BASE_URL;
+    }
+    return undefined;
+}
+/**
+ * Get the configured model for a provider
+ *
+ * @param providerName - The provider name
+ * @returns Model ID or undefined
+ */
+export function getProviderModel(providerName) {
+    const authFile = loadAuthFile();
+    return authFile?.providers?.[providerName]?.model;
+}
+/**
+ * Check if a provider is configured (auth.json or env vars)
+ *
+ * @param providerName - The provider name
+ * @returns true if provider has credentials in auth.json or env vars
+ */
+export function isProviderConfigured(providerName) {
+    // Check auth.json first
+    const authFile = loadAuthFile();
+    const credential = authFile?.providers?.[providerName];
+    if (credential) {
+        // For Ollama, just needs to exist (no API key required)
+        if (providerName === 'ollama') {
+            return true;
+        }
+        // For others, needs an API key in auth.json
+        if (credential.apiKey) {
+            return true;
+        }
+    }
+    // Fall back to environment variables
+    const envVarMap = {
+        anthropic: process.env.ANTHROPIC_API_KEY,
+        openai: process.env.OPENAI_API_KEY,
+        google: process.env.GOOGLE_API_KEY,
+        openrouter: process.env.OPENROUTER_API_KEY,
+        ollama: process.env.OLLAMA_BASE_URL,
+        groq: process.env.GROQ_API_KEY,
+        together: process.env.TOGETHER_API_KEY,
+        deepseek: process.env.DEEPSEEK_API_KEY,
+        fireworks: process.env.FIREWORKS_API_KEY,
+        perplexity: process.env.PERPLEXITY_API_KEY,
+    };
+    return !!envVarMap[providerName];
+}
+/**
+ * Clear the auth file cache
+ * Useful for testing or when auth.json is known to have changed
+ */
+export function clearAuthCache() {
+    authFileCache = null;
+    cacheTimestamp = 0;
+}

package/dist/src/llm/circuit-breaker.js

@@ -0,0 +1,116 @@
+/**
+ * Provider Circuit Breaker
+ *
+ * Prevents cascading failures by tracking consecutive errors per provider.
+ * When a provider fails too many times in a row, its circuit "opens" and
+ * requests are skipped until a cooldown period elapses. After cooldown the
+ * circuit enters HALF_OPEN, allowing a single probe request to determine
+ * whether the provider has recovered.
+ *
+ * States:
+ *   CLOSED    → normal operation (all requests pass through)
+ *   OPEN      → provider is failing; skip until cooldown expires
+ *   HALF_OPEN → cooldown elapsed; allow one probe request
+ */
+const DEFAULT_FAILURE_THRESHOLD = 5;
+const DEFAULT_COOLDOWN_MS = 60_000; // 60 seconds
+export class ProviderCircuitBreaker {
+    circuits = new Map();
+    failureThreshold;
+    cooldownMs;
+    constructor(opts) {
+        this.failureThreshold = opts?.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;
+        this.cooldownMs = opts?.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+    }
+    /**
+     * Check whether a provider is available for requests.
+     * Returns false only when the circuit is OPEN and cooldown hasn't elapsed.
+     */
+    isAvailable(provider) {
+        const circuit = this.circuits.get(provider);
+        if (!circuit) {
+            return true;
+        }
+        if (circuit.state === 'CLOSED') {
+            return true;
+        }
+        if (circuit.state === 'OPEN') {
+            const elapsed = Date.now() - circuit.lastFailure;
+            if (elapsed >= this.cooldownMs) {
+                // Transition to HALF_OPEN: allow a single probe
+                circuit.state = 'HALF_OPEN';
+                return true;
+            }
+            return false;
+        }
+        // HALF_OPEN: allow probe
+        return true;
+    }
+    /**
+     * Record a successful request. Resets the circuit to CLOSED.
+     */
+    recordSuccess(provider) {
+        const circuit = this.circuits.get(provider);
+        if (circuit) {
+            circuit.state = 'CLOSED';
+            circuit.failures = 0;
+        }
+    }
+    /**
+     * Record a failed request. Increments the failure counter and may
+     * open the circuit if the threshold is exceeded.
+     */
+    recordFailure(provider) {
+        let circuit = this.circuits.get(provider);
+        if (!circuit) {
+            circuit = { state: 'CLOSED', failures: 0, lastFailure: 0 };
+            this.circuits.set(provider, circuit);
+        }
+        circuit.failures++;
+        circuit.lastFailure = Date.now();
+        if (circuit.failures >= this.failureThreshold && circuit.state !== 'OPEN') {
+            circuit.state = 'OPEN';
+            // Emit a visible warning when a provider circuit opens
+            if (process.stderr.isTTY) {
+                process.stderr.write(`\x1b[33m  Warning: Provider '${provider}' disabled after ${this.failureThreshold} consecutive failures. Will retry in ${Math.round(this.cooldownMs / 1000)}s.\x1b[0m\n`);
+            }
+        }
+        else if (circuit.failures >= this.failureThreshold) {
+            circuit.state = 'OPEN';
+        }
+    }
+    /**
+     * Get the current state of a provider's circuit.
+     */
+    getState(provider) {
+        return this.circuits.get(provider)?.state ?? 'CLOSED';
+    }
+    /**
+     * Reset a specific provider's circuit (e.g., after manual recovery).
+     */
+    reset(provider) {
+        this.circuits.delete(provider);
+    }
+    /**
+     * Reset all circuits.
+     */
+    resetAll() {
+        this.circuits.clear();
+    }
+    /**
+     * Get the names of all providers whose circuits are currently OPEN.
+     * Useful for surfacing circuit breaker state in the TUI.
+     */
+    getOpenCircuits() {
+        const open = [];
+        for (const [name, circuit] of this.circuits) {
+            if (circuit.state === 'OPEN') {
+                const elapsed = Date.now() - circuit.lastFailure;
+                if (elapsed < this.cooldownMs) {
+                    open.push(name);
+                }
+            }
+        }
+        return open;
+    }
+}