@compilr-dev/agents 0.3.2 → 0.3.4

package/dist/providers/together.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Together AI LLM Provider
+ *
+ * Implements LLMProvider interface for Together AI models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createTogetherProvider({
+ *   model: 'meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo',
+ *   apiKey: process.env.TOGETHER_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Together AI API key
+ * - Default model is meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo
+ * - Supports Llama, Mistral, Qwen, and other open models
+ */
+import type { ChatOptions } from './types.js';
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+/**
+ * Configuration for TogetherProvider
+ */
+export interface TogetherProviderConfig {
+    /** Together AI API key (falls back to TOGETHER_API_KEY env var) */
+    apiKey?: string;
+    /** Base URL for Together API (default: https://api.together.xyz) */
+    baseUrl?: string;
+    /** Default model to use (default: meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Together AI LLM Provider
+ *
+ * Provides streaming chat completion using Together AI models.
+ * Supports Llama, Mistral, Qwen, and other open-source models.
+ */
+export declare class TogetherProvider extends OpenAICompatibleProvider {
+    readonly name = "together";
+    private readonly apiKey;
+    constructor(config?: TogetherProviderConfig);
+    /**
+     * Together AI authentication with Bearer token
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * Together AI chat completions endpoint (OpenAI-compatible)
+     */
+    protected getEndpointPath(): string;
+    /**
+     * Together AI uses standard OpenAI body format
+     */
+    protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with Together AI-specific messages
+     */
+    protected mapHttpError(status: number, body: string, _model: string): ProviderError;
+    /**
+     * Map connection errors with Together AI-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create a Together AI provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (TOGETHER_API_KEY)
+ * const provider = createTogetherProvider();
+ *
+ * // With explicit API key
+ * const provider = createTogetherProvider({ apiKey: 'xxx-...' });
+ *
+ * // With custom model
+ * const provider = createTogetherProvider({
+ *   model: 'meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo'
+ * });
+ * ```
+ */
+export declare function createTogetherProvider(config?: TogetherProviderConfig): TogetherProvider;

package/dist/providers/together.js

@@ -0,0 +1,123 @@
+/**
+ * Together AI LLM Provider
+ *
+ * Implements LLMProvider interface for Together AI models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createTogetherProvider({
+ *   model: 'meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo',
+ *   apiKey: process.env.TOGETHER_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Together AI API key
+ * - Default model is meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo
+ * - Supports Llama, Mistral, Qwen, and other open models
+ */
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+// Default configuration
+const DEFAULT_MODEL = 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo';
+const DEFAULT_BASE_URL = 'https://api.together.xyz';
+/**
+ * Together AI LLM Provider
+ *
+ * Provides streaming chat completion using Together AI models.
+ * Supports Llama, Mistral, Qwen, and other open-source models.
+ */
+export class TogetherProvider extends OpenAICompatibleProvider {
+    name = 'together';
+    apiKey;
+    constructor(config = {}) {
+        const apiKey = config.apiKey ?? process.env.TOGETHER_API_KEY;
+        if (!apiKey) {
+            throw new ProviderError('Together AI API key not found. Set TOGETHER_API_KEY environment variable or pass apiKey in config.', 'together');
+        }
+        const baseConfig = {
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            model: config.model ?? DEFAULT_MODEL,
+            maxTokens: config.maxTokens,
+            timeout: config.timeout,
+        };
+        super(baseConfig);
+        this.apiKey = apiKey;
+    }
+    /**
+     * Together AI authentication with Bearer token
+     */
+    getAuthHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+    }
+    /**
+     * Together AI chat completions endpoint (OpenAI-compatible)
+     */
+    getEndpointPath() {
+        return '/v1/chat/completions';
+    }
+    /**
+     * Together AI uses standard OpenAI body format
+     */
+    buildProviderSpecificBody(_options) {
+        return {};
+    }
+    /**
+     * Map HTTP errors with Together AI-specific messages
+     */
+    mapHttpError(status, body, _model) {
+        let message = `Together AI error (${String(status)})`;
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed.error?.message) {
+                message = parsed.error.message;
+            }
+        }
+        catch {
+            message = body || message;
+        }
+        switch (status) {
+            case 401:
+                return new ProviderError('Invalid Together AI API key. Check your TOGETHER_API_KEY.', 'together', 401);
+            case 403:
+                return new ProviderError('Access denied. Check your Together AI API key permissions.', 'together', 403);
+            case 429:
+                return new ProviderError('Together AI rate limit exceeded. Please wait and try again.', 'together', 429);
+            case 500:
+            case 502:
+            case 503:
+                return new ProviderError('Together AI service temporarily unavailable. Please try again later.', 'together', status);
+            default:
+                return new ProviderError(message, 'together', status);
+        }
+    }
+    /**
+     * Map connection errors with Together AI-specific messages
+     */
+    mapConnectionError(_error) {
+        return new ProviderError('Failed to connect to Together AI API. Check your internet connection.', 'together');
+    }
+}
+/**
+ * Create a Together AI provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (TOGETHER_API_KEY)
+ * const provider = createTogetherProvider();
+ *
+ * // With explicit API key
+ * const provider = createTogetherProvider({ apiKey: 'xxx-...' });
+ *
+ * // With custom model
+ * const provider = createTogetherProvider({
+ *   model: 'meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo'
+ * });
+ * ```
+ */
+export function createTogetherProvider(config = {}) {
+    return new TogetherProvider(config);
+}

package/dist/providers/types.d.ts

@@ -70,6 +70,14 @@ export interface LLMUsage {
     outputTokens: number;
     cacheReadTokens?: number;
     cacheCreationTokens?: number;
+    /** Thinking tokens (Gemini 2.5+ models with thinking) */
+    thinkingTokens?: number;
+    /** Debug payload info - estimated char counts before sending to provider */
+    debugPayload?: {
+        systemChars: number;
+        contentsChars: number;
+        toolsChars: number;
+    };
 }
 /**
  * Streaming chunk types

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",
@@ -78,5 +78,8 @@
   },
   "dependencies": {
     "@google/genai": "^1.38.0"
+  },
+  "overrides": {
+    "hono": "^4.11.7"
   }
 }