ashlrcode 1.0.0

package/src/agent/loop.ts

@@ -0,0 +1,314 @@
+/**
+ * Core agent loop — the heart of AshlrCode.
+ *
+ * Pattern from Claude Code's query.ts:
+ *   User Input → messages[] → Provider API (streaming) → stop_reason check
+ *     → "tool_use"? → Execute tool → Append result → Loop
+ *     → No tool_use? → Return text to user
+ */
+
+import type { ProviderRouter } from "../providers/router.ts";
+import type { ToolRegistry } from "../tools/registry.ts";
+import type { ToolContext } from "../tools/types.ts";
+import { executeToolCalls } from "./tool-executor.ts";
+import type {
+  Message,
+  ContentBlock,
+  StreamEvent,
+  ToolCall,
+  ToolDefinition,
+} from "../providers/types.ts";
+
+export interface AgentConfig {
+  systemPrompt: string;
+  router: ProviderRouter;
+  toolRegistry: ToolRegistry;
+  toolContext: ToolContext;
+  maxIterations?: number;
+  /** If true, only allow read-only tools (plan mode) */
+  readOnly?: boolean;
+  /** Callback for streaming text to the UI */
+  onText?: (text: string) => void;
+  /** Callback when a tool is being called */
+  onToolStart?: (name: string, input: Record<string, unknown>) => void;
+  /** Callback when a tool completes */
+  onToolEnd?: (name: string, result: string, isError: boolean) => void;
+}
+
+export interface AgentResult {
+  messages: Message[];
+  finalText: string;
+  toolCalls: Array<{ name: string; input: Record<string, unknown>; result: string }>;
+}
+
+/* ── Streaming event types for streamAgentLoop() ───────────────── */
+
+export type AgentEvent =
+  | { type: "text_delta"; text: string }
+  | { type: "tool_start"; name: string; input: Record<string, unknown> }
+  | { type: "tool_end"; name: string; result: string; isError: boolean }
+  | { type: "turn_end"; finalText: string; toolCalls: AgentResult["toolCalls"] };
+
+/**
+ * Run the agent loop for a single user turn.
+ * Streams responses, executes tools, and loops until the model stops.
+ */
+export async function runAgentLoop(
+  userMessage: string,
+  history: Message[],
+  config: AgentConfig
+): Promise<AgentResult> {
+  const messages: Message[] = [
+    ...history,
+    { role: "user", content: userMessage },
+  ];
+
+  const tools = config.readOnly
+    ? config.toolRegistry.getReadOnlyDefinitions()
+    : config.toolRegistry.getDefinitions();
+
+  const maxIterations = config.maxIterations ?? 25;
+  const allToolCalls: AgentResult["toolCalls"] = [];
+  let finalText = "";
+
+  for (let iteration = 0; iteration < maxIterations; iteration++) {
+    const { text, toolCalls, stopReason } = await streamResponse(
+      messages,
+      tools,
+      config
+    );
+
+    finalText = text;
+
+    // Build assistant message with content blocks
+    const contentBlocks: ContentBlock[] = [];
+    if (text) {
+      contentBlocks.push({ type: "text", text });
+    }
+    for (const tc of toolCalls) {
+      contentBlocks.push({
+        type: "tool_use",
+        id: tc.id,
+        name: tc.name,
+        input: tc.input,
+      });
+    }
+
+    messages.push({
+      role: "assistant",
+      content: contentBlocks.length === 1 && contentBlocks[0]!.type === "text"
+        ? text
+        : contentBlocks,
+    });
+
+    // If no tool calls, we're done
+    if (stopReason !== "tool_use" || toolCalls.length === 0) {
+      break;
+    }
+
+    // Execute tool calls (parallel for safe tools, sequential for unsafe)
+    const executionResults = await executeToolCalls(
+      toolCalls,
+      config.toolRegistry,
+      config.toolContext,
+      {
+        onToolStart: config.onToolStart,
+        onToolEnd: config.onToolEnd,
+      }
+    );
+
+    const resultBlocks: ContentBlock[] = [];
+    for (const er of executionResults) {
+      allToolCalls.push({ name: er.name, input: er.input, result: er.result });
+      resultBlocks.push({
+        type: "tool_result",
+        tool_use_id: er.toolCallId,
+        content: er.result,
+        is_error: er.isError,
+      });
+    }
+
+    messages.push({ role: "user", content: resultBlocks });
+  }
+
+  // If we hit max iterations with no final text, add a fallback
+  if (!finalText && allToolCalls.length > 0) {
+    finalText = `[Reached maximum iterations (${maxIterations}). ${allToolCalls.length} tool calls were executed.]`;
+  }
+
+  return { messages, finalText, toolCalls: allToolCalls };
+}
+
+/**
+ * Streaming agent loop — yields incremental events as an AsyncGenerator.
+ *
+ * Unlike runAgentLoop() which buffers everything and returns a Promise<AgentResult>,
+ * this lets callers react to each event as it arrives (text deltas, tool
+ * invocations, etc.). Useful for streaming UIs and programmatic consumers.
+ *
+ * The existing runAgentLoop() is intentionally left unchanged so current
+ * callers keep working — this is an additive, opt-in API.
+ */
+export async function* streamAgentLoop(
+  userMessage: string,
+  history: Message[],
+  config: AgentConfig
+): AsyncGenerator<AgentEvent> {
+  const messages: Message[] = [
+    ...history,
+    { role: "user", content: userMessage },
+  ];
+
+  const tools = config.readOnly
+    ? config.toolRegistry.getReadOnlyDefinitions()
+    : config.toolRegistry.getDefinitions();
+
+  const maxIterations = config.maxIterations ?? 25;
+  const allToolCalls: AgentResult["toolCalls"] = [];
+  let finalText = "";
+
+  for (let iteration = 0; iteration < maxIterations; iteration++) {
+    // Stream API response, yielding text deltas as they arrive
+    let text = "";
+    const toolCalls: ToolCall[] = [];
+    let stopReason = "end_turn";
+
+    const stream = config.router.stream({
+      systemPrompt: config.systemPrompt,
+      messages,
+      tools,
+    });
+
+    for await (const event of stream) {
+      switch (event.type) {
+        case "text_delta":
+          if (event.text) {
+            text += event.text;
+            yield { type: "text_delta", text: event.text };
+          }
+          break;
+
+        case "tool_call_end":
+          if (event.toolCall?.id && event.toolCall?.name && event.toolCall?.input) {
+            toolCalls.push(event.toolCall as ToolCall);
+          }
+          break;
+
+        case "message_end":
+          if (event.stopReason) {
+            stopReason = event.stopReason;
+          }
+          break;
+      }
+    }
+
+    finalText = text;
+
+    // Build assistant message with content blocks
+    const contentBlocks: ContentBlock[] = [];
+    if (text) {
+      contentBlocks.push({ type: "text", text });
+    }
+    for (const tc of toolCalls) {
+      contentBlocks.push({
+        type: "tool_use",
+        id: tc.id,
+        name: tc.name,
+        input: tc.input,
+      });
+    }
+
+    messages.push({
+      role: "assistant",
+      content: contentBlocks.length === 1 && contentBlocks[0]!.type === "text"
+        ? text
+        : contentBlocks,
+    });
+
+    // If no tool calls, we're done
+    if (stopReason !== "tool_use" || toolCalls.length === 0) {
+      break;
+    }
+
+    // Execute tool calls, yielding start/end events for each
+    const executionResults = await executeToolCalls(
+      toolCalls,
+      config.toolRegistry,
+      config.toolContext,
+      {
+        onToolStart: config.onToolStart,
+        onToolEnd: config.onToolEnd,
+      }
+    );
+
+    for (const er of executionResults) {
+      yield { type: "tool_start", name: er.name, input: er.input };
+      yield { type: "tool_end", name: er.name, result: er.result, isError: er.isError };
+      allToolCalls.push({ name: er.name, input: er.input, result: er.result });
+    }
+
+    // Add tool results to messages for the next iteration
+    const resultBlocks: ContentBlock[] = executionResults.map((er) => ({
+      type: "tool_result" as const,
+      tool_use_id: er.toolCallId,
+      content: er.result,
+      is_error: er.isError,
+    }));
+    messages.push({ role: "user", content: resultBlocks });
+  }
+
+  // If we hit max iterations with no final text, add a fallback
+  if (!finalText && allToolCalls.length > 0) {
+    finalText = `[Reached maximum iterations (${maxIterations}). ${allToolCalls.length} tool calls were executed.]`;
+  }
+
+  yield { type: "turn_end", finalText, toolCalls: allToolCalls };
+}
+
+/**
+ * Stream a single API response, collecting text and tool calls.
+ */
+async function streamResponse(
+  messages: Message[],
+  tools: ToolDefinition[],
+  config: AgentConfig
+): Promise<{
+  text: string;
+  toolCalls: ToolCall[];
+  stopReason: string;
+}> {
+  let text = "";
+  const toolCalls: ToolCall[] = [];
+  let stopReason = "end_turn";
+
+  const stream = config.router.stream({
+    systemPrompt: config.systemPrompt,
+    messages,
+    tools,
+  });
+
+  for await (const event of stream) {
+    switch (event.type) {
+      case "text_delta":
+        if (event.text) {
+          text += event.text;
+          config.onText?.(event.text);
+        }
+        break;
+
+      case "tool_call_end":
+        if (event.toolCall?.id && event.toolCall?.name && event.toolCall?.input) {
+          toolCalls.push(event.toolCall as ToolCall);
+        }
+        break;
+
+      case "message_end":
+        if (event.stopReason) {
+          stopReason = event.stopReason;
+        }
+        break;
+    }
+  }
+
+  return { text, toolCalls, stopReason };
+}

