@m6d/cortex-server 1.8.0 → 2.0.0

package/src/lib/ai/inspector.ts

@@ -0,0 +1,112 @@
+import type { ChatMiddleware, TokenUsage as ProviderTokenUsage } from "@tanstack/ai";
+import type { TokenUsage } from "@/types";
+
+/** One model call's raw exchange, as the LLM request inspector renders it. */
+export type CapturedStep = {
+    prompt: string;
+    output: string | null;
+    tokenUsage: TokenUsage | null;
+};
+
+/**
+ * Watches one turn's model calls. The SDK's `debug` logger reports call metadata
+ * but never raw bodies, so the raw exchange is captured where it actually
+ * exists — on the HTTP client — while usage arrives through middleware.
+ */
+export function createInspector() {
+    const steps: CapturedStep[] = [];
+    let modelId = "";
+    let tokenUsage: TokenUsage | undefined;
+
+    async function capturingFetch(input: string | URL | Request, init?: RequestInit) {
+        const step: CapturedStep = {
+            prompt: typeof init?.body === "string" ? init.body : "",
+            output: null,
+            tokenUsage: null,
+        };
+        steps.push(step);
+
+        const response = await fetch(input, init);
+        // Drain a tee rather than the response itself: the model call must keep
+        // streaming at full speed, and losing debug data must never fail a turn.
+        void response
+            .clone()
+            .text()
+            .then(function (text) {
+                step.output = text;
+            })
+            .catch(() => undefined);
+
+        return response;
+    }
+
+    const middleware: ChatMiddleware = {
+        name: "cortex-inspector",
+        onUsage(ctx, usage) {
+            modelId = ctx.model;
+            const stepUsage = toTokenUsage(usage);
+            const lastStep = steps.at(-1);
+            if (lastStep) lastStep.tokenUsage = stepUsage;
+            tokenUsage = addTokenUsage(tokenUsage, stepUsage);
+        },
+    };
+
+    return {
+        steps,
+        middleware,
+        // Bun's fetch type carries preconnect; delegate so the client accepts the shim.
+        fetch: Object.assign(capturingFetch, { preconnect: fetch.preconnect }),
+        get modelId() {
+            return modelId;
+        },
+        get tokenUsage() {
+            return tokenUsage;
+        },
+    };
+}
+
+/**
+ * Flattens the provider's usage shape into ours. The provider reports cached and
+ * cache-written prompt tokens but no uncached counter, so that dimension is the
+ * remainder — which is what makes the client's breakdown add up to the total.
+ */
+export function toTokenUsage(usage: ProviderTokenUsage) {
+    const cacheRead = usage.promptTokensDetails?.cachedTokens ?? 0;
+    const cacheWrite = usage.promptTokensDetails?.cacheWriteTokens ?? 0;
+    const reasoning = usage.completionTokensDetails?.reasoningTokens ?? 0;
+
+    return {
+        input: {
+            noCache: Math.max(usage.promptTokens - cacheRead - cacheWrite, 0),
+            cacheRead,
+            cacheWrite,
+            total: usage.promptTokens,
+        },
+        output: {
+            reasoning,
+            text: usage.completionTokensDetails?.textTokens ?? usage.completionTokens - reasoning,
+            total: usage.completionTokens,
+        },
+        total: usage.totalTokens,
+    } satisfies TokenUsage;
+}
+
+/** The agent loop reports usage per iteration; a turn's cost is their sum. */
+function addTokenUsage(left: TokenUsage | undefined, right: TokenUsage) {
+    if (!left) return right;
+
+    return {
+        input: {
+            noCache: left.input.noCache + right.input.noCache,
+            cacheRead: left.input.cacheRead + right.input.cacheRead,
+            cacheWrite: left.input.cacheWrite + right.input.cacheWrite,
+            total: left.input.total + right.input.total,
+        },
+        output: {
+            reasoning: left.output.reasoning + right.output.reasoning,
+            text: left.output.text + right.output.text,
+            total: left.output.total + right.output.total,
+        },
+        total: left.total + right.total,
+    } satisfies TokenUsage;
+}

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

