deepagentsdk 0.9.2

package/src/backends/state.ts

@@ -0,0 +1,244 @@
+/**
+ * StateBackend: Store files in shared state (ephemeral, in-memory).
+ */
+
+import type {
+  BackendProtocol,
+  EditResult,
+  FileData,
+  FileInfo,
+  GrepMatch,
+  WriteResult,
+  DeepAgentState,
+} from "../types";
+import {
+  createFileData,
+  fileDataToString,
+  formatReadResponse,
+  globSearchFiles,
+  grepMatchesFromFiles,
+  performStringReplacement,
+  updateFileData,
+} from "./utils";
+import {
+  FILE_NOT_FOUND,
+  FILE_ALREADY_EXISTS,
+} from "../constants/errors";
+
+/**
+ * Backend that stores files in shared state (ephemeral).
+ *
+ * Files persist within a single agent invocation but not across invocations.
+ * This is the default backend for Deep Agent when no backend is specified.
+ *
+ * Files are stored in memory as part of the `DeepAgentState`, making this backend
+ * fast but non-persistent. Use `FilesystemBackend` or `PersistentBackend` for
+ * cross-session persistence.
+ *
+ * @example Default usage (no backend specified)
+ * ```typescript
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   // StateBackend is used by default
+ * });
+ * ```
+ *
+ * @example Explicit usage
+ * ```typescript
+ * const state: DeepAgentState = { todos: [], files: {} };
+ * const backend = new StateBackend(state);
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend,
+ * });
+ * ```
+ */
+export class StateBackend implements BackendProtocol {
+  private state: DeepAgentState;
+
+  /**
+   * Create a new StateBackend instance.
+   *
+   * @param state - The DeepAgentState object that will store the files.
+   *                Files are stored in `state.files` as a Record<string, FileData>.
+   */
+  constructor(state: DeepAgentState) {
+    this.state = state;
+  }
+
+  /**
+   * Get files from current state.
+   */
+  private getFiles(): Record<string, FileData> {
+    return this.state.files || {};
+  }
+
+  /**
+   * List files and directories in the specified directory (non-recursive).
+   */
+  lsInfo(path: string): FileInfo[] {
+    const files = this.getFiles();
+    const infos: FileInfo[] = [];
+    const subdirs = new Set<string>();
+
+    const normalizedPath = path.endsWith("/") ? path : path + "/";
+
+    for (const [k, fd] of Object.entries(files)) {
+      if (!k.startsWith(normalizedPath)) {
+        continue;
+      }
+
+      const relative = k.substring(normalizedPath.length);
+
+      if (relative.includes("/")) {
+        const subdirName = relative.split("/")[0];
+        subdirs.add(normalizedPath + subdirName + "/");
+        continue;
+      }
+
+      const size = fd.content.join("\n").length;
+      infos.push({
+        path: k,
+        is_dir: false,
+        size: size,
+        modified_at: fd.modified_at,
+      });
+    }
+
+    for (const subdir of Array.from(subdirs).sort()) {
+      infos.push({
+        path: subdir,
+        is_dir: true,
+        size: 0,
+        modified_at: "",
+      });
+    }
+
+    infos.sort((a, b) => a.path.localeCompare(b.path));
+    return infos;
+  }
+
+  /**
+   * Read file content with line numbers.
+   */
+  read(filePath: string, offset: number = 0, limit: number = 2000): string {
+    const files = this.getFiles();
+    const fileData = files[filePath];
+
+    if (!fileData) {
+      return FILE_NOT_FOUND(filePath);
+    }
+
+    return formatReadResponse(fileData, offset, limit);
+  }
+
+  /**
+   * Read file content as raw FileData.
+   */
+  readRaw(filePath: string): FileData {
+    const files = this.getFiles();
+    const fileData = files[filePath];
+
+    if (!fileData) throw new Error(`File '${filePath}' not found`);
+    return fileData;
+  }
+
+  /**
+   * Create a new file with content.
+   */
+  write(filePath: string, content: string): WriteResult {
+    const files = this.getFiles();
+
+    // Validate file path
+    if (!filePath || filePath.trim() === "") {
+      return {
+        success: false,
+        error: "File path cannot be empty",
+      };
+    }
+
+    if (filePath in files) {
+      return {
+        success: false,
+        error: FILE_ALREADY_EXISTS(filePath),
+      };
+    }
+
+    const newFileData = createFileData(content);
+    this.state.files[filePath] = newFileData;
+    return { success: true, path: filePath };
+  }
+
+  /**
+   * Edit a file by replacing string occurrences.
+   */
+  edit(
+    filePath: string,
+    oldString: string,
+    newString: string,
+    replaceAll: boolean = false
+  ): EditResult {
+    const files = this.getFiles();
+    const fileData = files[filePath];
+
+    if (!fileData) {
+      return { success: false, error: FILE_NOT_FOUND(filePath) };
+    }
+
+    const content = fileDataToString(fileData);
+    const result = performStringReplacement(
+      content,
+      oldString,
+      newString,
+      replaceAll
+    );
+
+    if (typeof result === "string") {
+      return { success: false, error: result };
+    }
+
+    const [newContent, occurrences] = result;
+    const newFileData = updateFileData(fileData, newContent);
+    this.state.files[filePath] = newFileData;
+    return { success: true, path: filePath, occurrences };
+  }
+
+  /**
+   * Structured search results or error string for invalid input.
+   */
+  grepRaw(
+    pattern: string,
+    path: string = "/",
+    glob: string | null = null
+  ): GrepMatch[] | string {
+    const files = this.getFiles();
+    return grepMatchesFromFiles(files, pattern, path, glob);
+  }
+
+  /**
+   * Structured glob matching returning FileInfo objects.
+   */
+  globInfo(pattern: string, path: string = "/"): FileInfo[] {
+    const files = this.getFiles();
+    const result = globSearchFiles(files, pattern, path);
+
+    if (result === "No files found") {
+      return [];
+    }
+
+    const paths = result.split("\n");
+    const infos: FileInfo[] = [];
+    for (const p of paths) {
+      const fd = files[p];
+      const size = fd ? fd.content.join("\n").length : 0;
+      infos.push({
+        path: p,
+        is_dir: false,
+        size: size,
+        modified_at: fd?.modified_at || "",
+      });
+    }
+    return infos;
+  }
+}
+

