@m6d/cortex-server 1.8.0 → 2.0.0

package/README.md

@@ -1,6 +1,8 @@
 # @m6d/cortex-server
 
-Multi-agent AI chat server built on Hono + Bun. Supports MSSQL persistence, MinIO file storage, Neo4j knowledge graphs, and AI streaming with tool execution.
+Multi-agent AI chat server built on Hono + Bun. Supports MSSQL or Postgres persistence, MinIO file storage, Neo4j knowledge graphs, and AI streaming with tool execution.
+
+This package is a **runtime** library: it serves requests, resolves against the knowledge graph on every prompt, and exports the `define*` helpers you author domains with. Generation and seeding are not here — seeding the graph and generating endpoint schemas from Swagger are [`@m6d/cortex-cli`](https://www.npmjs.com/package/@m6d/cortex-cli) commands (`cortex graph seed`, `cortex swagger sync`). What the two share is the graph contract — `GRAPH_SCHEMA`, `GRAPH_SCHEMA_VERSION`, the `define*` helpers and their types, the Neo4j client and the embedder — which lives in the private `@cortex/contracts` workspace package (`internal/contracts`) and is vendored into this package's tarball at pack time. It is all re-exported from here, so authoring your domains stays one import. The CLI stamps the schema version it seeded onto the graph; this package reads that stamp on its first resolve and refuses a graph it cannot read, instead of quietly retrieving nothing.
 
 ## Usage
 
@@ -9,6 +11,7 @@ import { createCortex } from "@m6d/cortex-server";
 
 const cortex = createCortex({
     database: {
+        // Or `type: "postgres"` with a postgres:// connection string.
         type: "mssql",
         connectionString: process.env.DB_CONNECTION_STRING!,
     },
@@ -35,7 +38,7 @@ const cortex = createCortex({
         dimension: 1536,
     },
     neo4j: {
-        url: "bolt://localhost:7687",
+        url: "http://localhost:7474",
         user: "neo4j",
         password: "password",
     },
@@ -55,7 +58,9 @@ export default {
 };
 ```
 
-`cortex.serve()` is async — it runs database migrations on startup.
+`cortex.serve()` is async — it runs database migrations on startup, from the migration history belonging to the configured dialect.
+
+Only `database`, `model`, and `agents` are required for a minimal setup. `storage` enables attachment uploads/downloads, `embedding` is only required when `neo4j` graph features are configured, and agent `systemPrompt` defaults to an empty prompt when omitted. An optional `redis: { url, streamTtlSeconds? }` backs resumable streams with Redis so runs survive reconnects, reloads, and multiple server instances; without it an in-memory, single-process fallback is used.
 
 Each key in `agents` becomes a route prefix (e.g. `assistant` → `/agents/assistant/...`). Agents can define per-agent `systemPrompt`, `tools`, `backendFetch`, `loadSessionData`, `resolveRequestContext`, and lifecycle hooks (`onToolCall`, `onStreamFinish`).
 

package/contracts/README.md

@@ -0,0 +1,23 @@
+# @cortex/contracts
+
+The shapes both sides of a cortex boundary must agree on. Private on purpose —
+it never publishes; each publishable package carries its own copy:
+
+- `@m6d/cortex-server` and `@m6d/cortex-cli` publish raw source, so their
+  `prepack` vendors a copy of this directory into the tarball (`contracts/` and
+  `src/contracts/` respectively), resolved there by their shipped tsconfig paths.
+- `@m6d/cortex-angular` and `@m6d/cortex-react` compile the parts they import
+  into their build artifacts.
+
+Three boundaries, one subpath each:
+
+| import                      | boundary                                                      |
+| --------------------------- | ------------------------------------------------------------- |
+| `@cortex/contracts/wire`    | chat client ↔ server (HTTP/WebSocket types)                   |
+| `@cortex/contracts/runtime` | cortex-cc console ↔ server runtime API (zod schemas)          |
+| `@cortex/contracts/graph`   | graph authoring (cli) ↔ server (vocabulary, helpers, clients) |
+
+Everything is consumed as TypeScript source — no build, no dist. Nothing here
+has a runtime dependency beyond zod (for `/runtime`), and nothing here may grow
+one: these files are compiled into an Angular library, a React library, a CLI
+and a Bun server alike.

package/contracts/graph/embed.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 function createEmbedder(config: EmbeddingProviderConfig) {
+    const url = `${config.baseURL.replace(/\/+$/, "")}/embeddings`;
+
+    return async function embed(values: string[]) {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify({ model: config.modelName, input: values }),
+        });
+
+        if (!response.ok) {
+            throw new Error(
+                `Embedding request failed (${response.status}): ${await response.text()}`,
+            );
+        }
+
+        // The API is free to return entries out of order; `index` is authoritative.
+        const body = (await response.json()) as { data: { index: number; embedding: number[] }[] };
+        return [...body.data]
+            .sort((left, right) => left.index - right.index)
+            .map((entry) => entry.embedding);
+    };
+}

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

@@ -1,5 +1,7 @@
 /**
- * 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 {
@@ -9,11 +11,7 @@ import type {
     EndpointInput,
     RuleDef,
     ServiceDef,
-} from "./types.ts";
-
-// ---------------------------------------------------------------------------
-// Identity helpers
-// ---------------------------------------------------------------------------
+} from "./types";
 
 export function defineConcept(def: Omit<ConceptDef, "__brand">) {
     return { __brand: "concept" as const, ...def };
@@ -31,10 +29,6 @@ export function defineDomain(def: Omit<DomainDef, "__brand">) {
     return { __brand: "domain" as const, ...def };
 }
 
-// ---------------------------------------------------------------------------
-// Endpoint builder
-// ---------------------------------------------------------------------------
-
 export function defineEndpoint(input: EndpointInput) {
     const propertiesDescriptions = Object.fromEntries(
         Object.entries({

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

@@ -1,16 +1,11 @@
 /**
- * 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 { embed } from "ai";
-
-// ---------------------------------------------------------------------------
-// Config types
-// ---------------------------------------------------------------------------
+import type { EmbedFn } from "./embed";
 
 export type Neo4jConfig = {
     url: string;
@@ -22,33 +17,21 @@ export type Neo4jClient = {
     query(cypher: string, parameters?: Record<string, unknown>): Promise<string>;
 };
 
-// ---------------------------------------------------------------------------
-// Client factory
-// ---------------------------------------------------------------------------
-
-export function createNeo4jClient(config: Neo4jConfig, embeddingModel?: EmbeddingModel) {
+export function createNeo4jClient(config: Neo4jConfig, embed?: EmbedFn) {
     async function query(cypher: string, parameters?: Record<string, unknown>) {
         // Auto-embed parameters whose keys start with '#'
         const embeddedParams = Object.keys(parameters ?? {}).filter((x) => x.startsWith("#"));
 
         if (embeddedParams.length) {
-            if (!embeddingModel) {
-                throw new Error("An embedding model is required when using # parameters");
+            if (!embed) {
+                throw new Error("An embedder is required when using # parameters");
             }
 
-            const embeddingResults = await Promise.all(
-                embeddedParams.map(
-                    async (x) =>
-                        await embed({
-                            model: embeddingModel,
-                            value: parameters![x] as string,
-                        }),
-                ),
-            );
+            const embeddings = await embed(embeddedParams.map((k) => parameters![k] as string));
 
             embeddedParams.forEach((k, idx) => {
                 delete parameters![k];
-                parameters![k.slice(1)] = embeddingResults[idx]!.embedding;
+                parameters![k.slice(1)] = embeddings[idx]!;
             });
         }
 
@@ -77,13 +60,17 @@ export function createNeo4jClient(config: Neo4jConfig, embeddingModel?: Embeddin
         }
 
         const result = (await response.json()) as {
-            errors?: { message: string }[];
+            errors?: { code?: string; message: string }[];
             results: { columns: string[]; data: { row: unknown[] }[] }[];
         };
 
         if (result.errors && result.errors.length > 0) {
+            // `code` rides alongside the message rather than inside it: it is the
+            // one-line identifier a report shows, and existing readers of
+            // `message` keep seeing exactly what they saw before.
             return JSON.stringify({
                 error: true,
+                code: result.errors[0]!.code,
                 message: result.errors.map((e) => e.message).join("; "),
             });
         }

package/contracts/graph/schema.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 const GRAPH_SCHEMA_VERSION = 1;
+
+export const GRAPH_SCHEMA = {
+    label: {
+        domain: "Domain",
+        concept: "Concept",
+        endpoint: "Endpoint",
+        service: "Service",
+        rule: "Rule",
+        /** Stamped with the version above, so a stale graph is detectable later. */
+        marker: "CortexGraph",
+    },
+    rel: {
+        belongsTo: "BELONGS_TO",
+        specializes: "SPECIALIZES",
+        queriedVia: "QUERIED_VIA",
+        mutatedVia: "MUTATED_VIA",
+        returns: "RETURNS",
+        dependsOn: "DEPENDS_ON",
+        governs: "GOVERNS",
+        requestedVia: "REQUESTED_VIA",
+    },
+    prop: {
+        name: "name",
+        description: "description",
+        aliases: "aliases",
+        metadata: "metadata",
+        path: "path",
+        method: "method",
+        params: "params",
+        body: "body",
+        response: "response",
+        propertiesDescriptions: "propertiesDescriptions",
+        successStatus: "successStatus",
+        errorStatuses: "errorStatuses",
+        builtInId: "builtInId",
+        embedding: "embedding",
+        /** On a RETURNS edge: which part of the response carries the concept. */
+        field: "field",
+        /** On a DEPENDS_ON edge. */
+        paramName: "paramName",
+        fromField: "fromField",
+        /** On the marker node. */
+        version: "version",
+    },
+    /** Created by the CLI's seeder, queried by name in the resolver's first hop. */
+    conceptEmbeddingsIndex: "concept_embeddings",
+} as const;
+
+export type GraphSchema = typeof GRAPH_SCHEMA;

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

@@ -7,10 +7,6 @@
  * - Services are concept associations (no hardcoded endpoint steps).
  */
 
-// ---------------------------------------------------------------------------
-// Endpoint property model (v2)
-// ---------------------------------------------------------------------------
-
 export type EndpointScalarType =
     | "uuid"
     | "number"
@@ -24,7 +20,8 @@ export type EndpointScalarType =
 export type EndpointProperty = {
     readonly name: string;
     readonly required: boolean;
-    readonly type: EndpointScalarType | string;
+    // NonNullable<unknown> keeps the literal union visible to autocomplete.
+    readonly type: EndpointScalarType | (string & NonNullable<unknown>);
     readonly isArray?: boolean;
     readonly properties?: readonly EndpointProperty[];
     readonly description?: string;
@@ -41,10 +38,6 @@ export type AutoGenerated = {
     readonly responseKind?: ResponseKind;
 };
 
-// ---------------------------------------------------------------------------
-// Concept descriptor
-// ---------------------------------------------------------------------------
-
 export type ConceptDef = {
     readonly __brand: "concept";
     name: string;
@@ -55,10 +48,6 @@ export type ConceptDef = {
     metadata?: Record<string, unknown>;
 };
 
-// ---------------------------------------------------------------------------
-// Endpoint descriptor (v2)
-// ---------------------------------------------------------------------------
-
 export type EndpointDef = {
     readonly __brand: "endpoint";
     name: string;
@@ -88,10 +77,6 @@ export type EndpointDef = {
     metadata?: Record<string, unknown>;
 };
 
-// ---------------------------------------------------------------------------
-// EndpointInput
-// ---------------------------------------------------------------------------
-
 export type EndpointInput = {
     name: string;
     path: string;
@@ -117,10 +102,6 @@ export type EndpointInput = {
     metadata?: Record<string, unknown>;
 };
 
-// ---------------------------------------------------------------------------
-// Service descriptor (v2)
-// ---------------------------------------------------------------------------
-
 export type ServiceDef = {
     readonly __brand: "service";
     name: string;
@@ -131,10 +112,6 @@ export type ServiceDef = {
     metadata?: Record<string, unknown>;
 };
 
-// ---------------------------------------------------------------------------
-// Rule descriptor
-// ---------------------------------------------------------------------------
-
 export type RuleDef = {
     readonly __brand: "rule";
     name: string;
@@ -142,10 +119,6 @@ export type RuleDef = {
     metadata?: Record<string, unknown>;
 };
 
-// ---------------------------------------------------------------------------
-// Domain descriptor
-// ---------------------------------------------------------------------------
-
 export type DomainDef = {
     readonly __brand: "domain";
     name: string;

package/contracts/graph.ts

@@ -0,0 +1,36 @@
+/**
+ * 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/contracts/runtime.ts

@@ -0,0 +1,208 @@
+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"] as const;
+
+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>;