@compass-ai/nova 1.0.72 → 1.0.74

package/dist/tools/agent-tools.js

@@ -0,0 +1,349 @@
+/**
+ * Agent and sub-task management tools
+ *
+ * Tools for delegating tasks to sub-agents, spawning isolated processes,
+ * polling status, and managing background tasks.
+ */
+import { ActionType } from '../services/action-logger.js';
+import { logger } from '../utils/logger.js';
+export async function registerAgentTools(registry) {
+    // ============================================================
+    // SPAWN_TASK - Sub-agent with budget isolation
+    // ============================================================
+    registry.registerTool('spawn_task', `Spawns a specialized sub-agent to handle a task autonomously with isolated context and budget limits.
+
+## When to Use Each Agent
+
+| Agent | Best For | Tools | Model | Budget |
+|-------|----------|-------|-------|--------|
+| **explore** | Finding files, searching code, understanding structure | Read, Glob, Grep (read-only) | haiku (fast) | 50k tokens, 10 turns |
+| **code-reviewer** | Reviewing code changes for quality, security, best practices | Read, Grep, Glob (read-only) | sonnet | 80k tokens, 15 turns |
+| **debugger** | Investigating errors, test failures, fixing bugs | Read, Edit, Bash, Grep, Glob, AskUserQuestion | sonnet | 100k tokens, 25 turns |
+| **planner** | Designing implementation plans with impact analysis | Read, Glob, Grep, Bash (read-only), AskUserQuestion | sonnet | 60k tokens, 12 turns |
+| **default** | General multi-step tasks that don't fit above categories | All tools | sonnet | 80k tokens, 20 turns |
+
+## Agent Selection Guide
+
+- **"Find where X is defined"** → explore
+- **"Search for files related to Y"** → explore
+- **"Review my changes"** → code-reviewer (provide diff content or file paths in context)
+- **"Check this code for security issues"** → code-reviewer
+- **"Why is this test failing?"** → debugger (provide error output in context)
+- **"Fix this error"** → debugger
+- **"How should I implement X?"** → planner
+- **"Create an implementation plan for Y"** → planner
+- **"Refactor this module"** → default (needs both read and write access)
+- **"Set up CI pipeline"** → default
+
+## Safety Model
+
+- **explore** and **code-reviewer** are strictly **read-only** — they cannot modify files or run commands
+- **planner** has Bash for **read-only inspection** (git log, project config) but cannot edit files
+- **debugger** can read, edit, and execute commands — use when fixes are needed
+- **default** has full access to all tools — use for general multi-step tasks
+
+## Parallel Execution
+
+Launch multiple agents concurrently when tasks are independent:
+- Use **run_in_background=true** to spawn agents without blocking
+- Spawn multiple background agents in a single turn for maximum parallelism
+- Use **poll_task** to check on each agent's progress
+- Example: spawn explore to find files AND spawn code-reviewer to review known files — both run simultaneously
+
+## Features
+
+- **Isolated context**: Sub-agent gets fresh context, doesn't bloat parent
+- **Budget enforcement**: Automatically stops if token/turn limit exceeded
+- **Background execution**: Set run_in_background=true to continue working while agent runs
+- **Process tracking**: Returns processId to check status with poll_task
+- **Custom limits**: Override max_turns and max_tokens per invocation
+
+## Tips
+
+- Use **explore** for quick searches — it uses haiku (faster, cheaper)
+- Use **debugger** when you have an error message or stack trace
+- Provide **context** parameter with relevant code snippets, error messages, or diff output
+- For long tasks, use **run_in_background=true** and poll_task to check progress
+- For read-only agents (explore, code-reviewer), provide any shell output they'd need in the context parameter since they can't run commands themselves`, {
+        type: 'object',
+        properties: {
+            task: {
+                type: 'string',
+                description: 'The task for the sub-agent to complete',
+            },
+            agent_type: {
+                type: 'string',
+                enum: ['explore', 'code-reviewer', 'debugger', 'planner', 'default'],
+                description: 'Type of specialized agent to spawn. Defaults to "default".',
+            },
+            context: {
+                type: 'string',
+                description: 'Additional context to provide to the sub-agent (e.g., relevant code, file paths)',
+            },
+            max_turns: {
+                type: 'number',
+                description: 'Maximum iterations before termination (default varies by agent type)',
+            },
+            max_tokens: {
+                type: 'number',
+                description: 'Maximum context tokens before termination (default varies by agent type)',
+            },
+            run_in_background: {
+                type: 'boolean',
+                description: 'If true, spawns asynchronously and returns immediately with processId',
+            },
+        },
+        required: ['task'],
+    }, async (input, context) => {
+        const { getAgentSpawner } = await import('../services/agent-spawner.js');
+        const spawner = getAgentSpawner();
+        try {
+            const process = await spawner.spawn({
+                task: input.task,
+                agentName: input.agent_type || 'default',
+                context: input.context,
+                budget: {
+                    strategy: 'fixed',
+                    maxTurns: input.max_turns || undefined,
+                    maxTokens: input.max_tokens || undefined,
+                },
+                runInBackground: input.run_in_background || false,
+                projectRoot: context.projectRoot,
+                parentToolCallId: context.toolCallId,
+            });
+            if (input.run_in_background) {
+                return {
+                    success: true,
+                    processId: process.processId,
+                    status: process.status,
+                    agentType: process.agentName,
+                    outputFile: process.outputFile,
+                    message: 'Agent spawned in background. Use poll_task with this processId to check progress.',
+                    budget: {
+                        maxTokens: process.budget.maxTokens,
+                        maxTurns: process.budget.maxTurns,
+                    },
+                };
+            }
+            // Foreground execution - return result directly
+            return {
+                success: process.result?.success ?? false,
+                processId: process.processId,
+                status: process.status,
+                agentType: process.agentName,
+                agentModel: process.result?.agentModel || 'unknown',
+                response: process.result?.content || '',
+                error: process.result?.error || process.error,
+                usage: {
+                    tokensUsed: process.budget.tokensUsed,
+                    turnsUsed: process.budget.turnsUsed,
+                    maxTokens: process.budget.maxTokens,
+                    maxTurns: process.budget.maxTurns,
+                },
+                toolsUsed: process.result?.toolsUsed || [],
+                toolCallCount: process.result?.toolCallCount || 0,
+                budgetExceeded: process.result?.budgetExceeded || false,
+                durationMs: process.result?.durationMs,
+            };
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+            logger.error('spawn_task failed', err);
+            return {
+                success: false,
+                error: errorMessage,
+            };
+        }
+    }, {
+        actionType: ActionType.COMMAND_EXEC,
+        requiresApproval: false,
+        category: 'workflow',
+        tags: ['spawn', 'sub-agent', 'isolated', 'budget', 'background'],
+        displayName: 'Delegate',
+    });
+    // ============================================================
+    // POLL_TASK - Check on background task status
+    // ============================================================
+    registry.registerTool('poll_task', `Checks the status and retrieves results of a background agent process.
+
+By default, this tool **blocks until the process completes** and returns the final result.
+Set wait=false to check current status without blocking.
+
+Use this to:
+- Wait for a background task to finish and get its result (default behavior)
+- Check current progress of a running task without blocking (wait=false)`, {
+        type: 'object',
+        properties: {
+            process_id: {
+                type: 'string',
+                description: 'The processId returned from spawn_task',
+            },
+            wait: {
+                type: 'boolean',
+                description: 'If true (default), blocks until the process completes. If false, returns current status immediately.',
+            },
+        },
+        required: ['process_id'],
+    }, async (input, context) => {
+        const { getAgentSpawner } = await import('../services/agent-spawner.js');
+        const spawner = getAgentSpawner();
+        try {
+            const processId = input.process_id;
+            const shouldWait = input.wait !== false; // Default to true
+            let process = spawner.getProcess(processId);
+            if (!process) {
+                return {
+                    success: false,
+                    error: `Process ${processId} not found`,
+                };
+            }
+            // Wait for completion if requested and process is still running
+            if (shouldWait && !['completed', 'failed', 'cancelled', 'budget_exceeded'].includes(process.status)) {
+                // Redirect background agent's status messages to this poll_task's tool block
+                // so the user sees real-time activity while waiting
+                if (context.toolCallId) {
+                    spawner.redirectStatusTarget(processId, context.toolCallId);
+                }
+                process = await spawner.waitForCompletion(processId);
+            }
+            // Get output if background process
+            let output = '';
+            if (process.isBackground && process.outputFile) {
+                try {
+                    const pollResult = await spawner.pollOutput(processId);
+                    output = pollResult.output;
+                }
+                catch {
+                    // Ignore output read errors
+                }
+            }
+            return {
+                success: true,
+                processId: process.processId,
+                agentType: process.agentName,
+                status: process.status,
+                isComplete: ['completed', 'failed', 'cancelled', 'budget_exceeded'].includes(process.status),
+                task: process.task.slice(0, 200) + (process.task.length > 200 ? '...' : ''),
+                output: output || process.result?.content || '',
+                error: process.error || process.result?.error,
+                usage: {
+                    tokensUsed: process.budget.tokensUsed,
+                    turnsUsed: process.budget.turnsUsed,
+                    maxTokens: process.budget.maxTokens,
+                    maxTurns: process.budget.maxTurns,
+                },
+                budgetExceeded: process.result?.budgetExceeded || false,
+                startedAt: process.startedAt,
+                completedAt: process.completedAt,
+            };
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+            logger.error('poll_task failed', err);
+            return {
+                success: false,
+                error: errorMessage,
+            };
+        }
+    }, {
+        actionType: ActionType.FILE_READ, // Read-only operation
+        requiresApproval: false,
+        category: 'workflow',
+        tags: ['poll', 'status', 'background', 'check'],
+        displayName: 'Check Task',
+    });
+    // ============================================================
+    // LIST_TASKS - List all spawned agent processes
+    // ============================================================
+    registry.registerTool('list_tasks', `Lists all spawned agent processes and their current status.
+
+Use this to see:
+- Running background tasks
+- Completed tasks and their results
+- Tasks that failed or exceeded budget`, {
+        type: 'object',
+        properties: {
+            status: {
+                type: 'string',
+                enum: ['pending', 'running', 'paused', 'completed', 'failed', 'cancelled', 'budget_exceeded'],
+                description: 'Optional: filter by status',
+            },
+        },
+    }, async (input) => {
+        const { getAgentSpawner } = await import('../services/agent-spawner.js');
+        const spawner = getAgentSpawner();
+        try {
+            const filter = input.status ? { status: input.status } : undefined;
+            const processes = spawner.listProcesses(filter);
+            return {
+                success: true,
+                count: processes.length,
+                processes: processes.map((p) => ({
+                    processId: p.processId,
+                    agentType: p.agentName,
+                    status: p.status,
+                    task: p.task.slice(0, 100) + (p.task.length > 100 ? '...' : ''),
+                    isBackground: p.isBackground,
+                    tokensUsed: p.budget.tokensUsed,
+                    turnsUsed: p.budget.turnsUsed,
+                    startedAt: p.startedAt,
+                    completedAt: p.completedAt,
+                })),
+            };
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+            return {
+                success: false,
+                error: errorMessage,
+            };
+        }
+    }, {
+        actionType: ActionType.FILE_READ,
+        requiresApproval: false,
+        category: 'workflow',
+        tags: ['list', 'tasks', 'status'],
+        displayName: 'List Tasks',
+    });
+    // ============================================================
+    // CANCEL_TASK - Cancel a running task
+    // ============================================================
+    registry.registerTool('cancel_task', `Cancels a running or pending agent process.
+
+Use this to stop a background task that is no longer needed.`, {
+        type: 'object',
+        properties: {
+            process_id: {
+                type: 'string',
+                description: 'The processId of the task to cancel',
+            },
+        },
+        required: ['process_id'],
+    }, async (input) => {
+        const { getAgentSpawner } = await import('../services/agent-spawner.js');
+        const spawner = getAgentSpawner();
+        try {
+            const processId = input.process_id;
+            await spawner.cancel(processId);
+            return {
+                success: true,
+                processId,
+                message: `Process ${processId} has been cancelled`,
+            };
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+            return {
+                success: false,
+                error: errorMessage,
+            };
+        }
+    }, {
+        actionType: ActionType.COMMAND_EXEC,
+        requiresApproval: false,
+        category: 'workflow',
+        tags: ['cancel', 'stop', 'abort'],
+        displayName: 'Cancel Task',
+    });
+}
+//# sourceMappingURL=agent-tools.js.map

