@build-astron-co/nimbus 0.2.0

package/src/cli/openapi-spec.ts

@@ -0,0 +1,356 @@
+/**
+ * OpenAPI 3.1 Specification for `nimbus serve`
+ *
+ * Returns a static OpenAPI document describing every endpoint exposed by
+ * the headless API server. The spec is served at GET /api/openapi.json so
+ * that consumers (Swagger UI, code generators, etc.) can discover the API
+ * programmatically.
+ *
+ * @module cli/openapi-spec
+ */
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build and return the full OpenAPI 3.1 specification object.
+ *
+ * The return type is intentionally `Record<string, unknown>` rather than
+ * a strongly-typed OpenAPI interface, because the spec is serialized to
+ * JSON verbatim and consumed by external tooling, not by TypeScript code.
+ */
+export function getOpenAPISpec(): Record<string, unknown> {
+  return {
+    openapi: '3.1.0',
+    info: {
+      title: 'Nimbus API',
+      version: '0.2.0',
+      description:
+        'Headless HTTP API for the Nimbus AI Cloud Engineering Agent. ' +
+        'Supports SSE streaming for real-time agent responses, session ' +
+        'management, and non-interactive single-prompt execution.',
+      license: {
+        name: 'MIT',
+      },
+    },
+    servers: [{ url: 'http://localhost:4200', description: 'Local development' }],
+    paths: {
+      // -----------------------------------------------------------------
+      // Health
+      // -----------------------------------------------------------------
+      '/api/health': {
+        get: {
+          summary: 'Health check',
+          operationId: 'getHealth',
+          tags: ['System'],
+          responses: {
+            '200': {
+              description: 'Server health status',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      status: { type: 'string', enum: ['ok'] },
+                      version: { type: 'string' },
+                      uptime: { type: 'number', description: 'Seconds since server start' },
+                      db: { type: 'boolean' },
+                      llm: { type: 'boolean' },
+                    },
+                    required: ['status', 'version', 'uptime', 'db', 'llm'],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // Chat (SSE streaming)
+      // -----------------------------------------------------------------
+      '/api/chat': {
+        post: {
+          summary: 'Send a chat message (SSE streaming)',
+          operationId: 'chat',
+          tags: ['Chat'],
+          description:
+            'Sends a user message to the agent and returns an SSE stream. ' +
+            'Events: session, text, tool_start, tool_end, done, error.',
+          requestBody: {
+            required: true,
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  required: ['message'],
+                  properties: {
+                    message: { type: 'string', description: 'User message to send to the agent' },
+                    sessionId: {
+                      type: 'string',
+                      description: 'Session ID to continue. Auto-generated if omitted.',
+                    },
+                    model: {
+                      type: 'string',
+                      description: 'Model alias or fully qualified model name',
+                    },
+                    mode: {
+                      type: 'string',
+                      enum: ['plan', 'build', 'deploy'],
+                      default: 'build',
+                      description: 'Agent mode controlling available tools',
+                    },
+                  },
+                },
+              },
+            },
+          },
+          responses: {
+            '200': {
+              description: 'SSE stream of agent responses',
+              content: {
+                'text/event-stream': {
+                  schema: {
+                    type: 'string',
+                    description: 'Server-Sent Events stream',
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // Run (non-interactive)
+      // -----------------------------------------------------------------
+      '/api/run': {
+        post: {
+          summary: 'Non-interactive single prompt execution',
+          operationId: 'run',
+          tags: ['Chat'],
+          description:
+            'Executes a single prompt through the agent loop and returns ' +
+            'the complete result as JSON. Blocks until the agent finishes.',
+          requestBody: {
+            required: true,
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  required: ['prompt'],
+                  properties: {
+                    prompt: { type: 'string', description: 'Prompt to execute' },
+                    model: { type: 'string', description: 'Model alias or full name' },
+                    mode: {
+                      type: 'string',
+                      enum: ['plan', 'build', 'deploy'],
+                      default: 'build',
+                    },
+                  },
+                },
+              },
+            },
+          },
+          responses: {
+            '200': {
+              description: 'Complete agent response',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      sessionId: { type: 'string' },
+                      response: { type: 'string', description: 'Final assistant message content' },
+                      turns: { type: 'integer', description: 'Number of LLM turns taken' },
+                      usage: { $ref: '#/components/schemas/Usage' },
+                      cost: { type: 'number', description: 'Total estimated cost in USD' },
+                    },
+                    required: ['sessionId', 'response', 'turns', 'usage', 'cost'],
+                  },
+                },
+              },
+            },
+            '500': {
+              description: 'Agent execution error',
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/Error' },
+                },
+              },
+            },
+          },
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // Sessions list
+      // -----------------------------------------------------------------
+      '/api/sessions': {
+        get: {
+          summary: 'List all sessions',
+          operationId: 'listSessions',
+          tags: ['Sessions'],
+          responses: {
+            '200': {
+              description: 'Array of session records',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      sessions: {
+                        type: 'array',
+                        items: { $ref: '#/components/schemas/Session' },
+                      },
+                    },
+                    required: ['sessions'],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // Session by ID (GET + POST)
+      // -----------------------------------------------------------------
+      '/api/session/{id}': {
+        get: {
+          summary: 'Get session details and conversation messages',
+          operationId: 'getSession',
+          tags: ['Sessions'],
+          parameters: [
+            {
+              name: 'id',
+              in: 'path',
+              required: true,
+              schema: { type: 'string' },
+              description: 'Session UUID',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Session details with conversation history',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      session: { $ref: '#/components/schemas/Session' },
+                      messages: {
+                        type: 'array',
+                        items: { type: 'object' },
+                        description: 'LLM message history',
+                      },
+                    },
+                    required: ['session', 'messages'],
+                  },
+                },
+              },
+            },
+            '404': {
+              description: 'Session not found',
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/Error' },
+                },
+              },
+            },
+          },
+        },
+        post: {
+          summary: 'Continue an existing session (SSE streaming)',
+          operationId: 'continueSession',
+          tags: ['Sessions'],
+          parameters: [
+            {
+              name: 'id',
+              in: 'path',
+              required: true,
+              schema: { type: 'string' },
+              description: 'Session UUID',
+            },
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  required: ['message'],
+                  properties: {
+                    message: { type: 'string', description: 'Follow-up message' },
+                    model: { type: 'string', description: 'Model override for this turn' },
+                  },
+                },
+              },
+            },
+          },
+          responses: {
+            '200': {
+              description: 'SSE stream of agent responses',
+              content: { 'text/event-stream': {} },
+            },
+            '404': {
+              description: 'Session not found',
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/Error' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+
+    // -------------------------------------------------------------------
+    // Shared Components
+    // -------------------------------------------------------------------
+    components: {
+      schemas: {
+        Session: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', format: 'uuid' },
+            name: { type: 'string' },
+            status: { type: 'string', enum: ['active', 'suspended', 'completed'] },
+            mode: { type: 'string', enum: ['plan', 'build', 'deploy'] },
+            model: { type: 'string' },
+            tokenCount: { type: 'integer' },
+            costUSD: { type: 'number' },
+            createdAt: { type: 'string', format: 'date-time' },
+            updatedAt: { type: 'string', format: 'date-time' },
+          },
+          required: ['id', 'name', 'status', 'mode'],
+        },
+        Usage: {
+          type: 'object',
+          properties: {
+            promptTokens: { type: 'integer' },
+            completionTokens: { type: 'integer' },
+            totalTokens: { type: 'integer' },
+          },
+          required: ['promptTokens', 'completionTokens', 'totalTokens'],
+        },
+        Error: {
+          type: 'object',
+          properties: {
+            error: { type: 'string', description: 'Human-readable error message' },
+          },
+          required: ['error'],
+        },
+      },
+      securitySchemes: {
+        basicAuth: {
+          type: 'http',
+          scheme: 'basic',
+          description: 'Optional HTTP Basic Auth. Enable with --auth user:pass.',
+        },
+      },
+    },
+  };
+}