package/src/agent/model-patches.ts

@@ -0,0 +1,68 @@
+/**
+ * Model behavior patches — provider/model-specific prompt adjustments.
+ *
+ * Different models have known issues. These patches add targeted
+ * instructions to mitigate them.
+ */
+
+export interface ModelPatch {
+  pattern: string;        // Regex to match model name
+  name: string;           // Human-readable patch name
+  promptSuffix: string;   // Added to system prompt
+}
+
+const PATCHES: ModelPatch[] = [
+  {
+    pattern: "^grok(?!-4-1-fast)",
+    name: "Grok verbosity control",
+    promptSuffix: "\n\nIMPORTANT: Be concise. Avoid unnecessary preamble. Lead with the answer or action, not reasoning. If you can say it in one sentence, don't use three.",
+  },
+  {
+    pattern: "^grok-4-1-fast",
+    name: "Grok fast mode",
+    promptSuffix: "\n\nYou are running in fast mode. Prioritize speed. Use fewer tool calls. Give direct answers.",
+  },
+  {
+    pattern: "^claude.*sonnet",
+    name: "Sonnet conciseness",
+    promptSuffix: "\n\nBe extremely concise. Skip filler words and preamble. No trailing summaries.",
+  },
+  {
+    pattern: "^claude.*opus",
+    name: "Opus thoroughness",
+    promptSuffix: "\n\nBe thorough and precise. Verify your work. Check edge cases.",
+  },
+  {
+    pattern: "^o1(-mini)?$",
+    name: "OpenAI reasoning",
+    promptSuffix: "\n\nYou have reasoning capabilities. Use them for complex problems. Think step by step when the problem requires it.",
+  },
+  {
+    pattern: "^deepseek",
+    name: "DeepSeek format control",
+    promptSuffix: "\n\nAvoid over-commenting code. Keep code changes minimal and focused. Don't add docstrings unless asked.",
+  },
+  {
+    pattern: "^(llama|local)",
+    name: "Local model constraints",
+    promptSuffix: "\n\nKeep tool calls simple. Avoid deeply nested or complex operations. You have limited context — be efficient with tokens.",
+  },
+];
+
+/**
+ * Get applicable patches for the current model.
+ */
+export function getModelPatches(modelName: string): { names: string[]; combinedSuffix: string } {
+  const applicable = PATCHES.filter(p => new RegExp(p.pattern, "i").test(modelName));
+  return {
+    names: applicable.map(p => p.name),
+    combinedSuffix: applicable.map(p => p.promptSuffix).join(""),
+  };
+}
+
+/**
+ * List all available patches (for /patches command).
+ */
+export function listPatches(): ModelPatch[] {
+  return [...PATCHES];
+}

