fix: missing files in skillsMiddleware schema (#160)

* fix missing files in skillsMiddleware

* Update tests

* Add integration tests + fixes

* Restore skills.test.ts from main

* Update tests to unit from integration

* Update unit tests

* fix test

* changeset

Author: maahir30

.changeset/fix-skills-middleware.md

@@ -0,0 +1,9 @@
+---
+"deepagents": patch
+---
+
+fix(skills): properly restore skills from StateBackend checkpoint
+
+- Add `files` channel to `SkillsStateSchema` for StateBackend integration
+- Fix skills restoration check to require non-empty array instead of just non-null
+- Export `FileDataSchema` from fs middleware for reuse

libs/deepagents/src/middleware/skills.test.ts

@@ -9,6 +9,15 @@ import type {
   FileDownloadResponse,
   FileInfo,
 } from "../backends/protocol.js";
+import { createFileData } from "../backends/utils.js";
+import { createDeepAgent } from "../agent.js";
+import { FakeListChatModel } from "@langchain/core/utils/testing";
+import {
+  HumanMessage,
+  SystemMessage,
+  type BaseMessage,
+} from "@langchain/core/messages";
+import { MemorySaver } from "@langchain/langgraph";
 
 // Mock backend that returns specified files and directory listings
 function createMockBackend(config: {
@@ -672,3 +681,259 @@ describe("skillsMetadataReducer", () => {
     });
   });
 });
