@m6d/cortex-server 1.0.0

package/src/ai/index.ts

@@ -0,0 +1,145 @@
+import {
+  type ToolSet,
+  convertToModelMessages,
+  generateId,
+  generateText,
+  safeValidateUIMessages,
+  streamText,
+} from "ai";
+import { HTTPException } from "hono/http-exception";
+import type { ResolvedCortexAgentConfig } from "../config.ts";
+import type { Thread } from "../types.ts";
+import { createModel, createEmbeddingModel } from "./helpers.ts";
+import { buildSystemPrompt } from "./prompt.ts";
+import { createQueryGraphTool } from "./tools/query-graph.tool.ts";
+import { createCallEndpointTool } from "./tools/call-endpoint.tool.ts";
+import { createExecuteCodeTool } from "./tools/execute-code.tool.ts";
+import { captureFilesTool } from "./tools/capture-files.tool.ts";
+import { createCapturedFileInterceptor } from "./interceptors/resolve-captured-files.ts";
+import { createNeo4jClient } from "../graph/neo4j.ts";
+import { resolveFromGraph } from "../graph/resolver.ts";
+import { notify } from "../ws/index.ts";
+
+export async function stream(
+  messages: unknown[],
+  thread: Thread,
+  userId: string,
+  token: string,
+  config: ResolvedCortexAgentConfig,
+) {
+  const validationResult = await safeValidateUIMessages({ messages });
+  if (!validationResult.success) {
+    throw new HTTPException(423, { message: "Invalid messages format" });
+  }
+
+  const validatedMessages = validationResult.data;
+  await config.db.messages.upsert(thread.id, validatedMessages);
+
+  const originalMessages = await config.db.messages
+    .list(userId, thread.id, { limit: 20 })
+    .then((x) => x.map((y) => y.content));
+
+  const recentMessages = await convertToModelMessages(originalMessages);
+
+  const prompt =
+    originalMessages
+      .filter((x) => x.role === "user")
+      .at(-1)
+      ?.parts.find((x) => x.type === "text")?.text ?? "";
+
+  const model = createModel(config.model);
+  const embeddingModel = createEmbeddingModel(config.embedding);
+  const neo4j = createNeo4jClient(config.neo4j, embeddingModel);
+
+  // Pre-resolve graph context
+  const resolved = await resolveFromGraph(prompt, {
+    neo4j,
+    embeddingModel,
+    reranker: config.reranker,
+  });
+
+  // Build tools
+  const builtInTools: Record<string, unknown> = {
+    captureFiles: captureFilesTool,
+    queryGraph: createQueryGraphTool(neo4j),
+  };
+
+  if (config.backendFetch) {
+    const backendFetchWithInterceptor = {
+      ...config.backendFetch,
+      transformRequestBody:
+        config.backendFetch.transformRequestBody ??
+        createCapturedFileInterceptor(config.db, config.storage),
+    };
+
+    builtInTools["callEndpoint"] = createCallEndpointTool(
+      backendFetchWithInterceptor,
+      token,
+    );
+    builtInTools["executeCode"] = createExecuteCodeTool(
+      backendFetchWithInterceptor,
+      token,
+    );
+  }
+
+  const tools = {
+    ...builtInTools,
+    ...config.tools,
+  } as ToolSet;
+
+  const systemPrompt = await buildSystemPrompt(
+    config,
+    prompt,
+    thread,
+    token,
+    resolved,
+  );
+
+  const result = streamText({
+    model,
+    system: systemPrompt,
+    tools,
+    messages: recentMessages,
+    onAbort: () => {
+      console.log("Stream aborted");
+    },
+  });
+
+  return result.toUIMessageStreamResponse({
+    originalMessages,
+    generateMessageId: generateId,
+    onFinish: async ({ messages: finishedMessages, isAborted }) => {
+      if (isAborted) {
+        console.log("Stream was aborted");
+      }
+      await config.db.messages.upsert(thread.id, finishedMessages);
+      config.onStreamFinish?.({ messages: finishedMessages, isAborted });
+    },
+  });
+}
+
+export async function generateTitle(
+  threadId: string,
+  prompt: string,
+  userId: string,
+  config: ResolvedCortexAgentConfig,
+) {
+  const model = createModel(config.model);
+
+  const { output } = await generateText({
+    model,
+    system: `You are an expert in generating titles for threads of chats
+given the first message in that thread.
+
+When asked, only respond with the title without saying you're
+going to do so or any other speech. Spit out only the title.`,
+    prompt: `Generate a title for this prompt: ${prompt}`,
+  });
+
+  await config.db.threads.updateTitle(threadId, output ?? "");
+
+  notify(userId, {
+    type: "thread:title-updated",
+    payload: { threadId, title: output ?? "" },
+  });
+}

