fix(deepagents): fix type issues (#174)

* fix(deepagents): fix type issues

* fix types

* minor tweak

Author: christian-bromann

libs/deepagents/src/agent.test-d.ts

@@ -25,7 +25,7 @@ import type {
   InferCompiledSubagents,
   InferRegularSubagents,
 } from "./types.js";
-import type { FileData } from "./backends/protocol.js";
+import type { FilesRecordUpdate } from "./middleware/fs.js";
 
 // Test middleware with research state
 const ResearchStateSchema = z.object({
@@ -134,7 +134,7 @@ describe("createDeepAgent types", () => {
       expectTypeOf(result.counter).toEqualTypeOf<number>();
       // should have built-in state
       expectTypeOf(result).toHaveProperty("files");
-      expectTypeOf(result.files).toEqualTypeOf<Record<string, FileData>>();
+      expectTypeOf(result.files).toEqualTypeOf<FilesRecordUpdate | undefined>();
       expectTypeOf(result).toHaveProperty("todos");
       expectTypeOf(result.todos).toEqualTypeOf<
         {

libs/deepagents/src/agent.ts

@@ -111,7 +111,9 @@ export function createDeepAgent<
     skills,
   } = params;
 
-  // Combine system prompt with base prompt like Python implementation
+  /**
+   * Combine system prompt with base prompt like Python implementation
+   */
   const finalSystemPrompt = systemPrompt
     ? typeof systemPrompt === "string"
       ? `${systemPrompt}\n\n${BASE_PROMPT}`
@@ -128,15 +130,19 @@ export function createDeepAgent<
         })
     : BASE_PROMPT;
 
-  // Create backend configuration for filesystem middleware
-  // If no backend is provided, use a factory that creates a StateBackend
+  /**
+   * Create backend configuration for filesystem middleware
+   * If no backend is provided, use a factory that creates a StateBackend
+   */
   const filesystemBackend = backend
     ? backend
     : (config: { state: unknown; store?: BaseStore }) =>
         new StateBackend(config);
 
-  // Add skills middleware if skill sources provided
-  const skillsMiddleware =
+  /**
+   * Skills middleware (created conditionally for runtime use)
+   */
+  const skillsMiddlewareArray =
     skills != null && skills.length > 0
       ? [
           createSkillsMiddleware({
@@ -146,111 +152,144 @@ export function createDeepAgent<
         ]
       : [];
 
-  // Built-in middleware array
+  /**
+   * Memory middleware (created conditionally for runtime use)
+   */
+  const memoryMiddlewareArray =
+    memory != null && memory.length > 0
+      ? [
+          createMemoryMiddleware({
+            backend: filesystemBackend,
+            sources: memory,
+          }),
+        ]
+      : [];
+
+  /**
+   * Built-in middleware array - core middleware with known types
+   * This tuple is typed without conditional spreads to preserve TypeScript's tuple inference.
+   * Optional middleware (skills, memory, HITL) are handled at runtime but typed explicitly.
+   */
   const builtInMiddleware = [
-    // Provides todo list management capabilities for tracking tasks
+    /**
+     * Provides todo list management capabilities for tracking tasks
+     */
     todoListMiddleware(),
-    // Add skills middleware if skill sources provided
-    ...skillsMiddleware,
-    // Enables filesystem operations and optional long-term memory storage
+    /**
+     * Enables filesystem operations and optional long-term memory storage
+     */
     createFilesystemMiddleware({ backend: filesystemBackend }),
-    // Enables delegation to specialized subagents for complex tasks
+    /**
+     * Enables delegation to specialized subagents for complex tasks
+     */
     createSubAgentMiddleware({
       defaultModel: model,
       defaultTools: tools as StructuredTool[],
       defaultMiddleware: [
-        // Subagent middleware: Todo list management
+        /**
+         * Subagent middleware: Todo list management
+         */
         todoListMiddleware(),
-        // Subagent middleware: Skills (if provided)
-        ...skillsMiddleware,
-        // Subagent middleware: Filesystem operations
+        /**
+         * Subagent middleware: Skills (if provided) - added at runtime
+         */
+        ...skillsMiddlewareArray,
+        /**
+         * Subagent middleware: Filesystem operations
+         */
         createFilesystemMiddleware({
           backend: filesystemBackend,
         }),
-        // Subagent middleware: Automatic conversation summarization when token limits are approached
+        /**
+         * Subagent middleware: Automatic conversation summarization when token limits are approached
+         */
         summarizationMiddleware({
           model,
           trigger: { tokens: 170_000 },
           keep: { messages: 6 },
         }),
-        // Subagent middleware: Anthropic prompt caching for improved performance
+        /**
+         * Subagent middleware: Anthropic prompt caching for improved performance
+         */
         anthropicPromptCachingMiddleware({
           unsupportedModelBehavior: "ignore",
         }),
-        // Subagent middleware: Patches tool calls for compatibility
+        /**
+         * Subagent middleware: Patches tool calls for compatibility
+         */
         createPatchToolCallsMiddleware(),
       ],
       defaultInterruptOn: interruptOn,
       subagents: subagents as unknown as (SubAgent | CompiledSubAgent)[],
       generalPurposeAgent: true,
     }),
-    // Automatically summarizes conversation history when token limits are approached
+    /**
+     * Automatically summarizes conversation history when token limits are approached
+     */
     summarizationMiddleware({
       model,
       trigger: { tokens: 170_000 },
       keep: { messages: 6 },
     }),
-    // Enables Anthropic prompt caching for improved performance and reduced costs
+    /**
+     * Enables Anthropic prompt caching for improved performance and reduced costs
+     */
     anthropicPromptCachingMiddleware({
       unsupportedModelBehavior: "ignore",
     }),
-    // Patches tool calls to ensure compatibility across different model providers
+    /**
+     * Patches tool calls to ensure compatibility across different model providers
+     */
     createPatchToolCallsMiddleware(),
-    // Add memory middleware if memory sources provided
-    ...(memory != null && memory.length > 0
-      ? [
-          createMemoryMiddleware({
-            backend: filesystemBackend,
-            sources: memory,
-          }),
-        ]
-      : []),
   ] as const;
 
-  // Add human-in-the-loop middleware if interrupt config provided
-  if (interruptOn) {
-    // builtInMiddleware is typed as readonly to enable type inference
-    // however, we need to push to it to add the middleware, so let's ignore the type error
-    // @ts-expect-error - builtInMiddleware is readonly
-    builtInMiddleware.push(humanInTheLoopMiddleware({ interruptOn }));
-  }
-
-  // Combine built-in middleware with custom middleware
-  // The custom middleware is typed as TMiddleware to preserve type information
-  const allMiddleware = [
+  /**
+   * Runtime middleware array: combine built-in + optional middleware
+   * Note: The type is handled separately via AllMiddleware type alias
+   */
+  const runtimeMiddleware: AgentMiddleware[] = [
     ...builtInMiddleware,
-    ...(customMiddleware as unknown as TMiddleware),
-  ] as const;
+    ...skillsMiddlewareArray,
+    ...memoryMiddlewareArray,
+    ...(interruptOn ? [humanInTheLoopMiddleware({ interruptOn })] : []),
+    ...(customMiddleware as unknown as AgentMiddleware[]),
+  ];
 
-  // Note: Recursion limit of 1000 (matching Python behavior) should be passed
-  // at invocation time: agent.invoke(input, { recursionLimit: 1000 })
+  /**
+   * Note: Recursion limit of 1000 (matching Python behavior) should be passed
+   * at invocation time: agent.invoke(input, { recursionLimit: 1000 })
+   */
   const agent = createAgent({
     model,
     systemPrompt: finalSystemPrompt,
     tools: tools as StructuredTool[],
-    middleware: allMiddleware as unknown as AgentMiddleware[],
+    middleware: runtimeMiddleware,
     responseFormat: responseFormat as ResponseFormat,
     contextSchema,
     checkpointer,
     store,
     name,
   });
 
-  // Combine custom middleware with flattened subagent middleware for complete type inference
-  // This ensures InferMiddlewareStates captures state from both sources
+  /**
+   * Combine custom middleware with flattened subagent middleware for complete type inference
+   * This ensures InferMiddlewareStates captures state from both sources
+   */
   type AllMiddleware = readonly [
     ...typeof builtInMiddleware,
     ...TMiddleware,
     ...FlattenSubAgentMiddleware<TSubagents>,
   ];
 
-  // Return as DeepAgent with proper DeepAgentTypeConfig
-  // - Response: TResponse (from responseFormat parameter)
-  // - State: undefined (state comes from middleware)
-  // - Context: ContextSchema
-  // - Middleware: AllMiddleware (built-in + custom + subagent middleware for state inference)
-  // - Tools: TTools
-  // - Subagents: TSubagents (for type-safe streaming)
+  /**
+   * Return as DeepAgent with proper DeepAgentTypeConfig
+   * - Response: TResponse (from responseFormat parameter)
+   * - State: undefined (state comes from middleware)
+   * - Context: ContextSchema
+   * - Middleware: AllMiddleware (built-in + custom + subagent middleware for state inference)
+   * - Tools: TTools
+   * - Subagents: TSubagents (for type-safe streaming)
+   */
   return agent as unknown as DeepAgent<
     DeepAgentTypeConfig<
       TResponse,

libs/deepagents/src/backends/protocol.test.ts

@@ -98,7 +98,7 @@ describe("Protocol Types", () => {
 
 describe("isSandboxBackend", () => {
   it("should return true for backends with execute function and id string", () => {
-    const sandboxBackend: SandboxBackendProtocol = {
+    const sandboxBackend = {
       id: "test-sandbox",
       execute: async () => ({ output: "", exitCode: 0, truncated: false }),
       lsInfo: async () => [],
@@ -109,13 +109,13 @@ describe("isSandboxBackend", () => {
       edit: async () => ({ path: "" }),
       uploadFiles: async () => [],
       downloadFiles: async () => [],
-    };
+    } as unknown as SandboxBackendProtocol;
 
     expect(isSandboxBackend(sandboxBackend)).toBe(true);
   });
 
   it("should return false for backends without execute", () => {
-    const nonSandboxBackend: BackendProtocol = {
+    const nonSandboxBackend = {
       lsInfo: async () => [],
       read: async () => "",
       grepRaw: async () => [],
@@ -124,7 +124,7 @@ describe("isSandboxBackend", () => {
       edit: async () => ({ path: "" }),
       uploadFiles: async () => [],
       downloadFiles: async () => [],
-    };
+    } as unknown as BackendProtocol;
 
     expect(isSandboxBackend(nonSandboxBackend)).toBe(false);
   });