@build-astron-co/nimbus 0.2.0 → 0.4.0

package/dist/src/agent/permissions.js

@@ -0,0 +1,396 @@
+/**
+ * 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
+ */
+// ---------------------------------------------------------------------------
+// Blocked patterns -- these are NEVER allowed (Tier 4)
+// ---------------------------------------------------------------------------
+/** @internal */
+const BLOCKED_BASH_PATTERNS = [
+    /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 = [
+    /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 = [
+    /^(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 = 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() {
+    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, input, sessionState, config, autoApprove // H2: CI auto-approve flag
+) {
+    // 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.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;
+        return checkKubectlPermission(kubectlInput, sessionState, config);
+    }
+    // 4. Special handling for terraform actions
+    if (tool.name === 'terraform' && input && typeof input === 'object') {
+        const tfInput = input;
+        return checkTerraformPermission(tfInput, sessionState);
+    }
+    // 5. Special handling for helm actions
+    if (tool.name === 'helm' && input && typeof input === 'object') {
+        const helmInput = input;
+        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, sessionState) {
+    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, action, sessionState) {
+    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, tool, sessionState) {
+    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, sessionState, config) {
+    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, sessionState, config) {
+    const protectedNs = config?.protectedNamespaces
+        ? new Set(config.protectedNamespaces)
+        : DEFAULT_PROTECTED_NAMESPACES;
+    // Read-only actions are auto-allowed
+    const readOnlyActions = new Set(['get', 'describe', 'logs']);
+    if (input.action && readOnlyActions.has(input.action)) {
+        return 'allow';
+    }
+    // Destructive actions in protected namespaces -> always ask
+    const destructiveActions = 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, sessionState) {
+    const readOnlyActions = new Set([
+        'validate',
+        'fmt',
+        'show',
+        'output',
+        'providers',
+        'version',
+    ]);
+    if (input.action && readOnlyActions.has(input.action)) {
+        return 'allow';
+    }
+    const planLike = 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, _sessionState) {
+    const readOnlyActions = 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, input, forbiddenRules) {
+    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) {
+    return glob
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape regex special chars
+        .replace(/\*/g, '.*') // * -> .*
+        .replace(/\?/g, '.'); // ? -> .
+}

package/dist/src/agent/subagents/base.js

@@ -0,0 +1,67 @@
+/**
+ * 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 { ToolRegistry } from '../../tools/schemas/types';
+import { runAgentLoop } from '../loop';
+// ---------------------------------------------------------------------------
+// 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 {
+    config;
+    constructor(config) {
+        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, router) {
+        // 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 = 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 ?? '(no output)',
+            turns: result.turns,
+            totalTokens: result.usage.totalTokens,
+            interrupted: result.interrupted,
+        };
+    }
+}

package/dist/src/agent/subagents/cost.js

@@ -0,0 +1,45 @@
+/**
+ * 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 } from './base';
+import { readFileTool, globTool, grepTool, listDirTool } from '../../tools/schemas/standard';
+import { costEstimateTool, cloudDiscoverTool } from '../../tools/schemas/devops';
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const costConfig = {
+    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() {
+    return new Subagent(costConfig);
+}
+export { costConfig };

package/dist/src/agent/subagents/explore.js

@@ -0,0 +1,36 @@
+/**
+ * Explore Subagent
+ *
+ * Fast codebase exploration and search. Uses read-only tools and a
+ * small/fast model for efficient file discovery and content inspection.
+ *
+ * @module agent/subagents/explore
+ */
+import { Subagent } from './base';
+import { readFileTool, globTool, grepTool, listDirTool } from '../../tools/schemas/standard';
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const exploreConfig = {
+    name: 'explore',
+    description: 'Fast codebase exploration and search. Read-only, uses a small/fast model.',
+    systemPrompt: `You are a codebase explorer subagent. Your job is to search through code, find files, and report findings.
+
+Rules:
+- Search efficiently — use glob to find files, grep to search content, read_file for details
+- Report your findings clearly and concisely
+- Do NOT modify any files
+- Do NOT spawn further subagents
+- Focus on the specific question asked`,
+    tools: [readFileTool, globTool, grepTool, listDirTool],
+    model: 'anthropic/claude-haiku-4-5',
+    maxTurns: 15,
+};
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/** Create a new explore subagent instance. */
+export function createExploreSubagent() {
+    return new Subagent(exploreConfig);
+}
+export { exploreConfig };

package/dist/src/agent/subagents/general.js

@@ -0,0 +1,41 @@
+/**
+ * General-Purpose Research Subagent
+ *
+ * Broad-access subagent with code search, shell commands, and web fetch
+ * capabilities. Suitable for open-ended research tasks that do not fit
+ * neatly into a specialized category.
+ *
+ * @module agent/subagents/general
+ */
+import { Subagent } from './base';
+import { readFileTool, globTool, grepTool, listDirTool, bashTool, webfetchTool, } from '../../tools/schemas/standard';
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const generalConfig = {
+    name: 'general',
+    description: 'General-purpose research agent with broad tool access.',
+    systemPrompt: `You are a general-purpose research subagent. You can search code, run commands, and fetch web content.
+
+Your job:
+- Answer questions by searching the codebase and running commands
+- Research topics by fetching web content
+- Provide thorough, well-documented answers
+
+Rules:
+- Be thorough but efficient
+- Cite sources (file paths, URLs) for all findings
+- Run non-destructive commands only
+- Do NOT spawn further subagents`,
+    tools: [readFileTool, globTool, grepTool, listDirTool, bashTool, webfetchTool],
+    model: 'anthropic/claude-sonnet-4-20250514',
+    maxTurns: 20,
+};
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/** Create a new general-purpose research subagent instance. */
+export function createGeneralSubagent() {
+    return new Subagent(generalConfig);
+}
+export { generalConfig };

package/dist/src/agent/subagents/index.js

@@ -0,0 +1,88 @@
+/**
+ * Subagent System -- Barrel Re-exports
+ *
+ * Central entry point for the Nimbus subagent system. Provides factory
+ * functions for each specialized subagent, a type-safe factory by name,
+ * and a parser for the `@agent` mention syntax.
+ *
+ * @module agent/subagents
+ */
+// ---------------------------------------------------------------------------
+// Named Re-exports
+// ---------------------------------------------------------------------------
+export { Subagent } from './base';
+export { createExploreSubagent, exploreConfig } from './explore';
+export { createInfraSubagent, infraConfig } from './infra';
+export { createSecuritySubagent, securityConfig } from './security';
+export { createCostSubagent, costConfig } from './cost';
+export { createGeneralSubagent, generalConfig } from './general';
+import { createExploreSubagent } from './explore';
+import { createInfraSubagent } from './infra';
+import { createSecuritySubagent } from './security';
+import { createCostSubagent } from './cost';
+import { createGeneralSubagent } from './general';
+/**
+ * Create a subagent by type name.
+ *
+ * Uses an exhaustive switch so that adding a new {@link SubagentType}
+ * variant without a corresponding case produces a compile-time error.
+ *
+ * @param type - The subagent specialization to instantiate.
+ * @returns A configured {@link Subagent} instance.
+ *
+ * @example
+ * ```ts
+ * const agent = createSubagent('explore');
+ * const result = await agent.run('Find all TODO comments', router);
+ * ```
+ */
+export function createSubagent(type) {
+    switch (type) {
+        case 'explore':
+            return createExploreSubagent();
+        case 'infra':
+            return createInfraSubagent();
+        case 'security':
+            return createSecuritySubagent();
+        case 'cost':
+            return createCostSubagent();
+        case 'general':
+            return createGeneralSubagent();
+        default: {
+            const _exhaustive = type;
+            throw new Error(`Unknown subagent type: ${_exhaustive}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// @agent Mention Parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse `@agent` syntax from user input.
+ *
+ * Returns an object with the matched agent type and the remaining prompt
+ * if the input starts with a recognized `@<agent>` prefix, or `null` if
+ * the input does not match the pattern.
+ *
+ * @param input - Raw user input string.
+ * @returns Parsed agent mention, or `null` if no match.
+ *
+ * @example
+ * ```ts
+ * parseAgentMention('@explore find all TODO comments');
+ * // => { agent: 'explore', prompt: 'find all TODO comments' }
+ *
+ * parseAgentMention('@infra check EKS autoscaling');
+ * // => { agent: 'infra', prompt: 'check EKS autoscaling' }
+ *
+ * parseAgentMention('normal message');
+ * // => null
+ * ```
+ */
+export function parseAgentMention(input) {
+    const match = input.match(/^@(explore|infra|security|cost|general)\s+(.+)$/s);
+    if (!match) {
+        return null;
+    }
+    return { agent: match[1], prompt: match[2] };
+}