@node-llm/orm 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/CHANGELOG.md +155 -0
  2. package/LICENSE +21 -0
  3. package/README.md +38 -14
  4. package/dist/BaseChat.d.ts +124 -0
  5. package/dist/BaseChat.d.ts.map +1 -0
  6. package/dist/BaseChat.js +182 -0
  7. package/dist/Store.d.ts +109 -0
  8. package/dist/Store.d.ts.map +1 -0
  9. package/dist/Store.js +14 -0
  10. package/dist/adapters/prisma/AgentSession.d.ts +178 -0
  11. package/dist/adapters/prisma/AgentSession.d.ts.map +1 -0
  12. package/dist/adapters/prisma/AgentSession.js +328 -0
  13. package/dist/adapters/prisma/Chat.d.ts +70 -0
  14. package/dist/adapters/prisma/Chat.d.ts.map +1 -0
  15. package/dist/adapters/prisma/Chat.js +301 -0
  16. package/dist/adapters/prisma/PrismaStore.d.ts +54 -0
  17. package/dist/adapters/prisma/PrismaStore.d.ts.map +1 -0
  18. package/dist/adapters/prisma/PrismaStore.js +97 -0
  19. package/dist/adapters/prisma/index.d.ts +51 -0
  20. package/dist/adapters/prisma/index.d.ts.map +1 -0
  21. package/dist/adapters/prisma/index.js +51 -0
  22. package/dist/index.d.ts +61 -0
  23. package/dist/index.d.ts.map +1 -0
  24. package/dist/index.js +61 -0
  25. package/migrations/README.md +5 -4
  26. package/migrations/add_cached_tokens.sql +5 -0
  27. package/package.json +14 -12
  28. package/schema.prisma +1 -0
  29. package/src/Store.ts +135 -0
  30. package/src/adapters/prisma/AgentSession.ts +89 -185
  31. package/src/adapters/prisma/Chat.ts +95 -162
  32. package/src/adapters/prisma/PrismaStore.ts +156 -0
  33. package/src/adapters/prisma/index.ts +3 -0
  34. package/src/index.ts +14 -0
  35. package/test/CachedTokens.test.ts +40 -0
  36. package/test/Store.test.ts +214 -0
  37. package/test/docs/readme-exports.test.ts +8 -0
  38. package/tsconfig.tsbuildinfo +1 -0
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Where an ORM chat or agent session keeps its records. The Prisma store is the default; an app
3
+ * can pass its own to keep the same records anywhere else, such as behind its own HTTP API.
4
+ */
5
+ export interface StoredChat {
6
+ id: string;
7
+ model?: string | null;
8
+ provider?: string | null;
9
+ instructions?: string | null;
10
+ metadata?: any;
11
+ createdAt: Date;
12
+ updatedAt: Date;
13
+ }
14
+ export interface StoredMessage {
15
+ id: string;
16
+ chatId: string;
17
+ role: string;
18
+ content: string | null;
19
+ contentRaw?: string | null;
20
+ reasoning?: string | null;
21
+ inputTokens?: number | null;
22
+ outputTokens?: number | null;
23
+ thinkingText?: string | null;
24
+ thinkingSignature?: string | null;
25
+ thinkingTokens?: number | null;
26
+ modelId?: string | null;
27
+ provider?: string | null;
28
+ createdAt: Date;
29
+ }
30
+ export interface StoredAgentSession {
31
+ id: string;
32
+ agentClass: string;
33
+ chatId: string;
34
+ metadata?: Record<string, unknown> | null;
35
+ createdAt: Date;
36
+ updatedAt: Date;
37
+ }
38
+ export interface NewChat {
39
+ model?: string | null;
40
+ provider?: string | null;
41
+ instructions?: string | null;
42
+ metadata?: any;
43
+ /** Extra columns an app adds to its chat table, such as a user id */
44
+ [column: string]: unknown;
45
+ }
46
+ export type MessageUpdate = Partial<Omit<StoredMessage, "id" | "chatId" | "role" | "createdAt">>;
47
+ export interface NewToolCall {
48
+ messageId: string;
49
+ toolCallId: string;
50
+ name: string;
51
+ arguments: string;
52
+ thought?: string | null;
53
+ thoughtSignature?: string | null;
54
+ }
55
+ export interface NewRequest {
56
+ chatId: string;
57
+ messageId: string | null;
58
+ provider: string;
59
+ model: string;
60
+ statusCode: number;
61
+ /** Milliseconds */
62
+ duration: number;
63
+ inputTokens: number;
64
+ outputTokens: number;
65
+ /** Input tokens the provider served from its prompt cache, when it says (v0.10.0+) */
66
+ cachedTokens?: number;
67
+ cost: number;
68
+ }
69
+ export interface RequestTotals {
70
+ inputTokens: number;
71
+ outputTokens: number;
72
+ cost: number;
73
+ }
74
+ export interface ChatStore {
75
+ createChat(chat: NewChat): Promise<StoredChat>;
76
+ findChat(id: string): Promise<StoredChat | null>;
77
+ /** Removes the chat with everything recorded under it */
78
+ deleteChat(id: string): Promise<void>;
79
+ createMessage(message: {
80
+ chatId: string;
81
+ role: string;
82
+ content: string | null;
83
+ }): Promise<StoredMessage>;
84
+ updateMessage(id: string, changes: MessageUpdate): Promise<StoredMessage>;
85
+ deleteMessage(id: string): Promise<void>;
86
+ /** A chat's messages, oldest first, leaving out any listed in excludeIds */
87
+ listMessages(chatId: string, options?: {
88
+ excludeIds?: string[];
89
+ }): Promise<StoredMessage[]>;
90
+ createToolCall(toolCall: NewToolCall): Promise<void>;
91
+ finishToolCall(messageId: string, toolCallId: string, finished: {
92
+ result: string;
93
+ thought?: string | null;
94
+ }): Promise<void>;
95
+ createRequest(request: NewRequest): Promise<void>;
96
+ requestTotals(chatId: string): Promise<RequestTotals>;
97
+ createAgentSession(session: {
98
+ agentClass: string;
99
+ chatId: string;
100
+ metadata: Record<string, unknown> | null;
101
+ }): Promise<StoredAgentSession>;
102
+ findAgentSession(id: string): Promise<StoredAgentSession | null>;
103
+ updateAgentSession(id: string, changes: {
104
+ metadata: Record<string, unknown>;
105
+ }): Promise<void>;
106
+ }
107
+ /** Whether a value is a ChatStore rather than a Prisma client. */
108
+ export declare function isChatStore(value: unknown): value is ChatStore;
109
+ //# sourceMappingURL=Store.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Store.d.ts","sourceRoot":"","sources":["../src/Store.ts"],"names":[],"mappings":"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"}
package/dist/Store.js ADDED
@@ -0,0 +1,14 @@
1
+ /* eslint-disable @typescript-eslint/no-explicit-any */
2
+ const storeMethods = [
3
+ "createChat",
4
+ "createMessage",
5
+ "updateMessage",
6
+ "listMessages",
7
+ "createRequest"
8
+ ];
9
+ /** Whether a value is a ChatStore rather than a Prisma client. */
10
+ export function isChatStore(value) {
11
+ return (typeof value === "object" &&
12
+ value !== null &&
13
+ storeMethods.every((method) => typeof value[method] === "function"));
14
+ }
@@ -0,0 +1,178 @@
1
+ import { ChatOptions, AskOptions, NodeLLMCore, Agent, AgentConfig, Message, ChatChunk, Usage } from "@node-llm/core";
2
+ /**
3
+ * Record structure for the LLM Agent Session table.
4
+ */
5
+ export interface AgentSessionRecord {
6
+ id: string;
7
+ agentClass: string;
8
+ chatId: string;
9
+ metadata?: Record<string, unknown> | null;
10
+ createdAt: Date;
11
+ updatedAt: Date;
12
+ }
13
+ /**
14
+ * Record structure for the LLM Message table.
15
+ */
16
+ export interface MessageRecord {
17
+ id: string;
18
+ chatId: string;
19
+ role: string;
20
+ content: string | null;
21
+ contentRaw?: string | null;
22
+ thinkingText?: string | null;
23
+ thinkingSignature?: string | null;
24
+ thinkingTokens?: number | null;
25
+ inputTokens?: number | null;
26
+ outputTokens?: number | null;
27
+ modelId?: string | null;
28
+ provider?: string | null;
29
+ createdAt: Date;
30
+ }
31
+ /**
32
+ * Table name customization.
33
+ */
34
+ export interface TableNames {
35
+ agentSession?: string;
36
+ chat?: string;
37
+ message?: string;
38
+ toolCall?: string;
39
+ request?: string;
40
+ }
41
+ /**
42
+ * Internal interface for dynamic Prisma model access
43
+ */
44
+ type AgentClass<T extends Agent<any, any> = Agent<any, any>> = (new (overrides?: Partial<AgentConfig<any> & ChatOptions>) => T) & {
45
+ name: string;
46
+ model?: string;
47
+ instructions?: unknown;
48
+ tools?: unknown;
49
+ };
50
+ /**
51
+ * AgentSession - Wraps an Agent instance with persistence capabilities.
52
+ *
53
+ * Follows "Code Wins" sovereignty:
54
+ * - Model, Tools, Instructions come from the Agent class (code)
55
+ * - Message history comes from the database
56
+ * - Metadata from DB is injected as 'inputs' for dynamic resolution
57
+ *
58
+ * @example
59
+ * ```typescript
60
+ * // Create a new session
61
+ * const session = await createAgentSession(prisma, llm, SupportAgent, {
62
+ * metadata: { userId: "123" }
63
+ * });
64
+ *
65
+ * // Resume a session
66
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, "sess_abc");
67
+ *
68
+ * // Agent behavior is always defined in code
69
+ * const result = await session.ask("Hello");
70
+ * ```
71
+ */
72
+ export declare class AgentSession<I extends Record<string, any> = Record<string, any>, T extends Agent<I, any> = Agent<I, any>> {
73
+ private llm;
74
+ private AgentClass;
75
+ private record;
76
+ private agent;
77
+ private currentMessageId;
78
+ private store;
79
+ private debug;
80
+ constructor(prismaOrStore: unknown, llm: NodeLLMCore, AgentClass: AgentClass<T>, record: AgentSessionRecord, tableNames?: TableNames, agent?: T, debug?: boolean);
81
+ private log;
82
+ /** Agent instance (for direct access if needed) */
83
+ get instance(): T;
84
+ /** Session ID for persistence */
85
+ get id(): string;
86
+ /** Underlying chat ID */
87
+ get chatId(): string;
88
+ /** Session metadata */
89
+ get metadata(): I | null | undefined;
90
+ /** Agent class name */
91
+ get agentClass(): string;
92
+ /** Model ID used by the agent */
93
+ get modelId(): string;
94
+ /** Cumulative usage for this session (from agent memory) */
95
+ get totalUsage(): Usage;
96
+ /** Current in-memory message history */
97
+ get history(): readonly Message[];
98
+ /**
99
+ * Helper to get a typed Prisma model by its dynamic name.
100
+ */
101
+ /**
102
+ * Register persistence hooks on the agent.
103
+ */
104
+ private registerHooks;
105
+ /**
106
+ * Send a message and persist the conversation.
107
+ */
108
+ ask(message: string, options?: AskOptions & {
109
+ inputs?: I;
110
+ }): Promise<MessageRecord>;
111
+ /**
112
+ * Stream a response and persist the conversation.
113
+ */
114
+ askStream(message: string, options?: AskOptions & {
115
+ inputs?: I;
116
+ }): AsyncGenerator<ChatChunk, MessageRecord, undefined>;
117
+ /**
118
+ * Returns a usage summary for this chat session.
119
+ */
120
+ stats(): Promise<Usage>;
121
+ /**
122
+ * Add a tool to the session (turn-level).
123
+ */
124
+ withTool(tool: any): this;
125
+ /**
126
+ * Add instructions to the session (turn-level).
127
+ */
128
+ withInstructions(instructions: string, options?: {
129
+ replace?: boolean;
130
+ }): this;
131
+ /**
132
+ * Returns the current full message history for this session.
133
+ */
134
+ messages(): Promise<MessageRecord[]>;
135
+ /**
136
+ * Delete the entire session and its history.
137
+ */
138
+ delete(): Promise<void>;
139
+ /**
140
+ * Update session metadata and re-resolve agent configuration.
141
+ */
142
+ updateMetadata(metadata: Partial<I>): Promise<void>;
143
+ }
144
+ /**
145
+ * Options for creating a new agent session.
146
+ */
147
+ export interface CreateAgentSessionOptions<I = any> {
148
+ metadata?: I;
149
+ tableNames?: TableNames;
150
+ debug?: boolean;
151
+ model?: string;
152
+ provider?: string;
153
+ instructions?: string;
154
+ maxToolCalls?: number;
155
+ /** Tools for this session, in place of the ones the agent class defines */
156
+ tools?: ChatOptions["tools"];
157
+ }
158
+ /**
159
+ * Creates a new agent session and its persistent chat record.
160
+ */
161
+ export declare function createAgentSession<I extends Record<string, any>, T extends Agent<I, any>>(prismaOrStore: unknown, llm: NodeLLMCore, AgentClass: AgentClass<T>, options?: CreateAgentSessionOptions<I>): Promise<AgentSession<I, T>>;
162
+ /**
163
+ * Options for loading an existing agent session.
164
+ */
165
+ export interface LoadAgentSessionOptions {
166
+ tableNames?: TableNames;
167
+ debug?: boolean;
168
+ }
169
+ /**
170
+ * Loads an existing agent session and re-instantiates the agent with history.
171
+ */
172
+ export declare function loadAgentSession<I extends Record<string, any>, T extends Agent<I, any>>(prismaOrStore: unknown, llm: NodeLLMCore, AgentClass: AgentClass<T>, sessionId: string, options?: LoadAgentSessionOptions): Promise<AgentSession<I, T> | null>;
173
+ export {};
174
+ /**
175
+ * Dynamic helper to access Prisma models by name.
176
+ * Handles both case-sensitive and case-insensitive lookups for flexibility.
177
+ */
178
+ //# sourceMappingURL=AgentSession.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentSession.d.ts","sourceRoot":"","sources":["../../../src/adapters/prisma/AgentSession.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,328 @@
1
+ import { toStore } from "./PrismaStore.js";
2
+ /**
3
+ * AgentSession - Wraps an Agent instance with persistence capabilities.
4
+ *
5
+ * Follows "Code Wins" sovereignty:
6
+ * - Model, Tools, Instructions come from the Agent class (code)
7
+ * - Message history comes from the database
8
+ * - Metadata from DB is injected as 'inputs' for dynamic resolution
9
+ *
10
+ * @example
11
+ * ```typescript
12
+ * // Create a new session
13
+ * const session = await createAgentSession(prisma, llm, SupportAgent, {
14
+ * metadata: { userId: "123" }
15
+ * });
16
+ *
17
+ * // Resume a session
18
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, "sess_abc");
19
+ *
20
+ * // Agent behavior is always defined in code
21
+ * const result = await session.ask("Hello");
22
+ * ```
23
+ */
24
+ export class AgentSession {
25
+ llm;
26
+ AgentClass;
27
+ record;
28
+ agent;
29
+ currentMessageId = null;
30
+ store;
31
+ debug;
32
+ constructor(prismaOrStore, llm, AgentClass, record, tableNames, agent = new AgentClass({
33
+ llm,
34
+ inputs: record.metadata
35
+ }), debug = false) {
36
+ this.llm = llm;
37
+ this.AgentClass = AgentClass;
38
+ this.record = record;
39
+ this.agent = agent;
40
+ this.debug = debug;
41
+ this.store = toStore(prismaOrStore, tableNames);
42
+ this.registerHooks();
43
+ }
44
+ log(...args) {
45
+ if (this.debug) {
46
+ console.log(`[@node-llm/orm]`, ...args);
47
+ }
48
+ }
49
+ /** Agent instance (for direct access if needed) */
50
+ get instance() {
51
+ return this.agent;
52
+ }
53
+ /** Session ID for persistence */
54
+ get id() {
55
+ return this.record.id;
56
+ }
57
+ /** Underlying chat ID */
58
+ get chatId() {
59
+ return this.record.chatId;
60
+ }
61
+ /** Session metadata */
62
+ get metadata() {
63
+ return this.record.metadata;
64
+ }
65
+ /** Agent class name */
66
+ get agentClass() {
67
+ return this.record.agentClass;
68
+ }
69
+ /** Model ID used by the agent */
70
+ get modelId() {
71
+ return this.agent.modelId;
72
+ }
73
+ /** Cumulative usage for this session (from agent memory) */
74
+ get totalUsage() {
75
+ return this.agent.totalUsage;
76
+ }
77
+ /** Current in-memory message history */
78
+ get history() {
79
+ return this.agent.history;
80
+ }
81
+ /**
82
+ * Helper to get a typed Prisma model by its dynamic name.
83
+ */
84
+ /**
85
+ * Register persistence hooks on the agent.
86
+ */
87
+ registerHooks() {
88
+ this.agent.onToolCallStart(async (tc) => {
89
+ const toolCall = tc;
90
+ if (!this.currentMessageId)
91
+ return;
92
+ await this.store.createToolCall({
93
+ messageId: this.currentMessageId,
94
+ toolCallId: toolCall.id,
95
+ name: toolCall.function.name,
96
+ arguments: toolCall.function.arguments
97
+ });
98
+ });
99
+ this.agent.onToolCallEnd(async (tc, result) => {
100
+ const toolCall = tc;
101
+ if (!this.currentMessageId)
102
+ return;
103
+ try {
104
+ await this.store.finishToolCall(this.currentMessageId, toolCall.id, {
105
+ result: typeof result === "string" ? result : JSON.stringify(result)
106
+ });
107
+ }
108
+ catch (e) {
109
+ this.log(`Failed to update tool call result: ${e}`);
110
+ }
111
+ });
112
+ this.agent.afterResponse(async (response) => {
113
+ await this.store.createRequest({
114
+ chatId: this.chatId,
115
+ messageId: this.currentMessageId,
116
+ provider: response.provider || "unknown",
117
+ model: response.model || "unknown",
118
+ statusCode: 200,
119
+ duration: response.latency || 0,
120
+ inputTokens: response.usage?.input_tokens || 0,
121
+ outputTokens: response.usage?.output_tokens || 0,
122
+ cachedTokens: response.usage?.cached_tokens,
123
+ cost: response.usage?.cost || 0
124
+ });
125
+ });
126
+ }
127
+ /**
128
+ * Send a message and persist the conversation.
129
+ */
130
+ async ask(message, options = {}) {
131
+ // Persist user message
132
+ await this.store.createMessage({ chatId: this.chatId, role: "user", content: message });
133
+ // Create placeholder for assistant message
134
+ const assistantMessage = await this.store.createMessage({
135
+ chatId: this.chatId,
136
+ role: "assistant",
137
+ content: null
138
+ });
139
+ this.currentMessageId = assistantMessage.id;
140
+ try {
141
+ // Merge turn-level inputs with session metadata
142
+ const inputs = { ...this.record.metadata, ...options.inputs };
143
+ // Get response from agent (uses code-defined config + injected history)
144
+ const response = await this.agent.ask(message, { ...options, inputs });
145
+ // Update assistant message with response
146
+ return (await this.store.updateMessage(assistantMessage.id, {
147
+ content: response.content,
148
+ contentRaw: JSON.stringify(response.meta),
149
+ inputTokens: response.usage?.input_tokens || 0,
150
+ outputTokens: response.usage?.output_tokens || 0,
151
+ thinkingText: response.thinking?.text || null,
152
+ thinkingSignature: response.thinking?.signature || null,
153
+ thinkingTokens: response.thinking?.tokens || null,
154
+ modelId: response.model || null,
155
+ provider: response.provider || null
156
+ }));
157
+ }
158
+ catch (error) {
159
+ // Clean up placeholder on error
160
+ await this.store.deleteMessage(assistantMessage.id);
161
+ throw error;
162
+ }
163
+ }
164
+ /**
165
+ * Stream a response and persist the conversation.
166
+ */
167
+ async *askStream(message, options = {}) {
168
+ // Persist user message
169
+ await this.store.createMessage({ chatId: this.chatId, role: "user", content: message });
170
+ // Create placeholder for assistant message
171
+ const assistantMessage = await this.store.createMessage({
172
+ chatId: this.chatId,
173
+ role: "assistant",
174
+ content: null
175
+ });
176
+ this.currentMessageId = assistantMessage.id;
177
+ try {
178
+ // Merge turn-level inputs with session metadata
179
+ const inputs = { ...this.record.metadata, ...options.inputs };
180
+ const stream = this.agent.stream(message, { ...options, inputs });
181
+ let fullContent = "";
182
+ let lastChunk = null;
183
+ for await (const chunk of stream) {
184
+ fullContent += chunk.content;
185
+ lastChunk = chunk;
186
+ yield chunk;
187
+ }
188
+ // Final update with accumulated result
189
+ return (await this.store.updateMessage(assistantMessage.id, {
190
+ content: fullContent,
191
+ inputTokens: lastChunk?.usage?.input_tokens || 0,
192
+ outputTokens: lastChunk?.usage?.output_tokens || 0,
193
+ thinkingText: lastChunk?.thinking?.text || null,
194
+ thinkingSignature: lastChunk?.thinking?.signature || null,
195
+ thinkingTokens: lastChunk?.thinking?.tokens || null,
196
+ modelId: lastChunk?.metadata?.model || null,
197
+ provider: lastChunk?.metadata?.provider || null
198
+ }));
199
+ }
200
+ catch (error) {
201
+ await this.store.deleteMessage(assistantMessage.id);
202
+ throw error;
203
+ }
204
+ }
205
+ /**
206
+ * Returns a usage summary for this chat session.
207
+ */
208
+ async stats() {
209
+ const totals = await this.store.requestTotals(this.chatId);
210
+ return {
211
+ input_tokens: totals.inputTokens,
212
+ output_tokens: totals.outputTokens,
213
+ total_tokens: totals.inputTokens + totals.outputTokens,
214
+ cost: totals.cost
215
+ };
216
+ }
217
+ /**
218
+ * Add a tool to the session (turn-level).
219
+ */
220
+ withTool(tool) {
221
+ this.agent.use(tool);
222
+ return this;
223
+ }
224
+ /**
225
+ * Add instructions to the session (turn-level).
226
+ */
227
+ withInstructions(instructions, options) {
228
+ this.agent.withInstructions(instructions, options);
229
+ return this;
230
+ }
231
+ /**
232
+ * Returns the current full message history for this session.
233
+ */
234
+ async messages() {
235
+ return (await this.store.listMessages(this.chatId));
236
+ }
237
+ /**
238
+ * Delete the entire session and its history.
239
+ */
240
+ async delete() {
241
+ await this.store.deleteChat(this.chatId);
242
+ // AgentSession record is deleted via Cascade from LlmChat
243
+ }
244
+ /**
245
+ * Update session metadata and re-resolve agent configuration.
246
+ */
247
+ async updateMetadata(metadata) {
248
+ const newMetadata = { ...this.record.metadata, ...metadata };
249
+ await this.store.updateAgentSession(this.id, { metadata: newMetadata });
250
+ this.record.metadata = newMetadata;
251
+ // Apply changes to the underlying agent immediately
252
+ // resolveLazyConfig is private, so we need a cast or make it protected.
253
+ // Given we are in the same package, we can cast.
254
+ this.agent.resolveLazyConfig(newMetadata);
255
+ }
256
+ }
257
+ /**
258
+ * Creates a new agent session and its persistent chat record.
259
+ */
260
+ export async function createAgentSession(prismaOrStore, llm, AgentClass, options = {}) {
261
+ const store = toStore(prismaOrStore, options.tableNames);
262
+ if (options.debug) {
263
+ console.log(`[@node-llm/orm] createAgentSession: agentClass=${AgentClass.name}`);
264
+ }
265
+ // 1. Create underlying LlmChat record
266
+ const chatRecord = await store.createChat({
267
+ model: options.model || AgentClass.model || null,
268
+ provider: options.provider || null,
269
+ instructions: options.instructions ||
270
+ (typeof AgentClass.instructions === "string" ? AgentClass.instructions : null),
271
+ metadata: null // Runtime metadata goes in Chat, session context in AgentSession
272
+ });
273
+ // 2. Create AgentSession record
274
+ const sessionRecord = (await store.createAgentSession({
275
+ agentClass: AgentClass.name,
276
+ chatId: chatRecord.id,
277
+ metadata: options.metadata || null
278
+ }));
279
+ // 3. Instantiate Agent with overrides
280
+ const agent = new AgentClass({
281
+ llm,
282
+ inputs: sessionRecord.metadata,
283
+ model: options.model,
284
+ provider: options.provider,
285
+ instructions: options.instructions,
286
+ maxToolCalls: options.maxToolCalls,
287
+ ...(options.tools ? { tools: options.tools } : {})
288
+ });
289
+ return new AgentSession(store, llm, AgentClass, sessionRecord, options.tableNames, agent, options.debug);
290
+ }
291
+ /**
292
+ * Loads an existing agent session and re-instantiates the agent with history.
293
+ */
294
+ export async function loadAgentSession(prismaOrStore, llm, AgentClass, sessionId, options = {}) {
295
+ const store = toStore(prismaOrStore, options.tableNames);
296
+ if (options.debug) {
297
+ console.log(`[@node-llm/orm] loadAgentSession: id=${sessionId}`);
298
+ }
299
+ // 1. Find session record
300
+ const sessionRecord = (await store.findAgentSession(sessionId));
301
+ if (!sessionRecord) {
302
+ return null;
303
+ }
304
+ // 1.5. Validate Agent Class (Code Wins Sovereignty)
305
+ if (sessionRecord.agentClass !== AgentClass.name) {
306
+ throw new Error(`Agent class mismatch: Session "${sessionId}" was created for "${sessionRecord.agentClass}", but is being loaded with "${AgentClass.name}".`);
307
+ }
308
+ // 2. Load message history
309
+ const messages = (await store.listMessages(sessionRecord.chatId));
310
+ // 3. Convert DB messages to NodeLLM Message format
311
+ const history = messages.map((m) => ({
312
+ role: m.role,
313
+ content: m.content || ""
314
+ }));
315
+ // 4. Instantiate agent with injected history, LLM, AND metadata (as inputs)
316
+ // "Code Wins" - model, tools, instructions come from AgentClass
317
+ // Metadata from DB handles the lazy resolution of behavior
318
+ const agent = new AgentClass({
319
+ llm,
320
+ messages: history,
321
+ inputs: sessionRecord.metadata
322
+ });
323
+ return new AgentSession(store, llm, AgentClass, sessionRecord, options.tableNames, agent, options.debug);
324
+ }
325
+ /**
326
+ * Dynamic helper to access Prisma models by name.
327
+ * Handles both case-sensitive and case-insensitive lookups for flexibility.
328
+ */