@@ -1,6 +1,6 @@
-import type { DatabaseAdapter } from "../../adapters/database.ts";
-import type { StorageAdapter } from "../../adapters/storage.ts";
-import { streamToBase64, tokenToUserId } from "../helpers.ts";
+import type { DatabaseAdapter } from "@/adapters/database/index";
+import type { StorageAdapter } from "@/adapters/storage/index";
+import { streamToBase64 } from "@/ai/helpers";
 
 export type ResolvedFile = {
     name: string;
@@ -14,48 +14,76 @@ export type RequestInterceptorOptions = {
 export function createRequestInterceptor(
     db: DatabaseAdapter,
     storage: StorageAdapter,
-    options?: RequestInterceptorOptions,
+    options: RequestInterceptorOptions & { threadId: string; userId: string },
 ) {
-    const transformFile = options?.transformFile ?? ((file: ResolvedFile) => file);
-
-    return async function resolveRequestBody(
-        body: Record<string, unknown>,
-        context: { token: string },
-    ) {
-        const userId = tokenToUserId(context.token);
-
-        async function traverse(obj: Record<string, unknown>) {
-            await Promise.all(
-                Object.keys(obj).map(async (key) => {
-                    const value = obj[key];
-                    if (typeof value === "string" && value.startsWith("capturedFile")) {
-                        const [_, uploadId] = value.split("#");
-                        const file = await db.capturedFiles.getById(uploadId!, userId);
-                        if (file) {
-                            const fileStream = await storage.stream(`captured_files/${uploadId}`);
-                            const bytes = await streamToBase64(fileStream);
-                            obj[key] = transformFile({ name: file.name, bytes });
-                        }
-                    }
-
-                    if (Array.isArray(value)) {
-                        await Promise.all(
-                            value.map(async (child) => {
-                                if (typeof child === "object" && child !== null) {
-                                    await traverse(child as Record<string, unknown>);
-                                }
-                            }),
-                        );
-                    }
-
-                    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-                        await traverse(value as Record<string, unknown>);
-                    }
-                }),
-            );
+    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);
         }
 
-        await traverse(body);
         return body;
     };
 }

package/src/lib/ai/prompt.ts

@@ -1,6 +1,8 @@
-import type { ResolvedContext, ResolvedEndpoint, ResolvedService } from "../graph/resolver.ts";
-import type { PromptContext, ResolvedCortexAgentConfig } from "../config.ts";
-import type { Thread } from "../types.ts";
+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
@@ -27,29 +29,37 @@ 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;
+        basePrompt = config.systemPrompt ?? "";
     }
 
-    const sections: string[] = [basePrompt];
+    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");
 }
 
