indusagi-coding-agent 0.1.25 → 0.1.26

package/dist/core/tools/bash.d.ts

@@ -1,428 +0,0 @@
-/**
- * Bash Tool - Execute shell commands with streaming and timeout support
- *
- * @module core/tools/bash
- * @description
- * Implements the bash tool for the agent. Executes arbitrary bash commands
- * in the specified working directory with support for:
- * - Real-time output streaming via onUpdate callbacks
- * - Timeout enforcement
- * - Custom execution backends (SSH, containers)
- *
- * Based on Anthropic's Claude API tool definitions and bash execution patterns.
- * Refactored for agent streaming and multi-backend execution.
- * - Large output handling with temp files
- * - Error exit code detection
- *
- * ## Tool Interface
- *
- * **Input Parameters:**
- * - `command` (required): Bash command to execute
- * - `timeout` (optional): Timeout in seconds (no default)
- *
- * **Output:**
- * - Text content with command output
- * - Tool details with truncation info and full output path
- *
- * **Error Behavior:**
- * - Exit code !== 0 → Tool error (rejected)
- * - Timeout → Tool error "Command timed out after N seconds"
- * - Aborted → Tool error "Command aborted"
- * - Other errors → Tool error with message
- *
- * ## Usage in Agent Loops
- *
- * The agent can use this tool to:
- * - Run tests, builds, and deployments
- * - Query system state (ls, git status, npm list, etc.)
- * - Execute scripts and utilities
- * - Validate changes
- *
- * Tool results are included in LLM context for further analysis.
- *
- * ## Security & Safety
- *
- * **No input validation:**
- * - Commands are executed as-is (caller/LLM responsible for safety)
- * - No command whitelisting or blocking
- * - Caller can restrict via BashOperations interface
- *
- * **Execution isolation:**
- * - Runs in separate process (shell process)
- * - No access to parent's memory or file descriptors
- * - Process killed on abort/timeout (kills children too)
- *
- * **Output safety:**
- * - Large output written to temp files (not memory)
- * - Output truncated tail (keeps last 100KB)
- * - Temp files cleaned up by filesystem (caller responsibility)
- *
- * **Environment handling:**
- * - Merges provided env vars with shell defaults
- * - Caller responsible for filtering sensitive vars
- * - Shell config resolved from system defaults
- *
- * ## Customization
- *
- * **Custom Execution Backend:**
- * ```typescript
- * const sshTool = createBashTool(cwd, {
- *   operations: {
- *     exec: async (cmd, cwd, opts) => {
- *       // SSH execution: ssh user@host "cd cwd && cmd"
- *       const { execSync } = require('child_process');
- *       // Stream output via opts.onData(buffer)
- *       return { exitCode: 0 };
- *     },
- *   },
- * });
- * ```
- *
- * **Command Prefix:**
- * ```typescript
- * const aliasedTool = createBashTool(cwd, {
- *   commandPrefix: "shopt -s expand_aliases\n. ~/.bashrc",
- * });
- * // Now bash aliases will work
- * ```
- *
- * **Hook Integration:**
- * ```typescript
- * const toolWithHooks = createBashTool(cwd, {
- *   hookRunner: hooksRunner,
- * });
- * // Hooks can inject environment via shell.env hook
- * ```
- *
- * ## Output Handling
- *
- * **Small output (<50KB):**
- * - Returned directly in tool response
- * - Sent to LLM context immediately
- *
- * **Large output (>50KB):**
- * - Written to temp file: `/tmp/indusagi-bash-<random>.log`
- * - Tool response shows last 100KB with notice
- * - Truncated: true in details
- * - Agent can read full output from fullOutputPath
- *
- * **Very long lines (single line >30KB):**
- * - Edge case: line longer than entire max output
- * - Tool shows truncation notice
- * - Full output still in temp file
- *
- * ## Performance
- *
- * - Output streamed via onUpdate callbacks (no buffering)
- * - Large output written to disk (not memory)
- * - Process stdout/stderr captured separately
- * - Timeout checked per second (or per data chunk)
- *
- * ## Error Handling
- *
- * **Rejected with error message:**
- * - Non-zero exit codes: "Command exited with code X"
- * - Timeout: "Command timed out after X seconds"
- * - Abort: "Command aborted"
- * - Spawn errors: "ENOENT: command not found" etc.
- *
- * **Error recovery:**
- * - Extensions can handle via tool.error hooks
- * - Agent can suggest alternatives or retry
- * - Partial output included in error message
- *
- * ## Examples
- *
- * ### Simple command
- * ```typescript
- * // Agent calls: bash {command: "echo hello"}
- * // Output: "hello"
- * ```
- *
- * ### With streaming
- * ```typescript
- * // Agent calls: bash {command: "npm test"}
- * // onUpdate called repeatedly with partial output
- * // Final result includes full output or temp file path
- * ```
- *
- * ### With timeout
- * ```typescript
- * // Agent calls: bash {command: "sleep 100", timeout: 5}
- * // After 5 seconds: rejected with "Command timed out after 5 seconds"
- * ```
- *
- * ## Attribution
- *
- * Based on: indusagi-agent bash tool
- * Modifications:
- * - Added streaming via onUpdate callbacks
- * - Added temporary file handling for large output
- * - Added hook runner integration
- * - Improved error messages with context
- * - Added custom operations interface for pluggability
- */
-import type { AgentTool } from "indusagi/agent";
-import type { HookRunner } from "../hooks/index.js";
-import { type TruncationResult } from "./truncate.js";
-/**
- * JSON Schema for bash tool parameters
- * @internal
- */
-declare const bashSchema: import("@sinclair/typebox").TObject<{
-    command: import("@sinclair/typebox").TString;
-    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
-}>;
-/**
- * Tool-specific details returned with bash execution results
- *
- * Used to communicate truncation status and full output location to extensions.
- */
-export interface BashToolDetails {
-    /** Truncation information if output was too large */
-    truncation?: TruncationResult;
-    /** Path to temp file containing full output (only if truncated) */
-    fullOutputPath?: string;
-}
-/**
- * Pluggable interface for bash command execution
- *
- * Allows custom implementations for:
- * - Remote execution (SSH, containers, cloud VMs)
- * - Sandboxing (seccomp, chroot, etc.)
- * - Testing (mocked execution)
- * - Custom runtimes
- *
- * Implementations must:
- * 1. Call onData(buffer) as output becomes available
- * 2. Respect AbortSignal for cancellation
- * 3. Enforce timeout if provided
- * 4. Return exit code (null if killed/timeout)
- *
- * @example
- * ```typescript
- * const sshOps: BashOperations = {
- *   exec: async (cmd, cwd, opts) => {
- *     // Stream output via opts.onData()
- *     // Return exit code
- *   },
- * };
- *
- * const tool = createBashTool(cwd, { operations: sshOps });
- * ```
- */
-export interface BashOperations {
-    /**
-     * Execute a command with output streaming and timeout support
-     *
-     * **Responsibilities:**
-     * 1. Accept command and execution options
-     * 2. Stream output via onData callback as it becomes available
-     * 3. Respect AbortSignal for cancellation
-     * 4. Enforce timeout if provided
-     * 5. Kill/cleanup on timeout or abort
-     * 6. Return exit code or null if killed
-     *
-     * **Must NOT:**
-     * - Validate or filter commands
-     * - Change working directory before executing
-     * - Modify command arguments
-     * - Capture environment variables
-     *
-     * @param command - The bash command to execute (not validated)
-     * @param cwd - Working directory (must be validated by caller)
-     * @param options - Execution options:
-     *   - onData: Callback called with output buffers as available
-     *   - signal: AbortSignal for cancellation
-     *   - timeout: Timeout in seconds (enforce or error)
-     *   - env: Environment variables to merge
-     *
-     * @returns Promise<{ exitCode: number | null }>
-     *   - exitCode: 0-255 on successful completion
-     *   - null if process was killed (abort or timeout)
-     *
-     * @throws Error if:
-     *   - Working directory doesn't exist
-     *   - Process spawn fails (ENOENT, EPERM, etc.)
-     *   - Other system errors
-     *
-     * @example
-     * ```typescript
-     * // Local shell implementation
-     * exec: (cmd, cwd, opts) => {
-     *   const child = spawn(shell, ['-c', cmd], { cwd });
-     *   child.stdout.on('data', opts.onData);
-     *   return promise that resolves with exit code;
-     * }
-     * ```
-     */
-    exec: (command: string, cwd: string, options: {
-        /** Callback for streaming output buffers */
-        onData: (data: Buffer) => void;
-        /** AbortSignal for cancellation */
-        signal?: AbortSignal;
-        /** Timeout in seconds */
-        timeout?: number;
-        /** Environment variables to merge */
-        env?: NodeJS.ProcessEnv;
-    }) => Promise<{
-        exitCode: number | null;
-    }>;
-}
-/**
- * Configuration options for the bash tool
- *
- * Allows customization of execution backend, command preprocessing, and hooks.
- */
-export interface BashToolOptions {
-    /**
-     * Custom operations for command execution
-     *
-     * Default: Local system shell via spawn
-     * Custom: SSH, Docker, containers, mocked execution
-     *
-     * @example
-     * ```typescript
-     * const sshTool = createBashTool(cwd, {
-     *   operations: {
-     *     exec: (cmd, cwd, opts) => {
-     *       // SSH over wire
-     *       // Stream output via opts.onData
-     *       // Return { exitCode }
-     *     },
-     *   },
-     * });
-     * ```
-     */
-    operations?: BashOperations;
-    /**
-     * Command prefix prepended to every command
-     *
-     * Useful for:
-     * - Enabling bash options: "shopt -s expand_aliases"
-     * - Sourcing shell rc files: ". ~/.bashrc"
-     * - Setting default env vars: "export DEBUG=*"
-     * - Changing shell behavior
-     *
-     * @example
-     * ```typescript
-     * const tool = createBashTool(cwd, {
-     *   commandPrefix: "shopt -s expand_aliases\n. ~/.bashrc",
-     * });
-     * // User command "my-alias arg" becomes:
-     * // "shopt -s expand_aliases\n. ~/.bashrc\nmy-alias arg"
-     * ```
-     */
-    commandPrefix?: string;
-    /**
-     * Hook runner for advanced customization
-     *
-     * Allows hooks to inject environment variables via "shell.env" hook.
-     * Hooks can modify environment before command execution.
-     *
-     * @example
-     * ```typescript
-     * hookRunner.onHook("shell.env", (ctx, { env }) => {
-     *   env.CUSTOM_VAR = "value";
-     *   return { env };
-     * });
-     * ```
-     */
-    hookRunner?: HookRunner;
-}
-/**
- * Create a bash tool with custom configuration
- *
- * Creates an AgentTool that can execute bash commands. Supports:
- * - Custom execution backends (local, SSH, containers)
- * - Command preprocessing (aliases, initialization)
- * - Hook integration (environment variable injection)
- * - Streaming output and timeout enforcement
- * - Large output handling with temp files
- *
- * **Tool Behavior:**
- * - Commands execute in specified working directory
- * - Output streamed via onUpdate callbacks
- * - Large outputs written to temp files
- * - Non-zero exit codes → Tool error
- * - Timeout errors rejected with message
- * - Abort signal triggers clean cancellation
- *
- * **Tool Parameters:**
- * - `command` (required, string): Bash command to execute
- * - `timeout` (optional, number): Timeout in seconds
- *
- * **Tool Output:**
- * - Text: Command output (last 100KB if truncated)
- * - Details: Truncation info and temp file path
- *
- * @param cwd - Working directory for command execution
- *   - Must exist and be readable
- *   - Commands execute with this as working directory
- *   - Can be overridden per execution
- *
- * @param options - Optional configuration
- *   - operations: Custom execution backend (default: local shell)
- *   - commandPrefix: Prefix injected into every command
- *   - hookRunner: Hooks for environment customization
- *
- * @returns AgentTool instance ready to use
- *
- * **Error Handling:**
- * - Non-zero exit codes: `Tool error: "Command exited with code X"`
- * - Timeout: `Tool error: "Command timed out after X seconds"`
- * - Abort: `Tool error: "Command aborted"`
- * - Spawn errors: `Tool error: "ENOENT: command not found"`
- *
- * @example
- * ```typescript
- * // Basic tool
- * const tool = createBashTool(process.cwd());
- *
- * // With custom backend (SSH)
- * const sshTool = createBashTool("/workspace", {
- *   operations: sshOperations,
- * });
- *
- * // With alias support
- * const aliasTool = createBashTool(cwd, {
- *   commandPrefix: "shopt -s expand_aliases\n. ~/.bashrc",
- * });
- *
- * // With hooks
- * const hookTool = createBashTool(cwd, {
- *   hookRunner: hooksRunner,
- * });
- * ```
- *
- * @see BashToolOptions for detailed configuration options
- * @see BashOperations for custom execution backend interface
- */
-export declare function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema>;
-/**
- * Default bash tool instance
- *
- * Pre-created bash tool using current process working directory.
- * Useful for simple cases where customization isn't needed.
- *
- * Equivalent to:
- * ```typescript
- * const bashTool = createBashTool(process.cwd());
- * ```
- *
- * For custom configuration, use createBashTool() directly.
- *
- * @example
- * ```typescript
- * import { bashTool } from "./tools/bash.js";
- * const agent = new Agent({ tools: [bashTool] });
- * ```
- *
- * @see createBashTool for custom configuration
- */
-export declare const bashTool: AgentTool<import("@sinclair/typebox").TObject<{
-    command: import("@sinclair/typebox").TString;
-    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
-}>, any>;
-export {};
-//# sourceMappingURL=bash.d.ts.map

package/dist/core/tools/bash.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/core/tools/bash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmKG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAoD,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAmBtH;;;GAGG;AACH,QAAA,MAAM,UAAU;;;EAGd,CAAC;AAEH;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,qDAAqD;IACrD,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,IAAI,EAAE,CACL,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;QACR,4CAA4C;QAC5C,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAC/B,mCAAmC;QACnC,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,yBAAyB;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,qCAAqC;QACrC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;KACxB,KACG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC1C;AA2FD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAE5B;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAqJnG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,QAAQ;;;QAAgC,CAAC"}