@node-llm/orm 0.4.0 → 0.6.0

package/dist/adapters/prisma/AgentSession.js

@@ -0,0 +1,408 @@
+/**
+ * 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
+ * - Metadata from DB is injected as 'inputs' for dynamic resolution
+ *
+ * @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,
+        inputs: record.metadata
+    }), 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"
+        };
+        this.registerHooks();
+    }
+    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);
+    }
+    /**
+     * Register persistence hooks on the agent.
+     */
+    registerHooks() {
+        this.agent.onToolCallStart(async (toolCall) => {
+            if (!this.currentMessageId)
+                return;
+            const model = this.getModel(this.tableNames.toolCall);
+            await model.create({
+                data: {
+                    messageId: this.currentMessageId,
+                    toolCallId: toolCall.id,
+                    name: toolCall.function.name,
+                    arguments: toolCall.function.arguments
+                }
+            });
+        });
+        this.agent.onToolCallEnd(async (toolCall, result) => {
+            if (!this.currentMessageId)
+                return;
+            const model = this.getModel(this.tableNames.toolCall);
+            try {
+                await model.update({
+                    where: {
+                        messageId_toolCallId: {
+                            messageId: this.currentMessageId,
+                            toolCallId: toolCall.id
+                        }
+                    },
+                    data: {
+                        result: typeof result === "string" ? result : JSON.stringify(result)
+                    }
+                });
+            }
+            catch (e) {
+                this.log(`Failed to update tool call result: ${e}`);
+            }
+        });
+        this.agent.afterResponse(async (response) => {
+            const model = this.getModel(this.tableNames.request);
+            await model.create({
+                data: {
+                    chatId: this.chatId,
+                    messageId: this.currentMessageId,
+                    provider: response.provider || "unknown",
+                    model: response.model || "unknown",
+                    statusCode: 200,
+                    duration: 0,
+                    inputTokens: response.usage?.input_tokens || 0,
+                    outputTokens: response.usage?.output_tokens || 0,
+                    cost: response.usage?.cost || 0
+                }
+            });
+        });
+    }
+    /**
+     * Send a message and persist the conversation.
+     */
+    async ask(message, options = {}) {
+        const model = this.getModel(this.tableNames.message);
+        // Persist user message
+        await model.create({
+            data: { chatId: this.chatId, role: "user", content: message }
+        });
+        // Create placeholder for assistant message
+        const assistantMessage = await model.create({
+            data: { chatId: this.chatId, role: "assistant", content: null }
+        });
+        this.currentMessageId = assistantMessage.id;
+        try {
+            // Merge turn-level inputs with session metadata
+            const inputs = { ...this.record.metadata, ...options.inputs };
+            // Get response from agent (uses code-defined config + injected history)
+            const response = await this.agent.ask(message, { ...options, inputs });
+            // 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(message, options = {}) {
+        const model = this.getModel(this.tableNames.message);
+        // Persist user message
+        await model.create({
+            data: { chatId: this.chatId, role: "user", content: message }
+        });
+        // Create placeholder for assistant message
+        const assistantMessage = await model.create({
+            data: { chatId: this.chatId, role: "assistant", content: null }
+        });
+        this.currentMessageId = assistantMessage.id;
+        try {
+            // Merge turn-level inputs with session metadata
+            const inputs = { ...this.record.metadata, ...options.inputs };
+            const stream = this.agent.stream(message, { ...options, inputs });
+            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 a usage summary for this chat session.
+     */
+    async stats() {
+        const requestModel = getTable(this.prisma, this.tableNames.request);
+        const aggregate = await requestModel.aggregate({
+            where: { chatId: this.chatId },
+            _sum: {
+                inputTokens: true,
+                outputTokens: true,
+                cost: true
+            }
+        });
+        return {
+            input_tokens: Number(aggregate._sum.inputTokens || 0),
+            output_tokens: Number(aggregate._sum.outputTokens || 0),
+            total_tokens: Number((aggregate._sum.inputTokens || 0) + (aggregate._sum.outputTokens || 0)),
+            cost: Number(aggregate._sum.cost || 0)
+        };
+    }
+    /**
+     * Add a tool to the session (turn-level).
+     */
+    withTool(tool) {
+        this.agent.use(tool);
+        return this;
+    }
+    /**
+     * Add instructions to the session (turn-level).
+     */
+    withInstructions(instructions, options) {
+        this.agent.withInstructions(instructions, options);
+        return this;
+    }
+    /**
+     * 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
+    }
+    /**
+     * Update session metadata and re-resolve agent configuration.
+     */
+    async updateMetadata(metadata) {
+        const sessionTable = this.getModel(this.tableNames.agentSession);
+        const newMetadata = { ...this.record.metadata, ...metadata };
+        await sessionTable.update({
+            where: { id: this.id },
+            data: { metadata: newMetadata }
+        });
+        this.record.metadata = newMetadata;
+        // Apply changes to the underlying agent immediately
+        // resolveLazyConfig is private, so we need a cast or make it protected.
+        // Given we are in the same package, we can cast.
+        this.agent.resolveLazyConfig(newMetadata);
+    }
+}
+/**
+ * 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: options.model || AgentClass.model || null,
+            provider: options.provider || null,
+            instructions: options.instructions ||
+                (typeof AgentClass.instructions === "string" ? 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
+        }
+    }));
+    // 3. Instantiate Agent with overrides
+    const agent = new AgentClass({
+        llm,
+        inputs: sessionRecord.metadata,
+        model: options.model,
+        provider: options.provider,
+        instructions: options.instructions,
+        maxToolCalls: options.maxToolCalls
+    });
+    return new AgentSession(prisma, llm, AgentClass, sessionRecord, options.tableNames, agent, 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, LLM, AND metadata (as inputs)
+    // "Code Wins" - model, tools, instructions come from AgentClass
+    // Metadata from DB handles the lazy resolution of behavior
+    const agent = new AgentClass({
+        llm,
+        messages: history,
+        inputs: sessionRecord.metadata
+    });
+    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

@@ -40,12 +40,12 @@ export declare class Chat extends BaseChat {
     /**
      * Send a message and persist the conversation.
      */
-    ask(input: string, options?: AskOptions): Promise<MessageRecord>;
+    ask(message: string, options?: AskOptions): Promise<MessageRecord>;
     /**
      * Stream a response and persist the conversation.
      * Yields ChatChunk objects for full visibility of thinking, content, and tools.
      */
-    askStream(input: string, options?: AskOptions): AsyncGenerator<ChatChunk, MessageRecord, undefined>;
+    askStream(message: string, options?: AskOptions): AsyncGenerator<ChatChunk, MessageRecord, undefined>;
     /**
      * Get all messages for this chat.
      */

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;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"}
+{"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,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IA8C5E;;;OAGG;IACI,SAAS,CACd,OAAO,EAAE,MAAM,EACf,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

@@ -131,10 +131,10 @@ export class Chat extends BaseChat {
     /**
      * Send a message and persist the conversation.
      */
-    async ask(input, options = {}) {
+    async ask(message, options = {}) {
         const messageModel = this.tables.message;
         const userMessage = await this.prisma[messageModel].create({
-            data: { chatId: this.id, role: "user", content: input }
+            data: { chatId: this.id, role: "user", content: message }
         });
         const assistantMessage = await this.prisma[messageModel].create({
             data: { chatId: this.id, role: "assistant", content: null }
@@ -149,7 +149,7 @@ export class Chat extends BaseChat {
                 content: m.content || ""
             }));
             const coreChat = await this.prepareCoreChat(history, assistantMessage.id);
-            const response = await coreChat.ask(input, options);
+            const response = await coreChat.ask(message, options);
             return await this.prisma[messageModel].update({
                 where: { id: assistantMessage.id },
                 data: {
@@ -176,10 +176,10 @@ export class Chat extends BaseChat {
      * Stream a response and persist the conversation.
      * Yields ChatChunk objects for full visibility of thinking, content, and tools.
      */
-    async *askStream(input, options = {}) {
+    async *askStream(message, options = {}) {
         const messageModel = this.tables.message;
         const userMessage = await this.prisma[messageModel].create({
-            data: { chatId: this.id, role: "user", content: input }
+            data: { chatId: this.id, role: "user", content: message }
         });
         const assistantMessage = await this.prisma[messageModel].create({
             data: { chatId: this.id, role: "assistant", content: null }
@@ -194,7 +194,7 @@ export class Chat extends BaseChat {
                 content: m.content || ""
             }));
             const coreChat = await this.prepareCoreChat(history, assistantMessage.id);
-            const stream = coreChat.stream(input, options);
+            const stream = coreChat.stream(message, options);
             let fullContent = "";
             let metadata = {};
             for await (const chunk of stream) {

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)