@m6d/cortex-server 1.8.0 → 2.0.0

package/dist/contracts/wire.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The wire contract — every shape that crosses the HTTP/WebSocket boundary
+ * between `@m6d/cortex-server` and the client SDKs (`@m6d/cortex-angular`,
+ * `@m6d/cortex-react`).
+ *
+ * Nothing here has a runtime dependency, and nothing here may grow one: this
+ * file is compiled into an Angular library, a React library and a Bun server
+ * alike.
+ */
+export declare const ATTACHMENT_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "application/pdf"];
+export declare const ATTACHMENT_MAX_BYTES: number;
+export declare const MAX_ATTACHMENTS_PER_MESSAGE = 5;
+export declare const ATTACHMENT_STATUSES: readonly ["pending", "described", "failed", "skipped"];
+export declare function checkAttachmentPolicy(contentType: string, sizeBytes: number): "type" | "size" | "ok";
+export type AttachmentStatus = (typeof ATTACHMENT_STATUSES)[number];
+export type AttachmentSummary = {
+    id: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    status: AttachmentStatus;
+    description?: string;
+};
+export type ThreadSummary = {
+    id: string;
+    title?: string;
+    createdAt: string;
+    updatedAt: string;
+    isRunning: boolean;
+};
+/**
+ * Response of `POST /chat/:chatId/abort`. `aborted: false` means there was no
+ * live run to abort — the turn had already committed — so the caller must not
+ * present the turn as aborted and should read the settled state back instead.
+ */
+export type AbortRunResult = {
+    aborted: boolean;
+};
+export type TokenUsage = {
+    input: {
+        noCache: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+    output: {
+        reasoning: number;
+        text: number;
+        total: number;
+    };
+    total: number;
+};
+export type MessageMetadata = {
+    modelId?: string;
+    providerMetadata?: unknown;
+    isAborted?: boolean;
+    tokenUsage?: TokenUsage;
+    attachments?: AttachmentSummary[];
+};
+/**
+ * A stored message as it is persisted and served. TanStack AI's `UIMessage`
+ * has no metadata field, so cortex owns the envelope: the SDK's parts plus the
+ * server-derived metadata the UI renders on settled messages.
+ *
+ * `TPart` stays generic so this file keeps its zero dependencies — both
+ * sides substitute the SDK's `MessagePart`.
+ */
+export type CortexMessage<TPart = unknown> = {
+    id: string;
+    role: "system" | "user" | "assistant";
+    parts: TPart[];
+    metadata?: MessageMetadata;
+};
+export type ThreadCreatedEvent = {
+    type: "thread:created";
+    payload: {
+        thread: ThreadSummary;
+    };
+};
+export type ThreadDeletedEvent = {
+    type: "thread:deleted";
+    payload: {
+        threadId: string;
+    };
+};
+export type ThreadTitleUpdatedEvent = {
+    type: "thread:title-updated";
+    payload: {
+        thread: ThreadSummary;
+    };
+};
+export type ThreadRunStartedEvent = {
+    type: "thread:run-started";
+    payload: {
+        thread: ThreadSummary;
+    };
+};
+export type ThreadRunFinishedEvent = {
+    type: "thread:run-finished";
+    payload: {
+        thread: ThreadSummary;
+    };
+};
+export type ThreadMessagesUpdatedEvent = {
+    type: "thread:messages-updated";
+    payload: {
+        threadId: string;
+        thread: ThreadSummary;
+    };
+};
+export type ToolProgressEvent = {
+    type: "thread:tool-progress";
+    payload: {
+        threadId: string;
+        toolCallId: string;
+        toolName: string;
+        status: "started" | "finished";
+    };
+};
+export type WsEvent = ThreadCreatedEvent | ThreadDeletedEvent | ThreadTitleUpdatedEvent | ThreadRunStartedEvent | ThreadRunFinishedEvent | ThreadMessagesUpdatedEvent | ToolProgressEvent;

package/dist/src/lib/adapters/database/index.d.ts

@@ -0,0 +1,61 @@
+import type { Attachment, ChatMessage, NewAttachment, StoredMessage, Thread, TokenUsage } from "../../types";
+import type { ThreadContextMeta } from "../../ai/context/types";
+/**
+ * The persistence contract, implemented once per dialect under `mssql/` and
+ * `postgres/`.
+ *
+ * Those two trees are near-identical on purpose. Drizzle types its query
+ * builders per dialect, so a shared body is not expressible — `.top`/`.limit`,
+ * `.output`/`.returning` and the row-lock hint differ down in the query, not at
+ * a seam that could be factored out. What is *not* SQL lives in
+ * `message-content.ts` instead, so the rules the two must agree on are stated
+ * once.
+ *
+ * Drift is guarded rather than prevented: `db/schema.parity.test.ts` asserts the
+ * two schemas still infer the same rows, and the adapter tests beside this file
+ * run against both implementations. The `code-duplication` suppressions in
+ * `postgres/` record the same decision for fallow.
+ */
+export type DatabaseAdapter = {
+    threads: {
+        list(userId: string, agentId: string): Promise<Thread[]>;
+        getById(userId: string, threadId: string): Promise<Thread | null>;
+        create(userId: string, agentId: string): Promise<Thread>;
+        delete(userId: string, threadId: string): Promise<void>;
+        touch(threadId: string): Promise<Thread>;
+        updateTitle(threadId: string, title: string): Promise<void>;
+        updateSession(threadId: string, session: Record<string, unknown>): Promise<void>;
+        updateContextMeta(threadId: string, meta: ThreadContextMeta): Promise<void>;
+    };
+    messages: {
+        list(userId: string, threadId: string, opts?: {
+            limit?: number;
+        }): Promise<StoredMessage[]>;
+        upsert(threadId: string, messages: ChatMessage[], options?: {
+            replaceAttachments?: boolean;
+        }): Promise<void>;
+    };
+    llmRequests: {
+        insert(requests: {
+            messageId: string;
+            stepNumber: number;
+            prompt: string;
+            output: string | null;
+            tokenUsage: TokenUsage | null;
+        }[]): Promise<void>;
+        listByMessageId(messageId: string): Promise<{
+            id: string;
+            prompt: string;
+            output: string | null;
+            tokenUsage: TokenUsage | null;
+        }[]>;
+    };
+    attachments: {
+        createPending(row: NewAttachment, limit: number): Promise<Attachment | undefined>;
+        getById(id: string, userId: string): Promise<Attachment | undefined>;
+        listByThread(threadId: string, userId: string): Promise<Attachment[]>;
+        claimForMessage(threadId: string, userId: string, messageId: string): Promise<Attachment[]>;
+        setDescription(id: string, userId: string, status: Attachment["status"], description?: string): Promise<void>;
+        remove(id: string, userId: string): Promise<Attachment | undefined>;
+    };
+};

package/dist/src/lib/adapters/database/message-content.d.ts

@@ -0,0 +1,30 @@
+import type { ChatMessage } from "../../types";
+/**
+ * The parts of `messages.upsert` that are decisions rather than SQL. Each
+ * dialect writes its own queries, but they must agree on what gets written —
+ * so the rules live here and neither repository restates them.
+ */
+/** Denormalized alongside the JSON content so the column is searchable. */
+export declare function textOf(message: ChatMessage): string | undefined;
+/**
+ * Attachments are the server's to assign: a caller may name them but never
+ * establish them. Only a turn that has just claimed them may carry them in.
+ */
+export declare function withOwnedAttachments(messages: ChatMessage[], replaceAttachments?: boolean): (ChatMessage | {
+    metadata: {
+        modelId?: string;
+        providerMetadata?: unknown;
+        isAborted?: boolean;
+        tokenUsage?: import("../../types").TokenUsage;
+    };
+    id: string;
+    role: "system" | "user" | "assistant";
+    parts: import("@tanstack/ai").MessagePart[];
+})[];
+/**
+ * The envelope is the server's — usage, model id and the attachments it claimed
+ * are facts no caller carries in full, so an update only contributes the fields
+ * it actually set. Attachments were already stripped from anything that must
+ * not replace them.
+ */
+export declare function mergeStoredContent(existing: ChatMessage, incoming: ChatMessage): ChatMessage;

package/dist/src/lib/adapters/database/mssql/attachments.d.ts

@@ -0,0 +1,100 @@
+import type { MssqlDb } from "./client";
+export declare function createAttachmentsRepository(db: MssqlDb): {
+    createPending(row: {
+        userId: string;
+        threadId: string;
+        filename: string;
+        contentType: string;
+        sizeBytes: number;
+        storageKey: string;
+        status: "pending" | "described" | "failed" | "skipped";
+        id?: string | undefined;
+        createdAt?: Date | undefined;
+        updatedAt?: Date | undefined;
+        messageId?: string | null | undefined;
+        description?: string | null | undefined;
+    }, limit: number): Promise<{
+        id: string;
+        userId: string;
+        createdAt: Date;
+        updatedAt: Date;
+        threadId: string;
+        messageId: string | null;
+        filename: string;
+        contentType: string;
+        sizeBytes: number;
+        storageKey: string;
+        status: "pending" | "described" | "failed" | "skipped";
+        description: string | null;
+    } | undefined>;
+    getById(id: string, userId: string): Promise<{
+        id: string;
+        userId: string;
+        createdAt: Date;
+        updatedAt: Date;
+        threadId: string;
+        messageId: string | null;
+        filename: string;
+        contentType: string;
+        sizeBytes: number;
+        storageKey: string;
+        status: "pending" | "described" | "failed" | "skipped";
+        description: string | null;
+    } | {
+        createdAt: Date;
+        updatedAt: Date;
+        id: string;
+        threadId: string;
+        userId: string;
+        messageId: string | null;
+        filename: string;
+        contentType: string;
+        sizeBytes: number;
+        storageKey: string;
+        status: "pending" | "described" | "failed" | "skipped";
+        description: string | null;
+    } | undefined>;
+    listByThread(threadId: string, userId: string): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: string;
+        threadId: string;
+        userId: string;
+        messageId: string | null;
+        filename: string;
+        contentType: string;
+        sizeBytes: number;
+        storageKey: string;
+        status: "pending" | "described" | "failed" | "skipped";
+        description: string | null;
+    }[]>;
+    claimForMessage(threadId: string, userId: string, messageId: string): Promise<{
+        id: string;
+        userId: string;
+        createdAt: Date;
+        updatedAt: Date;
+        threadId: string;
+        messageId: string | null;
+        filename: string;
+        contentType: string;
+        sizeBytes: number;
+        storageKey: string;
+        status: "pending" | "described" | "failed" | "skipped";
+        description: string | null;
+    }[]>;
+    setDescription(id: string, userId: string, status: "pending" | "described" | "failed" | "skipped", description: string | undefined): Promise<void>;
+    remove(id: string, userId: string): Promise<{
+        id: string;
+        userId: string;
+        createdAt: Date;
+        updatedAt: Date;
+        threadId: string;
+        messageId: string | null;
+        filename: string;
+        contentType: string;
+        sizeBytes: number;
+        storageKey: string;
+        status: "pending" | "described" | "failed" | "skipped";
+        description: string | null;
+    } | undefined>;
+};

