@ebowwa/coder 0.2.1 → 0.7.64

package/packages/src/core/agent-loop/index.ts

@@ -0,0 +1,135 @@
+/**
+ * Agent Loop - Turn-based processing system
+ *
+ * This is the main orchestrator that coordinates:
+ * - State management (loop-state.ts)
+ * - Turn execution (turn-executor.ts)
+ * - Tool execution (tool-executor.ts)
+ * - Context compaction (compaction.ts)
+ * - Message building (message-builder.ts)
+ * - Formatting utilities (formatters.ts)
+ */
+
+import type { Message } from "../../types/index.js";
+import { DEFAULT_CACHE_CONFIG } from "../../types/index.js";
+import { PermissionManager } from "../permissions.js";
+import { DEFAULT_REMINDER_CONFIG } from "../system-reminders.js";
+import type { HookManager } from "../../ecosystem/hooks/index.js";
+
+import type { AgentLoopOptions, AgentLoopResult } from "./types.js";
+import { LoopState } from "./loop-state.js";
+import { executeTurn, type TurnExecutorOptions } from "./turn-executor.js";
+
+// Re-export types and utilities
+export type { AgentLoopOptions, AgentLoopResult } from "./types.js";
+export { formatCost, formatMetrics, formatCostBrief, formatCacheMetrics } from "./formatters.js";
+export { LoopState } from "./loop-state.js";
+export { executeTurn } from "./turn-executor.js";
+export { executeTools, type ToolExecutionOptions } from "./tool-executor.js";
+export { buildAPIMessages, injectReminderIntoContent } from "./message-builder.js";
+export {
+  handleProactiveCompaction,
+  handleReactiveCompaction,
+  needsCompaction,
+  estimateMessagesTokens,
+  DEFAULT_PROACTIVE_OPTIONS,
+  DEFAULT_REACTIVE_OPTIONS,
+} from "./compaction.js";
+
+/**
+ * Main agent loop - processes messages in turns until completion
+ */
+export async function agentLoop(
+  initialMessages: Message[],
+  options: AgentLoopOptions
+): Promise<AgentLoopResult> {
+  const {
+    apiKey,
+    model = "claude-sonnet-4-6",
+    maxTokens = 4096,
+    systemPrompt,
+    tools,
+    permissionMode,
+    workingDirectory,
+    gitStatus = null,
+    reminderConfig,
+    cacheConfig = DEFAULT_CACHE_CONFIG,
+    thinking,
+    extendedThinking,
+    hookManager,
+    sessionId,
+    onText,
+    onThinking,
+    onToolUse,
+    onToolResult,
+    onMetrics,
+    onReminder,
+    onPermissionRequest,
+    signal,
+  } = options;
+
+  // Initialize state
+  const state = new LoopState(initialMessages);
+  const permissionManager = new PermissionManager(permissionMode, onPermissionRequest);
+  const mergedReminderConfig = { ...DEFAULT_REMINDER_CONFIG, ...reminderConfig };
+
+  // Execute SessionStart hook
+  if (hookManager) {
+    await hookManager.execute("SessionStart", {
+      session_id: sessionId,
+    });
+  }
+
+  let shouldContinue = true;
+
+  while (shouldContinue) {
+    if (signal?.aborted) {
+      break;
+    }
+
+    // Build turn executor options
+    const turnOptions: TurnExecutorOptions = {
+      apiKey,
+      model,
+      maxTokens,
+      systemPrompt,
+      tools,
+      cacheConfig,
+      thinking,
+      extendedThinking,
+      workingDirectory,
+      gitStatus,
+      reminderConfig: mergedReminderConfig,
+      hookManager,
+      sessionId,
+      signal,
+      onText,
+      onThinking,
+      onToolUse,
+      onReminder,
+      permissionMode,
+      permissionManager,
+      onMetrics,
+      onToolResult,
+    };
+
+    // Execute a single turn
+    const turnResult = await executeTurn(state, turnOptions);
+
+    shouldContinue = turnResult.shouldContinue;
+
+    // Call onMetrics callback with the latest metrics
+    if (turnResult.metrics && onMetrics) {
+      onMetrics(turnResult.metrics);
+    }
+  }
+
+  // Execute SessionEnd hook
+  if (hookManager) {
+    await hookManager.execute("SessionEnd", {
+      session_id: sessionId,
+    });
+  }
+
+  return state.toResult();
+}

package/packages/src/core/agent-loop/loop-state.ts

