@dudousxd/nestjs-agent-store-drizzle 0.8.1 → 0.9.0

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import * as drizzle_orm_sqlite_core from 'drizzle-orm/sqlite-core';
 import { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
-import { MessageRole, ToolCallRequest, ToolResult, MessageUsage, ToolKind, ToolCallStatus, UsagePurpose, AgentStore, CreateThreadInput, ThreadSummary, ThreadDetail, AppendMessageInput, StoredMessage, RecordToolCallInput, UpdateToolCallInput, RecordUsageInput, AgentGovernanceQueries, AgentPricingStore, GovernanceRange, ModelSpendRow, ActorSpendRow, ThreadSpendRow, UsageTrendPoint, ToolCallActivityRow, ThreadActivityRow, RunMetrics, RunAgentBreakdownRow, RunErrorBreakdownRow, RunTrendPoint, RecentRunRow, PendingApprovalRow, ToolStatRow, GovernancePageQuery, ToolCallWhere, GovernancePage, ThreadWhere, RunWhere, ApprovalWhere, GovernanceRunDetail, GovernanceThreadDetailQuery, GovernanceThreadDetail, ModelPriceInput, CurrentModelPrice } from '@dudousxd/nestjs-agent-core';
+import { MessageRole, ToolCallRequest, ToolResult, MessageAttachment, MessageUsage, ToolKind, ToolCallStatus, UsagePurpose, AgentStore, ThreadTurnReader, CreateThreadInput, ThreadSummary, ThreadDetail, ThreadTurnQuery, ThreadTurnPage, UpdateThreadInput, RecordRunStartInput, AppendMessageInput, StoredMessage, RecordToolCallInput, UpdateToolCallInput, RecordUsageInput, AgentGovernanceQueries, AgentPricingStore, GovernanceRange, ModelSpendRow, ActorSpendRow, ThreadSpendRow, UsageTrendPoint, ToolCallActivityRow, ThreadActivityRow, RunMetrics, RunAgentBreakdownRow, RunErrorBreakdownRow, RunTrendPoint, RecentRunRow, PendingApprovalRow, ToolStatRow, GovernancePageQuery, ToolCallWhere, GovernancePage, ThreadWhere, RunWhere, ApprovalWhere, GovernanceRunDetail, GovernanceThreadDetailQuery, GovernanceThreadDetail, ModelPriceInput, CurrentModelPrice } from '@dudousxd/nestjs-agent-core';
+export { ThreadTurnPage, ThreadTurnQuery } from '@dudousxd/nestjs-agent-core';
+import { TablesRelationalConfig } from 'drizzle-orm';
 import { Type, DynamicModule } from '@nestjs/common';
 
 /**
@@ -131,6 +133,25 @@ declare const agentThread: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
         }, {}, {
             length: number | undefined;
         }>;
+        defaultAgent: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "default_agent";
+            tableName: "agent_thread";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
         createdAt: drizzle_orm_sqlite_core.SQLiteColumn<{
             name: "created_at";
             tableName: "agent_thread";
@@ -309,6 +330,25 @@ declare const agentMessage: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
         }, {}, {
             $type: ToolResult[];
         }>;
+        attachments: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "attachments";
+            tableName: "agent_message";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: MessageAttachment[];
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: MessageAttachment[];
+        }>;
         followUps: drizzle_orm_sqlite_core.SQLiteColumn<{
             name: "follow_ups";
             tableName: "agent_message";
@@ -366,6 +406,25 @@ declare const agentMessage: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
         }, {}, {
             length: number | undefined;
         }>;
+        runId: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "run_id";
+            tableName: "agent_message";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
         createdAt: drizzle_orm_sqlite_core.SQLiteColumn<{
             name: "created_at";
             tableName: "agent_message";
@@ -386,7 +445,13 @@ declare const agentMessage: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
     };
     dialect: "sqlite";
 }>;
-/** A tool call requested during an assistant turn. The pk is the model-supplied `toolCallId`. */
+/**
+ * A tool call requested during an assistant turn. The pk is the model-supplied `toolCallId`.
+ *
+ * `messageId` carries its own index rather than relying on the foreign key: MySQL indexes a foreign
+ * key column for you, Postgres does not — and every message-scoped read here filters on it (the
+ * thread reader's `IN (…)` over a turn's calls, and `truncateFrom`'s delete).
+ */
 declare const agentToolCall: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
     name: "agent_tool_call";
     schema: undefined;
@@ -1006,8 +1071,14 @@ declare const agentModelPricing: drizzle_orm_sqlite_core.SQLiteTableWithColumns<
     };
     dialect: "sqlite";
 }>;
