@m6d/cortex-server 1.8.0 → 2.0.0

package/dist/src/lib/routes/owned-thread.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from "hono";
+import type { CortexAppEnv } from "../types";
+/**
+ * Loads a thread and asserts it belongs to both the caller and the agent in the
+ * path. A thread owned by another agent 404s rather than 403 on purpose — a 403
+ * would confirm the thread exists, making cross-agent ids probeable.
+ */
+export declare function requireOwnedThread(c: Context<CortexAppEnv>, 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;
+}>;

package/dist/src/lib/routes/threads.d.ts

@@ -1,3 +1,3 @@
 import { Hono } from "hono";
-import type { CortexAppEnv } from "../types.ts";
+import type { CortexAppEnv } from "../types";
 export declare function createThreadRoutes(): Hono<CortexAppEnv, import("hono/types").BlankSchema, "/">;

package/dist/src/lib/routes/ws.d.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import type { AppEnv } from "../types.ts";
+import type { AppEnv } from "../types";
 type WsRouteOptions = {
     useAgentParam?: boolean;
 };

package/dist/src/lib/types.d.ts

@@ -1,42 +1,15 @@
+import type { MessagePart } from "@tanstack/ai";
 import type { ResolvedCortexAgentConfig } from "./config";
 import type { InferSelectModel } from "drizzle-orm";
-import type { messages, threads } from "./db/schema";
+import type { attachments, messages, threads } from "./db/schema.mssql";
+export type { CortexMessage, MessageMetadata, ThreadSummary, TokenUsage, } from "../../contracts/wire";
+import type { CortexMessage } from "../../contracts/wire";
+/** A message as cortex persists and serves it: SDK parts plus cortex's envelope. */
+export type ChatMessage = CortexMessage<MessagePart>;
 export type Thread = InferSelectModel<typeof threads>;
 export type StoredMessage = InferSelectModel<typeof messages>;
