@m6d/cortex-server 1.8.0 → 2.0.0

package/src/lib/cc/format.ts

@@ -0,0 +1,96 @@
+import type { ResolveResponse, RuntimeAgentConfig } from "./types";
+
+type SharedShape = ResolveResponse["sharedShapes"][number];
+type ToolSignature = ResolveResponse["tools"][number];
+type ServiceCard = ResolveResponse["services"][number];
+type KnowledgeChunk = ResolveResponse["knowledge"][number];
+
+function substitutePromptVariables(template: string, variables: Record<string, string>) {
+    return template.replace(/\{\{(\w+)\}\}/g, function replaceVariable(match, name: string) {
+        return variables[name] ?? match;
+    });
+}
+
+/** Values for the published prompt's `{{variable}}` placeholders, read from session/request context. */
+export function buildPromptVariables(
+    promptVariables: RuntimeAgentConfig["promptVariables"],
+    sources: Record<string, unknown>,
+) {
+    const variables: Record<string, string> = {};
+    for (const name of promptVariables) {
+        const value = sources[name];
+        if (typeof value === "string") variables[name] = value;
+    }
+    return variables;
+}
+
+export function formatSharedShapes(shapes: SharedShape[]) {
+    return shapes.map((shape) => `${shape.ref}: ${shape.shape}`).join("\n");
+}
+
+export function formatToolSignatures(tools: ToolSignature[]) {
+    return tools.map((tool) => tool.signature).join("\n\n");
+}
+
+export function formatServiceCards(services: ServiceCard[]) {
+    return services.map((service) => service.card).join("\n\n");
+}
+
+export function formatKnowledgeChunks(chunks: KnowledgeChunk[]) {
+    return chunks.map(formatKnowledgeChunk).join("\n\n");
+}
+
+function formatKnowledgeChunk(chunk: KnowledgeChunk) {
+    const { citation } = chunk;
+    const source = [
+        citation.service,
+        citation.documentTitle,
+        citation.section,
+        citation.page === null ? null : `p. ${citation.page}`,
+    ]
+        .filter(Boolean)
+        .join(", ");
+    return `${chunk.text}\n[Source: ${source}]`;
+}
+
+export type CcPromptInput = {
+    config: RuntimeAgentConfig;
+    resolved: ResolveResponse | null;
+    variables: Record<string, string>;
+};
+
+/**
+ * Dumb concatenator by contract: `signature`, `card`, and `shape` arrive
+ * pre-rendered from Control Center and are injected verbatim — never
+ * re-rendered from structured fields.
+ */
+export function buildCcSection(cc: CcPromptInput) {
+    const parts: string[] = [];
+
+    const prompt = substitutePromptVariables(cc.config.systemPrompt, cc.variables).trim();
+    if (prompt) parts.push(prompt);
+
+    if (cc.config.catalogBlurb) {
+        parts.push(`## Capabilities\n${cc.config.catalogBlurb}`);
+    }
+
+    if (cc.resolved) {
+        if (cc.resolved.sharedShapes.length > 0) {
+            parts.push(`## Response Shapes\n${formatSharedShapes(cc.resolved.sharedShapes)}`);
+        }
+        if (cc.resolved.tools.length > 0) {
+            parts.push(
+                "## Dynamic Tools\nCall these from executeCode via the `tools` global, e.g. `await tools.name(input)`.\n\n" +
+                    formatToolSignatures(cc.resolved.tools),
+            );
+        }
+        if (cc.resolved.services.length > 0) {
+            parts.push(`## Services\n${formatServiceCards(cc.resolved.services)}`);
+        }
+        if (cc.resolved.knowledge.length > 0) {
+            parts.push(`## Knowledge\n${formatKnowledgeChunks(cc.resolved.knowledge)}`);
+        }
+    }
+
+    return parts.join("\n\n");
+}

package/src/lib/cc/registry.ts

@@ -0,0 +1,62 @@
+import type { ControlCenterClient } from "./client";
+import type { RuntimeAgentConfig } from "./types";
+
+export type CcToolBinding = {
+    toolId: string;
+    readOnly: boolean;
+};
+
+/**
+ * Turn-scoped and mutable: seeded from /resolve, extended by searchTools
+ * mid-turn so a tool discovered at step 3 is callable at step 4.
+ */
+export type CcToolRegistry = Map<string, CcToolBinding>;
+
+export function registerCcTools(
+    registry: CcToolRegistry,
+    tools: { name: string; toolId: string; readOnly: boolean }[],
+) {
+    for (const tool of tools) {
+        registry.set(tool.name, { toolId: tool.toolId, readOnly: tool.readOnly });
+    }
+}
+
+// Dynamic tools run inside the sandbox, so they never appear as message tool
+// parts — track invocations here to feed /resolve's hints.recentToolNames.
+// ponytail: in-memory per-thread recency, move to the DB if multi-instance matters
+const MAX_RECENT_TOOLS = 20;
+const MAX_TRACKED_THREADS = 1_000;
+const recentToolsByThread = new Map<string, string[]>();
+
+export function recordRecentCcTool(threadId: string, name: string) {
+    const recent = recentToolsByThread.get(threadId) ?? [];
+    const next = [name, ...recent.filter((n) => n !== name)].slice(0, MAX_RECENT_TOOLS);
+    recentToolsByThread.delete(threadId);
+    recentToolsByThread.set(threadId, next);
+
+    if (recentToolsByThread.size > MAX_TRACKED_THREADS) {
+        const oldest = recentToolsByThread.keys().next().value;
+        if (oldest !== undefined) recentToolsByThread.delete(oldest);
+    }
+}
+
+export function getRecentCcTools(threadId: string) {
+    return recentToolsByThread.get(threadId) ?? [];
+}
+
+/** Everything a CC-aware tool needs for one turn. */
+export type CcRuntime = {
+    client: ControlCenterClient;
+    agentId: string;
+    config: RuntimeAgentConfig;
+    registry: CcToolRegistry;
+    threadId: string;
+    turnKey: string;
+    userId: string;
+    locale: RuntimeAgentConfig["defaultLocale"];
+    endUserToken: string;
+    abortSignal?: AbortSignal;
+    getStepIndex: () => number;
+    nextCallIndex: (stepIndex: number) => number;
+    onToolProgress?: (toolName: string, toolCallId: string, status: "started" | "finished") => void;
+};