-/** A run's lifecycle status. Not part of the core SPI (that surfaces `string`) — internal only. */
-type AgentRunStatus = 'running' | 'completed' | 'failed';
+/**
+ * A run's lifecycle status. Not part of the core SPI (that surfaces `string`) — internal only.
+ *
+ * `cancelled` is a third TERMINAL, not a flavour of `failed`: someone asked the run to stop and it
+ * did. A reliability read that folded it into `failed` would page whoever is on call for model
+ * failures every time a user pressed Stop.
+ */
+type AgentRunStatus = 'running' | 'completed' | 'failed' | 'cancelled';
 /**
  * One recorded run (turn) outcome — the durable half of what `aviary:agent:*` diagnostics report
  * ephemerally. Written by {@link import('./drizzle-agent-store.js').DrizzleAgentStore.recordRunStart}/
@@ -1241,6 +1312,25 @@ declare const agentRun: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
         }, {}, {
             length: number | undefined;
         }>;
+        parentRunId: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "parent_run_id";
+            tableName: "agent_run";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
     };
     dialect: "sqlite";
 }>;
@@ -1362,6 +1452,25 @@ declare const agentSchema: {
             }, {}, {
                 length: number | undefined;
             }>;
+            defaultAgent: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "default_agent";
+                tableName: "agent_thread";
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
             createdAt: drizzle_orm_sqlite_core.SQLiteColumn<{
                 name: "created_at";
                 tableName: "agent_thread";
@@ -1535,6 +1644,25 @@ declare const agentSchema: {
             }, {}, {
                 $type: ToolResult[];
             }>;
+            attachments: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "attachments";
+                tableName: "agent_message";
+                dataType: "json";
+                columnType: "SQLiteTextJson";
+                data: MessageAttachment[];
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                $type: MessageAttachment[];
+            }>;
             followUps: drizzle_orm_sqlite_core.SQLiteColumn<{
                 name: "follow_ups";
                 tableName: "agent_message";
@@ -1592,6 +1720,25 @@ declare const agentSchema: {
             }, {}, {
                 length: number | undefined;
             }>;
+            runId: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "run_id";
+                tableName: "agent_message";
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
             createdAt: drizzle_orm_sqlite_core.SQLiteColumn<{
                 name: "created_at";
                 tableName: "agent_message";
@@ -2454,6 +2601,25 @@ declare const agentSchema: {
             }, {}, {
                 length: number | undefined;
             }>;
+            parentRunId: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "parent_run_id";
+                tableName: "agent_run";
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
         };
         dialect: "sqlite";
     }>;
@@ -2463,7 +2629,7 @@ declare const agentSchema: {
  * driver (better-sqlite3, libsql, D1, …) in either sync or async result mode; the host app owns
  * the connection and passes the `drizzle(...)` instance in.
  */
-type AgentDrizzleDb = BaseSQLiteDatabase<'sync' | 'async', unknown>;
+type AgentDrizzleDb = BaseSQLiteDatabase<'sync' | 'async', unknown, Record<string, unknown>, TablesRelationalConfig>;
 /** A persisted thread row as Drizzle selects it. */
 type AgentThreadRow = typeof agentThread.$inferSelect;
 /** A persisted message row as Drizzle selects it. */
@@ -2471,7 +2637,10 @@ type AgentMessageRow = typeof agentMessage.$inferSelect;
 /** A persisted run row as Drizzle selects it. */
 type AgentRunRow = typeof agentRun.$inferSelect;
 
-/** Runs the `CREATE TABLE IF NOT EXISTS` DDL above against the supplied Drizzle SQLite db. */
+/**
+ * Runs the `CREATE TABLE IF NOT EXISTS` DDL above against the supplied Drizzle SQLite db, then adds
+ * any column missing from a table that already existed.
+ */
 declare function ensureAgentSchema(db: AgentDrizzleDb): Promise<void>;
 
 /**
@@ -2480,11 +2649,30 @@ declare function ensureAgentSchema(db: AgentDrizzleDb): Promise<void>;
  * owns the connection). Behaviour mirrors {@link import('@dudousxd/nestjs-agent-store-mikro-orm')}
  * exactly (fork/truncate/quota/active-stream/soft-delete semantics) so the two are interchangeable.
  */
