@m6d/cortex-server 1.7.0 → 2.0.0

package/src/lib/config.ts

@@ -0,0 +1,212 @@
+import type { AnyServerTool } from "@tanstack/ai";
+import type { DatabaseAdapter } from "./adapters/database/index";
+import type { StorageAdapter } from "./adapters/storage/index";
+import type { DomainDef } from "@cortex/contracts/graph";
+import type { RequestInterceptorOptions } from "./ai/interceptors/request-interceptor";
+import type { ContextConfig } from "./ai/context/types";
+import type { ChatMessage, Thread } from "./types";
+
+/** An agent's tools, as `chat()` takes them. */
+export type ToolSet = ReadonlyArray<AnyServerTool>;
+
+type ModelConfig = {
+    baseURL: string;
+    apiKey: string;
+    modelName: string;
+    providerName?: string;
+};
+
+type EmbeddingConfig = {
+    baseURL: string;
+    apiKey: string;
+    modelName: string;
+    dimension: number;
+};
+
+type Neo4jConfig = {
+    url: string;
+    user: string;
+    password: string;
+};
+
+type RerankerConfig = {
+    url: string;
+    apiKey: string;
+};
+
+export type ControlCenterConfig = {
+    url: string;
+    apiKey: string;
+};
+
+export type KnowledgeConfig = {
+    swagger?: { url: string };
+    domains?: Record<string, DomainDef>;
+};
+
+export type PromptContext<
+    TSession extends Record<string, unknown> = Record<string, unknown>,
+    TRequestContext extends Record<string, unknown> = Record<string, unknown>,
+> = {
+    session: TSession | null;
+    requestContext: TRequestContext;
+};
+
+/**
+ * Per-request context handed to a tools factory. Allows tool implementations to
+ * close over the active thread, user, session, and request-level context without
+ * reaching for globals or AsyncLocalStorage.
+ */
+export type ToolContext<
+    TSession extends Record<string, unknown> = Record<string, unknown>,
+    TRequestContext extends Record<string, unknown> = Record<string, unknown>,
+> = {
+    thread: Thread;
+    userId: string;
+    token: string;
+    session: TSession | null;
+    requestContext: TRequestContext;
+};
+
+export type ToolSetFactory<
+    TSession extends Record<string, unknown> = Record<string, unknown>,
+    TRequestContext extends Record<string, unknown> = Record<string, unknown>,
+> = (context: ToolContext<TSession, TRequestContext>) => ToolSet;
+
+export type DatabaseConfig = {
+    type: "mssql" | "postgres";
+    connectionString: string;
+};
+
+/**
+ * Optional. With Redis, live runs survive a producer restart and reach every
+ * instance: the chunk log, the thread→run claims, and abort fan-out all move
+ * there. Without it, an in-memory fallback covers a single process.
+ */
+export type RedisConfig = {
+    url: string;
+    /** How long a finished run's stream log stays replayable. Defaults to 24 h. */
+    streamTtlSeconds?: number;
+};
+
+export type StorageConfig = {
+    endPoint: string;
+    port: number;
+    useSSL: boolean;
+    accessKey: string;
+    secretKey: string;
+    bucketName?: string;
+};
+
+type BackendFetchConfig = {
+    baseUrl: string;
+    apiKey: string;
+    headers?: Record<string, string>;
+    transformRequestBody?: (
+        body: Record<string, unknown>,
+        context: { token: string },
+    ) => Promise<Record<string, unknown>>;
+    interceptor?: RequestInterceptorOptions;
+};
+
+/** Model and knowledge-graph providers. Declared once at server level; an agent may override any of them. */
+type ProviderConfig = {
+    model: ModelConfig;
+    fastModel?: ModelConfig;
+    vision?: ModelConfig;
+    embedding?: EmbeddingConfig;
+    neo4j?: Neo4jConfig;
+    reranker?: RerankerConfig;
+};
+
+/**
+ * What an agent *does*, independent of where its providers came from. Shared
+ * verbatim by the authored definition and its resolved form — the two differ
+ * only in how providers and opt-outs are expressed, so everything else lives
+ * here and cannot drift between them.
+ */
+type AgentBehavior<
+    TSession extends Record<string, unknown>,
+    TRequestContext extends Record<string, unknown>,
+> = {
+    systemPrompt?:
+        | string
+        | ((context: PromptContext<TSession, TRequestContext>) => string | Promise<string>);
+    tools?: ToolSet | ToolSetFactory<TSession, TRequestContext>;
+    backendFetch?: BackendFetchConfig;
+    loadSessionData?: (token: string) => Promise<TSession>;
+    resolveRequestContext?: (request: Request) => TRequestContext | Promise<TRequestContext>;
+    onToolCall?: (toolCall: {
+        toolName: string;
+        toolCallId: string;
+        args: Record<string, unknown>;
+    }) => void;
+    onStreamFinish?: (result: { messages: ChatMessage[]; isAborted: boolean }) => void;
+};
+
+/**
+ * An agent as authored. Providers are optional because an unset one inherits
+ * from server level; `null` on knowledge means "opt out entirely" rather than
+ * "inherit". The Control Center is server-level only: which agents it backs is
+ * decided by publishing them there, not per entry here.
+ */
+export type CortexAgentDefinition<
+    TSession extends Record<string, unknown> = Record<string, unknown>,
+    TRequestContext extends Record<string, unknown> = Record<string, unknown>,
+> = AgentBehavior<TSession, TRequestContext> &
+    Partial<ProviderConfig> & {
+        knowledge?: KnowledgeConfig | null;
+        context?: Partial<ContextConfig>;
+    };
+
+/**
+ * An agent after the factory has merged it with server-level config. Every
+ * inherit-or-opt-out decision is already resolved, so nothing here is nullable
+ * and `model`/`context` are guaranteed present.
+ */
+export type ResolvedCortexAgentConfig = AgentBehavior<
+    Record<string, unknown>,
+    Record<string, unknown>
+> &
+    ProviderConfig & {
+        agentId: string;
+        db: DatabaseAdapter;
+        storage?: StorageAdapter;
+        controlCenter?: ControlCenterConfig;
+        knowledge?: KnowledgeConfig;
+        context: ContextConfig;
+    };
+
+export type CortexConfig = ProviderConfig & {
+    port?: number;
+    database: DatabaseConfig;
+    storage?: StorageConfig;
+    redis?: RedisConfig;
+    auth?: {
+        jwksUri: string;
+        issuer: string;
+        tokenExtractor?: (req: Request) => string | null;
+        cookieName?: string;
+    };
+    controlCenter?: ControlCenterConfig;
+    context?: Partial<ContextConfig>;
+    knowledge?: KnowledgeConfig;
+    /**
+     * Locally-defined agents. With `controlCenter` set, agents published there
+     * are served automatically and need no entry here; an entry is only needed
+     * for local behavior (tools, backendFetch, provider overrides).
+     */
+    agents?: Record<string, CortexAgentDefinition>;
+};
+
+/**
+ * Helper to define an agent with full type inference for `systemPrompt` context.
+ * The `context.session` type is inferred from `loadSessionData`'s return type,
+ * and `context.requestContext` is inferred from `resolveRequestContext`'s return type.
+ */
+export function defineAgent<
+    TSession extends Record<string, unknown> = Record<string, unknown>,
+    TRequestContext extends Record<string, unknown> = Record<string, unknown>,
+>(config: CortexAgentDefinition<TSession, TRequestContext>) {
+    return config as CortexAgentDefinition;
+}

