@compilr-dev/agents 0.3.1 → 0.3.4

package/dist/state/agent-state.js

@@ -22,6 +22,7 @@ export function createEmptyState(sessionId, systemPrompt) {
         systemPrompt,
         todos: [],
         currentIteration: 0,
+        turnCount: 0,
         totalTokensUsed: 0,
         createdAt: now,
         updatedAt: now,
@@ -40,6 +41,7 @@ export function createAgentState(options) {
         model: options.model,
         todos: serializeTodos(options.todos),
         currentIteration: options.currentIteration,
+        turnCount: options.turnCount,
         totalTokensUsed: options.totalTokensUsed,
         createdAt: options.createdAt || now,
         updatedAt: now,

package/dist/state/serializer.js

@@ -34,7 +34,11 @@ export class JsonSerializer {
             throw StateError.deserialization('Invalid JSON format', error instanceof Error ? error : undefined);
         }
         this.validateParsed(parsed);
-        return parsed;
+        // Ensure turnCount has a default value for backward compatibility
+        // with saved states from before turnCount was added (pre-v2 states)
+        const partialState = parsed;
+        const turnCount = partialState.turnCount ?? partialState.messages.filter((m) => m.role === 'user').length;
+        return { ...partialState, turnCount };
     }
     /**
      * Validate state before serialization (public interface method).
@@ -77,6 +81,11 @@ export class JsonSerializer {
         if (typeof state.version !== 'number') {
             throw StateError.invalidState('version must be a number');
         }
+        // turnCount is optional for backward compatibility
+        // (old saved states may not have it)
+        if (state.turnCount !== undefined && typeof state.turnCount !== 'number') {
+            throw StateError.invalidState('turnCount must be a number if present');
+        }
         // Version check - safe to cast since we validated it's a number
         const version = state.version;
         if (version > CURRENT_STATE_VERSION) {
@@ -119,7 +128,11 @@ export class CompactJsonSerializer {
             throw StateError.deserialization('Invalid JSON format', error instanceof Error ? error : undefined);
         }
         this.validateParsed(parsed);
-        return parsed;
+        // Ensure turnCount has a default value for backward compatibility
+        // with saved states from before turnCount was added (pre-v2 states)
+        const partialState = parsed;
+        const turnCount = partialState.turnCount ?? partialState.messages.filter((m) => m.role === 'user').length;
+        return { ...partialState, turnCount };
     }
     /**
      * Validate state before serialization (public interface method).
@@ -159,6 +172,11 @@ export class CompactJsonSerializer {
         if (typeof state.version !== 'number') {
             throw StateError.invalidState('version must be a number');
         }
+        // turnCount is optional for backward compatibility
+        // (old saved states may not have it)
+        if (state.turnCount !== undefined && typeof state.turnCount !== 'number') {
+            throw StateError.invalidState('turnCount must be a number if present');
+        }
         // Version check - safe to cast since we validated it's a number
         const version = state.version;
         if (version > CURRENT_STATE_VERSION) {

package/dist/state/types.d.ts

@@ -35,6 +35,11 @@ export interface AgentState {
      * Current iteration count
      */
     currentIteration: number;
+    /**
+     * Number of conversation turns (user + assistant exchanges)
+     * Used by context manager to track recent vs old messages for compaction.
+     */
+    turnCount: number;
     /**
      * Total tokens used in the session
      */

package/dist/tools/builtin/ask-user-simple.js

@@ -145,5 +145,6 @@ export function createAskUserSimpleTool(options = {}) {
                 return createErrorResult(error instanceof Error ? error.message : String(error));
             }
         },
+        silent: true,
     });
 }

package/dist/tools/builtin/ask-user.js

@@ -191,5 +191,6 @@ export function createAskUserTool(options = {}) {
                 return createErrorResult(error instanceof Error ? error.message : String(error));
             }
         },
+        silent: true,
     });
 }

package/dist/tools/builtin/bash.js

@@ -132,6 +132,8 @@ async function executeBash(input, context) {
             env,
             onOutput: context.onOutput,
             fifoCheck,
+            abortSignal: context.abortSignal,
+            onBackground: context.onBackground,
         });
     }
     // Non-streaming execution (original behavior)
