@m6d/cortex-server 1.0.0

package/src/graph/validate.ts

@@ -0,0 +1,80 @@
+import type { DomainDef } from "./types.ts";
+
+export function validateDomain(data: DomainDef) {
+  const errors: string[] = [];
+
+  const seenConceptNames = new Set<string>();
+  for (const c of data.concepts ?? []) {
+    if (seenConceptNames.has(c.name)) {
+      errors.push(`Duplicate concept name: "${c.name}"`);
+    }
+    seenConceptNames.add(c.name);
+  }
+
+  const seenEndpointNames = new Set<string>();
+  for (const e of data.endpoints ?? []) {
+    if (seenEndpointNames.has(e.name)) {
+      errors.push(`Duplicate endpoint name: "${e.name}"`);
+    }
+    seenEndpointNames.add(e.name);
+  }
+
+  const seenServiceNames = new Set<string>();
+  for (const s of data.services ?? []) {
+    if (seenServiceNames.has(s.name)) {
+      errors.push(`Duplicate service name: "${s.name}"`);
+    }
+    seenServiceNames.add(s.name);
+  }
+
+  const seenRuleNames = new Set<string>();
+  for (const r of data.rules ?? []) {
+    if (seenRuleNames.has(r.name)) {
+      errors.push(`Duplicate rule name: "${r.name}"`);
+    }
+    seenRuleNames.add(r.name);
+  }
+
+  // Cross-domain references are allowed (concepts/endpoints/services may
+  // be defined in another domain), so we do not enforce local membership.
+
+  const referencedConcepts = new Set<string>();
+  const referencedRules = new Set<string>();
+
+  for (const ep of data.endpoints ?? []) {
+    ep.queries?.forEach((c) => referencedConcepts.add(c.name));
+    ep.mutates?.forEach((c) => referencedConcepts.add(c.name));
+    ep.returns?.forEach((r) => referencedConcepts.add(r.concept.name));
+    ep.governedBy?.forEach((r) => referencedRules.add(r.name));
+  }
+
+  for (const svc of data.services ?? []) {
+    referencedConcepts.add(svc.belongsTo.name);
+    svc.governedBy?.forEach((r) => referencedRules.add(r.name));
+  }
+
+  for (const c of data.concepts ?? []) {
+    c.governedBy?.forEach((r) => referencedRules.add(r.name));
+    if (c.parentConcept) {
+      referencedConcepts.add(c.parentConcept.name);
+    }
+  }
+
+  for (const c of data.concepts ?? []) {
+    if (!referencedConcepts.has(c.name)) {
+      errors.push(
+        `Concept "${c.name}" is never referenced by any endpoint, or service`,
+      );
+    }
+  }
+
+  for (const r of data.rules ?? []) {
+    if (!referencedRules.has(r.name)) {
+      errors.push(
+        `Rule "${r.name}" is never referenced by any endpoint, service, or concept`,
+      );
+    }
+  }
+
+  return errors;
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// Config types
+export type {
+  CortexConfig,
+  CortexAgentDefinition,
+  KnowledgeConfig,
+  DatabaseConfig,
+  StorageConfig,
+} from "./config";
+
+// Types consumers may need
+export type { Thread, AppEnv } from "./types";
+
+// Factory — main entry point
+export type { CortexInstance } from "./factory";
+export { createCortex } from "./factory";
+
+// Tools (consumers may register custom tools or use built-in ones)
+export { captureFilesTool } from "./ai/tools/capture-files.tool";
+export { createQueryGraphTool } from "./ai/tools/query-graph.tool";
+export { createCallEndpointTool } from "./ai/tools/call-endpoint.tool";
+export { createExecuteCodeTool } from "./ai/tools/execute-code.tool";
+
+// Graph (consumers may use independently)
+export * from "./graph/index";
+
+// WebSocket event types
+export type { WsEvent, ThreadTitleUpdatedEvent } from "./ws/index";

package/src/routes/chat.ts

@@ -0,0 +1,38 @@
+import { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import z from "zod";
+import { HTTPException } from "hono/http-exception";
+import type { CortexAppEnv } from "../types.ts";
+import { requireAuth } from "../auth/middleware.ts";
+import { stream } from "../ai/index.ts";
+
+export function createChatRoutes() {
+  const app = new Hono<CortexAppEnv>();
+
+  app.post(
+    "/chat",
+    requireAuth,
+    zValidator(
+      "json",
+      z.object({
+        id: z.string(),
+        messages: z.array(z.unknown()),
+      }),
+    ),
+    async function (c) {
+      const config = c.get("agentConfig");
+      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) {
+        throw new HTTPException(404, { message: "Not found" });
+      }
+
+      return stream(messages, thread, userId, token, config);
+    },
+  );
+
+  return app;
+}

package/src/routes/files.ts

@@ -0,0 +1,105 @@
+import { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import z from "zod";
+import { HTTPException } from "hono/http-exception";
+import { safeValidateUIMessages, type ToolUIPart, type UIMessage } from "ai";
+import type { CortexAppEnv } from "../types.ts";
+import { requireAuth } from "../auth/middleware.ts";
+
+export function createFileRoutes() {
+  const app = new Hono<CortexAppEnv>();
+
+  app.get("/files/:id", requireAuth, async function (c) {
+    const config = c.get("agentConfig");
+    const id = c.req.param("id");
+    const { id: userId } = c.get("user");
+    const file = await config.db.capturedFiles.getById(id, userId);
+
+    if (!file) {
+      throw new HTTPException(404, { message: "File not found" });
+    }
+
+    const fileStream = await config.storage.stream(`captured_files/${id}`);
+    return new Response(fileStream, {
+      headers: {
+        "Content-Type": "application/octet-stream",
+        "Content-Disposition": `attachment; filename="${file.name}"`,
+      },
+    });
+  });
+
+  app.post(
+    "/files",
+    requireAuth,
+    zValidator(
+      "json",
+      z.object({
+        toolCallId: z.string(),
+        message: z.unknown().transform(async (message, ctx) => {
+          const result = await safeValidateUIMessages({
+            messages: [message],
+          });
+          if (!result.success) {
+            ctx.addIssue({
+              code: "custom",
+              path: ["message"],
+              message: "Invalid message format",
+            });
+            return z.NEVER;
+          }
+
+          return result.data[0]!;
+        }),
+        files: z.array(
+          z.object({
+            id: z.string(),
+            file: z.object({
+              name: z.string(),
+              bytes: z.string(),
+            }),
+          }),
+        ),
+      }),
+    ),
+    async function (c) {
+      const config = c.get("agentConfig");
+      const { message, toolCallId, files } = c.req.valid("json");
+      const { id: userId } = c.get("user");
+
+      function isTool(value: UIMessage["parts"][number]): value is ToolUIPart {
+        return value.type.startsWith("tool-");
+      }
+
+      const toolPart = message.parts
+        .filter(isTool)
+        .find((x) => x.toolCallId === toolCallId);
+
+      if (!toolPart) {
+        throw new HTTPException(423, {
+          message: "Invalid tool call id",
+        });
+      }
+
+      const result = await config.db.capturedFiles.create(
+        userId,
+        message.id,
+        toolPart,
+        files,
+      );
+
+      // Store file bytes
+      await Promise.all(
+        result.map(async (r, i) => {
+          await config.storage.put(
+            `captured_files/${r.uploadId}`,
+            files[i]!.file.bytes,
+          );
+        }),
+      );
+
+      return c.json(result);
+    },
+  );
+
+  return app;
+}

package/src/routes/index.ts

@@ -0,0 +1,4 @@
+export { createThreadRoutes } from "./threads.ts";
+export { createChatRoutes } from "./chat.ts";
+export { createFileRoutes } from "./files.ts";
+export { createWsRoute } from "./ws.ts";

package/src/routes/threads.ts

@@ -0,0 +1,69 @@
+import { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import z from "zod";
+import type { CortexAppEnv } from "../types.ts";
+import { requireAuth } from "../auth/middleware.ts";
+import { generateTitle } from "../ai/index.ts";
+
+export function createThreadRoutes() {
+  const app = new Hono<CortexAppEnv>();
+
+  app.get("/threads", requireAuth, async function (c) {
+    const config = c.get("agentConfig");
+    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 })),
+      );
+    return c.json(threads);
+  });
+
+  app.post(
+    "/threads",
+    requireAuth,
+    zValidator("json", z.object({ prompt: z.string() })),
+    async function (c) {
+      const config = c.get("agentConfig");
+      const agentId = c.get("agentId");
+      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 });
+    },
+  );
+
+  app.delete("/threads/:threadId", requireAuth, async function (c) {
+    const config = c.get("agentConfig");
+    const threadId = c.req.param("threadId");
+    await config.db.threads.delete(c.get("user").id, threadId);
+    return c.body(null, 204);
+  });
+
+  app.get("/threads/:threadId/messages", requireAuth, async function (c) {
+    const config = c.get("agentConfig");
+    const threadId = c.req.param("threadId");
+    const messages = await config.db.messages
+      .list(c.get("user").id, threadId)
+      .then((x) => x.map((y) => y.content));
+    return c.json(messages);
+  });
+
+  app.post(
+    "/threads/:threadId/session",
+    requireAuth,
+    zValidator("json", z.object({ session: z.record(z.unknown()) })),
+    async function (c) {
+      const config = c.get("agentConfig");
+      const threadId = c.req.param("threadId");
+      const { session } = c.req.valid("json");
+      await config.db.threads.updateSession(threadId, session);
+      return c.body(null, 204);
+    },
+  );
+
+  return app;
+}