@@ -0,0 +1,187 @@
+/**
+ * Loop State - Mutable state management for the agent loop
+ */
+
+import type {
+  Message,
+  ToolUseBlock,
+  QueryMetrics,
+  CacheMetrics,
+  UsageMetrics,
+} from "../../types/index.js";
+import type { CompactionResult, getCompactionStats } from "../context-compaction.js";
+
+/**
+ * Creates an initial cache metrics object
+ */
+export function createInitialCacheMetrics(): CacheMetrics {
+  return {
+    cacheHits: 0,
+    cacheMisses: 0,
+    totalCacheReadTokens: 0,
+    totalCacheWriteTokens: 0,
+    cacheHitRate: 0,
+    estimatedSavingsUSD: 0,
+  };
+}
+
+/**
+ * LoopState class encapsulates all mutable state during the agent loop
+ */
+export class LoopState {
+  messages: Message[];
+  metrics: QueryMetrics[] = [];
+  allToolsUsed: ToolUseBlock[] = [];
+  totalCost = 0;
+  totalDuration = 0;
+  turnNumber = 0;
+  previousCost = 0;
+  compactionCount = 0;
+  totalTokensCompacted = 0;
+  cacheMetrics: CacheMetrics;
+
+  constructor(initialMessages: Message[]) {
+    this.messages = [...initialMessages];
+    this.cacheMetrics = createInitialCacheMetrics();
+  }
+
+  /**
+   * Get the latest metrics entry
+   */
+  get latestMetrics(): QueryMetrics | undefined {
+    return this.metrics[this.metrics.length - 1];
+  }
+
+  /**
+   * Get usage for reminder building (with fallback)
+   */
+  get currentUsage(): UsageMetrics {
+    return this.latestMetrics?.usage ?? {
+      input_tokens: 0,
+      output_tokens: 0,
+    };
+  }
+
+  /**
+   * Add a turn's results to the state
+   */
+  addTurnResult(result: {
+    message: { content: unknown[]; stop_reason: string | null; id: string };
+    usage: UsageMetrics;
+    cacheMetrics?: CacheMetrics;
+    costUSD: number;
+    durationMs: number;
+    model: string;
+    messageCount: number;
+  }): QueryMetrics {
+    const queryMetrics: QueryMetrics = {
+      model: result.model,
+      messageCount: result.messageCount,
+      messageTokens: result.usage.input_tokens + result.usage.output_tokens,
+      usage: result.usage,
+      cacheMetrics: result.cacheMetrics,
+      durationMs: result.durationMs,
+      ttftMs: 0, // Will be set by caller if available
+      costUSD: result.costUSD,
+      stopReason: result.message.stop_reason as import("../../types/index.js").StopReason,
+      requestId: result.message.id,
+    };
+
+    this.metrics.push(queryMetrics);
+    this.previousCost = this.totalCost;
+    this.totalCost += result.costUSD;
+    this.totalDuration += result.durationMs;
+
+    // Aggregate cache metrics
+    if (result.cacheMetrics) {
+      this.cacheMetrics.cacheHits += result.cacheMetrics.cacheHits;
+      this.cacheMetrics.cacheMisses += result.cacheMetrics.cacheMisses;
+      this.cacheMetrics.totalCacheReadTokens += result.cacheMetrics.totalCacheReadTokens;
+      this.cacheMetrics.totalCacheWriteTokens += result.cacheMetrics.totalCacheWriteTokens;
+      this.cacheMetrics.estimatedSavingsUSD += result.cacheMetrics.estimatedSavingsUSD;
+    }
+
+    // Update cache hit rate
+    const totalCacheOps = this.cacheMetrics.cacheHits + this.cacheMetrics.cacheMisses;
+    this.cacheMetrics.cacheHitRate = totalCacheOps > 0
+      ? this.cacheMetrics.cacheHits / totalCacheOps
+      : 0;
+
+    return queryMetrics;
+  }
+
+  /**
+   * Add assistant message to history
+   */
+  addAssistantMessage(content: unknown[]): void {
+    this.messages.push({
+      role: "assistant",
+      content: content as import("../../types/index.js").ContentBlock[],
+    });
+  }
+
+  /**
+   * Add user message (tool results) to history
+   */
+  addUserMessage(content: import("../../types/index.js").ToolResultBlock[]): void {
+    this.messages.push({
+      role: "user",
+      content,
+    });
+  }
+
+  /**
+   * Track tool usage
+   */
+  trackToolUse(toolUseBlocks: ToolUseBlock[]): void {
+    this.allToolsUsed.push(...toolUseBlocks);
+  }
+
+  /**
+   * Apply compaction result to state
+   */
+  applyCompaction(
+    compactionResult: CompactionResult,
+    getStats: typeof getCompactionStats
+  ): boolean {
+    // Only apply compaction if it actually saved tokens
+    if (!compactionResult.didCompact || compactionResult.tokensAfter >= compactionResult.tokensBefore) {
+      return false;
+    }
+
+    // Replace messages array content
+    this.messages.length = 0;
+    this.messages.push(...compactionResult.messages);
+
+    this.compactionCount++;
+    const tokensSaved = compactionResult.tokensBefore - compactionResult.tokensAfter;
+    this.totalTokensCompacted += tokensSaved;
+
+    const stats = getStats(compactionResult);
+    console.log(`Context compacted: ${stats.reductionPercent}% reduction, ${stats.tokensSaved} tokens saved`);
+
+    return true;
+  }
+
+  /**
+   * Increment turn counter
+   */
+  incrementTurn(): number {
+    return ++this.turnNumber;
+  }
+
+  /**
+   * Convert to AgentLoopResult
+   */
+  toResult(): import("./types.js").AgentLoopResult {
+    return {
+      messages: this.messages,
+      metrics: this.metrics,
+      totalCost: this.totalCost,
+      totalDuration: this.totalDuration,
+      totalCacheMetrics: this.cacheMetrics,
+      compactionCount: this.compactionCount,
+      totalTokensCompacted: this.totalTokensCompacted,
+    };
+  }
+}

