@m6d/cortex-server 1.6.0 → 1.8.0

package/src/lib/config.ts

@@ -0,0 +1,181 @@
+import type { Tool, ToolSet, UIMessage } from "ai";
+import type { DatabaseAdapter } from "./adapters/database";
+import type { StorageAdapter } from "./adapters/storage";
+import type { DomainDef } from "./graph/types.ts";
+import type { RequestInterceptorOptions } from "./ai/interceptors/request-interceptor.ts";
+import type { ContextConfig } from "./ai/context/types.ts";
+import type { Thread } from "./types.ts";
+
+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 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";
+    connectionString: string;
+};
+
+export type StorageConfig = {
+    endPoint: string;
+    port: number;
+    useSSL: boolean;
+    accessKey: string;
+    secretKey: string;
+    bucketName?: string;
+};
+
+export type CortexAgentDefinition<
+    TSession extends Record<string, unknown> = Record<string, unknown>,
+    TRequestContext extends Record<string, unknown> = Record<string, unknown>,
+> = {
+    systemPrompt:
+        | string
+        | ((context: PromptContext<TSession, TRequestContext>) => string | Promise<string>);
+    tools?: ToolSet | ToolSetFactory<TSession, TRequestContext>;
+    backendFetch?: {
+        baseUrl: string;
+        apiKey: string;
+        headers?: Record<string, string>;
+        transformRequestBody?: (
+            body: Record<string, unknown>,
+            context: { token: string },
+        ) => Promise<Record<string, unknown>>;
+        interceptor?: RequestInterceptorOptions;
+    };
+    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: UIMessage[]; isAborted: boolean }) => void;
+    model?: ModelConfig;
+    fastModel?: ModelConfig;
+    embedding?: EmbeddingConfig;
+    neo4j?: Neo4jConfig;
+    reranker?: RerankerConfig;
+    context?: Partial<ContextConfig>;
+    knowledge?: KnowledgeConfig | null;
+};
+
+export type ResolvedCortexAgentConfig = {
+    db: DatabaseAdapter;
+    storage: StorageAdapter;
+    model: ModelConfig;
+    fastModel?: ModelConfig;
+    embedding: EmbeddingConfig;
+    neo4j?: Neo4jConfig;
+    reranker?: RerankerConfig;
+    systemPrompt: string | ((context: PromptContext) => string | Promise<string>);
+    tools?: ToolSet | ToolSetFactory;
+    backendFetch?: {
+        baseUrl: string;
+        apiKey: string;
+        headers?: Record<string, string>;
+        transformRequestBody?: (
+            body: Record<string, unknown>,
+            context: { token: string },
+        ) => Promise<Record<string, unknown>>;
+        interceptor?: RequestInterceptorOptions;
+    };
+    loadSessionData?: (token: string) => Promise<Record<string, unknown>>;
+    resolveRequestContext?: (
+        request: Request,
+    ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    onToolCall?: (toolCall: {
+        toolName: string;
+        toolCallId: string;
+        args: Record<string, unknown>;
+    }) => void;
+    onStreamFinish?: (result: { messages: UIMessage[]; isAborted: boolean }) => void;
+    context: ContextConfig;
+    knowledge?: KnowledgeConfig;
+};
+
+export type CortexConfig = {
+    port?: number;
+    database: DatabaseConfig;
+    storage: StorageConfig;
+    auth?: {
+        jwksUri: string;
+        issuer: string;
+        tokenExtractor?: (req: Request) => string | null;
+        cookieName?: string;
+    };
+    model: ModelConfig;
+    fastModel?: ModelConfig;
+    embedding: EmbeddingConfig;
+    neo4j?: Neo4jConfig;
+    reranker?: RerankerConfig;
+    context?: Partial<ContextConfig>;
+    knowledge?: KnowledgeConfig;
+    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>): CortexAgentDefinition {
+    return config as CortexAgentDefinition;
+}

package/src/{db/migrations/20260309012148_cloudy_maria_hill → lib/db/migrations/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/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/{db → lib/db}/schema.ts

@@ -1,7 +1,7 @@
 import type { ToolUIPart, UIMessage } from "ai";
 import { sql } from "drizzle-orm";
-import { customType, datetime2, index, mssqlSchema, nvarchar } from "drizzle-orm/mssql-core";
-import type { MessageMetadata } from "src/types";
+import { customType, datetime2, index, int, mssqlSchema, nvarchar } from "drizzle-orm/mssql-core";
+import type { MessageMetadata, TokenUsage } from "../types.ts";
 import type { ThreadContextMeta } from "../ai/context/types.ts";
 
 const uniqueIdentifier = customType<{ data: string }>({
@@ -50,6 +50,19 @@ export const messages = aiSchema.table("messages", {
     ...auditColumns,
 });
 
+export const llmRequests = aiSchema.table("llm_requests", {
+    id: uniqueIdentifier()
+        .default(sql`NEWID()`)
+        .primaryKey(),
+    messageId: nvarchar({ length: 128 })
+        .references(() => messages.id, { onDelete: "cascade" })
+        .notNull(),
+    stepNumber: int().notNull(),
+    prompt: nvarchar({ length: "max" }).notNull(),
+    output: nvarchar({ length: "max" }),
+    tokenUsage: nvarchar({ length: "max", mode: "json" }).$type<TokenUsage>(),
+});
+
 export const capturedFiles = aiSchema.table(
     "captured_files",
     {

package/src/{factory.ts → lib/factory.ts}

@@ -84,6 +84,7 @@ export function createCortex(config: CortexConfig) {
                     db,
                     storage,
                     model: agentDef.model ?? config.model,
+                    fastModel: agentDef.fastModel ?? config.fastModel,
                     embedding: agentDef.embedding ?? config.embedding,
                     neo4j: agentDef.neo4j ?? config.neo4j,
                     reranker: agentDef.reranker ?? config.reranker,

package/src/{index.ts → lib/index.ts}

@@ -6,7 +6,10 @@ export type {
     DatabaseConfig,
     StorageConfig,
     PromptContext,
+    ToolContext,
+    ToolSetFactory,
 } from "./config";
+export { defineAgent } from "./config";
 
 export type { ContextConfig, ThreadContextMeta } from "./ai/context/types";
 
@@ -27,7 +30,6 @@ export { createRequestInterceptor } from "./ai/interceptors/request-interceptor"
 // Tools (consumers may register custom tools or use built-in ones)
 export { captureFilesTool } from "./ai/tools/capture-files.tool";
 export { createQueryGraphTool } from "./ai/tools/query-graph.tool";
-export { createCallEndpointTool } from "./ai/tools/call-endpoint.tool";
 export { createExecuteCodeTool } from "./ai/tools/execute-code.tool";
 
 // Graph (consumers may use independently)

package/src/{routes → lib/routes}/files.ts

@@ -86,12 +86,19 @@ export function createFileRoutes() {
             );
 
             // Store file bytes
-            await Promise.all(
+            const uploadResults = await Promise.all(
                 result.map(async (r, i) => {
-                    await config.storage.put(`captured_files/${r.uploadId}`, files[i]!.file.bytes);
+                    return await config.storage.put(
+                        `captured_files/${r.uploadId}`,
+                        files[i]!.file.bytes,
+                    );
                 }),
             );
 
+            if (uploadResults.some((x) => !x)) {
+                throw new HTTPException(400, { message: "Some or all files failed to upload" });
+            }
+
             return c.json(result);
         },
     );

package/src/{routes → lib/routes}/threads.ts

@@ -80,10 +80,17 @@ export function createThreadRoutes() {
         return c.json(messages);
     });
 
+    app.get("/messages/:messageId/llm-requests", requireAuth, async function (c) {
+        const config = c.get("agentConfig");
+        const messageId = c.req.param("messageId");
+        const requests = await config.db.llmRequests.listByMessageId(messageId);
+        return c.json(requests);
+    });
+
     app.post(
         "/threads/:threadId/session",
         requireAuth,
-        zValidator("json", z.object({ session: z.record(z.unknown()) })),
+        zValidator("json", z.object({ session: z.record(z.string(), z.unknown()) })),
         async function (c) {
             const config = c.get("agentConfig");
             const agentId = c.get("agentId");

package/src/{types.ts → lib/types.ts}

@@ -1,4 +1,3 @@
-import type { ToolUIPart, UIMessage } from "ai";
 import type { ResolvedCortexAgentConfig } from "./config";
 import type { InferSelectModel } from "drizzle-orm";
 import type { messages, threads } from "./db/schema";
@@ -15,24 +14,26 @@ export type ThreadSummary = {
     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?: {
-        input: {
-            noCache: number;
-            cacheRead: number;
-            cacheWrite: number;
-            total: number;
-        };
-        output: {
-            reasoning: number;
-            text: number;
-            total: number;
-        };
-        total: number;
-    };
+    tokenUsage?: TokenUsage;
 };
 
 export type CapturedFileInput = {

package/src/sample/db/client.ts

@@ -0,0 +1,9 @@
+import { Database } from "bun:sqlite";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { resolve } from "path";
+import * as schema from "./schema.ts";
+
+const url = process.env["SAMPLE_DB_URL"] ?? resolve(import.meta.dir, "sample.db");
+const client = new Database(url);
+
+export const db = drizzle({ client, schema, casing: "snake_case" });

package/src/sample/db/migrations/20260411023125_rich_purple_man/migration.sql

@@ -0,0 +1,5 @@
+CREATE TABLE `official_statements` (
+	`id` text PRIMARY KEY,
+	`thread_id` text NOT NULL,
+	`data` text NOT NULL
+);

package/src/sample/db/migrations/20260411023125_rich_purple_man/snapshot.json

@@ -0,0 +1,50 @@
+{
+    "version": "7",
+    "dialect": "sqlite",
+    "id": "d8da372b-c2d6-4299-a062-58550458a12d",
+    "prevIds": ["00000000-0000-0000-0000-000000000000"],
+    "ddl": [
+        {
+            "name": "official_statements",
+            "entityType": "tables"
+        },
+        {
+            "type": "text",
+            "notNull": false,
+            "autoincrement": false,
+            "default": null,
+            "generated": null,
+            "name": "id",
+            "entityType": "columns",
+            "table": "official_statements"
+        },
+        {
+            "type": "text",
+            "notNull": true,
+            "autoincrement": false,
+            "default": null,
+            "generated": null,
+            "name": "thread_id",
+            "entityType": "columns",
+            "table": "official_statements"
+        },
+        {
+            "type": "text",
+            "notNull": true,
+            "autoincrement": false,
+            "default": null,
+            "generated": null,
+            "name": "data",
+            "entityType": "columns",
+            "table": "official_statements"
+        },
+        {
+            "columns": ["id"],
+            "nameExplicit": false,
+            "name": "official_statements_pk",
+            "table": "official_statements",
+            "entityType": "pks"
+        }
+    ],
+    "renames": []
+}

package/src/sample/db/schema.ts

@@ -0,0 +1,10 @@
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+import type { OfficialStatementData } from "../official-statements/types.ts";
+
+export const officialStatements = sqliteTable("official_statements", {
+    id: text()
+        .primaryKey()
+        .$defaultFn(() => crypto.randomUUID()),
+    threadId: text().notNull(),
+    data: text({ mode: "json" }).$type<OfficialStatementData>().notNull(),
+});

package/src/sample/domains/account/concepts/session.concept.ts

@@ -0,0 +1,17 @@
+import { defineConcept } from "@m6d/cortex-server";
+
+export const sessionConcept = defineConcept({
+    name: "Session",
+    description:
+        "An authenticated login session for the current user, including device, IP address, last activity, and whether it is the active session on the current device.",
+    aliases: [
+        "session",
+        "login session",
+        "active sessions",
+        "my sessions",
+        "devices signed in",
+        "الجلسات",
+        "جلساتي",
+        "الأجهزة المسجل عليها الدخول",
+    ],
+});

package/src/sample/domains/account/endpoints/listCurrentSessions.endpoint.ts

@@ -0,0 +1,31 @@
+import { defineEndpoint } from "@m6d/cortex-server";
+import { sessionConcept } from "../concepts/session.concept";
+
+export const listCurrentSessionsEndpoint = defineEndpoint({
+    name: "List current user sessions",
+    path: "/auth/users/current/sessions",
+    method: "GET",
+    description:
+        "Returns all active sessions for the currently authenticated user. Useful for reviewing signed-in devices and recent session activity.",
+    queries: [sessionConcept],
+    returns: [{ concept: sessionConcept }],
+
+    // @auto-generated-start
+    autoGenerated: {
+        params: [] as const,
+        body: [] as const,
+        response: [
+            { name: "sessionId", required: false, type: "uuid" },
+            { name: "ipAddress", required: false, type: "string" },
+            { name: "deviceType", required: false, type: "string" },
+            { name: "userAgent", required: false, type: "string" },
+            { name: "createdTime", required: false, type: "datetime" },
+            { name: "lastUsedTime", required: false, type: "datetime" },
+            { name: "isCurrent", required: false, type: "boolean" },
+        ] as const,
+        successStatus: 200,
+        errorStatuses: [],
+        responseKind: "array",
+    } as const,
+    // @auto-generated-end
+});

package/src/sample/domains/account/endpoints/revokeAllOtherSessions.endpoint.ts

@@ -0,0 +1,22 @@
+import { defineEndpoint } from "@m6d/cortex-server";
+import { sessionConcept } from "../concepts/session.concept";
+
+export const revokeAllOtherSessionsEndpoint = defineEndpoint({
+    name: "Revoke all other current user sessions",
+    path: "/auth/users/current/sessions",
+    method: "DELETE",
+    description:
+        "Revokes every active session for the current user except the current session. Useful for signing out from all other devices at once.",
+    mutates: [sessionConcept],
+
+    // @auto-generated-start
+    autoGenerated: {
+        params: [] as const,
+        body: [] as const,
+        response: [] as const,
+        successStatus: 204,
+        errorStatuses: [],
+        responseKind: "none",
+    } as const,
+    // @auto-generated-end
+});