package/src/backends/utils.ts

@@ -0,0 +1,287 @@
+/**
+ * Shared utility functions for memory backend implementations.
+ */
+
+import micromatch from "micromatch";
+import { basename } from "path";
+import type { FileData, GrepMatch } from "../types";
+import { SYSTEM_REMINDER_FILE_EMPTY, INVALID_REGEX } from "../constants/errors";
+import {
+  MAX_LINE_LENGTH,
+  LINE_NUMBER_WIDTH,
+  DEFAULT_EVICTION_TOKEN_LIMIT,
+} from "../constants/limits";
+
+// Constants
+export const EMPTY_CONTENT_WARNING = SYSTEM_REMINDER_FILE_EMPTY;
+// Re-export from limits for backward compatibility
+export { MAX_LINE_LENGTH, LINE_NUMBER_WIDTH };
+export const TOOL_RESULT_TOKEN_LIMIT = DEFAULT_EVICTION_TOKEN_LIMIT;
+export const TRUNCATION_GUIDANCE =
+  "... [results truncated, try being more specific with your parameters]";
+
+/**
+ * Format file content with line numbers (cat -n style).
+ */
+export function formatContentWithLineNumbers(
+  content: string | string[],
+  startLine: number = 1
+): string {
+  let lines: string[];
+  if (typeof content === "string") {
+    lines = content.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+      lines = lines.slice(0, -1);
+    }
+  } else {
+    lines = content;
+  }
+
+  const resultLines: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + startLine;
+
+    if (line && line.length <= MAX_LINE_LENGTH) {
+      resultLines.push(
+        `${lineNum.toString().padStart(LINE_NUMBER_WIDTH)}\t${line}`
+      );
+    } else if (line) {
+      // Split long line into chunks with continuation markers
+      const numChunks = Math.ceil(line.length / MAX_LINE_LENGTH);
+      for (let chunkIdx = 0; chunkIdx < numChunks; chunkIdx++) {
+        const start = chunkIdx * MAX_LINE_LENGTH;
+        const end = Math.min(start + MAX_LINE_LENGTH, line.length);
+        const chunk = line.substring(start, end);
+        if (chunkIdx === 0) {
+          resultLines.push(
+            `${lineNum.toString().padStart(LINE_NUMBER_WIDTH)}\t${chunk}`
+          );
+        } else {
+          const continuationMarker = `${lineNum}.${chunkIdx}`;
+          resultLines.push(
+            `${continuationMarker.padStart(LINE_NUMBER_WIDTH)}\t${chunk}`
+          );
+        }
+      }
+    } else {
+      resultLines.push(
+        `${lineNum.toString().padStart(LINE_NUMBER_WIDTH)}\t`
+      );
+    }
+  }
+
+  return resultLines.join("\n");
+}
+
+/**
+ * Check if content is empty and return warning message.
+ */
+export function checkEmptyContent(content: string): string | null {
+  if (!content || content.trim() === "") {
+    return EMPTY_CONTENT_WARNING;
+  }
+  return null;
+}
+
+/**
+ * Convert FileData to plain string content.
+ */
+export function fileDataToString(fileData: FileData): string {
+  return fileData.content.join("\n");
+}
+
+/**
+ * Create a FileData object with timestamps.
+ */
+export function createFileData(content: string, createdAt?: string): FileData {
+  const lines = typeof content === "string" ? content.split("\n") : content;
+  const now = new Date().toISOString();
+
+  return {
+    content: lines,
+    created_at: createdAt || now,
+    modified_at: now,
+  };
+}
+
+/**
+ * Update FileData with new content, preserving creation timestamp.
+ */
+export function updateFileData(fileData: FileData, content: string): FileData {
+  const lines = typeof content === "string" ? content.split("\n") : content;
+  const now = new Date().toISOString();
+
+  return {
+    content: lines,
+    created_at: fileData.created_at,
+    modified_at: now,
+  };
+}
+
+/**
+ * Format file data for read response with line numbers.
+ */
+export function formatReadResponse(
+  fileData: FileData,
+  offset: number,
+  limit: number
+): string {
+  const content = fileDataToString(fileData);
+  const emptyMsg = checkEmptyContent(content);
+  if (emptyMsg) {
+    return emptyMsg;
+  }
+
+  const lines = content.split("\n");
+  const startIdx = offset;
+  const endIdx = Math.min(startIdx + limit, lines.length);
+
+  if (startIdx >= lines.length) {
+    return `Error: Line offset ${offset} exceeds file length (${lines.length} lines)`;
+  }
+
+  const selectedLines = lines.slice(startIdx, endIdx);
+  return formatContentWithLineNumbers(selectedLines, startIdx + 1);
+}
+
+/**
+ * Perform string replacement with occurrence validation.
+ */
+export function performStringReplacement(
+  content: string,
+  oldString: string,
+  newString: string,
+  replaceAll: boolean
+): [string, number] | string {
+  const occurrences = content.split(oldString).length - 1;
+
+  if (occurrences === 0) {
+    return `Error: String not found in file: '${oldString}'`;
+  }
+
+  if (occurrences > 1 && !replaceAll) {
+    return `Error: String '${oldString}' appears ${occurrences} times in file. Use replace_all=true to replace all instances, or provide a more specific string with surrounding context.`;
+  }
+
+  const newContent = content.split(oldString).join(newString);
+  return [newContent, occurrences];
+}
+
+/**
+ * Validate and normalize a path.
+ */
+export function validatePath(path: string | null | undefined): string {
+  const pathStr = path || "/";
+  if (!pathStr || pathStr.trim() === "") {
+    throw new Error("Path cannot be empty");
+  }
+
+  let normalized = pathStr.startsWith("/") ? pathStr : "/" + pathStr;
+
+  if (!normalized.endsWith("/")) {
+    normalized += "/";
+  }
+
+  return normalized;
+}
+
+/**
+ * Search files dict for paths matching glob pattern.
+ */
+export function globSearchFiles(
+  files: Record<string, FileData>,
+  pattern: string,
+  path: string = "/"
+): string {
+  let normalizedPath: string;
+  try {
+    normalizedPath = validatePath(path);
+  } catch {
+    return "No files found";
+  }
+
+  const filtered = Object.fromEntries(
+    Object.entries(files).filter(([fp]) => fp.startsWith(normalizedPath))
+  );
+
+  const matches: Array<[string, string]> = [];
+  for (const [filePath, fileData] of Object.entries(filtered)) {
+    let relative = filePath.substring(normalizedPath.length);
+    if (relative.startsWith("/")) {
+      relative = relative.substring(1);
+    }
+    if (!relative) {
+      const parts = filePath.split("/");
+      relative = parts[parts.length - 1] || "";
+    }
+
+    if (
+      micromatch.isMatch(relative, pattern, {
+        dot: true,
+        nobrace: false,
+      })
+    ) {
+      matches.push([filePath, fileData.modified_at]);
+    }
+  }
+
+  matches.sort((a, b) => b[1].localeCompare(a[1]));
+
+  if (matches.length === 0) {
+    return "No files found";
+  }
+
+  return matches.map(([fp]) => fp).join("\n");
+}
+
+/**
+ * Return structured grep matches from an in-memory files mapping.
+ */
+export function grepMatchesFromFiles(
+  files: Record<string, FileData>,
+  pattern: string,
+  path: string | null = null,
+  glob: string | null = null
+): GrepMatch[] | string {
+  let regex: RegExp;
+  try {
+    regex = new RegExp(pattern);
+  } catch (e: unknown) {
+    const error = e as Error;
+    return INVALID_REGEX(error.message);
+  }
+
+  let normalizedPath: string;
+  try {
+    normalizedPath = validatePath(path);
+  } catch {
+    return [];
+  }
+
+  let filtered = Object.fromEntries(
+    Object.entries(files).filter(([fp]) => fp.startsWith(normalizedPath))
+  );
+
+  if (glob) {
+    filtered = Object.fromEntries(
+      Object.entries(filtered).filter(([fp]) =>
+        micromatch.isMatch(basename(fp), glob, { dot: true, nobrace: false })
+      )
+    );
+  }
+
+  const matches: GrepMatch[] = [];
+  for (const [filePath, fileData] of Object.entries(filtered)) {
+    for (let i = 0; i < fileData.content.length; i++) {
+      const line = fileData.content[i];
+      const lineNum = i + 1;
+      if (line && regex.test(line)) {
+        matches.push({ path: filePath, line: lineNum, text: line });
+      }
+    }
+  }
+
+  return matches;
+}
+

