@node-llm/orm 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.12.0] - 2026-02-22 (@node-llm/core)
+
+### Features
+
+- **Lazy Agent Evaluation**: Support for defining `instructions` and `tools` as functions that resolve at runtime based on provided `inputs`.
+- **Runtime Agent Inputs**: Pass dynamic context (e.g., user preferences, scope) via `agent.ask(msg, { inputs })` for per-turn configuration overrides.
+- **Agent Telemetry Hooks**: Integrated delegation of life-cycle events (`onToolCallStart`, `onToolCallEnd`, `afterResponse`) from Agents to underlying Chat instances, enabling declarative observability.
+
+## [0.6.0] - 2026-02-22 (@node-llm/orm)
+
+### Features
+
+- **Automated Agent Persistence**: `AgentSession` now automatically registers internal hooks to persist tool calls and provider request metrics (tokens, latency) to the database.
+- **Dynamic Metadata Updates**: Added `session.updateMetadata()` for mid-conversation context updates with immediate agent re-resolution.
+- **Proof-of-Concept**: Full integration in HR Chatbot example demonstrating persistent multi-turn agent conversations with a complete audit trail.
+
 ## [1.11.0] - 2026-02-07 (@node-llm/core)
 
 ### Features

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

@@ -38,11 +38,11 @@ export interface TableNames {
     toolCall?: string;
     request?: string;
 }
