@m6d/cortex-server 1.7.0 → 2.0.0

package/src/lib/ai/interceptors/request-interceptor.ts

@@ -0,0 +1,89 @@
+import type { DatabaseAdapter } from "@/adapters/database/index";
+import type { StorageAdapter } from "@/adapters/storage/index";
+import { streamToBase64 } from "@/ai/helpers";
+
+export type ResolvedFile = {
+    name: string;
+    bytes: string;
+};
+
+export type RequestInterceptorOptions = {
+    transformFile?: (file: ResolvedFile) => unknown;
+};
+
+export function createRequestInterceptor(
+    db: DatabaseAdapter,
+    storage: StorageAdapter,
+    options: RequestInterceptorOptions & { threadId: string; userId: string },
+) {
+    const transformFile = options.transformFile ?? ((file: ResolvedFile) => file);
+
+    return async function resolveRequestBody(body: Record<string, unknown>) {
+        const resolvedAttachments = new Map<string, { value: unknown }>();
+        const pending = Object.entries(body).map(([key, value]) => ({
+            value,
+            replace: (resolved: unknown) => {
+                body[key] = resolved;
+            },
+        }));
+
+        async function resolveAttachment(id: string) {
+            const cached = resolvedAttachments.get(id);
+            if (cached) return cached;
+
+            const attachment = await db.attachments.getById(id, options.userId);
+            if (!attachment || attachment.threadId !== options.threadId) {
+                throw new Error(`Attachment "${id}" is not available in this thread`);
+            }
+
+            let bytes: string;
+            try {
+                bytes = await streamToBase64(await storage.stream(attachment.storageKey));
+            } catch (error) {
+                throw new Error(`Attachment "${id}" could not be loaded from storage`, {
+                    cause: error,
+                });
+            }
+            const resolved = { value: transformFile({ name: attachment.filename, bytes }) };
+            resolvedAttachments.set(id, resolved);
+            return resolved;
+        }
+
+        while (pending.length) {
+            const { value, replace } = pending.pop()!;
+
+            if (Array.isArray(value)) {
+                const items: unknown[] = value;
+                pending.push(
+                    ...items.map((child, index) => ({
+                        value: child,
+                        replace: (resolved: unknown) => {
+                            items[index] = resolved;
+                        },
+                    })),
+                );
+                continue;
+            }
+
+            if (typeof value === "object" && value !== null) {
+                const object = value as Record<string, unknown>;
+                pending.push(
+                    ...Object.entries(object).map(([key, child]) => ({
+                        value: child,
+                        replace: (resolved: unknown) => {
+                            object[key] = resolved;
+                        },
+                    })),
+                );
+                continue;
+            }
+
+            if (typeof value !== "string" || !value.startsWith("attachment#")) continue;
+
+            const resolved = await resolveAttachment(value.slice("attachment#".length));
+            replace(resolved.value);
+        }
+
+        return body;
+    };
+}

package/src/lib/ai/prompt.ts