package/src/checkpointer/file-saver.ts

@@ -0,0 +1,98 @@
+/**
+ * File-based checkpoint saver for local development.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { Checkpoint, BaseCheckpointSaver } from "./types";
+
+/**
+ * Options for FileSaver.
+ */
+export interface FileSaverOptions {
+  /** Directory to store checkpoint files */
+  dir: string;
+}
+
+/**
+ * File-based checkpoint saver.
+ * 
+ * Stores checkpoints as JSON files in a directory. Each thread gets
+ * its own file named `{threadId}.json`.
+ * 
+ * @example
+ * ```typescript
+ * const saver = new FileSaver({ dir: './.checkpoints' });
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   checkpointer: saver,
+ * });
+ * ```
+ */
+export class FileSaver implements BaseCheckpointSaver {
+  private dir: string;
+
+  constructor(options: FileSaverOptions) {
+    this.dir = options.dir;
+    
+    // Ensure directory exists
+    if (!existsSync(this.dir)) {
+      mkdirSync(this.dir, { recursive: true });
+    }
+  }
+
+  private getFilePath(threadId: string): string {
+    // Sanitize threadId to be safe for filenames
+    const safeId = threadId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return join(this.dir, `${safeId}.json`);
+  }
+
+  async save(checkpoint: Checkpoint): Promise<void> {
+    const filePath = this.getFilePath(checkpoint.threadId);
+    const data = {
+      ...checkpoint,
+      updatedAt: new Date().toISOString(),
+    };
+    writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+  }
+
+  async load(threadId: string): Promise<Checkpoint | undefined> {
+    const filePath = this.getFilePath(threadId);
+    
+    if (!existsSync(filePath)) {
+      return undefined;
+    }
+    
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      return JSON.parse(content) as Checkpoint;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async list(): Promise<string[]> {
+    if (!existsSync(this.dir)) {
+      return [];
+    }
+    
+    const files = readdirSync(this.dir);
+    return files
+      .filter(f => f.endsWith('.json'))
+      .map(f => f.replace('.json', ''));
+  }
+
+  async delete(threadId: string): Promise<void> {
+    const filePath = this.getFilePath(threadId);
+    
+    if (existsSync(filePath)) {
+      unlinkSync(filePath);
+    }
+  }
+
+  async exists(threadId: string): Promise<boolean> {
+    const filePath = this.getFilePath(threadId);
+    return existsSync(filePath);
+  }
+}
+

package/src/checkpointer/index.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./memory-saver";
+export * from "./file-saver";
+export * from "./kv-saver";
+

package/src/checkpointer/kv-saver.ts

@@ -0,0 +1,82 @@
+/**
+ * Checkpoint saver using KeyValueStore interface.
+ * 
+ * Allows using existing KeyValueStore implementations (Redis, etc.)
+ * for checkpoint storage.
+ */
+
+import type { KeyValueStore } from "../backends/persistent";
+import type { Checkpoint, BaseCheckpointSaver, CheckpointSaverOptions } from "./types";
+
+/**
+ * Options for KeyValueStoreSaver.
+ */
+export interface KeyValueStoreSaverOptions extends CheckpointSaverOptions {
+  /** The KeyValueStore implementation to use */
+  store: KeyValueStore;
+}
+
+/**
+ * Checkpoint saver using KeyValueStore interface.
+ * 
+ * This adapter allows using any KeyValueStore implementation (Redis,
+ * database, cloud storage, etc.) for checkpoint storage.
+ * 
+ * @example
+ * ```typescript
+ * import { InMemoryStore } from 'deepagentsdk';
+ * 
+ * const store = new InMemoryStore();
+ * const saver = new KeyValueStoreSaver({ store });
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   checkpointer: saver,
+ * });
+ * ```
+ * 
+ * @example With Redis
+ * ```typescript
+ * const redisStore = new RedisStore(redisClient); // Your implementation
+ * const saver = new KeyValueStoreSaver({ store: redisStore });
+ * ```
+ */
+export class KeyValueStoreSaver implements BaseCheckpointSaver {
+  private store: KeyValueStore;
+  private namespace: string[];
+
+  constructor(options: KeyValueStoreSaverOptions) {
+    this.store = options.store;
+    this.namespace = [options.namespace || "default", "checkpoints"];
+  }
+
+  async save(checkpoint: Checkpoint): Promise<void> {
+    const data = {
+      ...checkpoint,
+      updatedAt: new Date().toISOString(),
+    };
+    await this.store.put(this.namespace, checkpoint.threadId, data as unknown as Record<string, unknown>);
+  }
+
+  async load(threadId: string): Promise<Checkpoint | undefined> {
+    const data = await this.store.get(this.namespace, threadId);
+    if (!data) {
+      return undefined;
+    }
+    return data as unknown as Checkpoint;
+  }
+
+  async list(): Promise<string[]> {
+    const items = await this.store.list(this.namespace);
+    return items.map(item => item.key);
+  }
+
+  async delete(threadId: string): Promise<void> {
+    await this.store.delete(this.namespace, threadId);
+  }
+
+  async exists(threadId: string): Promise<boolean> {
+    const data = await this.store.get(this.namespace, threadId);
+    return data !== undefined;
+  }
+}
+