deepagentsdk 0.9.2

package/src/constants/limits.ts

@@ -0,0 +1,195 @@
+/**
+ * Centralized token, size, and timeout limits.
+ *
+ * These constants prevent magic number scattering across the codebase and provide
+ * a single source of truth for configuration values. When updating these values,
+ * consider the impact on performance, user experience, and API limits.
+ *
+ * @module constants/limits
+ */
+
+// ============================================================================
+// Token Limits
+// ============================================================================
+
+/**
+ * Default token limit for tool result eviction.
+ *
+ * When a tool result exceeds this limit, it is automatically evicted to a file
+ * to prevent context overflow. The evicted content is stored in the backend and
+ * a summary is kept in the conversation history.
+ *
+ * @default 20000
+ * @see {@link ../utils/eviction | evictToolResult}
+ */
+export const DEFAULT_EVICTION_TOKEN_LIMIT = 20000;
+
+/**
+ * Default threshold for message summarization.
+ *
+ * When the estimated token count of messages exceeds this threshold, the system
+ * automatically summarizes older messages to stay within context limits. This
+ * helps maintain conversation continuity while reducing token usage.
+ *
+ * @default 170000
+ * @see {@link ../utils/summarization | summarizeIfNeeded}
+ */
+export const DEFAULT_SUMMARIZATION_THRESHOLD = 170000;
+
+/**
+ * Maximum context window size for Claude models.
+ *
+ * This represents the maximum number of tokens that can be processed in a single
+ * conversation. Used for calculating token usage percentages and determining when
+ * summarization is needed.
+ *
+ * @default 200000
+ * @see {@link ../utils/summarization | estimateMessagesTokens}
+ */
+export const CONTEXT_WINDOW = 200000;
+
+// ============================================================================
+// Message Limits
+// ============================================================================
+
+/**
+ * Default number of recent messages to keep during summarization.
+ *
+ * When summarization is triggered, this many of the most recent messages are
+ * preserved verbatim while older messages are summarized. This ensures recent
+ * context is immediately available to the agent.
+ *
+ * @default 6
+ */
+export const DEFAULT_KEEP_MESSAGES = 6;
+
+/**
+ * Default maximum number of reasoning steps for the main agent.
+ *
+ * The agent will stop after reaching this many steps to prevent infinite loops
+ * or excessive token usage. Each step represents one tool invocation cycle.
+ *
+ * @default 100
+ */
+export const DEFAULT_MAX_STEPS = 100;
+
+/**
+ * Default maximum number of reasoning steps for subagents.
+ *
+ * Subagents are given a lower step limit than the main agent to prevent them
+ * from consuming too many resources. This ensures the parent agent maintains
+ * control over the overall task.
+ *
+ * @default 50
+ * @see {@link ../tools/subagent | createTaskTool}
+ */
+export const DEFAULT_SUBAGENT_MAX_STEPS = 50;
+
+/**
+ * Default maximum number of messages to keep in CLI history.
+ *
+ * The CLI maintains a history of conversation messages for display purposes.
+ * This limit prevents memory issues in long-running sessions.
+ *
+ * @default 100
+ */
+export const DEFAULT_MAX_HISTORY = 100;
+
+// ============================================================================
+// File Size Limits
+// ============================================================================
+
+/**
+ * Default maximum number of lines to read from a file.
+ *
+ * The read_file tool defaults to reading this many lines to prevent loading
+ * extremely large files into context. Can be overridden per-read operation.
+ *
+ * @default 2000
+ * @see {@link ../tools/filesystem | createReadFileTool}
+ */
+export const DEFAULT_READ_LIMIT = 2000;
+
+/**
+ * Maximum line length before content is considered invalid.
+ *
+ * Lines exceeding this length may indicate minified code, binary content, or
+ * other data that should not be processed as text. Used for validation.
+ *
+ * @default 10000
+ */
+export const MAX_LINE_LENGTH = 10000;
+
+/**
+ * Maximum file size in megabytes for file operations.
+ *
+ * Files larger than this size will be rejected to prevent memory issues and
+ * excessive token usage. This is a soft limit that can be adjusted for specific
+ * use cases.
+ *
+ * @default 10
+ */
+export const MAX_FILE_SIZE_MB = 10;
+
+/**
+ * Maximum output size in bytes before truncation.
+ *
+ * Tool results larger than this size will be truncated or evicted to prevent
+ * context overflow. This helps maintain stable performance even with large
+ * outputs.
+ *
+ * @default 1048576 (1 MB)
+ */
+export const MAX_OUTPUT_SIZE_BYTES = 1048576; // 1MB
+
+// ============================================================================
+// Timeouts
+// ============================================================================
+
+/**
+ * Default timeout for network requests in seconds.
+ *
+ * Used by web tools (http_request, fetch_url) to prevent hanging indefinitely
+ * on slow or unresponsive servers. Can be overridden per-request.
+ *
+ * @default 30
+ * @see {@link ../tools/web | createHttpRequestTool}
+ */
+export const DEFAULT_TIMEOUT_SECONDS = 30;
+
+/**
+ * Default timeout in milliseconds (derived from DEFAULT_TIMEOUT_SECONDS).
+ *
+ * Provided for convenience when working with APIs that expect milliseconds
+ * instead of seconds.
+ *
+ * @default 30000 (30 seconds)
+ */
+export const DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_SECONDS * 1000;
+
+/**
+ * Timeout for filesystem operations in milliseconds.
+ *
+ * Used by sandboxed filesystem operations to prevent blocking indefinitely on
+ * slow I/O operations.
+ *
+ * @default 30000 (30 seconds)
+ * @see {@link ../backends/sandbox | SandboxBackend}
+ */
+export const FILESYSTEM_TIMEOUT_MS = 30000;
+
+// ============================================================================
+// Formatting
+// ============================================================================
+
+/**
+ * Width for line number formatting in file read operations.
+ *
+ * When displaying file content with line numbers, this specifies the minimum
+ * width for the line number column. Ensures consistent alignment across
+ * different file sizes.
+ *
+ * @default 6
+ * @see {@link ../backends/utils | formatFileContent}
+ */
+export const LINE_NUMBER_WIDTH = 6;