package/src/ai/interceptors/resolve-captured-files.ts

@@ -0,0 +1,64 @@
+import type { DatabaseAdapter } from "../../adapters/database.ts";
+import type { StorageAdapter } from "../../adapters/storage.ts";
+import { streamToBase64, tokenToUserId } from "../helpers.ts";
+
+export type ResolvedFile = {
+  name: string;
+  bytes: string;
+};
+
+export function createCapturedFileInterceptor(
+  db: DatabaseAdapter,
+  storage: StorageAdapter,
+  options?: { transformFile?: (file: ResolvedFile) => unknown },
+) {
+  const transformFile =
+    options?.transformFile ?? ((file: ResolvedFile) => file);
+
+  return async function resolveCapturedFiles(
+    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>);
+          }
+        }),
+      );
+    }
+
+    await traverse(body);
+    return body;
+  };
+}

package/src/ai/prompt.ts

@@ -0,0 +1,120 @@
+import type { ResolvedContext } from "../graph/resolver.ts";
+import type { ResolvedCortexAgentConfig } from "../config.ts";
+import type { Thread } from "../types.ts";
+
+export async function buildSystemPrompt(
+  config: ResolvedCortexAgentConfig,
+  prompt: string,
+  thread: Thread,
+  token: string,
+  resolved: ResolvedContext | null,
+) {
+  // Resolve the consumer's base system prompt
+  let basePrompt: string;
+  if (typeof config.systemPrompt === "function") {
+    // Resolve session data with caching
+    let session: Record<string, unknown> | null = thread.session as Record<
+      string,
+      unknown
+    > | null;
+
+    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;
+    }
+
+    basePrompt = await config.systemPrompt(session);
+  } else {
+    basePrompt = config.systemPrompt;
+  }
+
+  const sections: string[] = [basePrompt];
+
+  // Pre-resolved endpoints from knowledge graph
+  if (resolved) {
+    sections.push(buildResolvedSection(resolved));
+  }
+
+  return sections.join("\n");
+}
+
+function buildResolvedSection(resolved: ResolvedContext) {
+  const parts: string[] = [
+    `
+## Pre-resolved API Endpoints
+The following endpoints were automatically matched to the user's message.`,
+  ];
+
+  for (const ep of resolved.readEndpoints) {
+    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")
+        : "";
+    parts.push(
+      `
+### ${ep.concept} (read)
+- Endpoint: ${ep.name}
+- ${ep.method} ${ep.path}
+- Params: ${ep.params}
+- Body: ${ep.body}
+- Response: ${ep.response}${rules}${deps}`,
+    );
+  }
+
+  for (const ep of resolved.writeEndpoints) {
+    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")
+        : "";
+    parts.push(
+      `
+### ${ep.concept} (write)
+- Endpoint: ${ep.name}
+- ${ep.method} ${ep.path}
+- Params: ${ep.params}
+- Body: ${ep.body}
+- Response: ${ep.response}${rules}${deps}`,
+    );
+  }
+
+  for (const svc of resolved.services) {
+    const rules =
+      svc.rules.length > 0 ? `\n  Rules: ${svc.rules.join("; ")}` : "";
+    parts.push(
+      `
+### ${svc.concept} via ${svc.serviceName} (service)
+- Built-in ID: ${svc.builtInId}
+- Description: ${svc.description || "N/A"}${rules}`,
+    );
+  }
+
+  if (
+    resolved.readEndpoints.length === 0 &&
+    resolved.writeEndpoints.length === 0 &&
+    resolved.services.length === 0
+  ) {
+    parts.push(
+      "\nNo matching endpoints found. Use queryGraph to search the knowledge graph manually.",
+    );
+  }
+
+  return parts.join("");
+}

package/src/ai/tools/call-endpoint.tool.ts

