@m6d/cortex-server 2.3.0 → 2.5.0

package/dist/src/lib/adapters/database/postgres/index.d.ts

@@ -4,7 +4,9 @@ import type { StorageAdapter } from "../../../adapters/storage/index";
  * table; only threads takes storage, because deleting a thread is the one
  * operation that also has to reach into object storage.
  */
-export declare function createPostgresAdapter(connectionString: string, storage?: StorageAdapter): {
+export declare function createPostgresAdapter(connectionString: string, storage?: StorageAdapter, options?: {
+    syncMirror?: boolean;
+}): {
     threads: {
         list(userId: string, agentId: string): Promise<{
             createdAt: Date;
@@ -13,39 +15,45 @@ export declare function createPostgresAdapter(connectionString: string, storage?
             userId: string;
             agentId: string;
             title: string | null;
+            isTest: boolean;
             session: Record<string, unknown> | null;
             contextMeta: import("../../..").ThreadContextMeta | null;
         }[]>;
         getById(userId: string, threadId: string): Promise<{
-            id: string;
-            userId: string;
             agentId: string;
+            userId: string;
+            id: string;
             title: string | null;
-            session: Record<string, unknown> | null;
-            contextMeta: import("../../..").ThreadContextMeta | null;
+            isTest: boolean;
             createdAt: Date;
             updatedAt: Date;
+            session: Record<string, unknown> | null;
+            contextMeta: import("../../..").ThreadContextMeta | null;
         } | null>;
-        create(userId: string, agentId: string): Promise<{
-            id: string;
-            userId: string;
+        create(userId: string, agentId: string, options: {
+            isTest?: boolean;
+        } | undefined): Promise<{
             agentId: string;
+            userId: string;
+            id: string;
             title: string | null;
-            session: Record<string, unknown> | null;
-            contextMeta: import("../../..").ThreadContextMeta | null;
+            isTest: boolean;
             createdAt: Date;
             updatedAt: Date;
+            session: Record<string, unknown> | null;
+            contextMeta: import("../../..").ThreadContextMeta | null;
         }>;
         delete(userId: string, threadId: string): Promise<void>;
         touch(threadId: string): Promise<{
-            id: string;
-            userId: string;
             agentId: string;
+            userId: string;
+            id: string;
             title: string | null;
-            session: Record<string, unknown> | null;
-            contextMeta: import("../../..").ThreadContextMeta | null;
+            isTest: boolean;
             createdAt: Date;
             updatedAt: Date;
+            session: Record<string, unknown> | null;
+            contextMeta: import("../../..").ThreadContextMeta | null;
         }>;
         updateTitle(threadId: string, title: string): Promise<void>;
         updateSession(threadId: string, session: Record<string, unknown>): Promise<void>;
@@ -55,14 +63,14 @@ export declare function createPostgresAdapter(connectionString: string, storage?
         list(userId: string, threadId: string, opts: {
             limit?: number;
         } | undefined): Promise<{
-            id: string;
             text: string | null;
+            threadId: string;
+            id: string;
             createdAt: Date;
             updatedAt: Date;
-            threadId: string;
-            content: import("../../../types").ChatMessage;
-            ordinal: number;
             role: "system" | "user" | "assistant" | "tool";
+            ordinal: number;
+            content: import("../../../types").ChatMessage;
         }[] | {
             createdAt: Date;
             updatedAt: Date;
@@ -78,7 +86,7 @@ export declare function createPostgresAdapter(connectionString: string, storage?
         }): Promise<void>;
     };
     llmRequests: {
-        insert(requests: {
+        insert(threadId: string, requests: {
             messageId: string;
             stepNumber: number;
             prompt: string;
@@ -94,8 +102,8 @@ export declare function createPostgresAdapter(connectionString: string, storage?
     };
     attachments: {
         createPending(row: {
-            userId: string;
             threadId: string;
+            userId: string;
             filename: string;
             contentType: string;
             sizeBytes: number;
@@ -107,11 +115,11 @@ export declare function createPostgresAdapter(connectionString: string, storage?
             messageId?: string | null | undefined;
             description?: string | null | undefined;
         }, limit: number): Promise<{
-            id: string;
+            threadId: string;
             userId: string;
+            id: string;
             createdAt: Date;
             updatedAt: Date;
-            threadId: string;
             messageId: string | null;
             filename: string;
             contentType: string;
@@ -121,11 +129,11 @@ export declare function createPostgresAdapter(connectionString: string, storage?
             description: string | null;
         } | undefined>;
         getById(id: string, userId: string): Promise<{
-            id: string;
+            threadId: string;
             userId: string;
+            id: string;
             createdAt: Date;
             updatedAt: Date;
-            threadId: string;
             messageId: string | null;
             filename: string;
             contentType: string;
@@ -177,11 +185,11 @@ export declare function createPostgresAdapter(connectionString: string, storage?
         }[]>;
         setDescription(id: string, userId: string, status: "pending" | "described" | "failed" | "skipped", description: string | undefined): Promise<void>;
         remove(id: string, userId: string): Promise<{
-            id: string;
+            threadId: string;
             userId: string;
+            id: string;
             createdAt: Date;
             updatedAt: Date;
-            threadId: string;
             messageId: string | null;
             filename: string;
             contentType: string;
@@ -190,11 +198,11 @@ export declare function createPostgresAdapter(connectionString: string, storage?
             status: "pending" | "described" | "failed" | "skipped";
             description: string | null;
         } | {
-            id: string;
+            threadId: string;
             userId: string;
+            id: string;
             createdAt: Date;
             updatedAt: Date;
-            threadId: string;
             messageId: string | null;
             filename: string;
             contentType: string;
@@ -204,4 +212,101 @@ export declare function createPostgresAdapter(connectionString: string, storage?
             description: string | null;
         } | undefined>;
     };
+    outbox: {
+        enqueue: (events: ({
+            type: "thread.upsert";
+            id: string;
+            agentSlug: string;
+            userId: string;
+            title: string | null;
+            isTest: boolean;
+            createdAt: string;
+            updatedAt: string;
+        } | {
+            type: "thread.delete";
+            id: string;
+        } | {
+            type: "message.upsert";
+            id: string;
+            threadId: string;
+            role: "system" | "user" | "assistant" | "tool";
+            text: string | null;
+            ordinal: number;
+            content: {
+                [x: string]: unknown;
+            };
+            createdAt: string;
+        } | {
+            type: "usage.record";
+            id: string;
+            messageId: string;
+            threadId: string;
+            stepNumber: number;
+            tokenUsage: {
+                input: {
+                    noCache: number;
+                    cacheRead: number;
+                    cacheWrite: number;
+                    total: number;
+                };
+                output: {
+                    reasoning: number;
+                    text: number;
+                    total: number;
+                };
+                total: number;
+            };
+            createdAt: string;
+        })[]) => Promise<void>;
+        peek(limit: number): Promise<{
+            id: number;
+            event: {
+                type: "thread.upsert";
+                id: string;
+                agentSlug: string;
+                userId: string;
+                title: string | null;
+                isTest: boolean;
+                createdAt: string;
+                updatedAt: string;
+            } | {
+                type: "thread.delete";
+                id: string;
+            } | {
+                type: "message.upsert";
+                id: string;
+                threadId: string;
+                role: "system" | "user" | "assistant" | "tool";
+                text: string | null;
+                ordinal: number;
+                content: {
+                    [x: string]: unknown;
+                };
+                createdAt: string;
+            } | {
+                type: "usage.record";
+                id: string;
+                messageId: string;
+                threadId: string;
+                stepNumber: number;
+                tokenUsage: {
+                    input: {
+                        noCache: number;
+                        cacheRead: number;
+                        cacheWrite: number;
+                        total: number;
+                    };
+                    output: {
+                        reasoning: number;
+                        text: number;
+                        total: number;
+                    };
+                    total: number;
+                };
+                createdAt: string;
+            };
+        }[]>;
+        epoch(): Promise<string>;
+        ack(ids: number[]): Promise<void>;
+    };
 };

package/dist/src/lib/adapters/database/postgres/llm-requests.d.ts

@@ -1,6 +1,7 @@
 import type { PostgresDb } from "./client";
-export declare function createLlmRequestsRepository(db: PostgresDb): {
-    insert(requests: {
+import { enqueueSyncEvents } from "./outbox";
+export declare function createLlmRequestsRepository(db: PostgresDb, enqueue?: typeof enqueueSyncEvents): {
+    insert(threadId: string, requests: {
         messageId: string;
         stepNumber: number;
         prompt: string;

package/dist/src/lib/adapters/database/postgres/messages.d.ts

@@ -1,6 +1,7 @@
 import type { ChatMessage } from "../../../types";
 import type { PostgresDb } from "./client";
-export declare function createMessagesRepository(db: PostgresDb): {
+import { enqueueSyncEvents } from "./outbox";
+export declare function createMessagesRepository(db: PostgresDb, enqueue?: typeof enqueueSyncEvents): {
     /**
      * Fetches the newest N and reverses, so a limit keeps the most recent
      * messages while callers still receive them oldest-first.
@@ -8,14 +9,14 @@ export declare function createMessagesRepository(db: PostgresDb): {
     list(userId: string, threadId: string, opts: {
         limit?: number;
     } | undefined): Promise<{
-        id: string;
         text: string | null;
+        threadId: string;
+        id: string;
         createdAt: Date;
         updatedAt: Date;
-        threadId: string;
-        content: ChatMessage;
-        ordinal: number;
         role: "system" | "user" | "assistant" | "tool";
+        ordinal: number;
+        content: ChatMessage;
     }[] | {
         createdAt: Date;
         updatedAt: Date;

package/dist/src/lib/adapters/database/postgres/outbox.d.ts

@@ -0,0 +1,103 @@
+import type { SyncEvent } from "../../../../../contracts/src/runtime";
+import type { PostgresDb } from "./client";
+/** A db or one of its transactions, so a write and its events commit together. */
+type Executor = Pick<PostgresDb, "insert">;
+export declare function enqueueSyncEvents(executor: Executor, events: SyncEvent[]): Promise<void>;
+export declare function createOutboxRepository(db: PostgresDb): {
+    enqueue: (events: ({
+        type: "thread.upsert";
+        id: string;
+        agentSlug: string;
+        userId: string;
+        title: string | null;
+        isTest: boolean;
+        createdAt: string;
+        updatedAt: string;
+    } | {
+        type: "thread.delete";
+        id: string;
+    } | {
+        type: "message.upsert";
+        id: string;
+        threadId: string;
+        role: "system" | "user" | "assistant" | "tool";
+        text: string | null;
+        ordinal: number;
+        content: {
+            [x: string]: unknown;
+        };
+        createdAt: string;
+    } | {
+        type: "usage.record";
+        id: string;
+        messageId: string;
+        threadId: string;
+        stepNumber: number;
+        tokenUsage: {
+            input: {
+                noCache: number;
+                cacheRead: number;
+                cacheWrite: number;
+                total: number;
+            };
+            output: {
+                reasoning: number;
+                text: number;
+                total: number;
+            };
+            total: number;
+        };
+        createdAt: string;
+    })[]) => Promise<void>;
+    peek(limit: number): Promise<{
+        id: number;
+        event: {
+            type: "thread.upsert";
+            id: string;
+            agentSlug: string;
+            userId: string;
+            title: string | null;
+            isTest: boolean;
+            createdAt: string;
+            updatedAt: string;
+        } | {
+            type: "thread.delete";
+            id: string;
+        } | {
+            type: "message.upsert";
+            id: string;
+            threadId: string;
+            role: "system" | "user" | "assistant" | "tool";
+            text: string | null;
+            ordinal: number;
+            content: {
+                [x: string]: unknown;
+            };
+            createdAt: string;
+        } | {
+            type: "usage.record";
+            id: string;
+            messageId: string;
+            threadId: string;
+            stepNumber: number;
+            tokenUsage: {
+                input: {
+                    noCache: number;
+                    cacheRead: number;
+                    cacheWrite: number;
+                    total: number;
+                };
+                output: {
+                    reasoning: number;
+                    text: number;
+                    total: number;
+                };
+                total: number;
+            };
+            createdAt: string;
+        };
+    }[]>;
+    epoch(): Promise<string>;
+    ack(ids: number[]): Promise<void>;
+};
+export {};

package/dist/src/lib/adapters/database/postgres/threads.d.ts

@@ -1,7 +1,8 @@
 import type { ThreadContextMeta } from "../../../ai/context/types";
 import type { PostgresDb } from "./client";
+import { enqueueSyncEvents } from "./outbox";
 import type { StorageAdapter } from "../../../adapters/storage/index";
-export declare function createThreadsRepository(db: PostgresDb, storage?: StorageAdapter): {
+export declare function createThreadsRepository(db: PostgresDb, storage?: StorageAdapter, enqueue?: typeof enqueueSyncEvents): {
     list(userId: string, agentId: string): Promise<{
         createdAt: Date;
         updatedAt: Date;
@@ -9,40 +10,46 @@ export declare function createThreadsRepository(db: PostgresDb, storage?: Storag
         userId: string;
         agentId: string;
         title: string | null;
+        isTest: boolean;
         session: Record<string, unknown> | null;
         contextMeta: ThreadContextMeta | null;
     }[]>;
     getById(userId: string, threadId: string): Promise<{
-        id: string;
-        userId: string;
         agentId: string;
+        userId: string;
+        id: string;
         title: string | null;
-        session: Record<string, unknown> | null;
-        contextMeta: ThreadContextMeta | null;
+        isTest: boolean;
         createdAt: Date;
         updatedAt: Date;
+        session: Record<string, unknown> | null;
+        contextMeta: ThreadContextMeta | null;
     } | null>;
-    create(userId: string, agentId: string): Promise<{
-        id: string;
-        userId: string;
+    create(userId: string, agentId: string, options: {
+        isTest?: boolean;
+    } | undefined): Promise<{
         agentId: string;
+        userId: string;
+        id: string;
         title: string | null;
-        session: Record<string, unknown> | null;
-        contextMeta: ThreadContextMeta | null;
+        isTest: boolean;
         createdAt: Date;
         updatedAt: Date;
+        session: Record<string, unknown> | null;
+        contextMeta: ThreadContextMeta | null;
     }>;
     /** Object storage has no foreign keys, so attachment paths must be swept before row cascade. */
     delete(userId: string, threadId: string): Promise<void>;
     touch(threadId: string): Promise<{
-        id: string;
-        userId: string;
         agentId: string;
+        userId: string;
+        id: string;
         title: string | null;
-        session: Record<string, unknown> | null;
-        contextMeta: ThreadContextMeta | null;
+        isTest: boolean;
         createdAt: Date;
         updatedAt: Date;
+        session: Record<string, unknown> | null;
+        contextMeta: ThreadContextMeta | null;
     }>;
     updateTitle(threadId: string, title: string): Promise<void>;
     updateSession(threadId: string, session: Record<string, unknown>): Promise<void>;

package/dist/src/lib/ai/attachments.d.ts

@@ -12,11 +12,11 @@ type AttachmentCapabilities = {
     attachmentSentinels: boolean;
 };
 export declare function prepareAttachmentsForTurn(options: PrepareAttachmentsOptions): Promise<{
-    id: string;
+    threadId: string;
     userId: string;
+    id: string;
     createdAt: Date;
     updatedAt: Date;
-    threadId: string;
     messageId: string | null;
     filename: string;
     contentType: string;

package/dist/src/lib/ai/client-tools.d.ts

@@ -30,7 +30,7 @@ export declare function createCcClient(config: ResolvedCortexAgentConfig): Contr
 export declare function clientToolAnswersFrom(forwardedProps: Record<string, unknown>): {
     toolCallId: string;
     output: unknown;
-    state: "complete" | "error";
+    state: "error" | "complete";
 }[] | null;
 /**
  * Applies client tool answers to the stored messages carrying their calls,

package/dist/src/lib/auth/middleware.d.ts

@@ -1,4 +1,4 @@
 import type { AppEnv, AuthedAppEnv } from "../types";
-import type { CortexConfig } from "../config";
-export declare function createUserLoaderMiddleware(authConfig: CortexConfig["auth"]): import("hono").MiddlewareHandler<AppEnv, string, {}, Response>;
+import type { ControlCenterConfig, CortexConfig } from "../config";
+export declare function createUserLoaderMiddleware(authConfig: CortexConfig["auth"], controlCenter?: ControlCenterConfig): import("hono").MiddlewareHandler<AppEnv, string, {}, Response>;
 export declare const requireAuth: import("hono").MiddlewareHandler<AuthedAppEnv, string, {}, Response>;

package/dist/src/lib/auth/playground.d.ts

@@ -0,0 +1,14 @@
+import type { ControlCenterConfig } from "../config";
+export declare function ccIssuer(config: ControlCenterConfig): string;
+/**
+ * True when the token's (unverified) `iss` names the playground-enabled cc —
+ * the routing decision only; verification still happens against the JWKS.
+ */
+export declare function isPlaygroundToken(controlCenter: ControlCenterConfig | undefined, token: string): boolean;
+export declare function verifyPlaygroundToken(controlCenter: ControlCenterConfig, token: string): Promise<import("jose").JWTPayload>;
+/**
+ * Verifies the cc-signed `X-Cortex-Playground` header. Works for both
+ * cc-minted and pasted-real-user-token modes: the header always carries the
+ * caller's own cc JWT, independent of the Authorization token.
+ */
+export declare function isPlaygroundRequest(controlCenter: ControlCenterConfig | undefined, request: Request): Promise<boolean>;

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

@@ -1,5 +1,5 @@
 import type { ControlCenterConfig } from "../config";
-import type { ExecuteRequest, ResolveRequest, SearchRequest } from "./types";
+import type { ExecuteRequest, ResolveRequest, SearchRequest, SyncRequest } from "./types";
 type ControlCenterFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 export type ExecuteOptions = {
     readOnly: boolean;
@@ -191,6 +191,14 @@ export declare class ControlCenterClient {
             }[];
         };
     } | null>;
+    /**
+     * Pushes one outbox batch to `POST /api/runtime/sync` (server-level, not
+     * under an agent). Returns true — the flusher's license to delete the
+     * rows — only when cc itself confirms the whole batch: a 2xx whose body
+     * parses as the sync response and counts every event. A gateway serving
+     * HTML with a 200, or a partial count, keeps the rows queued for retry.
+     */
+    sync(request: SyncRequest, abortSignal?: AbortSignal): Promise<boolean>;
     private agentPath;
     private post;
     private postResponse;

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

@@ -0,0 +1,40 @@
+import type { Redis } from "ioredis";
+import type { DatabaseAdapter } from "../adapters/database/index";
+import type { ControlCenterClient } from "./client";
+/**
+ * Drains the sync outbox to cc every 10s: peek → sync → ack on success, rows
+ * stay put on failure so the next tick retries. A quiet outbox still POSTs an
+ * empty batch once a minute — that is the heartbeat behind cc's online badge.
+ *
+ * With Redis configured (multi-replica deployments), a per-tick lease keeps
+ * exactly one replica flushing at a time, so batches cannot overlap or land
+ * out of order. Without Redis the deployment is single-process and the
+ * in-flight flag alone suffices.
+ */
+type OutboxRow = Awaited<ReturnType<DatabaseAdapter["outbox"]["peek"]>>[number];
+type SyncEvent = OutboxRow["event"];
+/** A contract-valid stand-in for a message too large for cc's request cap:
+ * enough text for the transcript, `content` reduced to a truncation marker.
+ * The full message stays in the server database. Only messages can grow
+ * unbounded; anything else oversized has no meaningful reduction. */
+export declare function shrinkOversizedEvent(event: SyncEvent): {
+    text: string | null;
+    content: {
+        truncated: boolean;
+    };
+    type: "message.upsert";
+    id: string;
+    threadId: string;
+    role: "system" | "user" | "assistant" | "tool";
+    ordinal: number;
+    createdAt: string;
+} | null;
+/** Longest row prefix whose serialized events stay under cc's request body
+ * cap, or null when the head row alone can never fit (a poison pill that
+ * would wedge the queue if kept). */
+export declare function sliceBatch(rows: OutboxRow[], maxBytes?: number): {
+    id: number;
+    event: import("./types").SyncEvent;
+}[] | null;
+export declare function startSyncFlusher(db: DatabaseAdapter, client: ControlCenterClient, redis?: Redis): () => void;
+export {};

package/dist/src/lib/cc/sync-events.d.ts

@@ -0,0 +1,45 @@
+import type { ChatMessage, Thread, TokenUsage } from "../types";
+export declare function threadUpsertEvent(thread: Thread): {
+    type: "thread.upsert";
+    id: string;
+    agentSlug: string;
+    userId: string;
+    title: string | null;
+    isTest: boolean;
+    createdAt: string;
+    updatedAt: string;
+};
+export declare function threadDeleteEvent(threadId: string): {
+    type: "thread.delete";
+    id: string;
+};
+export declare function messageUpsertEvent(input: {
+    threadId: string;
+    message: ChatMessage;
+    text: string | null | undefined;
+    ordinal: number;
+    createdAt: Date;
+}): {
+    type: "message.upsert";
+    id: string;
+    threadId: string;
+    role: "system" | "user" | "assistant";
+    text: string | null;
+    ordinal: number;
+    content: Record<string, unknown>;
+    createdAt: string;
+};
+export declare function usageRecordEvent(input: {
+    threadId: string;
+    messageId: string;
+    stepNumber: number;
+    tokenUsage: TokenUsage;
+}): {
+    type: "usage.record";
+    id: `${string}-${string}-${string}-${string}-${string}`;
+    messageId: string;
+    threadId: string;
+    stepNumber: number;
+    tokenUsage: TokenUsage;
+    createdAt: string;
+};

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

@@ -1,5 +1,5 @@
 import z from "zod";
-export { AGENT_SLUG_PATTERN, executeResponseSchema, resolveResponseSchema, runtimeAgentConfigSchema, searchKnowledgeResponseSchema, searchServicesResponseSchema, searchToolsResponseSchema, type ExecuteRequest, type ResolveRequest, type ResolveResponse, type RuntimeAgentConfig, type SearchRequest, type ToolEmbed, } from "../../../contracts/src/runtime";
+export { AGENT_SLUG_PATTERN, executeResponseSchema, resolveResponseSchema, runtimeAgentConfigSchema, searchKnowledgeResponseSchema, searchServicesResponseSchema, searchToolsResponseSchema, syncResponseSchema, type ExecuteRequest, type ResolveRequest, type ResolveResponse, type RuntimeAgentConfig, type SearchRequest, type SyncEvent, type SyncRequest, type ToolEmbed, } from "../../../contracts/src/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

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

@@ -36,6 +36,17 @@ type RerankerConfig = {
 export type ControlCenterConfig = {
     url: string;
     apiKey: string;
+    /**
+     * Trust cc as a secondary token issuer (its playground). cc-minted
+     * end-user JWTs then authenticate against `{url}/api/auth/jwks`, and a
+     * cc-signed `X-Cortex-Playground` header marks new threads as test data.
+     */
+    playground?: boolean;
+    /**
+     * The `iss` claim cc stamps (its Better Auth `baseURL`), when it differs
+     * from the URL this server dials. Defaults to `url`.
+     */
+    playgroundIssuer?: string;
 };
 export type KnowledgeConfig = {
     swagger?: {