@m6d/cortex-server 2.2.0 → 2.4.0

package/contracts/src/runtime/index.ts

@@ -7,10 +7,10 @@ import { z } from "zod";
  * payloads the runtime's parser then fills defaults into.
  */
 
-/** Runtime contract §1.1: the `:id` path param, validated on both sides of the wire. */
+/** The `:id` path param, validated on both sides of the wire. */
 export const AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
 
-/** Runtime contract §5: tool names become `tools.<name>()` sandbox bindings. */
+/** Tool names become `tools.<name>()` sandbox bindings on the server. */
 export const TOOL_NAME_PATTERN = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 
 export const PROMPT_VARIABLES = ["userName", "channel", "locale", "utcTime", "timezone"] as const;
@@ -90,7 +90,7 @@ export const knowledgeChunkSchema = z.object({
 });
 
 /**
- * Runtime contract §5.4: present on signatures of `embedded` tools — flows
+ * Present on signatures of `embedded` tools — flows
  * the end user completes in an embedded surface inside the chat widget. The
  * tool's endpoint fields act as the *initiate* call (returns the embed URL);
  * the result the page reports back is relayed as-is — verifying it is the
@@ -132,7 +132,6 @@ export const runtimeAgentConfigSchema = z.object({
     agentId: agentSlugSchema,
     systemPrompt: z.string(),
     promptVariables: z.array(z.enum(PROMPT_VARIABLES)),
-    catalogBlurb: z.string(),
     defaultLocale: localeSchema,
     metaTools: z.object({
         searchKnowledge: z.boolean(),
@@ -253,9 +252,105 @@ export const runtimeErrorSchema = z.object({
     }),
 });
 
+/*
+ * Fleet sync: `@m6d/cortex-server` mirrors thread/message/usage activity into
+ * cc via `POST /api/runtime/sync` batches. Upserts are idempotent on
+ * (serverId, id); an empty batch is the heartbeat.
+ */
+
+const tokenCountSchema = z.number().int().nonnegative();
+
+/** Mirrors the zero-dep `TokenUsage` shape in `wire/index.ts` (wire must stay import-free). */
+export const tokenUsageSchema = z.object({
+    input: z.object({
+        noCache: tokenCountSchema,
+        cacheRead: tokenCountSchema,
+        cacheWrite: tokenCountSchema,
+        total: tokenCountSchema,
+    }),
+    output: z.object({
+        reasoning: tokenCountSchema,
+        text: tokenCountSchema,
+        total: tokenCountSchema,
+    }),
+    total: tokenCountSchema,
+});
+
+export const MESSAGE_ROLES = ["system", "user", "assistant", "tool"] as const;
+
+export const syncEventSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("thread.upsert"),
+        id: z.uuid(),
+        agentSlug: agentSlugSchema,
+        userId: z.string().max(255),
+        title: z.string().max(256).nullable(),
+        isTest: z.boolean(),
+        createdAt: z.iso.datetime(),
+        updatedAt: z.iso.datetime(),
+    }),
+    z.object({
+        type: z.literal("thread.delete"),
+        id: z.uuid(),
+    }),
+    z.object({
+        type: z.literal("message.upsert"),
+        id: z.string().max(128),
+        threadId: z.uuid(),
+        role: z.enum(MESSAGE_ROLES),
+        text: z.string().nullable(),
+        ordinal: z.number().int(),
+        content: z.looseObject({}),
+        createdAt: z.iso.datetime(),
+    }),
+    z.object({
+        type: z.literal("usage.record"),
+        id: z.uuid(),
+        messageId: z.string().max(128),
+        threadId: z.uuid(),
+        stepNumber: z.number().int(),
+        tokenUsage: tokenUsageSchema,
+        // Stamped by the event constructor: llm_requests has no timestamp
+        // column, but the mirror needs one for time-bucketed usage stats.
+        createdAt: z.iso.datetime(),
+    }),
+]);
+
+/*
+ * `epoch` identifies the sending database's generation (a UUIDv7 minted into
+ * the server DB's `sync_meta` row): a recreated database gets a new epoch, so
+ * cc can tell a legitimately restarted outbox sequence from a stale batch.
+ * v7 uuids are time-ordered, so cc also rejects batches from a superseded
+ * (lexicographically lower) epoch outright.
+ * `seq` is the batch's highest outbox row id; batches are contiguous
+ * id-ordered outbox prefixes, so within one epoch cc keeps a per-server
+ * high-water mark and discards batches at or below it — a stale in-flight
+ * batch (an expired flusher lease, a replay after a lost ack) can never
+ * overwrite newer mirrored state. Heartbeats carry no events and nothing to
+ * fence, so `seq` exists only on the non-empty branch.
+ */
+export const syncRequestSchema = z.union([
+    z.object({
+        events: z.array(syncEventSchema).min(1).max(500),
+        epoch: z.uuid(),
+        seq: z.number().int().positive(),
+    }),
+    z.object({
+        events: z.array(syncEventSchema).length(0),
+        epoch: z.uuid(),
+    }),
+]);
+
+export const syncResponseSchema = z.object({
+    accepted: z.number().int(),
+});
+
 export type ToolEmbed = z.infer<typeof toolEmbedSchema>;
 export type RuntimeAgentConfig = z.infer<typeof runtimeAgentConfigSchema>;
 export type ResolveRequest = z.input<typeof resolveRequestSchema>;
 export type ResolveResponse = z.infer<typeof resolveResponseSchema>;
 export type SearchRequest = z.input<typeof searchRequestSchema>;
 export type ExecuteRequest = z.input<typeof executeRequestSchema>;
