@hexis-ai/engram-server 0.1.6 → 0.2.0

package/dist/adapters/memory-key-store.d.ts

@@ -20,5 +20,5 @@ export declare class InMemoryKeyStore implements KeyStore {
     listKeys(workspaceId: string): Promise<ApiKeyInfo[]>;
     revokeKey(workspaceId: string, keyId: string): Promise<void>;
     resolveKey(rawKey: string): Promise<KeyResolution | null>;
-    registerLegacyKey(workspaceId: string, rawKey: string, name?: string): Promise<void>;
+    registerKey(workspaceId: string, rawKey: string, name?: string): Promise<void>;
 }

package/dist/adapters/memory-key-store.js

@@ -77,7 +77,7 @@ export class InMemoryKeyStore {
         this.keys.set(id, { ...row, lastUsedAt: new Date().toISOString() });
         return { workspaceId: row.workspaceId, keyId: row.id };
     }
-    async registerLegacyKey(workspaceId, rawKey, name) {
+    async registerKey(workspaceId, rawKey, name) {
         if (!this.workspaces.has(workspaceId))
             throw new Error("workspace_not_found");
         const hash = hashKey(rawKey);

package/dist/adapters/postgres-key-store.d.ts

@@ -22,5 +22,5 @@ export declare class PostgresKeyStore implements KeyStore {
     listKeys(workspaceId: string): Promise<ApiKeyInfo[]>;
     revokeKey(workspaceId: string, keyId: string): Promise<void>;
     resolveKey(rawKey: string): Promise<KeyResolution | null>;
-    registerLegacyKey(workspaceId: string, rawKey: string, name?: string): Promise<void>;
+    registerKey(workspaceId: string, rawKey: string, name?: string): Promise<void>;
 }

package/dist/adapters/postgres-key-store.js

@@ -106,7 +106,7 @@ export class PostgresKeyStore {
     `.catch(() => undefined);
         return { workspaceId: row.workspace_id, keyId: row.id };
     }
-    async registerLegacyKey(workspaceId, rawKey, name) {
+    async registerKey(workspaceId, rawKey, name) {
         const ws = await this.getWorkspace(workspaceId);
         if (!ws)
             throw new Error("workspace_not_found");
@@ -114,7 +114,7 @@ export class PostgresKeyStore {
         const id = crypto.randomUUID();
         await this.sql `
       INSERT INTO engram_api_keys (id, workspace_id, key_hash, prefix, name)
-      VALUES (${id}, ${workspaceId}, ${hash}, ${keyPrefix(rawKey)}, ${name ?? "legacy"})
+      VALUES (${id}, ${workspaceId}, ${hash}, ${keyPrefix(rawKey)}, ${name ?? null})
       ON CONFLICT (key_hash) DO NOTHING
     `;
     }

package/dist/admin.js

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import { isValidWorkspaceId } from "./key-store";
+import { createWorkspaceSchema, issueKeySchema, parseJsonBody } from "./schemas";
 /**
  * Build the admin sub-router. Mount under `/admin/v1`.
  *
@@ -18,9 +19,9 @@ export function createAdminRouter(opts) {
         await next();
     });
     app.post("/workspaces", async (c) => {
-        const body = (await c.req.json().catch(() => null));
-        if (body === null)
-            return c.json({ error: "invalid_json" }, 400);
+        const body = await parseJsonBody(c, createWorkspaceSchema);
+        if (body instanceof Response)
+            return body;
         if (body.id !== undefined && !isValidWorkspaceId(body.id)) {
             return c.json({ error: "invalid_workspace_id" }, 400);
         }
@@ -67,9 +68,14 @@ export function createAdminRouter(opts) {
         const ws = await opts.keyStore.getWorkspace(workspaceId);
         if (!ws)
             return c.json({ error: "workspace_not_found" }, 404);
-        const body = (await c.req.json().catch(() => ({})));
+        // The body is optional here — an empty POST issues a key with no name.
+        const raw = await c.req.json().catch(() => ({}));
+        const parsed = issueKeySchema.safeParse(raw);
+        if (!parsed.success) {
+            return c.json({ error: "invalid_body", issues: parsed.error.issues }, 400);
+        }
         const key = await opts.keyStore.issueKey(workspaceId, {
-            ...(body.name !== undefined ? { name: body.name } : {}),
+            ...(parsed.data.name !== undefined ? { name: parsed.data.name } : {}),
         });
         return c.json(key);
     });

package/dist/context.d.ts

@@ -0,0 +1,26 @@
+import type { StorageAdapter } from "./storage";
+/**
+ * The per-request workspace context. Produced by an `AuthResolver` from a
+ * raw API key and stashed on the Hono context so route handlers can reach
+ * the tenant-scoped storage adapter without re-resolving the key.
+ */
+export interface WorkspaceContext {
+    workspaceId: string;
+    /** The storage adapter scoped to this workspace. */
+    storage: StorageAdapter;
+}
+/**
+ * Resolve an API key (raw `Authorization: Bearer <key>` or `X-Api-Key`
+ * token) into a workspace context. Throwing or returning null short-circuits
+ * the request to 401.
+ */
+export interface AuthResolver {
+    (apiKey: string): Promise<WorkspaceContext | null> | WorkspaceContext | null;
+}
+/** Hono environment shared by `createServer` and every `/v1` route module. */
+export interface Env {
+    Variables: {
+        ctx: WorkspaceContext;
+        request_id: string;
+    };
+}

package/dist/context.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { createServer, type CreateServerOptions, type AuthResolver, type WorkspaceContext, } from "./server";
+export { createServer, type CreateServerOptions } from "./server";
+export { type AuthResolver, type WorkspaceContext } from "./context";
 export { foldEvents, type StorageAdapter, type SessionRow, } from "./storage";
 export { InMemoryAdapter } from "./adapters/memory";
 export { PostgresAdapter, type PostgresAdapterOptions, type SqlClient, } from "./adapters/postgres";

package/dist/index.js

@@ -1,4 +1,5 @@
-export { createServer, } from "./server";
+export { createServer } from "./server";
+export {} from "./context";
 export { foldEvents, } from "./storage";
 export { InMemoryAdapter } from "./adapters/memory";
 export { PostgresAdapter, } from "./adapters/postgres";

package/dist/key-store.d.ts

@@ -50,11 +50,11 @@ export interface KeyStore {
      */
     resolveKey(rawKey: string): Promise<KeyResolution | null>;
     /**
-     * Register a pre-existing raw key under a workspace. Used at bootstrap to
-     * preserve a legacy `ENGRAM_API_KEY` without forcing a re-provisioning of
-     * existing callers. Idempotent on (workspace_id, key_hash).
+     * Register a caller-supplied raw key under a workspace, instead of minting
+     * a random one via `issueKey`. Used by the dev entrypoint to seed a known,
+     * fixed key. Idempotent on (workspace_id, key_hash).
      */
-    registerLegacyKey(workspaceId: string, rawKey: string, name?: string): Promise<void>;
+    registerKey(workspaceId: string, rawKey: string, name?: string): Promise<void>;
 }
 export declare const KEY_PREFIX = "eng_";
 export declare function generateRawKey(): string;

package/dist/routes/helpers.d.ts

@@ -0,0 +1,22 @@
+import type { Context } from "hono";
+import type { Session } from "@hexis-ai/engram-core";
+import type { PersonMap } from "@hexis-ai/engram-sdk";
+import type { StorageAdapter } from "../storage";
+/** Resolved server config threaded into each `/v1` route module. */
+export interface RouteConfig {
+    /** Generates session ids when the client doesn't supply one. */
+    newSessionId: () => string;
+    /** Default `?limit=` when the client omits it. */
+    defaultListLimit: number;
+    /** Hard cap on `?limit=` (and the search corpus size). */
+    maxListLimit: number;
+}
+/** Parse and clamp a `?limit=` query param into `[1, max]`, falling back to `def`. */
+export declare function clampLimit(c: Context, def: number, max: number): number;
+/**
+ * Build a deduped person_id → PersonInfo map covering every person id
+ * referenced by `sessions` (participants ∪ viewable_by). Returns {} if
+ * there are no session rows. Persons that exist as ids in sessions but
+ * have no engram_persons row are simply absent from the map.
+ */
+export declare function resolvePersonMap(storage: StorageAdapter, sessions: Pick<Session, "participants" | "viewable_by">[]): Promise<PersonMap>;

package/dist/routes/helpers.js

@@ -0,0 +1,32 @@
+/** Parse and clamp a `?limit=` query param into `[1, max]`, falling back to `def`. */
+export function clampLimit(c, def, max) {
+    const raw = c.req.query("limit");
+    if (!raw)
+        return def;
+    const n = parseInt(raw, 10);
+    if (isNaN(n) || n < 1)
+        return def;
+    return Math.min(n, max);
+}
+/**
+ * Build a deduped person_id → PersonInfo map covering every person id
+ * referenced by `sessions` (participants ∪ viewable_by). Returns {} if
+ * there are no session rows. Persons that exist as ids in sessions but
+ * have no engram_persons row are simply absent from the map.
+ */
+export async function resolvePersonMap(storage, sessions) {
+    const ids = new Set();
+    for (const s of sessions) {
+        for (const id of s.participants ?? [])
+            ids.add(id);
+        for (const id of s.viewable_by ?? [])
+            ids.add(id);
+    }
+    if (ids.size === 0)
+        return {};
+    const list = await storage.getPersons([...ids]);
+    const map = {};
+    for (const p of list)
+        map[p.id] = p;
+    return map;
+}

package/dist/routes/persons.d.ts

@@ -0,0 +1,13 @@
+import { Hono } from "hono";
+import type { Env } from "../context";
+import { type RouteConfig } from "./helpers";
+/**
+ * Person routes. Mount under `/v1`:
+ *   POST  /v1/persons              create a person (server allocates the id)
+ *   PUT   /v1/persons/:id          upsert at a host-supplied id
+ *   PATCH /v1/persons/:id          patch profile fields
+ *   GET   /v1/persons/:id          fetch one person
+ *   GET   /v1/persons              list / free-text search persons
+ *   GET   /v1/persons/:id/sessions sessions this person participates in / can view
+ */
+export declare function personsRoutes(cfg: RouteConfig): Hono<Env>;

package/dist/routes/persons.js

@@ -0,0 +1,67 @@
+import { Hono } from "hono";
+import { parseJsonBody, personCreateSchema, personUpdateSchema } from "../schemas";
+import { clampLimit, resolvePersonMap } from "./helpers";
+/**
+ * Person routes. Mount under `/v1`:
+ *   POST  /v1/persons              create a person (server allocates the id)
+ *   PUT   /v1/persons/:id          upsert at a host-supplied id
+ *   PATCH /v1/persons/:id          patch profile fields
+ *   GET   /v1/persons/:id          fetch one person
+ *   GET   /v1/persons              list / free-text search persons
+ *   GET   /v1/persons/:id/sessions sessions this person participates in / can view
+ */
+export function personsRoutes(cfg) {
+    const app = new Hono();
+    app.post("/persons", async (c) => {
+        const body = await parseJsonBody(c, personCreateSchema);
+        if (body instanceof Response)
+            return body;
+        const p = await c.var.ctx.storage.createPerson(body);
+        return c.json(p, 201);
+    });
+    app.put("/persons/:id", async (c) => {
+        const id = c.req.param("id");
+        const body = await parseJsonBody(c, personCreateSchema);
+        if (body instanceof Response)
+            return body;
+        const p = await c.var.ctx.storage.upsertPerson(id, body);
+        return c.json(p);
+    });
+    app.patch("/persons/:id", async (c) => {
+        const id = c.req.param("id");
+        const body = await parseJsonBody(c, personUpdateSchema);
+        if (body instanceof Response)
+            return body;
+        const p = await c.var.ctx.storage.updatePerson(id, body);
+        if (!p)
+            return c.json({ error: "person_not_found" }, 404);
+        return c.json(p);
+    });
+    app.get("/persons/:id", async (c) => {
+        const id = c.req.param("id");
+        const p = await c.var.ctx.storage.getPerson(id);
+        if (!p)
+            return c.json({ error: "person_not_found" }, 404);
+        return c.json(p);
+    });
+    app.get("/persons", async (c) => {
+        const limit = clampLimit(c, cfg.defaultListLimit, cfg.maxListLimit);
+        const q = c.req.query("q") || undefined;
+        const persons = await c.var.ctx.storage.listPersons({ limit, q });
+        return c.json({ persons });
+    });
+    app.get("/persons/:id/sessions", async (c) => {
+        const id = c.req.param("id");
+        const limit = clampLimit(c, cfg.defaultListLimit, cfg.maxListLimit);
+        const channel = c.req.query("channel") || undefined;
+        const scope = c.req.query("scope") === "viewable" ? "viewable" : "participant";
+        const sessions = await c.var.ctx.storage.sessionsForPerson(id, {
+            limit,
+            channel,
+            scope,
+        });
+        const persons = await resolvePersonMap(c.var.ctx.storage, sessions);
+        return c.json({ sessions, persons });
+    });
+    return app;
+}

package/dist/routes/search.d.ts

@@ -0,0 +1,9 @@
+import { Hono } from "hono";
+import type { Env } from "../context";
+import { type RouteConfig } from "./helpers";
+/**
+ * Search route. Mount under `/v1`:
+ *   POST /v1/search   score the workspace corpus against a query session
+ *                     (an existing session id, or an inline session)
+ */
+export declare function searchRoutes(cfg: RouteConfig): Hono<Env>;

package/dist/routes/search.js

@@ -0,0 +1,40 @@
+import { Hono } from "hono";
+import { buildIndex, search } from "@hexis-ai/engram-core";
+import { parseJsonBody, searchRequestSchema } from "../schemas";
+import { resolvePersonMap } from "./helpers";
+/**
+ * Search route. Mount under `/v1`:
+ *   POST /v1/search   score the workspace corpus against a query session
+ *                     (an existing session id, or an inline session)
+ */
+export function searchRoutes(cfg) {
+    const app = new Hono();
+    app.post("/search", async (c) => {
+        const body = await parseJsonBody(c, searchRequestSchema);
+        if (body instanceof Response)
+            return body;
+        const corpus = await c.var.ctx.storage.listSessions({
+            limit: cfg.maxListLimit,
+        });
+        let queryQuery;
+        if ("sessionId" in body.query) {
+            const q = await c.var.ctx.storage.getSession(body.query.sessionId);
+            if (!q)
+                return c.json({ error: "query_session_not_found" }, 404);
+            queryQuery = q;
+        }
+        else {
+            queryQuery = body.query.session;
+        }
+        const index = buildIndex(corpus);
+        const opts = (body.options ?? {});
+        const queryParticipants = opts.queryParticipants ?? queryQuery.participants ?? [];
+        const results = search(queryQuery.steps, index, {
+            ...opts,
+            queryParticipants,
+        });
+        const persons = await resolvePersonMap(c.var.ctx.storage, results.map((r) => r.session));
+        return c.json({ results, persons });
+    });
+    return app;
+}

package/dist/routes/sessions.d.ts

@@ -0,0 +1,11 @@
+import { Hono } from "hono";
+import type { Env } from "../context";
+import { type RouteConfig } from "./helpers";
+/**
+ * Session routes. Mount under `/v1`:
+ *   POST /v1/sessions            create a session
+ *   POST /v1/sessions/:id/events append events
+ *   GET  /v1/sessions/:id        fetch one session + its persons map
+ *   GET  /v1/sessions            list recent sessions + persons map
+ */
+export declare function sessionsRoutes(cfg: RouteConfig): Hono<Env>;

package/dist/routes/sessions.js

@@ -0,0 +1,51 @@
+import { Hono } from "hono";
+import { eventBatchSchema, parseJsonBody, sessionInitSchema } from "../schemas";
+import { clampLimit, resolvePersonMap } from "./helpers";
+/**
+ * Session routes. Mount under `/v1`:
+ *   POST /v1/sessions            create a session
+ *   POST /v1/sessions/:id/events append events
+ *   GET  /v1/sessions/:id        fetch one session + its persons map
+ *   GET  /v1/sessions            list recent sessions + persons map
+ */
+export function sessionsRoutes(cfg) {
+    const app = new Hono();
+    app.post("/sessions", async (c) => {
+        const body = await parseJsonBody(c, sessionInitSchema);
+        if (body instanceof Response)
+            return body;
+        const id = body.id ?? cfg.newSessionId();
+        const createdAt = new Date().toISOString();
+        await c.var.ctx.storage.createSession({ ...body, id, createdAt });
+        return c.json({ id });
+    });
+    app.post("/sessions/:id/events", async (c) => {
+        const id = c.req.param("id");
+        const body = await parseJsonBody(c, eventBatchSchema);
+        if (body instanceof Response)
+            return body;
+        try {
+            await c.var.ctx.storage.appendEvents(id, body.events);
+        }
+        catch (e) {
+            return c.json({ error: "session_not_found", message: e.message }, 404);
+        }
+        return c.body(null, 204);
+    });
+    app.get("/sessions/:id", async (c) => {
+        const id = c.req.param("id");
+        const s = await c.var.ctx.storage.getSession(id);
+        if (!s)
+            return c.json({ error: "session_not_found" }, 404);
+        const persons = await resolvePersonMap(c.var.ctx.storage, [s]);
+        return c.json({ session: s, persons });
+    });
+    app.get("/sessions", async (c) => {
+        const limit = clampLimit(c, cfg.defaultListLimit, cfg.maxListLimit);
+        const channel = c.req.query("channel") || undefined;
+        const sessions = await c.var.ctx.storage.listSessions({ limit, channel });
+        const persons = await resolvePersonMap(c.var.ctx.storage, sessions);
+        return c.json({ sessions, persons });
+    });
+    return app;
+}

package/dist/schemas.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Zod schemas for every request body the server accepts. These are the
+ * trust boundary: handlers parse with `parseJsonBody` and never cast raw
+ * JSON straight onto a wire type.
+ *
+ * The wire types themselves live in `@hexis-ai/engram-sdk` (dependency-free,
+ * reusable by language ports). Each schema is `satisfies z.ZodType<…>` so a
+ * drift between a schema and its wire type fails the build here.
+ */
+import { z } from "zod";
+import type { Context } from "hono";
+export declare const sessionInitSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    channel: z.ZodOptional<z.ZodString>;
+    participants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    viewable_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const sessionEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"step">;
+    seq: z.ZodNumber;
+    at: z.ZodString;
+    tool: z.ZodString;
+    resources: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"participant">;
+    seq: z.ZodNumber;
+    at: z.ZodString;
+    personId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"title">;
+    seq: z.ZodNumber;
+    at: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"end">;
+    seq: z.ZodNumber;
+    at: z.ZodString;
+}, z.core.$strip>], "type">;
+export declare const eventBatchSchema: z.ZodObject<{
+    events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"step">;
+        seq: z.ZodNumber;
+        at: z.ZodString;
+        tool: z.ZodString;
+        resources: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"participant">;
+        seq: z.ZodNumber;
+        at: z.ZodString;
+        personId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"title">;
+        seq: z.ZodNumber;
+        at: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"end">;
+        seq: z.ZodNumber;
+        at: z.ZodString;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>;
+export declare const personCreateSchema: z.ZodObject<{
+    display_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const personUpdateSchema: z.ZodObject<{
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const searchRequestSchema: z.ZodObject<{
+    query: z.ZodUnion<readonly [z.ZodObject<{
+        sessionId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        session: z.ZodObject<{
+            steps: z.ZodArray<z.ZodObject<{
+                tool: z.ZodString;
+                resources: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>;
+            participants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>]>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const createWorkspaceSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    issueKey: z.ZodOptional<z.ZodBoolean>;
+    keyName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const issueKeySchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Read and validate a JSON request body. Returns the parsed value, or a
+ * `Response` (400) the caller should return as-is:
+ *
+ *   const body = await parseJsonBody(c, sessionInitSchema);
+ *   if (body instanceof Response) return body;
+ */
+export declare function parseJsonBody<T>(c: Context, schema: z.ZodType<T>): Promise<T | Response>;

package/dist/schemas.js

@@ -0,0 +1,108 @@
+/**
+ * Zod schemas for every request body the server accepts. These are the
+ * trust boundary: handlers parse with `parseJsonBody` and never cast raw
+ * JSON straight onto a wire type.
+ *
+ * The wire types themselves live in `@hexis-ai/engram-sdk` (dependency-free,
+ * reusable by language ports). Each schema is `satisfies z.ZodType<…>` so a
+ * drift between a schema and its wire type fails the build here.
+ */
+import { z } from "zod";
+// --- Sessions --------------------------------------------------------
+export const sessionInitSchema = z.object({
+    id: z.string().min(1).optional(),
+    title: z.string().optional(),
+    channel: z.string().optional(),
+    participants: z.array(z.string()).optional(),
+    viewable_by: z.array(z.string()).optional(),
+});
+const stepEventSchema = z.object({
+    type: z.literal("step"),
+    seq: z.number().int().nonnegative(),
+    at: z.string(),
+    tool: z.string(),
+    resources: z.array(z.string()),
+});
+const participantEventSchema = z.object({
+    type: z.literal("participant"),
+    seq: z.number().int().nonnegative(),
+    at: z.string(),
+    personId: z.string(),
+});
+const titleEventSchema = z.object({
+    type: z.literal("title"),
+    seq: z.number().int().nonnegative(),
+    at: z.string(),
+    title: z.string(),
+});
+const endEventSchema = z.object({
+    type: z.literal("end"),
+    seq: z.number().int().nonnegative(),
+    at: z.string(),
+});
+export const sessionEventSchema = z.discriminatedUnion("type", [
+    stepEventSchema,
+    participantEventSchema,
+    titleEventSchema,
+    endEventSchema,
+]);
+export const eventBatchSchema = z.object({
+    events: z.array(sessionEventSchema),
+});
+// --- Persons ---------------------------------------------------------
+export const personCreateSchema = z.object({
+    display_name: z.string().optional(),
+});
+export const personUpdateSchema = z.object({
+    display_name: z.string().nullable().optional(),
+});
+// --- Search ----------------------------------------------------------
+const searchQuerySchema = z.union([
+    z.object({ sessionId: z.string().min(1) }),
+    z.object({
+        session: z.object({
+            steps: z.array(z.object({ tool: z.string(), resources: z.array(z.string()) })),
+            participants: z.array(z.string()).optional(),
+        }),
+    }),
+]);
+export const searchRequestSchema = z.object({
+    query: searchQuerySchema,
+    // `options` is forwarded as-is to engram-core's pure `search()`, which
+    // tolerates partial/absent options. Only the query (which drives storage
+    // lookups) needs strict validation here.
+    options: z.record(z.string(), z.unknown()).optional(),
+});
+// --- Admin -----------------------------------------------------------
+export const createWorkspaceSchema = z.object({
+    id: z.string().optional(),
+    name: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    issueKey: z.boolean().optional(),
+    keyName: z.string().optional(),
+});
+export const issueKeySchema = z.object({
+    name: z.string().optional(),
+});
+// --- Helper ----------------------------------------------------------
+/**
+ * Read and validate a JSON request body. Returns the parsed value, or a
+ * `Response` (400) the caller should return as-is:
+ *
+ *   const body = await parseJsonBody(c, sessionInitSchema);
+ *   if (body instanceof Response) return body;
+ */
+export async function parseJsonBody(c, schema) {
+    let raw;
+    try {
+        raw = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_json" }, 400);
+    }
+    const result = schema.safeParse(raw);
+    if (!result.success) {
+        return c.json({ error: "invalid_body", issues: result.error.issues }, 400);
+    }
+    return result.data;
+}

package/dist/server.d.ts

@@ -1,20 +1,8 @@
 import { Hono } from "hono";
-import type { StorageAdapter } from "./storage";
+import type { AuthResolver, Env } from "./context";
 import { type AdminOptions } from "./admin";
-/**
- * Resolve an API key (raw `Authorization: Bearer <key>` token) into a
- * workspace context. Throwing or returning null short-circuits to 401.
- */
-export interface AuthResolver {
-    (apiKey: string): Promise<WorkspaceContext | null> | WorkspaceContext | null;
-}
-export interface WorkspaceContext {
-    workspaceId: string;
-    /** The storage adapter scoped to this workspace. */
-    storage: StorageAdapter;
-}
 export interface CreateServerOptions {
-    /** Resolves Bearer tokens into workspace contexts. */
+    /** Resolves Bearer / X-Api-Key tokens into workspace contexts. */
     auth: AuthResolver;
     /**
      * Generates session ids. Defaults to `crypto.randomUUID()`.
@@ -32,11 +20,9 @@ export interface CreateServerOptions {
      */
     admin?: AdminOptions;
 }
-interface Env {
-    Variables: {
-        ctx: WorkspaceContext;
-        request_id: string;
-    };
-}
+/**
+ * Build the engram HTTP app. Wiring only: this sets up cross-cutting
+ * middleware (request id + access log), the workspace auth gate, and mounts
+ * the `/v1` route modules (`routes/*`) and the optional `/admin/v1` router.
+ */
 export declare function createServer(opts: CreateServerOptions): Hono<Env>;
-export {};

package/dist/server.js

@@ -1,11 +1,20 @@
 import { Hono } from "hono";
-import { buildIndex, search, } from "@hexis-ai/engram-core";
 import { log, newRequestId } from "./logger";
 import { createAdminRouter } from "./admin";
+import { sessionsRoutes } from "./routes/sessions";
+import { personsRoutes } from "./routes/persons";
+import { searchRoutes } from "./routes/search";
+/**
+ * Build the engram HTTP app. Wiring only: this sets up cross-cutting
+ * middleware (request id + access log), the workspace auth gate, and mounts
+ * the `/v1` route modules (`routes/*`) and the optional `/admin/v1` router.
+ */
 export function createServer(opts) {
-    const newId = opts.newSessionId ?? (() => crypto.randomUUID());
-    const defaultLimit = opts.defaultListLimit ?? 100;
-    const maxLimit = opts.maxListLimit ?? 500;
+    const cfg = {
+        newSessionId: opts.newSessionId ?? (() => crypto.randomUUID()),
+        defaultListLimit: opts.defaultListLimit ?? 100,
+        maxListLimit: opts.maxListLimit ?? 500,
+    };
     const app = new Hono();
     // Request id + access log middleware. Runs for every route.
     app.use("*", async (c, next) => {
@@ -54,6 +63,7 @@ export function createServer(opts) {
     if (opts.admin) {
         app.route("/admin/v1", createAdminRouter(opts.admin));
     }
+    // Workspace auth gate — every `/v1/*` route runs behind this.
     app.use("/v1/*", async (c, next) => {
         const apiKey = c.req.header("x-api-key") ??
             c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
@@ -68,157 +78,8 @@ export function createServer(opts) {
     // Identity probe — echoes the workspace the caller's key resolves to.
     // Used by clients (e.g. engram-web) to label which tenant they're viewing.
     app.get("/v1/me", (c) => c.json({ workspaceId: c.var.ctx.workspaceId }));
-    // --- Sessions --------------------------------------------------------
-    app.post("/v1/sessions", async (c) => {
-        const body = (await c.req.json().catch(() => null));
-        if (body === null)
-            return c.json({ error: "invalid_json" }, 400);
-        const id = body.id ?? newId();
-        const createdAt = new Date().toISOString();
-        await c.var.ctx.storage.createSession({
-            ...body,
-            id,
-            createdAt,
-        });
-        return c.json({ id });
-    });
-    app.post("/v1/sessions/:id/events", async (c) => {
-        const id = c.req.param("id");
-        const body = (await c.req.json().catch(() => null));
-        if (!body || !Array.isArray(body.events)) {
-            return c.json({ error: "events_array_required" }, 400);
-        }
-        try {
-            await c.var.ctx.storage.appendEvents(id, body.events);
-        }
-        catch (e) {
-            return c.json({ error: "session_not_found", message: e.message }, 404);
-        }
-        return c.body(null, 204);
-    });
-    app.get("/v1/sessions/:id", async (c) => {
-        const id = c.req.param("id");
-        const s = await c.var.ctx.storage.getSession(id);
-        if (!s)
-            return c.json({ error: "session_not_found" }, 404);
-        const persons = await resolvePersonMap(c.var.ctx.storage, [s]);
-        return c.json({ session: s, persons });
-    });
-    app.get("/v1/sessions", async (c) => {
-        const limit = clampLimit(c, defaultLimit, maxLimit);
-        const channel = c.req.query("channel") || undefined;
-        const sessions = await c.var.ctx.storage.listSessions({ limit, channel });
-        const persons = await resolvePersonMap(c.var.ctx.storage, sessions);
-        return c.json({ sessions, persons });
-    });
-    app.post("/v1/search", async (c) => {
-        const body = (await c.req.json().catch(() => null));
-        if (!body || !body.query)
-            return c.json({ error: "query_required" }, 400);
-        const corpus = await c.var.ctx.storage.listSessions({ limit: maxLimit });
-        let queryQuery;
-        if ("sessionId" in body.query) {
-            const q = await c.var.ctx.storage.getSession(body.query.sessionId);
-            if (!q)
-                return c.json({ error: "query_session_not_found" }, 404);
-            queryQuery = q;
-        }
-        else {
-            queryQuery = body.query.session;
-        }
-        const index = buildIndex(corpus);
-        const opts = body.options ?? {};
-        const queryParticipants = opts.queryParticipants ?? queryQuery.participants ?? [];
-        const results = search(queryQuery.steps, index, {
-            ...opts,
-            queryParticipants,
-        });
-        const persons = await resolvePersonMap(c.var.ctx.storage, results.map((r) => r.session));
-        return c.json({ results, persons });
-    });
-    // --- Persons ---------------------------------------------------------
-    app.post("/v1/persons", async (c) => {
-        const body = (await c.req.json().catch(() => null));
-        if (body === null)
-            return c.json({ error: "invalid_json" }, 400);
-        const p = await c.var.ctx.storage.createPerson(body);
-        return c.json(p, 201);
-    });
-    app.put("/v1/persons/:id", async (c) => {
-        const id = c.req.param("id");
-        const body = (await c.req.json().catch(() => null));
-        if (body === null)
-            return c.json({ error: "invalid_json" }, 400);
-        const p = await c.var.ctx.storage.upsertPerson(id, body);
-        return c.json(p);
-    });
-    app.patch("/v1/persons/:id", async (c) => {
-        const id = c.req.param("id");
-        const body = (await c.req.json().catch(() => null));
-        if (body === null)
-            return c.json({ error: "invalid_json" }, 400);
-        const p = await c.var.ctx.storage.updatePerson(id, body);
-        if (!p)
-            return c.json({ error: "person_not_found" }, 404);
-        return c.json(p);
-    });
-    app.get("/v1/persons/:id", async (c) => {
-        const id = c.req.param("id");
-        const p = await c.var.ctx.storage.getPerson(id);
-        if (!p)
-            return c.json({ error: "person_not_found" }, 404);
-        return c.json(p);
-    });
-    app.get("/v1/persons", async (c) => {
-        const limit = clampLimit(c, defaultLimit, maxLimit);
-        const q = c.req.query("q") || undefined;
-        const persons = await c.var.ctx.storage.listPersons({ limit, q });
-        return c.json({ persons });
-    });
-    app.get("/v1/persons/:id/sessions", async (c) => {
-        const id = c.req.param("id");
-        const limit = clampLimit(c, defaultLimit, maxLimit);
-        const channel = c.req.query("channel") || undefined;
-        const scopeRaw = c.req.query("scope");
-        const scope = scopeRaw === "viewable" ? "viewable" : "participant";
-        const sessions = await c.var.ctx.storage.sessionsForPerson(id, {
-            limit,
-            channel,
-            scope,
-        });
-        const persons = await resolvePersonMap(c.var.ctx.storage, sessions);
-        return c.json({ sessions, persons });
-    });
+    app.route("/v1", sessionsRoutes(cfg));
+    app.route("/v1", personsRoutes(cfg));
+    app.route("/v1", searchRoutes(cfg));
     return app;
 }
-function clampLimit(c, def, max) {
-    const raw = c.req.query("limit");
-    if (!raw)
-        return def;
-    const n = parseInt(raw, 10);
-    if (isNaN(n) || n < 1)
-        return def;
-    return Math.min(n, max);
-}
-/**
- * Build a deduped person_id → PersonInfo map covering every person id
- * referenced by `sessions` (participants ∪ viewable_by). Returns {} if
- * there are no session rows. Persons that exist as ids in sessions but
- * have no engram_persons row are simply absent from the map.
- */
-async function resolvePersonMap(storage, sessions) {
-    const ids = new Set();
-    for (const s of sessions) {
-        for (const id of s.participants ?? [])
-            ids.add(id);
-        for (const id of s.viewable_by ?? [])
-            ids.add(id);
-    }
-    if (ids.size === 0)
-        return {};
-    const list = await storage.getPersons([...ids]);
-    const map = {};
-    for (const p of list)
-        map[p.id] = p;
-    return map;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-server",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Engram server: ingest agent session events, persist via a pluggable adapter, expose search.",
   "keywords": [
     "engram",
@@ -41,7 +41,6 @@
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "prepack": "bun run build",
     "pack": "bun run build && bun pm pack",
     "test": "bun test",
     "type-check": "tsc --noEmit",
@@ -49,8 +48,9 @@
   },
   "dependencies": {
     "@hexis-ai/engram-core": "^0.1.5",
-    "@hexis-ai/engram-sdk": "^0.1.5",
-    "hono": "^4.6.0"
+    "@hexis-ai/engram-sdk": "^0.2.0",
+    "hono": "^4.6.0",
+    "zod": "^4.0.0"
   },
   "peerDependencies": {
     "postgres": "^3.4.0"