deepagentsdk 0.9.2

package/src/utils/eviction.ts

@@ -0,0 +1,181 @@
+/**
+ * Tool result eviction utility.
+ *
+ * When tool results exceed a certain size threshold, this utility
+ * writes them to the filesystem and returns a reference instead.
+ * This prevents context overflow from large tool outputs.
+ */
+
+import type { BackendProtocol, BackendFactory, DeepAgentState } from "../types.js";
+import { DEFAULT_EVICTION_TOKEN_LIMIT as CENTRALIZED_EVICTION_LIMIT } from "../constants/limits.js";
+
+/**
+ * Default token limit before evicting a tool result.
+ * Approximately 20,000 tokens (~80KB of text).
+ */
+export const DEFAULT_EVICTION_TOKEN_LIMIT = CENTRALIZED_EVICTION_LIMIT;
+
+/**
+ * Approximate characters per token (rough estimate).
+ */
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * Sanitize a tool call ID for use as a filename.
+ * Removes or replaces characters that are invalid in file paths.
+ */
+export function sanitizeToolCallId(toolCallId: string): string {
+  return toolCallId
+    .replace(/[^a-zA-Z0-9_-]/g, "_")
+    .substring(0, 100); // Limit length
+}
+
+/**
+ * Estimate the number of tokens in a string.
+ * Uses a simple character-based approximation.
+ */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+/**
+ * Check if a tool result should be evicted based on size.
+ */
+export function shouldEvict(
+  result: string,
+  tokenLimit: number = DEFAULT_EVICTION_TOKEN_LIMIT
+): boolean {
+  return estimateTokens(result) > tokenLimit;
+}
+
+/**
+ * Options for evicting a tool result.
+ */
+export interface EvictOptions {
+  /** The tool result content */
+  result: string;
+  /** The tool call ID (used for filename) */
+  toolCallId: string;
+  /** The tool name */
+  toolName: string;
+  /** Backend to write the evicted content to */
+  backend: BackendProtocol;
+  /** Token limit before eviction (default: 20000) */
+  tokenLimit?: number;
+}
+
+/**
+ * Result of an eviction operation.
+ */
+export interface EvictResult {
+  /** Whether the result was evicted */
+  evicted: boolean;
+  /** The content to return (either original or truncated message) */
+  content: string;
+  /** Path where content was evicted to (if evicted) */
+  evictedPath?: string;
+}
+
+/**
+ * Evict a large tool result to the filesystem.
+ *
+ * If the result exceeds the token limit, writes it to a file and
+ * returns a truncated message with the file path.
+ *
+ * @param options - Eviction options
+ * @returns Eviction result with content and metadata
+ *
+ * @example
+ * ```typescript
+ * const result = await evictToolResult({
+ *   result: veryLongString,
+ *   toolCallId: "call_123",
+ *   toolName: "grep",
+ *   backend: filesystemBackend,
+ * });
+ *
+ * if (result.evicted) {
+ *   console.log(`Content saved to ${result.evictedPath}`);
+ * }
+ * ```
+ */
+export async function evictToolResult(
+  options: EvictOptions
+): Promise<EvictResult> {
+  const {
+    result,
+    toolCallId,
+    toolName,
+    backend,
+    tokenLimit = DEFAULT_EVICTION_TOKEN_LIMIT,
+  } = options;
+
+  // Check if eviction is needed
+  if (!shouldEvict(result, tokenLimit)) {
+    return {
+      evicted: false,
+      content: result,
+    };
+  }
+
+  // Generate eviction path
+  const sanitizedId = sanitizeToolCallId(toolCallId);
+  const evictPath = `/large_tool_results/${toolName}_${sanitizedId}.txt`;
+
+  // Write to backend
+  const writeResult = await backend.write(evictPath, result);
+
+  if (writeResult.error) {
+    // If write fails, return original content (may cause context issues)
+    console.warn(`Failed to evict tool result: ${writeResult.error}`);
+    return {
+      evicted: false,
+      content: result,
+    };
+  }
+
+  // Return truncated message
+  const estimatedTokens = estimateTokens(result);
+  const truncatedContent = `Tool result too large (~${estimatedTokens} tokens). Content saved to ${evictPath}. Use read_file to access the full content.`;
+
+  return {
+    evicted: true,
+    content: truncatedContent,
+    evictedPath: evictPath,
+  };
+}
+
+/**
+ * Create a tool result wrapper that automatically evicts large results.
+ *
+ * @param backend - Backend or factory for filesystem operations
+ * @param state - Current agent state (for factory backends)
+ * @param tokenLimit - Token limit before eviction
+ * @returns Function that wraps tool results with eviction
+ */
+export function createToolResultWrapper(
+  backend: BackendProtocol | BackendFactory,
+  state: DeepAgentState,
+  tokenLimit: number = DEFAULT_EVICTION_TOKEN_LIMIT
+): (result: string, toolCallId: string, toolName: string) => Promise<string> {
+  // Resolve backend if factory
+  const resolvedBackend =
+    typeof backend === "function" ? backend(state) : backend;
+
+  return async (
+    result: string,
+    toolCallId: string,
+    toolName: string
+  ): Promise<string> => {
+    const evictResult = await evictToolResult({
+      result,
+      toolCallId,
+      toolName,
+      backend: resolvedBackend,
+      tokenLimit,
+    });
+
+    return evictResult.content;
+  };
+}
+