package/src/lib/db/drizzle.config.mssql.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "drizzle-kit";
+
+// Paths are relative to the package root, which is where drizzle-kit is invoked from.
+export default defineConfig({
+    schema: "./src/lib/db/schema.mssql.ts",
+    out: "./src/lib/db/migrations/mssql",
+    dialect: "mssql",
+    casing: "snake_case",
+});

package/src/lib/db/drizzle.config.pg.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "drizzle-kit";
+
+// Paths are relative to the package root, which is where drizzle-kit is invoked from.
+export default defineConfig({
+    schema: "./src/lib/db/schema.pg.ts",
+    out: "./src/lib/db/migrations/pg",
+    dialect: "postgresql",
+    casing: "snake_case",
+});

package/src/lib/db/migrate.ts

@@ -0,0 +1,56 @@
+import { resolve } from "path";
+import type { DatabaseConfig } from "@/config";
+
+/**
+ * Each dialect keeps its own migration history — Postgres starts from a
+ * squashed initial migration rather than replaying MSSQL's. The driver imports
+ * are lazy so a server only loads the one it was configured for.
+ */
+export async function runMigrations(database: DatabaseConfig) {
+    const migrationsFolder = resolve(import.meta.dir, "migrations", folderFor(database.type));
+    console.log("[cortex-server] Running migrations from:", migrationsFolder);
+
+    try {
+        if (database.type === "postgres") {
+            await migratePostgres(database.connectionString, migrationsFolder);
+        } else {
+            await migrateMssql(database.connectionString, migrationsFolder);
+        }
+        console.log("[cortex-server] Migrations complete");
+    } catch (e) {
+        console.log(e);
+    }
+}
+
+function folderFor(type: DatabaseConfig["type"]) {
+    return type === "postgres" ? "pg" : "mssql";
+}
+
+async function migrateMssql(connectionString: string, migrationsFolder: string) {
+    const { default: mssql } = await import("mssql");
+    const { drizzle } = await import("drizzle-orm/node-mssql");
+    const { migrate } = await import("drizzle-orm/node-mssql/migrator");
+
+    const pool = new mssql.ConnectionPool(connectionString);
+    await pool.connect();
+
+    try {
+        await migrate(drizzle({ client: pool, casing: "snake_case" }), { migrationsFolder });
+    } finally {
+        await pool.close();
+    }
+}
+
+async function migratePostgres(connectionString: string, migrationsFolder: string) {
+    const { default: pg } = await import("pg");
+    const { drizzle } = await import("drizzle-orm/node-postgres");
+    const { migrate } = await import("drizzle-orm/node-postgres/migrator");
+
+    const pool = new pg.Pool({ connectionString });
+
+    try {
+        await migrate(drizzle({ client: pool, casing: "snake_case" }), { migrationsFolder });
+    } finally {
+        await pool.end();
+    }
+}