package/src/agent/speculation.ts

@@ -0,0 +1,219 @@
+/**
+ * Speculation — pre-fetch likely tool results while the model streams.
+ *
+ * When the model starts generating a tool_use block, we can sometimes
+ * predict the full call and start executing early. This hides latency
+ * for read-only tools like Read, Glob, Grep.
+ *
+ * Only read-only tools are eligible — we never speculatively execute
+ * writes, edits, or shell commands.
+ */
+
+import { existsSync } from "fs";
+import { readFile, stat } from "fs/promises";
+import { dirname } from "path";
+
+// ---------------------------------------------------------------------------
+// Cache entry
+// ---------------------------------------------------------------------------
+
+interface CacheEntry {
+  key: string;
+  result: string;
+  timestamp: number;
+  hitCount: number;
+}
+
+// ---------------------------------------------------------------------------
+// SpeculationCache
+// ---------------------------------------------------------------------------
+
+export class SpeculationCache {
+  private cache = new Map<string, CacheEntry>();
+  private missCount = 0;
+  private maxSize: number;
+  private ttlMs: number;
+
+  constructor(maxSize = 100, ttlMs = 30_000) {
+    this.maxSize = maxSize;
+    this.ttlMs = ttlMs;
+  }
+
+  // -------------------------------------------------------------------------
+  // Core get / set
+  // -------------------------------------------------------------------------
+
+  /** Check if we have a valid cached result for a tool call. */
+  get(toolName: string, input: Record<string, unknown>): string | null {
+    const key = this.makeKey(toolName, input);
+    const entry = this.cache.get(key);
+    if (!entry) {
+      this.missCount++;
+      return null;
+    }
+
+    // TTL check
+    if (Date.now() - entry.timestamp > this.ttlMs) {
+      this.cache.delete(key);
+      this.missCount++;
+      return null;
+    }
+
+    entry.hitCount++;
+    return entry.result;
+  }
+
+  /** Store a tool result in the cache. */
+  set(toolName: string, input: Record<string, unknown>, result: string): void {
+    const key = this.makeKey(toolName, input);
+
+    // Evict oldest entry if at capacity
+    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+      let oldestKey: string | null = null;
+      let oldestTs = Infinity;
+      for (const [k, v] of this.cache) {
+        if (v.timestamp < oldestTs) {
+          oldestTs = v.timestamp;
+          oldestKey = k;
+        }
+      }
+      if (oldestKey) this.cache.delete(oldestKey);
+    }
+
+    this.cache.set(key, {
+      key,
+      result,
+      timestamp: Date.now(),
+      hitCount: 0,
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Speculative pre-fetching
+  // -------------------------------------------------------------------------
+
+  /**
+   * Speculatively pre-read a file into the cache.
+   * Skips files that don't exist or are too large (>1 MB).
+   */
+  async prefetchRead(filePath: string): Promise<void> {
+    try {
+      if (!existsSync(filePath)) return;
+      const stats = await stat(filePath);
+      if (stats.size > 1_000_000) return; // skip large files
+
+      const content = await readFile(filePath, "utf-8");
+      this.set("Read", { file_path: filePath }, content);
+    } catch {
+      // Silently ignore — speculation failures are harmless
+    }
+  }
+
+  /**
+   * After each tool execution, look at the recent history and
+   * speculatively pre-fetch results that the model is likely to
+   * request next.
+   *
+   * Heuristics:
+   * 1. After Glob → pre-read the first few matched files.
+   * 2. After Read of file X → pre-read sibling files with same ext.
+   * 3. After Grep returning file matches → pre-read those files.
+   */
+  async speculateFromHistory(
+    recentToolCalls: Array<{
+      name: string;
+      input: Record<string, unknown>;
+      result?: string;
+    }>
+  ): Promise<void> {
+    if (recentToolCalls.length === 0) return;
+
+    const last = recentToolCalls[recentToolCalls.length - 1]!;
+
+    // Heuristic 1: After Glob, pre-read the first few matched files
+    if (last.name === "Glob" && typeof last.result === "string") {
+      const paths = last.result
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .slice(0, 5); // limit to first 5
+
+      await Promise.allSettled(paths.map((p) => this.prefetchRead(p)));
+    }
+
+    // Heuristic 2: After Grep returning file paths, pre-read them
+    if (last.name === "Grep" && typeof last.result === "string") {
+      const paths = last.result
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.startsWith("/"))
+        .slice(0, 5);
+
+      await Promise.allSettled(paths.map((p) => this.prefetchRead(p)));
+    }
+
+    // Heuristic 3: After Read, pre-read sibling files with same extension
+    if (last.name === "Read" && typeof last.input.file_path === "string") {
+      const filePath = last.input.file_path;
+      const dir = dirname(filePath);
+      try {
+        const { readdir } = await import("fs/promises");
+        const { extname, join } = await import("path");
+        const ext = extname(filePath);
+        const entries = await readdir(dir);
+        const siblings = entries
+          .filter((e) => extname(e) === ext && join(dir, e) !== filePath)
+          .slice(0, 3) // limit to 3 siblings
+          .map((e) => join(dir, e));
+
+        await Promise.allSettled(siblings.map((p) => this.prefetchRead(p)));
+      } catch {
+        // Ignore — dir may not exist or may not be readable
+      }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Invalidation
+  // -------------------------------------------------------------------------
+
+  /** Invalidate cache entries that might be stale after a write/edit. */
+  invalidateForFile(filePath: string): void {
+    // Remove any Read cache for this exact file
+    const readKey = this.makeKey("Read", { file_path: filePath });
+    this.cache.delete(readKey);
+
+    // Remove any Grep/Glob results that might reference this file
+    // (conservative: remove all Grep/Glob entries since results may change)
+    for (const [key] of this.cache) {
+      if (key.startsWith("Grep:") || key.startsWith("Glob:")) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Diagnostics
+  // -------------------------------------------------------------------------
+
+  /** Return cache statistics for debugging. */
+  getStats(): { size: number; hits: number; misses: number } {
+    let hits = 0;
+    for (const entry of this.cache.values()) hits += entry.hitCount;
+    return { size: this.cache.size, hits, misses: this.missCount };
+  }
+
+  /** Clear the entire cache. */
+  clear(): void {
+    this.cache.clear();
+    this.missCount = 0;
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+
+  private makeKey(toolName: string, input: Record<string, unknown>): string {
+    return `${toolName}:${JSON.stringify(input)}`;
+  }
+}