@build-astron-co/nimbus 0.2.0 → 0.4.0

package/dist/src/tools/schemas/types.js

@@ -0,0 +1,409 @@
+/**
+ * Nimbus Agentic Tool-Use Type System
+ *
+ * Core type definitions for the agentic tool-use system. Every tool that
+ * Nimbus can invoke -- whether a built-in operation, a DevOps command, or
+ * an MCP server tool -- is described by a {@link ToolDefinition} and
+ * registered in the {@link ToolRegistry}.
+ *
+ * The permission model follows a four-tier escalation ladder
+ * ({@link PermissionTier}) that controls whether a tool invocation requires
+ * user confirmation, and the three-category taxonomy ({@link ToolCategory})
+ * allows consumers to filter tools by surface area.
+ *
+ * Provider-specific serialization helpers ({@link AnthropicTool},
+ * {@link OpenAITool}, {@link GoogleTool}) let the engine convert a single
+ * {@link ToolDefinition} into whatever shape each LLM API expects.
+ *
+ * @module tools/schemas/types
+ */
+/**
+ * Ordered list of all permission tiers from least restrictive to most
+ * restrictive. Useful for comparison and escalation logic.
+ */
+export const PERMISSION_TIER_ORDER = [
+    'auto_allow',
+    'ask_once',
+    'always_ask',
+    'blocked',
+];
+/**
+ * Return the numeric severity index of a {@link PermissionTier}.
+ * Lower values are less restrictive.
+ *
+ * @param tier - The permission tier to evaluate.
+ * @returns An integer from 0 (`auto_allow`) to 3 (`blocked`).
+ */
+export function permissionTierIndex(tier) {
+    return PERMISSION_TIER_ORDER.indexOf(tier);
+}
+// ---------------------------------------------------------------------------
+// JSON Schema Conversion Utility
+// ---------------------------------------------------------------------------
+/**
+ * Convert a Zod schema into a plain JSON Schema object suitable for
+ * provider APIs.
+ *
+ * This is a lightweight converter that handles the most common Zod types
+ * used in tool definitions (objects, strings, numbers, booleans, arrays,
+ * enums, optionals, and defaults). For deeply nested or exotic schemas
+ * consider using a full-featured library like `zod-to-json-schema`.
+ *
+ * @param schema - Any Zod schema.
+ * @returns A JSON Schema object.
+ */
+export function zodToJsonSchema(schema) {
+    return convertZodNode(schema);
+}
+/**
+ * Internal recursive walker that translates individual Zod nodes into
+ * their JSON Schema equivalents.
+ *
+ * Because this function must work with Zod v3 _and_ v4 (whose generic
+ * constraints differ significantly), the runtime casts use `any` to
+ * bypass version-specific type parameter requirements. This is safe
+ * because every branch is guarded by a runtime type-tag check first.
+ */
+function convertZodNode(schema) {
+    // Cast once to `any` for internal introspection. Every access below is
+    // guarded by a runtime type-tag check, so this is safe.
+    const s = schema;
+    // Unwrap ZodOptional / ZodNullable / ZodDefault to reach the inner type.
+    if (isZodOptional(schema)) {
+        return convertZodNode(s.unwrap());
+    }
+    if (isZodDefault(schema)) {
+        const inner = convertZodNode(s.removeDefault());
+        // Zod v3: _def.defaultValue is a function. Zod v4: it is a plain value.
+        const raw = s._def?.defaultValue ?? s._zod?.def?.defaultValue;
+        const defaultValue = typeof raw === 'function' ? raw() : raw;
+        return { ...inner, default: defaultValue };
+    }
+    if (isZodNullable(schema)) {
+        const inner = convertZodNode(s.unwrap());
+        return { ...inner, nullable: true };
+    }
+    // ZodObject
+    if (isZodObject(schema)) {
+        const shape = s.shape;
+        const properties = {};
+        const required = [];
+        for (const [key, value] of Object.entries(shape)) {
+            const fieldSchema = value;
+            properties[key] = convertZodNode(fieldSchema);
+            // Attach description from .describe() if present.
+            // Zod v3: _def.description.  Zod v4: _zod.def.description.
+            const fieldAny = fieldSchema;
+            const desc = fieldAny._def?.description ?? fieldAny._zod?.def?.description;
+            if (desc) {
+                properties[key].description = desc;
+            }
+            // A field is required unless it is optional/default-wrapped.
+            if (!isZodOptional(fieldSchema) && !isZodDefault(fieldSchema)) {
+                required.push(key);
+            }
+        }
+        const result = { type: 'object', properties };
+        if (required.length > 0) {
+            result.required = required;
+        }
+        const objDesc = s._def?.description ?? s._zod?.def?.description;
+        if (objDesc) {
+            result.description = objDesc;
+        }
+        return result;
+    }
+    // ZodString
+    if (isZodString(schema)) {
+        return { type: 'string' };
+    }
+    // ZodNumber
+    if (isZodNumber(schema)) {
+        return { type: 'number' };
+    }
+    // ZodBoolean
+    if (isZodBoolean(schema)) {
+        return { type: 'boolean' };
+    }
+    // ZodEnum
+    if (isZodEnum(schema)) {
+        // `.options` is available in both Zod v3 and v4.
+        const values = s.options;
+        return { type: 'string', enum: values };
+    }
+    // ZodArray
+    if (isZodArray(schema)) {
+        const itemSchema = s.element;
+        return { type: 'array', items: convertZodNode(itemSchema) };
+    }
+    // ZodLiteral
+    if (isZodLiteral(schema)) {
+        const value = s.value;
+        return { type: typeof value, const: value };
+    }
+    // ZodUnion (simple enum-like unions of literals)
+    if (isZodUnion(schema)) {
+        const options = s.options;
+        return { type: 'object', anyOf: options.map(o => convertZodNode(o)) };
+    }
+    // ZodRecord
+    if (isZodRecord(schema)) {
+        // Zod v3: `.valueSchema`.  Zod v4: `._zod.def.valueType`.
+        const valueSchema = s.valueSchema ?? s._zod?.def?.valueType;
+        if (valueSchema) {
+            return { type: 'object', additionalProperties: convertZodNode(valueSchema) };
+        }
+        return { type: 'object' };
+    }
+    // Fallback -- treat as opaque object
+    return { type: 'object' };
+}
+// ---------------------------------------------------------------------------
+// Zod type-tag guards (work across Zod v3 and v4)
+// ---------------------------------------------------------------------------
+/**
+ * Extract the internal type discriminator from a Zod schema.
+ *
+ * - Zod v3 stores it at `_def.typeName` (e.g. `'ZodString'`).
+ * - Zod v4 stores it at `_zod.def.type` (e.g. `'string'`).
+ *
+ * We normalize both to the v3-style `'ZodXxx'` name so the guards below
+ * can use a single comparison.
+ */
+function zodTypeName(schema) {
+    const s = schema;
+    // Zod v3 path
+    const v3Name = s._def?.typeName;
+    if (v3Name) {
+        return v3Name;
+    }
+    // Zod v4 path: `_zod.def.type` is a lowercase short name like 'string'.
+    const v4Type = s._zod?.def?.type;
+    if (v4Type) {
+        // Capitalize to match Zod v3 convention: 'string' -> 'ZodString'.
+        return `Zod${v4Type.charAt(0).toUpperCase()}${v4Type.slice(1)}`;
+    }
+    return '';
+}
+function isZodObject(s) {
+    return zodTypeName(s) === 'ZodObject';
+}
+function isZodString(s) {
+    return zodTypeName(s) === 'ZodString';
+}
+function isZodNumber(s) {
+    return zodTypeName(s) === 'ZodNumber';
+}
+function isZodBoolean(s) {
+    return zodTypeName(s) === 'ZodBoolean';
+}
+function isZodEnum(s) {
+    return zodTypeName(s) === 'ZodEnum';
+}
+function isZodArray(s) {
+    return zodTypeName(s) === 'ZodArray';
+}
+function isZodOptional(s) {
+    return zodTypeName(s) === 'ZodOptional';
+}
+function isZodDefault(s) {
+    return zodTypeName(s) === 'ZodDefault';
+}
+function isZodNullable(s) {
+    return zodTypeName(s) === 'ZodNullable';
+}
+function isZodLiteral(s) {
+    return zodTypeName(s) === 'ZodLiteral';
+}
+function isZodUnion(s) {
+    return zodTypeName(s) === 'ZodUnion';
+}
+function isZodRecord(s) {
+    return zodTypeName(s) === 'ZodRecord';
+}
+// ---------------------------------------------------------------------------
+// Provider Format Converters
+// ---------------------------------------------------------------------------
+/**
+ * Convert a {@link ToolDefinition} into an {@link AnthropicTool}.
+ *
+ * @param tool - The tool definition to convert.
+ * @returns The tool in Anthropic Messages API format.
+ */
+export function toAnthropicTool(tool) {
+    const jsonSchema = zodToJsonSchema(tool.inputSchema);
+    return {
+        name: tool.name,
+        description: tool.description,
+        input_schema: {
+            ...jsonSchema,
+            type: 'object',
+        },
+    };
+}
+/**
+ * Convert a {@link ToolDefinition} into an {@link OpenAITool}.
+ *
+ * @param tool - The tool definition to convert.
+ * @returns The tool in OpenAI function-calling format.
+ */
+export function toOpenAITool(tool) {
+    return {
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: zodToJsonSchema(tool.inputSchema),
+        },
+    };
+}
+/**
+ * Convert one or more {@link ToolDefinition}s into a single
+ * {@link GoogleTool} object (Google expects all declarations inside a
+ * single array).
+ *
+ * @param tools - The tool definitions to convert.
+ * @returns The tool in Google Generative AI format.
+ */
+export function toGoogleTool(tools) {
+    return {
+        functionDeclarations: tools.map(tool => {
+            const jsonSchema = zodToJsonSchema(tool.inputSchema);
+            return {
+                name: tool.name,
+                description: tool.description,
+                parameters: {
+                    ...jsonSchema,
+                    type: 'OBJECT',
+                },
+            };
+        }),
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool Registry
+// ---------------------------------------------------------------------------
+/**
+ * Central, mutable registry that stores all available tool definitions.
+ *
+ * The registry is intentionally a plain class (not a singleton) so that
+ * tests can instantiate isolated instances. Production code should use
+ * the shared {@link defaultToolRegistry} export.
+ *
+ * @example
+ * ```ts
+ * const registry = new ToolRegistry();
+ * registry.register(readFileTool);
+ * registry.register(terraformApplyTool);
+ *
+ * const devopsTools = registry.getByCategory('devops');
+ * const anthropicPayload = registry.getAll().map(toAnthropicTool);
+ * ```
+ */
+export class ToolRegistry {
+    /** Internal map keyed by tool name. */
+    tools = new Map();
+    /**
+     * Register a tool definition. Throws if a tool with the same name is
+     * already registered -- call {@link get} first if you need upsert
+     * semantics.
+     *
+     * @param tool - The tool definition to register.
+     * @throws {Error} If a tool with the same {@link ToolDefinition.name}
+     *   already exists.
+     */
+    register(tool) {
+        if (this.tools.has(tool.name)) {
+            throw new Error(`ToolRegistry: tool '${tool.name}' is already registered. ` +
+                `Unregister it first or use a different name.`);
+        }
+        this.tools.set(tool.name, tool);
+    }
+    /**
+     * Retrieve a tool definition by name.
+     *
+     * @param name - The unique tool name.
+     * @returns The tool definition, or `undefined` if not found.
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Return every registered tool definition, in insertion order.
+     */
+    getAll() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * Return all tools that belong to the given {@link ToolCategory}.
+     *
+     * @param category - The category to filter by.
+     * @returns An array of matching tool definitions (may be empty).
+     */
+    getByCategory(category) {
+        return this.getAll().filter(t => t.category === category);
+    }
+    /**
+     * Return all tools that belong to the given {@link PermissionTier}.
+     *
+     * @param tier - The permission tier to filter by.
+     * @returns An array of matching tool definitions (may be empty).
+     */
+    getByPermissionTier(tier) {
+        return this.getAll().filter(t => t.permissionTier === tier);
+    }
+    /**
+     * Return the names of all registered tools, in insertion order.
+     */
+    getNames() {
+        return Array.from(this.tools.keys());
+    }
+    /**
+     * Remove a previously registered tool by name.
+     *
+     * @param name - The tool name to unregister.
+     * @returns `true` if the tool was found and removed, `false` otherwise.
+     */
+    unregister(name) {
+        return this.tools.delete(name);
+    }
+    /**
+     * Remove all registered tools. Primarily useful in tests.
+     */
+    clear() {
+        this.tools.clear();
+    }
+    /**
+     * The number of currently registered tools.
+     */
+    get size() {
+        return this.tools.size;
+    }
+    /**
+     * Convert all registered tools to the Anthropic Messages API format.
+     */
+    toAnthropicTools() {
+        return this.getAll().map(toAnthropicTool);
+    }
+    /**
+     * Convert all registered tools to the OpenAI function-calling format.
+     */
+    toOpenAITools() {
+        return this.getAll().map(toOpenAITool);
+    }
+    /**
+     * Convert all registered tools to a single Google Generative AI tool
+     * object.
+     */
+    toGoogleTool() {
+        return toGoogleTool(this.getAll());
+    }
+}
+// ---------------------------------------------------------------------------
+// Shared Default Instance
+// ---------------------------------------------------------------------------
+/**
+ * Application-wide tool registry instance. Import this wherever you need
+ * to register or look up tools at runtime.
+ */
+export const defaultToolRegistry = new ToolRegistry();

package/dist/src/tools/spawn-exec.js

@@ -0,0 +1,109 @@
+/**
+ * Streaming subprocess wrapper.
+ *
+ * Replaces `promisify(exec)` for long-running DevOps commands (terraform,
+ * kubectl, helm, bash). Unlike `execAsync`, this streams stdout/stderr chunks
+ * in real-time via the `onChunk` callback so the TUI can show live output
+ * instead of a frozen spinner for multi-minute operations.
+ */
+import { spawn } from 'node:child_process';
+// ---------------------------------------------------------------------------
+// Secret redaction
+// ---------------------------------------------------------------------------
+const SECRET_PATTERNS = [
+    /AKIA[0-9A-Z]{16}/g,
+    /(?:password|secret|token|key)\s*[:=]\s*\S+/gi,
+    /Bearer\s+[A-Za-z0-9\-._~+/]+=*/gi,
+];
+function redactSecrets(text) {
+    return SECRET_PATTERNS.reduce((t, p) => t.replace(p, '[REDACTED]'), text);
+}
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Spawn a shell command and stream its output in real-time.
+ *
+ * - stdout and stderr are both captured and forwarded to `onChunk`.
+ * - The returned promise resolves with the full stdout, stderr, and exit code.
+ * - If `timeout` is set, the process is killed after that many milliseconds
+ *   and the promise rejects with a timeout error.
+ *
+ * @example
+ * ```ts
+ * const result = await spawnExec('terraform apply -auto-approve', {
+ *   cwd: '/infra/aws',
+ *   onChunk: (chunk) => process.stdout.write(chunk),
+ * });
+ * ```
+ */
+export async function spawnExec(command, options = {}) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn('sh', ['-c', command], {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+        });
+        let stdout = '';
+        let stderr = '';
+        // Buffer chunks and flush every 100ms to avoid excessive re-renders
+        let buffer = '';
+        const flushInterval = setInterval(() => {
+            if (buffer && options.onChunk) {
+                options.onChunk(buffer);
+                buffer = '';
+            }
+        }, 100);
+        proc.stdout.on('data', (chunk) => {
+            const text = chunk.toString();
+            stdout += text;
+            buffer += redactSecrets(text);
+        });
+        proc.stderr.on('data', (chunk) => {
+            const text = chunk.toString();
+            stderr += text;
+            // C5: Prefix each stderr line with dim-red ANSI so ToolCallDisplay renders them distinctly
+            const tagged = text.split('\n').map(l => l ? `\x1b[2;31m${l}\x1b[0m` : l).join('\n');
+            buffer += tagged;
+        });
+        proc.on('close', (code) => {
+            clearInterval(flushInterval);
+            // Flush any remaining buffered content
+            if (buffer && options.onChunk) {
+                options.onChunk(buffer);
+                buffer = '';
+            }
+            resolve({ stdout, stderr, exitCode: code ?? 0 });
+        });
+        proc.on('error', (err) => {
+            clearInterval(flushInterval);
+            reject(err);
+        });
+        // GAP-9: AbortSignal support — kill process and reject on abort
+        if (options.signal) {
+            const abortHandler = () => {
+                try {
+                    proc.kill('SIGTERM');
+                }
+                catch { /* ignore */ }
+                clearInterval(flushInterval);
+                reject(new Error('Operation cancelled by user (Ctrl+C)'));
+            };
+            options.signal.addEventListener('abort', abortHandler, { once: true });
+            proc.on('close', () => {
+                try {
+                    options.signal?.removeEventListener('abort', abortHandler);
+                }
+                catch { /* ignore */ }
+            });
+        }
+        if (options.timeout) {
+            setTimeout(() => {
+                proc.kill();
+                clearInterval(flushInterval);
+                const toolLabel = options.label ?? command.split(' ')[0];
+                const seconds = Math.round(options.timeout / 1000);
+                reject(new Error(`[${toolLabel}] timed out after ${seconds}s. Override via NIMBUS.md "## Tool Timeouts".`));
+            }, options.timeout);
+        }
+    });
+}