-export type ThreadSummary = {
-    id: string;
-    title?: string;
-    createdAt: Date;
-    updatedAt: Date;
-    isRunning: 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;
-};
-export type CapturedFileInput = {
-    id: string;
-    file: {
-        name: string;
-        bytes: string;
-    };
-};
+export type Attachment = InferSelectModel<typeof attachments>;
+export type NewAttachment = typeof attachments.$inferInsert;
 export type AppEnv = {
     Bindings: {};
     Variables: {
@@ -66,10 +39,20 @@ export type CortexAppEnv = {
         agentId: string;
     };
 };
+/** Maps a stored row to the wire shape. Dates become ISO strings — the same bytes
+ * `JSON.stringify` would have produced, but now the type says so. */
 export declare function toThreadSummary(thread: Thread, isRunning: boolean): {
     id: string;
     title: string | undefined;
-    createdAt: Date;
-    updatedAt: Date;
+    createdAt: string;
+    updatedAt: string;
     isRunning: boolean;
 };
+export declare function toAttachmentSummary(attachment: Attachment): {
+    id: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    status: "pending" | "described" | "failed" | "skipped";
+    description: string | undefined;
+};

package/dist/src/lib/ws/connections.d.ts

@@ -1,4 +1,5 @@
 import type { WSContext } from "hono/ws";
+import type { WsEvent } from "../../../contracts/wire";
 export declare function addConnection(userId: string, agentId: string, ws: WSContext): void;
 export declare function removeConnection(userId: string, agentId: string, ws: WSContext): void;
-export declare function getConnections(userId: string, agentId: string): WSContext<unknown>[];
+export declare function notify(userId: string, agentId: string, event: WsEvent): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-server",
-    "version": "1.8.0",
+    "version": "2.0.0",
     "description": "Reusable AI agent chat server library for Hono + Bun",
     "license": "MIT",
     "type": "module",
@@ -16,43 +16,58 @@
     "files": [
         "dist",
         "src",
+        "contracts",
         "index.ts",
-        "README.md"
+        "README.md",
+        "tsconfig.json",
+        "!src/**/*.test.ts",
+        "!src/**/*.mock.ts"
     ],
     "scripts": {
-        "build": "tsc -p tsconfig.build.json",
-        "db:generate": "drizzle-kit generate",
-        "db:migrate": "drizzle-kit migrate",
-        "db:sample:generate": "drizzle-kit generate --config ./src/sample/drizzle.config.ts",
-        "db:sample:migrate": "drizzle-kit migrate --config ./src/sample/drizzle.config.ts",
-        "dev": "bun run --hot src/sample/index.ts"
+        "build": "bun run vendor && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && rm -rf contracts",
+        "check": "tsc --noEmit",
+        "db:generate:mssql": "drizzle-kit generate --config=src/lib/db/drizzle.config.mssql.ts",
+        "db:generate:pg": "drizzle-kit generate --config=src/lib/db/drizzle.config.pg.ts",
+        "db:migrate:mssql": "drizzle-kit migrate --config=src/lib/db/drizzle.config.mssql.ts",
+        "db:migrate:pg": "drizzle-kit migrate --config=src/lib/db/drizzle.config.pg.ts",
+        "prepack": "bun run vendor",
+        "postpack": "rm -rf contracts",
+        "test": "bun test",
+        "vendor": "rm -rf contracts && cp -R ../../internal/contracts contracts && rm contracts/package.json contracts/tsconfig.json"
     },
     "dependencies": {
-        "@ai-sdk/provider": "^3.0.0",
-        "@hono/zod-validator": "^0.5.0",
-        "drizzle-orm": "^1.0.0-beta.15-859cf75",
+        "@hono/zod-validator": "^0.9.0",
+        "@hyzyla/pdfium": "^2.1.13",
+        "drizzle-orm": "1.0.0-beta.15-859cf75",
+        "ioredis": "^5.9.2",
+        "jpeg-js": "^0.4.4",
         "minio": "^8.0.7",
         "mssql": "^12.2.0",
+        "pg": "^8.16.3",
         "quickjs-emscripten": "^0.32.0"
     },
     "devDependencies": {
-        "@ai-sdk/openai-compatible": "^2.0.0",
+        "@tanstack/ai": "^0.43.1",
+        "@tanstack/ai-openai": "^0.18.0",
         "@types/bun": "latest",
         "@types/minio": "^7.1.1",
         "@types/mssql": "^9.1.5",
-        "ai": "^6.0.104",
-        "drizzle-kit": "^1.0.0-beta.15-859cf75",
+        "@types/pg": "^8.15.6",
+        "drizzle-kit": "1.0.0-beta.15-859cf75",
         "hono": "^4.12.3",
         "jose": "^6.1.3",
-        "typescript": "^5",
+        "openai": "^6",
+        "tsc-alias": "^1.9.1",
+        "typescript": "~5.9.3",
         "zod": "^4.3.6"
     },
     "peerDependencies": {
-        "@ai-sdk/openai-compatible": "^2.0.0",
-        "ai": "^6.0.0",
+        "@tanstack/ai": "^0.43.1",
+        "@tanstack/ai-openai": "^0.18.0",
         "hono": "^4.12.3",
         "jose": "^6.1.3",
-        "zod": "^3.24.0"
+        "openai": "^6",
+        "zod": "^4.1.8"
     },
     "engines": {
         "bun": ">=1.0.0"

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

@@ -0,0 +1,78 @@
+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/src/lib/adapters/database/message-content.ts

@@ -0,0 +1,39 @@
+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 function textOf(message: ChatMessage) {
+    return message.parts.find((part) => part.type === "text")?.content;
+}
+
+/**
+ * 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 function withOwnedAttachments(messages: ChatMessage[], replaceAttachments?: boolean) {
+    if (replaceAttachments) return messages;
+
+    return messages.map((message) => {
+        if (!message.metadata) return message;
+
+        const { attachments: _, ...metadata } = message.metadata;
+        return { ...message, metadata };
+    });
+}
+
+/**
+ * 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 function mergeStoredContent(existing: ChatMessage, incoming: ChatMessage) {
+    return existing.metadata
+        ? { ...incoming, metadata: { ...existing.metadata, ...incoming.metadata } }
+        : incoming;
+}

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

@@ -0,0 +1,90 @@
+// fallow-ignore-file duplicate-export -- mssql twin of the postgres repository, same factory name by design
+import { and, asc, count, eq, isNull, or, sql } from "drizzle-orm";
+import { attachments, threads } from "@/db/schema.mssql";
+import type { DatabaseAdapter } from "@/adapters/database/index";
+import type { MssqlDb } from "./client";
+
+export function createAttachmentsRepository(db: MssqlDb) {
+    return {
+        async createPending(row, limit) {
+            return await db.transaction(async function (tx) {
+                await tx.execute(
+                    sql`SELECT 1 FROM ${threads} WITH (UPDLOCK, HOLDLOCK) WHERE ${threads.id} = ${row.threadId}`,
+                );
+                const pending = await tx
+                    .select({ value: count() })
+                    .from(attachments)
+                    .where(
+                        and(
+                            eq(attachments.threadId, row.threadId),
+                            eq(attachments.userId, row.userId),
+                            isNull(attachments.messageId),
+                        ),
+                    )
+                    .execute()
+                    .then((rows) => rows[0]!.value);
+                if (pending >= limit) return undefined;
+
+                return await tx
+                    .insert(attachments)
+                    .output()
+                    .values(row)
+                    .execute()
+                    .then((rows) => rows[0]!);
+            });
+        },
+
+        async getById(id, userId) {
+            return await db
+                .select()
+                .top(1)
+                .from(attachments)
+                .where(and(eq(attachments.id, id), eq(attachments.userId, userId)))
+                .execute()
+                .then((rows) => rows[0]);
+        },
+
+        async listByThread(threadId, userId) {
+            return await db
+                .select()
+                .from(attachments)
+                .where(and(eq(attachments.threadId, threadId), eq(attachments.userId, userId)))
+                .orderBy(asc(attachments.createdAt), asc(attachments.id))
+                .execute();
+        },
+
+        async claimForMessage(threadId, userId, messageId) {
+            // ponytail: retries only this message's pending rows; add claim timestamps for cross-message recovery.
+            return await db
+                .update(attachments)
+                .set({ messageId })
+                .where(
+                    and(
+                        eq(attachments.threadId, threadId),
+                        eq(attachments.userId, userId),
+                        eq(attachments.status, "pending"),
+                        or(isNull(attachments.messageId), eq(attachments.messageId, messageId)),
+                    ),
+                )
+                .output()
+                .execute();
+        },
+
+        async setDescription(id, userId, status, description) {
+            await db
+                .update(attachments)
+                .set(description === undefined ? { status } : { status, description })
+                .where(and(eq(attachments.id, id), eq(attachments.userId, userId)))
+                .execute();
+        },
+
+        async remove(id, userId) {
+            return await db
+                .delete(attachments)
+                .where(and(eq(attachments.id, id), eq(attachments.userId, userId)))
+                .output()
+                .execute()
+                .then((rows) => rows[0]);
+        },
+    } satisfies DatabaseAdapter["attachments"];
+}

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

@@ -0,0 +1,11 @@
+import { drizzle } from "drizzle-orm/node-mssql";
+
+/**
+ * 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 function createMssqlDb(connectionString: string) {
+    return drizzle(connectionString, { casing: "snake_case" });
+}
+
+export type MssqlDb = ReturnType<typeof createMssqlDb>;

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

@@ -0,0 +1,23 @@
+import type { DatabaseAdapter } from "@/adapters/database/index";
+import type { StorageAdapter } from "@/adapters/storage/index";
+import { createMssqlDb } from "./client";
+import { createThreadsRepository } from "./threads";
+import { createMessagesRepository } from "./messages";
+import { createLlmRequestsRepository } from "./llm-requests";
+import { createAttachmentsRepository } from "./attachments";
+
+/**
+ * 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 function createMssqlAdapter(connectionString: string, storage?: StorageAdapter) {
+    const db = createMssqlDb(connectionString);
+
+    return {
+        threads: createThreadsRepository(db, storage),
+        messages: createMessagesRepository(db),
+        llmRequests: createLlmRequestsRepository(db),
+        attachments: createAttachmentsRepository(db),
+    } satisfies DatabaseAdapter;
+}

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

@@ -0,0 +1,43 @@
+import { asc, eq, type InferInsertModel } from "drizzle-orm";
+import { llmRequests } from "@/db/schema.mssql";
+import type { DatabaseAdapter } from "@/adapters/database/index";
+import type { MssqlDb } from "./client";
+
+export function createLlmRequestsRepository(db: MssqlDb) {
+    return {
+        async insert(requests) {
+            if (!requests.length) return;
+
+            await db
+                .insert(llmRequests)
+                .values(
+                    requests.map(
+                        (r) =>
+                            ({
+                                messageId: r.messageId,
+                                stepNumber: r.stepNumber,
+                                prompt: r.prompt,
+                                output: r.output,
+                                tokenUsage: r.tokenUsage,
+                            }) satisfies InferInsertModel<typeof llmRequests>,
+                    ),
+                )
+                .execute();
+        },
+
+        /** Ordered by step so the inspector replays a turn in the order it ran. */
+        async listByMessageId(messageId) {
+            return await db
+                .select({
+                    id: llmRequests.id,
+                    prompt: llmRequests.prompt,
+                    output: llmRequests.output,
+                    tokenUsage: llmRequests.tokenUsage,
+                })
+                .from(llmRequests)
+                .where(eq(llmRequests.messageId, messageId))
+                .orderBy(asc(llmRequests.stepNumber))
+                .execute();
+        },
+    } satisfies DatabaseAdapter["llmRequests"];
+}

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