-declare class DrizzleAgentStore implements AgentStore {
+declare class DrizzleAgentStore implements AgentStore, ThreadTurnReader {
     private readonly db;
     constructor(db: AgentDrizzleDb);
     createThread(input: CreateThreadInput): Promise<ThreadSummary>;
     getThread(threadId: string): Promise<ThreadDetail | null>;
+    /**
+     * The window a turn reads off a thread: its newest `messageLimit` messages (oldest first), the
+     * title, the default agent, and whether the thread has EVER been answered.
+     *
+     * {@link getThread} is the wrong read for a turn. It materializes the transcript — every message,
+     * every attachment, every tool output the thread ever recorded — and the run then journals what it
+     * loaded, so a long thread pays for its whole history on every turn and again on every replay.
+     *
+     * `hasAssistantMessage` is answered over the WHOLE thread, not the returned page: it answers "has
+     * this conversation been answered before?", and a thread whose window happens to hold only the
+     * user's last questions has still been answered. `null` when the thread is unknown or
+     * soft-deleted, same as {@link getThread}.
+     */
+    loadThreadForTurn(query: ThreadTurnQuery): Promise<ThreadTurnPage | null>;
+    /**
+     * The newest `limit` messages of a thread, oldest first, projected to the columns a model turn
+     * reads. Read newest-first so the LIMIT is the database's job, then reversed for the prompt.
+     */
+    private loadTurnWindow;
     listThreads(actorRef: string, limit?: number): Promise<ThreadSummary[]>;
     softDeleteThread(threadId: string): Promise<void>;
     forkThread(threadId: string, fromMessageId: string): Promise<ThreadSummary>;
@@ -2495,18 +2683,30 @@ declare class DrizzleAgentStore implements AgentStore {
     setTitle(threadId: string, title: string): Promise<void>;
     promoteThread(threadId: string): Promise<void>;
     setActiveStream(threadId: string, runId: string | null): Promise<void>;
-    /** Persist the start of a run (turn). Replay-safe: called under a durable localStep. */
-    recordRunStart(run: {
-        runId: string;
-        threadId: string;
-        actorRef: string;
-        agentName?: string;
-        promptHash?: string;
-    }): Promise<void>;
+    /**
+     * Patch a thread's `title` and/or `defaultAgent`. Each field is only touched when PRESENT in
+     * `patch` — `defaultAgent: null` clears it (falls back to the app default), while an omitted
+     * `defaultAgent` leaves whatever is stored untouched. A no-op (including `updatedAt`) when the
+     * patch is empty or the thread doesn't exist.
+     */
+    updateThread(threadId: string, patch: UpdateThreadInput): Promise<void>;
+    /**
+     * The thread's default agent, projected — the caller wants one nullable scalar to decide which
+     * agent answers the next turn, and {@link getThread} would materialize the whole transcript to
+     * hand it over. `null` when the thread is unknown, soft-deleted, or has no default set.
+     */
+    defaultAgentForThread(threadId: string): Promise<string | null>;
+    /**
+     * Persist the start of a run (turn). Replay-safe: called under a durable localStep.
+     *
+     * Takes the SPI's own {@link RecordRunStartInput} rather than a hand-copied shape: a field added
+     * to the input is otherwise accepted and dropped, silently, by every adapter that re-declares it.
+     */
+    recordRunStart(run: RecordRunStartInput): Promise<void>;
     /** Settle a run's outcome. A no-op when the run is unknown (mirrors `setTitle`/`updateThread`). */
     recordRunEnd(end: {
         runId: string;
-        status: 'completed' | 'failed';
+        status: 'completed' | 'failed' | 'cancelled';
         durationMs?: number;
         errorCode?: string;
         errorMessage?: string;
@@ -2514,9 +2714,24 @@ declare class DrizzleAgentStore implements AgentStore {
     /** Bump the run's llm-step retry counter. Atomic `retries = retries + 1`, no read-modify-write. */
     bumpRunRetries(runId: string): Promise<void>;
     appendMessage(input: AppendMessageInput): Promise<StoredMessage>;
+    setMessageToolResults(messageId: string, results: ToolResult[]): Promise<void>;
     truncateFrom(threadId: string, messageId: string): Promise<void>;
     recordToolCall(input: RecordToolCallInput): Promise<void>;
     updateToolCall(input: UpdateToolCallInput): Promise<void>;
+    /**
+     * Of `mediaIds`, the ones a surviving message in one of this actor's threads still carries.
+     *
+     * Reads the `attachments` JSON back out and matches in memory rather than pushing the match into
+     * SQL: the column holds an array of objects, and every dialect this adapter's sibling targets
+     * spells that query differently (`jsonb` containment, `json_table`, `json_each`), while none of
+     * them can use an index for it anyway. The scan is bounded by ONE actor's attachment-bearing
+     * messages, which is a small set — attachments are rare, and a message without one is excluded
+     * by the `is not null` before any JSON is parsed.
+     *
+     * Soft-deleted threads are deliberately included: their message rows survive, so the bytes they
+     * point at are still reachable from stored state and are not garbage.
+     */
+    referencedMediaIds(actorRef: string, mediaIds: readonly string[]): Promise<string[]>;
     recordUsage(input: RecordUsageInput): Promise<void>;
     quotaToday(actorRef: string, day: string): Promise<{
         usedTokens: number;