package/packages/src/core/agent-loop/message-builder.ts

@@ -0,0 +1,62 @@
+/**
+ * Message Builder - API message construction with reminder injection
+ */
+
+import type { Message, ContentBlock, TextBlock } from "../../types/index.js";
+
+/**
+ * Build API messages with system reminders injected
+ */
+export function buildAPIMessages(
+  messages: Message[],
+  systemPrompt: string,
+  systemReminder?: string
+): Message[] {
+  // If we have a system reminder, inject it into the last user message
+  if (systemReminder && messages.length > 0) {
+    const result = [...messages];
+    // Find the last user message
+    for (let i = result.length - 1; i >= 0; i--) {
+      const msg = result[i];
+      if (msg && msg.role === "user") {
+        // Clone the message to avoid mutating original
+        const updatedMessage: Message = {
+          role: "user",
+          content: Array.isArray(msg.content)
+            ? injectReminderIntoContent(msg.content, systemReminder)
+            : [{ type: "text" as const, text: `${String(msg.content)}\n\n${systemReminder}` }],
+        };
+        result[i] = updatedMessage;
+        break;
+      }
+    }
+    return result;
+  }
+
+  return messages;
+}
+
+/**
+ * Inject system reminder into content blocks
+ */
+export function injectReminderIntoContent(
+  content: ContentBlock[],
+  reminder: string
+): ContentBlock[] {
+  // Check if the last block is a text block we can append to
+  if (content.length > 0) {
+    const lastBlock = content[content.length - 1];
+    if (lastBlock && lastBlock.type === "text") {
+      // Append to existing text block
+      const textBlock: TextBlock = {
+        type: "text",
+        text: `${lastBlock.text}\n\n${reminder}`,
+      };
+      return [...content.slice(0, -1), textBlock];
+    }
+  }
+
+  // Add as new text block
+  const newBlock: TextBlock = { type: "text", text: `\n\n${reminder}` };
+  return [...content, newBlock];
+}

package/packages/src/core/agent-loop/tool-executor.ts