package/src/utils/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Utility functions for AI SDK Deep Agent.
+ */
+
+export { patchToolCalls, hasDanglingToolCalls } from "./patch-tool-calls.js";
+export {
+  evictToolResult,
+  createToolResultWrapper,
+  shouldEvict,
+  estimateTokens,
+  sanitizeToolCallId,
+  DEFAULT_EVICTION_TOKEN_LIMIT,
+  type EvictOptions,
+  type EvictResult,
+} from "./eviction.js";
+export {
+  summarizeIfNeeded,
+  needsSummarization,
+  estimateMessagesTokens,
+  DEFAULT_SUMMARIZATION_THRESHOLD,
+  DEFAULT_KEEP_MESSAGES,
+  type SummarizationOptions,
+  type SummarizationResult,
+} from "./summarization.js";
+export {
+  parseModelString,
+} from "./model-parser.js";
+export {
+  applyInterruptConfig,
+  wrapToolsWithApproval,
+  hasApprovalTools,
+  type ApprovalCallback,
+} from "./approval.js";
+

package/src/utils/model-parser.ts

@@ -0,0 +1,38 @@
+/**
+ * Utility to parse model strings into LanguageModel instances.
+ * Provides backward compatibility for CLI and other string-based model specifications.
+ */
+
+import { anthropic } from "@ai-sdk/anthropic";
+import { openai } from "@ai-sdk/openai";
+import type { LanguageModel } from "ai";
+
+/**
+ * Parse a model string into a LanguageModel instance.
+ *
+ * Supports formats like:
+ * - "anthropic/claude-sonnet-4-20250514"
+ * - "openai/gpt-4o"
+ * - "claude-sonnet-4-20250514" (defaults to Anthropic)
+ *
+ * @param modelString - The model string to parse
+ * @returns A LanguageModel instance
+ *
+ * @example
+ * ```typescript
+ * const model = parseModelString("anthropic/claude-sonnet-4-20250514");
+ * const agent = createDeepAgent({ model });
+ * ```
+ */
+export function parseModelString(modelString: string): LanguageModel {
+  const [provider, modelName] = modelString.split("/");
+
+  if (provider === "anthropic") {
+    return anthropic(modelName || "claude-sonnet-4-20250514");
+  } else if (provider === "openai") {
+    return openai(modelName || "gpt-5-mini") as any;
+  }
+
+  // Default to anthropic if no provider specified
+  return anthropic(modelString);
+}

package/src/utils/patch-tool-calls.ts

