@hexis-ai/engram-server 0.1.7 → 0.3.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";
@@ -6,3 +7,4 @@ export { type KeyStore, type Workspace, type ApiKeyInfo, type IssuedKey, type Ke
 export { InMemoryKeyStore } from "./adapters/memory-key-store";
 export { PostgresKeyStore } from "./adapters/postgres-key-store";
 export { createAdminRouter, type AdminOptions } from "./admin";
+export { buildOpenApiDocument } from "./openapi";

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";
@@ -6,3 +7,4 @@ export { generateRawKey, hashKey, keyPrefix, isValidWorkspaceId, } from "./key-s
 export { InMemoryKeyStore } from "./adapters/memory-key-store";
 export { PostgresKeyStore } from "./adapters/postgres-key-store";
 export { createAdminRouter } from "./admin";
+export { buildOpenApiDocument } from "./openapi";

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/openapi.d.ts

@@ -0,0 +1,8 @@
+type Json = Record<string, unknown>;
+/**
+ * Build the OpenAPI 3.1 document. Pure and deterministic — `gen-openapi.ts`
+ * writes its output to `openapi.json`, and `openapi.test.ts` asserts the
+ * committed file still matches.
+ */
+export declare function buildOpenApiDocument(): Json;
+export {};

package/dist/openapi.js

@@ -0,0 +1,296 @@
+/**
+ * OpenAPI 3.1 document for the engram HTTP API, assembled from the same Zod
+ * schemas the server validates with (`src/schemas.ts`). The request-body
+ * contract therefore cannot drift from what the server actually accepts —
+ * a sync test (`test/openapi.test.ts`) fails the build if it does.
+ *
+ * This is the language-neutral contract artifact. Non-TypeScript engram SDK
+ * ports generate their wire types from `packages/server/openapi.json`
+ * (produced by `bun run gen:openapi`) instead of hand-mirroring the
+ * TypeScript interfaces in `@hexis-ai/engram-sdk`.
+ *
+ * `info.version` is the API version (the `/v1` surface), not the npm package
+ * version — it changes only when the wire contract changes.
+ */
+import { z } from "zod";
+import { createWorkspaceSchema, eventBatchSchema, issueKeySchema, personCreateSchema, personUpdateSchema, searchRequestSchema, sessionInitSchema, } from "./schemas";
+/** Convert a Zod schema to a JSON Schema object for an OpenAPI component. */
+function toComponent(schema) {
+    const js = z.toJSONSchema(schema);
+    delete js.$schema;
+    return js;
+}
+const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
+const jsonBody = (schemaName, required = true) => ({
+    required,
+    content: { "application/json": { schema: ref(schemaName) } },
+});
+const pathParam = (name, description) => ({
+    name,
+    in: "path",
+    required: true,
+    schema: { type: "string" },
+    description,
+});
+const queryParam = (name, description, schema = { type: "string" }) => ({ name, in: "query", required: false, schema, description });
+const res = (description) => ({ description });
+/** Default security: a workspace API key. `/admin/v1` paths override this. */
+const workspaceAuth = [{ workspaceKey: [] }];
+const adminAuth = [{ adminToken: [] }];
+const limitParam = queryParam("limit", "Page size; clamped server-side.", {
+    type: "integer",
+    minimum: 1,
+});
+const channelParam = queryParam("channel", "Filter by session channel.");
+function buildPaths() {
+    return {
+        "/v1/me": {
+            get: {
+                summary: "Identity probe — the workspace the caller's key resolves to.",
+                responses: { "200": res("workspace id"), "401": res("unauthorized") },
+            },
+        },
+        "/v1/sessions": {
+            post: {
+                summary: "Create a session.",
+                requestBody: jsonBody("SessionInit"),
+                responses: {
+                    "200": res("created session id"),
+                    "400": res("invalid body"),
+                    "401": res("unauthorized"),
+                },
+            },
+            get: {
+                summary: "List recent sessions plus their persons map.",
+                parameters: [limitParam, channelParam],
+                responses: { "200": res("session list envelope"), "401": res("unauthorized") },
+            },
+        },
+        "/v1/sessions/{id}": {
+            get: {
+                summary: "Fetch one session plus its persons map.",
+                parameters: [pathParam("id", "Session id.")],
+                responses: {
+                    "200": res("session envelope"),
+                    "404": res("session not found"),
+                    "401": res("unauthorized"),
+                },
+            },
+        },
+        "/v1/sessions/{id}/events": {
+            post: {
+                summary: "Append events to a session.",
+                parameters: [pathParam("id", "Session id.")],
+                requestBody: jsonBody("EventBatch"),
+                responses: {
+                    "204": res("appended"),
+                    "400": res("invalid body"),
+                    "404": res("session not found"),
+                    "401": res("unauthorized"),
+                },
+            },
+        },
+        "/v1/search": {
+            post: {
+                summary: "Score the workspace corpus against a query session.",
+                requestBody: jsonBody("SearchRequest"),
+                responses: {
+                    "200": res("scored results plus persons map"),
+                    "400": res("invalid body"),
+                    "404": res("query session not found"),
+                    "401": res("unauthorized"),
+                },
+            },
+        },
+        "/v1/persons": {
+            post: {
+                summary: "Create a person (server allocates the id).",
+                requestBody: jsonBody("PersonCreate"),
+                responses: {
+                    "201": res("created person"),
+                    "400": res("invalid body"),
+                    "401": res("unauthorized"),
+                },
+            },
+            get: {
+                summary: "List or free-text search persons.",
+                parameters: [limitParam, queryParam("q", "Free-text query over id + display_name.")],
+                responses: { "200": res("person list"), "401": res("unauthorized") },
+            },
+        },
+        "/v1/persons/{id}": {
+            put: {
+                summary: "Upsert a person at a caller-supplied id.",
+                parameters: [pathParam("id", "Person id.")],
+                requestBody: jsonBody("PersonCreate"),
+                responses: {
+                    "200": res("upserted person"),
+                    "400": res("invalid body"),
+                    "401": res("unauthorized"),
+                },
+            },
+            patch: {
+                summary: "Patch a person's profile fields.",
+                parameters: [pathParam("id", "Person id.")],
+                requestBody: jsonBody("PersonUpdate"),
+                responses: {
+                    "200": res("updated person"),
+                    "400": res("invalid body"),
+                    "404": res("person not found"),
+                    "401": res("unauthorized"),
+                },
+            },
+            get: {
+                summary: "Fetch one person.",
+                parameters: [pathParam("id", "Person id.")],
+                responses: {
+                    "200": res("person"),
+                    "404": res("person not found"),
+                    "401": res("unauthorized"),
+                },
+            },
+        },
+        "/v1/persons/{id}/sessions": {
+            get: {
+                summary: "Sessions this person participates in (or can view).",
+                parameters: [
+                    pathParam("id", "Person id."),
+                    limitParam,
+                    channelParam,
+                    queryParam("scope", "`participant` (default) or `viewable`.", {
+                        type: "string",
+                        enum: ["participant", "viewable"],
+                    }),
+                ],
+                responses: { "200": res("session list envelope"), "401": res("unauthorized") },
+            },
+        },
+        "/admin/v1/workspaces": {
+            post: {
+                summary: "Create a workspace (and, by default, an initial key).",
+                security: adminAuth,
+                requestBody: jsonBody("CreateWorkspace"),
+                responses: {
+                    "200": res("workspace, plus key unless issueKey=false"),
+                    "400": res("invalid body or workspace id"),
+                    "401": res("unauthorized"),
+                },
+            },
+            get: {
+                summary: "List all workspaces.",
+                security: adminAuth,
+                responses: { "200": res("workspace list"), "401": res("unauthorized") },
+            },
+        },
+        "/admin/v1/workspaces/{id}": {
+            get: {
+                summary: "Fetch one workspace.",
+                security: adminAuth,
+                parameters: [pathParam("id", "Workspace id.")],
+                responses: {
+                    "200": res("workspace"),
+                    "404": res("workspace not found"),
+                    "401": res("unauthorized"),
+                },
+            },
+            delete: {
+                summary: "Delete a workspace (cascades to keys, sessions, events).",
+                security: adminAuth,
+                parameters: [pathParam("id", "Workspace id.")],
+                responses: {
+                    "204": res("deleted"),
+                    "404": res("workspace not found"),
+                    "401": res("unauthorized"),
+                },
+            },
+        },
+        "/admin/v1/workspaces/{id}/keys": {
+            post: {
+                summary: "Issue a new API key for a workspace.",
+                security: adminAuth,
+                parameters: [pathParam("id", "Workspace id.")],
+                requestBody: jsonBody("IssueKey", false),
+                responses: {
+                    "200": res("issued key (raw key returned once)"),
+                    "400": res("invalid body"),
+                    "404": res("workspace not found"),
+                    "401": res("unauthorized"),
+                },
+            },
+            get: {
+                summary: "List a workspace's API keys (hashes only).",
+                security: adminAuth,
+                parameters: [pathParam("id", "Workspace id.")],
+                responses: {
+                    "200": res("key list"),
+                    "404": res("workspace not found"),
+                    "401": res("unauthorized"),
+                },
+            },
+        },
+        "/admin/v1/workspaces/{id}/keys/{keyId}": {
+            delete: {
+                summary: "Revoke an API key.",
+                security: adminAuth,
+                parameters: [
+                    pathParam("id", "Workspace id."),
+                    pathParam("keyId", "Key id."),
+                ],
+                responses: {
+                    "204": res("revoked (idempotent)"),
+                    "404": res("key not found"),
+                    "401": res("unauthorized"),
+                },
+            },
+        },
+    };
+}
+/**
+ * Build the OpenAPI 3.1 document. Pure and deterministic — `gen-openapi.ts`
+ * writes its output to `openapi.json`, and `openapi.test.ts` asserts the
+ * committed file still matches.
+ */
+export function buildOpenApiDocument() {
+    return {
+        openapi: "3.1.0",
+        info: {
+            title: "engram-server",
+            version: "1.0",
+            description: "Cross-session retrieval for AI agents. Request bodies are derived " +
+                "from the server's Zod schemas (src/schemas.ts); response schemas " +
+                "are described by status only for now and are a planned follow-up.",
+        },
+        servers: [
+            { url: "/", description: "relative to the deployed engram-server" },
+        ],
+        security: workspaceAuth,
+        components: {
+            securitySchemes: {
+                workspaceKey: {
+                    type: "http",
+                    scheme: "bearer",
+                    description: "Workspace API key (`eng_…`). Also accepted as the `X-Api-Key` header.",
+                },
+                adminToken: {
+                    type: "apiKey",
+                    in: "header",
+                    name: "X-Admin-Token",
+                    description: "Platform admin token for `/admin/v1/*`. Also accepted as `Authorization: Bearer`.",
+                },
+            },
+            schemas: {
+                SessionInit: toComponent(sessionInitSchema),
+                // `EventBatch` inlines the per-event shape. A standalone `SessionEvent`
+                // component (cross-`$ref`'d) is a planned follow-up alongside response
+                // schemas — zod's `toJSONSchema` inlines by default.
+                EventBatch: toComponent(eventBatchSchema),
+                PersonCreate: toComponent(personCreateSchema),
+                PersonUpdate: toComponent(personUpdateSchema),
+                SearchRequest: toComponent(searchRequestSchema),
+                CreateWorkspace: toComponent(createWorkspaceSchema),
+                IssueKey: toComponent(issueKeySchema),
+            },
+        },
+        paths: buildPaths(),
+    };
+}

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>;