@m6d/cortex-server 1.8.0 → 2.0.1

package/contracts/runtime.ts

@@ -0,0 +1,243 @@
+import { z } from "zod";
+
+/*
+ * The HTTP contract of the cortex-cc runtime API: the console (`apps/cortex-cc`)
+ * validates requests against these schemas and `@m6d/cortex-server` validates the
+ * responses it gets back. Request types use `z.input` because the callers build
+ * payloads the runtime's parser then fills defaults into.
+ */
+
+/** Runtime contract §1.1: 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. */
+export const TOOL_NAME_PATTERN = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+
+export const PROMPT_VARIABLES = ["userName", "channel", "locale", "utcTime", "timezone"] as const;
+
+/**
+ * One entry per prompt variable, driving editor autocomplete, validation, and
+ * runtime substitution alike. Adding a variable = extending the tuple above
+ * plus one entry here (the compiler enforces the pair); the consumer embedding
+ * the agent supplies the value in its session/request context under the same
+ * key. Descriptions are plain English on purpose: variables are code-like
+ * identifiers shown in an LTR suggestion list, not localized UI copy.
+ */
+export const PROMPT_VARIABLE_DEFINITIONS = {
+    userName: {
+        description: "Display name of the signed-in user",
+        example: "Sara",
+    },
+    channel: {
+        description: "Channel the conversation arrived on",
+        example: "web",
+    },
+    locale: {
+        description: "Resolved locale of the session",
+        example: "ar",
+    },
+    // The server computes utcTime per request (a consumer-supplied value
+    // still wins); timezone has no server default — only the consumer knows
+    // the session's zone, so it must arrive via session/request context or
+    // the placeholder stays literal.
+    utcTime: {
+        description: "Current time in UTC (ISO 8601)",
+        example: "2026-08-16T09:30:00Z",
+    },
+    timezone: {
+        description: "IANA time zone of the session",
+        example: "Asia/Dubai",
+    },
+} satisfies Record<(typeof PROMPT_VARIABLES)[number], { description: string; example: string }>;
+
+export const RUNTIME_ERROR_KINDS = [
+    "timeout",
+    "upstream_4xx",
+    "upstream_5xx",
+    "schema_mismatch",
+    "rate_limited",
+    "not_found",
+    "unauthorized",
+    "invalid_request",
+    "egress_blocked",
+    "internal",
+] as const;
+
+/** The ways an execute output may disagree with the tool's declared schema. */
+export const JSON_SCHEMA_ISSUE_KINDS = ["missing", "unexpected", "type_mismatch"] as const;
+
+export const agentSlugSchema = z.string().regex(AGENT_SLUG_PATTERN);
+export const localeSchema = z.enum(["en", "ar"]);
+export const catalogVersionSchema = z.string().regex(/^[0-9a-f]{16}$/);
+
+export const sharedShapeSchema = z.object({
+    ref: z.string().regex(/^\$R\d+$/),
+    shape: z.string(),
+});
+
+export const knowledgeChunkSchema = z.object({
+    chunkId: z.uuid(),
+    text: z.string(),
+    score: z.number(),
+    citation: z.object({
+        documentId: z.uuid(),
+        documentTitle: z.string(),
+        page: z.number().int().positive().nullable(),
+        section: z.string().nullable(),
+        uri: z.url().nullable(),
+        service: z.string().nullable(),
+    }),
+});
+
+export const toolSignatureSchema = z.object({
+    toolId: z.uuid(),
+    name: z.string().regex(TOOL_NAME_PATTERN),
+    version: z.number().int().positive(),
+    readOnly: z.boolean(),
+    tags: z.array(z.string()),
+    signature: z.string(),
+    score: z.number().nullable(),
+    pinned: z.boolean(),
+});
+
+export const serviceCardSchema = z.object({
+    serviceId: z.uuid(),
+    key: z
+        .string()
+        .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/)
+        .max(64),
+    name: z.string(),
+    card: z.string(),
+    score: z.number(),
+});
+
+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(),
+        searchTools: z.boolean(),
+        searchServices: z.boolean(),
+    }),
+    limits: z.object({
+        resolveTokenBudget: z.number().int().positive(),
+        executeTimeoutMs: z.number().int().positive(),
+        maxResponseBytes: z.number().int().positive(),
+    }),
+    catalogVersion: catalogVersionSchema,
+    publishedAt: z.iso.datetime(),
+});
+
+export const resolveRequestSchema = z.object({
+    query: z.string().trim().min(1).max(4000),
+    locale: localeSchema.optional(),
+    hints: z
+        .object({
+            threadId: z.string().max(128).optional(),
+            recentToolNames: z.array(z.string()).max(20).default([]),
+            turnIndex: z.number().int().min(0).optional(),
+        })
+        .optional(),
+    tokenBudget: z.number().int().min(500).max(20000).optional(),
+    limits: z
+        .object({
+            knowledge: z.number().int().min(0).max(20).default(6),
+            tools: z.number().int().min(0).max(20).default(8),
+            services: z.number().int().min(0).max(20).default(5),
+        })
+        .optional(),
+});
+
+export const resolveResponseSchema = z.object({
+    resolveId: z.uuid(),
+    catalogVersion: catalogVersionSchema,
+    locale: localeSchema,
+    knowledge: z.array(knowledgeChunkSchema),
+    tools: z.array(toolSignatureSchema),
+    services: z.array(serviceCardSchema),
+    sharedShapes: z.array(sharedShapeSchema),
+    budget: z.object({
+        requested: z.number().int(),
+        used: z.number().int(),
+        truncated: z.boolean(),
+    }),
+});
+
+export const searchRequestSchema = z.object({
+    query: z.string().trim().min(1).max(4000),
+    limit: z.number().int().min(1).max(20).default(5),
+    locale: localeSchema.optional(),
+    threadId: z.string().max(128).optional(),
+    service: z.string().max(64).optional(),
+});
+
+export const searchToolsResponseSchema = z.object({
+    catalogVersion: catalogVersionSchema,
+    tools: z.array(toolSignatureSchema),
+    sharedShapes: z.array(sharedShapeSchema),
+});
+
+export const searchServicesResponseSchema = z.object({
+    catalogVersion: catalogVersionSchema,
+    services: z.array(serviceCardSchema),
+    tools: z.array(toolSignatureSchema),
+    sharedShapes: z.array(sharedShapeSchema),
+});
+
+export const searchKnowledgeResponseSchema = z.object({
+    catalogVersion: catalogVersionSchema,
+    knowledge: z.array(knowledgeChunkSchema),
+});
+
+export const executeRequestSchema = z.object({
+    input: z.record(z.string(), z.unknown()).default({}),
+    context: z
+        .object({
+            threadId: z.string().max(128).optional(),
+            userId: z.string().max(128).optional(),
+            locale: localeSchema.optional(),
+        })
+        .optional(),
+});
+
+export const executeResponseSchema = z.object({
+    toolId: z.uuid(),
+    name: z.string(),
+    version: z.number().int().positive(),
+    output: z.unknown(),
+    meta: z.object({
+        upstreamStatus: z.number().int().min(100).max(599),
+        durationMs: z.number().int().min(0),
+        replayed: z.boolean(),
+        truncated: z.boolean(),
+        truncatedPaths: z.array(z.string()),
+        drift: z.array(
+            z.object({
+                path: z.string(),
+                kind: z.enum(JSON_SCHEMA_ISSUE_KINDS),
+            }),
+        ),
+    }),
+});
+
+const runtimeErrorKindSchema = z.enum(RUNTIME_ERROR_KINDS);
+export type RuntimeErrorKind = z.infer<typeof runtimeErrorKindSchema>;
+
+export const runtimeErrorSchema = z.object({
+    error: z.object({
+        kind: runtimeErrorKindSchema,
+        detail: z.string().max(512),
+        retryable: z.boolean(),
+        retryAfterSeconds: z.number().int().positive().optional(),
+        upstreamStatus: z.number().int().min(100).max(599).optional(),
+    }),
+});
+
+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>;