@@ -0,0 +1,233 @@
+/**
+ * Utility to patch dangling tool calls in message history.
+ *
+ * When an AI message contains tool_calls but subsequent messages don't include
+ * the corresponding tool result responses, this utility adds synthetic
+ * tool result messages saying the tool call was cancelled.
+ *
+ * This prevents errors when sending the conversation history to the model,
+ * as models expect every tool call to have a corresponding result.
+ */
+
+import type { ModelMessage } from "ai";
+
+/**
+ * Check if a message is an assistant message with tool calls.
+ */
+function hasToolCalls(message: ModelMessage): boolean {
+  if (message.role !== "assistant") return false;
+
+  // Check if content contains tool calls
+  const content = message.content;
+  if (Array.isArray(content)) {
+    return content.some(
+      (part) => typeof part === "object" && part !== null && "type" in part && part.type === "tool-call"
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Extract tool call IDs from an assistant message.
+ */
+function getToolCallIds(message: ModelMessage): string[] {
+  if (message.role !== "assistant") return [];
+
+  const content = message.content;
+  if (!Array.isArray(content)) return [];
+
+  const ids: string[] = [];
+  for (const part of content) {
+    if (
+      typeof part === "object" &&
+      part !== null &&
+      "type" in part &&
+      part.type === "tool-call" &&
+      "toolCallId" in part
+    ) {
+      ids.push(part.toolCallId as string);
+    }
+  }
+
+  return ids;
+}
+
+/**
+ * Check if a message is a tool result for a specific tool call ID.
+ */
+function isToolResultFor(message: ModelMessage, toolCallId: string): boolean {
+  if (message.role !== "tool") return false;
+
+  // Tool messages should have a toolCallId
+  if ("toolCallId" in message && message.toolCallId === toolCallId) {
+    return true;
+  }
+
+  // Also check content array for tool-result parts
+  const content = message.content;
+  if (Array.isArray(content)) {
+    return content.some(
+      (part) =>
+        typeof part === "object" &&
+        part !== null &&
+        "type" in part &&
+        part.type === "tool-result" &&
+        "toolCallId" in part &&
+        part.toolCallId === toolCallId
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Create a synthetic tool result message for a cancelled tool call.
+ */
+function createCancelledToolResult(
+  toolCallId: string,
+  toolName: string
+): ModelMessage {
+  const message: ModelMessage = {
+    role: "tool",
+    content: [
+      {
+        type: "tool-result" as const,
+        toolCallId,
+        toolName,
+        output: {
+          type: "text" as const,
+          value: `Tool call ${toolName} with id ${toolCallId} was cancelled - another message came in before it could be completed.`,
+        },
+      },
+    ],
+  };
+  return message;
+}
+
+/**
+ * Get tool name from a tool call part.
+ */
+function getToolName(message: ModelMessage, toolCallId: string): string {
+  if (message.role !== "assistant") return "unknown";
+
+  const content = message.content;
+  if (!Array.isArray(content)) return "unknown";
+
+  for (const part of content) {
+    if (
+      typeof part === "object" &&
+      part !== null &&
+      "type" in part &&
+      part.type === "tool-call" &&
+      "toolCallId" in part &&
+      part.toolCallId === toolCallId &&
+      "toolName" in part
+    ) {
+      return part.toolName as string;
+    }
+  }
+
+  return "unknown";
+}
+
+/**
+ * Patch dangling tool calls in a message array.
+ *
+ * Scans for assistant messages with tool_calls that don't have corresponding
+ * tool result messages, and adds synthetic "cancelled" responses.
+ *
+ * @param messages - Array of messages to patch
+ * @returns New array with patched messages (original array is not modified)
+ *
+ * @example
+ * ```typescript
+ * const messages = [
+ *   { role: "user", content: "Hello" },
+ *   { role: "assistant", content: [{ type: "tool-call", toolCallId: "1", toolName: "search" }] },
+ *   // Missing tool result for tool call "1"
+ *   { role: "user", content: "Never mind" },
+ * ];
+ *
+ * const patched = patchToolCalls(messages);
+ * // patched now includes a synthetic tool result for the dangling call
+ * ```
+ */
+export function patchToolCalls(messages: ModelMessage[]): ModelMessage[] {
+  if (!messages || messages.length === 0) {
+    return messages;
+  }
+
+  const result: ModelMessage[] = [];
+
+  for (let i = 0; i < messages.length; i++) {
+    const message = messages[i];
+    if (!message) continue;
+    
+    result.push(message);
+
+    // Check if this is an assistant message with tool calls
+    if (hasToolCalls(message)) {
+      const toolCallIds = getToolCallIds(message);
+
+      for (const toolCallId of toolCallIds) {
+        // Look for a corresponding tool result in subsequent messages
+        let hasResult = false;
+        for (let j = i + 1; j < messages.length; j++) {
+          const subsequentMsg = messages[j];
+          if (subsequentMsg && isToolResultFor(subsequentMsg, toolCallId)) {
+            hasResult = true;
+            break;
+          }
+        }
+
+        // If no result found, add a synthetic cancelled result
+        if (!hasResult) {
+          const toolName = getToolName(message, toolCallId);
+          result.push(createCancelledToolResult(toolCallId, toolName));
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Check if messages have any dangling tool calls.
+ *
+ * @param messages - Array of messages to check
+ * @returns True if there are dangling tool calls
+ */
+export function hasDanglingToolCalls(messages: ModelMessage[]): boolean {
+  if (!messages || messages.length === 0) {
+    return false;
+  }
+
+  for (let i = 0; i < messages.length; i++) {
+    const message = messages[i];
+    if (!message) continue;
+
+    if (hasToolCalls(message)) {
+      const toolCallIds = getToolCallIds(message);
+
+      for (const toolCallId of toolCallIds) {
+        let hasResult = false;
+        for (let j = i + 1; j < messages.length; j++) {
+          const subsequentMsg = messages[j];
+          if (subsequentMsg && isToolResultFor(subsequentMsg, toolCallId)) {
+            hasResult = true;
+            break;
+          }
+        }
+
+        if (!hasResult) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+}
+

package/src/utils/project-detection.ts

@@ -0,0 +1,32 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+/**
+ * Find the git root by walking up the directory tree.
+ * Returns null if no .git directory is found.
+ *
+ * @param startPath - Starting directory (defaults to process.cwd())
+ * @returns Absolute path to git root, or null if not in a git repository
+ */
+export async function findGitRoot(startPath?: string): Promise<string | null> {
+  let current = path.resolve(startPath || process.cwd());
+  const root = path.parse(current).root;
+
+  while (current !== root) {
+    try {
+      const gitPath = path.join(current, '.git');
+      const stat = await fs.stat(gitPath);
+
+      if (stat.isDirectory()) {
+        return current;
+      }
+    } catch {
+      // .git doesn't exist at this level, continue upward
+    }
+
+    // Move up one directory
+    current = path.dirname(current);
+  }
+
+  return null;
+}