package/dist/src/lib/adapters/database/mssql/client.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Global snake_case mapping means schema columns are never spelled out twice —
+ * the TypeScript name is the source of truth and Drizzle derives the column.
+ */
+export declare function createMssqlDb(connectionString: string): import("drizzle-orm/node-mssql").NodeMsSqlDatabase<Record<string, never>> & {
+    $client: import("drizzle-orm/node-mssql/pool").AutoPool;
+};
+export type MssqlDb = ReturnType<typeof createMssqlDb>;

package/dist/src/lib/adapters/database/mssql/index.d.ts

@@ -0,0 +1,194 @@
+import type { StorageAdapter } from "../../../adapters/storage/index";
+/**
+ * The MSSQL implementation of the database contract. One repository per table;
+ * only threads takes storage, because deleting a thread is the one operation
+ * that also has to reach into object storage.
+ */
+export declare function createMssqlAdapter(connectionString: string, storage?: StorageAdapter): {
+    threads: {
+        list(userId: string, agentId: string): Promise<{
+            createdAt: Date;
+            updatedAt: Date;
+            id: string;
+            userId: string;
+            agentId: string;
+            title: string | null;
+            session: Record<string, unknown> | null;
+            contextMeta: import("../../..").ThreadContextMeta | null;
+        }[]>;
+        getById(userId: string, threadId: string): Promise<{
+            id: string;
+            userId: string;
+            agentId: string;
+            title: string | null;
+            session: Record<string, unknown> | null;
+            contextMeta: import("../../..").ThreadContextMeta | null;
+            createdAt: Date;
+            updatedAt: Date;
+        } | null>;
+        create(userId: string, agentId: string): Promise<{
+            id: string;
+            userId: string;
+            agentId: string;
+            title: string | null;
+            session: Record<string, unknown> | null;
+            contextMeta: import("../../..").ThreadContextMeta | null;
+            createdAt: Date;
+            updatedAt: Date;
+        }>;
+        delete(userId: string, threadId: string): Promise<void>;
+        touch(threadId: string): Promise<{
+            id: string;
+            userId: string;
+            agentId: string;
+            title: string | null;
+            session: Record<string, unknown> | null;
+            contextMeta: import("../../..").ThreadContextMeta | null;
+            createdAt: Date;
+            updatedAt: Date;
+        }>;
+        updateTitle(threadId: string, title: string): Promise<void>;
+        updateSession(threadId: string, session: Record<string, unknown>): Promise<void>;
+        updateContextMeta(threadId: string, meta: import("../../..").ThreadContextMeta): Promise<void>;
+    };
+    messages: {
+        list(userId: string, threadId: string, opts: {
+            limit?: number;
+        } | undefined): Promise<{
+            id: string;
+            text: string | null;
+            createdAt: Date;
+            updatedAt: Date;
+            threadId: string;
+            content: import("../../../types").ChatMessage;
+            ordinal: number;
+            role: "system" | "user" | "assistant" | "tool";
+        }[] | {
+            createdAt: Date;
+            updatedAt: Date;
+            id: string;
+            threadId: string;
+            text: string | null;
+            content: import("../../../types").ChatMessage;
+            ordinal: number;
+            role: "system" | "user" | "assistant" | "tool";
+        }[]>;
+        upsert(threadId: string, messagesToUpsert: import("../../../types").ChatMessage[], options?: {
+            replaceAttachments?: boolean;
+        }): Promise<void>;
+    };
+    llmRequests: {
+        insert(requests: {
+            messageId: string;
+            stepNumber: number;
+            prompt: string;
+            output: string | null;
+            tokenUsage: import("../../..").TokenUsage | null;
+        }[]): Promise<void>;
+        listByMessageId(messageId: string): Promise<{
+            id: string;
+            prompt: string;
+            output: string | null;
+            tokenUsage: import("../../..").TokenUsage | null;
+        }[]>;
+    };
+    attachments: {
+        createPending(row: {
+            userId: string;
+            threadId: string;
+            filename: string;
+            contentType: string;
+            sizeBytes: number;
+            storageKey: string;
+            status: "pending" | "described" | "failed" | "skipped";
+            id?: string | undefined;
+            createdAt?: Date | undefined;
+            updatedAt?: Date | undefined;
+            messageId?: string | null | undefined;
+            description?: string | null | undefined;
+        }, limit: number): Promise<{
+            id: string;
+            userId: string;
+            createdAt: Date;
+            updatedAt: Date;
+            threadId: string;
+            messageId: string | null;
+            filename: string;
+            contentType: string;
+            sizeBytes: number;
+            storageKey: string;
+            status: "pending" | "described" | "failed" | "skipped";
+            description: string | null;
+        } | undefined>;
+        getById(id: string, userId: string): Promise<{
+            id: string;
+            userId: string;
+            createdAt: Date;
+            updatedAt: Date;
+            threadId: string;
+            messageId: string | null;
+            filename: string;
+            contentType: string;
+            sizeBytes: number;
+            storageKey: string;
+            status: "pending" | "described" | "failed" | "skipped";
+            description: string | null;
+        } | {
+            createdAt: Date;
+            updatedAt: Date;
+            id: string;
+            threadId: string;
+            userId: string;
+            messageId: string | null;
+            filename: string;
+            contentType: string;
+            sizeBytes: number;
+            storageKey: string;
+            status: "pending" | "described" | "failed" | "skipped";
+            description: string | null;
+        } | undefined>;
+        listByThread(threadId: string, userId: string): Promise<{
+            createdAt: Date;
+            updatedAt: Date;
+            id: string;
+            threadId: string;
+            userId: string;
+            messageId: string | null;
+            filename: string;
+            contentType: string;
+            sizeBytes: number;
+            storageKey: string;
+            status: "pending" | "described" | "failed" | "skipped";
+            description: string | null;
+        }[]>;
+        claimForMessage(threadId: string, userId: string, messageId: string): Promise<{
+            id: string;
+            userId: string;
+            createdAt: Date;
+            updatedAt: Date;
+            threadId: string;
+            messageId: string | null;
+            filename: string;
+            contentType: string;
+            sizeBytes: number;
+            storageKey: string;
+            status: "pending" | "described" | "failed" | "skipped";
+            description: string | null;
+        }[]>;
+        setDescription(id: string, userId: string, status: "pending" | "described" | "failed" | "skipped", description: string | undefined): Promise<void>;
+        remove(id: string, userId: string): Promise<{
+            id: string;
+            userId: string;
+            createdAt: Date;
+            updatedAt: Date;
+            threadId: string;
+            messageId: string | null;
+            filename: string;
+            contentType: string;
+            sizeBytes: number;
+            storageKey: string;
+            status: "pending" | "described" | "failed" | "skipped";
+            description: string | null;
+        } | undefined>;
+    };
+};