package/src/index.ts

@@ -0,0 +1,176 @@
+/**
+ * AI SDK Deep Agent
+ *
+ * A TypeScript library for building controllable AI agents using Vercel AI SDK v6.
+ * Implements the four pillars of Deep Agent:
+ * - Planning tools (write_todos)
+ * - Filesystem access (ls, read_file, write_file, edit_file, glob, grep)
+ * - Subagent spawning (task)
+ * - Detailed prompting
+ */
+
+// Main agent
+export { createDeepAgent, DeepAgent } from "./agent";
+
+// Re-export AI SDK v6 primitives for convenience
+export { ToolLoopAgent, stepCountIs, hasToolCall } from "ai";
+
+// Types
+export type {
+  CreateDeepAgentParams,
+  DeepAgentState,
+  SubAgent,
+  TodoItem,
+  FileData,
+  FileInfo,
+  GrepMatch,
+  WriteResult,
+  EditResult,
+  BackendProtocol,
+  BackendFactory,
+  SummarizationConfig,
+  // Sandbox types
+  ExecuteResponse,
+  SandboxBackendProtocol,
+  // Event types for streaming
+  DeepAgentEvent,
+  EventCallback,
+  TextEvent,
+  StepStartEvent,
+  StepFinishEvent,
+  ToolCallEvent,
+  ToolResultEvent,
+  TodosChangedEvent,
+  FileWriteStartEvent,
+  FileWrittenEvent,
+  FileEditedEvent,
+  ExecuteStartEvent,
+  ExecuteFinishEvent,
+  WebSearchStartEvent,
+  WebSearchFinishEvent,
+  HttpRequestStartEvent,
+  HttpRequestFinishEvent,
+  FetchUrlStartEvent,
+  FetchUrlFinishEvent,
+  SubagentStartEvent,
+  SubagentFinishEvent,
+  ApprovalRequestedEvent,
+  ApprovalResponseEvent,
+  CheckpointSavedEvent,
+  CheckpointLoadedEvent,
+  DoneEvent,
+  ErrorEvent,
+  // Approval configuration types
+  InterruptOnConfig,
+  DynamicApprovalConfig,
+} from "./types";
+
+// Type guard for sandbox backends
+export { isSandboxBackend } from "./types";
+
+// Backends
+export {
+  StateBackend,
+  FilesystemBackend,
+  CompositeBackend,
+  PersistentBackend,
+  InMemoryStore,
+  type KeyValueStore,
+  type PersistentBackendOptions,
+  // Sandbox backends
+  BaseSandbox,
+  LocalSandbox,
+  type LocalSandboxOptions,
+} from "./backends/index";
+
+// Tools (for advanced usage)
+export {
+  createTodosTool,
+  createFilesystemTools,
+  createSubagentTool,
+  type CreateSubagentToolOptions,
+  // Execute tool for sandbox backends
+  createExecuteTool,
+  createExecuteToolFromBackend,
+  type CreateExecuteToolOptions,
+  // Web tools
+  createWebTools,
+  htmlToMarkdown,
+  type CreateWebToolsOptions,
+  // Individual tool creator functions
+  createLsTool,
+  createReadFileTool,
+  createWriteFileTool,
+  createEditFileTool,
+  createGlobTool,
+  createGrepTool,
+  createWebSearchTool,
+  createHttpRequestTool,
+  createFetchUrlTool,
+  // Individual builtin tool references (for selective subagent configuration)
+  web_search,
+  http_request,
+  fetch_url,
+  ls,
+  read_file,
+  write_file,
+  edit_file,
+  glob,
+  grep,
+  write_todos,
+  execute,
+} from "./tools/index";
+
+// Prompts (for customization)
+export {
+  BASE_PROMPT,
+  TODO_SYSTEM_PROMPT,
+  FILESYSTEM_SYSTEM_PROMPT,
+  TASK_SYSTEM_PROMPT,
+  EXECUTE_SYSTEM_PROMPT,
+  getTaskToolDescription,
+  DEFAULT_GENERAL_PURPOSE_DESCRIPTION,
+  DEFAULT_SUBAGENT_PROMPT,
+} from "./prompts";
+
+// Utilities
+export {
+  patchToolCalls,
+  hasDanglingToolCalls,
+  evictToolResult,
+  createToolResultWrapper,
+  shouldEvict,
+  estimateTokens,
+  DEFAULT_EVICTION_TOKEN_LIMIT,
+  type EvictOptions,
+  type EvictResult,
+  summarizeIfNeeded,
+  needsSummarization,
+  estimateMessagesTokens,
+  DEFAULT_SUMMARIZATION_THRESHOLD,
+  DEFAULT_KEEP_MESSAGES,
+  type SummarizationOptions,
+  type SummarizationResult,
+} from "./utils/index";
+
+// Checkpointer
+export * from "./checkpointer/index";
+
+// Re-export AI SDK middleware types for user convenience
+export type { LanguageModelMiddleware } from 'ai';
+export { wrapLanguageModel } from 'ai';
+
+// Skills System
+export { listSkills, parseSkillMetadata } from "./skills/index";
+export type { SkillMetadata, SkillLoadOptions } from "./skills/index";
+
+// Agent Memory Middleware
+export { createAgentMemoryMiddleware } from "./middleware/agent-memory";
+export type { AgentMemoryOptions } from "./types";
+
+// Structured Output Utilities
+export { getStructuredOutput, getEventOutput, hasStructuredOutput, eventHasStructuredOutput } from "./types/structured-output";
+export type { StructuredAgentResult } from "./types/structured-output";
+
+// Project Detection Utilities
+export { findGitRoot } from "./utils/project-detection";

