@node-llm/orm 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.11.0] - 2026-02-07 (@node-llm/core)
+
+### Features
+
+- **Agent Class**: Declarative DSL for defining agents with static properties (model, instructions, tools, temperature, thinking, schema).
+- **ToolHalt Mechanism**: Early termination of agentic loops via `this.halt(result)` in Tool.execute().
+- **defineAgent()**: Inline agent definition without creating a class.
+- **Agent Inheritance**: Child agents inherit parent static properties.
+- **Instance Overrides**: Override static properties at instantiation (temperature, maxTokens, etc.).
+
+### Documentation
+
+- Comprehensive Agent documentation with examples for RAG, model routing, and multi-agent patterns.
+- Added doc tests for Agent, Tool, and ToolHalt patterns.
+
+## [0.5.0] - 2026-02-07 (@node-llm/orm)
+
+### Features
+
+- **AgentSession**: Persistent agent conversations following "Code Wins" principle.
+  - `createAgentSession()`: Create new session with metadata.
+  - `loadAgentSession()`: Resume session by ID with class validation.
+  - Agent class defines behavior (model, tools, instructions), database provides history.
+- **Idempotent Migrations**: Safe migration files for LlmAgentSession table.
+- **Custom Table Names**: Support for custom table name mapping.
+
+## [0.5.0] - 2026-02-07 (@node-llm/testing)
+
+### Features
+
+- **Agent Testing Support**:
+  - `mocker.callsTools()`: Mock responses that trigger multiple tool calls.
+  - `mocker.sequence()`: Return different responses for multi-turn agent conversations.
+  - `mocker.times(n)`: Limit mock matches with fallthrough behavior.
+- **Improved Matching**: First-match semantics enable `times()` fallthrough patterns.
+
+## [1.10.0] - 2026-02-01 (@node-llm/core)
+
+### Features
+
+- **Middleware Architecture**: Standardized interception layer for LLM requests and responses.
+- **Global & Local Interceptors**: Support for global middlewares via `createLLM` and local overrides in `chat()`.
+- **Standard Middleware Library**:
+  - `PIIMaskMiddleware`: Automated sensitive data masking.
+  - `CostGuardMiddleware`: Budget enforcement and cost monitoring.
+  - `UsageLoggerMiddleware`: Unified telemetry for token usage.
+- **Architectural Refinement**: Enhanced the `NodeLLM` instance with lazy-initialization and internal immutability for better configuration safety in concurrent environments.
+- **Enhanced Hooks**: New `onError` hook for robust error orchestration across the pipeline.
+
+### Improvements
+
+- **Streaming Stability**: Fixed critical state-sharing bug in multi-turn tool loops during streaming.
+- **Lazy Initialization**: Better support for `dotenv` and other environment loaders in ESM.
+
+## [0.4.0] - 2026-02-01 (@node-llm/orm)
+
+### Features
+
+- **Middleware Support**: Native support for LLM middlewares in `BaseChat` and `Chat` adapters.
+- **Persistence Strictness**: Automatically strips NodeLLM runtime options (middlewares, temperature, thinking, etc.) before persisting chat records to the database.
+- **Improved Table Lookup**: Robust Prisma table detection with case-insensitive matching and improved error messaging.
+
+## [0.4.0] - 2026-02-01 (@node-llm/testing)
+
+### Features
+
+- **Middleware Support**: Added comprehensive middleware orchestration in `Mocker`, allowing testing of middleware logic with mocked LLM calls.
+- **History Tracking**: Refined internal call history tracking with improved metadata capture.
+
 ## [0.3.0] - 2026-01-27 (@node-llm/orm)
 
 ### Features
@@ -76,7 +145,7 @@ All notable changes to this project will be documented in this file.
   - Shifted from `db push` to professional **Prisma Migrate** workflow for safe, versioned schema updates.
   - Added repository-wide `prisma/migrations` folder for reproducible deployments.
   - New built-in scripts: `npm run db:migrate`, `npm run db:deploy`, and `npm run db:status`.