package/contracts/wire.ts

@@ -0,0 +1,143 @@
+/**
+ * The wire contract — every shape that crosses the HTTP/WebSocket boundary
+ * between `@m6d/cortex-server` and the client SDKs (`@m6d/cortex-angular`,
+ * `@m6d/cortex-react`).
+ *
+ * Nothing here has a runtime dependency, and nothing here may grow one: this
+ * file is compiled into an Angular library, a React library and a Bun server
+ * alike.
+ */
+
+export const ATTACHMENT_MIME_TYPES = [
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "application/pdf",
+] as const;
+
+export const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+
+export const MAX_ATTACHMENTS_PER_MESSAGE = 5;
+
+export const ATTACHMENT_STATUSES = ["pending", "described", "failed", "skipped"] as const;
+
+export function checkAttachmentPolicy(contentType: string, sizeBytes: number) {
+    if (!ATTACHMENT_MIME_TYPES.some((type) => type === contentType)) return "type";
+    if (sizeBytes > ATTACHMENT_MAX_BYTES) return "size";
+    return "ok";
+}
+
+export type AttachmentStatus = (typeof ATTACHMENT_STATUSES)[number];
+
+export type AttachmentSummary = {
+    id: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    status: AttachmentStatus;
+    description?: string;
+};
+
+export type ThreadSummary = {
+    id: string;
+    title?: string;
+    createdAt: string;
+    updatedAt: string;
+    isRunning: boolean;
+};
+
+/**
+ * Response of `POST /chat/:chatId/abort`. `aborted: false` means there was no
+ * live run to abort — the turn had already committed — so the caller must not
+ * present the turn as aborted and should read the settled state back instead.
+ */
+export type AbortRunResult = {
+    aborted: 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?: TokenUsage;
+    attachments?: AttachmentSummary[];
+};
+
+/**
+ * A stored message as it is persisted and served. TanStack AI's `UIMessage`
+ * has no metadata field, so cortex owns the envelope: the SDK's parts plus the
+ * server-derived metadata the UI renders on settled messages.
+ *
+ * `TPart` stays generic so this file keeps its zero dependencies — both
+ * sides substitute the SDK's `MessagePart`.
+ */
+export type CortexMessage<TPart = unknown> = {
+    id: string;
+    role: "system" | "user" | "assistant";
+    parts: TPart[];
+    metadata?: MessageMetadata;
+};
+
+export type ThreadCreatedEvent = {
+    type: "thread:created";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadDeletedEvent = {
+    type: "thread:deleted";
+    payload: { threadId: string };
+};
+
+export type ThreadTitleUpdatedEvent = {
+    type: "thread:title-updated";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadRunStartedEvent = {
+    type: "thread:run-started";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadRunFinishedEvent = {
+    type: "thread:run-finished";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadMessagesUpdatedEvent = {
+    type: "thread:messages-updated";
+    payload: { threadId: string; thread: ThreadSummary };
+};
+
+export type ToolProgressEvent = {
+    type: "thread:tool-progress";
+    payload: {
+        threadId: string;
+        toolCallId: string;
+        toolName: string;
+        status: "started" | "finished";
+    };
+};
+
+export type WsEvent =
+    | ThreadCreatedEvent
+    | ThreadDeletedEvent
+    | ThreadTitleUpdatedEvent
+    | ThreadRunStartedEvent
+    | ThreadRunFinishedEvent
+    | ThreadMessagesUpdatedEvent
+    | ToolProgressEvent;

package/dist/contracts/graph/embed.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Embeddings, which both halves of the graph need: `@m6d/cortex-cli` embeds every
+ * concept description as it seeds, `@m6d/cortex-server` embeds every prompt as it
+ * resolves. Two embedders would mean two vector spaces, so there is one.
+ *
+ * TanStack AI removed embeddings, and the graph only ever needed the plain
+ * OpenAI-compatible `/embeddings` call cortex is already configured for — so this
+ * is a bare `fetch`, and this package keeps its zero dependencies.
+ *
+ * Everything under `./graph` is written to the oldest target any consumer builds
+ * against — an Angular library compiles these sources directly — and imports
+ * siblings by their `.js` specifier so one emit serves both `dist` and source.
+ */
+/** Everything cortex needs to reach one OpenAI-compatible embeddings endpoint. */
+export type EmbeddingProviderConfig = {
+    baseURL: string;
+    apiKey: string;
+    modelName: string;
+};
+/** Turns a batch of strings into their vectors, in the order given. */
+export type EmbedFn = (values: string[]) => Promise<number[][]>;
+export declare function createEmbedder(config: EmbeddingProviderConfig): (values: string[]) => Promise<number[][]>;

package/dist/{src/lib → contracts}/graph/helpers.d.ts

@@ -1,39 +1,41 @@
 /**
- * Helper functions for building knowledge graph seed data.
+ * Helper functions for building knowledge graph seed data. Projects author
+ * domains with these; `@m6d/cortex-server` re-exports them so authoring needs
+ * exactly one import path.
  */
-import type { ConceptDef, DomainDef, EndpointDef, EndpointInput, RuleDef, ServiceDef } from "./types.ts";
+import type { ConceptDef, DomainDef, EndpointDef, EndpointInput, RuleDef, ServiceDef } from "./types";
 export declare function defineConcept(def: Omit<ConceptDef, "__brand">): {
-    name: string;
     description: string;
+    name: string;
     aliases?: string[] | undefined;
+    metadata?: Record<string, unknown> | undefined;
     parentConcept?: ConceptDef | undefined;
     governedBy?: RuleDef[] | undefined;
-    metadata?: Record<string, unknown> | undefined;
     __brand: "concept";
 };
 export declare function defineRule(def: Omit<RuleDef, "__brand">): {
-    name: string;
     description: string;
+    name: string;
     metadata?: Record<string, unknown> | undefined;
     __brand: "rule";
 };
 export declare function defineService(def: Omit<ServiceDef, "__brand">): {
-    name: string;
     description: string;
-    governedBy?: RuleDef[] | undefined;
+    name: string;
     metadata?: Record<string, unknown> | undefined;
     builtInId: string;
+    governedBy?: RuleDef[] | undefined;
     belongsTo: ConceptDef;
     __brand: "service";
 };
 export declare function defineDomain(def: Omit<DomainDef, "__brand">): {
-    name: string;
     description: string;
+    name: string;
     metadata?: Record<string, unknown> | undefined;
-    rules?: RuleDef[] | undefined;
     concepts?: ConceptDef[] | undefined;
-    services?: ServiceDef[] | undefined;
     endpoints?: EndpointDef[] | undefined;
+    services?: ServiceDef[] | undefined;
+    rules?: RuleDef[] | undefined;
     __brand: "domain";
 };
 export declare function defineEndpoint(input: EndpointInput): {
@@ -43,12 +45,12 @@ export declare function defineEndpoint(input: EndpointInput): {
     path: string;
     method: "GET" | "POST" | "PUT" | "DELETE";
     propertiesDescriptions: Record<string, string>;
-    params: import("./types.ts").EndpointProperty[];
-    body: import("./types.ts").EndpointProperty[];
-    response: import("./types.ts").EndpointProperty[];
+    params: import("./types").EndpointProperty[];
+    body: import("./types").EndpointProperty[];
+    response: import("./types").EndpointProperty[];
     successStatus: number;
     errorStatuses: number[];
-    responseKind: import("./types.ts").ResponseKind;
+    responseKind: import("./types").ResponseKind;
     queries: ConceptDef[] | undefined;
     mutates: ConceptDef[] | undefined;
     returns: {

package/dist/{src/lib → contracts}/graph/neo4j.d.ts

@@ -1,10 +1,10 @@
 /**
- * Configurable Neo4j HTTP client.
+ * Configurable Neo4j HTTP client, shared by the graph's writer and its reader.
  *
- * Replaces the hardcoded process.env-based client from packages/sample-backend.
- * All configuration is passed explicitly — no environment variables are read.
+ * All configuration is passed explicitly — no environment variables are read —
+ * and the transport is `fetch`, so this package stays dependency-free.
  */
-import type { EmbeddingModel } from "ai";
+import type { EmbedFn } from "./embed";
 export type Neo4jConfig = {
     url: string;
     user: string;
@@ -13,6 +13,6 @@ export type Neo4jConfig = {
 export type Neo4jClient = {
     query(cypher: string, parameters?: Record<string, unknown>): Promise<string>;
 };
-export declare function createNeo4jClient(config: Neo4jConfig, embeddingModel?: EmbeddingModel): {
+export declare function createNeo4jClient(config: Neo4jConfig, embed?: EmbedFn): {
     query: (cypher: string, parameters?: Record<string, unknown>) => Promise<string>;
 };

package/dist/contracts/graph/schema.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The contract between the graph's writer and its reader.
+ *
+ * Seeding lives in `@m6d/cortex-cli` and resolution lives in `@m6d/cortex-server`,
+ * two packages a project installs and upgrades separately. The labels, relationship
+ * types, property names and index name they agree on are this module, here, so
+ * neither side owns the vocabulary the other has to match.
+ *
+ * A mismatch between the two is invisible at runtime: the resolver's Cypher
+ * matches nothing and retrieval comes back empty rather than failing. That is what
+ * `GRAPH_SCHEMA_VERSION` is for — bump it on any change to the shape below. The
+ * CLI stamps the version it wrote onto the graph and the server checks that stamp
+ * on its first resolve, so skew surfaces as an error instead of as silence.
+ */
+export declare const GRAPH_SCHEMA_VERSION = 1;
+export declare const GRAPH_SCHEMA: {
+    readonly label: {
+        readonly domain: "Domain";
+        readonly concept: "Concept";
+        readonly endpoint: "Endpoint";
+        readonly service: "Service";
+        readonly rule: "Rule";
+        /** Stamped with the version above, so a stale graph is detectable later. */
+        readonly marker: "CortexGraph";
+    };
+    readonly rel: {
+        readonly belongsTo: "BELONGS_TO";
+        readonly specializes: "SPECIALIZES";
+        readonly queriedVia: "QUERIED_VIA";
+        readonly mutatedVia: "MUTATED_VIA";
+        readonly returns: "RETURNS";
+        readonly dependsOn: "DEPENDS_ON";
+        readonly governs: "GOVERNS";
+        readonly requestedVia: "REQUESTED_VIA";
+    };
+    readonly prop: {
+        readonly name: "name";
+        readonly description: "description";
+        readonly aliases: "aliases";
+        readonly metadata: "metadata";
+        readonly path: "path";
+        readonly method: "method";
+        readonly params: "params";
+        readonly body: "body";
+        readonly response: "response";
+        readonly propertiesDescriptions: "propertiesDescriptions";
+        readonly successStatus: "successStatus";
+        readonly errorStatuses: "errorStatuses";
+        readonly builtInId: "builtInId";
+        readonly embedding: "embedding";
+        /** On a RETURNS edge: which part of the response carries the concept. */
+        readonly field: "field";
+        /** On a DEPENDS_ON edge. */
+        readonly paramName: "paramName";
+        readonly fromField: "fromField";
+        /** On the marker node. */
+        readonly version: "version";
+    };
+    /** Created by the CLI's seeder, queried by name in the resolver's first hop. */
+    readonly conceptEmbeddingsIndex: "concept_embeddings";
+};
+export type GraphSchema = typeof GRAPH_SCHEMA;

package/dist/{src/lib → contracts}/graph/types.d.ts

@@ -10,7 +10,7 @@ export type EndpointScalarType = "uuid" | "number" | "date" | "datetime" | "stri
 export type EndpointProperty = {
     readonly name: string;
     readonly required: boolean;
-    readonly type: EndpointScalarType | string;
+    readonly type: EndpointScalarType | (string & NonNullable<unknown>);
     readonly isArray?: boolean;
     readonly properties?: readonly EndpointProperty[];
     readonly description?: string;

package/dist/contracts/graph.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The graph contract — the knowledge-graph vocabulary, authoring types and
+ * clients that `@m6d/cortex-cli` writes with and `@m6d/cortex-server` reads
+ * with. `@m6d/cortex-server` re-exports all of it, so a project authoring
+ * domains still has exactly one import path.
+ */
+export type { GraphSchema } from "./graph/schema";
+export { GRAPH_SCHEMA, GRAPH_SCHEMA_VERSION } from "./graph/schema";
+export type { EndpointScalarType, EndpointProperty, ResponseKind, AutoGenerated, ConceptDef, EndpointDef, EndpointInput, ServiceDef, RuleDef, DomainDef, } from "./graph/types";
+export { defineConcept, defineRule, defineService, defineDomain, defineEndpoint, } from "./graph/helpers";
+export type { Neo4jConfig, Neo4jClient } from "./graph/neo4j";
+export { createNeo4jClient } from "./graph/neo4j";
+export type { EmbedFn, EmbeddingProviderConfig } from "./graph/embed";
+export { createEmbedder } from "./graph/embed";

package/dist/contracts/rich-text.d.ts

@@ -0,0 +1,32 @@
+/** One mention token, unanchored and flagless — the editor's tokenizer anchors it, the helpers below add `g`. */
+export declare const MENTION_PATTERN_SOURCE: string;
+export declare function extractMentionedToolIds(text: string): string[];
+/** Replaces each mention token with the tool's current name (falling back to the cached inline name). */
+export declare function renderMentions(text: string, toolNameById: ReadonlyMap<string, string>): string;
+/** Refreshes stale display names inside stored text, keeping the tokens intact. */
+export declare function normalizeMentions(text: string, toolNameById: ReadonlyMap<string, string>): string;
+/** Splits the `{{variables}}` referenced in a text into known and unknown ones. */
+export declare function analyzeVariables<Variable extends string>(text: string, known: ReadonlyArray<Variable>): {
+    variables: Variable[];
+    unknownVariables: string[];
+};
+/** Fills `{{variables}}` with per-request values; unknown names stay verbatim. */
+export declare function substituteVariables(text: string, values: Record<string, string>): string;
+/**
+ * Shifts user-authored headings down so they can never collide with the prompt
+ * skeleton, which owns `##` (sections) and `###` (card titles): `#` becomes
+ * `####`, deeper levels cap at `######`. Setext headings are rewritten as the
+ * equivalent demoted ATX heading, since two-level setext cannot express the
+ * shift. Fenced code is left alone.
+ */
+export declare function demoteHeadings(text: string): string;
+/** The one render step for LLM-bound rich text: resolve mentions, then demote headings. */
+export declare function renderRichText(text: string, toolNameById: ReadonlyMap<string, string>): string;
+/**
+ * Reduces rich text to plain prose for embeddings: mentions become tool names
+ * (cached inline names when no map is given) and markdown syntax is dropped.
+ * ponytail: a regex stripper, not a markdown parser — nested emphasis or exotic
+ * constructs may leave residue; swap in a real parser if retrieval quality
+ * ever shows it.
+ */
+export declare function stripToPlaintext(text: string, toolNameById?: ReadonlyMap<string, string>): string;