-// ---------------------------------------------------------------------------
-// Schema field type (parsed from endpoint JSON strings)
-// ---------------------------------------------------------------------------
-
 type SchemaField = {
     name: string;
     required?: boolean;
@@ -58,11 +68,7 @@ type SchemaField = {
     properties?: SchemaField[];
 };
 
-// ---------------------------------------------------------------------------
-// Layer 2: Schema compression
-// ---------------------------------------------------------------------------
-
-/** Compact param/body: `name?: type, nested?: {a: string, b: number}[]` */
+/** Compression layer 2. Compact param/body: `name?: type, nested?: {a: string, b: number}[]` */
 function compactParamFields(fields: SchemaField[]): string {
     return fields
         .map((f) => {
@@ -109,14 +115,48 @@ function compactResponse(jsonStr: string) {
     }
 }
 
-// ---------------------------------------------------------------------------
-// Layer 1: Group endpoints by method + path
-// ---------------------------------------------------------------------------
-
+/**
+ * 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>();
 
@@ -125,46 +165,19 @@ function groupEndpointsBySignature(endpoints: ResolvedEndpoint[]) {
         const existing = groups.get(key);
 
         if (existing) {
-            if (!existing.concepts.includes(ep.concept)) {
-                existing.concepts.push(ep.concept);
-            }
-            for (const rule of ep.rules) {
-                if (!existing.rules.includes(rule)) {
-                    existing.rules.push(rule);
-                }
-            }
-            for (const dep of ep.dependencies) {
-                const isDuplicate = existing.dependencies.some(
-                    (d) => d.depPath === dep.depPath && d.paramName === dep.paramName,
-                );
-                if (!isDuplicate) {
-                    existing.dependencies.push(dep);
-                }
-            }
+            mergeEndpoint(existing, ep);
         } else {
-            groups.set(key, {
-                concepts: [ep.concept],
-                relation: ep.relation,
-                name: ep.name,
-                path: ep.path,
-                method: ep.method,
-                params: ep.params,
-                body: ep.body,
-                response: ep.response,
-                dependencies: [...ep.dependencies],
-                rules: [...ep.rules],
-                metadata: ep.metadata,
-            });
+            groups.set(key, toGroup(ep));
         }
     }
 
     return Array.from(groups.values());
 }
 
-// ---------------------------------------------------------------------------
-// Layer 3: Extract shared rules into a global section
-// ---------------------------------------------------------------------------
-
+/**
+ * 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>();
 
@@ -198,16 +211,16 @@ function extractSharedRules(groups: GroupedEndpoint[], services: ResolvedService
     };
 }
 
-// ---------------------------------------------------------------------------
-// Layer 4: Deduplicate identical response schemas across endpoints
-// ---------------------------------------------------------------------------
-
+/**
+ * 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[]): ResponseShapeRefs {
+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.
@@ -258,9 +271,50 @@ function buildResponseShapeRefs(groups: GroupedEndpoint[]): ResponseShapeRefs {
     return { shapeDefs, refMap };
 }
 
-// ---------------------------------------------------------------------------
-// Pre-resolved section builder
-// ---------------------------------------------------------------------------
+/** 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];
@@ -282,73 +336,20 @@ function buildResolvedSection(resolved: ResolvedContext) {
     // Layer 4: deduplicate identical response schemas
     const { shapeDefs, refMap } = buildResponseShapeRefs(cleanedGroups);
 
-    const parts: string[] = [
+    return [
         `
 ## Pre-resolved API Endpoints
 The following endpoints were automatically matched to the user's message.`,
-    ];
-
-    // Shared rules
-    if (sharedRules.length > 0) {
-        parts.push("\n### General Rules");
-        for (const rule of sharedRules) {
-            parts.push(`\n- ${rule}`);
-        }
-    }
-
-    // Response shape definitions
-    if (shapeDefs.length > 0) {
-        parts.push("\n### Response Shapes");
-        for (const def of shapeDefs) {
-            parts.push(`\n${def.name}: ${def.content}`);
-        }
-    }
-
-    // Endpoints (Layer 2: compact schemas)
-    for (const ep of cleanedGroups) {
-        const concepts = ep.concepts.join(", ");
-        const params = compactParams(ep.params);
-        const body = compactParams(ep.body);
-        const compactResp = compactResponse(ep.response);
-        const response = refMap.get(compactResp) ?? compactResp;
-
-        const rules = ep.rules.length > 0 ? `\n  Rules: ${ep.rules.join("; ")}` : "";
-        const deps =
-            ep.dependencies.length > 0
-                ? "\n  Dependencies:\n" +
-                  ep.dependencies
-                      .map(
-                          (d) =>
-                              `    - Call ${d.depMethod} ${d.depPath} first → use its "${d.fromField}" as "${d.paramName}"`,
-                      )
-                      .join("\n")
-                : "";
-        const meta = ep.metadata !== "{}" ? `\n  Metadata: ${ep.metadata}` : "";
-
-        let block = `\n### ${ep.name} — ${ep.method} ${ep.path} (${ep.relation})`;
-        block += `\n- Concepts: ${concepts}`;
-        block += `\n- Params: ${params}`;
-        if (body !== "(none)") {
-            block += `\n- Body: ${body}`;
-        }
-        block += `\n- Response: ${response}`;
-        block += rules;
-        block += deps;
-        block += meta;
-
-        parts.push(block);
-    }
-
-    // Services
-    for (const svc of cleanedServices) {
-        const rules = svc.rules.length > 0 ? `\n  Rules: ${svc.rules.join("; ")}` : "";
-        const meta = svc.metadata !== "{}" ? `\n- Metadata: ${svc.metadata}` : "";
-        parts.push(
-            `\n### ${svc.concept} via ${svc.serviceName} (service)` +
-                `\n- Built-in ID: ${svc.builtInId}` +
-                `\n- Description: ${svc.description || "N/A"}${rules}${meta}`,
-        );
-    }
-
-    return parts.join("");
+        ...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("");
 }