@compilr-dev/agents 0.2.1 → 0.3.1

package/dist/agent.d.ts

@@ -35,10 +35,18 @@ export type AgentEvent = {
     type: 'tool_start';
     name: string;
     input: Record<string, unknown>;
+    toolUseId: string;
+} | {
+    type: 'tool_output';
+    toolUseId: string;
+    toolName: string;
+    output: string;
+    stream?: 'stdout' | 'stderr';
 } | {
     type: 'tool_end';
     name: string;
     result: ToolExecutionResult;
+    toolUseId: string;
 } | {
     type: 'iteration_end';
     iteration: number;
@@ -1449,6 +1457,9 @@ export declare class Agent {
     /**
      * Generate a summary of messages using the LLM provider.
      * Used for context summarization when approaching limits.
+     *
+     * If anchors are configured, the summary will prioritize keeping
+     * information related to anchor content (anchor-weighted summarization).
      */
     private generateSummary;
     /**

package/dist/agent.js

@@ -1621,13 +1621,34 @@ export class Agent {
             messages.push(assistantMsg);
             newMessages.push(assistantMsg);
             // Execute tools and add results
-            for (const toolUse of toolUses) {
-                // Check for abort before each tool
+            // Check if we can parallelize - only parallelize tools marked as parallel-safe
+            const parallelTools = toolUses.filter((tu) => {
+                const tool = this.toolRegistry.get(tu.name);
+                return tool?.parallel === true;
+            });
+            const canParallelize = parallelTools.length > 1 && parallelTools.length === toolUses.length;
+            // Helper to execute a single tool with all checks
+            const executeSingleTool = async (toolUse) => {
+                // Check for abort
                 if (signal?.aborted) {
-                    aborted = true;
-                    break;
+                    return {
+                        result: { success: false, error: 'Aborted' },
+                        toolResultMsg: {
+                            role: 'user',
+                            content: [
+                                { type: 'tool_result', toolUseId: toolUse.id, content: 'Aborted', isError: true },
+                            ],
+                        },
+                        skipped: true,
+                        aborted: true,
+                    };
                 }
-                emit({ type: 'tool_start', name: toolUse.name, input: toolUse.input });
+                emit({
+                    type: 'tool_start',
+                    name: toolUse.name,
+                    input: toolUse.input,
+                    toolUseId: toolUse.id,
+                });
                 let result;
                 // Check permissions before execution
                 if (this.permissionManager) {
@@ -1646,27 +1667,23 @@ export class Agent {
                             success: false,
                             error: `Permission denied: ${permResult.reason ?? 'Tool execution not allowed'}`,
                         };
-                        // Emit tool_end and record the tool call
-                        emit({ type: 'tool_end', name: toolUse.name, result });
-                        const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
-                        toolCalls.push(toolCallEntry);
-                        iterationToolCalls.push(toolCallEntry);
-                        // CRITICAL: Add tool_result message to messages array
-                        // Claude API requires every tool_use to have a corresponding tool_result
-                        const toolResultMsg = {
-                            role: 'user',
-                            content: [
-                                {
-                                    type: 'tool_result',
-                                    toolUseId: toolUse.id,
-                                    content: `Error: ${result.error ?? 'Permission denied'}`,
-                                    isError: true,
-                                },
-                            ],
+                        emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
+                        return {
+                            result,
+                            toolResultMsg: {
+                                role: 'user',
+                                content: [
+                                    {
+                                        type: 'tool_result',
+                                        toolUseId: toolUse.id,
+                                        content: `Error: ${result.error ?? 'Permission denied'}`,
+                                        isError: true,
+                                    },
+                                ],
+                            },
+                            skipped: true,
+                            aborted: false,
                         };
-                        messages.push(toolResultMsg);
-                        newMessages.push(toolResultMsg);
-                        continue;
                     }
                     emit({ type: 'permission_granted', toolName: toolUse.name, level: permResult.level });
                 }
@@ -1676,37 +1693,31 @@ export class Agent {
                     if (guardrailResult.triggered) {
                         emit({ type: 'guardrail_triggered', result: guardrailResult });
                         if (!proceed) {
-                            // Guardrail blocked the execution
                             const message = guardrailResult.guardrail?.message ?? 'Operation blocked by guardrail';
                             emit({ type: 'guardrail_blocked', result: guardrailResult, message });
                             result = {
                                 success: false,
                                 error: `Guardrail blocked: ${message}`,
                             };
-                            // Emit tool_end and record the tool call
-                            emit({ type: 'tool_end', name: toolUse.name, result });
-                            const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
-                            toolCalls.push(toolCallEntry);
-                            iterationToolCalls.push(toolCallEntry);
-                            // CRITICAL: Add tool_result message to messages array
-                            // Claude API requires every tool_use to have a corresponding tool_result
-                            const toolResultMsg = {
-                                role: 'user',
-                                content: [
-                                    {
-                                        type: 'tool_result',
-                                        toolUseId: toolUse.id,
-                                        content: `Error: ${result.error ?? 'Blocked by guardrail'}`,
-                                        isError: true,
-                                    },
-                                ],
+                            emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
+                            return {
+                                result,
+                                toolResultMsg: {
+                                    role: 'user',
+                                    content: [
+                                        {
+                                            type: 'tool_result',
+                                            toolUseId: toolUse.id,
+                                            content: `Error: ${result.error ?? 'Blocked by guardrail'}`,
+                                            isError: true,
+                                        },
+                                    ],
+                                },
+                                skipped: true,
+                                aborted: false,
                             };
-                            messages.push(toolResultMsg);
-                            newMessages.push(toolResultMsg);
-                            continue;
                         }
                         else if (guardrailResult.action === 'warn') {
-                            // Log warning and continue
                             const message = guardrailResult.guardrail?.message ?? 'Warning from guardrail';
                             emit({ type: 'guardrail_warning', result: guardrailResult, message });
                         }
@@ -1722,20 +1733,45 @@ export class Agent {
                     });
                     if (!beforeToolResult.proceed) {
                         result = beforeToolResult.skipResult ?? { success: false, error: 'Skipped by hook' };
-                        emit({ type: 'tool_end', name: toolUse.name, result });
-                        const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
-                        toolCalls.push(toolCallEntry);
-                        iterationToolCalls.push(toolCallEntry);
-                        continue;
+                        emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
+                        return {
+                            result,
+                            toolResultMsg: {
+                                role: 'user',
+                                content: [
+                                    {
+                                        type: 'tool_result',
+                                        toolUseId: toolUse.id,
+                                        content: result.success
+                                            ? JSON.stringify(result.result)
+                                            : `Error: ${result.error ?? 'Unknown error'}`,
+                                        isError: !result.success,
+                                    },
+                                ],
+                            },
+                            skipped: true,
+                            aborted: false,
+                        };
                     }
                     toolInput = beforeToolResult.input;
                 }
                 const toolStartTime = Date.now();
                 try {
-                    result = await this.toolRegistry.execute(toolUse.name, toolInput);
+                    const toolContext = {
+                        toolUseId: toolUse.id,
+                        onOutput: (output, stream) => {
+                            emit({
+                                type: 'tool_output',
+                                toolUseId: toolUse.id,
+                                toolName: toolUse.name,
+                                output,
+                                stream,
+                            });
+                        },
+                    };
+                    result = await this.toolRegistry.execute(toolUse.name, toolInput, toolContext);
                 }
                 catch (error) {
-                    // Run onError hooks for tool errors (thrown exceptions)
                     if (this.hooksManager && error instanceof Error) {
                         const errorResult = await this.hooksManager.runOnError({
                             ...hookContext,
@@ -1760,8 +1796,7 @@ export class Agent {
                         };
                     }
                 }
-                // Run onError hooks for failed tool results (not thrown, but returned errors)
-                // The tool registry catches errors internally and returns { success: false }
+                // Run onError hooks for failed tool results
                 if (this.hooksManager && !result.success) {
                     const syntheticError = new Error(result.error);
                     const errorResult = await this.hooksManager.runOnError({
@@ -1784,89 +1819,116 @@ export class Agent {
                         durationMs: Date.now() - toolStartTime,
                     });
                 }
-                emit({ type: 'tool_end', name: toolUse.name, result });
-                // Tool loop detection: check for consecutive identical calls
-                if (this.maxConsecutiveToolCalls > 0) {
-                    const currentHash = hashToolCall(toolUse.name, toolUse.input);
-                    if (currentHash === lastToolCallHash) {
-                        consecutiveIdenticalCalls++;
-                        if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
-                            throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
-                        }
-                        // Emit warning before throwing
-                        emit({
-                            type: 'tool_loop_warning',
-                            toolName: toolUse.name,
-                            consecutiveCalls: consecutiveIdenticalCalls,
-                        });
-                    }
-                    else {
-                        // Different tool call, reset counter
-                        lastToolCallHash = currentHash;
-                        consecutiveIdenticalCalls = 1;
-                    }
-                }
-                const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
-                toolCalls.push(toolCallEntry);
-                iterationToolCalls.push(toolCallEntry);
+                emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
                 // Build tool result content
                 let toolResultContent = result.success
                     ? JSON.stringify(result.result)
                     : `Error: ${result.error ?? 'Unknown error'}`;
-                // Context management: pre-flight check and filtering for tool results
-                if (this.contextManager && this.autoContextManagement) {
+                // Context management (only for sequential - parallel handles this after)
+                if (!canParallelize && this.contextManager && this.autoContextManagement) {
                     const estimatedTokens = this.contextManager.estimateTokens(toolResultContent);
                     const preflight = this.contextManager.canAddContent(estimatedTokens, 'toolResults');
                     if (!preflight.allowed) {
                         if (preflight.action === 'reject') {
-                            // Content too large - filter it
                             const filtered = this.contextManager.filterContent(toolResultContent, 'tool_result');
                             toolResultContent = filtered.content;
                         }
-                        else if (preflight.action === 'compact') {
-                            // Category budget exceeded - compact the category first
-                            const tokensBefore = this.contextManager.getTokenCount();
-                            const compactResult = await this.contextManager.compactCategory(messages, 'toolResults', (content, index) => Promise.resolve(`[compacted_tool_result_${String(index)}]`));
-                            messages = compactResult.messages;
-                            // Inject restoration hints after compaction
-                            this.injectRestorationHints(messages);
+                        // Note: compact/summarize actions are complex with parallel execution
+                        // For now, only filter is applied during parallel; full context mgmt happens after
+                    }
+                    const finalTokens = this.contextManager.estimateTokens(toolResultContent);
+                    this.contextManager.addToCategory('toolResults', finalTokens);
+                }
+                return {
+                    result,
+                    toolResultMsg: {
+                        role: 'user',
+                        content: [
+                            {
+                                type: 'tool_result',
+                                toolUseId: toolUse.id,
+                                content: toolResultContent,
+                                isError: !result.success,
+                            },
+                        ],
+                    },
+                    skipped: false,
+                    aborted: false,
+                };
+            };
+            // Execute tools - parallel if all are parallel-safe, otherwise sequential
+            if (canParallelize) {
+                // Parallel execution
+                const results = await Promise.all(toolUses.map((tu) => executeSingleTool(tu)));
+                for (let i = 0; i < toolUses.length; i++) {
+                    const toolUse = toolUses[i];
+                    const { result, toolResultMsg, aborted: wasAborted } = results[i];
+                    if (wasAborted) {
+                        aborted = true;
+                        break;
+                    }
+                    // Tool loop detection (still applies per-tool)
+                    if (this.maxConsecutiveToolCalls > 0) {
+                        const currentHash = hashToolCall(toolUse.name, toolUse.input);
+                        if (currentHash === lastToolCallHash) {
+                            consecutiveIdenticalCalls++;
+                            if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
+                                throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+                            }
                             emit({
-                                type: 'context_compacted',
-                                tokensBefore,
-                                tokensAfter: this.contextManager.getTokenCount(),
+                                type: 'tool_loop_warning',
+                                toolName: toolUse.name,
+                                consecutiveCalls: consecutiveIdenticalCalls,
                             });
                         }
-                        else if (preflight.action === 'summarize') {
-                            // Approaching context limit - summarize
-                            const { messages: summarized, result: sumResult } = await this.contextManager.summarizeWithRetry(messages, (msgs) => this.generateSummary(msgs));
-                            messages = summarized;
-                            // Inject restoration hints after summarization
-                            this.injectRestorationHints(messages);
+                        else {
+                            lastToolCallHash = currentHash;
+                            consecutiveIdenticalCalls = 1;
+                        }
+                    }
+                    const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
+                    toolCalls.push(toolCallEntry);
+                    iterationToolCalls.push(toolCallEntry);
+                    messages.push(toolResultMsg);
+                    newMessages.push(toolResultMsg);
+                }
+            }
+            else {
+                // Sequential execution (original loop, but using the helper)
+                for (const toolUse of toolUses) {
+                    const { result, toolResultMsg, skipped, aborted: wasAborted, } = await executeSingleTool(toolUse);
+                    if (wasAborted) {
+                        aborted = true;
+                        break;
+                    }
+                    // Tool loop detection
+                    if (this.maxConsecutiveToolCalls > 0) {
+                        const currentHash = hashToolCall(toolUse.name, toolUse.input);
+                        if (currentHash === lastToolCallHash) {
+                            consecutiveIdenticalCalls++;
+                            if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
+                                throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+                            }
                             emit({
-                                type: 'context_summarized',
-                                tokensBefore: sumResult.originalTokens,
-                                tokensAfter: sumResult.summaryTokens,
-                                rounds: sumResult.rounds,
+                                type: 'tool_loop_warning',
+                                toolName: toolUse.name,
+                                consecutiveCalls: consecutiveIdenticalCalls,
                             });
                         }
+                        else {
+                            lastToolCallHash = currentHash;
+                            consecutiveIdenticalCalls = 1;
+                        }
+                    }
+                    const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
+                    toolCalls.push(toolCallEntry);
+                    iterationToolCalls.push(toolCallEntry);
+                    messages.push(toolResultMsg);
+                    newMessages.push(toolResultMsg);
+                    if (skipped) {
+                        continue;
                     }
-                    // Track tool result tokens
-                    const finalTokens = this.contextManager.estimateTokens(toolResultContent);
-                    this.contextManager.addToCategory('toolResults', finalTokens);
                 }
-                const toolResultMsg = {
-                    role: 'user',
-                    content: [
-                        {
-                            type: 'tool_result',
-                            toolUseId: toolUse.id,
-                            content: toolResultContent,
-                            isError: !result.success,
-                        },
-                    ],
-                };
-                messages.push(toolResultMsg);
-                newMessages.push(toolResultMsg);
             }
             if (aborted) {
                 break;
@@ -1904,7 +1966,11 @@ export class Agent {
                         addedIterations: result,
                     });
                 }
-                // If false or 0, loop will exit naturally on next condition check
+                else {
+                    // User chose to stop - set aborted to prevent error throw
+                    aborted = true;
+                    emit({ type: 'done', response: finalResponse });
+                }
             }
         }
         // Check if we hit max iterations without completing
@@ -2083,14 +2149,36 @@ export class Agent {
     /**
      * Generate a summary of messages using the LLM provider.
      * Used for context summarization when approaching limits.
+     *
+     * If anchors are configured, the summary will prioritize keeping
+     * information related to anchor content (anchor-weighted summarization).
      */
     async generateSummary(messages) {
+        // Build anchor context if available (for weighted summarization)
+        let anchorContext = '';
+        if (this.anchorManager && this.anchorManager.size > 0) {
+            const anchors = this.anchorManager.getAll();
+            if (anchors.length > 0) {
+                const anchorItems = anchors.map((a) => `- [${a.priority}] ${a.content}`).join('\n');
+                anchorContext = `
+## PRIORITY CONTEXT (Anchors)
+
+The following are critical anchors that should be preserved in context. When summarizing,
+PRIORITIZE keeping information that relates to these anchors:
+
+${anchorItems}
+
+Ensure the summary captures any conversation details related to these anchors.
+`;
+            }
+        }
         const summaryPrompt = `Please provide a concise summary of the following conversation. Focus on:
 1. Key decisions made
 2. Important context established
 3. Tasks completed or in progress
 4. Any relevant file paths or code snippets mentioned
-
+${anchorContext ? '5. Information related to the priority anchors listed below' : ''}
+${anchorContext}
 Keep the summary under 500 words.
 
 Conversation to summarize:

package/dist/anchors/manager.d.ts

@@ -66,6 +66,40 @@ export declare class AnchorManager {
      * Clear anchors based on criteria
      */
     clear(options?: AnchorClearOptions): number;
+    /**
+     * Get all anchors for a specific project
+     *
+     * @param projectId - The project ID to filter by
+     * @param options - Additional query options (priority, scope, tags)
+     */
+    getByProject(projectId: string, options?: Omit<AnchorQueryOptions, 'projectId' | 'globalOnly'>): Anchor[];
+    /**
+     * Get all global anchors (those without a projectId)
+     *
+     * @param options - Additional query options (priority, scope, tags)
+     */
+    getGlobal(options?: Omit<AnchorQueryOptions, 'projectId' | 'globalOnly'>): Anchor[];
+    /**
+     * Clear all anchors for a specific project
+     *
+     * @param projectId - The project ID
+     * @returns Number of anchors removed
+     */
+    clearByProject(projectId: string): number;
+    /**
+     * Get list of unique project IDs that have anchors
+     */
+    getProjectIds(): string[];
+    /**
+     * Check if a project has any anchors
+     */
+    hasProjectAnchors(projectId: string): boolean;
+    /**
+     * Get anchor counts grouped by project
+     *
+     * @returns Map where keys are project IDs (null for global) and values are counts
+     */
+    getProjectStats(): Map<string | null, number>;
     /**
      * Get the current number of anchors
      */

package/dist/anchors/manager.js

@@ -104,6 +104,7 @@ export class AnchorManager {
             expiresAt: input.expiresAt,
             tags: input.tags,
             metadata: input.metadata,
+            projectId: input.projectId,
         };
         // Store the anchor
         this.anchors.set(anchor.id, anchor);
@@ -149,6 +150,14 @@ export class AnchorManager {
                 return tagsFilter.every((tag) => anchorTags.includes(tag));
             });
         }
+        // Filter by project ID
+        if (options?.projectId) {
+            anchors = anchors.filter((a) => a.projectId === options.projectId);
+        }
+        // Filter to global only (no projectId)
+        if (options?.globalOnly) {
+            anchors = anchors.filter((a) => !a.projectId);
+        }
         // Filter out expired unless requested
         if (!options?.includeExpired) {
             anchors = anchors.filter((a) => !this.isExpired(a));
@@ -204,6 +213,14 @@ export class AnchorManager {
             if (options?.expiredOnly && !this.isExpired(anchor)) {
                 continue;
             }
+            // Filter by project ID
+            if (options?.projectId && anchor.projectId !== options.projectId) {
+                continue;
+            }
+            // Filter to global only (no projectId)
+            if (options?.globalOnly && anchor.projectId) {
+                continue;
+            }
             toRemove.push(id);
         }
         for (const id of toRemove) {
@@ -212,6 +229,74 @@ export class AnchorManager {
         }
         return removed;
     }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Project-scoped methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Get all anchors for a specific project
+     *
+     * @param projectId - The project ID to filter by
+     * @param options - Additional query options (priority, scope, tags)
+     */
+    getByProject(projectId, options) {
+        return this.getAll({ ...options, projectId });
+    }
+    /**
+     * Get all global anchors (those without a projectId)
+     *
+     * @param options - Additional query options (priority, scope, tags)
+     */
+    getGlobal(options) {
+        return this.getAll({ ...options, globalOnly: true });
+    }
+    /**
+     * Clear all anchors for a specific project
+     *
+     * @param projectId - The project ID
+     * @returns Number of anchors removed
+     */
+    clearByProject(projectId) {
+        return this.clear({ projectId });
+    }
+    /**
+     * Get list of unique project IDs that have anchors
+     */
+    getProjectIds() {
+        const projectIds = new Set();
+        for (const anchor of this.anchors.values()) {
+            if (anchor.projectId && !this.isExpired(anchor)) {
+                projectIds.add(anchor.projectId);
+            }
+        }
+        return Array.from(projectIds);
+    }
+    /**
+     * Check if a project has any anchors
+     */
+    hasProjectAnchors(projectId) {
+        for (const anchor of this.anchors.values()) {
+            if (anchor.projectId === projectId && !this.isExpired(anchor)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Get anchor counts grouped by project
+     *
+     * @returns Map where keys are project IDs (null for global) and values are counts
+     */
+    getProjectStats() {
+        const stats = new Map();
+        for (const anchor of this.anchors.values()) {
+            if (this.isExpired(anchor))
+                continue;
+            const key = anchor.projectId ?? null;
+            stats.set(key, (stats.get(key) ?? 0) + 1);
+        }
+        return stats;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
     /**
      * Get the current number of anchors
      */
@@ -391,6 +476,7 @@ export class AnchorManager {
                 expiresAt: a.expiresAt?.toISOString(),
                 tags: a.tags,
                 metadata: a.metadata,
+                projectId: a.projectId,
             }));
             fs.writeFileSync(expandedPath, JSON.stringify(serialized, null, 2));
             this.emit('anchor:persisted', undefined, `Saved ${String(serialized.length)} persistent anchors`);