+
+/**
+ * StateBackend integration tests.
+ *
+ * These tests verify that skills are properly loaded from state.files and
+ * injected into the system prompt when using createDeepAgent with StateBackend.
+ */
+describe("StateBackend integration with createDeepAgent", () => {
+  const VALID_SKILL_MD = `---
+name: test-skill
+description: A test skill for StateBackend integration
+---
+
+# Test Skill
+
+Instructions for the test skill.
+`;
+
+  const ANOTHER_SKILL_MD = `---
+name: another-skill
+description: Another test skill
+---
+
+# Another Skill
+`;
+
+  /**
+   * Helper to extract system prompt content from model invoke spy.
+   * The system message can have content as string or array of content blocks.
+   */
+  function getSystemPromptFromSpy(
+    invokeSpy: ReturnType<typeof vi.spyOn>,
+  ): string {
+    const lastCall = invokeSpy.mock.calls[invokeSpy.mock.calls.length - 1];
+    const messages = lastCall?.[0] as BaseMessage[] | undefined;
+    if (!messages) return "";
+    const systemMessage = messages.find(SystemMessage.isInstance);
+    if (!systemMessage) return "";
+
+    return systemMessage.text;
+  }
+
+  it("should load skills from state.files and inject into system prompt", async () => {
+    const invokeSpy = vi.spyOn(FakeListChatModel.prototype, "invoke");
+    const model = new FakeListChatModel({ responses: ["Done"] });
+
+    const checkpointer = new MemorySaver();
+    const agent = createDeepAgent({
+      model: model as any,
+      skills: ["/skills/"],
+      checkpointer,
+    });
+
+    await agent.invoke(
+      {
+        messages: [new HumanMessage("What skills are available?")],
+        files: {
+          "/skills/test-skill/SKILL.md": createFileData(VALID_SKILL_MD),
+        },
+      } as any,
+      { configurable: { thread_id: `test-${Date.now()}` }, recursionLimit: 50 },
+    );
+
+    expect(invokeSpy).toHaveBeenCalled();
+    const systemPrompt = getSystemPromptFromSpy(invokeSpy);
+
+    // Verify skill was injected into system prompt
+    expect(systemPrompt).toContain("test-skill");
+    expect(systemPrompt).toContain("A test skill for StateBackend integration");
+    expect(systemPrompt).toContain("/skills/test-skill/SKILL.md");
+    invokeSpy.mockRestore();
+  });
+
+  it("should load multiple skills from state.files", async () => {
+    const invokeSpy = vi.spyOn(FakeListChatModel.prototype, "invoke");
+    const model = new FakeListChatModel({ responses: ["Done"] });
+
+    const checkpointer = new MemorySaver();
+    const agent = createDeepAgent({
+      model: model as any,
+      skills: ["/skills/"],
+      checkpointer,
+    });
+
+    await agent.invoke(
+      {
+        messages: [new HumanMessage("List all skills")],
+        files: {
+          "/skills/test-skill/SKILL.md": createFileData(VALID_SKILL_MD),
+          "/skills/another-skill/SKILL.md": createFileData(ANOTHER_SKILL_MD),
+        },
+      } as any,
+      {
+        configurable: { thread_id: `test-multi-${Date.now()}` },
+        recursionLimit: 50,
+      },
+    );
+
+    expect(invokeSpy).toHaveBeenCalled();
+    const systemPrompt = getSystemPromptFromSpy(invokeSpy);
+
+    // Verify both skills were injected
+    expect(systemPrompt).toContain("test-skill");
+    expect(systemPrompt).toContain("another-skill");
+    expect(systemPrompt).toContain("A test skill for StateBackend integration");
+    expect(systemPrompt).toContain("Another test skill");
+    invokeSpy.mockRestore();
+  });
+
+  it("should show no skills message when state.files is empty", async () => {
+    const invokeSpy = vi.spyOn(FakeListChatModel.prototype, "invoke");
+    const model = new FakeListChatModel({ responses: ["Done"] });
+
+    const checkpointer = new MemorySaver();
+    const agent = createDeepAgent({
+      model: model as any,
+      skills: ["/skills/"],
+      checkpointer,
+    });
+
+    await agent.invoke(
+      {
+        messages: [new HumanMessage("Hello")],
+        files: {},
+      } as any,
+      {
+        configurable: { thread_id: `test-empty-${Date.now()}` },
+        recursionLimit: 50,
+      },
+    );
+
+    expect(invokeSpy).toHaveBeenCalled();
+    const systemPrompt = getSystemPromptFromSpy(invokeSpy);
+
+    // Verify "no skills" message appears
+    expect(systemPrompt).toContain("No skills available yet");
+    expect(systemPrompt).toContain("/skills/");
+    invokeSpy.mockRestore();
+  });
+
+  it("should load skills from multiple sources via StateBackend", async () => {
+    const userSkillMd = `---
+name: user-skill
+description: User-level skill for personal workflows
+---
+# User Skill`;
+
+    const projectSkillMd = `---
+name: project-skill
+description: Project-level skill for team collaboration
+---
+# Project Skill`;
+
+    const invokeSpy = vi.spyOn(FakeListChatModel.prototype, "invoke");
+    const model = new FakeListChatModel({ responses: ["Done"] });
+
+    const checkpointer = new MemorySaver();
+    const agent = createDeepAgent({
+      model: model as any,
+      skills: ["/skills/user/", "/skills/project/"],
+      checkpointer,
+    });
+
+    await agent.invoke(
+      {
+        messages: [new HumanMessage("List skills")],
+        files: {
+          "/skills/user/user-skill/SKILL.md": createFileData(userSkillMd),
+          "/skills/project/project-skill/SKILL.md":
+            createFileData(projectSkillMd),
+        },
+      } as any,
+      {
+        configurable: { thread_id: `test-sources-${Date.now()}` },
+        recursionLimit: 50,
+      },
+    );
+
+    expect(invokeSpy).toHaveBeenCalled();
+    const systemPrompt = getSystemPromptFromSpy(invokeSpy);
+
+    // Verify both sources' skills are present
+    expect(systemPrompt).toContain("user-skill");
+    expect(systemPrompt).toContain("project-skill");
+    expect(systemPrompt).toContain("User-level skill");
+    expect(systemPrompt).toContain("Project-level skill");
+    invokeSpy.mockRestore();
+  });
+
+  it("should include skill paths for progressive disclosure", async () => {
+    const invokeSpy = vi.spyOn(FakeListChatModel.prototype, "invoke");
+    const model = new FakeListChatModel({ responses: ["Done"] });
+
+    const checkpointer = new MemorySaver();
+    const agent = createDeepAgent({
+      model: model as any,
+      skills: ["/skills/"],
+      checkpointer,
+    });
+
+    await agent.invoke(
+      {
+        messages: [new HumanMessage("What skills?")],
+        files: {
+          "/skills/test-skill/SKILL.md": createFileData(VALID_SKILL_MD),
+        },
+      } as any,
+      {
+        configurable: { thread_id: `test-paths-${Date.now()}` },
+        recursionLimit: 50,
+      },
+    );
+
+    expect(invokeSpy).toHaveBeenCalled();
+    const systemPrompt = getSystemPromptFromSpy(invokeSpy);
+
+    // Verify the full path is included for progressive disclosure
+    expect(systemPrompt).toContain("/skills/test-skill/SKILL.md");
+    // Verify progressive disclosure instructions are present
+    expect(systemPrompt).toContain("Progressive Disclosure");
+    invokeSpy.mockRestore();
+  });
+
+  it("should handle empty skills directory gracefully", async () => {
+    const invokeSpy = vi.spyOn(FakeListChatModel.prototype, "invoke");
+    const model = new FakeListChatModel({ responses: ["Done"] });
+
+    const checkpointer = new MemorySaver();
+    const agent = createDeepAgent({
+      model: model as any,
+      skills: ["/skills/empty/"],
+      checkpointer,
+    });
+
+    // Should not throw even when no skills exist (empty files)
+    await expect(
+      agent.invoke(
+        {
+          messages: [new HumanMessage("Hello")],
+          files: {},
+        } as any,
+        {
+          configurable: { thread_id: `test-empty-graceful-${Date.now()}` },
+          recursionLimit: 50,
+        },
+      ),
+    ).resolves.toBeDefined();
+
+    expect(invokeSpy).toHaveBeenCalled();
+    const systemPrompt = getSystemPromptFromSpy(invokeSpy);
+
+    // Should still have a system prompt with the "no skills" message
+    expect(systemPrompt).toContain("No skills available yet");
+    invokeSpy.mockRestore();
+  });
+});