+export type SyncEvent = z.infer<typeof syncEventSchema>;
+export type SyncRequest = z.input<typeof syncRequestSchema>;
+export type SyncResponse = z.infer<typeof syncResponseSchema>;

package/dist/contracts/src/graph/helpers.d.ts

@@ -5,8 +5,8 @@
  */
 import type { ConceptDef, DomainDef, EndpointDef, EndpointInput, RuleDef, ServiceDef } from "./types";
 export declare function defineConcept(def: Omit<ConceptDef, "__brand">): {
-    description: string;
     name: string;
+    description: string;
     aliases?: string[] | undefined;
     metadata?: Record<string, unknown> | undefined;
     parentConcept?: ConceptDef | undefined;
@@ -14,14 +14,14 @@ export declare function defineConcept(def: Omit<ConceptDef, "__brand">): {
     __brand: "concept";
 };
 export declare function defineRule(def: Omit<RuleDef, "__brand">): {
-    description: string;
     name: string;
+    description: string;
     metadata?: Record<string, unknown> | undefined;
     __brand: "rule";
 };
 export declare function defineService(def: Omit<ServiceDef, "__brand">): {
-    description: string;
     name: string;
+    description: string;
     metadata?: Record<string, unknown> | undefined;
     builtInId: string;
     governedBy?: RuleDef[] | undefined;
@@ -29,12 +29,12 @@ export declare function defineService(def: Omit<ServiceDef, "__brand">): {
     __brand: "service";
 };
 export declare function defineDomain(def: Omit<DomainDef, "__brand">): {
-    description: string;
     name: string;
+    services?: ServiceDef[] | undefined;
+    description: string;
     metadata?: Record<string, unknown> | undefined;
     concepts?: ConceptDef[] | undefined;
     endpoints?: EndpointDef[] | undefined;
-    services?: ServiceDef[] | undefined;
     rules?: RuleDef[] | undefined;
     __brand: "domain";
 };

package/dist/contracts/src/runtime/index.d.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
-/** Runtime contract §1.1: the `:id` path param, validated on both sides of the wire. */
+/** The `:id` path param, validated on both sides of the wire. */
 export declare const AGENT_SLUG_PATTERN: RegExp;
-/** Runtime contract §5: tool names become `tools.<name>()` sandbox bindings. */
+/** Tool names become `tools.<name>()` sandbox bindings on the server. */
 export declare const TOOL_NAME_PATTERN: RegExp;
 export declare const PROMPT_VARIABLES: readonly ["userName", "channel", "locale", "utcTime", "timezone"];
 /**
@@ -61,7 +61,7 @@ export declare const knowledgeChunkSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 /**
- * Runtime contract §5.4: present on signatures of `embedded` tools — flows
+ * Present on signatures of `embedded` tools — flows
  * the end user completes in an embedded surface inside the chat widget. The
  * tool's endpoint fields act as the *initiate* call (returns the embed URL);
  * the result the page reports back is relayed as-is — verifying it is the
@@ -109,7 +109,6 @@ export declare const runtimeAgentConfigSchema: z.ZodObject<{
         utcTime: "utcTime";
         timezone: "timezone";
     }>>;
-    catalogBlurb: z.ZodString;
     defaultLocale: z.ZodEnum<{
         ar: "ar";
         en: "en";
@@ -348,10 +347,182 @@ export declare const runtimeErrorSchema: z.ZodObject<{
         upstreamStatus: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/** Mirrors the zero-dep `TokenUsage` shape in `wire/index.ts` (wire must stay import-free). */
+export declare const tokenUsageSchema: z.ZodObject<{
+    input: z.ZodObject<{
+        noCache: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+        cacheWrite: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strip>;
+    output: z.ZodObject<{
+        reasoning: z.ZodNumber;
+        text: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strip>;
+    total: z.ZodNumber;
+}, z.core.$strip>;
+export declare const MESSAGE_ROLES: readonly ["system", "user", "assistant", "tool"];
+export declare const syncEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"thread.upsert">;
+    id: z.ZodUUID;
+    agentSlug: z.ZodString;
+    userId: z.ZodString;
+    title: z.ZodNullable<z.ZodString>;
+    isTest: z.ZodBoolean;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"thread.delete">;
+    id: z.ZodUUID;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"message.upsert">;
+    id: z.ZodString;
+    threadId: z.ZodUUID;
+    role: z.ZodEnum<{
+        system: "system";
+        user: "user";
+        assistant: "assistant";
+        tool: "tool";
+    }>;
+    text: z.ZodNullable<z.ZodString>;
+    ordinal: z.ZodNumber;
+    content: z.ZodObject<{}, z.core.$loose>;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"usage.record">;
+    id: z.ZodUUID;
+    messageId: z.ZodString;
+    threadId: z.ZodUUID;
+    stepNumber: z.ZodNumber;
+    tokenUsage: z.ZodObject<{
+        input: z.ZodObject<{
+            noCache: z.ZodNumber;
+            cacheRead: z.ZodNumber;
+            cacheWrite: z.ZodNumber;
+            total: z.ZodNumber;
+        }, z.core.$strip>;
+        output: z.ZodObject<{
+            reasoning: z.ZodNumber;
+            text: z.ZodNumber;
+            total: z.ZodNumber;
+        }, z.core.$strip>;
+        total: z.ZodNumber;
+    }, z.core.$strip>;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strip>], "type">;
+export declare const syncRequestSchema: z.ZodUnion<readonly [z.ZodObject<{
+    events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"thread.upsert">;
+        id: z.ZodUUID;
+        agentSlug: z.ZodString;
+        userId: z.ZodString;
+        title: z.ZodNullable<z.ZodString>;
+        isTest: z.ZodBoolean;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"thread.delete">;
+        id: z.ZodUUID;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"message.upsert">;
+        id: z.ZodString;
+        threadId: z.ZodUUID;
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        text: z.ZodNullable<z.ZodString>;
+        ordinal: z.ZodNumber;
+        content: z.ZodObject<{}, z.core.$loose>;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"usage.record">;
+        id: z.ZodUUID;
+        messageId: z.ZodString;
+        threadId: z.ZodUUID;
+        stepNumber: z.ZodNumber;
+        tokenUsage: z.ZodObject<{
+            input: z.ZodObject<{
+                noCache: z.ZodNumber;
+                cacheRead: z.ZodNumber;
+                cacheWrite: z.ZodNumber;
+                total: z.ZodNumber;
+            }, z.core.$strip>;
+            output: z.ZodObject<{
+                reasoning: z.ZodNumber;
+                text: z.ZodNumber;
+                total: z.ZodNumber;
+            }, z.core.$strip>;
+            total: z.ZodNumber;
+        }, z.core.$strip>;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strip>], "type">>;
+    epoch: z.ZodUUID;
+    seq: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"thread.upsert">;
+        id: z.ZodUUID;
+        agentSlug: z.ZodString;
+        userId: z.ZodString;
+        title: z.ZodNullable<z.ZodString>;
+        isTest: z.ZodBoolean;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"thread.delete">;
+        id: z.ZodUUID;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"message.upsert">;
+        id: z.ZodString;
+        threadId: z.ZodUUID;
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        text: z.ZodNullable<z.ZodString>;
+        ordinal: z.ZodNumber;
+        content: z.ZodObject<{}, z.core.$loose>;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"usage.record">;
+        id: z.ZodUUID;
+        messageId: z.ZodString;
+        threadId: z.ZodUUID;
+        stepNumber: z.ZodNumber;
+        tokenUsage: z.ZodObject<{
+            input: z.ZodObject<{
+                noCache: z.ZodNumber;
+                cacheRead: z.ZodNumber;
+                cacheWrite: z.ZodNumber;
+                total: z.ZodNumber;
+            }, z.core.$strip>;
+            output: z.ZodObject<{
+                reasoning: z.ZodNumber;
+                text: z.ZodNumber;
+                total: z.ZodNumber;
+            }, z.core.$strip>;
+            total: z.ZodNumber;
+        }, z.core.$strip>;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strip>], "type">>;
+    epoch: z.ZodUUID;
+}, z.core.$strip>]>;
+export declare const syncResponseSchema: z.ZodObject<{
+    accepted: z.ZodNumber;
+}, z.core.$strip>;
 export type ToolEmbed = z.infer<typeof toolEmbedSchema>;
 export type RuntimeAgentConfig = z.infer<typeof runtimeAgentConfigSchema>;
 export type ResolveRequest = z.input<typeof resolveRequestSchema>;
 export type ResolveResponse = z.infer<typeof resolveResponseSchema>;
 export type SearchRequest = z.input<typeof searchRequestSchema>;
 export type ExecuteRequest = z.input<typeof executeRequestSchema>;
+export type SyncEvent = z.infer<typeof syncEventSchema>;
+export type SyncRequest = z.input<typeof syncRequestSchema>;
+export type SyncResponse = z.infer<typeof syncResponseSchema>;
 export {};

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

@@ -1,3 +1,4 @@
+import type { SyncEvent } from "../../../../contracts/src/runtime";
 import type { Attachment, ChatMessage, NewAttachment, StoredMessage, Thread, TokenUsage } from "../../types";
 import type { ThreadContextMeta } from "../../ai/context/types";
 /**
@@ -20,7 +21,9 @@ export type DatabaseAdapter = {
     threads: {
         list(userId: string, agentId: string): Promise<Thread[]>;
         getById(userId: string, threadId: string): Promise<Thread | null>;
-        create(userId: string, agentId: string): Promise<Thread>;
+        create(userId: string, agentId: string, options?: {
+            isTest?: boolean;
+        }): Promise<Thread>;
         delete(userId: string, threadId: string): Promise<void>;
         touch(threadId: string): Promise<Thread>;
         updateTitle(threadId: string, title: string): Promise<void>;
@@ -36,7 +39,7 @@ export type DatabaseAdapter = {
         }): Promise<void>;
     };
     llmRequests: {
-        insert(requests: {
+        insert(threadId: string, requests: {
             messageId: string;
             stepNumber: number;
             prompt: string;
@@ -58,4 +61,19 @@ export type DatabaseAdapter = {
         setDescription(id: string, userId: string, status: Attachment["status"], description?: string): Promise<void>;
         remove(id: string, userId: string): Promise<Attachment | undefined>;
     };
+    /**
+     * The cc sync queue. Write sites enqueue through the dialect's
+     * `enqueueSyncEvents` inside their own transaction; the flusher drains via
+     * `peek` (id ascending = insertion order) and `ack` (delete) here.
+     */
+    outbox: {
+        enqueue(events: SyncEvent[]): Promise<void>;
+        peek(limit: number): Promise<{
+            id: number;
+            event: SyncEvent;
+        }[]>;
+        ack(ids: number[]): Promise<void>;
+        /** This database generation's id, minted on first use (see `syncMeta`). */
+        epoch(): Promise<string>;
+    };
 };

package/dist/src/lib/adapters/database/mssql/attachments.d.ts

@@ -1,8 +1,8 @@
 import type { MssqlDb } from "./client";
 export declare function createAttachmentsRepository(db: MssqlDb): {
     createPending(row: {
-        userId: string;
         threadId: string;
+        userId: string;
         filename: string;
         contentType: string;
         sizeBytes: number;
@@ -14,11 +14,11 @@ export declare function createAttachmentsRepository(db: MssqlDb): {
         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;
@@ -28,11 +28,11 @@ export declare function createAttachmentsRepository(db: MssqlDb): {
         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;
@@ -69,11 +69,11 @@ export declare function createAttachmentsRepository(db: MssqlDb): {
         description: string | null;
     }[]>;
     claimForMessage(threadId: string, userId: string, messageId: string): Promise<{
-        id: string;
+        threadId: string;
         userId: string;
+        id: string;
         createdAt: Date;
         updatedAt: Date;
-        threadId: string;
         messageId: string | null;
         filename: string;
         contentType: string;
@@ -84,11 +84,11 @@ export declare function createAttachmentsRepository(db: MssqlDb): {
     }[]>;
     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;