@node-llm/orm 0.3.0 → 0.5.0

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@node-llm/orm",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Database persistence layer for NodeLLM - Chat, Message, and ToolCall tracking with streaming support",
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -53,7 +56,7 @@
   "author": "NodeLLM Contributors",
   "license": "MIT",
   "peerDependencies": {
-    "@node-llm/core": "^1.9.0",
+    "@node-llm/core": "^1.10.0",
     "@prisma/client": "^5.0.0"
   },
   "devDependencies": {
@@ -68,6 +71,7 @@
   "scripts": {
     "build": "prisma generate --schema=schema.prisma && tsc",
     "test": "vitest run",
+    "test:docs": "vitest run test/docs",
     "test:watch": "vitest"
   }
 }

package/schema.prisma

@@ -12,53 +12,70 @@ datasource db {
 
 // NodeLLM ORM Models (matches @node-llm/orm schema)
 model LlmChat {
-  id           String       @id @default(uuid())
+  id           String           @id @default(uuid())
   model        String?
   provider     String?
-  instructions String?      // System instructions
-  metadata     Json?         // JSON metadata
-  createdAt    DateTime      @default(now())
-  updatedAt    DateTime     @updatedAt
+  instructions String? // System instructions
+  metadata     Json? // JSON metadata
+  createdAt    DateTime         @default(now())
+  updatedAt    DateTime         @updatedAt
   messages     LlmMessage[]
   requests     LlmRequest[]
+  agentSession LlmAgentSession?
+}
+
+// Agent Session - Links Agent class to persistent Chat
+// "Code defines behavior, DB provides history"
+model LlmAgentSession {
+  id         String   @id @default(uuid())
+  agentClass String // Class name for validation (e.g., 'SupportAgent')
+  chatId     String   @unique
+  metadata   Json? // Session context (userId, ticketId, etc.)
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+
+  chat LlmChat @relation(fields: [chatId], references: [id], onDelete: Cascade)
+
+  @@index([agentClass])
+  @@index([createdAt])
 }
 
 model LlmMessage {
-  id                String        @id @default(uuid())
+  id                String   @id @default(uuid())
   chatId            String
-  role              String        // user, assistant, system, tool
+  role              String // user, assistant, system, tool
   content           String?
-  contentRaw        String?       // JSON raw payload
-  reasoning         String?       // Chain of thought (deprecated)
-  thinkingText      String?       // Extended thinking text
-  thinkingSignature String?       // Cryptographic signature
-  thinkingTokens    Int?          // Tokens spent on thinking
+  contentRaw        String? // JSON raw payload
+  reasoning         String? // Chain of thought (deprecated)
+  thinkingText      String? // Extended thinking text
+  thinkingSignature String? // Cryptographic signature
+  thinkingTokens    Int? // Tokens spent on thinking
   inputTokens       Int?
   outputTokens      Int?
   modelId           String?
   provider          String?
-  createdAt         DateTime      @default(now())
+  createdAt         DateTime @default(now())
 
-  chat         LlmChat       @relation(fields: [chatId], references: [id], onDelete: Cascade)
-  toolCalls    LlmToolCall[]
-  requests     LlmRequest[]
+  chat      LlmChat       @relation(fields: [chatId], references: [id], onDelete: Cascade)
+  toolCalls LlmToolCall[]
+  requests  LlmRequest[]
 
   @@index([chatId])
   @@index([createdAt])
 }
 
 model LlmToolCall {
-  id               String     @id @default(uuid())
+  id               String   @id @default(uuid())
   messageId        String
-  toolCallId       String     // ID from the provider
+  toolCallId       String // ID from the provider
   name             String
-  arguments        String     // JSON string
-  thought          String?    // The LLM's reasoning for this tool call
-  thoughtSignature String?    // Signature for the thought
-  result           String?    // Tool execution result
-  createdAt        DateTime   @default(now())
+  arguments        String // JSON string
+  thought          String? // The LLM's reasoning for this tool call
+  thoughtSignature String? // Signature for the thought
+  result           String? // Tool execution result
+  createdAt        DateTime @default(now())
 
-  message      LlmMessage @relation(fields: [messageId], references: [id], onDelete: Cascade)
+  message LlmMessage @relation(fields: [messageId], references: [id], onDelete: Cascade)
 
   @@unique([messageId, toolCallId])
   @@index([messageId])
@@ -66,22 +83,22 @@ model LlmToolCall {
 }
 
 model LlmRequest {
-  id           String      @id @default(uuid())
-  chatId       String
-  messageId    String?     // Optional because requests might fail before message creation
-  
+  id        String  @id @default(uuid())
+  chatId    String
+  messageId String? // Optional because requests might fail before message creation
+
   provider     String
   model        String
   statusCode   Int
-  duration     Int         // milliseconds
+  duration     Int // milliseconds
   inputTokens  Int
   outputTokens Int
   cost         Float?
-  
-  createdAt    DateTime    @default(now())
 
-  chat         LlmChat     @relation(fields: [chatId], references: [id], onDelete: Cascade)
-  message      LlmMessage? @relation(fields: [messageId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now())
+
+  chat    LlmChat     @relation(fields: [chatId], references: [id], onDelete: Cascade)
+  message LlmMessage? @relation(fields: [messageId], references: [id], onDelete: Cascade)
 
   @@index([chatId])
   @@index([createdAt])

package/src/BaseChat.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import type { Usage } from "@node-llm/core";
+import type { Usage, Middleware } from "@node-llm/core";
 
 export interface ChatRecord {
   id: string;
@@ -31,6 +31,7 @@ export interface ChatOptions {
   maxToolCalls?: number;
   requestTimeout?: number;
   params?: Record<string, any>;
+  middlewares?: Middleware[];
 }
 
 export interface UserHooks {
@@ -52,6 +53,7 @@ export abstract class BaseChat<
   public id: string;
   protected localOptions: any = {};
   protected customTools: any[] = [];
+  protected customMiddlewares: Middleware[] = [];
   protected userHooks: UserHooks = {
     onToolCallStart: [],
     onToolCallEnd: [],
@@ -78,6 +80,11 @@ export abstract class BaseChat<
     this.localOptions.maxToolCalls = options.maxToolCalls;
     this.localOptions.requestTimeout = options.requestTimeout;
     this.localOptions.params = options.params;
+
+    // Initialize middlewares
+    if (options.middlewares) {
+      this.customMiddlewares = options.middlewares;
+    }
   }
 
   protected log(...args: any[]) {

package/src/adapters/prisma/AgentSession.ts

@@ -0,0 +1,458 @@
+import {
+  ChatOptions,
+  AskOptions,
+  NodeLLMCore,
+  Agent,
+  AgentConfig,
+  Message,
+  ChatChunk,
+  Usage
+} from "@node-llm/core";
+
+/**
+ * Internal interface for dynamic Prisma Client access.
+ * We use 'any' here because PrismaClient has no index signature by default,
+ * making it hard to access models dynamically by string name.
+ */
+type GenericPrismaClient = any;
+
+/**
+ * Record structure for the LLM Agent Session table.
+ */
+export interface AgentSessionRecord {
+  id: string;
+  agentClass: string;
+  chatId: string;
+  metadata?: Record<string, unknown> | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Record structure for the LLM Message table.
+ */
+export interface MessageRecord {
+  id: string;
+  chatId: string;
+  role: string;
+  content: string | null;
+  contentRaw?: string | null;
+  thinkingText?: string | null;
+  thinkingSignature?: string | null;
+  thinkingTokens?: number | null;
+  inputTokens?: number | null;
+  outputTokens?: number | null;
+  modelId?: string | null;
+  provider?: string | null;
+  createdAt: Date;
+}
+
+/**
+ * Table name customization.
+ */
+export interface TableNames {
+  agentSession?: string;
+  chat?: string;
+  message?: string;
+  toolCall?: string;
+  request?: string;
+}
+
+/**
+ * Internal interface for dynamic Prisma model access
+ */
+interface PrismaModel<T = Record<string, unknown>> {
+  create(args: { data: Record<string, unknown> }): Promise<T>;
+  update(args: { where: { id: string }; data: Record<string, unknown> }): Promise<T>;
+  delete(args: { where: { id: string } }): Promise<void>;
+  findMany(args: {
+    where: Record<string, unknown>;
+    orderBy?: Record<string, string>;
+  }): Promise<T[]>;
+  findUnique(args: { where: { id: string } }): Promise<T | null>;
+}
+
+type AgentClass<T extends Agent = Agent> = (new (
+  overrides?: Partial<AgentConfig & ChatOptions>
+) => T) & {
+  name: string;
+  model?: string;
+  instructions?: string;
+  tools?: unknown[];
+};
+
+/**
+ * AgentSession - Wraps an Agent instance with persistence capabilities.
+ *
+ * Follows "Code Wins" sovereignty:
+ * - Model, Tools, Instructions come from the Agent class (code)
+ * - Message history comes from the database
+ *
+ * @example
+ * ```typescript
+ * // Create a new session
+ * const session = await createAgentSession(prisma, llm, SupportAgent, {
+ *   metadata: { userId: "123" }
+ * });
+ *
+ * // Resume a session
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, "sess_abc");
+ *
+ * // Agent behavior is always defined in code
+ * const result = await session.ask("Hello");
+ * ```
+ */
+export class AgentSession<T extends Agent = Agent> {
+  private currentMessageId: string | null = null;
+  private tableNames: Required<TableNames>;
+  private debug: boolean;
+
+  constructor(
+    private prisma: any,
+    private llm: NodeLLMCore,
+    private AgentClass: AgentClass<T>,
+    private record: AgentSessionRecord,
+    tableNames?: TableNames,
+    private agent: T = new AgentClass({
+      llm
+    }),
+    debug: boolean = false
+  ) {
+    this.debug = debug;
+    this.tableNames = {
+      agentSession: tableNames?.agentSession || "llmAgentSession",
+      chat: tableNames?.chat || "llmChat",
+      message: tableNames?.message || "llmMessage",
+      toolCall: tableNames?.toolCall || "llmToolCall",
+      request: tableNames?.request || "llmRequest"
+    };
+  }
+
+  private log(...args: any[]) {
+    if (this.debug) {
+      console.log(`[@node-llm/orm]`, ...args);
+    }
+  }
+
+  /** Agent instance (for direct access if needed) */
+  get instance(): T {
+    return this.agent;
+  }
+
+  /** Session ID for persistence */
+  get id(): string {
+    return this.record.id;
+  }
+
+  /** Underlying chat ID */
+  get chatId(): string {
+    return this.record.chatId;
+  }
+
+  /** Session metadata */
+  get metadata(): Record<string, unknown> | null | undefined {
+    return this.record.metadata;
+  }
+
+  /** Agent class name */
+  get agentClass(): string {
+    return this.record.agentClass;
+  }
+
+  /** Model ID used by the agent */
+  get modelId(): string {
+    return this.agent.modelId;
+  }
+
+  /** Cumulative usage for this session (from agent memory) */
+  get totalUsage(): Usage {
+    return this.agent.totalUsage;
+  }
+
+  /** Current in-memory message history */
+  get history(): readonly Message[] {
+    return this.agent.history;
+  }
+
+  /**
+   * Helper to get a typed Prisma model by its dynamic name.
+   */
+  private getModel<R = Record<string, unknown>>(name: string): PrismaModel<R> {
+    return getTable(this.prisma, name) as unknown as PrismaModel<R>;
+  }
+
+  /**
+   * Send a message and persist the conversation.
+   */
+  async ask(input: string, options: AskOptions = {}): Promise<MessageRecord> {
+    const model = this.getModel<MessageRecord>(this.tableNames.message);
+
+    // Persist user message
+    await model.create({
+      data: { chatId: this.chatId, role: "user", content: input }
+    });
+
+    // Create placeholder for assistant message
+    const assistantMessage = await model.create({
+      data: { chatId: this.chatId, role: "assistant", content: null }
+    });
+
+    this.currentMessageId = assistantMessage.id;
+
+    try {
+      // Get response from agent (uses code-defined config + injected history)
+      const response = await this.agent.ask(input, options);
+
+      // Update assistant message with response
+      return await model.update({
+        where: { id: assistantMessage.id },
+        data: {
+          content: response.content,
+          contentRaw: JSON.stringify(response.meta),
+          inputTokens: response.usage?.input_tokens || 0,
+          outputTokens: response.usage?.output_tokens || 0,
+          thinkingText: response.thinking?.text || null,
+          thinkingSignature: response.thinking?.signature || null,
+          thinkingTokens: response.thinking?.tokens || null,
+          modelId: response.model || null,
+          provider: response.provider || null
+        }
+      });
+    } catch (error) {
+      // Clean up placeholder on error
+      await model.delete({ where: { id: assistantMessage.id } });
+      throw error;
+    }
+  }
+
+  /**
+   * Stream a response and persist the conversation.
+   */
+  async *askStream(
+    input: string,
+    options: AskOptions = {}
+  ): AsyncGenerator<ChatChunk, MessageRecord, undefined> {
+    const model = this.getModel<MessageRecord>(this.tableNames.message);
+
+    // Persist user message
+    await model.create({
+      data: { chatId: this.chatId, role: "user", content: input }
+    });
+
+    // Create placeholder for assistant message
+    const assistantMessage = await model.create({
+      data: { chatId: this.chatId, role: "assistant", content: null }
+    });
+
+    this.currentMessageId = assistantMessage.id;
+
+    try {
+      const stream = this.agent.stream(input, options);
+
+      let fullContent = "";
+      let lastChunk: ChatChunk | null = null;
+
+      for await (const chunk of stream) {
+        fullContent += chunk.content;
+        lastChunk = chunk;
+        yield chunk;
+      }
+
+      // Final update with accumulated result
+      return await model.update({
+        where: { id: assistantMessage.id },
+        data: {
+          content: fullContent,
+          inputTokens: lastChunk?.usage?.input_tokens || 0,
+          outputTokens: lastChunk?.usage?.output_tokens || 0,
+          thinkingText: lastChunk?.thinking?.text || null,
+          thinkingSignature: lastChunk?.thinking?.signature || null,
+          thinkingTokens: lastChunk?.thinking?.tokens || null,
+          modelId: (lastChunk?.metadata?.model as string) || null,
+          provider: (lastChunk?.metadata?.provider as string) || null
+        }
+      });
+    } catch (error) {
+      await model.delete({ where: { id: assistantMessage.id } });
+      throw error;
+    }
+  }
+
+  /**
+   * Returns the current full message history for this session.
+   */
+  async messages(): Promise<MessageRecord[]> {
+    const model = this.getModel<MessageRecord>(this.tableNames.message);
+    return await model.findMany({
+      where: { chatId: this.chatId },
+      orderBy: { createdAt: "asc" }
+    });
+  }
+
+  /**
+   * Delete the entire session and its history.
+   */
+  async delete(): Promise<void> {
+    const chatTable = this.getModel(this.tableNames.chat);
+    await chatTable.delete({ where: { id: this.chatId } });
+    // AgentSession record is deleted via Cascade from LlmChat
+  }
+}
+
+/**
+ * Options for creating a new agent session.
+ */
+export interface CreateAgentSessionOptions {
+  metadata?: Record<string, unknown>;
+  tableNames?: TableNames;
+  debug?: boolean;
+}
+
+/**
+ * Creates a new agent session and its persistent chat record.
+ */
+export async function createAgentSession<T extends Agent>(
+  prisma: any,
+  llm: NodeLLMCore,
+  AgentClass: AgentClass<T>,
+  options: CreateAgentSessionOptions = {}
+): Promise<AgentSession<T>> {
+  const tableNames = {
+    agentSession: options.tableNames?.agentSession || "llmAgentSession",
+    chat: options.tableNames?.chat || "llmChat",
+    message: options.tableNames?.message || "llmMessage"
+  };
+
+  if (options.debug) {
+    console.log(`[@node-llm/orm] createAgentSession: agentClass=${AgentClass.name}`);
+  }
+
+  // 1. Create underlying LlmChat record
+  const chatTable = getTable(prisma, tableNames.chat);
+  const chatRecord = (await chatTable.create({
+    data: {
+      model: AgentClass.model || null,
+      provider: null,
+      instructions: AgentClass.instructions || null,
+      metadata: null // Runtime metadata goes in Chat, session context in AgentSession
+    }
+  })) as unknown as { id: string };
+
+  // 2. Create AgentSession record
+  const sessionTable = getTable(prisma, tableNames.agentSession);
+  const sessionRecord = (await sessionTable.create({
+    data: {
+      agentClass: AgentClass.name,
+      chatId: chatRecord.id,
+      metadata: options.metadata || null
+    }
+  })) as unknown as AgentSessionRecord;
+
+  return new AgentSession(
+    prisma,
+    llm,
+    AgentClass,
+    sessionRecord,
+    options.tableNames,
+    undefined,
+    options.debug
+  );
+}
+
+/**
+ * Options for loading an existing agent session.
+ */
+export interface LoadAgentSessionOptions {
+  tableNames?: TableNames;
+  debug?: boolean;
+}
+
+/**
+ * Loads an existing agent session and re-instantiates the agent with history.
+ */
+export async function loadAgentSession<T extends Agent>(
+  prisma: any,
+  llm: NodeLLMCore,
+  AgentClass: AgentClass<T>,
+  sessionId: string,
+  options: LoadAgentSessionOptions = {}
+): Promise<AgentSession<T> | null> {
+  const tableNames = {
+    agentSession: options.tableNames?.agentSession || "llmAgentSession",
+    chat: options.tableNames?.chat || "llmChat",
+    message: options.tableNames?.message || "llmMessage"
+  };
+
+  if (options.debug) {
+    console.log(`[@node-llm/orm] loadAgentSession: id=${sessionId}`);
+  }
+
+  // 1. Find session record
+  const sessionTable = getTable(prisma, tableNames.agentSession);
+  const sessionRecord = (await sessionTable.findUnique({
+    where: { id: sessionId }
+  })) as unknown as AgentSessionRecord | null;
+
+  if (!sessionRecord) {
+    return null;
+  }
+
+  // 1.5. Validate Agent Class (Code Wins Sovereignty)
+  if (sessionRecord.agentClass !== AgentClass.name) {
+    throw new Error(
+      `Agent class mismatch: Session "${sessionId}" was created for "${sessionRecord.agentClass}", but is being loaded with "${AgentClass.name}".`
+    );
+  }
+
+  // 2. Load message history
+  const messageTable = getTable(prisma, tableNames.message);
+  const messages = (await messageTable.findMany({
+    where: { chatId: sessionRecord.chatId },
+    orderBy: { createdAt: "asc" }
+  })) as unknown as MessageRecord[];
+
+  // 3. Convert DB messages to NodeLLM Message format
+  const history: Message[] = messages.map((m) => ({
+    role: m.role as "user" | "assistant" | "system",
+    content: m.content || ""
+  }));
+
+  // 4. Instantiate agent with injected history and LLM
+  // "Code Wins" - model, tools, instructions come from AgentClass
+  const agent = new AgentClass({
+    llm,
+    messages: history
+  }) as T;
+
+  return new AgentSession(
+    prisma,
+    llm,
+    AgentClass,
+    sessionRecord,
+    options.tableNames,
+    agent,
+    options.debug
+  );
+}
+
+/**
+ * Dynamic helper to access Prisma models by name.
+ * Handles both case-sensitive and case-insensitive lookups for flexibility.
+ */
+function getTable(prisma: GenericPrismaClient, tableName: string): PrismaModel {
+  const p = prisma as unknown as Record<string, PrismaModel>;
+
+  // 1. Direct match
+  const table = p[tableName];
+  if (table) return table;
+
+  // 2. Case-insensitive match
+  const keys = Object.keys(prisma).filter((k) => !k.startsWith("$") && !k.startsWith("_"));
+  const match = keys.find((k) => k.toLowerCase() === tableName.toLowerCase());
+
+  if (match && p[match]) return p[match];
+
+  throw new Error(
+    `[@node-llm/orm] Prisma table "${tableName}" not found. Available tables: ${keys.join(", ")}`
+  );
+}