@@ -0,0 +1,96 @@
+import { tool } from "ai";
+import z from "zod";
+import type { ResolvedCortexAgentConfig } from "../../config.ts";
+import { fetchBackend } from "../fetch.ts";
+
+export function createCallEndpointTool(
+  backendFetch: NonNullable<ResolvedCortexAgentConfig["backendFetch"]>,
+  token: string,
+) {
+  return tool({
+    title: "Call an API endpoint",
+    description:
+      "Call an API endpoint on the backend. Use queryGraph first to discover the correct endpoint, parameters, and business rules. For write operations (POST/PUT/DELETE), ALWAYS get explicit user confirmation before calling.",
+    inputSchema: z.object({
+      path: z
+        .string()
+        .describe(
+          'The API path including path parameters. Example: "/items/list" or "/resources/{id}"',
+        ),
+      method: z
+        .enum(["GET", "POST", "PUT", "DELETE"])
+        .describe("The HTTP method"),
+      queryParams: z
+        .string()
+        .optional()
+        .describe("Optional JSON-encoded string of query parameters."),
+      body: z
+        .string()
+        .optional()
+        .describe(
+          "Optional JSON-encoded string of request body for POST/PUT. For parameters of type file, use `capturedFile#[uploadId]` as the value.",
+        ),
+    }),
+    execute: async ({ path, method, queryParams, body }) => {
+      let fullPath = path;
+      if (queryParams) {
+        const params = JSON.parse(queryParams) as Record<string, unknown>;
+        const searchParams = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+          if (value == null || value === "") continue;
+          if (Array.isArray(value)) {
+            for (const item of value) {
+              searchParams.append(key, String(item));
+            }
+          } else {
+            searchParams.set(key, String(value));
+          }
+        }
+        const qs = searchParams.toString();
+        if (qs) fullPath += `?${qs}`;
+      }
+
+      const options: RequestInit = { method };
+      if (body && (method === "POST" || method === "PUT")) {
+        options.body = body;
+      }
+
+      const response = await fetchBackend(
+        fullPath,
+        backendFetch,
+        token,
+        options,
+      );
+
+      if (!response.ok) {
+        let message: string;
+        let details: unknown = undefined;
+        try {
+          const errorBody = (await response.json()) as Record<string, unknown>;
+          message =
+            (errorBody.message as string) ||
+            (errorBody.title as string) ||
+            JSON.stringify(errorBody);
+          if (errorBody.errors) {
+            details = errorBody.errors;
+          }
+        } catch {
+          message = `Request failed with status ${response.status}`;
+        }
+        return JSON.stringify({
+          error: true,
+          status: response.status,
+          message,
+          ...(details ? { details } : {}),
+        });
+      }
+
+      if (response.status === 204) {
+        return JSON.stringify({ success: true });
+      }
+
+      const data = await response.json();
+      return JSON.stringify(data);
+    },
+  });
+}

package/src/ai/tools/capture-files.tool.ts

@@ -0,0 +1,22 @@
+import { tool } from "ai";
+import z from "zod";
+
+export const captureFilesTool = tool({
+  description: "Let the user upload a file",
+  inputSchema: z.object({
+    files: z.array(
+      z.object({
+        label: z
+          .string()
+          .describe(
+            "A label to view to the user to know what file they need to upload",
+          ),
+        id: z
+          .string()
+          .describe(
+            "An ID to the file for you to use it when calling apis or later processing",
+          ),
+      }),
+    ),
+  }),
+});

package/src/ai/tools/execute-code.tool.ts

@@ -0,0 +1,108 @@
+import { tool } from "ai";
+import z from "zod";
+import type { ResolvedCortexAgentConfig } from "../../config.ts";
+import { fetchBackend } from "../fetch.ts";
+
+type ApiHelper = {
+  get: (
+    path: string,
+    queryParams?: Record<string, unknown>,
+  ) => Promise<unknown>;
+  post: (path: string, body?: unknown) => Promise<unknown>;
+  put: (path: string, body?: unknown) => Promise<unknown>;
+  del: (path: string) => Promise<unknown>;
+};
+
+function buildQueryString(params: Record<string, unknown>) {
+  const searchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value == null || value === "") continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        searchParams.append(key, String(item));
+      }
+    } else {
+      searchParams.set(key, String(value));
+    }
+  }
+  const qs = searchParams.toString();
+  return qs ? `?${qs}` : "";
+}
+
+function createApiHelper(
+  backendFetch: NonNullable<ResolvedCortexAgentConfig["backendFetch"]>,
+  token: string,
+) {
+  async function request(method: string, path: string, body?: unknown) {
+    const options: RequestInit = { method };
+    if (body !== undefined && (method === "POST" || method === "PUT")) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetchBackend(path, backendFetch, token, options);
+
+    if (!response.ok) {
+      let message: string;
+      try {
+        const errorBody = await response.json();
+        message = JSON.stringify(errorBody);
+      } catch {
+        message = `HTTP ${response.status}`;
+      }
+      throw new Error(
+        `API ${method} ${path} failed (${response.status}): ${message}`,
+      );
+    }
+
+    if (response.status === 204) return { success: true };
+    return response.json();
+  }
+
+  return {
+    get: (path, queryParams) => {
+      const fullPath = queryParams
+        ? path + buildQueryString(queryParams)
+        : path;
+      return request("GET", fullPath);
+    },
+    post: (path, body) => request("POST", path, body),
+    put: (path, body) => request("PUT", path, body),
+    del: (path) => request("DELETE", path),
+  } satisfies ApiHelper;
+}
+
+const AsyncFunction: new (
+  ...args: [...paramNames: string[], body: string]
+) => (...args: unknown[]) => Promise<unknown> = Object.getPrototypeOf(
+  async function () {},
+).constructor;
+
+export function createExecuteCodeTool(
+  backendFetch: NonNullable<ResolvedCortexAgentConfig["backendFetch"]>,
+  token: string,
+) {
+  return tool({
+    title: "Executes JavaScript code",
+    description:
+      "Run a JavaScript script that calls APIs and returns only relevant data. The script has an `api` helper: api.get(path, params?), api.post(path, body?), api.put(path, body?), api.del(path). Each returns parsed JSON and throws on error. For parameters of type file, use `capturedFile#[uploadId]` as the value.",
+    inputSchema: z.object({
+      code: z
+        .string()
+        .describe(
+          "Async JS function body. Use the `api` helper to call endpoints. Return only the data needed for your response.",
+        ),
+    }),
+    execute: async ({ code }) => {
+      const apiHelper = createApiHelper(backendFetch, token);
+
+      try {
+        const fn = new AsyncFunction("api", code);
+        const result = await fn(apiHelper);
+        return JSON.stringify(result);
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return JSON.stringify({ error: true, message });
+      }
+    },
+  });
+}

