@node-llm/orm 0.10.0 → 0.11.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 (47) hide show
  1. package/CHANGELOG.md +130 -0
  2. package/dist/BaseChat.d.ts +2 -2
  3. package/dist/BaseChat.d.ts.map +1 -1
  4. package/dist/Store.d.ts +28 -1
  5. package/dist/Store.d.ts.map +1 -1
  6. package/dist/adapters/prisma/AgentSession.d.ts +42 -9
  7. package/dist/adapters/prisma/AgentSession.d.ts.map +1 -1
  8. package/dist/adapters/prisma/AgentSession.js +69 -17
  9. package/dist/adapters/prisma/Chat.d.ts +5 -0
  10. package/dist/adapters/prisma/Chat.d.ts.map +1 -1
  11. package/dist/adapters/prisma/Chat.js +14 -4
  12. package/dist/adapters/prisma/PrismaStore.d.ts +4 -2
  13. package/dist/adapters/prisma/PrismaStore.d.ts.map +1 -1
  14. package/dist/adapters/prisma/PrismaStore.js +15 -2
  15. package/dist/adapters/prisma/index.d.ts +1 -1
  16. package/dist/adapters/prisma/index.d.ts.map +1 -1
  17. package/dist/errors.d.ts +14 -0
  18. package/dist/errors.d.ts.map +1 -0
  19. package/dist/errors.js +15 -0
  20. package/dist/history.d.ts +10 -0
  21. package/dist/history.d.ts.map +1 -0
  22. package/dist/history.js +42 -0
  23. package/dist/index.d.ts +3 -1
  24. package/dist/index.d.ts.map +1 -1
  25. package/dist/index.js +2 -0
  26. package/dist/redact.d.ts +20 -0
  27. package/dist/redact.d.ts.map +1 -0
  28. package/dist/redact.js +118 -0
  29. package/package.json +2 -2
  30. package/src/BaseChat.ts +2 -2
  31. package/src/Store.ts +30 -1
  32. package/src/adapters/prisma/AgentSession.ts +130 -26
  33. package/src/adapters/prisma/Chat.ts +23 -5
  34. package/src/adapters/prisma/PrismaStore.ts +21 -3
  35. package/src/adapters/prisma/index.ts +3 -0
  36. package/src/errors.ts +15 -0
  37. package/src/history.ts +48 -0
  38. package/src/index.ts +4 -0
  39. package/src/redact.ts +157 -0
  40. package/test/AgentSession.test.ts +12 -2
  41. package/test/CountCall.test.ts +147 -0
  42. package/test/Redact.test.ts +228 -0
  43. package/test/Resume.test.ts +232 -0
  44. package/test/SessionData.test.ts +109 -0
  45. package/test/SessionOverrides.test.ts +130 -0
  46. package/test/StoreStops.test.ts +163 -0
  47. 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
 
@@ -180,7 +205,8 @@ export class AgentSession<
180
205
  messageId: this.currentMessageId,
181
206
  toolCallId: toolCall.id,
182
207
  name: toolCall.function.name,
183
- arguments: toolCall.function.arguments
208
+ arguments: toolCall.function.arguments,
209
+ thoughtSignature: toolCall.thought_signature ?? null
184
210
  });
185
211
  });
186
212
 
@@ -196,8 +222,12 @@ export class AgentSession<
196
222
  }
197
223
  });
198
224
 