-  - Comprehensive [Database Migration Guide](https://node-llm.eshaiju.com/orm/migrations) for application scaling.
+  - Comprehensive [Database Migration Guide](https://nodellm.dev/orm/migrations) for application scaling.
 
 ## [1.6.2] - 2026-01-21 (@node-llm/core)
 
@@ -178,7 +247,7 @@ All notable changes to this project will be documented in this file.
   - `onToolCallStart`: Triggered when a tool call begins
   - `onToolCallEnd`: Triggered when a tool call completes successfully
   - `onToolCallError`: Triggered when a tool call fails
-- **Security Documentation**: New comprehensive [Security & Compliance](https://node-llm.eshaiju.com/advanced/security.html) guide covering:
+- **Security Documentation**: New comprehensive [Security & Compliance](https://nodellm.dev/advanced/security.html) guide covering:
   - Smart Context Isolation
   - Content Policy Hooks
   - Tool Execution Policies

package/README.md

@@ -7,7 +7,7 @@
 
 > Database persistence layer for NodeLLM. Automatically tracks chats, messages, tool calls, and API requests.
 
-**[Read the Full Documentation](https://node-llm.eshaiju.com/orm/prisma)** | **[View Example App](https://github.com/node-llm/node-llm/tree/main/examples/applications/hr-chatbot-rag)**
+**[Read the Full Documentation](https://nodellm.dev/orm/prisma)** | **[View Example App](https://github.com/node-llm/node-llm/tree/main/examples/applications/hr-chatbot-rag)**
 
 ## Features
 
@@ -123,14 +123,15 @@ console.log(messages); // [{ role: 'user', content: '...' }, { role: 'assistant'
 
 ## Architecture
 
-The ORM tracks four core entities:
+The ORM tracks five core entities:
 
-| Model           | Purpose              | Example                                    |
-| --------------- | -------------------- | ------------------------------------------ |
-| **LlmChat**     | Session container    | Holds model, provider, system instructions |
-| **LlmMessage**  | Conversation history | User queries and assistant responses       |
-| **LlmToolCall** | Tool executions      | Function calls made by the assistant       |
-| **LlmRequest**  | API metrics          | Token usage, latency, cost per API call    |
+| Model               | Purpose              | Example                                    |
+| ------------------- | -------------------- | ------------------------------------------ |
+| **LlmAgentSession** | Agent persistence    | Links Agent class to Chat (v0.5.0+)        |
+| **LlmChat**         | Session container    | Holds model, provider, system instructions |
+| **LlmMessage**      | Conversation history | User queries and assistant responses       |
+| **LlmToolCall**     | Tool executions      | Function calls made by the assistant       |
+| **LlmRequest**      | API metrics          | Token usage, latency, cost per API call    |
 
 ### Data Flow
 
@@ -152,6 +153,91 @@ Chat.ask()
 Return Response
 ```
 
+## Agent Sessions (v0.5.0+)
+
+For **stateful agents** with persistence, use `AgentSession`. This follows the "Code Wins" principle:
+
+- **Model, Tools, Instructions** → from Agent class (code)
+- **Message History** → from database
+
+### Define an Agent (in @node-llm/core)
+
+```typescript
+import { Agent, Tool, z } from "@node-llm/core";
+
+class LookupOrderTool extends Tool {
+  static definition = {
+    name: "lookup_order",
+    description: "Look up order status",
+    parameters: z.object({ orderId: z.string() })
+  };
+  async execute({ orderId }) {
+    return { status: "shipped", eta: "Tomorrow" };
+  }
+}
+
+class SupportAgent extends Agent {
+  static model = "gpt-4.1";
+  static instructions = "You are a helpful support agent.";
+  static tools = [LookupOrderTool];
+}
+```
+
+### Create & Resume Sessions
+
+```typescript
+import { createAgentSession, loadAgentSession } from "@node-llm/orm/prisma";
+
+// Create a new persistent session
+const session = await createAgentSession(prisma, llm, SupportAgent, {
+  metadata: { userId: "user_123", ticketId: "TKT-456" }
+});
+
+await session.ask("Where is my order #789?");
+console.log(session.id); // "sess_abc123" - save this!
+
+// Resume later (even after code upgrades)
+const session = await loadAgentSession(prisma, llm, SupportAgent, "sess_abc123");
+await session.ask("Can you cancel it?");
+```
+
+### Code Wins Principle
+
+When you deploy a code change (new model, updated tools), resumed sessions use the **new configuration**:
+
+| Aspect       | Source      | Why                             |
+| ------------ | ----------- | ------------------------------- |
+| Model        | Agent class | Immediate upgrades              |
+| Tools        | Agent class | Only code can execute functions |
+| Instructions | Agent class | Deploy prompt fixes immediately |
+| History      | Database    | Sacred, never modified          |
+
+### Schema Addition
+
+Add `LlmAgentSession` to your Prisma schema:
+
+```prisma
+model LlmAgentSession {
+  id         String   @id @default(uuid())
+  agentClass String   // For validation (e.g., 'SupportAgent')
+  chatId     String   @unique
+  metadata   Json?    // Session context (userId, ticketId)
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+
+  chat       LlmChat  @relation(fields: [chatId], references: [id], onDelete: Cascade)
+
+  @@index([agentClass])
+  @@index([createdAt])
+}
+
+// Add relation to LlmChat
+model LlmChat {
+  // ... existing fields
+  agentSession LlmAgentSession?
+}
+```
+
 ## Advanced Usage
 
 ### Streaming Responses

package/bin/cli.js

@@ -63,21 +63,55 @@ function sync() {
     "thoughtSignature"
   ];
 
+  // Check for AgentSession model (v0.5.0+)
+  const hasAgentSession =
+    userSchema.includes("LlmAgentSession") || userSchema.includes("AgentSession");
+
   const missingFields = requiredFields.filter((field) => !userSchema.includes(field));
 
-  if (missingFields.length === 0) {
-    console.log("✓ Schema is already up to date with @node-llm/orm v0.2.0 features.");
+  if (missingFields.length === 0 && hasAgentSession) {
+    console.log("✓ Schema is already up to date with @node-llm/orm v0.5.0 features.");
     return;
   }
 
-  console.log("🛠  Syncing missing fields for Extended Thinking support...");
-  console.log(`\nDetected missing fields: ${missingFields.join(", ")}`);
+  if (missingFields.length > 0) {
+    console.log("🛠  Syncing missing fields for Extended Thinking support...");
+    console.log(`\nDetected missing fields: ${missingFields.join(", ")}`);
+  }
+
+  if (!hasAgentSession) {
+    console.log("\n🤖 Missing AgentSession support (v0.5.0+)");
+    console.log(
+      "   AgentSession enables persistent agent conversations with the 'Code Wins' pattern."
+    );
+    console.log("\n   To add AgentSession, copy the migration from:");
+    console.log("   node_modules/@node-llm/orm/migrations/add_agent_session.sql");
+    console.log("\n   Or add this to your schema.prisma:");
+    console.log(`
+model LlmAgentSession {
+  id         String   @id @default(uuid())
+  agentClass String
+  chatId     String   @unique
+  metadata   Json?
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+
+  chat       LlmChat  @relation(fields: [chatId], references: [id], onDelete: Cascade)
+
+  @@index([agentClass])
+  @@index([createdAt])
+}
+
+// Also add to LlmChat:
+// agentSession LlmAgentSession?
+`);
+  }
 
   console.log("\nTo update your schema safely, follow the Reference Schema at:");
   console.log("https://github.com/node-llm/node-llm/blob/main/packages/orm/schema.prisma");
 
   console.log("\nOr run this to generate a versioned migration:");
-  console.log("  npx prisma migrate dev --name add_reasoning_support");
+  console.log("  npx prisma migrate dev --name add_agent_session");
 }
 
 function main() {
@@ -103,7 +137,7 @@ function main() {
       console.log("  npx @node-llm/orm sync     # Check for missing ORM fields");
       console.log("  npx @node-llm/orm migrate  # Rails-style migration helper");
       console.log("\nFor enterprise patterns, see:");
-      console.log("  https://node-llm.eshaiju.com/orm/migrations");
+      console.log("  https://nodellm.dev/orm/migrations");
   }
 }
 

package/dist/BaseChat.d.ts

@@ -1,4 +1,4 @@
-import type { Usage } from "@node-llm/core";
+import type { Usage, Middleware } from "@node-llm/core";
 export interface ChatRecord {
     id: string;
     model?: string | null;
@@ -28,6 +28,7 @@ export interface ChatOptions {
     maxToolCalls?: number;
     requestTimeout?: number;
     params?: Record<string, any>;
+    middlewares?: Middleware[];
 }
 export interface UserHooks {
     onToolCallStart: ((call: any) => void | Promise<void>)[];
@@ -46,6 +47,7 @@ export declare abstract class BaseChat<R extends ChatRecord = ChatRecord, O exte
     id: string;
     protected localOptions: any;
     protected customTools: any[];
+    protected customMiddlewares: Middleware[];
     protected userHooks: UserHooks;
     constructor(record: R, options?: O);
     protected log(...args: any[]): void;

package/dist/BaseChat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseChat.d.ts","sourceRoot":"","sources":["../src/BaseChat.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BaseChat.d.ts","sourceRoot":"","sources":["../src/BaseChat.ts"],"names":[],"mappings":"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"}

package/dist/BaseChat.js

@@ -7,6 +7,7 @@ export class BaseChat {
     id;
     localOptions = {};
     customTools = [];
+    customMiddlewares = [];
     userHooks = {
         onToolCallStart: [],
         onToolCallEnd: [],
@@ -30,6 +31,10 @@ export class BaseChat {
         this.localOptions.maxToolCalls = options.maxToolCalls;
         this.localOptions.requestTimeout = options.requestTimeout;
         this.localOptions.params = options.params;
+        // Initialize middlewares
+        if (options.middlewares) {
+            this.customMiddlewares = options.middlewares;
+        }
     }
     log(...args) {
         if (this.options?.debug) {

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

@@ -0,0 +1,140 @@
+import { ChatOptions, AskOptions, NodeLLMCore, Agent, AgentConfig, Message, ChatChunk, Usage } from "@node-llm/core";
+/**
+ * Record structure for the LLM Agent Session table.
+ */
+export interface AgentSessionRecord {
+    id: string;
+    agentClass: string;
+    chatId: string;
+    metadata?: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Record structure for the LLM Message table.
+ */
+export interface MessageRecord {
+    id: string;
+    chatId: string;
+    role: string;
+    content: string | null;
+    contentRaw?: string | null;
+    thinkingText?: string | null;
+    thinkingSignature?: string | null;
+    thinkingTokens?: number | null;
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+    modelId?: string | null;
+    provider?: string | null;
+    createdAt: Date;
+}
+/**
+ * Table name customization.
+ */
+export interface TableNames {
+    agentSession?: string;
+    chat?: string;
+    message?: string;
+    toolCall?: string;
+    request?: string;
+}
+type AgentClass<T extends Agent = Agent> = (new (overrides?: Partial<AgentConfig & ChatOptions>) => T) & {
+    name: string;
+    model?: string;
+    instructions?: string;
+    tools?: unknown[];
+};
+/**
+ * AgentSession - Wraps an Agent instance with persistence capabilities.
+ *
+ * Follows "Code Wins" sovereignty:
+ * - Model, Tools, Instructions come from the Agent class (code)
+ * - Message history comes from the database
+ *
+ * @example
+ * ```typescript
+ * // Create a new session
+ * const session = await createAgentSession(prisma, llm, SupportAgent, {
+ *   metadata: { userId: "123" }
+ * });
+ *
+ * // Resume a session
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, "sess_abc");
+ *
+ * // Agent behavior is always defined in code
+ * const result = await session.ask("Hello");
+ * ```
+ */
+export declare class AgentSession<T extends Agent = Agent> {
+    private prisma;
+    private llm;
+    private AgentClass;
+    private record;
+    private agent;
+    private currentMessageId;
+    private tableNames;
+    private debug;
+    constructor(prisma: any, llm: NodeLLMCore, AgentClass: AgentClass<T>, record: AgentSessionRecord, tableNames?: TableNames, agent?: T, debug?: boolean);
+    private log;
+    /** Agent instance (for direct access if needed) */
+    get instance(): T;
+    /** Session ID for persistence */
+    get id(): string;
+    /** Underlying chat ID */
+    get chatId(): string;
+    /** Session metadata */
+    get metadata(): Record<string, unknown> | null | undefined;
+    /** Agent class name */
+    get agentClass(): string;
+    /** Model ID used by the agent */
+    get modelId(): string;
+    /** Cumulative usage for this session (from agent memory) */
+    get totalUsage(): Usage;
+    /** Current in-memory message history */
+    get history(): readonly Message[];
+    /**
+     * Helper to get a typed Prisma model by its dynamic name.
+     */
+    private getModel;
+    /**
+     * Send a message and persist the conversation.
+     */
+    ask(input: string, options?: AskOptions): Promise<MessageRecord>;
+    /**
+     * Stream a response and persist the conversation.
+     */
+    askStream(input: string, options?: AskOptions): AsyncGenerator<ChatChunk, MessageRecord, undefined>;
+    /**
+     * Returns the current full message history for this session.
+     */
+    messages(): Promise<MessageRecord[]>;
+    /**
+     * Delete the entire session and its history.
+     */
+    delete(): Promise<void>;
+}
+/**
+ * Options for creating a new agent session.
+ */
+export interface CreateAgentSessionOptions {
+    metadata?: Record<string, unknown>;
+    tableNames?: TableNames;
+    debug?: boolean;
+}
+/**
+ * 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>>;
+/**
+ * Options for loading an existing agent session.
+ */
+export interface LoadAgentSessionOptions {
+    tableNames?: TableNames;
+    debug?: boolean;
+}
+/**
+ * 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 {};
+//# sourceMappingURL=AgentSession.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSession.d.ts","sourceRoot":"","sources":["../../../src/adapters/prisma/AgentSession.ts"],"names":[],"mappings":"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"}