@node-llm/orm 0.10.1 → 0.12.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.
- package/CHANGELOG.md +139 -0
- package/dist/BaseChat.d.ts +2 -2
- package/dist/BaseChat.d.ts.map +1 -1
- package/dist/Store.d.ts +28 -1
- package/dist/Store.d.ts.map +1 -1
- package/dist/adapters/prisma/AgentSession.d.ts +42 -9
- package/dist/adapters/prisma/AgentSession.d.ts.map +1 -1
- package/dist/adapters/prisma/AgentSession.js +89 -16
- package/dist/adapters/prisma/Chat.d.ts +5 -0
- package/dist/adapters/prisma/Chat.d.ts.map +1 -1
- package/dist/adapters/prisma/Chat.js +38 -4
- package/dist/adapters/prisma/PrismaStore.d.ts +4 -2
- package/dist/adapters/prisma/PrismaStore.d.ts.map +1 -1
- package/dist/adapters/prisma/PrismaStore.js +15 -2
- package/dist/adapters/prisma/index.d.ts +1 -1
- package/dist/adapters/prisma/index.d.ts.map +1 -1
- package/dist/errors.d.ts +14 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +15 -0
- package/dist/history.d.ts +10 -0
- package/dist/history.d.ts.map +1 -0
- package/dist/history.js +42 -0
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/redact.d.ts +20 -0
- package/dist/redact.d.ts.map +1 -0
- package/dist/redact.js +118 -0
- package/package.json +2 -2
- package/src/BaseChat.ts +2 -2
- package/src/Store.ts +30 -1
- package/src/adapters/prisma/AgentSession.ts +149 -25
- package/src/adapters/prisma/Chat.ts +45 -5
- package/src/adapters/prisma/PrismaStore.ts +21 -3
- package/src/adapters/prisma/index.ts +3 -0
- package/src/errors.ts +15 -0
- package/src/history.ts +48 -0
- package/src/index.ts +4 -0
- package/src/redact.ts +157 -0
- package/test/AgentSession.test.ts +12 -2
- package/test/CountCall.test.ts +147 -0
- package/test/Redact.test.ts +228 -0
- package/test/Resume.test.ts +232 -0
- package/test/SessionData.test.ts +109 -0
- package/test/SessionOverrides.test.ts +130 -0
- package/test/StoreStops.test.ts +262 -0
- package/tsconfig.tsbuildinfo +1 -1
|
@@ -17,6 +17,29 @@ import {
|
|
|
17
17
|
*/
|
|
18
18
|
import type { ChatStore } from "../../Store.js";
|
|
19
19
|
import { toStore } from "./PrismaStore.js";
|
|
20
|
+
import { storedHistory } from "../../history.js";
|
|
21
|
+
import { StoppedByStoreError } from "../../errors.js";
|
|
22
|
+
import { redactorFor, type StoreRedactor } from "../../redact.js";
|
|
23
|
+
|
|
24
|
+
/** What an agent's answers parse to: its schema's type, or unknown without one. */
|
|
25
|
+
export type AgentData<T> = T extends Agent<any, infer S> ? S : unknown;
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* The saved assistant message, with the answer's parsed `data`: checked against the agent's schema
|
|
29
|
+
* when it has a Zod one, and found inside a code fence or surrounding text. Reading `data` throws
|
|
30
|
+
* the schema's error when the answer doesn't match. `data` isn't a column, so it isn't saved or
|
|
31
|
+
* sent when the record is serialized.
|
|
32
|
+
*/
|
|
33
|
+
export type AgentAnswer<T> = MessageRecord & { readonly data: AgentData<T> };
|
|
34
|
+
|
|
35
|
+
function withData<T>(record: MessageRecord, response: { data: unknown }): AgentAnswer<T> {
|
|
36
|
+
Object.defineProperty(record, "data", {
|
|
37
|
+
get: () => response.data,
|
|
38
|
+
enumerable: false,
|
|
39
|
+
configurable: true
|
|
40
|
+
});
|
|
41
|
+
return record as AgentAnswer<T>;
|
|
42
|
+
}
|
|
20
43
|
|
|
21
44
|
/**
|
|
22
45
|
* Record structure for the LLM Agent Session table.
|
|
@@ -99,6 +122,8 @@ export class AgentSession<
|
|
|
99
122
|
T extends Agent<I, any> = Agent<I, any>
|
|
100
123
|
> {
|
|
101
124
|
private currentMessageId: string | null = null;
|
|
125
|
+
/** Set when the store asks to stop; the next request throws it instead */
|
|
126
|
+
private stopReason?: string;
|
|
102
127
|
private store: ChatStore;
|
|
103
128
|
private debug: boolean;
|
|
104
129
|
|
|
@@ -197,8 +222,33 @@ export class AgentSession<
|
|
|
197
222
|
}
|
|
198
223
|
});
|
|
199
224
|
|
|
225
|
+
this.agent.beforeRequest(async () => {
|
|
226
|
+
if (this.stopReason !== undefined) throw new StoppedByStoreError(this.stopReason);
|
|
227
|
+
});
|
|
228
|
+
|
|
229
|
+
// Subagents started from this agent's tools (Agent.toTool, runAgents): their requests are
|
|
230
|
+
// recorded under the answer being written, and the store's `{ stop }` stops them too.
|
|
231
|
+
this.agent.beforeSubagentRequest?.(async () => {
|
|
232
|
+
if (this.stopReason !== undefined) throw new StoppedByStoreError(this.stopReason);
|
|
233
|
+
});
|
|
234
|
+
this.agent.afterSubagentResponse?.(async (sub) => {
|
|
235
|
+
const recorded = await this.store.createRequest({
|
|
236
|
+
chatId: this.chatId,
|
|
237
|
+
messageId: this.currentMessageId,
|
|
238
|
+
provider: sub.provider || "unknown",
|
|
239
|
+
model: sub.model || "unknown",
|
|
240
|
+
statusCode: 200,
|
|
241
|
+
duration: sub.latency || 0,
|
|
242
|
+
inputTokens: sub.usage?.input_tokens || 0,
|
|
243
|
+
outputTokens: sub.usage?.output_tokens || 0,
|
|
244
|
+
cachedTokens: sub.usage?.cached_tokens,
|
|
245
|
+
cost: sub.usage?.cost || 0
|
|
246
|
+
});
|
|
247
|
+
if (recorded && recorded.stop !== undefined) this.stopReason = recorded.stop;
|
|
248
|
+
});
|
|
249
|
+
|
|
200
250
|
this.agent.afterResponse(async (response) => {
|
|
201
|
-
await this.store.createRequest({
|
|
251
|
+
const recorded = await this.store.createRequest({
|
|
202
252
|
chatId: this.chatId,
|
|
203
253
|
messageId: this.currentMessageId,
|
|
204
254
|
provider: response.provider || "unknown",
|
|
@@ -210,13 +260,42 @@ export class AgentSession<
|
|
|
210
260
|
cachedTokens: response.usage?.cached_tokens,
|
|
211
261
|
cost: response.usage?.cost || 0
|
|
212
262
|
});
|
|
263
|
+
if (recorded && recorded.stop !== undefined) this.stopReason = recorded.stop;
|
|
264
|
+
});
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/**
|
|
268
|
+
* Records a call made outside the agent's own requests, such as a tool asking another model
|
|
269
|
+
* about an image: as a request row of this chat, under the answer being written now, and in the
|
|
270
|
+
* agent's usage, so `stats()`, `totalUsage` and the ask's `maxCost` all include it.
|
|
271
|
+
*/
|
|
272
|
+
async countCall(response: {
|
|
273
|
+
usage?: Usage;
|
|
274
|
+
model?: string;
|
|
275
|
+
provider?: string;
|
|
276
|
+
latency?: number;
|
|
277
|
+
}): Promise<void> {
|
|
278
|
+
const usage = response.usage;
|
|
279
|
+
if (!usage) return;
|
|
280
|
+
this.agent.countUsage(usage);
|
|
281
|
+
await this.store.createRequest({
|
|
282
|
+
chatId: this.chatId,
|
|
283
|
+
messageId: this.currentMessageId,
|
|
284
|
+
provider: response.provider || "unknown",
|
|
285
|
+
model: response.model || "unknown",
|
|
286
|
+
statusCode: 200,
|
|
287
|
+
duration: response.latency || 0,
|
|
288
|
+
inputTokens: usage.input_tokens || 0,
|
|
289
|
+
outputTokens: usage.output_tokens || 0,
|
|
290
|
+
cachedTokens: usage.cached_tokens,
|
|
291
|
+
cost: usage.cost || 0
|
|
213
292
|
});
|
|
214
293
|
}
|
|
215
294
|
|
|
216
295
|
/**
|
|
217
296
|
* Send a message and persist the conversation.
|
|
218
297
|
*/
|
|
219
|
-
async ask(message: string, options: AskOptions & { inputs?: I } = {}): Promise<
|
|
298
|
+
async ask(message: string, options: AskOptions & { inputs?: I } = {}): Promise<AgentAnswer<T>> {
|
|
220
299
|
// Persist user message
|
|
221
300
|
await this.store.createMessage({ chatId: this.chatId, role: "user", content: message });
|
|
222
301
|
|
|
@@ -237,7 +316,7 @@ export class AgentSession<
|
|
|
237
316
|
const response = await this.agent.ask(message, { ...options, inputs });
|
|
238
317
|
|
|
239
318
|
// Update assistant message with response
|
|
240
|
-
|
|
319
|
+
const saved = (await this.store.updateMessage(assistantMessage.id, {
|
|
241
320
|
content: response.content,
|
|
242
321
|
contentRaw: JSON.stringify(response.meta),
|
|
243
322
|
inputTokens: response.usage?.input_tokens || 0,
|
|
@@ -248,6 +327,7 @@ export class AgentSession<
|
|
|
248
327
|
modelId: response.model || null,
|
|
249
328
|
provider: response.provider || null
|
|
250
329
|
})) as MessageRecord;
|
|
330
|
+
return withData<T>(saved, response);
|
|
251
331
|
} catch (error) {
|
|
252
332
|
// Clean up placeholder on error
|
|
253
333
|
await this.store.deleteMessage(assistantMessage.id);
|
|
@@ -367,19 +447,50 @@ export class AgentSession<
|
|
|
367
447
|
}
|
|
368
448
|
}
|
|
369
449
|
|
|
450
|
+
/**
|
|
451
|
+
* Agent settings for one session, in place of the agent class's own, such as `maxCost` or
|
|
452
|
+
* `maxToolCalls` for a run with its own budget. Not kept in the store: pass them again to
|
|
453
|
+
* loadAgentSession().
|
|
454
|
+
*/
|
|
455
|
+
export type AgentSessionOverrides<I = any> = Omit<
|
|
456
|
+
Partial<AgentConfig<I>>,
|
|
457
|
+
"llm" | "inputs" | "tools" | "schema"
|
|
458
|
+
> & {
|
|
459
|
+
/** Tools for this session, in place of the ones the agent class defines */
|
|
460
|
+
tools?: ChatOptions["tools"];
|
|
461
|
+
};
|
|
462
|
+
|
|
370
463
|
/**
|
|
371
464
|
* Options for creating a new agent session.
|
|
372
465
|
*/
|
|
373
|
-
export interface CreateAgentSessionOptions<I = any> {
|
|
466
|
+
export interface CreateAgentSessionOptions<I = any> extends AgentSessionOverrides<I> {
|
|
374
467
|
metadata?: I;
|
|
375
468
|
tableNames?: TableNames;
|
|
469
|
+
/** Changes text before it is saved, after keys and tokens are masked; see StoreRedactor. */
|
|
470
|
+
redact?: StoreRedactor;
|
|
376
471
|
debug?: boolean;
|
|
377
|
-
model?: string;
|
|
378
|
-
provider?: string;
|
|
379
472
|
instructions?: string;
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
473
|
+
}
|
|
474
|
+
|
|
475
|
+
/** The agent settings in session options, leaving out the session's own options. */
|
|
476
|
+
function agentOverrides<I>(
|
|
477
|
+
options: AgentSessionOverrides<I> & {
|
|
478
|
+
metadata?: unknown;
|
|
479
|
+
tableNames?: unknown;
|
|
480
|
+
debug?: unknown;
|
|
481
|
+
redact?: unknown;
|
|
482
|
+
}
|
|
483
|
+
): AgentSessionOverrides<I> {
|
|
484
|
+
const {
|
|
485
|
+
metadata: _metadata,
|
|
486
|
+
tableNames: _tableNames,
|
|
487
|
+
debug: _debug,
|
|
488
|
+
redact: _redact,
|
|
489
|
+
...overrides
|
|
490
|
+
} = options;
|
|
491
|
+
return Object.fromEntries(
|
|
492
|
+
Object.entries(overrides).filter(([, value]) => value !== undefined)
|
|
493
|
+
) as AgentSessionOverrides<I>;
|
|
383
494
|
}
|
|
384
495
|
|
|
385
496
|
/**
|
|
@@ -391,7 +502,14 @@ export async function createAgentSession<I extends Record<string, any>, T extend
|
|
|
391
502
|
AgentClass: AgentClass<T>,
|
|
392
503
|
options: CreateAgentSessionOptions<I> = {}
|
|
393
504
|
): Promise<AgentSession<I, T>> {
|
|
394
|
-
const store = toStore(
|
|
505
|
+
const store = toStore(
|
|
506
|
+
prismaOrStore,
|
|
507
|
+
options.tableNames,
|
|
508
|
+
redactorFor(options.redact, [
|
|
509
|
+
...((AgentClass as { middlewares?: unknown[] }).middlewares ?? []),
|
|
510
|
+
...(options.middlewares ?? [])
|
|
511
|
+
])
|
|
512
|
+
);
|
|
395
513
|
|
|
396
514
|
if (options.debug) {
|
|
397
515
|
console.log(`[@node-llm/orm] createAgentSession: agentClass=${AgentClass.name}`);
|
|
@@ -416,13 +534,9 @@ export async function createAgentSession<I extends Record<string, any>, T extend
|
|
|
416
534
|
|
|
417
535
|
// 3. Instantiate Agent with overrides
|
|
418
536
|
const agent = new AgentClass({
|
|
537
|
+
...agentOverrides<I>(options),
|
|
419
538
|
llm,
|
|
420
|
-
inputs: sessionRecord.metadata as I
|
|
421
|
-
model: options.model,
|
|
422
|
-
provider: options.provider,
|
|
423
|
-
instructions: options.instructions,
|
|
424
|
-
maxToolCalls: options.maxToolCalls,
|
|
425
|
-
...(options.tools ? { tools: options.tools } : {})
|
|
539
|
+
inputs: sessionRecord.metadata as I
|
|
426
540
|
});
|
|
427
541
|
|
|
428
542
|
return new AgentSession<I, T>(
|
|
@@ -439,8 +553,10 @@ export async function createAgentSession<I extends Record<string, any>, T extend
|
|
|
439
553
|
/**
|
|
440
554
|
* Options for loading an existing agent session.
|
|
441
555
|
*/
|
|
442
|
-
export interface LoadAgentSessionOptions {
|
|
556
|
+
export interface LoadAgentSessionOptions<I = any> extends AgentSessionOverrides<I> {
|
|
443
557
|
tableNames?: TableNames;
|
|
558
|
+
/** Changes text before it is saved, after keys and tokens are masked; see StoreRedactor. */
|
|
559
|
+
redact?: StoreRedactor;
|
|
444
560
|
debug?: boolean;
|
|
445
561
|
}
|
|
446
562
|
|
|
@@ -452,9 +568,16 @@ export async function loadAgentSession<I extends Record<string, any>, T extends
|
|
|
452
568
|
llm: NodeLLMCore,
|
|
453
569
|
AgentClass: AgentClass<T>,
|
|
454
570
|
sessionId: string,
|
|
455
|
-
options: LoadAgentSessionOptions = {}
|
|
571
|
+
options: LoadAgentSessionOptions<I> = {}
|
|
456
572
|
): Promise<AgentSession<I, T> | null> {
|
|
457
|
-
const store = toStore(
|
|
573
|
+
const store = toStore(
|
|
574
|
+
prismaOrStore,
|
|
575
|
+
options.tableNames,
|
|
576
|
+
redactorFor(options.redact, [
|
|
577
|
+
...((AgentClass as { middlewares?: unknown[] }).middlewares ?? []),
|
|
578
|
+
...(options.middlewares ?? [])
|
|
579
|
+
])
|
|
580
|
+
);
|
|
458
581
|
|
|
459
582
|
if (options.debug) {
|
|
460
583
|
console.log(`[@node-llm/orm] loadAgentSession: id=${sessionId}`);
|
|
@@ -474,19 +597,20 @@ export async function loadAgentSession<I extends Record<string, any>, T extends
|
|
|
474
597
|
);
|
|
475
598
|
}
|
|
476
599
|
|
|
477
|
-
// 2. Load message history
|
|
600
|
+
// 2. Load message history, with the tool calls of earlier turns when the store keeps them
|
|
478
601
|
const messages = (await store.listMessages(sessionRecord.chatId)) as MessageRecord[];
|
|
602
|
+
const toolCalls = store.listToolCalls
|
|
603
|
+
? await store.listToolCalls(messages.map((message) => message.id))
|
|
604
|
+
: [];
|
|
479
605
|
|
|
480
|
-
// 3. Convert DB
|
|
481
|
-
const history: Message[] = messages
|
|
482
|
-
role: m.role as "user" | "assistant" | "system",
|
|
483
|
-
content: m.content || ""
|
|
484
|
-
}));
|
|
606
|
+
// 3. Convert DB records to NodeLLM messages
|
|
607
|
+
const history: Message[] = storedHistory(messages, toolCalls);
|
|
485
608
|
|
|
486
609
|
// 4. Instantiate agent with injected history, LLM, AND metadata (as inputs)
|
|
487
610
|
// "Code Wins" - model, tools, instructions come from AgentClass
|
|
488
611
|
// Metadata from DB handles the lazy resolution of behavior
|
|
489
612
|
const agent = new AgentClass({
|
|
613
|
+
...agentOverrides<I>(options),
|
|
490
614
|
llm,
|
|
491
615
|
messages: history,
|
|
492
616
|
inputs: sessionRecord.metadata as I
|
|
@@ -3,6 +3,8 @@ import type { NodeLLMCore, ChatChunk, AskOptions, Usage } from "@node-llm/core";
|
|
|
3
3
|
import { BaseChat, type ChatRecord, type ChatOptions } from "../../BaseChat.js";
|
|
4
4
|
import type { ChatStore } from "../../Store.js";
|
|
5
5
|
import { toStore } from "./PrismaStore.js";
|
|
6
|
+
import { StoppedByStoreError } from "../../errors.js";
|
|
7
|
+
import { redactorFor, type StoreRedactor } from "../../redact.js";
|
|
6
8
|
|
|
7
9
|
export { type ChatRecord, type ChatOptions };
|
|
8
10
|
|
|
@@ -37,6 +39,8 @@ export interface TableNames {
|
|
|
37
39
|
export class Chat extends BaseChat {
|
|
38
40
|
private store: ChatStore;
|
|
39
41
|
private persistenceConfig: Required<NonNullable<ChatOptions["persistence"]>>;
|
|
42
|
+
/** Set when the store asks to stop; the next request throws it instead */
|
|
43
|
+
private stopReason?: string;
|
|
40
44
|
|
|
41
45
|
constructor(
|
|
42
46
|
prismaOrStore: unknown,
|
|
@@ -117,6 +121,32 @@ export class Chat extends BaseChat {
|
|
|
117
121
|
for (const h of this.userHooks.onToolCallEnd) await h(call, result);
|
|
118
122
|
});
|
|
119
123
|
|
|
124
|
+
coreChat.beforeRequest(async () => {
|
|
125
|
+
if (this.stopReason !== undefined) throw new StoppedByStoreError(this.stopReason);
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
// Subagents started from this chat's tools (Agent.toTool, runAgents): their requests are
|
|
129
|
+
// recorded under this chat's answer, and the store's `{ stop }` stops them too.
|
|
130
|
+
coreChat.beforeSubagentRequest?.(async () => {
|
|
131
|
+
if (this.stopReason !== undefined) throw new StoppedByStoreError(this.stopReason);
|
|
132
|
+
});
|
|
133
|
+
coreChat.afterSubagentResponse?.(async (sub: any) => {
|
|
134
|
+
if (!this.persistenceConfig.requests) return;
|
|
135
|
+
const recorded = await this.store.createRequest({
|
|
136
|
+
chatId: this.id,
|
|
137
|
+
messageId: assistantMessageId,
|
|
138
|
+
provider: sub.provider || "unknown",
|
|
139
|
+
model: sub.model || "unknown",
|
|
140
|
+
statusCode: 200,
|
|
141
|
+
duration: sub.latency || 0,
|
|
142
|
+
inputTokens: sub.usage?.input_tokens || 0,
|
|
143
|
+
outputTokens: sub.usage?.output_tokens || 0,
|
|
144
|
+
cachedTokens: sub.usage?.cached_tokens,
|
|
145
|
+
cost: sub.usage?.cost || 0
|
|
146
|
+
});
|
|
147
|
+
if (recorded && recorded.stop !== undefined) this.stopReason = recorded.stop;
|
|
148
|
+
});
|
|
149
|
+
|
|
120
150
|
coreChat.afterResponse(async (finalResp: any) => {
|
|
121
151
|
this.log(
|
|
122
152
|
`Internal afterResponse triggered. Calling ${this.userHooks.afterResponse.length} user hooks.`
|
|
@@ -130,7 +160,7 @@ export class Chat extends BaseChat {
|
|
|
130
160
|
|
|
131
161
|
// Only persist if requests persistence is enabled
|
|
132
162
|
if (this.persistenceConfig.requests) {
|
|
133
|
-
await this.store.createRequest({
|
|
163
|
+
const recorded = await this.store.createRequest({
|
|
134
164
|
chatId: this.id,
|
|
135
165
|
messageId: assistantMessageId,
|
|
136
166
|
provider: finalResp.provider || provider || "unknown",
|
|
@@ -142,6 +172,7 @@ export class Chat extends BaseChat {
|
|
|
142
172
|
cachedTokens: finalResp.usage?.cached_tokens,
|
|
143
173
|
cost: finalResp.usage?.cost || 0
|
|
144
174
|
});
|
|
175
|
+
if (recorded && recorded.stop !== undefined) this.stopReason = recorded.stop;
|
|
145
176
|
}
|
|
146
177
|
|
|
147
178
|
return finalResp;
|
|
@@ -349,7 +380,7 @@ export class Chat extends BaseChat {
|
|
|
349
380
|
export async function createChat<T = Record<string, any>>(
|
|
350
381
|
prismaOrStore: unknown,
|
|
351
382
|
llm: NodeLLMCore,
|
|
352
|
-
options: ChatOptions & { tableNames?: TableNames } & T = {} as any
|
|
383
|
+
options: ChatOptions & { tableNames?: TableNames; redact?: StoreRedactor } & T = {} as any
|
|
353
384
|
): Promise<Chat> {
|
|
354
385
|
const {
|
|
355
386
|
model,
|
|
@@ -367,10 +398,15 @@ export async function createChat<T = Record<string, any>>(
|
|
|
367
398
|
headers: _headers,
|
|
368
399
|
requestTimeout: _requestTimeout,
|
|
369
400
|
params: _params,
|
|
401
|
+
redact: _redact,
|
|
370
402
|
...extras
|
|
371
403
|
} = options;
|
|
372
404
|
|
|
373
|
-
const store = toStore(
|
|
405
|
+
const store = toStore(
|
|
406
|
+
prismaOrStore,
|
|
407
|
+
options.tableNames,
|
|
408
|
+
redactorFor(options.redact, options.middlewares)
|
|
409
|
+
);
|
|
374
410
|
if (options.debug) console.log(`[@node-llm/orm] createChat: store=${store.constructor.name}`);
|
|
375
411
|
|
|
376
412
|
const record = await store.createChat({
|
|
@@ -391,9 +427,13 @@ export async function loadChat(
|
|
|
391
427
|
prismaOrStore: unknown,
|
|
392
428
|
llm: NodeLLMCore,
|
|
393
429
|
chatId: string,
|
|
394
|
-
options: ChatOptions & { tableNames?: TableNames; debug?: boolean } = {}
|
|
430
|
+
options: ChatOptions & { tableNames?: TableNames; debug?: boolean; redact?: StoreRedactor } = {}
|
|
395
431
|
): Promise<Chat | null> {
|
|
396
|
-
const store = toStore(
|
|
432
|
+
const store = toStore(
|
|
433
|
+
prismaOrStore,
|
|
434
|
+
options.tableNames,
|
|
435
|
+
redactorFor(options.redact, options.middlewares)
|
|
436
|
+
);
|
|
397
437
|
if (options.debug) console.log(`[@node-llm/orm] loadChat: store=${store.constructor.name}`);
|
|
398
438
|
|
|
399
439
|
const record = await store.findChat(chatId);
|
|
@@ -8,9 +8,11 @@ import type {
|
|
|
8
8
|
RequestTotals,
|
|
9
9
|
StoredAgentSession,
|
|
10
10
|
StoredChat,
|
|
11
|
-
StoredMessage
|
|
11
|
+
StoredMessage,
|
|
12
|
+
StoredToolCall
|
|
12
13
|
} from "../../Store.js";
|
|
13
14
|
import { isChatStore } from "../../Store.js";
|
|
15
|
+
import { redactingStore, type StoreRedactor } from "../../redact.js";
|
|
14
16
|
|
|
15
17
|
export interface TableNames {
|
|
16
18
|
agentSession?: string;
|
|
@@ -82,6 +84,14 @@ export class PrismaStore implements ChatStore {
|
|
|
82
84
|
await this.table("toolCall").create({ data: toolCall });
|
|
83
85
|
}
|
|
84
86
|
|
|
87
|
+
async listToolCalls(messageIds: string[]): Promise<StoredToolCall[]> {
|
|
88
|
+
if (messageIds.length === 0) return [];
|
|
89
|
+
return await this.table("toolCall").findMany({
|
|
90
|
+
where: { messageId: { in: messageIds } },
|
|
91
|
+
orderBy: { createdAt: "asc" }
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
|
|
85
95
|
async finishToolCall(
|
|
86
96
|
messageId: string,
|
|
87
97
|
toolCallId: string,
|
|
@@ -151,6 +161,14 @@ export class PrismaStore implements ChatStore {
|
|
|
151
161
|
}
|
|
152
162
|
|
|
153
163
|
/** A ChatStore as given, or a Prisma client wrapped in a PrismaStore. */
|
|
154
|
-
export function toStore(
|
|
155
|
-
|
|
164
|
+
export function toStore(
|
|
165
|
+
prismaOrStore: unknown,
|
|
166
|
+
tableNames?: TableNames,
|
|
167
|
+
redact?: StoreRedactor
|
|
168
|
+
): ChatStore {
|
|
169
|
+
const store = isChatStore(prismaOrStore)
|
|
170
|
+
? prismaOrStore
|
|
171
|
+
: new PrismaStore(prismaOrStore, tableNames);
|
|
172
|
+
// Keys and tokens are masked in everything saved, whatever the store.
|
|
173
|
+
return redactingStore(store, redact);
|
|
156
174
|
}
|
|
@@ -54,6 +54,9 @@ export { PrismaStore, toStore } from "./PrismaStore.js";
|
|
|
54
54
|
// AgentSession API
|
|
55
55
|
export { AgentSession, createAgentSession, loadAgentSession } from "./AgentSession.js";
|
|
56
56
|
export type {
|
|
57
|
+
AgentAnswer,
|
|
58
|
+
AgentData,
|
|
59
|
+
AgentSessionOverrides,
|
|
57
60
|
AgentSessionRecord,
|
|
58
61
|
CreateAgentSessionOptions,
|
|
59
62
|
LoadAgentSessionOptions,
|
package/src/errors.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { LLMError } from "@node-llm/core";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The store stopped a chat or agent session, before its next request, by answering
|
|
5
|
+
* `createRequest` with `{ stop }`: for example, when the account has reached a spending limit
|
|
6
|
+
* kept outside the app. Every tool call that ran has its result in the history.
|
|
7
|
+
*/
|
|
8
|
+
export class StoppedByStoreError extends LLMError {
|
|
9
|
+
constructor(
|
|
10
|
+
/** What the store gave as the reason */
|
|
11
|
+
public readonly reason: string
|
|
12
|
+
) {
|
|
13
|
+
super(reason, "STOPPED_BY_STORE");
|
|
14
|
+
}
|
|
15
|
+
}
|
package/src/history.ts
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import type { Message } from "@node-llm/core";
|
|
2
|
+
import type { StoredMessage, StoredToolCall } from "./Store.js";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The chat history to give an agent from what the store recorded. Each assistant message is
|
|
6
|
+
* preceded by the tool calls it made, with their results, so the model sees what it did. A call
|
|
7
|
+
* with no result, whose run stopped before it finished, is left out with its message's empty
|
|
8
|
+
* text, so the history stays valid and the run can be asked to continue.
|
|
9
|
+
*/
|
|
10
|
+
export function storedHistory(
|
|
11
|
+
messages: StoredMessage[],
|
|
12
|
+
toolCalls: StoredToolCall[] = []
|
|
13
|
+
): Message[] {
|
|
14
|
+
const callsByMessage = new Map<string, StoredToolCall[]>();
|
|
15
|
+
for (const call of toolCalls) {
|
|
16
|
+
if (call.result === null || call.result === undefined) continue;
|
|
17
|
+
callsByMessage.set(call.messageId, [...(callsByMessage.get(call.messageId) ?? []), call]);
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
const history: Message[] = [];
|
|
21
|
+
for (const message of messages) {
|
|
22
|
+
const role = message.role as Message["role"];
|
|
23
|
+
if (role !== "assistant") {
|
|
24
|
+
history.push({ role, content: message.content || "" });
|
|
25
|
+
continue;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
const calls = callsByMessage.get(message.id) ?? [];
|
|
29
|
+
if (calls.length > 0) {
|
|
30
|
+
history.push({
|
|
31
|
+
role: "assistant",
|
|
32
|
+
content: null,
|
|
33
|
+
tool_calls: calls.map((call) => ({
|
|
34
|
+
id: call.toolCallId,
|
|
35
|
+
type: "function" as const,
|
|
36
|
+
function: { name: call.name, arguments: call.arguments },
|
|
37
|
+
...(call.thoughtSignature ? { thought_signature: call.thoughtSignature } : {})
|
|
38
|
+
}))
|
|
39
|
+
});
|
|
40
|
+
for (const call of calls) {
|
|
41
|
+
history.push({ role: "tool", tool_call_id: call.toolCallId, content: call.result! });
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
// Providers reject an empty assistant message, such as one whose run never finished.
|
|
45
|
+
if (message.content) history.push({ role: "assistant", content: message.content });
|
|
46
|
+
}
|
|
47
|
+
return history;
|
|
48
|
+
}
|
package/src/index.ts
CHANGED
|
@@ -61,13 +61,17 @@ export * from "./adapters/prisma/index.js";
|
|
|
61
61
|
|
|
62
62
|
// Custom stores
|
|
63
63
|
export { isChatStore } from "./Store.js";
|
|
64
|
+
export { StoppedByStoreError } from "./errors.js";
|
|
65
|
+
export { maskSecrets, redactingStore, type StoreRedactor } from "./redact.js";
|
|
64
66
|
export type {
|
|
65
67
|
ChatStore,
|
|
66
68
|
StoredChat,
|
|
67
69
|
StoredMessage,
|
|
68
70
|
StoredAgentSession,
|
|
71
|
+
StoredToolCall,
|
|
69
72
|
NewChat,
|
|
70
73
|
NewToolCall,
|
|
74
|
+
RequestRecorded,
|
|
71
75
|
NewRequest,
|
|
72
76
|
MessageUpdate,
|
|
73
77
|
RequestTotals
|
package/src/redact.ts
ADDED
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
import type { ChatStore, MessageUpdate, NewToolCall } from "./Store.js";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Changes text before it is saved, such as to mask personal data. Runs after NodeLLM's own
|
|
5
|
+
* masking of keys and tokens.
|
|
6
|
+
*/
|
|
7
|
+
export type StoreRedactor = (text: string) => string;
|
|
8
|
+
|
|
9
|
+
// Kept the same as @node-llm/core's utils/redact.ts, which this package can't import while
|
|
10
|
+
// it supports older core versions.
|
|
11
|
+
/** Key and token formats, masked wherever they appear in text. */
|
|
12
|
+
const SECRET_VALUE = new RegExp(
|
|
13
|
+
"(?<![A-Za-z0-9])(?:" +
|
|
14
|
+
[
|
|
15
|
+
"sk-(?:ant-|proj-|or-v1-|svcacct-|admin-)?[A-Za-z0-9_-]{16,256}", // OpenAI, Anthropic, OpenRouter
|
|
16
|
+
"[sr]k_(?:live|test)_[A-Za-z0-9]{16,256}", // Stripe
|
|
17
|
+
"AIza[0-9A-Za-z_-]{30,64}", // Google
|
|
18
|
+
"xai-[A-Za-z0-9]{20,256}", // xAI
|
|
19
|
+
"(?:AKIA|ASIA)[0-9A-Z]{16}", // AWS access key IDs, long-lived and temporary
|
|
20
|
+
"gh[pousr]_[A-Za-z0-9]{30,255}", // GitHub tokens
|
|
21
|
+
"github_pat_[A-Za-z0-9_]{20,255}", // GitHub fine-grained tokens
|
|
22
|
+
"xox[abprs]-[A-Za-z0-9-]{10,255}", // Slack tokens
|
|
23
|
+
"eyJ[A-Za-z0-9_-]{8,4096}\\.eyJ[A-Za-z0-9_-]{8,8192}\\.[A-Za-z0-9_-]{8,4096}" // JWTs
|
|
24
|
+
].join("|") +
|
|
25
|
+
")",
|
|
26
|
+
"g"
|
|
27
|
+
);
|
|
28
|
+
|
|
29
|
+
/** The credential after `Bearer` or `Basic`, keeping the scheme so the text still reads. */
|
|
30
|
+
const AUTH_SCHEME = /(?<=\b(?:Bearer|Basic)\s{1,4})[A-Za-z0-9._~+/=-]{16,4096}/g;
|
|
31
|
+
|
|
32
|
+
/** A PEM private key, from its BEGIN line to its END line. */
|
|
33
|
+
const PRIVATE_KEY =
|
|
34
|
+
/-----BEGIN [A-Z0-9 ]{0,40}PRIVATE KEY-----[\s\S]{0,16384}?-----END [A-Z0-9 ]{0,40}PRIVATE KEY-----/g;
|
|
35
|
+
|
|
36
|
+
/** A secret written as `name = value` or `"name": "value"`, such as an AWS secret access key. */
|
|
37
|
+
const NAMED_SECRET =
|
|
38
|
+
/((?:aws_secret_access_key|aws_session_token|secret_access_key|secretAccessKey|sessionToken|client_secret|clientSecret|api_key|apiKey|password|passwd)["']?\s{0,4}[:=]\s{0,4}["']?)[^\s"',;&]{8,512}/gi;
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* The password in a URL such as postgres://user:password@host or redis://:password@host. The
|
|
42
|
+
* scheme must start the word, and no part may hold quotes or spaces, so it never spans JSON
|
|
43
|
+
* fields; the password runs to the last `@` before the host.
|
|
44
|
+
*/
|
|
45
|
+
const URL_PASSWORD =
|
|
46
|
+
/(?<![a-z0-9+.-])([a-z][a-z0-9+.-]{0,30}:\/\/[^\s:/@"'<>\\]{0,256}:)[^\s/"'<>\\]{1,256}@/gi;
|
|
47
|
+
|
|
48
|
+
/** Masks API keys, tokens, private keys and passwords in URLs, which a conversation should never keep. */
|
|
49
|
+
export function maskSecrets(text: string): string {
|
|
50
|
+
return text
|
|
51
|
+
.replace(PRIVATE_KEY, "[REDACTED PRIVATE KEY]")
|
|
52
|
+
.replace(SECRET_VALUE, "[REDACTED]")
|
|
53
|
+
.replace(AUTH_SCHEME, "[REDACTED]")
|
|
54
|
+
.replace(NAMED_SECRET, "$1[REDACTED]")
|
|
55
|
+
.replace(URL_PASSWORD, "$1[REDACTED]@");
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
const REDACTING = Symbol.for("nodellm.orm.redacting");
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* The redactor for a chat or session: `redact`, then the masking of any PIIMaskMiddleware among
|
|
62
|
+
* its middlewares, so what is saved is masked as what the model is sent.
|
|
63
|
+
*/
|
|
64
|
+
export function redactorFor(
|
|
65
|
+
redact: StoreRedactor | undefined,
|
|
66
|
+
middlewares: unknown[] | undefined
|
|
67
|
+
): StoreRedactor | undefined {
|
|
68
|
+
const masks = (middlewares ?? [])
|
|
69
|
+
.filter(
|
|
70
|
+
(middleware): middleware is { mask: (text: string) => string } =>
|
|
71
|
+
typeof middleware === "object" &&
|
|
72
|
+
middleware !== null &&
|
|
73
|
+
(middleware as { name?: unknown }).name === "PIIMask" &&
|
|
74
|
+
typeof (middleware as { mask?: unknown }).mask === "function"
|
|
75
|
+
)
|
|
76
|
+
.map((middleware) => (text: string) => middleware.mask(text));
|
|
77
|
+
const steps = [...(redact ? [redact] : []), ...masks];
|
|
78
|
+
if (steps.length === 0) return undefined;
|
|
79
|
+
return (text) => steps.reduce((current, step) => step(current), text);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** A copy of a value with every string in it cleaned. */
|
|
83
|
+
function cleanDeep<T>(value: T, clean: (text: string) => string, depth = 0): T {
|
|
84
|
+
if (typeof value === "string") return clean(value) as T;
|
|
85
|
+
if (depth > 30 || value === null || typeof value !== "object" || value instanceof Date)
|
|
86
|
+
return value;
|
|
87
|
+
if (Array.isArray(value)) return value.map((item) => cleanDeep(item, clean, depth + 1)) as T;
|
|
88
|
+
return Object.fromEntries(
|
|
89
|
+
Object.entries(value as Record<string, unknown>).map(([key, item]) => [
|
|
90
|
+
key,
|
|
91
|
+
cleanDeep(item, clean, depth + 1)
|
|
92
|
+
])
|
|
93
|
+
) as T;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* A store that masks keys and tokens, then applies `redact`, in everything it saves: message
|
|
98
|
+
* text, reasoning and thinking, tool arguments and results, a chat's instructions and metadata,
|
|
99
|
+
* and a session's inputs. Reads are passed through as they are.
|
|
100
|
+
*/
|
|
101
|
+
export function redactingStore(store: ChatStore, redact?: StoreRedactor): ChatStore {
|
|
102
|
+
if ((store as { [REDACTING]?: boolean })[REDACTING]) return store;
|
|
103
|
+
const clean = (text: string | null | undefined) =>
|
|
104
|
+
typeof text === "string" ? (redact ? redact(maskSecrets(text)) : maskSecrets(text)) : text;
|
|
105
|
+
|
|
106
|
+
const cleanText = (text: string) => (redact ? redact(maskSecrets(text)) : maskSecrets(text));
|
|
107
|
+
|
|
108
|
+
const wrapped: ChatStore = Object.create(store);
|
|
109
|
+
wrapped.createChat = (chat) =>
|
|
110
|
+
store.createChat({
|
|
111
|
+
...chat,
|
|
112
|
+
...(typeof chat.instructions === "string" ? { instructions: clean(chat.instructions) } : {}),
|
|
113
|
+
...(chat.metadata !== undefined ? { metadata: cleanDeep(chat.metadata, cleanText) } : {})
|
|
114
|
+
});
|
|
115
|
+
wrapped.createAgentSession = (session) =>
|
|
116
|
+
store.createAgentSession({
|
|
117
|
+
...session,
|
|
118
|
+
metadata: session.metadata ? cleanDeep(session.metadata, cleanText) : session.metadata
|
|
119
|
+
});
|
|
120
|
+
wrapped.updateAgentSession = (id, changes) =>
|
|
121
|
+
store.updateAgentSession(id, { ...changes, metadata: cleanDeep(changes.metadata, cleanText) });
|
|
122
|
+
wrapped.createMessage = (message) =>
|
|
123
|
+
store.createMessage({ ...message, content: clean(message.content) ?? null });
|
|
124
|
+
wrapped.updateMessage = (id, changes: MessageUpdate) =>
|
|
125
|
+
store.updateMessage(id, {
|
|
126
|
+
...changes,
|
|
127
|
+
...("content" in changes ? { content: clean(changes.content) ?? null } : {}),
|
|
128
|
+
...("contentRaw" in changes ? { contentRaw: clean(changes.contentRaw) ?? null } : {}),
|
|
129
|
+
...("thinkingText" in changes ? { thinkingText: clean(changes.thinkingText) ?? null } : {}),
|
|
130
|
+
...("reasoning" in changes ? { reasoning: clean(changes.reasoning) ?? null } : {})
|
|
131
|
+
});
|
|
132
|
+
wrapped.createToolCall = (toolCall: NewToolCall) =>
|
|
133
|
+
store.createToolCall({
|
|
134
|
+
...toolCall,
|
|
135
|
+
arguments: clean(toolCall.arguments) ?? "",
|
|
136
|
+
...("thought" in toolCall ? { thought: clean(toolCall.thought) ?? null } : {})
|
|
137
|
+
});
|
|
138
|
+
wrapped.finishToolCall = (messageId, toolCallId, finished) =>
|
|
139
|
+
store.finishToolCall(messageId, toolCallId, {
|
|
140
|
+
...finished,
|
|
141
|
+
result: clean(finished.result) ?? "",
|
|
142
|
+
...("thought" in finished ? { thought: clean(finished.thought) ?? null } : {})
|
|
143
|
+
});
|
|
144
|
+
// Methods the app's store has beyond ChatStore keep working through the prototype.
|
|
145
|
+
for (const name of Object.getOwnPropertyNames(Object.getPrototypeOf(store))) {
|
|
146
|
+
const value = (store as unknown as Record<string, unknown>)[name];
|
|
147
|
+
if (
|
|
148
|
+
name !== "constructor" &&
|
|
149
|
+
typeof value === "function" &&
|
|
150
|
+
!(name in wrapped && Object.hasOwn(wrapped, name))
|
|
151
|
+
) {
|
|
152
|
+
(wrapped as unknown as Record<string, unknown>)[name] = value.bind(store);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
Object.defineProperty(wrapped, REDACTING, { value: true });
|
|
156
|
+
return wrapped;
|
|
157
|
+
}
|