package/src/cli/run.ts

@@ -0,0 +1,237 @@
+/**
+ * Non-Interactive CLI Mode
+ *
+ * Runs the Nimbus agent with a prompt from the command line.
+ * Outputs results to stdout and exits.
+ *
+ * Usage:
+ *   nimbus run "deploy the staging environment"
+ *   nimbus run "fix the failing tests" --auto-approve
+ *   echo "analyze this repo" | nimbus run --stdin
+ *   nimbus run "estimate costs" --format json --model anthropic/claude-haiku-4-5
+ */
+
+import { runAgentLoop } from '../agent/loop';
+import { createPermissionState, checkPermission } from '../agent/permissions';
+import { defaultToolRegistry } from '../tools/schemas/types';
+import { standardTools } from '../tools/schemas/standard';
+import { devopsTools } from '../tools/schemas/devops';
+import type { AgentMode } from '../agent/system-prompt';
+import type { LLMRouter } from '../llm/router';
+
+/** Options parsed from command-line arguments */
+export interface RunOptions {
+  /** The prompt to execute */
+  prompt: string;
+  /** Output format */
+  format: 'text' | 'json';
+  /** Skip permission prompts — auto-approve everything */
+  autoApprove: boolean;
+  /** Read prompt from stdin */
+  stdin: boolean;
+  /** Model override */
+  model?: string;
+  /** Agent mode override */
+  mode: AgentMode;
+  /** Maximum turns */
+  maxTurns: number;
+}
+
+/** Result of a non-interactive run */
+export interface RunResult {
+  /** Whether the run completed successfully */
+  success: boolean;
+  /** The final output text */
+  output: string;
+  /** Number of turns taken */
+  turns: number;
+  /** Token usage */
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  /** Cost in USD */
+  cost: number;
+  /** Whether the run was interrupted */
+  interrupted: boolean;
+}
+
+/**
+ * Parse `nimbus run` CLI arguments.
+ */
+export function parseRunArgs(args: string[]): RunOptions {
+  let prompt = '';
+  let format: 'text' | 'json' = 'text';
+  let autoApprove = false;
+  let stdin = false;
+  let model: string | undefined;
+  let mode: AgentMode = 'build';
+  let maxTurns = 50;
+
+  const positional: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    switch (arg) {
+      case '--format':
+        format = (args[++i] ?? 'text') as 'text' | 'json';
+        break;
+      case '--json':
+        format = 'json';
+        break;
+      case '--auto-approve':
+      case '-y':
+        autoApprove = true;
+        break;
+      case '--stdin':
+        stdin = true;
+        break;
+      case '--model':
+        model = args[++i];
+        break;
+      case '--mode':
+        mode = (args[++i] ?? 'build') as AgentMode;
+        break;
+      case '--max-turns':
+        maxTurns = parseInt(args[++i] ?? '50', 10);
+        break;
+      default:
+        if (!arg.startsWith('-')) {
+          positional.push(arg);
+        }
+        break;
+    }
+  }
+
+  prompt = positional.join(' ');
+
+  return { prompt, format, autoApprove, stdin, model, mode, maxTurns };
+}
+
+/**
+ * Execute a non-interactive run.
+ */
+export async function executeRun(router: LLMRouter, options: RunOptions): Promise<RunResult> {
+  // Get prompt from stdin if requested
+  let prompt = options.prompt;
+  if (options.stdin && !prompt) {
+    prompt = await readStdin();
+  }
+
+  if (!prompt) {
+    return {
+      success: false,
+      output: 'Error: No prompt provided. Usage: nimbus run "your prompt"',
+      turns: 0,
+      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      cost: 0,
+      interrupted: false,
+    };
+  }
+
+  // Set up tool registry
+  const registry = defaultToolRegistry;
+  if (registry.size === 0) {
+    // Register all built-in tools
+    for (const tool of [...standardTools, ...devopsTools]) {
+      try {
+        registry.register(tool);
+      } catch {
+        /* skip duplicates */
+      }
+    }
+  }
+
+  // Set up permission state
+  const permissionState = createPermissionState();
+
+  // Collect output
+  const outputParts: string[] = [];
+
+  // Run the agent loop
+  const result = await runAgentLoop(prompt, [], {
+    router,
+    toolRegistry: registry,
+    mode: options.mode,
+    maxTurns: options.maxTurns,
+    model: options.model,
+    cwd: process.cwd(),
+
+    onText: text => {
+      outputParts.push(text);
+      if (options.format === 'text') {
+        process.stdout.write(text);
+      }
+    },
+
+    onToolCallStart: toolCall => {
+      if (options.format === 'text') {
+        process.stderr.write(`\n[Tool: ${toolCall.name}]\n`);
+      }
+    },
+
+    onToolCallEnd: (toolCall, result) => {
+      if (options.format === 'text' && result.isError) {
+        process.stderr.write(`[Error: ${result.error}]\n`);
+      }
+    },
+
+    checkPermission: async (tool, input) => {
+      if (options.autoApprove) {
+        return 'allow';
+      }
+      const decision = checkPermission(tool, input, permissionState);
+      if (decision === 'ask') {
+        // In non-interactive mode without --auto-approve, deny by default
+        return 'deny';
+      }
+      return decision;
+    },
+  });
+
+  const output = outputParts.join('');
+
+  // Format output
+  if (options.format === 'json') {
+    const jsonResult = {
+      success: !result.interrupted,
+      output,
+      turns: result.turns,
+      usage: result.usage,
+      cost: result.totalCost,
+      interrupted: result.interrupted,
+    };
+    console.log(JSON.stringify(jsonResult, null, 2));
+  } else if (options.format === 'text') {
+    // Text was already streamed above
+    console.log(''); // Final newline
+  }
+
+  return {
+    success: !result.interrupted,
+    output,
+    turns: result.turns,
+    usage: result.usage,
+    cost: result.totalCost,
+    interrupted: result.interrupted,
+  };
+}
+
+/**
+ * Read all input from stdin.
+ */
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+
+  return new Promise(resolve => {
+    process.stdin.on('data', chunk => chunks.push(Buffer.from(chunk)));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8').trim()));
+
+    // If stdin is a TTY (no pipe), resolve immediately
+    if (process.stdin.isTTY) {
+      resolve('');
+    }
+  });
+}

