@build-astron-co/nimbus 0.4.1 → 0.4.3

package/src/agent/permissions.ts

@@ -1,513 +0,0 @@
-/**
- * Permission Engine
- *
- * 4-tier permission system that controls tool execution:
- * - Tier 1 (auto_allow): Reads, validates — no prompt needed
- * - Tier 2 (ask_once): Edits, non-destructive bash — ask once per session
- * - Tier 3 (always_ask): terraform apply, kubectl delete — always prompt
- * - Tier 4 (blocked): rm -rf /, DROP DATABASE — never allow
- *
- * The engine evaluates permissions in the following precedence order:
- *   1. User config overrides (`~/.nimbus/config.yaml`)
- *   2. Tool-specific pattern matching (bash, kubectl, terraform, helm)
- *   3. The tool's declared {@link PermissionTier}
- *
- * Session-level state tracks which tools have been approved via "ask once",
- * so users are not repeatedly prompted for the same non-destructive tool
- * within a single session.
- *
- * @module agent/permissions
- */
-
-import type { ToolDefinition, PermissionTier } from '../tools/schemas/types';
-
-// ---------------------------------------------------------------------------
-// Public Types
-// ---------------------------------------------------------------------------
-
-/** Result of a permission check. */
-export type PermissionDecision = 'allow' | 'ask' | 'block';
-
-/** Full context passed to a permission check. */
-export interface PermissionContext {
-  /** The tool being invoked. */
-  tool: ToolDefinition;
-  /** The parsed input arguments. */
-  input: unknown;
-  /** Session-level state for ask-once tracking. */
-  sessionState: PermissionSessionState;
-}
-
-/** Tracks which tools have been approved in the current session. */
-export interface PermissionSessionState {
-  /** Tools that have been approved for the session (ask-once). */
-  approvedTools: Set<string>;
-  /** Specific tool+action combos that have been approved. */
-  approvedActions: Set<string>;
-}
-
-/**
- * User permission configuration (loaded from `~/.nimbus/config.yaml`).
- *
- * Allows operators to tighten or loosen defaults without modifying code.
- */
-export interface PermissionConfig {
-  /** Override permission tier for specific tools. */
-  toolOverrides?: Record<string, PermissionTier>;
-  /** Bash commands that are auto-allowed (glob patterns). */
-  autoAllowBashPatterns?: string[];
-  /** Bash commands that are always blocked (glob patterns). */
-  blockedBashPatterns?: string[];
-  /** K8s namespaces that require always-ask. */
-  protectedNamespaces?: string[];
-}
-
-// ---------------------------------------------------------------------------
-// Blocked patterns -- these are NEVER allowed (Tier 4)
-// ---------------------------------------------------------------------------
-
-/** @internal */
-const BLOCKED_BASH_PATTERNS: readonly RegExp[] = [
-  /rm\s+(-[a-zA-Z]*)?r[a-zA-Z]*f[a-zA-Z]*\s+\//, // rm -rf /
-  /rm\s+(-[a-zA-Z]*)?f[a-zA-Z]*r[a-zA-Z]*\s+\//, // rm -fr /
-  /rm\s+-[a-zA-Z]*\s+\/\s*$/, // rm -* / (root)
-  /DROP\s+DATABASE/i,
-  /DROP\s+TABLE/i,
-  /TRUNCATE\s+TABLE/i,
-  /FORMAT\s+C:/i,
-  /mkfs\./,
-  /dd\s+if=.*of=\/dev\//,
-  />\s*\/dev\/sd[a-z]/,
-  /chmod\s+-R\s+777\s+\//,
-  /chown\s+-R.*\s+\//,
-  /:(){ :\|:& };:/, // fork bomb
-];
-
-// ---------------------------------------------------------------------------
-// Always-ask patterns (Tier 3)
-// ---------------------------------------------------------------------------
-
-/** @internal */
-const ALWAYS_ASK_BASH_PATTERNS: readonly RegExp[] = [
-  /git\s+push\s+.*--force/,
-  /git\s+push\s+-f/,
-  /git\s+reset\s+--hard/,
-  /git\s+clean\s+-f/,
-  /npm\s+publish/,
-  /docker\s+rm/,
-  /docker\s+rmi/,
-  /docker\s+system\s+prune/,
-  /kubectl\s+delete/,
-  /terraform\s+destroy/,
-  /terraform\s+apply/,
-  /helm\s+uninstall/,
-  /curl.*\|\s*(bash|sh)/, // pipe to shell
-  /wget.*\|\s*(bash|sh)/,
-];
-
-// ---------------------------------------------------------------------------
-// Auto-allow patterns (Tier 1)
-// ---------------------------------------------------------------------------
-
-/** @internal */
-const AUTO_ALLOW_BASH_PATTERNS: readonly RegExp[] = [
-  /^(ls|pwd|echo|cat|head|tail|wc|which|whoami|hostname|date|uname)/,
-  /^(node|bun|deno|python|python3|ruby|go)\s+--version/,
-  /^(npm|yarn|pnpm|bun)\s+(test|lint|format|check|run\s+test)/,
-  /^(npm|yarn|pnpm|bun)\s+install/,
-  /^git\s+(status|log|diff|branch|remote|show|tag)/,
-  /^terraform\s+(validate|fmt|version|providers|show|output)/,
-  /^kubectl\s+(get|describe|logs|version|config)/,
-  /^helm\s+(list|version|status|show|template|lint)/,
-  /^grep\s/,
-  /^find\s/,
-  /^rg\s/,
-];
-
-// ---------------------------------------------------------------------------
-// Protected K8s namespaces
-// ---------------------------------------------------------------------------
-
-/** @internal */
-const DEFAULT_PROTECTED_NAMESPACES: ReadonlySet<string> = new Set([
-  'production',
-  'prod',
-  'kube-system',
-  'kube-public',
-  'istio-system',
-  'cert-manager',
-  'monitoring',
-]);
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-/**
- * Create a fresh permission session state.
- *
- * Call this once when a new interactive session begins. The returned object
- * is mutated in-place by {@link approveForSession} and
- * {@link approveActionForSession}.
- *
- * @returns A new, empty {@link PermissionSessionState}.
- */
-export function createPermissionState(): PermissionSessionState {
-  return {
-    approvedTools: new Set(),
-    approvedActions: new Set(),
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Core Permission Check
-// ---------------------------------------------------------------------------
-
-/**
- * Check whether a tool invocation should be allowed, prompted, or blocked.
- *
- * Evaluation order:
- *   1. If {@link autoApprove} is `true`, immediately return `'allow'`
- *      (used by CI / `--auto-approve` / `--non-interactive` flags).
- *   2. User-level tool overrides from {@link PermissionConfig.toolOverrides}.
- *   3. Tool-specific pattern matching for `bash`, `kubectl`, `terraform`,
- *      and `helm` tools.
- *   4. The tool's declared {@link ToolDefinition.permissionTier}.
- *
- * @param tool         - The tool definition.
- * @param input        - The parsed tool input.
- * @param sessionState - Session-level tracking for ask-once decisions.
- * @param config       - Optional user permission config overrides.
- * @param autoApprove  - When `true`, bypass all tier logic and return `'allow'`
- *                       immediately (H2 — CI auto-approve flag).
- * @returns A {@link PermissionDecision} indicating the action to take.
- */
-export function checkPermission(
-  tool: ToolDefinition,
-  input: unknown,
-  sessionState: PermissionSessionState,
-  config?: PermissionConfig,
-  autoApprove?: boolean  // H2: CI auto-approve flag
-): PermissionDecision {
-  // H2: When running in CI / --auto-approve / --non-interactive mode,
-  // bypass all tier logic and immediately allow the tool call.
-  if (autoApprove) return 'allow';
-
-  // 1. Check user overrides first
-  if (config?.toolOverrides?.[tool.name]) {
-    const overrideTier = config.toolOverrides[tool.name];
-    return tierToDecision(overrideTier, tool, sessionState);
-  }
-
-  // 2. Special handling for bash commands
-  if (tool.name === 'bash' && input && typeof input === 'object' && 'command' in input) {
-    const command = (input as { command: string }).command;
-    return checkBashPermission(command, sessionState, config);
-  }
-
-  // 3. Special handling for kubectl with namespace awareness
-  if (tool.name === 'kubectl' && input && typeof input === 'object') {
-    const kubectlInput = input as { action?: string; namespace?: string };
-    return checkKubectlPermission(kubectlInput, sessionState, config);
-  }
-
-  // 4. Special handling for terraform actions
-  if (tool.name === 'terraform' && input && typeof input === 'object') {
-    const tfInput = input as { action?: string };
-    return checkTerraformPermission(tfInput, sessionState);
-  }
-
-  // 5. Special handling for helm actions
-  if (tool.name === 'helm' && input && typeof input === 'object') {
-    const helmInput = input as { action?: string };
-    return checkHelmPermission(helmInput, sessionState);
-  }
-
-  // 6. Default: use the tool's declared permission tier
-  return tierToDecision(tool.permissionTier, tool, sessionState);
-}
-
-// ---------------------------------------------------------------------------
-// Session Approval
-// ---------------------------------------------------------------------------
-
-/**
- * Record that the user approved a tool for the remainder of the session.
- *
- * After calling this, subsequent {@link checkPermission} calls for the
- * same tool with an `ask_once` tier will return `'allow'` instead of
- * `'ask'`.
- *
- * @param tool         - The tool that was approved.
- * @param sessionState - The session state to mutate.
- */
-export function approveForSession(
-  tool: ToolDefinition,
-  sessionState: PermissionSessionState
-): void {
-  sessionState.approvedTools.add(tool.name);
-}
-
-/**
- * Record that the user approved a specific tool+action combination
- * for the remainder of the session.
- *
- * This is more granular than {@link approveForSession} and is used for
- * tools like `kubectl` and `terraform` where some actions (e.g. `get`)
- * are safe but others (e.g. `apply`) require continued prompting.
- *
- * @param toolName     - The tool name (e.g. `'kubectl'`).
- * @param action       - The action subcommand (e.g. `'apply'`).
- * @param sessionState - The session state to mutate.
- */
-export function approveActionForSession(
-  toolName: string,
-  action: string,
-  sessionState: PermissionSessionState
-): void {
-  sessionState.approvedActions.add(`${toolName}:${action}`);
-}
-
-// ---------------------------------------------------------------------------
-// Internal Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Map a {@link PermissionTier} to a {@link PermissionDecision}, taking
- * session state into account for the `ask_once` tier.
- *
- * @internal
- */
-function tierToDecision(
-  tier: PermissionTier,
-  tool: ToolDefinition,
-  sessionState: PermissionSessionState
-): PermissionDecision {
-  switch (tier) {
-    case 'auto_allow':
-      return 'allow';
-    case 'ask_once':
-      return sessionState.approvedTools.has(tool.name) ? 'allow' : 'ask';
-    case 'always_ask':
-      return 'ask';
-    case 'blocked':
-      return 'block';
-  }
-}
-
-/**
- * Evaluate bash command permission against the three pattern tiers and
- * optional user config.
- *
- * @internal
- */
-function checkBashPermission(
-  command: string,
-  sessionState: PermissionSessionState,
-  config?: PermissionConfig
-): PermissionDecision {
-  const trimmed = command.trim();
-
-  // --- Tier 4: blocked ---
-  for (const pattern of BLOCKED_BASH_PATTERNS) {
-    if (pattern.test(trimmed)) {
-      return 'block';
-    }
-  }
-  if (config?.blockedBashPatterns) {
-    for (const glob of config.blockedBashPatterns) {
-      if (new RegExp(globToRegex(glob)).test(trimmed)) {
-        return 'block';
-      }
-    }
-  }
-
-  // --- Tier 3: always ask ---
-  for (const pattern of ALWAYS_ASK_BASH_PATTERNS) {
-    if (pattern.test(trimmed)) {
-      return 'ask';
-    }
-  }
-
-  // --- Tier 1: auto allow ---
-  for (const pattern of AUTO_ALLOW_BASH_PATTERNS) {
-    if (pattern.test(trimmed)) {
-      return 'allow';
-    }
-  }
-  if (config?.autoAllowBashPatterns) {
-    for (const glob of config.autoAllowBashPatterns) {
-      if (new RegExp(globToRegex(glob)).test(trimmed)) {
-        return 'allow';
-      }
-    }
-  }
-
-  // --- Tier 2 (default for bash): ask once ---
-  return sessionState.approvedTools.has('bash') ? 'allow' : 'ask';
-}
-
-/**
- * Evaluate kubectl permission with namespace awareness.
- *
- * Read-only actions (`get`, `describe`, `logs`) are always allowed.
- * Destructive actions in protected namespaces always prompt.
- * Destructive actions in non-protected namespaces use ask-once semantics.
- *
- * @internal
- */
-function checkKubectlPermission(
-  input: { action?: string; namespace?: string },
-  sessionState: PermissionSessionState,
-  config?: PermissionConfig
-): PermissionDecision {
-  const protectedNs: ReadonlySet<string> = config?.protectedNamespaces
-    ? new Set(config.protectedNamespaces)
-    : DEFAULT_PROTECTED_NAMESPACES;
-
-  // Read-only actions are auto-allowed
-  const readOnlyActions: ReadonlySet<string> = new Set(['get', 'describe', 'logs']);
-  if (input.action && readOnlyActions.has(input.action)) {
-    return 'allow';
-  }
-
-  // Destructive actions in protected namespaces -> always ask
-  const destructiveActions: ReadonlySet<string> = new Set([
-    'delete',
-    'apply',
-    'scale',
-    'rollout',
-    'exec',
-  ]);
-  if (input.action && destructiveActions.has(input.action)) {
-    if (input.namespace && protectedNs.has(input.namespace)) {
-      return 'ask'; // always ask for protected namespaces
-    }
-    // Non-protected namespace: ask once per action
-    const key = `kubectl:${input.action}`;
-    return sessionState.approvedActions.has(key) ? 'allow' : 'ask';
-  }
-
-  // Unknown kubectl action -> ask
-  return 'ask';
-}
-
-/**
- * Evaluate terraform permission based on the subcommand.
- *
- * Read-only actions (`validate`, `fmt`, `show`, etc.) are auto-allowed.
- * Planning actions (`init`, `plan`, `state`) use ask-once semantics.
- * Mutating actions (`apply`, `destroy`, `import`) always prompt.
- *
- * @internal
- */
-function checkTerraformPermission(
-  input: { action?: string },
-  sessionState: PermissionSessionState
-): PermissionDecision {
-  const readOnlyActions: ReadonlySet<string> = new Set([
-    'validate',
-    'fmt',
-    'show',
-    'output',
-    'providers',
-    'version',
-  ]);
-  if (input.action && readOnlyActions.has(input.action)) {
-    return 'allow';
-  }
-
-  const planLike: ReadonlySet<string> = new Set(['init', 'plan', 'state']);
-  if (input.action && planLike.has(input.action)) {
-    const key = `terraform:${input.action}`;
-    return sessionState.approvedActions.has(key) ? 'allow' : 'ask';
-  }
-
-  // apply, destroy, import -> always ask
-  return 'ask';
-}
-
-/**
- * Evaluate helm permission based on the subcommand.
- *
- * Read-only actions (`list`, `status`, `show`, etc.) are auto-allowed.
- * Mutating actions (`install`, `upgrade`, `uninstall`, `rollback`)
- * always prompt.
- *
- * @internal
- */
-function checkHelmPermission(
-  input: { action?: string },
-  _sessionState: PermissionSessionState
-): PermissionDecision {
-  const readOnlyActions: ReadonlySet<string> = new Set([
-    'list',
-    'status',
-    'show',
-    'template',
-    'lint',
-    'version',
-  ]);
-  if (input.action && readOnlyActions.has(input.action)) {
-    return 'allow';
-  }
-
-  // install, upgrade, uninstall, rollback -> always ask
-  return 'ask';
-}
-
-// ---------------------------------------------------------------------------
-// G14: Forbidden rules enforcement
-// ---------------------------------------------------------------------------
-
-/**
- * Check whether a tool invocation matches any forbidden rule from NIMBUS.md.
- *
- * Rules are plain-text descriptions. We do a case-insensitive substring match
- * against the tool name and serialized input. If any rule matches, return
- * `'block'`; otherwise return `null` (no opinion).
- *
- * @param toolName     - The tool being invoked.
- * @param input        - The parsed tool input.
- * @param forbiddenRules - Array of rule strings extracted from `## Forbidden`.
- * @returns `'block'` if forbidden, `null` otherwise.
- */
-export function checkForbiddenPatterns(
-  toolName: string,
-  input: unknown,
-  forbiddenRules: readonly string[]
-): 'block' | null {
-  if (forbiddenRules.length === 0) return null;
-
-  const inputStr = JSON.stringify(input ?? {}).toLowerCase();
-  const toolLower = toolName.toLowerCase();
-
-  for (const rule of forbiddenRules) {
-    const ruleLower = rule.toLowerCase();
-    // Check if the rule mentions this tool or its input contains the rule keywords
-    const keywords = ruleLower.split(/\s+/).filter(w => w.length > 3);
-    const matchCount = keywords.filter(kw => toolLower.includes(kw) || inputStr.includes(kw)).length;
-    if (matchCount >= Math.min(2, keywords.length)) {
-      return 'block';
-    }
-  }
-  return null;
-}
-
-/**
- * Convert a simple glob pattern to a regex string.
- *
- * Supports `*` (any sequence of characters) and `?` (single character).
- * All other regex-significant characters are escaped.
- *
- * @param glob - The glob pattern to convert.
- * @returns A regex source string (without delimiters).
- *
- * @internal
- */
-function globToRegex(glob: string): string {
-  return glob
-    .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape regex special chars
-    .replace(/\*/g, '.*') // * -> .*
-    .replace(/\?/g, '.'); // ? -> .
-}

package/src/agent/subagents/base.ts

@@ -1,116 +0,0 @@
-/**
- * Base Subagent
- *
- * Provides the foundation for specialized subagents. Each subagent runs
- * with its own isolated conversation, restricted tool set, and permissions.
- * Subagents cannot spawn further subagents (no nesting).
- *
- * @module agent/subagents/base
- */
-
-import type { LLMRouter } from '../../llm/router';
-import { ToolRegistry, type ToolDefinition } from '../../tools/schemas/types';
-import { runAgentLoop, type AgentLoopResult } from '../loop';
-
-// ---------------------------------------------------------------------------
-// Public Types
-// ---------------------------------------------------------------------------
-
-/** Configuration for a specialized subagent. */
-export interface SubagentConfig {
-  /** Unique name for this subagent type. */
-  name: string;
-
-  /** Description shown to the parent agent when selecting a subagent. */
-  description: string;
-
-  /** System prompt specific to this subagent. */
-  systemPrompt: string;
-
-  /** Tools available to this subagent. */
-  tools: ToolDefinition[];
-
-  /** Model to use (e.g. `'anthropic/claude-haiku-4-5'` for fast/cheap). */
-  model: string;
-
-  /** Maximum turns for subagent execution. */
-  maxTurns: number;
-}
-
-/** Result returned after a subagent completes execution. */
-export interface SubagentResult {
-  /** The final text output from the subagent. */
-  output: string;
-
-  /** Number of LLM turns taken. */
-  turns: number;
-
-  /** Total tokens used across all turns. */
-  totalTokens: number;
-
-  /** Whether the subagent was interrupted before completion. */
-  interrupted: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Subagent Class
-// ---------------------------------------------------------------------------
-
-/**
- * Base class for all Nimbus subagents.
- *
- * A subagent is a lightweight, scoped agent that runs within the parent
- * agent's process. It has its own conversation history, tool registry,
- * and system prompt, but shares the parent's LLM router.
- *
- * Subagents are intentionally prevented from spawning further subagents
- * by filtering out the `task` tool from their registry.
- */
-export class Subagent {
-  readonly config: SubagentConfig;
-
-  constructor(config: SubagentConfig) {
-    this.config = config;
-  }
-
-  /**
-   * Run the subagent with a given prompt.
-   *
-   * Creates an isolated tool registry (excluding the `task` tool to
-   * prevent nesting), then delegates to {@link runAgentLoop} with the
-   * subagent's own system prompt, model, and turn limit.
-   *
-   * @param prompt - The task description for the subagent.
-   * @param router - The shared LLM router instance.
-   * @returns The subagent's final output, turn count, token usage, and
-   *   whether it was interrupted.
-   */
-  async run(prompt: string, router: LLMRouter): Promise<SubagentResult> {
-    // Create isolated tool registry (no task tool -- prevent nesting)
-    const registry = new ToolRegistry();
-    for (const tool of this.config.tools) {
-      if (tool.name !== 'task') {
-        registry.register(tool);
-      }
-    }
-
-    const result: AgentLoopResult = await runAgentLoop(prompt, [], {
-      router,
-      toolRegistry: registry,
-      mode: 'plan', // Subagents default to plan mode (read-only unless configured otherwise)
-      maxTurns: this.config.maxTurns,
-      model: this.config.model,
-      nimbusInstructions: this.config.systemPrompt,
-    });
-
-    // Extract the final assistant message
-    const lastAssistant = [...result.messages].reverse().find(m => m.role === 'assistant');
-
-    return {
-      output: (lastAssistant?.content as string) ?? '(no output)',
-      turns: result.turns,
-      totalTokens: result.usage.totalTokens,
-      interrupted: result.interrupted,
-    };
-  }
-}

package/src/agent/subagents/cost.ts

@@ -1,51 +0,0 @@
-/**
- * Cost Analysis Subagent
- *
- * Analyzes infrastructure costs and identifies optimization opportunities.
- * Uses a small/fast model since cost analysis is largely pattern-matching
- * against resource configurations and pricing data.
- *
- * @module agent/subagents/cost
- */
-
-import { Subagent, type SubagentConfig } from './base';
-import { readFileTool, globTool, grepTool, listDirTool } from '../../tools/schemas/standard';
-import { costEstimateTool, cloudDiscoverTool } from '../../tools/schemas/devops';
-
-// ---------------------------------------------------------------------------
-// Configuration
-// ---------------------------------------------------------------------------
-
-const costConfig: SubagentConfig = {
-  name: 'cost',
-  description: 'Cost optimization specialist — analyzes infrastructure costs and suggests savings.',
-  systemPrompt: `You are a cost optimization subagent. You analyze cloud infrastructure costs.
-
-Your job:
-- Read Terraform/K8s configs to understand resource sizing
-- Use cost_estimate to calculate projected costs
-- Use cloud_discover to find running resources
-- Identify cost optimization opportunities
-- Compare pricing across regions/instance types
-
-Rules:
-- Be specific with cost numbers (monthly, annual)
-- Suggest concrete optimization actions
-- Flag oversized or underutilized resources
-- Do NOT modify any files
-- Do NOT spawn further subagents`,
-  tools: [readFileTool, globTool, grepTool, listDirTool, costEstimateTool, cloudDiscoverTool],
-  model: 'anthropic/claude-haiku-4-5',
-  maxTurns: 15,
-};
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-/** Create a new cost analysis subagent instance. */
-export function createCostSubagent(): Subagent {
-  return new Subagent(costConfig);
-}
-
-export { costConfig };