package/src/lib/cc/types.ts

@@ -0,0 +1,44 @@
+import z from "zod";
+import {
+    RUNTIME_ERROR_KINDS,
+    runtimeErrorSchema as strictRuntimeErrorSchema,
+} from "@cortex/contracts/runtime";
+
+export {
+    AGENT_SLUG_PATTERN,
+    executeResponseSchema,
+    resolveResponseSchema,
+    runtimeAgentConfigSchema,
+    searchKnowledgeResponseSchema,
+    searchServicesResponseSchema,
+    searchToolsResponseSchema,
+    type ExecuteRequest,
+    type ResolveRequest,
+    type ResolveResponse,
+    type RuntimeAgentConfig,
+    type SearchRequest,
+} from "@cortex/contracts/runtime";
+
+const knownRuntimeErrorKinds = new Set<string>(RUNTIME_ERROR_KINDS);
+
+/**
+ * The contract's error envelope, hardened for this consumer: a newer runtime may
+ * answer with an error kind this build has never heard of, which must degrade to a
+ * generic non-retryable `internal` rather than fail the parse.
+ */
+export const runtimeErrorSchema = z.preprocess(function normalizeUnknownErrorKind(value) {
+    if (typeof value !== "object" || value === null || !("error" in value)) return value;
+
+    const error = value.error;
+    if (typeof error !== "object" || error === null || !("kind" in error)) return value;
+    if (typeof error.kind === "string" && knownRuntimeErrorKinds.has(error.kind)) return value;
+
+    return {
+        ...value,
+        error: {
+            ...error,
+            kind: "internal",
+            retryable: false,
+        },
+    };
+}, strictRuntimeErrorSchema);

package/src/lib/config.ts

@@ -1,10 +1,13 @@
-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";
+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;
@@ -31,6 +34,11 @@ type RerankerConfig = {
     apiKey: string;
 };
 
+export type ControlCenterConfig = {
+    url: string;
+    apiKey: string;
+};
+
 export type KnowledgeConfig = {
     swagger?: { url: string };
     domains?: Record<string, DomainDef>;
@@ -66,10 +74,21 @@ export type ToolSetFactory<
 > = (context: ToolContext<TSession, TRequestContext>) => ToolSet;
 
 export type DatabaseConfig = {
-    type: "mssql";
+    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;
@@ -79,24 +98,42 @@ export type StorageConfig = {
     bucketName?: string;
 };
 
-export type CortexAgentDefinition<
-    TSession extends Record<string, unknown> = Record<string, unknown>,
-    TRequestContext extends Record<string, unknown> = Record<string, unknown>,
+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:
+    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;
-    };
+    backendFetch?: BackendFetchConfig;
     loadSessionData?: (token: string) => Promise<TSession>;
     resolveRequestContext?: (request: Request) => TRequestContext | Promise<TRequestContext>;
     onToolCall?: (toolCall: {
@@ -104,68 +141,62 @@ export type CortexAgentDefinition<
         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;
+    onStreamFinish?: (result: { messages: ChatMessage[]; isAborted: boolean }) => void;
 };
 
-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;
+/**
+ * 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>;
     };
-    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 = {
+/**
+ * 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;
+    storage?: StorageConfig;
+    redis?: RedisConfig;
     auth?: {
         jwksUri: string;
         issuer: string;
         tokenExtractor?: (req: Request) => string | null;
         cookieName?: string;
     };
-    model: ModelConfig;
-    fastModel?: ModelConfig;
-    embedding: EmbeddingConfig;
-    neo4j?: Neo4jConfig;
-    reranker?: RerankerConfig;
+    controlCenter?: ControlCenterConfig;
     context?: Partial<ContextConfig>;
     knowledge?: KnowledgeConfig;
-    agents: Record<string, CortexAgentDefinition>;
+    /**
+     * 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>;
 };
 
 /**
@@ -176,6 +207,6 @@ export type CortexConfig = {
 export function defineAgent<
     TSession extends Record<string, unknown> = Record<string, unknown>,
     TRequestContext extends Record<string, unknown> = Record<string, unknown>,
->(config: CortexAgentDefinition<TSession, TRequestContext>): CortexAgentDefinition {
+>(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

@@ -1,21 +1,56 @@
-import mssql from "mssql";
-import { drizzle } from "drizzle-orm/node-mssql";
-import { migrate } from "drizzle-orm/node-mssql/migrator";
 import { resolve } from "path";
+import type { DatabaseConfig } from "@/config";
 
-export async function runMigrations(connectionString: string) {
-    const pool = new mssql.ConnectionPool(connectionString);
-    await pool.connect();
+/**
+ * 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 {
-        const db = drizzle({ client: pool, casing: "snake_case" });
-        const migrationsFolder = resolve(import.meta.dir, "migrations");
-        console.log("[cortex-server] Running migrations from:", migrationsFolder);
-        await migrate(db, { migrationsFolder });
+        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/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]);