@build-astron-co/nimbus 0.2.0

package/src/agent/subagents/general.ts

@@ -0,0 +1,54 @@
+/**
+ * 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, type SubagentConfig } from './base';
+import {
+  readFileTool,
+  globTool,
+  grepTool,
+  listDirTool,
+  bashTool,
+  webfetchTool,
+} from '../../tools/schemas/standard';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const generalConfig: SubagentConfig = {
+  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(): Subagent {
+  return new Subagent(generalConfig);
+}
+
+export { generalConfig };

package/src/agent/subagents/index.ts

@@ -0,0 +1,102 @@
+/**
+ * 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, type SubagentConfig, type SubagentResult } 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';
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+import type { Subagent } from './base';
+import { createExploreSubagent } from './explore';
+import { createInfraSubagent } from './infra';
+import { createSecuritySubagent } from './security';
+import { createCostSubagent } from './cost';
+import { createGeneralSubagent } from './general';
+
+/** Union of all built-in subagent type identifiers. */
+export type SubagentType = 'explore' | 'infra' | 'security' | 'cost' | '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: SubagentType): Subagent {
+  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: never = 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: string): { agent: SubagentType; prompt: string } | null {
+  const match = input.match(/^@(explore|infra|security|cost|general)\s+(.+)$/s);
+  if (!match) {
+    return null;
+  }
+  return { agent: match[1] as SubagentType, prompt: match[2] };
+}

package/src/agent/subagents/infra.ts

@@ -0,0 +1,59 @@
+/**
+ * Infrastructure Analysis Subagent
+ *
+ * Reads IaC files, discovers cloud resources, detects drift, and estimates
+ * costs. Uses a mid-tier model for deeper reasoning on infrastructure
+ * configurations.
+ *
+ * @module agent/subagents/infra
+ */
+
+import { Subagent, type SubagentConfig } from './base';
+import { readFileTool, globTool, grepTool, listDirTool } from '../../tools/schemas/standard';
+import { cloudDiscoverTool, costEstimateTool, driftDetectTool } from '../../tools/schemas/devops';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const infraConfig: SubagentConfig = {
+  name: 'infra',
+  description:
+    'Infrastructure analysis — reads IaC files, discovers cloud resources, detects drift, estimates costs.',
+  systemPrompt: `You are an infrastructure analysis subagent. You specialize in cloud infrastructure.
+
+Your capabilities:
+- Read Terraform, Kubernetes, and Helm configuration files
+- Discover cloud resources (AWS, GCP, Azure)
+- Detect infrastructure drift
+- Estimate costs
+
+Rules:
+- Analyze thoroughly but efficiently
+- Report findings with specific file paths and line numbers
+- Flag any security concerns or misconfigurations
+- Do NOT make changes — analysis only
+- Do NOT spawn further subagents`,
+  tools: [
+    readFileTool,
+    globTool,
+    grepTool,
+    listDirTool,
+    cloudDiscoverTool,
+    costEstimateTool,
+    driftDetectTool,
+  ],
+  model: 'anthropic/claude-sonnet-4-20250514',
+  maxTurns: 20,
+};
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/** Create a new infrastructure analysis subagent instance. */
+export function createInfraSubagent(): Subagent {
+  return new Subagent(infraConfig);
+}
+
+export { infraConfig };

package/src/agent/subagents/security.ts

@@ -0,0 +1,69 @@
+/**
+ * Security Scanning Subagent
+ *
+ * Scans codebases for vulnerabilities, leaked secrets, and
+ * misconfigurations. Reports findings with severity levels and
+ * remediation guidance.
+ *
+ * @module agent/subagents/security
+ */
+
+import { Subagent, type SubagentConfig } from './base';
+import { readFileTool, globTool, grepTool, listDirTool } from '../../tools/schemas/standard';
+
+// ---------------------------------------------------------------------------
+// Security Patterns
+// ---------------------------------------------------------------------------
+
+/**
+ * Common security anti-patterns the subagent is instructed to scan for.
+ * These are embedded in the system prompt so the LLM knows what to look for.
+ */
+const SECURITY_PATTERNS = [
+  'AWS access keys (AKIA...)',
+  'Private keys (.pem, .key)',
+  'Hardcoded passwords',
+  'Open security groups (0.0.0.0/0)',
+  'Unencrypted S3 buckets',
+  'Missing HTTPS/TLS',
+  'SQL injection vectors',
+  'XSS vulnerabilities',
+  'Exposed secrets in env files',
+  'Overly permissive IAM policies',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const securityConfig: SubagentConfig = {
+  name: 'security',
+  description:
+    'Security auditor — scans for vulnerabilities, leaked secrets, and misconfigurations.',
+  systemPrompt: `You are a security auditor subagent. You scan codebases for security issues.
+
+Scan for:
+${SECURITY_PATTERNS.map(p => `- ${p}`).join('\n')}
+
+Rules:
+- Search systematically — use grep for patterns, glob to find config files
+- Report findings with severity levels (CRITICAL, HIGH, MEDIUM, LOW)
+- Include file paths and line numbers for every finding
+- Suggest remediation steps
+- Do NOT modify any files
+- Do NOT spawn further subagents`,
+  tools: [readFileTool, globTool, grepTool, listDirTool],
+  model: 'anthropic/claude-sonnet-4-20250514',
+  maxTurns: 20,
+};
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/** Create a new security scanning subagent instance. */
+export function createSecuritySubagent(): Subagent {
+  return new Subagent(securityConfig);
+}
+
+export { securityConfig };