-type AgentClass<T extends Agent = Agent> = (new (overrides?: Partial<AgentConfig & ChatOptions>) => T) & {
+type AgentClass<T extends Agent<any, any> = Agent<any, any>> = (new (overrides?: Partial<AgentConfig<any> & ChatOptions>) => T) & {
     name: string;
     model?: string;
-    instructions?: string;
-    tools?: unknown[];
+    instructions?: unknown;
+    tools?: unknown;
 };
 /**
  * AgentSession - Wraps an Agent instance with persistence capabilities.
@@ -50,6 +50,7 @@ type AgentClass<T extends Agent = Agent> = (new (overrides?: Partial<AgentConfig
  * 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
@@ -65,7 +66,7 @@ type AgentClass<T extends Agent = Agent> = (new (overrides?: Partial<AgentConfig
  * const result = await session.ask("Hello");
  * ```
  */
-export declare class AgentSession<T extends Agent = Agent> {
+export declare class AgentSession<I extends Record<string, any> = Record<string, any>, T extends Agent<I, any> = Agent<I, any>> {
     private prisma;
     private llm;
     private AgentClass;
@@ -83,7 +84,7 @@ export declare class AgentSession<T extends Agent = Agent> {
     /** Underlying chat ID */
     get chatId(): string;
     /** Session metadata */
-    get metadata(): Record<string, unknown> | null | undefined;
+    get metadata(): I | null | undefined;
     /** Agent class name */
     get agentClass(): string;
     /** Model ID used by the agent */
@@ -96,14 +97,36 @@ export declare class AgentSession<T extends Agent = Agent> {
      * Helper to get a typed Prisma model by its dynamic name.
      */
     private getModel;
+    /**
+     * Register persistence hooks on the agent.
+     */
+    private registerHooks;
     /**
      * Send a message and persist the conversation.
      */
-    ask(input: string, options?: AskOptions): Promise<MessageRecord>;
+    ask(message: string, options?: AskOptions & {
+        inputs?: I;
+    }): Promise<MessageRecord>;
     /**
      * Stream a response and persist the conversation.
      */
-    askStream(input: string, options?: AskOptions): AsyncGenerator<ChatChunk, MessageRecord, undefined>;
+    askStream(message: string, options?: AskOptions & {
+        inputs?: I;
+    }): AsyncGenerator<ChatChunk, MessageRecord, undefined>;
+    /**
+     * Returns a usage summary for this chat session.
+     */
+    stats(): Promise<Usage>;
+    /**
+     * Add a tool to the session (turn-level).
+     */
+    withTool(tool: any): this;
+    /**
+     * Add instructions to the session (turn-level).
+     */
+    withInstructions(instructions: string, options?: {
+        replace?: boolean;
+    }): this;
     /**
      * Returns the current full message history for this session.
      */
@@ -112,19 +135,27 @@ export declare class AgentSession<T extends Agent = Agent> {
      * Delete the entire session and its history.
      */
     delete(): Promise<void>;
+    /**
+     * Update session metadata and re-resolve agent configuration.
+     */
+    updateMetadata(metadata: Partial<I>): Promise<void>;
 }
 /**
  * Options for creating a new agent session.
  */
-export interface CreateAgentSessionOptions {
-    metadata?: Record<string, unknown>;
+export interface CreateAgentSessionOptions<I = any> {
+    metadata?: I;
     tableNames?: TableNames;
     debug?: boolean;
+    model?: string;
+    provider?: string;
+    instructions?: string;
+    maxToolCalls?: number;
 }
 /**
  * Creates a new agent session and its persistent chat record.
  */
-export declare function createAgentSession<T extends Agent>(prisma: any, llm: NodeLLMCore, AgentClass: AgentClass<T>, options?: CreateAgentSessionOptions): Promise<AgentSession<T>>;
+export declare function createAgentSession<I extends Record<string, any>, T extends Agent<I, any>>(prisma: any, llm: NodeLLMCore, AgentClass: AgentClass<T>, options?: CreateAgentSessionOptions<I>): Promise<AgentSession<I, T>>;
 /**
  * Options for loading an existing agent session.
  */
@@ -135,6 +166,6 @@ export interface LoadAgentSessionOptions {
 /**
  * Loads an existing agent session and re-instantiates the agent with history.
  */
-export declare function loadAgentSession<T extends Agent>(prisma: any, llm: NodeLLMCore, AgentClass: AgentClass<T>, sessionId: string, options?: LoadAgentSessionOptions): Promise<AgentSession<T> | null>;
+export declare function loadAgentSession<I extends Record<string, any>, T extends Agent<I, any>>(prisma: any, llm: NodeLLMCore, AgentClass: AgentClass<T>, sessionId: string, options?: LoadAgentSessionOptions): Promise<AgentSession<I, T> | null>;
 export {};
 //# sourceMappingURL=AgentSession.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"AgentSession.d.ts","sourceRoot":"","sources":["../../../src/adapters/prisma/AgentSession.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AgentSession.d.ts","sourceRoot":"","sources":["../../../src/adapters/prisma/AgentSession.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,KAAK,EACL,WAAW,EACX,OAAO,EACP,SAAS,EACT,KAAK,EACN,MAAM,gBAAgB,CAAC;AASxB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1C,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,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,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAgBD,KAAK,UAAU,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,KAC9D,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,KAChD,CAAC,CAAC,GAAG;IACR,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY,CACvB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACnD,CAAC,SAAS,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;IAOrC,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,MAAM;IAEd,OAAO,CAAC,KAAK;IAVf,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,KAAK,CAAU;gBAGb,MAAM,EAAE,GAAG,EACX,GAAG,EAAE,WAAW,EAChB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,kBAAkB,EAClC,UAAU,CAAC,EAAE,UAAU,EACf,KAAK,GAAE,CAGb,EACF,KAAK,GAAE,OAAe;IAcxB,OAAO,CAAC,GAAG;IAMX,mDAAmD;IACnD,IAAI,QAAQ,IAAI,CAAC,CAEhB;IAED,iCAAiC;IACjC,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,yBAAyB;IACzB,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,uBAAuB;IACvB,IAAI,QAAQ,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,CAEnC;IAED,uBAAuB;IACvB,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,iCAAiC;IACjC,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,4DAA4D;IAC5D,IAAI,UAAU,IAAI,KAAK,CAEtB;IAED,wCAAwC;IACxC,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,aAAa;IAoDrB;;OAEG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,UAAU,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAO,GAAG,OAAO,CAAC,aAAa,CAAC;IA4C7F;;OAEG;IACI,SAAS,CACd,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,UAAU,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAO,GACxC,cAAc,CAAC,SAAS,EAAE,aAAa,EAAE,SAAS,CAAC;IAiDtD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC;IAmB7B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI;IAKzB;;OAEG;IACH,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAK7E;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAQ1C;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAgB1D;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC,GAAG,GAAG;IAChD,QAAQ,CAAC,EAAE,CAAC,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,SAAS,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAC7F,MAAM,EAAE,GAAG,EACX,GAAG,EAAE,WAAW,EAChB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,OAAO,GAAE,yBAAyB,CAAC,CAAC,CAAM,GACzC,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAqD7B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,SAAS,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAC3F,MAAM,EAAE,GAAG,EACX,GAAG,EAAE,WAAW,EAChB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CA2DpC"}

package/dist/adapters/prisma/AgentSession.js

@@ -4,6 +4,7 @@
  * 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
@@ -29,7 +30,8 @@ export class AgentSession {
     tableNames;
     debug;
     constructor(prisma, llm, AgentClass, record, tableNames, agent = new AgentClass({
-        llm
+        llm,
+        inputs: record.metadata
     }), debug = false) {
         this.prisma = prisma;
         this.llm = llm;
@@ -44,6 +46,7 @@ export class AgentSession {
             toolCall: tableNames?.toolCall || "llmToolCall",
             request: tableNames?.request || "llmRequest"
         };
+        this.registerHooks();
     }
     log(...args) {
         if (this.debug) {
@@ -88,14 +91,69 @@ export class AgentSession {
     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(input, options = {}) {
+    async ask(message, options = {}) {
         const model = this.getModel(this.tableNames.message);
         // Persist user message
         await model.create({
-            data: { chatId: this.chatId, role: "user", content: input }
+            data: { chatId: this.chatId, role: "user", content: message }
         });
         // Create placeholder for assistant message
         const assistantMessage = await model.create({
@@ -103,8 +161,10 @@ export class AgentSession {
         });
         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(input, options);
+            const response = await this.agent.ask(message, { ...options, inputs });
             // Update assistant message with response
             return await model.update({
                 where: { id: assistantMessage.id },
@@ -130,11 +190,11 @@ export class AgentSession {
     /**
      * Stream a response and persist the conversation.
      */
-    async *askStream(input, options = {}) {
+    async *askStream(message, options = {}) {
         const model = this.getModel(this.tableNames.message);
         // Persist user message
         await model.create({
-            data: { chatId: this.chatId, role: "user", content: input }
+            data: { chatId: this.chatId, role: "user", content: message }
         });
         // Create placeholder for assistant message
         const assistantMessage = await model.create({
@@ -142,7 +202,9 @@ export class AgentSession {
         });
         this.currentMessageId = assistantMessage.id;
         try {
-            const stream = this.agent.stream(input, options);
+            // 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) {
@@ -170,6 +232,40 @@ export class AgentSession {
             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.
      */
@@ -188,6 +284,22 @@ export class AgentSession {
         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.
@@ -205,9 +317,10 @@ export async function createAgentSession(prisma, llm, AgentClass, options = {})
     const chatTable = getTable(prisma, tableNames.chat);
     const chatRecord = (await chatTable.create({
         data: {
-            model: AgentClass.model || null,
-            provider: null,
-            instructions: AgentClass.instructions || null,
+            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
         }
     }));
@@ -220,7 +333,16 @@ export async function createAgentSession(prisma, llm, AgentClass, options = {})
             metadata: options.metadata || null
         }
     }));
-    return new AgentSession(prisma, llm, AgentClass, sessionRecord, options.tableNames, undefined, options.debug);
+    // 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.
@@ -257,11 +379,13 @@ export async function loadAgentSession(prisma, llm, AgentClass, sessionId, optio
         role: m.role,
         content: m.content || ""
     }));
-    // 4. Instantiate agent with injected history and LLM
+    // 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
+        messages: history,
+        inputs: sessionRecord.metadata
     });
     return new AgentSession(prisma, llm, AgentClass, sessionRecord, options.tableNames, agent, options.debug);
 }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@node-llm/orm",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Database persistence layer for NodeLLM - Chat, Message, and ToolCall tracking with streaming support",
   "publishConfig": {
     "access": "public"
@@ -56,7 +56,7 @@
   "author": "NodeLLM Contributors",
   "license": "MIT",
   "peerDependencies": {
-    "@node-llm/core": "^1.10.0",
+    "@node-llm/core": "^1.12.0",
     "@prisma/client": "^5.0.0"
   },
   "devDependencies": {