package/src/{db/migrations/20260309012148_cloudy_maria_hill → lib/db/migrations/mssql/20260326231647_nice_speedball}/migration.sql

@@ -10,6 +10,16 @@ CREATE TABLE [ai].[captured_files] (
 	CONSTRAINT [captured_files_pkey] PRIMARY KEY([id])
 );
 --> statement-breakpoint
+CREATE TABLE [ai].[llm_requests] (
+	[id] UNIQUEIDENTIFIER CONSTRAINT [llm_requests_id_default] DEFAULT (NEWID()),
+	[message_id] nvarchar(128) NOT NULL,
+	[step_number] int NOT NULL,
+	[prompt] nvarchar(max) NOT NULL,
+	[output] nvarchar(max),
+	[token_usage] nvarchar(max),
+	CONSTRAINT [llm_requests_pkey] PRIMARY KEY([id])
+);
+--> statement-breakpoint
 CREATE TABLE [ai].[messages] (
 	[id] nvarchar(128),
 	[thread_id] UNIQUEIDENTIFIER NOT NULL,
@@ -27,10 +37,12 @@ CREATE TABLE [ai].[threads] (
 	[agent_id] nvarchar(128) NOT NULL CONSTRAINT [threads_agent_id_default] DEFAULT ('default'),
 	[title] nvarchar(256),
 	[session] nvarchar(max),
+	[context_meta] nvarchar(max),
 	[created_at] datetime2 NOT NULL,
 	[updated_at] datetime2 NOT NULL,
 	CONSTRAINT [threads_pkey] PRIMARY KEY([id])
 );
 --> statement-breakpoint
 ALTER TABLE [ai].[captured_files] ADD CONSTRAINT [captured_files_message_id_messages_id_fk] FOREIGN KEY ([message_id]) REFERENCES [ai].[messages]([id]) ON DELETE CASCADE;--> statement-breakpoint
+ALTER TABLE [ai].[llm_requests] ADD CONSTRAINT [llm_requests_message_id_messages_id_fk] FOREIGN KEY ([message_id]) REFERENCES [ai].[messages]([id]) ON DELETE CASCADE;--> statement-breakpoint
 ALTER TABLE [ai].[messages] ADD CONSTRAINT [messages_thread_id_threads_id_fk] FOREIGN KEY ([thread_id]) REFERENCES [ai].[threads]([id]) ON DELETE CASCADE;

package/src/{db/migrations/20260309012148_cloudy_maria_hill → lib/db/migrations/mssql/20260326231647_nice_speedball}/snapshot.json

@@ -1,7 +1,7 @@
 {
     "version": "2",
     "dialect": "mssql",
-    "id": "d92d3e1a-9613-4d7e-a224-de2dd01b2718",
+    "id": "407c2a91-87ca-412e-92c4-1c4d0d3c71b0",
     "prevIds": ["00000000-0000-0000-0000-000000000000"],
     "ddl": [
         {
@@ -13,6 +13,11 @@
             "entityType": "tables",
             "schema": "ai"
         },
+        {
+            "name": "llm_requests",
+            "entityType": "tables",
+            "schema": "ai"
+        },
         {
             "name": "messages",
             "entityType": "tables",
@@ -83,6 +88,66 @@
             "entityType": "columns",
             "table": "captured_files"
         },
+        {
+            "type": "UNIQUEIDENTIFIER",
+            "notNull": true,
+            "generated": null,
+            "identity": null,
+            "name": "id",
+            "schema": "ai",
+            "entityType": "columns",
+            "table": "llm_requests"
+        },
+        {
+            "type": "nvarchar(128)",
+            "notNull": true,
+            "generated": null,
+            "identity": null,
+            "name": "message_id",
+            "schema": "ai",
+            "entityType": "columns",
+            "table": "llm_requests"
+        },
+        {
+            "type": "int",
+            "notNull": true,
+            "generated": null,
+            "identity": null,
+            "name": "step_number",
+            "schema": "ai",
+            "entityType": "columns",
+            "table": "llm_requests"
+        },
+        {
+            "type": "nvarchar(max)",
+            "notNull": true,
+            "generated": null,
+            "identity": null,
+            "name": "prompt",
+            "schema": "ai",
+            "entityType": "columns",
+            "table": "llm_requests"
+        },
+        {
+            "type": "nvarchar(max)",
+            "notNull": false,
+            "generated": null,
+            "identity": null,
+            "name": "output",
+            "schema": "ai",
+            "entityType": "columns",
+            "table": "llm_requests"
+        },
+        {
+            "type": "nvarchar(max)",
+            "notNull": false,
+            "generated": null,
+            "identity": null,
+            "name": "token_usage",
+            "schema": "ai",
+            "entityType": "columns",
+            "table": "llm_requests"
+        },
         {
             "type": "nvarchar(128)",
             "notNull": true,
@@ -203,6 +268,16 @@
             "entityType": "columns",
             "table": "threads"
         },
+        {
+            "type": "nvarchar(max)",
+            "notNull": false,
+            "generated": null,
+            "identity": null,
+            "name": "context_meta",
+            "schema": "ai",
+            "entityType": "columns",
+            "table": "threads"
+        },
         {
             "type": "datetime2",
             "notNull": true,
@@ -236,6 +311,19 @@
             "table": "captured_files",
             "schema": "ai"
         },
+        {
+            "columns": ["message_id"],
+            "nameExplicit": false,
+            "schemaTo": "ai",
+            "tableTo": "messages",
+            "columnsTo": ["id"],
+            "onUpdate": "NO ACTION",
+            "onDelete": "CASCADE",
+            "name": "llm_requests_message_id_messages_id_fk",
+            "entityType": "fks",
+            "table": "llm_requests",
+            "schema": "ai"
+        },
         {
             "columns": ["thread_id"],
             "nameExplicit": false,
@@ -257,6 +345,14 @@
             "schema": "ai",
             "entityType": "pks"
         },
+        {
+            "nameExplicit": false,
+            "columns": ["id"],
+            "name": "llm_requests_pkey",
+            "table": "llm_requests",
+            "schema": "ai",
+            "entityType": "pks"
+        },
         {
             "nameExplicit": false,
             "columns": ["id"],
@@ -282,6 +378,15 @@
             "schema": "ai",
             "table": "captured_files"
         },
+        {
+            "column": "id",
+            "nameExplicit": false,
+            "default": "(NEWID())",
+            "name": "llm_requests_id_default",
+            "entityType": "defaults",
+            "schema": "ai",
+            "table": "llm_requests"
+        },
         {
             "column": "id",
             "nameExplicit": false,

package/src/lib/db/migrations/mssql/20260729092726_talented_wilson_fisk/migration.sql

@@ -0,0 +1,20 @@
+CREATE TABLE [ai].[attachments] (
+	[id] UNIQUEIDENTIFIER CONSTRAINT [attachments_id_default] DEFAULT (NEWID()),
+	[thread_id] UNIQUEIDENTIFIER NOT NULL,
+	[user_id] UNIQUEIDENTIFIER NOT NULL,
+	[message_id] nvarchar(128),
+	[filename] nvarchar(2048) NOT NULL,
+	[content_type] nvarchar(256) NOT NULL,
+	[size_bytes] int NOT NULL,
+	[storage_key] nvarchar(512) NOT NULL,
+	[status] nvarchar(16) NOT NULL,
+	[description] nvarchar(max),
+	[created_at] datetime2 NOT NULL,
+	[updated_at] datetime2 NOT NULL,
+	CONSTRAINT [attachments_pkey] PRIMARY KEY([id])
+);
+--> statement-breakpoint
+DROP TABLE [ai].[captured_files];--> statement-breakpoint
+ALTER TABLE [ai].[attachments] ADD CONSTRAINT [attachments_thread_id_threads_id_fk] FOREIGN KEY ([thread_id]) REFERENCES [ai].[threads]([id]) ON DELETE CASCADE;--> statement-breakpoint
+ALTER TABLE [ai].[attachments] ADD CONSTRAINT [attachments_message_id_messages_id_fk] FOREIGN KEY ([message_id]) REFERENCES [ai].[messages]([id]);--> statement-breakpoint
+CREATE INDEX [attachments_thread_id_index] ON [ai].[attachments] ([thread_id]);