deepagents 1.4.2 → 1.5.1

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import * as zod_v30 from "zod/v3";
-import { z } from "zod/v3";
 import * as langchain9 from "langchain";
 import { AgentMiddleware, AgentMiddleware as AgentMiddleware$1, AgentTypeConfig, InferMiddlewareStates, InterruptOnConfig, ReactAgent, ResponseFormat, ResponseFormatUndefined, StructuredTool, SystemMessage, ToolMessage } from "langchain";
 import * as zod0 from "zod";
+import { z } from "zod";
 import * as zod_v4_core0 from "zod/v4/core";
 import { BaseCheckpointSaver, BaseStore } from "@langchain/langgraph-checkpoint";
 import * as _langchain_core_language_models_base0 from "@langchain/core/language_models/base";
@@ -163,7 +163,7 @@ interface BackendProtocol {
    *
    * @param filePath - Absolute file path
    * @param offset - Line offset to start reading from (0-indexed), default 0
-   * @param limit - Maximum number of lines to read, default 2000
+   * @param limit - Maximum number of lines to read, default 500
    * @returns Formatted file content with line numbers, or error message
    */
   read(filePath: string, offset?: number, limit?: number): MaybePromise<string>;
@@ -213,18 +213,20 @@ interface BackendProtocol {
   edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): MaybePromise<EditResult>;
   /**
    * Upload multiple files.
+   * Optional - backends that don't support file upload can omit this.
    *
    * @param files - List of [path, content] tuples to upload
    * @returns List of FileUploadResponse objects, one per input file
    */
-  uploadFiles(files: Array<[string, Uint8Array]>): MaybePromise<FileUploadResponse[]>;
+  uploadFiles?(files: Array<[string, Uint8Array]>): MaybePromise<FileUploadResponse[]>;
   /**
    * Download multiple files.
+   * Optional - backends that don't support file download can omit this.
    *
    * @param paths - List of file paths to download
    * @returns List of FileDownloadResponse objects, one per input path
    */
-  downloadFiles(paths: string[]): MaybePromise<FileDownloadResponse[]>;
+  downloadFiles?(paths: string[]): MaybePromise<FileDownloadResponse[]>;
 }
 /**
  * Protocol for sandboxed backends with isolated runtime.
@@ -442,16 +444,10 @@ interface SubAgentMiddlewareOptions {
 /**
  * Create subagent middleware with task tool
  */
