@m6d/cortex-server 1.7.0 → 2.0.0

package/dist/src/lib/cc/client.d.ts

@@ -0,0 +1,183 @@
+import type { ControlCenterConfig } from "../config";
+import type { ExecuteRequest, ResolveRequest, SearchRequest } from "./types";
+type ControlCenterFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type ExecuteOptions = {
+    readOnly: boolean;
+    endUserToken?: string;
+    threadId: string;
+    turnKey: string;
+    stepIndex: number;
+    callIndex: number;
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+};
+export declare class ControlCenterClient {
+    readonly url: string;
+    readonly cacheKey: string;
+    private readonly apiKey;
+    private readonly fetcher;
+    constructor(config: ControlCenterConfig, fetcher?: ControlCenterFetch);
+    getConfig(agentId: string, etag?: string, abortSignal?: AbortSignal): Promise<{
+        readonly status: "not-modified";
+        readonly config?: undefined;
+        readonly etag?: undefined;
+    } | {
+        readonly status: "not-found";
+        readonly config?: undefined;
+        readonly etag?: undefined;
+    } | {
+        readonly status: "modified";
+        readonly config: {
+            agentId: string;
+            systemPrompt: string;
+            promptVariables: ("userName" | "channel" | "locale")[];
+            catalogBlurb: string;
+            defaultLocale: "en" | "ar";
+            metaTools: {
+                searchKnowledge: boolean;
+                searchTools: boolean;
+                searchServices: boolean;
+            };
+            limits: {
+                resolveTokenBudget: number;
+                executeTimeoutMs: number;
+                maxResponseBytes: number;
+            };
+            catalogVersion: string;
+            publishedAt: string;
+        };
+        readonly etag: string | null;
+    } | null>;
+    resolve(agentId: string, request: ResolveRequest, abortSignal?: AbortSignal): Promise<{
+        resolveId: string;
+        catalogVersion: string;
+        locale: "en" | "ar";
+        knowledge: {
+            chunkId: string;
+            text: string;
+            score: number;
+            citation: {
+                documentId: string;
+                documentTitle: string;
+                page: number | null;
+                section: string | null;
+                uri: string | null;
+                service: string | null;
+            };
+        }[];
+        tools: {
+            toolId: string;
+            name: string;
+            version: number;
+            readOnly: boolean;
+            tags: string[];
+            signature: string;
+            score: number | null;
+            pinned: boolean;
+        }[];
+        services: {
+            serviceId: string;
+            key: string;
+            name: string;
+            card: string;
+            score: number;
+        }[];
+        sharedShapes: {
+            ref: string;
+            shape: string;
+        }[];
+        budget: {
+            requested: number;
+            used: number;
+            truncated: boolean;
+        };
+    } | null>;
+    searchTools(agentId: string, request: SearchRequest, abortSignal?: AbortSignal): Promise<{
+        catalogVersion: string;
+        tools: {
+            toolId: string;
+            name: string;
+            version: number;
+            readOnly: boolean;
+            tags: string[];
+            signature: string;
+            score: number | null;
+            pinned: boolean;
+        }[];
+        sharedShapes: {
+            ref: string;
+            shape: string;
+        }[];
+    } | null>;
+    searchServices(agentId: string, request: SearchRequest, abortSignal?: AbortSignal): Promise<{
+        catalogVersion: string;
+        services: {
+            serviceId: string;
+            key: string;
+            name: string;
+            card: string;
+            score: number;
+        }[];
+        tools: {
+            toolId: string;
+            name: string;
+            version: number;
+            readOnly: boolean;
+            tags: string[];
+            signature: string;
+            score: number | null;
+            pinned: boolean;
+        }[];
+        sharedShapes: {
+            ref: string;
+            shape: string;
+        }[];
+    } | null>;
+    searchKnowledge(agentId: string, request: SearchRequest, abortSignal?: AbortSignal): Promise<{
+        catalogVersion: string;
+        knowledge: {
+            chunkId: string;
+            text: string;
+            score: number;
+            citation: {
+                documentId: string;
+                documentTitle: string;
+                page: number | null;
+                section: string | null;
+                uri: string | null;
+                service: string | null;
+            };
+        }[];
+    } | null>;
+    execute(agentId: string, toolId: string, request: ExecuteRequest, options: ExecuteOptions): Promise<{
+        error: {
+            kind: "timeout" | "upstream_4xx" | "upstream_5xx" | "schema_mismatch" | "rate_limited" | "not_found" | "unauthorized" | "invalid_request" | "egress_blocked" | "internal";
+            detail: string;
+            retryable: boolean;
+            retryAfterSeconds?: number | undefined;
+            upstreamStatus?: number | undefined;
+        };
+    } | {
+        toolId: string;
+        name: string;
+        version: number;
+        output: unknown;
+        meta: {
+            upstreamStatus: number;
+            durationMs: number;
+            replayed: boolean;
+            truncated: boolean;
+            truncatedPaths: string[];
+            drift: {
+                path: string;
+                kind: "missing" | "unexpected" | "type_mismatch";
+            }[];
+        };
+    } | null>;
+    private agentPath;
+    private post;
+    private postResponse;
+    private request;
+    private parse;
+}
+export {};

