@m6d/cortex-server 1.3.0 → 1.5.0

package/src/graph/expand-domains.ts

@@ -0,0 +1,276 @@
+import type { ConceptDef, DomainDef, EndpointDef, RuleDef, ServiceDef } from "./types.ts";
+
+type DomainCollections = {
+    concepts: ConceptDef[];
+    endpoints: EndpointDef[];
+    services: ServiceDef[];
+    rules: RuleDef[];
+};
+
+type OwnershipMaps = {
+    concepts: WeakMap<ConceptDef, string>;
+    endpoints: WeakMap<EndpointDef, string>;
+    services: WeakMap<ServiceDef, string>;
+    rules: WeakMap<RuleDef, string>;
+};
+
+export function expandDomains(domains: Record<string, DomainDef>) {
+    const ownership = createOwnershipMaps(domains);
+    const expanded: Record<string, DomainDef> = {};
+
+    for (const [domainKey, domain] of Object.entries(domains)) {
+        const collections = cloneCollections(domain);
+        const pendingConcepts = [...collections.concepts];
+        const pendingEndpoints = [...collections.endpoints];
+        const pendingServices = [...collections.services];
+
+        while (
+            pendingConcepts.length > 0 ||
+            pendingEndpoints.length > 0 ||
+            pendingServices.length > 0
+        ) {
+            const concept = pendingConcepts.pop();
+            if (concept) {
+                includeConcept({
+                    domainKey,
+                    concept,
+                    ownership,
+                    collections,
+                    pendingConcepts,
+                    pendingEndpoints,
+                });
+            }
+
+            const endpoint = pendingEndpoints.pop();
+            if (endpoint) {
+                includeEndpoint({
+                    domainKey,
+                    endpoint,
+                    ownership,
+                    collections,
+                    pendingConcepts,
+                    pendingEndpoints,
+                });
+            }
+
+            const service = pendingServices.pop();
+            if (service) {
+                includeService({
+                    domainKey,
+                    service,
+                    ownership,
+                    collections,
+                    pendingConcepts,
+                });
+            }
+        }
+
+        expanded[domainKey] = {
+            ...domain,
+            concepts: collections.concepts,
+            endpoints: collections.endpoints,
+            services: collections.services,
+            rules: collections.rules,
+        };
+    }
+
+    return expanded;
+}
+
+function createOwnershipMaps(domains: Record<string, DomainDef>) {
+    const ownership: OwnershipMaps = {
+        concepts: new WeakMap<ConceptDef, string>(),
+        endpoints: new WeakMap<EndpointDef, string>(),
+        services: new WeakMap<ServiceDef, string>(),
+        rules: new WeakMap<RuleDef, string>(),
+    };
+
+    for (const [domainKey, domain] of Object.entries(domains)) {
+        for (const concept of domain.concepts ?? []) {
+            assignOwner(ownership.concepts, concept, domainKey);
+        }
+
+        for (const endpoint of domain.endpoints ?? []) {
+            assignOwner(ownership.endpoints, endpoint, domainKey);
+        }
+
+        for (const service of domain.services ?? []) {
+            assignOwner(ownership.services, service, domainKey);
+        }
+
+        for (const rule of domain.rules ?? []) {
+            assignOwner(ownership.rules, rule, domainKey);
+        }
+    }
+
+    return ownership;
+}
+
+function assignOwner<T extends object>(owners: WeakMap<T, string>, value: T, domainKey: string) {
+    if (!owners.has(value)) {
+        owners.set(value, domainKey);
+    }
+}
+
+function cloneCollections(domain: DomainDef) {
+    return {
+        concepts: [...(domain.concepts ?? [])],
+        endpoints: [...(domain.endpoints ?? [])],
+        services: [...(domain.services ?? [])],
+        rules: [...(domain.rules ?? [])],
+    } satisfies DomainCollections;
+}
+
+function includeConcept(options: {
+    domainKey: string;
+    concept: ConceptDef;
+    ownership: OwnershipMaps;
+    collections: DomainCollections;
+    pendingConcepts: ConceptDef[];
+    pendingEndpoints: EndpointDef[];
+}) {
+    const { domainKey, concept, ownership, collections, pendingConcepts, pendingEndpoints } =
+        options;
+
+    includeRule(domainKey, concept.governedBy ?? [], ownership, collections);
+
+    if (shouldAttach(ownership.concepts, concept, domainKey)) {
+        pushUnique(collections.concepts, concept);
+    }
+
+    if (
+        concept.parentConcept &&
+        shouldAttach(ownership.concepts, concept.parentConcept, domainKey)
+    ) {
+        if (pushUnique(collections.concepts, concept.parentConcept)) {
+            pendingConcepts.push(concept.parentConcept);
+        }
+    }
+
+    for (const endpoint of collections.endpoints) {
+        if (referencesConcept(endpoint, concept)) {
+            includeEndpoint({
+                domainKey,
+                endpoint,
+                ownership,
+                collections,
+                pendingConcepts,
+                pendingEndpoints,
+            });
+        }
+    }
+}
+
+function includeEndpoint(options: {
+    domainKey: string;
+    endpoint: EndpointDef;
+    ownership: OwnershipMaps;
+    collections: DomainCollections;
+    pendingConcepts: ConceptDef[];
+    pendingEndpoints: EndpointDef[];
+}) {
+    const { domainKey, endpoint, ownership, collections, pendingConcepts, pendingEndpoints } =
+        options;
+
+    if (shouldAttach(ownership.endpoints, endpoint, domainKey)) {
+        pushUnique(collections.endpoints, endpoint);
+    }
+
+    includeRule(domainKey, endpoint.governedBy ?? [], ownership, collections);
+
+    for (const concept of endpoint.queries ?? []) {
+        if (
+            shouldAttach(ownership.concepts, concept, domainKey) &&
+            pushUnique(collections.concepts, concept)
+        ) {
+            pendingConcepts.push(concept);
+        }
+    }
+
+    for (const concept of endpoint.mutates ?? []) {
+        if (
+            shouldAttach(ownership.concepts, concept, domainKey) &&
+            pushUnique(collections.concepts, concept)
+        ) {
+            pendingConcepts.push(concept);
+        }
+    }
+
+    for (const returned of endpoint.returns ?? []) {
+        if (
+            shouldAttach(ownership.concepts, returned.concept, domainKey) &&
+            pushUnique(collections.concepts, returned.concept)
+        ) {
+            pendingConcepts.push(returned.concept);
+        }
+    }
+
+    for (const dependency of endpoint.dependsOn ?? []) {
+        if (
+            shouldAttach(ownership.endpoints, dependency.endpoint, domainKey) &&
+            pushUnique(collections.endpoints, dependency.endpoint)
+        ) {
+            pendingEndpoints.push(dependency.endpoint);
+        }
+    }
+}
+
+function includeService(options: {
+    domainKey: string;
+    service: ServiceDef;
+    ownership: OwnershipMaps;
+    collections: DomainCollections;
+    pendingConcepts: ConceptDef[];
+}) {
+    const { domainKey, service, ownership, collections, pendingConcepts } = options;
+
+    if (shouldAttach(ownership.services, service, domainKey)) {
+        pushUnique(collections.services, service);
+    }
+
+    includeRule(domainKey, service.governedBy ?? [], ownership, collections);
+
+    if (
+        shouldAttach(ownership.concepts, service.belongsTo, domainKey) &&
+        pushUnique(collections.concepts, service.belongsTo)
+    ) {
+        pendingConcepts.push(service.belongsTo);
+    }
+}
+
+function includeRule(
+    domainKey: string,
+    rules: readonly RuleDef[],
+    ownership: OwnershipMaps,
+    collections: DomainCollections,
+) {
+    for (const rule of rules) {
+        if (shouldAttach(ownership.rules, rule, domainKey)) {
+            pushUnique(collections.rules, rule);
+        }
+    }
+}
+
+function shouldAttach<T extends object>(owners: WeakMap<T, string>, value: T, domainKey: string) {
+    const owner = owners.get(value);
+    return owner == null || owner === domainKey;
+}
+
+function pushUnique<T extends object>(values: T[], value: T) {
+    if (values.includes(value)) {
+        return false;
+    }
+
+    values.push(value);
+    return true;
+}
+
+function referencesConcept(endpoint: EndpointDef, concept: ConceptDef) {
+    return (
+        endpoint.queries?.includes(concept) ||
+        endpoint.mutates?.includes(concept) ||
+        endpoint.returns?.some(function (returned) {
+            return returned.concept === concept;
+        })
+    );
+}