225
+ this.agent.beforeRequest(async () => {
226
+ if (this.stopReason !== undefined) throw new StoppedByStoreError(this.stopReason);
227
+ });
228
+
199
229
  this.agent.afterResponse(async (response) => {
200
- await this.store.createRequest({
230
+ const recorded = await this.store.createRequest({
201
231
  chatId: this.chatId,
202
232
  messageId: this.currentMessageId,
203
233
  provider: response.provider || "unknown",
@@ -209,13 +239,42 @@ export class AgentSession<
209
239
  cachedTokens: response.usage?.cached_tokens,
210
240
  cost: response.usage?.cost || 0
211
241
  });
242
+ if (recorded && recorded.stop !== undefined) this.stopReason = recorded.stop;
243
+ });
244
+ }
245
+
246
+ /**
247
+ * Records a call made outside the agent's own requests, such as a tool asking another model
248
+ * about an image: as a request row of this chat, under the answer being written now, and in the
249
+ * agent's usage, so `stats()`, `totalUsage` and the ask's `maxCost` all include it.
250
+ */
251
+ async countCall(response: {
252
+ usage?: Usage;
253
+ model?: string;
254
+ provider?: string;
255
+ latency?: number;
256
+ }): Promise<void> {
257
+ const usage = response.usage;
258
+ if (!usage) return;
259
+ this.agent.countUsage(usage);
260
+ await this.store.createRequest({
261
+ chatId: this.chatId,
262
+ messageId: this.currentMessageId,
263
+ provider: response.provider || "unknown",
264
+ model: response.model || "unknown",
265
+ statusCode: 200,
266
+ duration: response.latency || 0,
267
+ inputTokens: usage.input_tokens || 0,
268
+ outputTokens: usage.output_tokens || 0,
269
+ cachedTokens: usage.cached_tokens,
270
+ cost: usage.cost || 0
212
271
  });
213
272
  }
214
273
 
215
274
  /**
216
275
  * Send a message and persist the conversation.
217
276
  */
218
- async ask(message: string, options: AskOptions & { inputs?: I } = {}): Promise<MessageRecord> {
277
+ async ask(message: string, options: AskOptions & { inputs?: I } = {}): Promise<AgentAnswer<T>> {
219
278
  // Persist user message
220
279
  await this.store.createMessage({ chatId: this.chatId, role: "user", content: message });
221
280
 
@@ -236,7 +295,7 @@ export class AgentSession<
236
295
  const response = await this.agent.ask(message, { ...options, inputs });
237
296
 
238
297
  // Update assistant message with response
239
- return (await this.store.updateMessage(assistantMessage.id, {
298
+ const saved = (await this.store.updateMessage(assistantMessage.id, {
240
299
  content: response.content,
241
300
  contentRaw: JSON.stringify(response.meta),
242
301
  inputTokens: response.usage?.input_tokens || 0,
@@ -247,6 +306,7 @@ export class AgentSession<
247
306
  modelId: response.model || null,
248
307
  provider: response.provider || null
249
308
  })) as MessageRecord;
309
+ return withData<T>(saved, response);
250
310
  } catch (error) {
251
311
  // Clean up placeholder on error
252
312
  await this.store.deleteMessage(assistantMessage.id);
@@ -366,19 +426,50 @@ export class AgentSession<
366
426
  }
367
427
  }
368
428
 
429
+ /**
430
+ * Agent settings for one session, in place of the agent class's own, such as `maxCost` or
431
+ * `maxToolCalls` for a run with its own budget. Not kept in the store: pass them again to
432
+ * loadAgentSession().
433
+ */
434
+ export type AgentSessionOverrides<I = any> = Omit<
435
+ Partial<AgentConfig<I>>,
436
+ "llm" | "inputs" | "tools" | "schema"
437
+ > & {
438
+ /** Tools for this session, in place of the ones the agent class defines */
439
+ tools?: ChatOptions["tools"];
440
+ };
441
+
369
442
  /**
370
443
  * Options for creating a new agent session.
371
444
  */
372
- export interface CreateAgentSessionOptions<I = any> {
445
+ export interface CreateAgentSessionOptions<I = any> extends AgentSessionOverrides<I> {
373
446
  metadata?: I;
374
447
  tableNames?: TableNames;
448
+ /** Changes text before it is saved, after keys and tokens are masked; see StoreRedactor. */
449
+ redact?: StoreRedactor;
375
450
  debug?: boolean;
376
- model?: string;
377
- provider?: string;
378
451
  instructions?: string;
379
- maxToolCalls?: number;
380
- /** Tools for this session, in place of the ones the agent class defines */
381
- tools?: ChatOptions["tools"];
452
+ }
453
+
454
+ /** The agent settings in session options, leaving out the session's own options. */
455
+ function agentOverrides<I>(
456
+ options: AgentSessionOverrides<I> & {
457
+ metadata?: unknown;
458
+ tableNames?: unknown;
459
+ debug?: unknown;
460
+ redact?: unknown;
461
+ }
462
+ ): AgentSessionOverrides<I> {
463
+ const {
464
+ metadata: _metadata,
465
+ tableNames: _tableNames,
466
+ debug: _debug,
467
+ redact: _redact,
468
+ ...overrides
469
+ } = options;
470
+ return Object.fromEntries(
471
+ Object.entries(overrides).filter(([, value]) => value !== undefined)
472
+ ) as AgentSessionOverrides<I>;
382
473
  }
383
474
 
384
475
  /**
@@ -390,7 +481,14 @@ export async function createAgentSession<I extends Record<string, any>, T extend
390
481
  AgentClass: AgentClass<T>,
391
482
  options: CreateAgentSessionOptions<I> = {}
392
483
  ): Promise<AgentSession<I, T>> {
393
- const store = toStore(prismaOrStore, options.tableNames);
484
+ const store = toStore(
485
+ prismaOrStore,
486
+ options.tableNames,
487
+ redactorFor(options.redact, [
488
+ ...((AgentClass as { middlewares?: unknown[] }).middlewares ?? []),
489
+ ...(options.middlewares ?? [])
490
+ ])
491
+ );
394
492
 
395
493
  if (options.debug) {
396
494
  console.log(`[@node-llm/orm] createAgentSession: agentClass=${AgentClass.name}`);
@@ -415,13 +513,9 @@ export async function createAgentSession<I extends Record<string, any>, T extend
415
513
 
416
514
  // 3. Instantiate Agent with overrides
417
515
  const agent = new AgentClass({
516
+ ...agentOverrides<I>(options),
418
517
  llm,
419
- inputs: sessionRecord.metadata as I,
420
- model: options.model,
421
- provider: options.provider,
422
- instructions: options.instructions,
423
- maxToolCalls: options.maxToolCalls,
424
- ...(options.tools ? { tools: options.tools } : {})
518
+ inputs: sessionRecord.metadata as I
425
519
  });
426
520
 
427
521
  return new AgentSession<I, T>(
@@ -438,8 +532,10 @@ export async function createAgentSession<I extends Record<string, any>, T extend
438
532
  /**
439
533
  * Options for loading an existing agent session.
440
534
  */
441
- export interface LoadAgentSessionOptions {
535
+ export interface LoadAgentSessionOptions<I = any> extends AgentSessionOverrides<I> {
442
536
  tableNames?: TableNames;
537
+ /** Changes text before it is saved, after keys and tokens are masked; see StoreRedactor. */
538
+ redact?: StoreRedactor;
443
539
  debug?: boolean;
444
540
  }
445
541
 
@@ -451,9 +547,16 @@ export async function loadAgentSession<I extends Record<string, any>, T extends
451
547
  llm: NodeLLMCore,
452
548
  AgentClass: AgentClass<T>,
453
549
  sessionId: string,
454
- options: LoadAgentSessionOptions = {}
550
+ options: LoadAgentSessionOptions<I> = {}
455
551
  ): Promise<AgentSession<I, T> | null> {
456
- const store = toStore(prismaOrStore, options.tableNames);
552
+ const store = toStore(
553
+ prismaOrStore,
554
+ options.tableNames,
555
+ redactorFor(options.redact, [
556
+ ...((AgentClass as { middlewares?: unknown[] }).middlewares ?? []),
557
+ ...(options.middlewares ?? [])
558
+ ])
559
+ );
457
560
 
458
561
  if (options.debug) {
459
562
  console.log(`[@node-llm/orm] loadAgentSession: id=${sessionId}`);
@@ -473,19 +576,20 @@ export async function loadAgentSession<I extends Record<string, any>, T extends
473
576
  );
474
577
  }
475
578
 
476
- // 2. Load message history
579
+ // 2. Load message history, with the tool calls of earlier turns when the store keeps them
477
580
  const messages = (await store.listMessages(sessionRecord.chatId)) as MessageRecord[];
581
+ const toolCalls = store.listToolCalls
582
+ ? await store.listToolCalls(messages.map((message) => message.id))
583
+ : [];
478
584
 
479
- // 3. Convert DB messages to NodeLLM Message format
480
- const history: Message[] = messages.map((m) => ({
481
- role: m.role as "user" | "assistant" | "system",
482
- content: m.content || ""
483
- }));
585
+ // 3. Convert DB records to NodeLLM messages
586
+ const history: Message[] = storedHistory(messages, toolCalls);
484
587
 
485
588
  // 4. Instantiate agent with injected history, LLM, AND metadata (as inputs)
486
589
  // "Code Wins" - model, tools, instructions come from AgentClass
487
590
  // Metadata from DB handles the lazy resolution of behavior
488
591
  const agent = new AgentClass({
592
+ ...agentOverrides<I>(options),
489
593
  llm,
490
594
  messages: history,
491
595
  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,10 @@ 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
+
120
128
  coreChat.afterResponse(async (finalResp: any) => {
121
129
  this.log(
122
130
  `Internal afterResponse triggered. Calling ${this.userHooks.afterResponse.length} user hooks.`
@@ -130,7 +138,7 @@ export class Chat extends BaseChat {
130
138
 
131
139
  // Only persist if requests persistence is enabled
132
140
  if (this.persistenceConfig.requests) {
133
- await this.store.createRequest({
141
+ const recorded = await this.store.createRequest({
134
142
  chatId: this.id,
135
143
  messageId: assistantMessageId,
136
144
  provider: finalResp.provider || provider || "unknown",
@@ -142,6 +150,7 @@ export class Chat extends BaseChat {
142
150
  cachedTokens: finalResp.usage?.cached_tokens,
143
151
  cost: finalResp.usage?.cost || 0
144
152
  });
153
+ if (recorded && recorded.stop !== undefined) this.stopReason = recorded.stop;
145
154
  }
146
155
 
147
156
  return finalResp;
@@ -349,7 +358,7 @@ export class Chat extends BaseChat {
349
358
  export async function createChat<T = Record<string, any>>(
350
359
  prismaOrStore: unknown,
351
360
  llm: NodeLLMCore,
352
- options: ChatOptions & { tableNames?: TableNames } & T = {} as any
361
+ options: ChatOptions & { tableNames?: TableNames; redact?: StoreRedactor } & T = {} as any
353
362
  ): Promise<Chat> {
354
363
  const {
355
364
  model,
@@ -367,10 +376,15 @@ export async function createChat<T = Record<string, any>>(
367
376
  headers: _headers,
368
377
  requestTimeout: _requestTimeout,
369
378
  params: _params,
379
+ redact: _redact,
370
380
  ...extras
371
381
  } = options;
372
382
 
373
- const store = toStore(prismaOrStore, options.tableNames);
383
+ const store = toStore(
384
+ prismaOrStore,
385
+ options.tableNames,
386
+ redactorFor(options.redact, options.middlewares)
387
+ );
374
388
  if (options.debug) console.log(`[@node-llm/orm] createChat: store=${store.constructor.name}`);
375
389
 
376
390
  const record = await store.createChat({
@@ -391,9 +405,13 @@ export async function loadChat(
391
405
  prismaOrStore: unknown,
392
406
  llm: NodeLLMCore,
393
407
  chatId: string,
394
- options: ChatOptions & { tableNames?: TableNames; debug?: boolean } = {}
408
+ options: ChatOptions & { tableNames?: TableNames; debug?: boolean; redact?: StoreRedactor } = {}
395
409
  ): Promise<Chat | null> {
396
- const store = toStore(prismaOrStore, options.tableNames);
410
+ const store = toStore(
411
+ prismaOrStore,
412
+ options.tableNames,
413
+ redactorFor(options.redact, options.middlewares)
414
+ );
397
415
  if (options.debug) console.log(`[@node-llm/orm] loadChat: store=${store.constructor.name}`);
398
416
 
399
417
  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(prismaOrStore: unknown, tableNames?: TableNames): ChatStore {
155
- return isChatStore(prismaOrStore) ? prismaOrStore : new PrismaStore(prismaOrStore, tableNames);
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
+ }
@@ -20,6 +20,11 @@ const mockPrisma = {
20
20
  findMany: vi.fn(),
21
21
  update: vi.fn(),
22
22
  delete: vi.fn()
23
+ },
24
+ llmToolCall: {
25
+ create: vi.fn(),
26
+ update: vi.fn(),
27
+ findMany: vi.fn().mockResolvedValue([])
23
28
  }
24
29
  };
25
30
 
@@ -123,12 +128,17 @@ describe("AgentSession", () => {
123
128
  });
124
129
 
125
130
  mockPrisma.llmMessage.findMany.mockResolvedValue([
126
- { role: "user", content: "Hello" },
127
- { role: "assistant", content: "Hi there" }
131
+ { id: "m1", role: "user", content: "Hello" },
132
+ { id: "m2", role: "assistant", content: "Hi there" }
128
133
  ]);
129
134
 
130
135
  const session = await loadAgentSession(mockPrisma as any, mockLlm, TestAgent, "session-123");
131
136
 
137
+ expect(mockPrisma.llmToolCall.findMany).toHaveBeenCalledWith({
138
+ where: { messageId: { in: ["m1", "m2"] } },
139
+ orderBy: { createdAt: "asc" }
140
+ });
141
+
132
142
  expect(session).not.toBeNull();
133
143
  expect(session?.id).toBe("session-123");
134
144