@hexis-ai/engram-server 0.1.2 → 0.1.5

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import type { StorageAdapter } from "./storage";
+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.
@@ -25,10 +26,16 @@ export interface CreateServerOptions {
      */
     defaultListLimit?: number;
     maxListLimit?: number;
+    /**
+     * When set, mounts the admin sub-router at `/admin/v1`. Admin auth is
+     * a separate platform token, never crossed with workspace API keys.
+     */
+    admin?: AdminOptions;
 }
 interface Env {
     Variables: {
         ctx: WorkspaceContext;
+        request_id: string;
     };
 }
 export declare function createServer(opts: CreateServerOptions): Hono<Env>;

package/dist/server.js

@@ -1,12 +1,42 @@
 import { Hono } from "hono";
 import { buildIndex, search, } from "@hexis-ai/engram-core";
+import { log, newRequestId } from "./logger";
+import { createAdminRouter } from "./admin";
 export function createServer(opts) {
     const newId = opts.newSessionId ?? (() => crypto.randomUUID());
     const defaultLimit = opts.defaultListLimit ?? 100;
     const maxLimit = opts.maxListLimit ?? 500;
     const app = new Hono();
-    // Unauthenticated service info. Useful for browser sanity checks and
-    // health probes (Cloud Run, k8s, uptime monitors).
+    // Request id + access log middleware. Runs for every route.
+    app.use("*", async (c, next) => {
+        const rid = c.req.header("x-request-id") ?? newRequestId();
+        c.set("request_id", rid);
+        c.header("x-request-id", rid);
+        const start = Date.now();
+        let status = 500;
+        try {
+            await next();
+            status = c.res.status;
+        }
+        finally {
+            log.info("request", {
+                request_id: rid,
+                method: c.req.method,
+                path: c.req.path,
+                status,
+                duration_ms: Date.now() - start,
+            });
+        }
+    });
+    app.onError((err, c) => {
+        log.error("unhandled", {
+            request_id: c.var.request_id,
+            path: c.req.path,
+            error: err instanceof Error ? err.message : String(err),
+            stack: err instanceof Error ? err.stack : undefined,
+        });
+        return c.json({ error: "internal_error" }, 500);
+    });
     app.get("/", (c) => c.json({
         service: "@hexis-ai/engram-server",
         ok: true,
@@ -15,20 +45,30 @@ export function createServer(opts) {
             sessionById: "GET /v1/sessions/:id",
             events: "POST /v1/sessions/:id/events",
             search: "POST /v1/search",
+            persons: "POST/GET /v1/persons",
+            personById: "GET/PUT/PATCH /v1/persons/:id",
+            personSessions: "GET /v1/persons/:id/sessions",
         },
     }));
     app.get("/healthz", (c) => c.json({ ok: true }));
+    if (opts.admin) {
+        app.route("/admin/v1", createAdminRouter(opts.admin));
+    }
     app.use("/v1/*", async (c, next) => {
-        const auth = c.req.header("authorization");
-        const m = auth?.match(/^Bearer\s+(.+)$/i);
-        if (!m)
+        const apiKey = c.req.header("x-api-key") ??
+            c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
+        if (!apiKey)
             return c.json({ error: "unauthorized" }, 401);
-        const ctx = await opts.auth(m[1]);
+        const ctx = await opts.auth(apiKey);
         if (!ctx)
             return c.json({ error: "unauthorized" }, 401);
         c.set("ctx", ctx);
         await next();
     });
+    // 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)
@@ -61,13 +101,15 @@ export function createServer(opts) {
         const s = await c.var.ctx.storage.getSession(id);
         if (!s)
             return c.json({ error: "session_not_found" }, 404);
-        return c.json(s);
+        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 });
-        return c.json(sessions);
+        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));
@@ -91,7 +133,61 @@ export function createServer(opts) {
             ...opts,
             queryParticipants,
         });
-        return c.json({ results });
+        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 });
     });
     return app;
 }
