@node-llm/orm 0.3.0 → 0.5.0

package/dist/adapters/prisma/AgentSession.js

@@ -0,0 +1,284 @@
+/**
+ * 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 {
+    prisma;
+    llm;
+    AgentClass;
+    record;
+    agent;
+    currentMessageId = null;
+    tableNames;
+    debug;
+    constructor(prisma, llm, AgentClass, record, tableNames, agent = new AgentClass({
+        llm
+    }), debug = false) {
+        this.prisma = prisma;
+        this.llm = llm;
+        this.AgentClass = AgentClass;
+        this.record = record;
+        this.agent = agent;
+        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"
+        };
+    }
+    log(...args) {
+        if (this.debug) {
+            console.log(`[@node-llm/orm]`, ...args);
+        }
+    }
+    /** Agent instance (for direct access if needed) */
+    get instance() {
+        return this.agent;
+    }
+    /** Session ID for persistence */
+    get id() {
+        return this.record.id;
+    }
+    /** Underlying chat ID */
+    get chatId() {
+        return this.record.chatId;
+    }
+    /** Session metadata */
+    get metadata() {
+        return this.record.metadata;
+    }
+    /** Agent class name */
+    get agentClass() {
+        return this.record.agentClass;
+    }
+    /** Model ID used by the agent */
+    get modelId() {
+        return this.agent.modelId;
+    }
+    /** Cumulative usage for this session (from agent memory) */
+    get totalUsage() {
+        return this.agent.totalUsage;
+    }
+    /** Current in-memory message history */
+    get history() {
+        return this.agent.history;
+    }
+    /**
+     * Helper to get a typed Prisma model by its dynamic name.
+     */
+    getModel(name) {
+        return getTable(this.prisma, name);
+    }
+    /**
+     * Send a message and persist the conversation.
+     */
+    async ask(input, options = {}) {
+        const model = this.getModel(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, options = {}) {
+        const model = this.getModel(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 = 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 || null,
+                    provider: lastChunk?.metadata?.provider || null
+                }
+            });
+        }
+        catch (error) {
+            await model.delete({ where: { id: assistantMessage.id } });
+            throw error;
+        }
+    }
+    /**
+     * Returns the current full message history for this session.
+     */
+    async messages() {
+        const model = this.getModel(this.tableNames.message);
+        return await model.findMany({
+            where: { chatId: this.chatId },
+            orderBy: { createdAt: "asc" }
+        });
+    }
+    /**
+     * Delete the entire session and its history.
+     */
+    async delete() {
+        const chatTable = this.getModel(this.tableNames.chat);
+        await chatTable.delete({ where: { id: this.chatId } });
+        // AgentSession record is deleted via Cascade from LlmChat
+    }
+}
+/**
+ * Creates a new agent session and its persistent chat record.
+ */
+export async function createAgentSession(prisma, llm, AgentClass, options = {}) {
+    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
+        }
+    }));
+    // 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
+        }
+    }));
+    return new AgentSession(prisma, llm, AgentClass, sessionRecord, options.tableNames, undefined, options.debug);
+}
+/**
+ * Loads an existing agent session and re-instantiates the agent with history.
+ */
+export async function loadAgentSession(prisma, llm, AgentClass, sessionId, options = {}) {
+    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 }
+    }));
+    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" }
+    }));
+    // 3. Convert DB messages to NodeLLM Message format
+    const history = messages.map((m) => ({
+        role: m.role,
+        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
+    });
+    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, tableName) {
+    const p = prisma;
+    // 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(", ")}`);
+}

package/dist/adapters/prisma/Chat.d.ts