@@ -0,0 +1,355 @@
+import type { ResolvedContext, ResolvedEndpoint, ResolvedService } from "@/graph/resolver";
+import type { PromptContext, ResolvedCortexAgentConfig } from "@/config";
+import type { Thread } from "@/types";
+import type { CcPromptInput } from "@/cc/format";
+import { buildCcSection } from "@/cc/format";
+
+/**
+ * Resolves session data for the thread, loading from the configured
+ * session loader if not already cached on the thread.
+ */
+export async function resolveSession(
+    config: ResolvedCortexAgentConfig,
+    thread: Thread,
+    token: string,
+) {
+    let session = thread.session;
+
+    if (!session && config.loadSessionData) {
+        session = await config.loadSessionData(token);
+        // Persist to DB for future cache hits
+        await config.db.threads.updateSession(thread.id, session);
+        thread.session = session;
+    }
+
+    return session;
+}
+
+export async function buildSystemPrompt(
+    config: ResolvedCortexAgentConfig,
+    resolved: ResolvedContext | null,
+    promptContext: PromptContext,
+    cc?: CcPromptInput,
+    attachmentListing?: string,
+) {
+    // Resolve the consumer's base system prompt
+    let basePrompt: string;
+    if (typeof config.systemPrompt === "function") {
+        basePrompt = await config.systemPrompt(promptContext);
+    } else {
+        basePrompt = config.systemPrompt ?? "";
+    }
+
+    const sections: string[] = basePrompt ? [basePrompt] : [];
+
+    // Pre-resolved endpoints from knowledge graph
+    if (resolved) {
+        sections.push(buildResolvedSection(resolved));
+    }
+
+    // Control Center: published prompt + per-turn resolved catalog section
+    if (cc) {
+        const ccSection = buildCcSection(cc);
+        if (ccSection) sections.push(ccSection);
+    }
+
+    if (attachmentListing) {
+        sections.push(attachmentListing);
+    }
+
+    return sections.join("\n");
+}
+
+type SchemaField = {
+    name: string;
+    required?: boolean;
+    type?: string;
+    isArray?: boolean;
+    properties?: SchemaField[];
+};
+
+/** Compression layer 2. Compact param/body: `name?: type, nested?: {a: string, b: number}[]` */
+function compactParamFields(fields: SchemaField[]): string {
+    return fields
+        .map((f) => {
+            const opt = f.required ? "" : "?";
+            const arr = f.isArray ? "[]" : "";
+            if (f.properties && f.properties.length > 0) {
+                return `${f.name}${opt}: {${compactParamFields(f.properties)}}${arr}`;
+            }
+            return `${f.name}${opt}: ${f.type ?? "unknown"}${arr}`;
+        })
+        .join(", ");
+}
+
+function compactParams(jsonStr: string) {
+    try {
+        const fields = JSON.parse(jsonStr) as SchemaField[];
+        if (!Array.isArray(fields) || fields.length === 0) return "(none)";
+        return compactParamFields(fields);
+    } catch {
+        return jsonStr;
+    }
+}
+
+/** Compact response: `items[].{id, employee.{id, name.{ar, en}}}, count` */
+function compactResponseFields(fields: SchemaField[]): string {
+    return fields
+        .map((f) => {
+            const arr = f.isArray ? "[]" : "";
+            if (f.properties && f.properties.length > 0) {
+                return `${f.name}${arr}.{${compactResponseFields(f.properties)}}`;
+            }
+            return f.name;
+        })
+        .join(", ");
+}
+
+function compactResponse(jsonStr: string) {
+    try {
+        const fields = JSON.parse(jsonStr) as SchemaField[];
+        if (!Array.isArray(fields) || fields.length === 0) return "(none)";
+        return compactResponseFields(fields);
+    } catch {
+        return jsonStr;
+    }
+}
+
+/**
+ * Compression layer 1. Endpoints reached via several concepts arrive as
+ * duplicates sharing one method+path; collapsing them first means every later
+ * layer works on one entry per real endpoint.
+ */
+type GroupedEndpoint = Omit<ResolvedEndpoint, "concept"> & {
+    concepts: string[];
+};
+
+function addUnique<T>(list: T[], value: T, matches: (a: T, b: T) => boolean = Object.is) {
+    if (!list.some((item) => matches(item, value))) {
+        list.push(value);
+    }
+}
+
+/** Folds a second endpoint sharing this method and path into the group already collected. */
+function mergeEndpoint(existing: GroupedEndpoint, ep: ResolvedEndpoint) {
+    addUnique(existing.concepts, ep.concept);
+
+    for (const rule of ep.rules) {
+        addUnique(existing.rules, rule);
+    }
+    for (const dep of ep.dependencies) {
+        addUnique(
+            existing.dependencies,
+            dep,
+            (a, b) => a.depPath === b.depPath && a.paramName === b.paramName,
+        );
+    }
+}
+
+/** The arrays are copied because merging mutates them, and the source endpoint is shared. */
+function toGroup(ep: ResolvedEndpoint) {
+    const { concept, ...rest } = ep;
+    return {
+        ...rest,
+        concepts: [concept],
+        dependencies: [...ep.dependencies],
+        rules: [...ep.rules],
+    };
+}
+
+function groupEndpointsBySignature(endpoints: ResolvedEndpoint[]) {
+    const groups = new Map<string, GroupedEndpoint>();
+
+    for (const ep of endpoints) {
+        const key = `${ep.method}|${ep.path}`;
+        const existing = groups.get(key);
+
+        if (existing) {
+            mergeEndpoint(existing, ep);
+        } else {
+            groups.set(key, toGroup(ep));
+        }
+    }
+
+    return Array.from(groups.values());
+}
+
+/**
+ * Compression layer 3. Hoists rules repeated across endpoints into one global
+ * section, so a rule governing twenty endpoints is stated once, not twenty times.
+ */
+function extractSharedRules(groups: GroupedEndpoint[], services: ResolvedService[]) {
+    const ruleCounts = new Map<string, number>();
+
+    for (const ep of groups) {
+        for (const rule of ep.rules) {
+            ruleCounts.set(rule, (ruleCounts.get(rule) ?? 0) + 1);
+        }
+    }
+    for (const svc of services) {
+        for (const rule of svc.rules) {
+            ruleCounts.set(rule, (ruleCounts.get(rule) ?? 0) + 1);
+        }
+    }
+
+    const sharedRules = [...ruleCounts.entries()]
+        .filter(([, count]) => count >= 2)
+        .map(([rule]) => rule);
+
+    const sharedSet = new Set(sharedRules);
+
+    return {
+        sharedRules,
+        groups: groups.map((ep) => ({
+            ...ep,
+            rules: ep.rules.filter((r) => !sharedSet.has(r)),
+        })),
+        services: services.map((svc) => ({
+            ...svc,
+            rules: svc.rules.filter((r) => !sharedSet.has(r)),
+        })),
+    };
+}
+
+/**
+ * Compression layer 4. Endpoints returning an identical response schema get one
+ * named shape definition and a reference each, instead of repeating the schema.
+ */
+type ResponseShapeRefs = {
+    shapeDefs: { name: string; content: string }[];
+    refMap: Map<string, string>;
+};
+
+function buildResponseShapeRefs(groups: GroupedEndpoint[]) {
+    // Key on the raw JSON string (byte-identical for endpoints sharing the same
+    // Endpoint node in Neo4j). Fall back to the compact string for cases where
+    // different raw JSON produces the same compact shape.
+    const rawToEndpoints = new Map<string, string[]>();
+
+    for (const ep of groups) {
+        if (ep.response === "[]") continue;
+        const existing = rawToEndpoints.get(ep.response);
+        if (existing) {
+            existing.push(`${ep.method} ${ep.path}`);
+        } else {
+            rawToEndpoints.set(ep.response, [`${ep.method} ${ep.path}`]);
+        }
+    }
+
+    // Second pass: also group by compact output to catch different raw JSON
+    // that normalizes to the same shape
+    const compactToRaws = new Map<string, Set<string>>();
+    for (const raw of rawToEndpoints.keys()) {
+        const compact = compactResponse(raw);
+        const existing = compactToRaws.get(compact);
+        if (existing) {
+            existing.add(raw);
+        } else {
+            compactToRaws.set(compact, new Set([raw]));
+        }
+    }
+
+    // Merge: a shape is shared if its raw string appears on 2+ endpoints,
+    // OR if multiple raw strings compact to the same output
+    const shapeDefs: { name: string; content: string }[] = [];
+    const refMap = new Map<string, string>();
+    let idx = 1;
+
+    for (const [compact, raws] of compactToRaws) {
+        let totalEndpoints = 0;
+        for (const raw of raws) {
+            totalEndpoints += rawToEndpoints.get(raw)!.length;
+        }
+
+        if (totalEndpoints >= 2) {
+            const name = `$R${idx++}`;
+            shapeDefs.push({ name, content: compact });
+            refMap.set(compact, name);
+        }
+    }
+
+    return { shapeDefs, refMap };
+}
+
+/** A heading and its lines, or nothing at all when there are no lines to show. */
+function renderSection(heading: string, lines: string[]) {
+    if (lines.length === 0) return [];
+    return [`\n### ${heading}`, ...lines.map((line) => `\n${line}`)];
+}
+
+function renderEndpoint(ep: GroupedEndpoint, refMap: ResponseShapeRefs["refMap"]) {
+    const compactResp = compactResponse(ep.response);
+    const body = compactParams(ep.body);
+
+    const lines = [
+        `\n### ${ep.name} — ${ep.method} ${ep.path} (${ep.relation})`,
+        `\n- Concepts: ${ep.concepts.join(", ")}`,
+        `\n- Params: ${compactParams(ep.params)}`,
+        body === "(none)" ? "" : `\n- Body: ${body}`,
+        `\n- Response: ${refMap.get(compactResp) ?? compactResp}`,
+        ep.rules.length > 0 ? `\n  Rules: ${ep.rules.join("; ")}` : "",
+        renderDependencies(ep.dependencies),
+        ep.metadata === "{}" ? "" : `\n  Metadata: ${ep.metadata}`,
+    ];
+
+    return lines.join("");
+}
+
+function renderDependencies(dependencies: GroupedEndpoint["dependencies"]) {
+    if (dependencies.length === 0) return "";
+
+    const calls = dependencies.map(
+        (d) =>
+            `    - Call ${d.depMethod} ${d.depPath} first → use its "${d.fromField}" as "${d.paramName}"`,
+    );
+    return `\n  Dependencies:\n${calls.join("\n")}`;
+}
+
+function renderService(svc: ResolvedService) {
+    const rules = svc.rules.length > 0 ? `\n  Rules: ${svc.rules.join("; ")}` : "";
+    const meta = svc.metadata === "{}" ? "" : `\n- Metadata: ${svc.metadata}`;
+
+    return (
+        `\n### ${svc.concept} via ${svc.serviceName} (service)` +
+        `\n- Built-in ID: ${svc.builtInId}` +
+        `\n- Description: ${svc.description || "N/A"}${rules}${meta}`
+    );
+}
+
+function buildResolvedSection(resolved: ResolvedContext) {
+    const allEndpoints = [...resolved.readEndpoints, ...resolved.writeEndpoints];
+
+    if (allEndpoints.length === 0 && resolved.services.length === 0) {
+        return "\n## Pre-resolved API Endpoints\nNo matching endpoints found. Use queryGraph to search the knowledge graph manually.";
+    }
+
+    // Layer 1: deduplicate endpoints by method+path
+    const grouped = groupEndpointsBySignature(allEndpoints);
+
+    // Layer 3: hoist repeated rules to a shared section
+    const {
+        sharedRules,
+        groups: cleanedGroups,
+        services: cleanedServices,
+    } = extractSharedRules(grouped, resolved.services);
+
+    // Layer 4: deduplicate identical response schemas
+    const { shapeDefs, refMap } = buildResponseShapeRefs(cleanedGroups);
+
+    return [
+        `
+## Pre-resolved API Endpoints
+The following endpoints were automatically matched to the user's message.`,
+        ...renderSection(
+            "General Rules",
+            sharedRules.map((rule) => `- ${rule}`),
+        ),
+        ...renderSection(
+            "Response Shapes",
+            shapeDefs.map((def) => `${def.name}: ${def.content}`),
+        ),
+        // Layer 2: compact schemas
+        ...cleanedGroups.map((ep) => renderEndpoint(ep, refMap)),
+        ...cleanedServices.map(renderService),
+    ].join("");
+}