@@ -179,7 +181,7 @@ async function executeBash(input, context) {
  * Execute command with streaming output to onOutput callback
  */
 async function executeWithStreaming(command, options) {
-    const { cwd, timeout = DEFAULT_TIMEOUT, env, onOutput, fifoCheck } = options;
+    const { cwd, timeout = DEFAULT_TIMEOUT, env, onOutput, fifoCheck, abortSignal, onBackground, } = options;
     return new Promise((resolve) => {
         const child = spawn(command, [], {
             cwd,
@@ -189,6 +191,7 @@ async function executeWithStreaming(command, options) {
         let stdoutBuffer = '';
         let stderrBuffer = '';
         let timedOut = false;
+        let backgrounded = false;
         // Set up timeout
         const timeoutId = timeout > 0
             ? setTimeout(() => {
@@ -198,8 +201,62 @@ async function executeWithStreaming(command, options) {
                 setTimeout(() => child.kill('SIGKILL'), 5000);
             }, timeout)
             : undefined;
+        // Handle abort signal for backgrounding
+        if (abortSignal) {
+            const handleAbort = () => {
+                // Check if this is a "background" abort (not a cancel)
+                const reason = abortSignal.reason;
+                if (reason === 'background') {
+                    backgrounded = true;
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    // Move process to ShellManager
+                    const manager = getDefaultShellManager();
+                    const shellId = manager.adoptProcess(child, {
+                        command,
+                        cwd,
+                        initialStdout: stdoutBuffer,
+                        initialStderr: stderrBuffer,
+                    });
+                    // Notify via callback
+                    if (onBackground) {
+                        onBackground(shellId, stdoutBuffer + stderrBuffer);
+                    }
+                    // Resolve with backgrounded result
+                    resolve(createSuccessResult({
+                        backgrounded: true,
+                        shell_id: shellId,
+                        partial_stdout: truncateOutput(stdoutBuffer, DEFAULT_MAX_OUTPUT_SIZE).content,
+                        partial_stderr: truncateOutput(stderrBuffer, DEFAULT_MAX_OUTPUT_SIZE).content,
+                        message: `Command moved to background. Use bash_output with shell_id '${shellId}' to check status.`,
+                    }));
+                }
+                else {
+                    // Regular cancellation - kill the process
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    child.kill('SIGTERM');
+                    setTimeout(() => {
+                        try {
+                            child.kill('SIGKILL');
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                    }, 5000);
+                    resolve(createErrorResult('Command cancelled by user'));
+                }
+            };
+            if (abortSignal.aborted) {
+                handleAbort();
+                return;
+            }
+            abortSignal.addEventListener('abort', handleAbort, { once: true });
+        }
         // Stream stdout
         child.stdout.on('data', (data) => {
+            if (backgrounded)
+                return; // Stop collecting if backgrounded
             const text = data.toString();
             stdoutBuffer += text;
             // Emit each line separately for better UI updates
@@ -212,6 +269,8 @@ async function executeWithStreaming(command, options) {
         });
         // Stream stderr
         child.stderr.on('data', (data) => {
+            if (backgrounded)
+                return; // Stop collecting if backgrounded
             const text = data.toString();
             stderrBuffer += text;
             // Emit each line separately
@@ -224,6 +283,8 @@ async function executeWithStreaming(command, options) {
         });
         // Handle completion
         child.on('close', (code) => {
+            if (backgrounded)
+                return; // Already resolved
             if (timeoutId)
                 clearTimeout(timeoutId);
             if (timedOut) {
@@ -243,6 +304,8 @@ async function executeWithStreaming(command, options) {
         });
         // Handle spawn errors
         child.on('error', (error) => {
+            if (backgrounded)
+                return; // Already resolved
             if (timeoutId)
                 clearTimeout(timeoutId);
             resolve(createErrorResult(error.message));
@@ -253,7 +316,7 @@ async function executeWithStreaming(command, options) {
  * Execute command with streaming output (custom options version for createBashTool)
  */
 async function executeWithStreamingCustom(command, options) {
-    const { cwd, timeout = DEFAULT_TIMEOUT, env, onOutput, fifoCheck, maxOutputSize, shell, } = options;
+    const { cwd, timeout = DEFAULT_TIMEOUT, env, onOutput, fifoCheck, maxOutputSize, shell, abortSignal, onBackground, } = options;
     return new Promise((resolve) => {
         const child = spawn(command, [], {
             cwd,
@@ -263,6 +326,7 @@ async function executeWithStreamingCustom(command, options) {
         let stdoutBuffer = '';
         let stderrBuffer = '';
         let timedOut = false;
+        let backgrounded = false;
         // Set up timeout
         const timeoutId = timeout > 0
             ? setTimeout(() => {
@@ -272,8 +336,57 @@ async function executeWithStreamingCustom(command, options) {
                 setTimeout(() => child.kill('SIGKILL'), 5000);
             }, timeout)
             : undefined;
+        // Handle abort signal for backgrounding
+        if (abortSignal) {
+            const handleAbort = () => {
+                const reason = abortSignal.reason;
+                if (reason === 'background') {
+                    backgrounded = true;
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    const manager = getDefaultShellManager();
+                    const shellId = manager.adoptProcess(child, {
+                        command,
+                        cwd,
+                        initialStdout: stdoutBuffer,
+                        initialStderr: stderrBuffer,
+                    });
+                    if (onBackground) {
+                        onBackground(shellId, stdoutBuffer + stderrBuffer);
+                    }
+                    resolve(createSuccessResult({
+                        backgrounded: true,
+                        shell_id: shellId,
+                        partial_stdout: truncateOutput(stdoutBuffer, maxOutputSize).content,
+                        partial_stderr: truncateOutput(stderrBuffer, maxOutputSize).content,
+                        message: `Command moved to background. Use bash_output with shell_id '${shellId}' to check status.`,
+                    }));
+                }
+                else {
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    child.kill('SIGTERM');
+                    setTimeout(() => {
+                        try {
+                            child.kill('SIGKILL');
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                    }, 5000);
+                    resolve(createErrorResult('Command cancelled by user'));
+                }
+            };
+            if (abortSignal.aborted) {
+                handleAbort();
+                return;
+            }
+            abortSignal.addEventListener('abort', handleAbort, { once: true });
+        }
         // Stream stdout
         child.stdout.on('data', (data) => {
+            if (backgrounded)
+                return;
             const text = data.toString();
             stdoutBuffer += text;
             // Emit each line separately for better UI updates
@@ -286,6 +399,8 @@ async function executeWithStreamingCustom(command, options) {
         });
         // Stream stderr
         child.stderr.on('data', (data) => {
+            if (backgrounded)
+                return;
             const text = data.toString();
             stderrBuffer += text;
             // Emit each line separately
@@ -298,6 +413,8 @@ async function executeWithStreamingCustom(command, options) {
         });
         // Handle completion
         child.on('close', (code) => {
+            if (backgrounded)
+                return;
             if (timeoutId)
                 clearTimeout(timeoutId);
             if (timedOut) {
@@ -317,6 +434,8 @@ async function executeWithStreamingCustom(command, options) {
         });
         // Handle spawn errors
         child.on('error', (error) => {
+            if (backgrounded)
+                return;
             if (timeoutId)
                 clearTimeout(timeoutId);
             resolve(createErrorResult(error.message));
@@ -444,6 +563,8 @@ export function createBashTool(options) {
                     fifoCheck,
                     maxOutputSize,
                     shell,
+                    abortSignal: context.abortSignal,
+                    onBackground: context.onBackground,
                 });
             }
             // Execute with merged options (non-streaming)

package/dist/tools/builtin/shell-manager.d.ts

@@ -1,6 +1,7 @@
 /**
  * Shell Manager - Track and manage background shell processes
  */
+import { type ChildProcess } from 'node:child_process';
 /**
  * Status of a background shell
  */
@@ -153,6 +154,20 @@ export declare class ShellManager {
      * Kill all running shells
      */
     killAll(): number;
+    /**
+     * Adopt an existing running process into the shell manager.
+     * Used when moving a foreground bash command to background (Ctrl+B).
+     *
+     * @param process - The ChildProcess to adopt
+     * @param options - Options including command and initial buffers
+     * @returns The shell ID for tracking
+     */
+    adoptProcess(process: ChildProcess, options: {
+        command: string;
+        cwd?: string;
+        initialStdout?: string;
+        initialStderr?: string;
+    }): string;
     /**
      * Cleanup - kill all shells and clear state
      */

package/dist/tools/builtin/shell-manager.js

@@ -277,6 +277,57 @@ export class ShellManager {
         }
         return count;
     }
+    /**
+     * Adopt an existing running process into the shell manager.
+     * Used when moving a foreground bash command to background (Ctrl+B).
+     *
+     * @param process - The ChildProcess to adopt
+     * @param options - Options including command and initial buffers
+     * @returns The shell ID for tracking
+     */
+    adoptProcess(process, options) {
+        const id = randomUUID().slice(0, 8);
+        const state = {
+            info: {
+                id,
+                command: options.command,
+                status: 'running',
+                startTime: new Date(),
+                cwd: options.cwd,
+            },
+            process,
+            stdoutBuffer: options.initialStdout ? [options.initialStdout] : [],
+            stderrBuffer: options.initialStderr ? [options.initialStderr] : [],
+            readIndex: { stdout: 0, stderr: 0 },
+        };
+        // Attach listeners for ongoing output (stdout may be null if already closed)
+        if (process.stdout) {
+            process.stdout.on('data', (chunk) => {
+                this.appendToBuffer(state.stdoutBuffer, chunk.toString());
+            });
+        }
+        // Attach stderr listener
+        if (process.stderr) {
+            process.stderr.on('data', (chunk) => {
+                this.appendToBuffer(state.stderrBuffer, chunk.toString());
+            });
+        }
+        // Handle completion
+        process.on('close', (code) => {
+            state.info.status = code === 0 ? 'completed' : 'failed';
+            state.info.exitCode = code ?? undefined;
+            state.info.endTime = new Date();
+            this.scheduleCleanup(id);
+        });
+        process.on('error', (error) => {
+            state.info.status = 'failed';
+            state.info.endTime = new Date();
+            state.stderrBuffer.push(`Process error: ${error.message}`);
+            this.scheduleCleanup(id);
+        });
+        this.shells.set(id, state);
+        return id;
+    }
     /**
      * Cleanup - kill all shells and clear state
      */

package/dist/tools/builtin/suggest.js

@@ -95,5 +95,6 @@ export function createSuggestTool(options = {}) {
                 action: input.action,
             }));
         },
+        silent: true,
     });
 }

package/dist/tools/builtin/todo.js

@@ -271,6 +271,7 @@ export function createTodoTools(store) {
                 total: input.todos.length,
             }));
         },
+        silent: true,
     });
     const todoRead = defineTool({
         name: 'todo_read',
@@ -308,6 +309,7 @@ export function createTodoTools(store) {
                 total: todos.length,
             }));
         },
+        silent: true,
     });
     return { todoWrite, todoRead, store: todoStore };
 }

package/dist/tools/define.d.ts

@@ -29,6 +29,12 @@ export interface DefineToolOptions<T extends object> {
      * Default: false (sequential execution)
      */
     parallel?: boolean;
+    /**
+     * If true, this tool runs silently without spinner updates or result output.
+     * Used for internal housekeeping tools like todo_read, suggest, etc.
+     * Default: false (normal visibility)
+     */
+    silent?: boolean;
 }
 /**
  * Define a tool with type-safe input handling

package/dist/tools/define.js

@@ -33,6 +33,7 @@ export function defineTool(options) {
         definition,
         execute: options.execute,
         parallel: options.parallel,
+        silent: options.silent,
     };
 }
 /**

package/dist/tools/types.d.ts

@@ -39,6 +39,19 @@ export interface ToolExecutionContext {
      * Tool use ID for correlation with events
      */
     toolUseId?: string;
+    /**
+     * AbortSignal for cancelling/backgrounding the tool execution.
+     * When aborted with reason 'background', the bash tool should move the
+     * process to ShellManager instead of terminating.
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * Callback to notify when a process has been moved to background.
+     * Called by bash tool when user presses Ctrl+B (abortSignal with 'background' reason).
+     * @param shellId - The shell ID in ShellManager for later retrieval
+     * @param partialOutput - Output collected so far (stdout + stderr)
+     */
+    onBackground?: (shellId: string, partialOutput: string) => void;
 }
 /**
  * Tool handler function type
@@ -59,6 +72,12 @@ export interface Tool<T = object> {
      * Default: false (sequential execution)
      */
     parallel?: boolean;
+    /**
+     * If true, this tool runs silently without spinner updates or result output.
+     * Used for internal housekeeping tools like todo_read, suggest, etc.
+     * Default: false (normal visibility)
+     */
+    silent?: boolean;
 }
 /**
  * Tool registry for managing available tools

package/dist/utils/index.d.ts

@@ -1,16 +1,131 @@
 /**
- * Utility functions
+ * Utility functions for @compilr-dev/agents
  */
 /**
  * Generate a unique ID for tool uses
  */
 export declare function generateId(): string;
 /**
- * Sleep for a specified duration
+ * Sleep for a specified duration, respecting AbortSignal
+ *
+ * @param ms - Duration in milliseconds
+ * @param signal - Optional AbortSignal to cancel sleep
+ * @throws Error if signal is aborted
  */
-export declare function sleep(ms: number): Promise<void>;
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
 /**
- * Retry a function with exponential backoff
+ * Configuration for LLM retry behavior
+ */
+export interface RetryConfig {
+    /**
+     * Enable/disable automatic retry.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of retry attempts (not including initial attempt).
+     * Total attempts = maxAttempts + 1
+     * @default 10
+     */
+    maxAttempts?: number;
+    /**
+     * Base delay in milliseconds for exponential backoff.
+     * Actual delay = min(baseDelayMs * 2^attempt, maxDelayMs) + jitter
+     * @default 1000
+     */
+    baseDelayMs?: number;
+    /**
+     * Maximum delay in milliseconds (cap for exponential growth).
+     * @default 30000
+     */
+    maxDelayMs?: number;
+}
+/**
+ * Default retry configuration
+ */
+export declare const DEFAULT_RETRY_CONFIG: Required<RetryConfig>;
+/**
+ * Options for the withRetry function
+ */
+export interface WithRetryOptions<E extends Error> {
+    /**
+     * Maximum retry attempts (default: 10)
+     */
+    maxAttempts?: number;
+    /**
+     * Base delay in milliseconds (default: 1000)
+     */
+    baseDelayMs?: number;
+    /**
+     * Maximum delay cap in milliseconds (default: 30000)
+     */
+    maxDelayMs?: number;
+    /**
+     * Function to determine if an error is retryable
+     */
+    isRetryable?: (error: E) => boolean;
+    /**
+     * Callback invoked before each retry attempt
+     */
+    onRetry?: (attempt: number, maxAttempts: number, error: E, delayMs: number) => void;
+    /**
+     * Callback invoked when all retries are exhausted
+     */
+    onExhausted?: (attempts: number, error: E) => void;
+    /**
+     * AbortSignal to cancel retries
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (0-indexed)
+ * @param baseDelayMs - Base delay in milliseconds
+ * @param maxDelayMs - Maximum delay cap in milliseconds
+ * @returns Delay in milliseconds
+ */
+export declare function calculateBackoffDelay(attempt: number, baseDelayMs?: number, maxDelayMs?: number): number;
+/**
+ * Execute an async function with automatic retry on failure
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry options
+ * @returns Result of the function
+ * @throws Last error if all retries exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => {
+ *     const response = await fetch(url);
+ *     if (!response.ok) throw new Error(`HTTP ${response.status}`);
+ *     return response.json();
+ *   },
+ *   {
+ *     maxAttempts: 5,
+ *     isRetryable: (error) => error.message.includes('HTTP 5'),
+ *     onRetry: (attempt, max, error, delay) => {
+ *       console.log(`Retry ${attempt}/${max} in ${delay}ms: ${error.message}`);
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export declare function withRetry<T, E extends Error = Error>(fn: () => Promise<T>, options?: WithRetryOptions<E>): Promise<T>;
+/**
+ * Create a retryable async generator for streaming responses
+ *
+ * This is specifically designed for streaming LLM responses where we need to
+ * retry the entire stream if it fails partway through.
+ *
+ * @param fn - Function that returns an async iterable
+ * @param options - Retry options
+ * @returns Async generator that retries on failure
+ */
+export declare function withRetryGenerator<T, E extends Error = Error>(fn: () => AsyncIterable<T>, options?: WithRetryOptions<E>): AsyncGenerator<T, void, undefined>;
+/**
+ * @deprecated Use withRetry instead. This function is kept for backward compatibility.
  */
 export declare function retry<T>(fn: () => Promise<T>, options?: {
     maxRetries?: number;