@node-llm/orm 0.3.0 → 0.5.0

package/src/adapters/prisma/Chat.ts

@@ -68,7 +68,8 @@ export class Chat extends BaseChat {
 
     const coreChat = llmInstance.chat(model || undefined, {
       messages: history,
-      ...this.localOptions
+      ...this.localOptions,
+      middlewares: this.customMiddlewares
     }) as any;
 
     // Register tools
@@ -333,17 +334,39 @@ export class Chat extends BaseChat {
   }
 }
 
+/**
+ * Helper to find the correct table property in the prisma client.
+ * Prisma usually camelCases model names (e.g., AssistantChat -> assistantChat),
+ * but mapping can vary based on configuration.
+ */
+function getTable(prisma: any, tableName: string): any {
+  if (prisma[tableName]) return prisma[tableName];
+
+  // Try case-insensitive match if not found directly
+  const keys = Object.keys(prisma).filter((k) => !k.startsWith("$") && !k.startsWith("_"));
+  const match = keys.find((k) => k.toLowerCase() === tableName.toLowerCase());
+
+  if (match) return prisma[match];
+
+  // If still not found, search for the model name if it's different from the property name
+  // but for now, we'll just throw a clear error
+  throw new Error(
+    `[@node-llm/orm] Prisma table "${tableName}" not found. Available tables: ${keys.join(", ")}`
+  );
+}
+
 /**
  * Convenience method to create a new chat session.
  */
 export async function createChat<T = Record<string, any>>(
-  prisma: PrismaClient,
+  prisma: any,
   llm: NodeLLMCore,
   options: ChatOptions & { tableNames?: TableNames } & T = {} as any
 ): Promise<Chat> {
   const chatTable = options.tableNames?.chat || "llmChat";
 
   // Extract known options so we don't double-pass them or pass them incorrectly
+  // runtime options should NOT be persisted to DB
   const {
     model,
     provider,
@@ -352,16 +375,32 @@ export async function createChat<T = Record<string, any>>(
     tableNames: _tableNames,
     debug: _debug,
     persistence: _persistence,
+    middlewares: _middlewares,
+    maxToolCalls: _maxToolCalls,
+    thinking: _thinking,
+    temperature: _temperature,
+    maxTokens: _maxTokens,
+    headers: _headers,
+    requestTimeout: _requestTimeout,
+    params: _params,
     ...extras
   } = options;
 
-  const record = await (prisma as any)[chatTable].create({
+  if (options.debug) {
+    const keys = Object.keys(prisma).filter((k) => !k.startsWith("$") && !k.startsWith("_"));
+    console.log(
+      `[@node-llm/orm] createChat: table=${chatTable}, availableTables=${keys.join(", ")}`
+    );
+  }
+
+  const table = getTable(prisma, chatTable);
+  const record = await table.create({
     data: {
       model,
       provider,
       instructions,
       metadata: metadata ?? null,
-      ...extras
+      ...(extras as any)
     }
   });
 
@@ -372,16 +411,25 @@ export async function createChat<T = Record<string, any>>(
  * Convenience method to load an existing chat session.
  */
 export async function loadChat(
-  prisma: PrismaClient,
+  prisma: any,
   llm: NodeLLMCore,
   chatId: string,
-  options: ChatOptions & { tableNames?: TableNames } = {}
+  options: ChatOptions & { tableNames?: TableNames; debug?: boolean } = {}
 ): Promise<Chat | null> {
   const chatTable = options.tableNames?.chat || "llmChat";
-  const record = await (prisma as any)[chatTable].findUnique({
+
+  if (options.debug) {
+    const keys = Object.keys(prisma).filter((k) => !k.startsWith("$") && !k.startsWith("_"));
+    console.log(`[@node-llm/orm] loadChat: table=${chatTable}, availableTables=${keys.join(", ")}`);
+  }
+
+  const table = getTable(prisma, chatTable);
+  const record = await table.findUnique({
     where: { id: chatId }
   });
 
   if (!record) return null;
+
+  // Reconstruct chat with options from DB or manual overrides if needed
   return new Chat(prisma, llm, record, options, options.tableNames);
 }

package/src/adapters/prisma/index.ts

@@ -4,7 +4,7 @@
  * Prisma adapter for NodeLLM ORM.
  * Provides automatic persistence of chats, messages, tool calls, and API requests.
  *
- * @example
+ * @example Chat API (low-level)
  * ```typescript
  * import { PrismaClient } from '@prisma/client';
  * import { createLLM } from '@node-llm/core';
@@ -21,7 +21,38 @@
  * const response = await chat.ask('Hello!');
  * console.log(response.content);
  * ```
+ *
+ * @example AgentSession API (recommended for agents)
+ * ```typescript
+ * import { Agent } from '@node-llm/core';
+ * import { createAgentSession, loadAgentSession } from '@node-llm/orm/prisma';
+ *
+ * class SupportAgent extends Agent {
+ *   static model = 'gpt-4.1';
+ *   static instructions = 'You are a helpful support agent.';
+ * }
+ *
+ * // Create new session
+ * const session = await createAgentSession(prisma, llm, SupportAgent, {
+ *   metadata: { userId: 'user_123' }
+ * });
+ * await session.ask('Hello!');
+ *
+ * // Resume later (Code Wins - model/tools from class, history from DB)
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, sessionId);
+ * await session.ask('Continue our conversation');
+ * ```
  */
 
+// Chat API
 export { Chat, createChat, loadChat } from "./Chat.js";
-export type { ChatRecord, MessageRecord, ChatOptions, TableNames } from "./Chat.js";
+export type { ChatRecord, MessageRecord, ChatOptions } from "./Chat.js";
+
+// AgentSession API
+export { AgentSession, createAgentSession, loadAgentSession } from "./AgentSession.js";
+export type {
+  AgentSessionRecord,
+  CreateAgentSessionOptions,
+  LoadAgentSessionOptions,
+  TableNames // Export from AgentSession which includes agentSession key
+} from "./AgentSession.js";

package/src/index.ts

@@ -23,13 +23,33 @@
  * await chat.ask('Hello!');
  * ```
  *
+ * ## Agent Sessions (Recommended for Agents)
+ *
+ * ```typescript
+ * import { Agent } from '@node-llm/core';
+ * import { createAgentSession, loadAgentSession } from '@node-llm/orm/prisma';
+ *
+ * class SupportAgent extends Agent {
+ *   static model = 'gpt-4.1';
+ *   static instructions = 'You are a helpful support agent.';
+ * }
+ *
+ * // Create and persist
+ * const session = await createAgentSession(prisma, llm, SupportAgent);
+ * await session.ask('Hello!');
+ *
+ * // Resume later (Code Wins - model/tools from class, history from DB)
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, sessionId);
+ * ```
+ *
  * ## Adapters
  *
  * - `@node-llm/orm/prisma` - Prisma adapter (recommended)
  *
  * ## Schema
  *
- * The ORM tracks four core entities:
+ * The ORM tracks five core entities:
+ * - **AgentSession** - Links Agent class to persistent Chat (v0.5.0+)
  * - **Chat** - Session container (model, provider, instructions)
  * - **Message** - User/Assistant conversation history
  * - **ToolCall** - Tool executions (name, arguments, results)

package/test/AgentSession.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Agent, Tool, NodeLLM } from "@node-llm/core";
+import { createAgentSession, loadAgentSession } from "../src/adapters/prisma/AgentSession";
+
+// --- Mocks ---
+
+// Mock Prisma Client
+const mockPrisma = {
+  llmChat: {
+    create: vi.fn(),
+    findUnique: vi.fn()
+  },
+  llmAgentSession: {
+    create: vi.fn(),
+    findUnique: vi.fn()
+  },
+  llmMessage: {
+    create: vi.fn(),
+    findMany: vi.fn(),
+    update: vi.fn(),
+    delete: vi.fn()
+  }
+};
+
+// Mock LLM
+const createMockChat = () => {
+  const mockChat = {
+    withInstructions: vi.fn().mockReturnThis(),
+    withTools: vi.fn().mockReturnThis(),
+    withSchema: vi.fn().mockReturnThis(),
+    ask: vi.fn().mockResolvedValue({
+      content: "Response",
+      meta: {},
+      usage: { input_tokens: 10, output_tokens: 5 }
+    }),
+    stream: vi.fn(),
+    history: [],
+    totalUsage: { input_tokens: 0, output_tokens: 0 },
+    modelId: "mock-model",
+    // Hook methods required by Agent constructor
+    beforeRequest: vi.fn().mockReturnThis(),
+    onToolCallStart: vi.fn().mockReturnThis(),
+    onToolCallEnd: vi.fn().mockReturnThis(),
+    onToolCallError: vi.fn().mockReturnThis(),
+    onEndMessage: vi.fn().mockReturnThis()
+  };
+  return mockChat;
+};
+
+const mockLlm = {
+  chat: vi.fn().mockImplementation(() => createMockChat())
+} as unknown as typeof NodeLLM;
+
+// --- Test Classes ---
+
+class TestAgent extends Agent {
+  static model = "gpt-4-test";
+  static instructions = "Test instructions";
+}
+
+describe("AgentSession", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("createAgentSession", () => {
+    it("creates a new session with correct metadata", async () => {
+      // Setup mocks
+      mockPrisma.llmChat.create.mockResolvedValue({ id: "chat-123" });
+      mockPrisma.llmAgentSession.create.mockResolvedValue({
+        id: "session-123",
+        chatId: "chat-123",
+        agentClass: "TestAgent",
+        metadata: { userId: "user-1" }
+      });
+
+      const session = await createAgentSession(mockPrisma as any, mockLlm, TestAgent, {
+        metadata: { userId: "user-1" }
+      });
+
+      // Verify DB calls
+      expect(mockPrisma.llmChat.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            model: "gpt-4-test",
+            instructions: "Test instructions"
+          })
+        })
+      );
+
+      expect(mockPrisma.llmAgentSession.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            agentClass: "TestAgent",
+            chatId: "chat-123",
+            metadata: { userId: "user-1" }
+          })
+        })
+      );
+
+      // Verify Session Object
+      expect(session.id).toBe("session-123");
+      expect(session.metadata).toEqual({ userId: "user-1" });
+      expect(session.agentClass).toBe("TestAgent");
+    });
+  });
+
+  describe("loadAgentSession", () => {
+    it("loads an existing session and injects history", async () => {
+      // Setup Mocks
+      mockPrisma.llmAgentSession.findUnique.mockResolvedValue({
+        id: "session-123",
+        chatId: "chat-123",
+        agentClass: "TestAgent",
+        metadata: { userId: "user-1" }
+      });
+
+      mockPrisma.llmMessage.findMany.mockResolvedValue([
+        { role: "user", content: "Hello" },
+        { role: "assistant", content: "Hi there" }
+      ]);
+
+      const session = await loadAgentSession(mockPrisma as any, mockLlm, TestAgent, "session-123");
+
+      expect(session).not.toBeNull();
+      expect(session?.id).toBe("session-123");
+
+      // Verify history injection (implicit via mock setup, would check agent internals in real integration)
+      // Implementation detail: The Agent constructor is called with { messages: [...] }
+      // We can verify this by checking if the agent property exists and works
+
+      expect(mockPrisma.llmMessage.findMany).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: { chatId: "chat-123" },
+          orderBy: { createdAt: "asc" }
+        })
+      );
+    });
+
+    it("throws error on agent class mismatch", async () => {
+      mockPrisma.llmAgentSession.findUnique.mockResolvedValue({
+        id: "session-123",
+        agentClass: "OtherAgent", // Mismatch
+        chatId: "chat-123"
+      });
+
+      await expect(
+        loadAgentSession(mockPrisma as any, mockLlm, TestAgent, "session-123")
+      ).rejects.toThrow("Agent class mismatch");
+    });
+  });
+
+  describe("ask", () => {
+    it("persists user and assistant messages", async () => {
+      // Setup Session
+      const sessionRecord = {
+        id: "session-123",
+        chatId: "chat-123",
+        agentClass: "TestAgent",
+        metadata: {},
+        createdAt: new Date(),
+        updatedAt: new Date()
+      };
+
+      // Mock AgentSession manually to test .ask()
+      // But simpler to use createAgentSession mock return if we could,
+      // here we instantiate directly or via factory.
+
+      mockPrisma.llmChat.create.mockResolvedValue({ id: "chat-123" });
+      mockPrisma.llmAgentSession.create.mockResolvedValue(sessionRecord);
+
+      const session = await createAgentSession(mockPrisma as any, mockLlm, TestAgent);
+
+      // Mock message creation
+      mockPrisma.llmMessage.create
+        .mockResolvedValueOnce({ id: "msg-user" }) // User message
+        .mockResolvedValueOnce({ id: "msg-asst" }); // Assistant placeholder
+
+      mockPrisma.llmMessage.update.mockResolvedValue({
+        id: "msg-asst",
+        content: "Response",
+        role: "assistant"
+      });
+
+      await session.ask("Hello");
+
+      // Verify persistence
+      expect(mockPrisma.llmMessage.create).toHaveBeenCalledTimes(2);
+      expect(mockPrisma.llmMessage.create).toHaveBeenNthCalledWith(
+        1,
+        expect.objectContaining({
+          data: expect.objectContaining({ role: "user", content: "Hello" })
+        })
+      );
+
+      expect(mockPrisma.llmMessage.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: { id: "msg-asst" },
+          data: expect.objectContaining({ content: "Response" })
+        })
+      );
+    });
+  });
+});

package/test/CodeWins.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { PrismaClient } from "@prisma/client";
+import { NodeLLMCore, Agent } from "@node-llm/core";
+import { createAgentSession, loadAgentSession } from "../src/adapters/prisma/AgentSession.js";
+
+// Mock Prisma
+const mockChatTable = {
+  create: vi.fn(),
+  findUnique: vi.fn(),
+  update: vi.fn()
+};
+
+const mockSessionTable = {
+  create: vi.fn(),
+  findUnique: vi.fn()
+};
+
+const mockMessageTable = {
+  create: vi.fn(),
+  findMany: vi.fn(),
+  delete: vi.fn(),
+  update: vi.fn()
+};
+
+const prisma = {
+  llmChat: mockChatTable,
+  llmAgentSession: mockSessionTable,
+  llmMessage: mockMessageTable
+} as unknown as PrismaClient;
+
+// Mock Agent & LLM
+class TestAgent extends Agent {
+  static override model = "agent-model";
+  static override instructions = "agent-instructions";
+}
+
+const mockChat = {
+  withInstructions: vi.fn().mockReturnThis(),
+  withTools: vi.fn().mockReturnThis(),
+  withSchema: vi.fn().mockReturnThis(),
+  beforeRequest: vi.fn().mockReturnThis(),
+  onToolCallStart: vi.fn().mockReturnThis(),
+  onToolCallEnd: vi.fn().mockReturnThis(),
+  onToolCallError: vi.fn().mockReturnThis(),
+  onEndMessage: vi.fn().mockReturnThis(),
+  ask: vi.fn(),
+  messages: [],
+  modelId: "agent-model"
+};
+
+const llm = {
+  chat: vi.fn(() => mockChat)
+} as unknown as NodeLLMCore;
+
+describe("AgentSession - Code Wins Sovereignty", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should prioritize Agent class instructions over DB instructions when loading a session", async () => {
+    const sessionId = "sess_123";
+    const chatId = "chat_456";
+
+    // 1. Mock DB returning DIFFERENT instructions than the class
+    mockSessionTable.findUnique.mockResolvedValue({
+      id: sessionId,
+      chatId: chatId,
+      agentClass: "TestAgent"
+    });
+
+    mockChatTable.findUnique.mockResolvedValue({
+      id: chatId,
+      model: "db-model", // DB says db-model
+      instructions: "db-instructions" // DB says db-instructions
+    });
+
+    mockMessageTable.findMany.mockResolvedValue([]);
+
+    // 2. Load the session
+    const session = await loadAgentSession(prisma, llm, TestAgent, sessionId);
+
+    expect(session).toBeDefined();
+
+    // 3. Verify Agent was instantiated with the correct LLM and history (empty here)
+    // The Agent constructor calls llm.chat(model, options)
+    expect(llm.chat).toHaveBeenCalledWith("agent-model", expect.any(Object));
+
+    // 4. Verify instructions applied to chat came from TestAgent.instructions
+    expect(mockChat.withInstructions).toHaveBeenCalledWith("agent-instructions");
+    expect(mockChat.withInstructions).not.toHaveBeenCalledWith("db-instructions");
+  });
+
+  it("should prioritize Agent class model over DB model when creating a session", async () => {
+    mockChatTable.create.mockResolvedValue({ id: "chat_789" });
+    mockSessionTable.create.mockResolvedValue({
+      id: "sess_789",
+      chatId: "chat_789",
+      agentClass: "TestAgent"
+    });
+
+    // 1. Create a session
+    await createAgentSession(prisma, llm, TestAgent);
+
+    // 2. Verify chat record was created with Agent class properties
+    expect(mockChatTable.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        model: "agent-model",
+        instructions: "agent-instructions"
+      })
+    });
+
+    // 3. Verify the live agent instance also uses these
+    expect(llm.chat).toHaveBeenCalledWith("agent-model", expect.any(Object));
+    expect(mockChat.withInstructions).toHaveBeenCalledWith("agent-instructions");
+  });
+});

package/test/Middleware.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { createChat } from "../src/adapters/prisma/index.js";
+import { Middleware } from "@node-llm/core";
+
+// Mock Prisma Client
+const createMockPrisma = () => {
+  const messages: any[] = [];
+  const chats: any[] = [];
+
+  const tables: any = {
+    chat: {
+      create: vi.fn(async ({ data }) => {
+        const chat = { id: "chat-123", ...data, createdAt: new Date(), updatedAt: new Date() };
+        chats.push(chat);
+        return chat;
+      })
+    },
+    message: {
+      create: vi.fn(async ({ data }) => {
+        const message = { id: `msg-${messages.length}`, ...data, createdAt: new Date() };
+        messages.push(message);
+        return message;
+      }),
+      findMany: vi.fn(async ({ where }) => {
+        let filtered = messages.filter((m) => m.chatId === where.chatId);
+        if (where.id?.notIn) {
+          filtered = filtered.filter((m) => !where.id.notIn.includes(m.id));
+        }
+        return filtered;
+      }),
+      update: vi.fn(async ({ where, data }) => {
+        const message = messages.find((m) => m.id === where.id);
+        if (message) {
+          Object.assign(message, data);
+        }
+        return message;
+      }),
+      delete: vi.fn()
+    },
+    toolCall: {
+      create: vi.fn(),
+      update: vi.fn()
+    },
+    request: {
+      create: vi.fn()
+    },
+    _messages: messages
+  };
+
+  return new Proxy(tables, {
+    get(target, prop) {
+      if (prop in target) return target[prop];
+      if (typeof prop === "string") {
+        if (prop.toLowerCase().includes("chat")) return target.chat;
+        if (prop.toLowerCase().includes("message")) return target.message;
+        if (prop.toLowerCase().includes("toolcall")) return target.toolCall;
+        if (prop.toLowerCase().includes("request")) return target.request;
+      }
+      return undefined;
+    }
+  });
+};
+
+// Mock NodeLLM with middleware support
+const createMockLLM = () => {
+  let capturedMiddlewares: Middleware[] = [];
+
+  const mockChat: any = {
+    system: vi.fn(() => mockChat),
+    withTools: vi.fn(() => mockChat),
+    onToolCallStart: vi.fn(() => mockChat),
+    onToolCallEnd: vi.fn(() => mockChat),
+    afterResponse: vi.fn(() => mockChat),
+    onNewMessage: vi.fn(() => mockChat),
+    onEndMessage: vi.fn(() => mockChat),
+    beforeRequest: vi.fn(() => mockChat),
+    ask: vi.fn(async () => {
+      return {
+        content: "Test response",
+        meta: { model: "gpt-4o-mini", provider: "openai" },
+        usage: { input_tokens: 10, output_tokens: 5, total_tokens: 15 },
+        model: "gpt-4o-mini",
+        provider: "openai"
+      };
+    })
+  };
+
+  const llm: any = {
+    chat: vi.fn((model, options) => {
+      if (options?.middlewares) {
+        capturedMiddlewares = options.middlewares;
+      }
+      return mockChat;
+    }),
+    withProvider: vi.fn(() => llm),
+    getMiddlewares: () => capturedMiddlewares
+  };
+
+  return llm;
+};
+
+describe("ORM Middleware Integration", () => {
+  let mockPrisma: any;
+  let mockLLM: any;
+
+  beforeEach(() => {
+    mockPrisma = createMockPrisma();
+    mockLLM = createMockLLM();
+  });
+
+  it("should pass middlewares to core Chat instance", async () => {
+    const middleware: Middleware = {
+      name: "TestMiddleware",
+      onRequest: vi.fn()
+    };
+
+    const chat = await createChat(mockPrisma, mockLLM, {
+      model: "gpt-4o-mini",
+      middlewares: [middleware]
+    });
+
+    // Middlewares are passed when ask() is called
+    await chat.ask("Hello");
+
+    // Verify chat was created with middlewares
+    expect(mockLLM.chat).toHaveBeenCalledWith(
+      "gpt-4o-mini",
+      expect.objectContaining({
+        middlewares: [middleware]
+      })
+    );
+
+    const captured = mockLLM.getMiddlewares();
+    expect(captured).toHaveLength(1);
+    expect(captured[0].name).toBe("TestMiddleware");
+  });
+});