@@ -104,3 +200,25 @@ function clampLimit(c, def, max) {
         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/dist/storage.d.ts

@@ -1,12 +1,15 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import type { PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
 /**
  * Storage adapter interface. Each implementation owns persistence for
- * a single workspace's sessions. Multi-tenancy is the host's concern: the
- * server keys adapters by workspace id (derived from API key).
+ * a single workspace's sessions and persons. Multi-tenancy is the host's
+ * concern: the server keys adapters by workspace id (derived from API key).
  */
 export interface StorageAdapter {
-    /** Create a session row. Returns the assigned id. */
+    /**
+     * Create a session row. Stores participants + viewable_by as the host
+     * passed them (person ids; identity resolution is upstream).
+     */
     createSession(init: SessionInit & {
         id: string;
         createdAt: string;
@@ -20,6 +23,35 @@ export interface StorageAdapter {
         limit: number;
         channel?: string;
     }): Promise<Session[]>;
+    /**
+     * Create a person with a freshly allocated id. The host (e.g. monet)
+     * then stores this id locally.
+     */
+    createPerson(input: PersonCreate): Promise<PersonInfo>;
+    /**
+     * Upsert at an explicit id. Used by hosts that already have a stable id
+     * (backfill, fallback after an outage).
+     */
+    upsertPerson(id: string, input: PersonCreate): Promise<PersonInfo>;
+    /** Update profile fields. Returns the updated record. */
+    updatePerson(id: string, patch: PersonUpdate): Promise<PersonInfo | null>;
+    getPerson(id: string): Promise<PersonInfo | null>;
+    /** Batch fetch — used by response envelopes to inline `persons` maps. */
+    getPersons(ids: string[]): Promise<PersonInfo[]>;
+    /** List or search persons in this workspace. */
+    listPersons(opts: {
+        limit: number;
+        q?: string;
+    }): Promise<PersonInfo[]>;
+    /**
+     * Sessions where `personId` appears in `participants` (or `viewable_by`
+     * when `scope === "viewable"`). Ordered newest-first.
+     */
+    sessionsForPerson(personId: string, opts: {
+        limit: number;
+        channel?: string;
+        scope?: "participant" | "viewable";
+    }): Promise<Session[]>;
 }
 /**
  * Pure fold of an event log into the parts a Session needs. Used by adapters
@@ -30,6 +62,7 @@ export interface SessionRow {
     title?: string;
     channel?: string;
     participants: string[];
+    viewable_by: string[];
     createdAt: string;
 }
 export declare function foldEvents(row: SessionRow, events: SessionEvent[], now: Date): Session;

package/dist/storage.js

@@ -8,12 +8,14 @@ export function foldEvents(row, events, now) {
             steps.push({ tool: ev.tool, resources: [...ev.resources] });
         }
         else if (ev.type === "participant") {
-            participants.add(ev.identityRef);
+            participants.add(ev.personId);
         }
         else if (ev.type === "title") {
             title = ev.title;
         }
     }
+    // viewable_by always includes participants (the set is canonical here).
+    const viewableSet = new Set([...row.viewable_by, ...participants]);
     const created = new Date(row.createdAt).getTime();
     const daysAgo = Math.max(0, (now.getTime() - created) / 86_400_000);
     return {
@@ -22,5 +24,6 @@ export function foldEvents(row, events, now) {
         steps,
         daysAgo,
         ...(participants.size > 0 ? { participants: [...participants] } : {}),
+        ...(viewableSet.size > 0 ? { viewable_by: [...viewableSet] } : {}),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-server",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Engram server: ingest agent session events, persist via a pluggable adapter, expose search.",
   "keywords": ["engram", "agents", "search", "hono", "postgres", "server"],
   "homepage": "https://github.com/hexis-ltd/engram#readme",
@@ -41,8 +41,8 @@
     "dev": "bun --hot src/dev.ts"
   },
   "dependencies": {
-    "@hexis-ai/engram-core": "^0.1.2",
-    "@hexis-ai/engram-sdk": "^0.1.2",
+    "@hexis-ai/engram-core": "^0.1.5",
+    "@hexis-ai/engram-sdk": "^0.1.5",
     "hono": "^4.6.0"
   },
   "peerDependencies": {