package/src/middleware/agent-memory.ts

@@ -0,0 +1,330 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import os from 'node:os';
+import type { LanguageModelMiddleware } from 'ai';
+import { findGitRoot } from '../utils/project-detection.js';
+
+/**
+ * Configuration options for agent memory middleware.
+ */
+export interface AgentMemoryOptions {
+  /**
+   * Unique identifier for the agent (e.g., "code-architect", "research-agent").
+   * Used to locate agent-specific memory at ~/.deepagents/{agentId}/agent.md
+   */
+  agentId: string;
+
+  /**
+   * Optional working directory for project-level memory detection.
+   * Defaults to process.cwd().
+   */
+  workingDirectory?: string;
+
+  /**
+   * Optional custom path for user-level .deepagents directory.
+   * Defaults to os.homedir() + '/.deepagents'.
+   *
+   * Useful for testing or custom deployment environments.
+   *
+   * @example
+   * ```typescript
+   * userDeepagentsDir: '/custom/path/.deepagents'
+   * // Will look for memory at: /custom/path/.deepagents/{agentId}/agent.md
+   * ```
+   */
+  userDeepagentsDir?: string;
+
+  /**
+   * Optional callback to request user approval for creating project-level .deepagents/ directory.
+   * If not provided, project memory will be silently skipped if directory doesn't exist.
+   *
+   * @param projectPath - Absolute path to the detected git root
+   * @returns Promise<boolean> - true if user approves, false otherwise
+   */
+  requestProjectApproval?: (projectPath: string) => Promise<boolean>;
+}
+
+/**
+ * Load agent memory from a file path.
+ * Returns empty string if file doesn't exist or can't be read.
+ */
+async function loadAgentMemory(filePath: string): Promise<string> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return content.trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Load all additional .md files from the agent's directory (excluding agent.md).
+ * Returns an array of { filename, content } objects.
+ */
+async function loadAdditionalMemoryFiles(
+  dirPath: string
+): Promise<Array<{ filename: string; content: string }>> {
+  try {
+    const files = await fs.readdir(dirPath);
+    const mdFiles = files.filter(
+      (f) => f.endsWith('.md') && f !== 'agent.md'
+    );
+
+    const results = await Promise.all(
+      mdFiles.map(async (filename) => {
+        const content = await loadAgentMemory(path.join(dirPath, filename));
+        return { filename, content };
+      })
+    );
+
+    return results.filter((r) => r.content.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Build the memory section for the system prompt.
+ * This comprehensive prompt teaches the agent how to use memory effectively.
+ */
+function buildMemorySection(
+  userMemory: string,
+  projectMemory: string,
+  additionalFiles: Array<{ filename: string; content: string }>,
+  agentId: string,
+  userMemoryPath: string,
+  projectMemoryPath: string | null
+): string {
+  let sections: string[] = [];
+
+  // Build memory content sections
+  if (userMemory) {
+    sections.push(`# Agent Memory (User-Level)
+
+The following is your persistent memory stored at ${userMemoryPath}:
+
+${userMemory}`);
+  }
+
+  if (projectMemory && projectMemoryPath) {
+    sections.push(`# Agent Memory (Project-Level)
+
+The following is project-specific context stored at ${projectMemoryPath}:
+
+${projectMemory}`);
+  }
+
+  if (additionalFiles.length > 0) {
+    const additionalSections = additionalFiles.map(
+      ({ filename, content }) => `## ${filename}
+
+${content}`
+    );
+    sections.push(`# Additional Context Files
+
+${additionalSections.join('\n\n')}`);
+  }
+
+  if (sections.length === 0) {
+    return ''; // No memory to inject
+  }
+
+  // Build comprehensive instructions
+  const memoryContent = sections.join('\n\n---\n\n');
+  const instructions = `
+<agent_memory>
+${memoryContent}
+
+---
+
+## How to Use This Memory
+
+**What is this?**
+- The content above is your persistent memory, stored in markdown files
+- **User-level memory** (${userMemoryPath}) contains your core personality, preferences, and cross-project context
+- **Project-level memory** ${projectMemoryPath ? `(${projectMemoryPath})` : '(not available)'} contains project-specific context and conventions
+
+**When to read memory:**
+- You already have the memory content above in your context - no need to read the files unless you need to verify exact content
+- If you need to check current memory state or see if it's been updated, use \`read_file\` tool
+
+**When to update memory:**
+- **User memory**: When you learn something important about the user's preferences, working style, or recurring patterns
+- **Project memory**: When you discover project-specific conventions, architecture decisions, or important context
+- **Additional files**: For specialized context that doesn't fit in agent.md (e.g., decision logs, architecture notes)
+
+**How to update memory:**
+- Use the \`write_file\` or \`edit_file\` tools with the file paths shown above
+- Keep entries concise and relevant
+- Organize information clearly with markdown headings
+- Remove outdated information when updating
+
+**Important guidelines:**
+- Memory is meant for long-term context, not temporary task tracking
+- Don't store information that's already in the codebase or documentation
+- Focus on insights, patterns, and preferences that aren't obvious from other sources
+- When in doubt, ask the user if something should be remembered
+
+**Example use cases:**
+- User prefers TypeScript strict mode and comprehensive error handling
+- Project uses custom testing framework located in \`test-utils/\`
+- User wants all API responses to follow specific error format
+- Project has specific commit message conventions
+</agent_memory>
+`;
+
+  return instructions.trim();
+}
+
+/**
+ * Create agent memory middleware for AI SDK v6.
+ *
+ * This middleware loads agent memory from:
+ * 1. User-level: ~/.deepagents/{agentId}/agent.md (personality, preferences)
+ * 2. Project-level: [git-root]/.deepagents/agent.md (project-specific context)
+ * 3. Additional files: Any other .md files in the user-level directory
+ *
+ * The memory is injected into the system prompt before each model call, teaching
+ * the agent when and how to read/update its own memory using filesystem tools.
+ *
+ * @param options - Configuration for agent memory
+ * @param options.agentId - Unique identifier for the agent (e.g., "code-architect")
+ * @param options.workingDirectory - Optional working directory for project detection (defaults to process.cwd())
+ * @param options.userDeepagentsDir - Optional custom path for user-level .deepagents directory (defaults to ~/.deepagents)
+ * @param options.requestProjectApproval - Optional callback to request approval before creating project .deepagents/ directory
+ * @returns AI SDK v6 middleware
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createDeepAgent } from 'deepagentsdk';
+ * import { createAgentMemoryMiddleware } from 'deepagentsdk/middleware';
+ * import { anthropic } from '@ai-sdk/anthropic';
+ *
+ * const memoryMiddleware = createAgentMemoryMiddleware({
+ *   agentId: 'code-architect',
+ * });
+ *
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-5'),
+ *   middleware: memoryMiddleware,
+ * });
+ * ```
+ *
+ * @example With project approval callback
+ * ```typescript
+ * const memoryMiddleware = createAgentMemoryMiddleware({
+ *   agentId: 'code-architect',
+ *   requestProjectApproval: async (projectPath) => {
+ *     console.log(`Create .deepagents/ in ${projectPath}? (y/n)`);
+ *     // ... get user input
+ *     return userSaidYes;
+ *   }
+ * });
+ * ```
+ *
+ * @example With custom user directory path
+ * ```typescript
+ * const memoryMiddleware = createAgentMemoryMiddleware({
+ *   agentId: 'code-architect',
+ *   userDeepagentsDir: '/custom/path/.deepagents',
+ *   // Memory will be loaded from:
+ *   // - /custom/path/.deepagents/code-architect/agent.md
+ *   // - [git-root]/.deepagents/agent.md (project-level)
+ * });
+ * ```
+ */
+export function createAgentMemoryMiddleware(
+  options: AgentMemoryOptions
+): LanguageModelMiddleware {
+  const { agentId, workingDirectory, userDeepagentsDir, requestProjectApproval } = options;
+
+  // Memory is loaded once and cached in closure variables
+  let memoryLoaded = false;
+  let cachedMemorySection = '';
+
+  return {
+    specificationVersion: 'v3',
+    transformParams: async ({ params }) => {
+      // Load memory on first call only (closure-based caching)
+      if (!memoryLoaded) {
+        const workDir = workingDirectory || process.cwd();
+
+        // 1. Load user-level memory
+        const baseUserDir = userDeepagentsDir || path.join(os.homedir(), '.deepagents');
+        const userAgentDir = path.join(baseUserDir, agentId);
+        const userMemoryPath = path.join(userAgentDir, 'agent.md');
+        const userMemory = await loadAgentMemory(userMemoryPath);
+
+        // Auto-create user directory if it doesn't exist (safe operation)
+        if (!userMemory) {
+          try {
+            await fs.mkdir(userAgentDir, { recursive: true });
+          } catch {
+            // Ignore errors - directory might already exist or permissions issue
+          }
+        }
+
+        // 2. Load additional .md files from user directory
+        const additionalFiles = await loadAdditionalMemoryFiles(userAgentDir);
+
+        // 3. Load project-level memory (if in git repository)
+        let projectMemory = '';
+        let projectMemoryPath: string | null = null;
+
+        const gitRoot = await findGitRoot(workDir);
+        if (gitRoot) {
+          const projectDeepagentsDir = path.join(gitRoot, '.deepagents');
+          projectMemoryPath = path.join(projectDeepagentsDir, 'agent.md');
+
+          // Check if project directory exists
+          try {
+            await fs.stat(projectDeepagentsDir);
+            projectMemory = await loadAgentMemory(projectMemoryPath);
+          } catch {
+            // Project directory doesn't exist - request approval if callback provided
+            if (requestProjectApproval) {
+              const approved = await requestProjectApproval(gitRoot);
+              if (approved) {
+                try {
+                  await fs.mkdir(projectDeepagentsDir, { recursive: true });
+                  // Don't create agent.md yet - let the agent do it when needed
+                } catch {
+                  // Ignore errors - permissions issue or race condition
+                }
+              }
+            }
+          }
+        }
+
+        // Build and cache memory section
+        cachedMemorySection = buildMemorySection(
+          userMemory,
+          projectMemory,
+          additionalFiles,
+          agentId,
+          userMemoryPath,
+          projectMemoryPath
+        );
+
+        memoryLoaded = true;
+      }
+
+      // Inject memory into system prompt if available
+      if (cachedMemorySection) {
+        const updatedPrompt = params.prompt.map((msg) => {
+          if (msg.role === 'system') {
+            return {
+              ...msg,
+              content: `${msg.content}\n\n${cachedMemorySection}`,
+            };
+          }
+          return msg;
+        });
+
+        return { ...params, prompt: updatedPrompt };
+      }
+
+      return params;
+    },
+  };
+}