@@ -0,0 +1,211 @@
+/**
+ * Tool Executor - Parallel tool execution with hooks and permissions
+ */
+
+import type {
+  ToolDefinition,
+  ToolUseBlock,
+  ToolResultBlock,
+  ToolResult,
+  PermissionMode,
+} from "../../types/index.js";
+import type { PermissionManager, PermissionResult } from "../permissions.js";
+import type { HookManager } from "../../ecosystem/hooks/index.js";
+export interface ToolExecutionOptions {
+  tools: ToolDefinition[];
+  workingDirectory: string;
+  permissionMode: PermissionMode;
+  hookManager?: HookManager;
+  sessionId?: string;
+  signal?: AbortSignal;
+  permissionManager: import("../permissions.js").PermissionManager;
+  onToolResult?: (result: { id: string; result: ToolResult }) => void;
+}
+
+/**
+ * Internal result of a single tool execution
+ */
+interface ToolExecutionResult {
+  toolUseId: string;
+  result: ToolResultBlock;
+  toolResult: { id: string; result: ToolResult } | null;
+}
+
+/**
+ * Execute a single tool with permission checks and hooks
+ */
+async function executeSingleTool(
+  toolUse: ToolUseBlock,
+  options: ToolExecutionOptions
+): Promise<ToolExecutionResult> {
+  const { tools, workingDirectory, permissionMode, hookManager, sessionId, signal, permissionManager } = options;
+
+  const tool = tools.find((t) => t.name === toolUse.name);
+
+  if (!tool) {
+    return {
+      toolUseId: toolUse.id,
+      result: {
+        type: "tool_result" as const,
+        tool_use_id: toolUse.id,
+        content: `Error: Unknown tool "${toolUse.name}"`,
+        is_error: true,
+      },
+      toolResult: null,
+    };
+  }
+
+  // Check permissions using PermissionManager
+  const permissionResult = await permissionManager.checkPermission(
+    tool.name,
+    toolUse.input as Record<string, unknown>
+  );
+
+  if (permissionResult.decision === "deny" || permissionResult.decision === "denyAlways") {
+    return {
+      toolUseId: toolUse.id,
+      result: {
+        type: "tool_result" as const,
+        tool_use_id: toolUse.id,
+        content: `Permission denied for tool "${toolUse.name}"${permissionResult.reason ? `: ${permissionResult.reason}` : ""}`,
+        is_error: true,
+      },
+      toolResult: null,
+    };
+  }
+
+  // Execute PreToolUse hooks
+  if (hookManager) {
+    const hookResult = await hookManager.execute("PreToolUse", {
+      tool_name: tool.name,
+      tool_input: toolUse.input as Record<string, unknown>,
+      session_id: sessionId,
+    });
+
+    if (hookResult.decision === "deny" || hookResult.decision === "block") {
+      return {
+        toolUseId: toolUse.id,
+        result: {
+          type: "tool_result" as const,
+          tool_use_id: toolUse.id,
+          content: hookResult.reason || `Tool "${tool.name}" blocked by hook`,
+          is_error: true,
+        },
+        toolResult: null,
+      };
+    }
+
+    // Apply modified input if provided
+    if (hookResult.modified_input) {
+      Object.assign(toolUse.input, hookResult.modified_input);
+    }
+  }
+
+  // Execute tool
+  try {
+    const handlerResult = await tool.handler(toolUse.input as Record<string, unknown>, {
+      workingDirectory,
+      permissionMode,
+      abortSignal: signal,
+    });
+
+    // Execute PostToolUse hooks
+    let finalContent = handlerResult.content;
+    if (hookManager) {
+      const hookResult = await hookManager.execute("PostToolUse", {
+        tool_name: tool.name,
+        tool_input: toolUse.input as Record<string, unknown>,
+        tool_result: handlerResult,
+        tool_result_is_error: handlerResult.is_error,
+        session_id: sessionId,
+      });
+
+      if (hookResult.decision === "deny" || hookResult.decision === "block") {
+        return {
+          toolUseId: toolUse.id,
+          result: {
+            type: "tool_result" as const,
+            tool_use_id: toolUse.id,
+            content: hookResult.reason || `Tool "${tool.name}" result blocked by hook`,
+            is_error: true,
+          },
+          toolResult: null,
+        };
+      }
+
+      // Apply modified output if provided
+      if (hookResult.modified_input?.tool_result) {
+        finalContent = hookResult.modified_input.tool_result as string;
+      }
+    }
+
+    return {
+      toolUseId: toolUse.id,
+      result: {
+        type: "tool_result" as const,
+        tool_use_id: toolUse.id,
+        content: finalContent,
+        is_error: handlerResult.is_error,
+      },
+      toolResult: {
+        id: toolUse.id,
+        result: { ...handlerResult, content: finalContent },
+      },
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+
+    // Execute PostToolUseFailure hooks
+    if (hookManager) {
+      await hookManager.execute("PostToolUseFailure", {
+        tool_name: tool.name,
+        tool_input: toolUse.input as Record<string, unknown>,
+        error: errorMessage,
+        session_id: sessionId,
+      });
+    }
+
+    return {
+      toolUseId: toolUse.id,
+      result: {
+        type: "tool_result" as const,
+        tool_use_id: toolUse.id,
+        content: `Error: ${errorMessage}`,
+        is_error: true,
+      },
+      toolResult: null,
+    };
+  }
+}
+
+/**
+ * Execute multiple tools in parallel and collect results
+ */
+export async function executeTools(
+  toolUseBlocks: ToolUseBlock[],
+  options: ToolExecutionOptions
+): Promise<ToolResultBlock[]> {
+  // Check for abort before starting parallel execution
+  if (options.signal?.aborted) {
+    return [];
+  }
+
+  // Map each tool use to an async operation
+  const toolExecutions = toolUseBlocks.map((toolUse) =>
+    executeSingleTool(toolUse, options)
+  );
+
+  // Execute all tools in parallel
+  const executionResults = await Promise.all(toolExecutions);
+
+  // Collect results and notify callbacks
+  const toolResults: ToolResultBlock[] = [];
+  for (const executionResult of executionResults) {
+    toolResults.push(executionResult.result);
+    if (executionResult.toolResult && options.onToolResult) {
+      options.onToolResult(executionResult.toolResult);
+    }
+  }
+
+  return toolResults;
+}