package/src/ai/tools/query-graph.tool.ts

@@ -0,0 +1,35 @@
+import { tool } from "ai";
+import z from "zod";
+import type { Neo4jClient } from "../../graph/neo4j.ts";
+
+export function createQueryGraphTool(neo4j: Neo4jClient) {
+  return tool({
+    title: "Query existing Knowledge Graph",
+    description: `Run a Cypher query against the Neo4j knowledge graph to find relevant
+API endpoints, business rules, and system concepts.
+
+Concepts' descriptions are embedded (vectorized), always use this method to search unknowns; use regular keywords only if you received it before or you know it for a fact:
+\`\`\`cypher
+CALL db.index.vector.queryNodes('concept_embeddings', 10, $embedding)
+YIELD node, score
+WHERE score > 0.85
+MATCH (node)-[:SPECIALIZES*0..3]->(ancestor)
+MATCH (ancestor)-[:QUERIED_VIA|MUTATED_VIA]->(e)
+RETURN node, e
+ORDER BY score DESC;
+\`\`\``,
+    inputSchema: z.object({
+      query: z.string().describe("The Cypher query to execute"),
+      parameters: z
+        .string()
+        .optional()
+        .describe(
+          'Optional JSON-encoded string of query parameters. Example: `{"name": "LeaveBalance"}` if you know the exact name; for parameters that need to be embedded first prepend the name with `#`, e.g., `{"#paramName": "Text to be embedded before passed to query"}`',
+        ),
+    }),
+    execute: async ({ query, parameters }) => {
+      const params = parameters ? JSON.parse(parameters) : undefined;
+      return neo4j.query(query, params);
+    },
+  });
+}

package/src/auth/middleware.ts

@@ -0,0 +1,63 @@
+import { createMiddleware } from "hono/factory";
+import { getCookie } from "hono/cookie";
+import { HTTPException } from "hono/http-exception";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import type { AppEnv, AuthedAppEnv } from "../types";
+import type { CortexConfig } from "../config";
+
+export function createUserLoaderMiddleware(authConfig: CortexConfig["auth"]) {
+  const jwks = createRemoteJWKSet(new URL(authConfig.jwksUri));
+
+  return createMiddleware<AppEnv>(async (c, next) => {
+    let token: string | null = null;
+
+    if (authConfig.tokenExtractor) {
+      token = authConfig.tokenExtractor(c.req.raw);
+    } else {
+      // 1. Authorization header
+      const authHeader = c.req.header("Authorization");
+      if (authHeader?.startsWith("Bearer ")) {
+        token = authHeader.slice(7);
+      }
+
+      // 2. Query parameter
+      if (!token) {
+        const url = new URL(c.req.url);
+        token = url.searchParams.get("token");
+      }
+
+      // 3. Cookie
+      if (!token && authConfig.cookieName) {
+        token = getCookie(c, authConfig.cookieName) ?? null;
+      }
+    }
+
+    if (!token) {
+      await next();
+      return;
+    }
+
+    try {
+      const { payload } = await jwtVerify(token, jwks, {
+        issuer: authConfig.issuer,
+        clockTolerance: Infinity,
+      });
+
+      if (payload.sub) {
+        c.set("user", { id: payload.sub, token });
+      }
+      await next();
+    } catch {
+      await next();
+    }
+  });
+}
+
+export const requireAuth = createMiddleware<AuthedAppEnv>(async (c, next) => {
+  const user = c.get("user");
+  if (!user) {
+    throw new HTTPException(401, { message: "Unauthorized" });
+  }
+  c.set("user", user);
+  await next();
+});