package/src/cli/serve-auth.ts

@@ -0,0 +1,80 @@
+/**
+ * HTTP Basic Auth Middleware for `nimbus serve`
+ *
+ * Provides optional HTTP Basic Authentication for the headless API server.
+ * Disabled by default for local development; enabled via `--auth user:pass`.
+ *
+ * Unauthenticated endpoints (always bypassed):
+ *   - GET /api/health
+ *   - GET /api/openapi.json
+ *   - OPTIONS (CORS preflight)
+ *
+ * @module cli/serve-auth
+ */
+
+// ---------------------------------------------------------------------------
+// Public Types
+// ---------------------------------------------------------------------------
+
+/** Credentials for HTTP Basic Auth. */
+export interface ServeAuthOptions {
+  /** Username for Basic Auth. */
+  readonly username: string;
+  /** Password for Basic Auth. */
+  readonly password: string;
+}
+
+// ---------------------------------------------------------------------------
+// Paths that are always public (no auth required)
+// ---------------------------------------------------------------------------
+
+const PUBLIC_PATHS = new Set(['/api/health', '/api/openapi.json']);
+
+// ---------------------------------------------------------------------------
+// Middleware Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an Elysia-compatible `onBeforeHandle` function that enforces
+ * HTTP Basic Authentication on protected endpoints.
+ *
+ * @param options - The username and password to validate against.
+ * @returns A handler that short-circuits with 401 when credentials are
+ *          missing or invalid, or `undefined` to let the request through.
+ */
+export function createAuthMiddleware(
+  options: ServeAuthOptions
+): (ctx: { request: Request; set: any }) => { error: string } | undefined {
+  const expectedToken = btoa(`${options.username}:${options.password}`);
+
+  return ({ request, set }: { request: Request; set: any }) => {
+    const url = new URL(request.url);
+
+    // Skip auth for public endpoints
+    if (PUBLIC_PATHS.has(url.pathname)) {
+      return undefined;
+    }
+
+    // Skip auth for CORS preflight requests
+    if (request.method === 'OPTIONS') {
+      return undefined;
+    }
+
+    const authHeader = request.headers.get('Authorization');
+    if (!authHeader) {
+      set.status = 401;
+      set.headers = { 'WWW-Authenticate': 'Basic realm="Nimbus API"' };
+      return { error: 'Authentication required' };
+    }
+
+    const [scheme, token] = authHeader.split(' ');
+    if (scheme !== 'Basic' || token !== expectedToken) {
+      set.status = 401;
+      set.headers = { 'WWW-Authenticate': 'Basic realm="Nimbus API"' };
+      return { error: 'Invalid credentials' };
+    }
+
+    // Credentials valid -- proceed
+    return undefined;
+  };
+}