@@ -0,0 +1,92 @@
+// fallow-ignore-file duplicate-export -- mssql twin of the postgres repository, same factory name by design
+import { and, desc, eq, getColumns, inArray, type InferInsertModel } from "drizzle-orm";
+import { threads, messages } from "@/db/schema.mssql";
+import type { ChatMessage } from "@/types";
+import type { DatabaseAdapter } from "@/adapters/database/index";
+import {
+    mergeStoredContent,
+    textOf,
+    withOwnedAttachments,
+} from "@/adapters/database/message-content";
+import type { MssqlDb } from "./client";
+
+const DEFAULT_MESSAGE_LIMIT = 100;
+
+export function createMessagesRepository(db: MssqlDb) {
+    return {
+        /**
+         * Fetches the newest N and reverses, so a limit keeps the most recent
+         * messages while callers still receive them oldest-first.
+         */
+        async list(userId, threadId, opts) {
+            return await db
+                .select(getColumns(messages))
+                .from(messages)
+                .innerJoin(threads, eq(threads.id, messages.threadId))
+                .where(and(eq(threads.userId, userId), eq(threads.id, threadId)))
+                .orderBy(desc(messages.createdAt), desc(messages.ordinal))
+                .offset(0)
+                .fetch(opts?.limit ?? DEFAULT_MESSAGE_LIMIT)
+                .then((x) => x.reverse());
+        },
+
+        /**
+         * 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.
+         */
+        async upsert(
+            threadId: string,
+            messagesToUpsert: ChatMessage[],
+            options?: { replaceAttachments?: boolean },
+        ) {
+            const incomingMessages = withOwnedAttachments(
+                messagesToUpsert,
+                options?.replaceAttachments,
+            );
+            const existingMessages = await db
+                .select({ id: messages.id, content: messages.content })
+                .from(messages)
+                .where(
+                    inArray(
+                        messages.id,
+                        incomingMessages.map((x) => x.id),
+                    ),
+                )
+                .execute();
+            const existingById = new Map(
+                existingMessages.map((message) => [message.id, message.content]),
+            );
+
+            const newMessages = incomingMessages.filter((x) => !existingById.has(x.id));
+            if (newMessages.length) {
+                await db
+                    .insert(messages)
+                    .values(
+                        newMessages.map(
+                            (x, ordinal) =>
+                                ({
+                                    id: x.id,
+                                    role: x.role,
+                                    threadId,
+                                    content: x,
+                                    text: textOf(x),
+                                    ordinal,
+                                }) satisfies InferInsertModel<typeof messages>,
+                        ),
+                    )
+                    .execute();
+            }
+
+            for (const message of incomingMessages.filter((x) => existingById.has(x.id))) {
+                const content = mergeStoredContent(existingById.get(message.id)!, message);
+
+                await db
+                    .update(messages)
+                    .set({ content, text: textOf(content) })
+                    .where(eq(messages.id, message.id))
+                    .execute();
+            }
+        },
+    } satisfies DatabaseAdapter["messages"];
+}

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