libs/deepagents/src/middleware/skills.ts

@@ -54,6 +54,7 @@ import { StateSchema, ReducedValue } from "@langchain/langgraph";
 import type { BackendProtocol, BackendFactory } from "../backends/protocol.js";
 import type { StateBackend } from "../backends/state.js";
 import type { BaseStore } from "@langchain/langgraph-checkpoint";
+import { fileDataReducer, FileDataSchema } from "./fs.js";
 
 // Security: Maximum size for SKILL.md files to prevent DoS attacks (10MB)
 export const MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024;
@@ -170,6 +171,13 @@ const SkillsStateSchema = new StateSchema({
       reducer: skillsMetadataReducer,
     },
   ),
+  files: new ReducedValue(
+    z.record(z.string(), FileDataSchema).default(() => ({})),
+    {
+      inputSchema: z.record(z.string(), FileDataSchema.nullable()).optional(),
+      reducer: fileDataReducer,
+    },
+  ),
 });
 
 /**
@@ -513,7 +521,12 @@ export function createSkillsMiddleware(options: SkillsMiddlewareOptions) {
       if (loadedSkills.length > 0) {
         return undefined;
       }
-      if ("skillsMetadata" in state && state.skillsMetadata != null) {
+      // Check if skills were restored from checkpoint (non-empty array in state)
+      if (
+        "skillsMetadata" in state &&
+        Array.isArray(state.skillsMetadata) &&
+        state.skillsMetadata.length > 0
+      ) {
         // Restore from state (e.g., after checkpoint restore)
         loadedSkills = state.skillsMetadata as SkillMetadata[];
         return undefined;