package/dist/tools/agent-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tools.js","sourceRoot":"","sources":["../../src/tools/agent-tools.ts"],"names":[],"mappings":"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"}

package/dist/tools/edit-replacers.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Edit Replacer Strategies
+ *
+ * Multiple fallback strategies for finding and replacing text in files.
+ * These handle various whitespace, indentation, and formatting differences
+ * that commonly occur when LLMs generate edit operations.
+ *
+ * Sourced from:
+ * - https://github.com/cline/cline/blob/main/evals/diff-edits/diff-apply/diff-06-23-25.ts
+ * - https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/utils/editCorrector.ts
+ * - https://github.com/cline/cline/blob/main/evals/diff-edits/diff-apply/diff-06-26-25.ts
+ */
+/**
+ * A replacer is a generator that yields potential matches for a search string.
+ * Each yielded string is an exact substring of the content that should be replaced.
+ */
+export type Replacer = (content: string, find: string) => Generator<string, void, unknown>;
+/**
+ * Strategy 1: Simple exact match
+ * The most basic strategy - just returns the find string if it exists in content
+ */
+export declare const SimpleReplacer: Replacer;
+/**
+ * Strategy 2: Line-trimmed matching
+ * Trims each line individually and compares trimmed versions.
+ * Handles cases where file has different trailing/leading spaces per line.
+ */
+export declare const LineTrimmedReplacer: Replacer;
+/**
+ * Strategy 3: Block anchor matching with fuzzy middle content
+ * Uses first and last lines as "anchors" and applies Levenshtein distance
+ * for fuzzy matching of the middle content.
+ */
+export declare const BlockAnchorReplacer: Replacer;
+/**
+ * Strategy 4: Whitespace normalized matching
+ * Collapses all whitespace (spaces, tabs, newlines) to single spaces.
+ * Handles internal whitespace differences like "foo  bar" vs "foo bar".
+ */
+export declare const WhitespaceNormalizedReplacer: Replacer;
+/**
+ * Strategy 5: Indentation flexible matching
+ * Removes the minimum indentation from all lines before comparing.
+ * Handles cases where the LLM generated code with different base indentation.
+ */
+export declare const IndentationFlexibleReplacer: Replacer;
+/**
+ * Strategy 6: Escape sequence normalized matching
+ * Handles escape sequences that LLMs sometimes output differently.
+ * Supports: \n, \t, \r, \', \", \`, \\, \$
+ */
+export declare const EscapeNormalizedReplacer: Replacer;
+/**
+ * Strategy 7: Trimmed boundary matching
+ * Trims leading and trailing whitespace from the entire search string.
+ * Handles cases where the LLM added extra newlines or spaces at boundaries.
+ */
+export declare const TrimmedBoundaryReplacer: Replacer;
+/**
+ * Strategy 8: Context-aware matching
+ * Uses first and last lines as context anchors with a 50% similarity threshold.
+ * More lenient than BlockAnchorReplacer for middle content.
+ */
+export declare const ContextAwareReplacer: Replacer;
+/**
+ * Strategy 9: Multi-occurrence matching
+ * Yields all exact matches, allowing the replace function to handle
+ * multiple occurrences based on replaceAll parameter.
+ */
+export declare const MultiOccurrenceReplacer: Replacer;
+/**
+ * All replacers in order of strictness (most strict to most lenient).
+ * The replace function tries each in sequence until one succeeds.
+ */
+export declare const REPLACERS: Replacer[];
+/**
+ * Result of a replace operation with metadata about which strategy succeeded.
+ */
+export interface ReplaceResult {
+    content: string;
+    strategy: string;
+    matchedText: string;
+}
+export declare function replaceWithStrategies(content: string, oldString: string, newString: string, replaceAll?: boolean): ReplaceResult;
+/**
+ * Simple replace function (compatible with existing API).
+ * Returns just the modified content string.
+ */
+export declare function replace(content: string, oldString: string, newString: string, replaceAll?: boolean): string;
+//# sourceMappingURL=edit-replacers.d.ts.map

package/dist/tools/edit-replacers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-replacers.d.ts","sourceRoot":"","sources":["../../src/tools/edit-replacers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AA+B3F;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,QAE5B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAuCjC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAuIjC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,QA0C1C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,QA0BzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,QA+CtC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAwBrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAwDlC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAUrC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,QAAQ,EAU/B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAoCD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,UAAQ,GACjB,aAAa,CAgGf;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,UAAQ,GACjB,MAAM,CAER"}