package/dist/src/lib/cc/config-cache.d.ts

@@ -0,0 +1,20 @@
+import type { ControlCenterClient } from "./client";
+export declare function getControlCenterConfig(cc: ControlCenterClient, agentId: string, abortSignal?: AbortSignal): Promise<{
+    agentId: string;
+    systemPrompt: string;
+    promptVariables: ("userName" | "channel" | "locale")[];
+    catalogBlurb: string;
+    defaultLocale: "en" | "ar";
+    metaTools: {
+        searchKnowledge: boolean;
+        searchTools: boolean;
+        searchServices: boolean;
+    };
+    limits: {
+        resolveTokenBudget: number;
+        executeTimeoutMs: number;
+        maxResponseBytes: number;
+    };
+    catalogVersion: string;
+    publishedAt: string;
+} | null>;

package/dist/src/lib/cc/format.d.ts

@@ -0,0 +1,23 @@
+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];
+/** Values for the published prompt's `{{variable}}` placeholders, read from session/request context. */
+export declare function buildPromptVariables(promptVariables: RuntimeAgentConfig["promptVariables"], sources: Record<string, unknown>): Record<string, string>;
+export declare function formatSharedShapes(shapes: SharedShape[]): string;
+export declare function formatToolSignatures(tools: ToolSignature[]): string;
+export declare function formatServiceCards(services: ServiceCard[]): string;
+export declare function formatKnowledgeChunks(chunks: KnowledgeChunk[]): string;
+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 declare function buildCcSection(cc: CcPromptInput): string;
+export {};

package/dist/src/lib/cc/registry.d.ts

@@ -0,0 +1,34 @@
+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 declare function registerCcTools(registry: CcToolRegistry, tools: {
+    name: string;
+    toolId: string;
+    readOnly: boolean;
+}[]): void;
+export declare function recordRecentCcTool(threadId: string, name: string): void;
+export declare function getRecentCcTools(threadId: string): string[];
+/** 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/dist/src/lib/cc/types.d.ts

@@ -0,0 +1,27 @@
+import z from "zod";
+export { AGENT_SLUG_PATTERN, executeResponseSchema, resolveResponseSchema, runtimeAgentConfigSchema, searchKnowledgeResponseSchema, searchServicesResponseSchema, searchToolsResponseSchema, type ExecuteRequest, type ResolveRequest, type ResolveResponse, type RuntimeAgentConfig, type SearchRequest, } from "../../../contracts/runtime";
+/**
+ * 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 declare const runtimeErrorSchema: z.ZodPreprocess<z.ZodObject<{
+    error: z.ZodObject<{
+        kind: z.ZodEnum<{
+            timeout: "timeout";
+            upstream_4xx: "upstream_4xx";
+            upstream_5xx: "upstream_5xx";
+            schema_mismatch: "schema_mismatch";
+            rate_limited: "rate_limited";
+            not_found: "not_found";
+            unauthorized: "unauthorized";
+            invalid_request: "invalid_request";
+            egress_blocked: "egress_blocked";
+            internal: "internal";
+        }>;
+        detail: z.ZodString;
+        retryable: z.ZodBoolean;
+        retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+        upstreamStatus: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>>;

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

@@ -0,0 +1,170 @@
+import type { AnyServerTool } from "@tanstack/ai";
+import type { DatabaseAdapter } from "./adapters/database/index";
+import type { StorageAdapter } from "./adapters/storage/index";
+import type { DomainDef } from "../../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 declare function defineAgent<TSession extends Record<string, unknown> = Record<string, unknown>, TRequestContext extends Record<string, unknown> = Record<string, unknown>>(config: CortexAgentDefinition<TSession, TRequestContext>): CortexAgentDefinition;
+export {};

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

@@ -0,0 +1,2 @@
+declare const _default: import("drizzle-kit").Config;
+export default _default;

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

@@ -0,0 +1,2 @@
+declare const _default: import("drizzle-kit").Config;
+export default _default;

package/dist/src/lib/db/migrate.d.ts

@@ -0,0 +1,7 @@
+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 declare function runMigrations(database: DatabaseConfig): Promise<void>;