package/dist/src/lib/adapters/database/mssql/llm-requests.d.ts

@@ -0,0 +1,17 @@
+import type { MssqlDb } from "./client";
+export declare function createLlmRequestsRepository(db: MssqlDb): {
+    insert(requests: {
+        messageId: string;
+        stepNumber: number;
+        prompt: string;
+        output: string | null;
+        tokenUsage: import("../../..").TokenUsage | null;
+    }[]): Promise<void>;
+    /** Ordered by step so the inspector replays a turn in the order it ran. */
+    listByMessageId(messageId: string): Promise<{
+        id: string;
+        prompt: string;
+        output: string | null;
+        tokenUsage: import("../../..").TokenUsage | null;
+    }[]>;
+};

package/dist/src/lib/adapters/database/mssql/messages.d.ts

@@ -0,0 +1,37 @@
+import type { ChatMessage } from "../../../types";
+import type { MssqlDb } from "./client";
+export declare function createMessagesRepository(db: MssqlDb): {
+    /**
+     * Fetches the newest N and reverses, so a limit keeps the most recent
+     * messages while callers still receive them oldest-first.
+     */
+    list(userId: string, threadId: string, opts: {
+        limit?: number;
+    } | undefined): Promise<{
+        id: string;
+        text: string | null;
+        createdAt: Date;
+        updatedAt: Date;
+        threadId: string;
+        content: ChatMessage;
+        ordinal: number;
+        role: "system" | "user" | "assistant" | "tool";
+    }[] | {
+        createdAt: Date;
+        updatedAt: Date;
+        id: string;
+        threadId: string;
+        text: string | null;
+        content: ChatMessage;
+        ordinal: number;
+        role: "system" | "user" | "assistant" | "tool";
+    }[]>;
+    /**
+     * Ids are client-generated, so a turn mixes new messages with edits to
+     * ones already stored. Splitting on existence lets the new ones go in as
+     * a single insert; the rest are updated individually.
+     */
+    upsert(threadId: string, messagesToUpsert: ChatMessage[], options?: {
+        replaceAttachments?: boolean;
+    }): Promise<void>;
+};