@@ -0,0 +1,83 @@
+import { and, desc, eq } from "drizzle-orm";
+import { attachments, threads } from "@/db/schema.mssql";
+import type { Thread } from "@/types";
+import type { ThreadContextMeta } from "@/ai/context/types";
+import type { DatabaseAdapter } from "@/adapters/database/index";
+import type { MssqlDb } from "./client";
+import type { StorageAdapter } from "@/adapters/storage/index";
+
+export function createThreadsRepository(db: MssqlDb, storage?: StorageAdapter) {
+    return {
+        async list(userId, agentId) {
+            return await db
+                .select()
+                .from(threads)
+                .where(and(eq(threads.userId, userId), eq(threads.agentId, agentId)))
+                .orderBy(desc(threads.updatedAt), desc(threads.createdAt));
+        },
+
+        async getById(userId, threadId) {
+            const result = await db
+                .select()
+                .top(1)
+                .from(threads)
+                .where(and(eq(threads.id, threadId), eq(threads.userId, userId)))
+                .execute();
+            return result.length ? (result[0] as Thread) : null;
+        },
+
+        async create(userId, agentId) {
+            const result = await db.insert(threads).output().values({ userId, agentId }).execute();
+            return result[0] as Thread;
+        },
+
+        /** Object storage has no foreign keys, so attachment paths must be swept before row cascade. */
+        async delete(userId, threadId) {
+            const attachmentPaths = await db
+                .select({ storageKey: attachments.storageKey })
+                .from(attachments)
+                .where(and(eq(attachments.threadId, threadId), eq(attachments.userId, userId)))
+                .execute()
+                .then((rows) => rows.map((row) => row.storageKey));
+
+            if (storage && attachmentPaths.length) {
+                await storage.delete(attachmentPaths);
+            }
+
+            // Avoid SQL Server error 547 from the NO ACTION attachments.message_id constraint.
+            await db.delete(attachments).where(eq(attachments.threadId, threadId)).execute();
+
+            await db
+                .delete(threads)
+                .where(and(eq(threads.id, threadId), eq(threads.userId, userId)))
+                .execute();
+        },
+
+        async touch(threadId) {
+            const result = await db
+                .update(threads)
+                .set({ updatedAt: new Date() })
+                .where(eq(threads.id, threadId))
+                .output()
+                .execute();
+
+            return result[0] as Thread;
+        },
+
+        async updateTitle(threadId, title) {
+            await db.update(threads).set({ title }).where(eq(threads.id, threadId)).execute();
+        },
+
+        async updateSession(threadId, session) {
+            await db.update(threads).set({ session }).where(eq(threads.id, threadId)).execute();
+        },
+
+        async updateContextMeta(threadId, meta: ThreadContextMeta) {
+            await db
+                .update(threads)
+                .set({ contextMeta: meta })
+                .where(eq(threads.id, threadId))
+                .execute();
+        },
+    } satisfies DatabaseAdapter["threads"];
+}