package/src/lib/ai/redis-runs.ts

@@ -0,0 +1,167 @@
+import type { RedisConnections } from "@/redis";
+import type { ActiveRun, RunCoordinator } from "./active-runs";
+import { JOIN_FIRST_CHUNK_TIMEOUT_MS } from "./active-runs";
+import { offsetBelongsToRun, redisStreamLog } from "./redis-stream-log";
+
+/**
+ * The claim is the producer's liveness signal: a heartbeat refreshes its short
+ * TTL while the run is live, so a claim that expired means the producer died —
+ * that is how joiners on an orphaned run learn to stop tailing, and how a
+ * crashed instance's threads free up within a minute instead of fifteen. The
+ * stream TTL governs how long a run's chunk log stays replayable.
+ */
+const CLAIM_TTL_SECONDS = 60;
+const CLAIM_HEARTBEAT_MS = 20_000;
+const DEFAULT_STREAM_TTL_SECONDS = 24 * 60 * 60;
+
+/**
+ * Cross-instance abort: the producer's AbortController lives in-process on
+ * whichever instance runs the turn, but a stop may land on any instance — so
+ * abort publishes the run id and every instance listens, aborting the run if
+ * it owns the controller. Single-instance works too: the publisher's own
+ * subscriber receives the message.
+ */
+const ABORT_CHANNEL = "cortex:chat:abort";
+
+/**
+ * The claim doubles as mutex and discovery pointer: a joiner that only knows
+ * the thread id finds the live run here.
+ */
+function claimKey(threadId: string) {
+    return `cortex:chat:active:${threadId}`;
+}
+
+/**
+ * Atomically take the claim and learn who held it. Two concurrent starts on
+ * one thread each see the other exactly once, so the loser is always aborted —
+ * a GET-then-SET pair could interleave and leave both producers running.
+ */
+const CLAIM_SWAP = `local previous = redis.call("get", KEYS[1])
+redis.call("set", KEYS[1], ARGV[1], "EX", ARGV[2])
+return previous`;
+
+/** Release only if still held by this run — a superseded run finishing late
+ *  must not evict its replacement. GET-then-DEL would race; the script cannot. */
+const RELEASE_IF_HELD = `if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end`;
+
+/** The heartbeat must never resurrect a claim that abort or supersede released. */
+const REFRESH_IF_HELD = `if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("expire", KEYS[1], ARGV[2]) else return 0 end`;
+
+type RedisRunOptions = {
+    streamTtlSeconds?: number;
+};
+
+export function createRedisRuns(connections: RedisConnections, options: RedisRunOptions = {}) {
+    const { publisher, subscriber } = connections;
+    const streamTtlMs = (options.streamTtlSeconds ?? DEFAULT_STREAM_TTL_SECONDS) * 1000;
+    const logOptions = { streamTtlMs, firstChunkDeadlineMs: JOIN_FIRST_CHUNK_TIMEOUT_MS };
+    const aborters = new Map<string, AbortController>();
+    const heartbeats = new Map<string, ReturnType<typeof setInterval>>();
+
+    subscriber.on("message", function (channel: string, runId: string) {
+        if (channel === ABORT_CHANNEL) aborters.get(runId)?.abort();
+    });
+
+    /**
+     * Lazy and retried, never memoized-rejected: caching one boot-time
+     * subscribe promise would leave every future startRun rethrowing a single
+     * transient outage forever. Once it resolves, ioredis re-subscribes by
+     * itself across reconnects.
+     */
+    let abortSubscription: Promise<unknown> | undefined;
+    function ensureAbortSubscription() {
+        abortSubscription ??= subscriber.subscribe(ABORT_CHANNEL).catch((error: unknown) => {
+            abortSubscription = undefined;
+            throw error;
+        });
+        return abortSubscription;
+    }
+
+    async function abortRun(threadId: string) {
+        const runId = await publisher.get(claimKey(threadId));
+        if (!runId) return false;
+        // The local abort is immediate; the publish reaches the other instances.
+        aborters.get(runId)?.abort();
+        await publisher.publish(ABORT_CHANNEL, runId);
+        await publisher.eval(RELEASE_IF_HELD, 1, claimKey(threadId), runId);
+        return true;
+    }
+
+    function startHeartbeat(threadId: string, runId: string) {
+        const timer = setInterval(function () {
+            void publisher
+                .eval(REFRESH_IF_HELD, 1, claimKey(threadId), runId, String(CLAIM_TTL_SECONDS))
+                .catch((error: unknown) =>
+                    console.error("[cortex-server] redis claim heartbeat:", error),
+                );
+        }, CLAIM_HEARTBEAT_MS);
+        heartbeats.set(runId, timer);
+    }
+
+    function stopHeartbeat(runId: string) {
+        const timer = heartbeats.get(runId);
+        if (timer !== undefined) clearInterval(timer);
+        heartbeats.delete(runId);
+    }
+
+    return {
+        async startRun(threadId) {
+            // A producer must be able to hear aborts before it may exist, or a
+            // stop from another instance could slip by while we boot.
+            await ensureAbortSubscription();
+            const run: ActiveRun = {
+                runId: crypto.randomUUID(),
+                abortController: new AbortController(),
+            };
+            // Registered before the claim exists, so an abort cannot land in
+            // between; unregistered again if the claim never materializes.
+            aborters.set(run.runId, run.abortController);
+            try {
+                const superseded = (await publisher.eval(
+                    CLAIM_SWAP,
+                    1,
+                    claimKey(threadId),
+                    run.runId,
+                    String(CLAIM_TTL_SECONDS),
+                )) as string | null;
+                if (superseded !== null) {
+                    aborters.get(superseded)?.abort();
+                    await publisher.publish(ABORT_CHANNEL, superseded);
+                }
+            } catch (error) {
+                aborters.delete(run.runId);
+                throw error;
+            }
+            startHeartbeat(threadId, run.runId);
+            return run;
+        },
+        async getRunId(threadId) {
+            return (await publisher.get(claimKey(threadId))) ?? undefined;
+        },
+        async runningThreadIds(threadIds) {
+            if (threadIds.length === 0) return new Set<string>();
+            const claims = await publisher.mget(threadIds.map(claimKey));
+            return new Set(threadIds.filter((_, index) => claims[index] !== null));
+        },
+        abortRun,
+        async endRun(threadId, runId) {
+            stopHeartbeat(runId);
+            aborters.delete(runId);
+            await publisher.eval(RELEASE_IF_HELD, 1, claimKey(threadId), runId);
+        },
+        producerLog(runId) {
+            return redisStreamLog(publisher, runId, { resumeOffset: null, ...logOptions });
+        },
+        joinLog(threadId, runId, offset = "-1") {
+            return redisStreamLog(publisher, runId, {
+                resumeOffset: offset,
+                // The claim is the producer's pulse: while this run holds it the
+                // reader may park between chunks indefinitely, and once it is
+                // gone with the log still unclosed, the producer died.
+                isLive: async () => (await publisher.get(claimKey(threadId))) === runId,
+                ...logOptions,
+            });
+        },
+        offsetBelongsToRun,
+    } satisfies RunCoordinator;
+}