package/src/graph/generate-cypher.ts

@@ -31,9 +31,12 @@ export function generateCypher(data: DomainDef) {
     const edges: string[] = [];
 
     // -- Domain node --
+    const domainMeta = data.metadata
+        ? `,\n            d.metadata = '${jsonStr(data.metadata)}'`
+        : "";
     nodes.push(
         `MERGE (d:Domain {name: '${esc(data.name)}'})
-        SET d.description = '${esc(data.description)}'`,
+        SET d.description = '${esc(data.description)}'${domainMeta}`,
     );
 
     // -- Concept nodes --
@@ -42,10 +45,11 @@ export function generateCypher(data: DomainDef) {
             c.aliases && c.aliases.length > 0
                 ? `, c.aliases = [${c.aliases.map((a) => `'${esc(a)}'`).join(", ")}]`
                 : "";
+        const conceptMeta = c.metadata ? `, c.metadata = '${jsonStr(c.metadata)}'` : "";
 
         nodes.push(
             `MERGE (c:Concept {name: '${esc(c.name)}'})
-            SET c.description = '${esc(c.description)}'${aliasClause}`,
+            SET c.description = '${esc(c.description)}'${aliasClause}${conceptMeta}`,
         );
 
         edges.push(
@@ -73,6 +77,9 @@ export function generateCypher(data: DomainDef) {
 
     // -- Endpoint nodes --
     for (const ep of data.endpoints ?? []) {
+        const endpointMeta = ep.metadata
+            ? `,\n                e.metadata = '${jsonStr(ep.metadata)}'`
+            : "";
         nodes.push(
             `MERGE (e:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
             SET e.name = '${esc(ep.name)}',
@@ -82,7 +89,7 @@ export function generateCypher(data: DomainDef) {
                 e.response = '${jsonStr(ep.response)}',
                 e.propertiesDescriptions = '${jsonStr(ep.propertiesDescriptions)}',
                 e.successStatus = ${ep.successStatus},
-                e.errorStatuses = [${ep.errorStatuses.join(", ")}]`,
+                e.errorStatuses = [${ep.errorStatuses.join(", ")}]${endpointMeta}`,
         );
 
         for (const concept of ep.queries ?? []) {
@@ -131,10 +138,13 @@ export function generateCypher(data: DomainDef) {
 
     // -- Service nodes --
     for (const svc of data.services ?? []) {
+        const serviceMeta = svc.metadata
+            ? `,\n            s.metadata = '${jsonStr(svc.metadata)}'`
+            : "";
         nodes.push(
             `MERGE (s:Service {builtInId: '${esc(svc.builtInId)}'})
             SET s.name = '${esc(svc.name)}',
-            s.description = '${esc(svc.description)}'`,
+            s.description = '${esc(svc.description)}'${serviceMeta}`,
         );
 
         edges.push(
@@ -154,9 +164,12 @@ export function generateCypher(data: DomainDef) {
 
     // -- Rule nodes --
     for (const rule of data.rules ?? []) {
+        const ruleMeta = rule.metadata
+            ? `,\n            r.metadata = '${jsonStr(rule.metadata)}'`
+            : "";
         nodes.push(
             `MERGE (r:Rule {name: '${esc(rule.name)}'})
-            SET r.description = '${esc(rule.description)}'`,
+            SET r.description = '${esc(rule.description)}'${ruleMeta}`,
         );
     }
 

package/src/graph/helpers.ts

@@ -64,5 +64,6 @@ export function defineEndpoint(input: EndpointInput) {
         returns: input.returns,
         dependsOn: input.dependsOn,
         governedBy: input.governedBy,
+        metadata: input.metadata,
     } satisfies EndpointDef;
 }

package/src/graph/resolver.ts

@@ -50,6 +50,7 @@ export type ResolvedEndpoint = {
     response: string;
     dependencies: EndpointDependency[];
     rules: string[];
+    metadata: string;
 };
 
 export type ResolvedService = {
@@ -58,6 +59,7 @@ export type ResolvedService = {
     builtInId: string;
     description: string;
     rules: string[];
+    metadata: string;
 };
 
 export type ResolvedContext = {
@@ -79,6 +81,7 @@ type EndpointRow = {
     params: string | null;
     body: string | null;
     response: string | null;
+    metadata: string | null;
     dependencies: (EndpointDependency | { depPath: null })[];
     rules: (string | null)[];
 };
@@ -88,6 +91,7 @@ type ServiceRow = {
     serviceName: string;
     builtInId: string;
     description: string | null;
+    metadata: string | null;
     rules: (string | null)[];
 };
 
@@ -158,6 +162,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                     e.params AS params,
                     e.body AS body,
                     e.response AS response,
+                    e.metadata AS metadata,
                     dependencies,
                     collect(DISTINCT rEndpoint.description) +
                     collect(DISTINCT rConcept.description) AS rules`,
@@ -177,6 +182,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                     params: row.params ?? "[]",
                     body: row.body ?? "[]",
                     response: row.response ?? "[]",
+                    metadata: row.metadata ?? "{}",
                     dependencies: row.dependencies.filter(
                         (dep): dep is EndpointDependency => dep.depPath != null,
                     ),
@@ -198,6 +204,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                     svc.name AS serviceName,
                     svc.builtInId AS builtInId,
                     svc.description AS description,
+                    svc.metadata AS metadata,
                     collect(DISTINCT rService.description) +
                     collect(DISTINCT rConcept.description) AS rules`,
             { names: conceptNames },
@@ -210,6 +217,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                     serviceName: row.serviceName,
                     builtInId: row.builtInId,
                     description: row.description ?? "",
+                    metadata: row.metadata ?? "{}",
                     rules: row.rules.filter((rule): rule is string => Boolean(rule)),
                 };
             }),
@@ -239,6 +247,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                         e.params AS params,
                         e.body AS body,
                         e.response AS response,
+                        e.metadata AS metadata,
                         dependencies,
                         collect(DISTINCT rEndpoint.description) +
                         collect(DISTINCT rConcept.description) AS rules`,
@@ -259,6 +268,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                         params: row.params ?? "[]",
                         body: row.body ?? "[]",
                         response: row.response ?? "[]",
+                        metadata: row.metadata ?? "{}",
                         dependencies: row.dependencies.filter(
                             (dep): dep is EndpointDependency => dep.depPath != null,
                         ),

package/src/graph/seed.ts

@@ -10,6 +10,7 @@ import type { EmbeddingModel } from "ai";
 import { embed } from "ai";
 import type { Neo4jClient, Neo4jConfig } from "./neo4j.ts";
 import { createNeo4jClient } from "./neo4j.ts";
+import { expandDomains } from "./expand-domains.ts";
 import { generateCypher, type GeneratedCypher } from "./generate-cypher.ts";
 import type { DomainDef } from "./types.ts";
 import { validateDomain } from "./validate.ts";
@@ -122,8 +123,10 @@ async function generateEmbeddings(client: Neo4jClient, embeddingConfig: Embeddin
 // ---------------------------------------------------------------------------
 
 export async function seedGraph(config: SeedGraphConfig, domains: Record<string, DomainDef>) {
+    const expandedDomains = expandDomains(domains);
+
     // Validate all domains
-    const validationErrors = Object.entries(domains).flatMap(([name, domain]) =>
+    const validationErrors = Object.entries(expandedDomains).flatMap(([name, domain]) =>
         validateDomain(domain).map((err) => `[${name}] ${err}`),
     );
 
@@ -133,7 +136,7 @@ export async function seedGraph(config: SeedGraphConfig, domains: Record<string,
     }
 
     const client = createNeo4jClient(config.neo4j, config.embedding.model);
-    const targets = Object.entries(domains);
+    const targets = Object.entries(expandedDomains);
 
     console.log(`Seeding ${targets.length} domain(s)...`);
 

package/src/graph/types.ts

@@ -52,6 +52,7 @@ export type ConceptDef = {
     aliases?: string[];
     parentConcept?: ConceptDef;
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 
 // ---------------------------------------------------------------------------
@@ -84,6 +85,7 @@ export type EndpointDef = {
     }[];
 
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 
 // ---------------------------------------------------------------------------
@@ -112,6 +114,7 @@ export type EndpointInput = {
     }[];
 
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 
 // ---------------------------------------------------------------------------
@@ -125,6 +128,7 @@ export type ServiceDef = {
     builtInId: string;
     belongsTo: ConceptDef;
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 
 // ---------------------------------------------------------------------------
@@ -135,6 +139,7 @@ export type RuleDef = {
     readonly __brand: "rule";
     name: string;
     description: string;
+    metadata?: Record<string, unknown>;
 };
 
 // ---------------------------------------------------------------------------
@@ -149,4 +154,5 @@ export type DomainDef = {
     endpoints?: EndpointDef[];
     services?: ServiceDef[];
     rules?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };

package/src/index.ts

@@ -7,6 +7,8 @@ export type {
     StorageConfig,
 } from "./config";
 
+export type { ContextConfig, ThreadContextMeta } from "./ai/context/types";
+
 // Types consumers may need
 export type { Thread, AppEnv } from "./types";
 

package/src/routes/chat.ts

@@ -5,6 +5,9 @@ import { HTTPException } from "hono/http-exception";
 import type { CortexAppEnv } from "../types.ts";
 import { requireAuth } from "../auth/middleware.ts";
 import { stream } from "../ai/index.ts";
+import { subscribe, abortStream } from "../ai/active-streams.ts";
+import { notify } from "../ws/index.ts";
+import { toThreadSummary } from "../types.ts";
 
 export function createChatRoutes() {
     const app = new Hono<CortexAppEnv>();
@@ -21,18 +24,60 @@ export function createChatRoutes() {
         ),
         async function (c) {
             const config = c.get("agentConfig");
+            const agentId = c.get("agentId");
             const { id: userId, token } = c.get("user");
             const { messages, id: threadId } = c.req.valid("json");
 
             const thread = await config.db.threads.getById(userId, threadId);
 
-            if (!thread) {
+            if (!thread || thread.agentId !== agentId) {
                 throw new HTTPException(404, { message: "Not found" });
             }
 
-            return stream(messages, thread, userId, token, config, c.req.raw.signal);
+            return stream(messages, thread, userId, token, config);
         },
     );
 
+    app.get("/chat/:chatId/stream", requireAuth, async function (c) {
+        const config = c.get("agentConfig");
+        const agentId = c.get("agentId");
+        const chatId = c.req.param("chatId");
+        const thread = await config.db.threads.getById(c.get("user").id, chatId);
+        if (!thread || thread.agentId !== agentId) {
+            throw new HTTPException(404, { message: "Not found" });
+        }
+
+        const subscriberStream = subscribe(chatId);
+        if (!subscriberStream) {
+            return c.body(null, 204);
+        }
+
+        return new Response(subscriberStream.pipeThrough(new TextEncoderStream()), {
+            headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            },
+        });
+    });
+
+    app.post("/chat/:chatId/abort", requireAuth, async function (c) {
+        const config = c.get("agentConfig");
+        const agentId = c.get("agentId");
+        const userId = c.get("user").id;
+        const chatId = c.req.param("chatId");
+        const thread = await config.db.threads.getById(userId, chatId);
+        if (!thread || thread.agentId !== agentId) {
+            throw new HTTPException(404, { message: "Not found" });
+        }
+
+        abortStream(chatId);
+        notify(userId, agentId, {
+            type: "thread:run-finished",
+            payload: { thread: toThreadSummary(thread, false) },
+        });
+        return c.body(null, 204);
+    });
+
     return app;
 }

package/src/routes/threads.ts

@@ -4,6 +4,9 @@ import z from "zod";
 import type { CortexAppEnv } from "../types.ts";
 import { requireAuth } from "../auth/middleware.ts";
 import { generateTitle } from "../ai/index.ts";
+import { abortStream, isStreamRunning } from "../ai/active-streams.ts";
+import { notify } from "../ws/index.ts";
+import { toThreadSummary } from "../types.ts";
 
 export function createThreadRoutes() {
     const app = new Hono<CortexAppEnv>();
@@ -13,7 +16,7 @@ export function createThreadRoutes() {
         const agentId = c.get("agentId");
         const threads = await config.db.threads
             .list(c.get("user").id, agentId)
-            .then((x) => x.map((y) => ({ id: y.id, title: y.title, createdAt: y.createdAt })));
+            .then((x) => x.map((y) => toThreadSummary(y, isStreamRunning(y.id))));
         return c.json(threads);
     });
 
@@ -24,28 +27,55 @@ export function createThreadRoutes() {
         async function (c) {
             const config = c.get("agentConfig");
             const agentId = c.get("agentId");
+            const userId = c.get("user").id;
             const { prompt } = c.req.valid("json");
-            const { id, createdAt, title } = await config.db.threads.create(
-                c.get("user").id,
-                agentId,
-            );
-            generateTitle(id, prompt, c.get("user").id, config);
-            return c.json({ id, title, createdAt });
+            const thread = await config.db.threads.create(userId, agentId);
+
+            notify(userId, agentId, {
+                type: "thread:created",
+                payload: { thread: toThreadSummary(thread, false) },
+            });
+
+            generateTitle(thread.id, prompt, userId, config);
+
+            return c.json(toThreadSummary(thread, false));
         },
     );
 
     app.delete("/threads/:threadId", requireAuth, async function (c) {
         const config = c.get("agentConfig");
+        const agentId = c.get("agentId");
+        const userId = c.get("user").id;
         const threadId = c.req.param("threadId");
-        await config.db.threads.delete(c.get("user").id, threadId);
+
+        const thread = await config.db.threads.getById(userId, threadId);
+        if (!thread || thread.agentId !== agentId) {
+            return c.body(null, 404);
+        }
+
+        abortStream(threadId);
+        await config.db.threads.delete(userId, threadId);
+
+        notify(userId, agentId, {
+            type: "thread:deleted",
+            payload: { threadId },
+        });
+
         return c.body(null, 204);
     });
 
     app.get("/threads/:threadId/messages", requireAuth, async function (c) {
         const config = c.get("agentConfig");
+        const agentId = c.get("agentId");
+        const userId = c.get("user").id;
         const threadId = c.req.param("threadId");
+        const thread = await config.db.threads.getById(userId, threadId);
+        if (!thread || thread.agentId !== agentId) {
+            return c.body(null, 404);
+        }
+
         const messages = await config.db.messages
-            .list(c.get("user").id, threadId)
+            .list(userId, threadId)
             .then((x) => x.map((y) => y.content));
         return c.json(messages);
     });
@@ -56,8 +86,15 @@ export function createThreadRoutes() {
         zValidator("json", z.object({ session: z.record(z.unknown()) })),
         async function (c) {
             const config = c.get("agentConfig");
+            const agentId = c.get("agentId");
+            const userId = c.get("user").id;
             const threadId = c.req.param("threadId");
             const { session } = c.req.valid("json");
+            const thread = await config.db.threads.getById(userId, threadId);
+            if (!thread || thread.agentId !== agentId) {
+                return c.body(null, 404);
+            }
+
             await config.db.threads.updateSession(threadId, session);
             return c.body(null, 204);
         },