@@ -58,13 +58,14 @@ export declare class Chat extends BaseChat {
 /**
  * Convenience method to create a new chat session.
  */
-export declare function createChat<T = Record<string, any>>(prisma: PrismaClient, llm: NodeLLMCore, options?: ChatOptions & {
+export declare function createChat<T = Record<string, any>>(prisma: any, llm: NodeLLMCore, options?: ChatOptions & {
     tableNames?: TableNames;
 } & T): Promise<Chat>;
 /**
  * Convenience method to load an existing chat session.
  */
-export declare function loadChat(prisma: PrismaClient, llm: NodeLLMCore, chatId: string, options?: ChatOptions & {
+export declare function loadChat(prisma: any, llm: NodeLLMCore, chatId: string, options?: ChatOptions & {
     tableNames?: TableNames;
+    debug?: boolean;
 }): Promise<Chat | null>;
 //# sourceMappingURL=Chat.d.ts.map

package/dist/adapters/prisma/Chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../../src/adapters/prisma/Chat.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,IAAK,SAAQ,QAAQ;IAK9B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,GAAG;IALb,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,iBAAiB,CAAoD;gBAGnE,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,WAAW,EACxB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,WAAgB,EACzB,UAAU,GAAE,UAAe;IAgB7B;;OAEG;YACW,eAAe;IAoH7B;;OAEG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IA8C1E;;;OAGG;IACI,SAAS,CACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,UAAe,GACvB,cAAc,CAAC,SAAS,EAAE,aAAa,EAAE,SAAS,CAAC;IAmEtD;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAQ1C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC;CAkB9B;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACtD,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,WAAW,GAAG;IAAE,UAAU,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,CAAa,GACjE,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAW,GAAG;IAAE,UAAU,CAAC,EAAE,UAAU,CAAA;CAAO,GACtD,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAQtB"}
+{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../../src/adapters/prisma/Chat.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,IAAK,SAAQ,QAAQ;IAK9B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,GAAG;IALb,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,iBAAiB,CAAoD;gBAGnE,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,WAAW,EACxB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,WAAgB,EACzB,UAAU,GAAE,UAAe;IAgB7B;;OAEG;YACW,eAAe;IAqH7B;;OAEG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IA8C1E;;;OAGG;IACI,SAAS,CACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,UAAe,GACvB,cAAc,CAAC,SAAS,EAAE,aAAa,EAAE,SAAS,CAAC;IAmEtD;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAQ1C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC;CAkB9B;AAuBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACtD,MAAM,EAAE,GAAG,EACX,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,WAAW,GAAG;IAAE,UAAU,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,CAAa,GACjE,OAAO,CAAC,IAAI,CAAC,CA2Cf;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,GAAG,EACX,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAW,GAAG;IAAE,UAAU,CAAC,EAAE,UAAU,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GACvE,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAiBtB"}

package/dist/adapters/prisma/Chat.js

@@ -31,7 +31,8 @@ export class Chat extends BaseChat {
         const llmInstance = provider ? this.llm.withProvider(provider) : this.llm;
         const coreChat = llmInstance.chat(model || undefined, {
             messages: history,
-            ...this.localOptions
+            ...this.localOptions,
+            middlewares: this.customMiddlewares
         });
         // Register tools
         if (this.customTools.length > 0) {
@@ -265,14 +266,37 @@ 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, tableName) {
+    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(prisma, llm, options = {}) {
     const chatTable = options.tableNames?.chat || "llmChat";
     // Extract known options so we don't double-pass them or pass them incorrectly
-    const { model, provider, instructions, metadata, tableNames: _tableNames, debug: _debug, persistence: _persistence, ...extras } = options;
-    const record = await prisma[chatTable].create({
+    // runtime options should NOT be persisted to DB
+    const { model, provider, instructions, metadata, tableNames: _tableNames, debug: _debug, persistence: _persistence, middlewares: _middlewares, maxToolCalls: _maxToolCalls, thinking: _thinking, temperature: _temperature, maxTokens: _maxTokens, headers: _headers, requestTimeout: _requestTimeout, params: _params, ...extras } = options;
+    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,
@@ -288,10 +312,16 @@ export async function createChat(prisma, llm, options = {}) {
  */
 export async function loadChat(prisma, llm, chatId, options = {}) {
     const chatTable = options.tableNames?.chat || "llmChat";
-    const record = await prisma[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/dist/adapters/prisma/index.d.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,30 @@
  * 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');
+ * ```
  */
 export { Chat, createChat, loadChat } from "./Chat.js";
-export type { ChatRecord, MessageRecord, ChatOptions, TableNames } from "./Chat.js";
+export type { ChatRecord, MessageRecord, ChatOptions } from "./Chat.js";
+export { AgentSession, createAgentSession, loadAgentSession } from "./AgentSession.js";
+export type { AgentSessionRecord, CreateAgentSessionOptions, LoadAgentSessionOptions, TableNames } from "./AgentSession.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters/prisma/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/prisma/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACvD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/prisma/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACvD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGxE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvF,YAAY,EACV,kBAAkB,EAClB,yBAAyB,EACzB,uBAAuB,EACvB,UAAU,EACX,MAAM,mBAAmB,CAAC"}

package/dist/adapters/prisma/index.js

@@ -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,5 +21,29 @@
  * 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";
+// AgentSession API
+export { AgentSession, createAgentSession, loadAgentSession } from "./AgentSession.js";

package/dist/index.d.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/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAGH,cAAc,4BAA4B,CAAC"}

package/dist/index.js

@@ -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/migrations/README.md

@@ -0,0 +1,53 @@
+# @node-llm/orm Migrations
+
+Reference SQL migrations for upgrading your database schema.
+
+## Who Needs These?
+
+| User Type         | Action                                                             |
+| ----------------- | ------------------------------------------------------------------ |
+| **New user**      | ❌ Skip these. Run `npx @node-llm/orm init` → full schema included |
+| **Existing user** | ✅ Use these to upgrade without losing data                        |
+
+> **Note:** These migrations are **idempotent** — safe to run multiple times. They use `IF NOT EXISTS` and conditional checks, so running them on a fresh database won't cause errors.
+
+## Available Migrations
+
+| File                       | Version | Description                                         |
+| -------------------------- | ------- | --------------------------------------------------- |
+| `add_thinking_support.sql` | v0.2.0+ | Extended Thinking columns (Claude 3.7, DeepSeek R1) |
+| `add_agent_session.sql`    | v0.5.0+ | AgentSession for persistent agent conversations     |
+
+## How to Use
+
+### Option 1: Copy and Apply
+
+```bash
+# Create migration folder
+mkdir -p prisma/migrations/$(date +%Y%m%d%H%M%S)_add_agent_session
+
+# Copy the SQL
+cp node_modules/@node-llm/orm/migrations/add_agent_session.sql \
+   prisma/migrations/$(date +%Y%m%d%H%M%S)_add_agent_session/migration.sql
+
+# Mark as applied
+npx prisma migrate resolve --applied $(date +%Y%m%d%H%M%S)_add_agent_session
+```
+
+### Option 2: Let Prisma Generate
+
+1. Update your `schema.prisma` with the new models from `@node-llm/orm/schema.prisma`
+2. Run: `npx prisma migrate dev --name add_agent_session`
+
+## Custom Table Names
+
+If you're using custom table names (e.g., `AssistantMessage` instead of `LlmMessage`),
+edit the SQL file to match your table names before applying.
+
+## Documentation
+
+See the full [Migration Guide](https://node-llm.eshaiju.com/orm/migrations) for:
+
+- Baseline migrations
+- Production deployment
+- Renaming columns safely

package/migrations/add_agent_session.sql

@@ -0,0 +1,44 @@
+-- Migration: Add AgentSession support
+-- Version: @node-llm/orm v0.5.0+
+-- 
+-- This migration adds the LlmAgentSession table for persistent agent conversations.
+-- Run this if you're upgrading from a previous version of @node-llm/orm.
+--
+-- Usage:
+--   1. Copy this file to your prisma/migrations/<timestamp>_add_agent_session/ folder
+--   2. Run: npx prisma migrate resolve --applied <timestamp>_add_agent_session
+--   Or simply run: npx prisma migrate dev --name add_agent_session
+
+-- Create the AgentSession table
+CREATE TABLE IF NOT EXISTS "LlmAgentSession" (
+    "id" TEXT NOT NULL,
+    "agentClass" TEXT NOT NULL,
+    "chatId" TEXT NOT NULL,
+    "metadata" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "LlmAgentSession_pkey" PRIMARY KEY ("id")
+);
+
+-- Create unique constraint on chatId (1:1 with LlmChat)
+CREATE UNIQUE INDEX IF NOT EXISTS "LlmAgentSession_chatId_key" ON "LlmAgentSession"("chatId");
+
+-- Create indexes for common queries
+CREATE INDEX IF NOT EXISTS "LlmAgentSession_agentClass_idx" ON "LlmAgentSession"("agentClass");
+CREATE INDEX IF NOT EXISTS "LlmAgentSession_createdAt_idx" ON "LlmAgentSession"("createdAt");
+
+-- Add foreign key constraint (idempotent - skips if already exists)
+DO $$ 
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'LlmAgentSession_chatId_fkey'
+    ) THEN
+        ALTER TABLE "LlmAgentSession" 
+            ADD CONSTRAINT "LlmAgentSession_chatId_fkey" 
+            FOREIGN KEY ("chatId") 
+            REFERENCES "LlmChat"("id") 
+            ON DELETE CASCADE 
+            ON UPDATE CASCADE;
+    END IF;
+END $$;

package/migrations/add_thinking_support.sql

@@ -0,0 +1,34 @@
+-- Migration: Add Extended Thinking support
+-- Version: @node-llm/orm v0.2.0+
+-- 
+-- This migration adds columns for Extended Thinking (Claude 3.7+, DeepSeek R1).
+-- Run this if you're upgrading from a previous version of @node-llm/orm.
+--
+-- Usage:
+--   1. Copy this file to your prisma/migrations/<timestamp>_add_thinking_support/ folder
+--   2. Run: npx prisma migrate resolve --applied <timestamp>_add_thinking_support
+--   Or simply run: npx prisma migrate dev --name add_thinking_support
+--
+-- Note: Adjust table names if using custom names (e.g., AssistantMessage instead of LlmMessage)
+-- Note: This migration is idempotent - safe to run multiple times.
+
+-- AlterTable: Convert metadata to native JSONB (idempotent - skips if already JSONB)
+DO $$ 
+BEGIN
+    IF EXISTS (
+        SELECT 1 FROM information_schema.columns 
+        WHERE table_name = 'LlmChat' AND column_name = 'metadata' AND data_type != 'jsonb'
+    ) THEN
+        ALTER TABLE "LlmChat" ALTER COLUMN "metadata" TYPE JSONB USING metadata::JSONB;
+    END IF;
+END $$;
+
+-- AlterTable: Add thinking columns to Message
+ALTER TABLE "LlmMessage" 
+ADD COLUMN IF NOT EXISTS "thinkingText" TEXT,
+ADD COLUMN IF NOT EXISTS "thinkingSignature" TEXT,
+ADD COLUMN IF NOT EXISTS "thinkingTokens" INTEGER;
+
+-- AlterTable: Add thought signature to ToolCall
+ALTER TABLE "LlmToolCall" 
+ADD COLUMN IF NOT EXISTS "thoughtSignature" TEXT;