package/src/routes/ws.ts

@@ -0,0 +1,33 @@
+import { Hono } from "hono";
+import { upgradeWebSocket } from "hono/bun";
+import type { AppEnv } from "../types.ts";
+import { addConnection, removeConnection } from "../ws/index.ts";
+
+export function createWsRoute() {
+  const app = new Hono<AppEnv>();
+
+  app.get(
+    "/ws",
+    upgradeWebSocket(function (c) {
+      const user = c.get("user");
+      const userId = user?.id;
+
+      return {
+        onOpen(_, ws) {
+          if (userId) {
+            addConnection(userId, ws);
+          }
+          ws.send("Connected!");
+        },
+
+        onClose(_, ws) {
+          if (userId) {
+            removeConnection(userId, ws);
+          }
+        },
+      };
+    }),
+  );
+
+  return app;
+}

package/src/types.ts

@@ -0,0 +1,50 @@
+import type { ToolUIPart, UIMessage } from "ai";
+import type { ResolvedCortexAgentConfig } from "./config";
+
+export type Thread = {
+  id: string;
+  userId: string;
+  agentId: string;
+  title: string | null;
+  session: Record<string, unknown> | null;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export type StoredMessage = {
+  id: string;
+  threadId: string;
+  text: string | null;
+  content: UIMessage;
+  role: "system" | "user" | "assistant" | "tool";
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export type CapturedFileInput = {
+  id: string;
+  file: { name: string; bytes: string };
+};
+
+export type AppEnv = {
+  Bindings: {};
+  Variables: {
+    user: { id: string; token: string } | undefined;
+  };
+};
+
+export type AuthedAppEnv = {
+  Bindings: {};
+  Variables: {
+    user: { id: string; token: string };
+  };
+};
+
+export type CortexAppEnv = {
+  Bindings: {};
+  Variables: {
+    user: { id: string; token: string };
+    agentConfig: ResolvedCortexAgentConfig;
+    agentId: string;
+  };
+};

package/src/ws/connections.ts

@@ -0,0 +1,23 @@
+import type { WSContext } from "hono/ws";
+
+const connections = new Map<string, WSContext[]>();
+
+export function addConnection(userId: string, ws: WSContext) {
+  const sockets = connections.get(userId) ?? [];
+  sockets.push(ws);
+  connections.set(userId, sockets);
+}
+
+export function removeConnection(userId: string, ws: WSContext) {
+  let sockets = connections.get(userId) ?? [];
+  sockets = sockets.filter((x) => x !== ws);
+  if (sockets.length) {
+    connections.set(userId, sockets);
+  } else {
+    connections.delete(userId);
+  }
+}
+
+export function getConnections(userId: string) {
+  return connections.get(userId) ?? [];
+}

package/src/ws/events.ts

@@ -0,0 +1,6 @@
+export type ThreadTitleUpdatedEvent = {
+  type: "thread:title-updated";
+  payload: { threadId: string; title: string };
+};
+
+export type WsEvent = ThreadTitleUpdatedEvent;

package/src/ws/index.ts

@@ -0,0 +1,7 @@
+export {
+  addConnection,
+  removeConnection,
+  getConnections,
+} from "./connections.ts";
+export { notify } from "./notify.ts";
+export type { WsEvent, ThreadTitleUpdatedEvent } from "./events.ts";

package/src/ws/notify.ts

@@ -0,0 +1,9 @@
+import { getConnections } from "./connections.ts";
+import type { WsEvent } from "./events.ts";
+
+export function notify(userId: string, event: WsEvent) {
+  const message = JSON.stringify(event);
+  for (const ws of getConnections(userId)) {
+    ws.send(message);
+  }
+}