-declare function createSubAgentMiddleware(options: SubAgentMiddlewareOptions): AgentMiddleware$1<undefined, undefined, unknown, readonly [langchain9.DynamicStructuredTool<z.ZodObject<{
-  description: z.ZodString;
-  subagent_type: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-  description: string;
-  subagent_type: string;
-}, {
-  description: string;
-  subagent_type: string;
-}>, {
+declare function createSubAgentMiddleware(options: SubAgentMiddlewareOptions): AgentMiddleware$1<undefined, undefined, unknown, readonly [langchain9.DynamicStructuredTool<z$1.ZodObject<{
+  description: z$1.ZodString;
+  subagent_type: z$1.ZodString;
+}, z$1.core.$strip>, {
   description: string;
   subagent_type: string;
 }, {
@@ -564,6 +560,123 @@ declare class StateBackend implements BackendProtocol {
   downloadFiles(paths: string[]): FileDownloadResponse[];
 }
 //#endregion
+//#region src/middleware/memory.d.ts
+/**
+ * Options for the memory middleware.
+ */
+interface MemoryMiddlewareOptions {
+  /**
+   * Backend instance or factory function for file operations.
+   * Use a factory for StateBackend since it requires runtime state.
+   */
+  backend: BackendProtocol | BackendFactory | ((config: {
+    state: unknown;
+    store?: BaseStore;
+  }) => StateBackend);
+  /**
+   * List of memory file paths to load (e.g., ["~/.deepagents/AGENTS.md", "./.deepagents/AGENTS.md"]).
+   * Display names are automatically derived from the paths.
+   * Sources are loaded in order.
+   */
+  sources: string[];
+}
+/**
+ * Create middleware for loading agent memory from AGENTS.md files.
+ *
+ * Loads memory content from configured sources and injects into the system prompt.
+ * Supports multiple sources that are combined together.
+ *
+ * @param options - Configuration options
+ * @returns AgentMiddleware for memory loading and injection
+ *
+ * @example
+ * ```typescript
+ * const middleware = createMemoryMiddleware({
+ *   backend: new FilesystemBackend({ rootDir: "/" }),
+ *   sources: [
+ *     "~/.deepagents/AGENTS.md",
+ *     "./.deepagents/AGENTS.md",
+ *   ],
+ * });
+ * ```
+ */
+declare function createMemoryMiddleware(options: MemoryMiddlewareOptions): AgentMiddleware<z.ZodObject<{
+  memoryContents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>, undefined, unknown, readonly (_langchain_core_tools3.ClientTool | _langchain_core_tools3.ServerTool)[]>;
+//#endregion
+//#region src/middleware/skills.d.ts
+declare const MAX_SKILL_FILE_SIZE: number;
+declare const MAX_SKILL_NAME_LENGTH = 64;
+declare const MAX_SKILL_DESCRIPTION_LENGTH = 1024;
+/**
+ * Metadata for a skill per Agent Skills specification.
+ */
+interface SkillMetadata$1 {
+  /** Skill identifier (max 64 chars, lowercase alphanumeric and hyphens) */
+  name: string;
+  /** What the skill does (max 1024 chars) */
+  description: string;
+  /** Path to the SKILL.md file in the backend */
+  path: string;
+  /** License name or reference to bundled license file */
+  license?: string | null;
+  /** Environment requirements (max 500 chars) */
+  compatibility?: string | null;
+  /** Arbitrary key-value mapping for additional metadata */
+  metadata?: Record<string, string>;
+  /** List of pre-approved tools (experimental) */
+  allowedTools?: string[];
+}
+/**
+ * Options for the skills middleware.
+ */
+interface SkillsMiddlewareOptions {
+  /**
+   * Backend instance or factory function for file operations.
+   * Use a factory for StateBackend since it requires runtime state.
+   */
+  backend: BackendProtocol | BackendFactory | ((config: {
+    state: unknown;
+    store?: BaseStore;
+  }) => StateBackend);
+  /**
+   * List of skill source paths to load (e.g., ["/skills/user/", "/skills/project/"]).
+   * Paths must use POSIX conventions (forward slashes).
+   * Later sources override earlier ones for skills with the same name (last one wins).
+   */
+  sources: string[];
+}
+/**
+ * Create backend-agnostic middleware for loading and exposing agent skills.
+ *
+ * This middleware loads skills from configurable backend sources and injects
+ * skill metadata into the system prompt. It implements the progressive disclosure
+ * pattern: skill names and descriptions are shown in the prompt, but the agent
+ * reads full SKILL.md content only when needed.
+ *
+ * @param options - Configuration options
+ * @returns AgentMiddleware for skills loading and injection
+ *
+ * @example
+ * ```typescript
+ * const middleware = createSkillsMiddleware({
+ *   backend: new FilesystemBackend({ rootDir: "/" }),
+ *   sources: ["/skills/user/", "/skills/project/"],
+ * });
+ * ```
+ */
+declare function createSkillsMiddleware(options: SkillsMiddlewareOptions): AgentMiddleware<z.ZodObject<{
+  skillsMetadata: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    path: z.ZodString;
+    license: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    compatibility: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strip>>>;
+}, z.core.$strip>, undefined, unknown, readonly (_langchain_core_tools3.ClientTool | _langchain_core_tools3.ServerTool)[]>;
+//#endregion
 //#region src/backends/store.d.ts
 /**
  * Backend that stores files in LangGraph's BaseStore (persistent).
@@ -1132,6 +1245,44 @@ interface CreateDeepAgentParams<TResponse extends ResponseFormat = ResponseForma
   interruptOn?: Record<string, boolean | InterruptOnConfig>;
   /** The name of the agent */
   name?: string;
+  /**
+   * Optional list of memory file paths (AGENTS.md files) to load
+   * (e.g., ["~/.deepagents/AGENTS.md", "./.deepagents/AGENTS.md"]).
+   * Display names are automatically derived from paths.
+   * Memory is loaded at agent startup and added into the system prompt.
+   */
+  memory?: string[];
+  /**
+   * Optional list of skill source paths (e.g., `["/skills/user/", "/skills/project/"]`).
+   *
+   * Paths use POSIX conventions (forward slashes) and are relative to the backend's root.
+   * Later sources override earlier ones for skills with the same name (last one wins).
+   *
+   * @example
+   * ```typescript
+   * // With FilesystemBackend - skills loaded from disk
+   * const agent = await createDeepAgent({
+   *   backend: new FilesystemBackend({ rootDir: "/home/user/.deepagents" }),
+   *   skills: ["/skills/"],
+   * });
+   *
+   * // With StateBackend - skills provided in state
+   * const agent = await createDeepAgent({
+   *   skills: ["/skills/"],
+   * });
+   * const result = await agent.invoke({
+   *   messages: [...],
+   *   files: {
+   *     "/skills/my-skill/SKILL.md": {
+   *       content: ["---", "name: my-skill", "description: ...", "---", "# My Skill"],
+   *       created_at: new Date().toISOString(),
+   *       modified_at: new Date().toISOString(),
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  skills?: string[];
 }
 //#endregion
 //#region src/agent.d.ts
@@ -1224,7 +1375,17 @@ declare function createDeepAgent<TResponse extends ResponseFormat = ResponseForm
     status: "completed" | "in_progress" | "pending";
   }[];
   messages: _messages.ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>>[];
-}, string>, "write_todos">]>, AgentMiddleware<zod0.ZodObject<{
+}, string>, "write_todos">]>, ...(AgentMiddleware<zod0.ZodObject<{
+  skillsMetadata: zod0.ZodOptional<zod0.ZodArray<zod0.ZodObject<{
+    name: zod0.ZodString;
+    description: zod0.ZodString;
+    path: zod0.ZodString;
+    license: zod0.ZodOptional<zod0.ZodNullable<zod0.ZodString>>;
+    compatibility: zod0.ZodOptional<zod0.ZodNullable<zod0.ZodString>>;
+    metadata: zod0.ZodOptional<zod0.ZodRecord<zod0.ZodString, zod0.ZodString>>;
+    allowedTools: zod0.ZodOptional<zod0.ZodArray<zod0.ZodString>>;
+  }, zod_v4_core0.$strip>>>;
+}, zod_v4_core0.$strip>, undefined, unknown, readonly (ClientTool | ServerTool)[]> | AgentMiddleware<zod0.ZodObject<{
   files: zod0.ZodDefault<zod0.ZodRecord<zod0.ZodString, zod0.ZodObject<{
     content: zod0.ZodArray<zod0.ZodString>;
     created_at: zod0.ZodString;
@@ -1305,22 +1466,7 @@ declare function createDeepAgent<TResponse extends ResponseFormat = ResponseForm
   command: string;
 }, {
   command: string;
-}, string, "execute">)[]>, AgentMiddleware<undefined, undefined, unknown, readonly [langchain9.DynamicStructuredTool<zod_v30.ZodObject<{
-  description: zod_v30.ZodString;
-  subagent_type: zod_v30.ZodString;
-}, "strip", zod_v30.ZodTypeAny, {
-  description: string;
-  subagent_type: string;
-}, {
-  description: string;
-  subagent_type: string;
-}>, {
-  description: string;
-  subagent_type: string;
-}, {
-  description: string;
-  subagent_type: string;
-}, string | _Command.Command<unknown, Record<string, unknown>, string>, "task">]>, AgentMiddleware<undefined, zod_v30.ZodObject<{
+}, string, "execute">)[]> | AgentMiddleware<undefined, zod_v30.ZodObject<{
   trigger: zod_v30.ZodOptional<zod_v30.ZodUnion<[zod_v30.ZodEffects<zod_v30.ZodObject<{
     fraction: zod_v30.ZodOptional<zod_v30.ZodNumber>;
     tokens: zod_v30.ZodOptional<zod_v30.ZodNumber>;
@@ -1457,7 +1603,7 @@ declare function createDeepAgent<TResponse extends ResponseFormat = ResponseForm
   maxTokensBeforeSummary?: number | undefined;
   messagesToKeep?: number | undefined;
   model?: _langchain_core_language_models_base0.BaseLanguageModel<any, _langchain_core_language_models_base0.BaseLanguageModelCallOptions> | undefined;
-}, readonly (ClientTool | ServerTool)[]>, AgentMiddleware<undefined, zod_v30.ZodObject<{
+}, readonly (ClientTool | ServerTool)[]> | AgentMiddleware<undefined, zod_v30.ZodObject<{
   enableCaching: zod_v30.ZodOptional<zod_v30.ZodBoolean>;
   ttl: zod_v30.ZodOptional<zod_v30.ZodEnum<["5m", "1h"]>>;
   minMessagesToCache: zod_v30.ZodOptional<zod_v30.ZodNumber>;
@@ -1477,7 +1623,18 @@ declare function createDeepAgent<TResponse extends ResponseFormat = ResponseForm
   ttl?: "1h" | "5m" | undefined;
   minMessagesToCache?: number | undefined;
   unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
-}, readonly (ClientTool | ServerTool)[]>, AgentMiddleware<undefined, undefined, unknown, readonly (ClientTool | ServerTool)[]>, ...TMiddleware, ...FlattenSubAgentMiddleware<TSubagents>], TTools, TSubagents>>;
+}, readonly (ClientTool | ServerTool)[]> | AgentMiddleware<undefined, undefined, unknown, readonly (ClientTool | ServerTool)[]> | AgentMiddleware<undefined, undefined, unknown, readonly [langchain9.DynamicStructuredTool<zod0.ZodObject<{
+  description: zod0.ZodString;
+  subagent_type: zod0.ZodString;
+}, zod_v4_core0.$strip>, {
+  description: string;
+  subagent_type: string;
+}, {
+  description: string;
+  subagent_type: string;
+}, string | _Command.Command<unknown, Record<string, unknown>, string>, "task">]> | AgentMiddleware<zod0.ZodObject<{
+  memoryContents: zod0.ZodOptional<zod0.ZodRecord<zod0.ZodString, zod0.ZodString>>;
+}, zod_v4_core0.$strip>, undefined, unknown, readonly (ClientTool | ServerTool)[]>)[], ...TMiddleware, ...FlattenSubAgentMiddleware<TSubagents>], TTools, TSubagents>>;
 //#endregion
 //#region src/config.d.ts
 /**
@@ -1580,36 +1737,6 @@ declare function findProjectRoot(startPath?: string): string | null;
  */
 declare function createSettings(options?: SettingsOptions): Settings;
 //#endregion
-//#region src/middleware/skills.d.ts
-/**
- * Options for the skills middleware.
- */
-interface SkillsMiddlewareOptions {
-  /** Path to the user-level skills directory (per-agent) */
-  skillsDir: string;
-  /** The agent identifier for path references in prompts */
-  assistantId: string;
-  /** Optional path to project-level skills directory */
-  projectSkillsDir?: string;
-}
-/**
- * Create middleware for loading and exposing agent skills.
- *
- * This middleware implements Anthropic's agent skills pattern:
- * - Loads skills metadata (name, description) from YAML frontmatter at session start
- * - Injects skills list into system prompt for discoverability
- * - Agent reads full SKILL.md content when a skill is relevant (progressive disclosure)
- *
- * Supports both user-level and project-level skills:
- * - User skills: ~/.deepagents/{AGENT_NAME}/skills/
- * - Project skills: {PROJECT_ROOT}/.deepagents/skills/
- * - Project skills override user skills with the same name
- *
- * @param options - Configuration options
- * @returns AgentMiddleware for skills loading and injection
- */
-declare function createSkillsMiddleware(options: SkillsMiddlewareOptions): AgentMiddleware<any, undefined, unknown, readonly (_langchain_core_tools3.ClientTool | _langchain_core_tools3.ServerTool)[]>;
-//#endregion
 //#region src/middleware/agent-memory.d.ts
 /**
  * Options for the agent memory middleware.
@@ -1635,36 +1762,6 @@ interface AgentMemoryMiddlewareOptions {
 declare function createAgentMemoryMiddleware(options: AgentMemoryMiddlewareOptions): AgentMiddleware<any, undefined, unknown, readonly (_langchain_core_tools3.ClientTool | _langchain_core_tools3.ServerTool)[]>;
 //#endregion
 //#region src/skills/loader.d.ts
-/**
- * Skill loader for parsing and loading agent skills from SKILL.md files.
- *
- * This module implements Anthropic's agent skills pattern with YAML frontmatter parsing.
- * Each skill is a directory containing a SKILL.md file with:
- * - YAML frontmatter (name, description required)
- * - Markdown instructions for the agent
- * - Optional supporting files (scripts, configs, etc.)
- *
- * @example
- * ```markdown
- * ---
- * name: web-research
- * description: Structured approach to conducting thorough web research
- * ---
- *
- * # Web Research Skill
- *
- * ## When to Use
- * - User asks you to research a topic
- * ...
- * ```
- *
- * @see https://agentskills.io/specification
- */
-/** Maximum size for SKILL.md files (10MB) */
-declare const MAX_SKILL_FILE_SIZE: number;
-/** Agent Skills spec constraints */
-declare const MAX_SKILL_NAME_LENGTH = 64;
-declare const MAX_SKILL_DESCRIPTION_LENGTH = 1024;
 /**
  * Metadata for a skill per Agent Skills spec.
  * @see https://agentskills.io/specification
@@ -1716,5 +1813,5 @@ declare function parseSkillMetadata(skillMdPath: string, source: "user" | "proje
  */
 declare function listSkills(options: ListSkillsOptions): SkillMetadata[];
 //#endregion
-export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type Settings, type SettingsOptions, type SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, type WriteResult, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
+export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, type WriteResult, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
 //# sourceMappingURL=index.d.cts.map