package/dist/src/lib/adapters/database/mssql/threads.d.ts

@@ -0,0 +1,50 @@
+import type { ThreadContextMeta } from "../../../ai/context/types";
+import type { MssqlDb } from "./client";
+import type { StorageAdapter } from "../../../adapters/storage/index";
+export declare function createThreadsRepository(db: MssqlDb, storage?: StorageAdapter): {
+    list(userId: string, agentId: string): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: string;
+        userId: string;
+        agentId: string;
+        title: string | null;
+        session: Record<string, unknown> | null;
+        contextMeta: ThreadContextMeta | null;
+    }[]>;
+    getById(userId: string, threadId: string): Promise<{
+        id: string;
+        userId: string;
+        agentId: string;
+        title: string | null;
+        session: Record<string, unknown> | null;
+        contextMeta: ThreadContextMeta | null;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    create(userId: string, agentId: string): Promise<{
+        id: string;
+        userId: string;
+        agentId: string;
+        title: string | null;
+        session: Record<string, unknown> | null;
+        contextMeta: ThreadContextMeta | null;
+        createdAt: Date;
+        updatedAt: Date;
+    }>;
+    /** Object storage has no foreign keys, so attachment paths must be swept before row cascade. */
+    delete(userId: string, threadId: string): Promise<void>;
+    touch(threadId: string): Promise<{
+        id: string;
+        userId: string;
+        agentId: string;
+        title: string | null;
+        session: Record<string, unknown> | null;
+        contextMeta: ThreadContextMeta | null;
+        createdAt: Date;
+        updatedAt: Date;
+    }>;
+    updateTitle(threadId: string, title: string): Promise<void>;
+    updateSession(threadId: string, session: Record<string, unknown>): Promise<void>;
+    updateContextMeta(threadId: string, meta: ThreadContextMeta): Promise<void>;
+};