@hexis-ai/engram-server 0.1.4 → 0.1.6

package/dist/migrations/index.d.ts

@@ -0,0 +1,12 @@
+export interface Migration {
+    name: string;
+    sql: string;
+}
+/**
+ * Schema migrations, applied in array order. Add a new file under
+ * `migrations/NNNN-<slug>.ts` exporting `name` and `sql`, then append it
+ * here. Each migration's SQL must be idempotent (CREATE TABLE IF NOT
+ * EXISTS, ADD COLUMN IF NOT EXISTS, etc.) so a first apply on a DB that
+ * predates the migrator is a no-op.
+ */
+export declare const MIGRATIONS: Migration[];

package/dist/migrations/index.js

@@ -0,0 +1,9 @@
+import * as m0001 from "./0001-baseline";
+/**
+ * Schema migrations, applied in array order. Add a new file under
+ * `migrations/NNNN-<slug>.ts` exporting `name` and `sql`, then append it
+ * here. Each migration's SQL must be idempotent (CREATE TABLE IF NOT
+ * EXISTS, ADD COLUMN IF NOT EXISTS, etc.) so a first apply on a DB that
+ * predates the migrator is a no-op.
+ */
+export const MIGRATIONS = [{ name: m0001.name, sql: m0001.sql }];

package/dist/migrator.d.ts

@@ -0,0 +1,17 @@
+import type { SqlClient } from "./adapters/postgres";
+import { type Migration } from "./migrations";
+/**
+ * Apply pending schema migrations in order. Records applied migrations in
+ * `engram_schema_migrations` so subsequent boots skip them.
+ *
+ * Each migration's SQL must itself be idempotent (IF NOT EXISTS, etc.) —
+ * the tracking table protects against unnecessary re-runs but a partial
+ * failure between executing the SQL and inserting the tracking row would
+ * cause a replay on next boot, and we want that replay to be a no-op.
+ *
+ * Safe to call concurrently from multiple instances: the INSERT uses ON
+ * CONFLICT and the migration SQL itself is idempotent, so two boots
+ * applying the same migration in parallel just race to a consistent end
+ * state.
+ */
+export declare function runMigrations(sql: SqlClient, migrations?: readonly Migration[]): Promise<void>;

package/dist/migrator.js

@@ -0,0 +1,37 @@
+import { MIGRATIONS } from "./migrations";
+/**
+ * Apply pending schema migrations in order. Records applied migrations in
+ * `engram_schema_migrations` so subsequent boots skip them.
+ *
+ * Each migration's SQL must itself be idempotent (IF NOT EXISTS, etc.) —
+ * the tracking table protects against unnecessary re-runs but a partial
+ * failure between executing the SQL and inserting the tracking row would
+ * cause a replay on next boot, and we want that replay to be a no-op.
+ *
+ * Safe to call concurrently from multiple instances: the INSERT uses ON
+ * CONFLICT and the migration SQL itself is idempotent, so two boots
+ * applying the same migration in parallel just race to a consistent end
+ * state.
+ */
+export async function runMigrations(sql, migrations = MIGRATIONS) {
+    await sql.unsafe(`
+    CREATE TABLE IF NOT EXISTS engram_schema_migrations (
+      name       TEXT PRIMARY KEY,
+      applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+    )
+  `);
+    const appliedRows = await sql `
+    SELECT name FROM engram_schema_migrations
+  `;
+    const applied = new Set(appliedRows.map((r) => r.name));
+    for (const m of migrations) {
+        if (applied.has(m.name))
+            continue;
+        await sql.unsafe(m.sql);
+        await sql `
+      INSERT INTO engram_schema_migrations (name)
+      VALUES (${m.name})
+      ON CONFLICT (name) DO NOTHING
+    `;
+    }
+}

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,6 +26,11 @@ 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: {

package/dist/server.js

@@ -1,6 +1,7 @@
 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;
@@ -36,8 +37,6 @@ export function createServer(opts) {
         });
         return c.json({ error: "internal_error" }, 500);
     });
-    // Unauthenticated service info. Useful for browser sanity checks and
-    // health probes (Cloud Run, k8s, uptime monitors).
     app.get("/", (c) => c.json({
         service: "@hexis-ai/engram-server",
         ok: true,
@@ -46,14 +45,16 @@ 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) => {
-        // Prefer X-Api-Key so callers can use the Authorization header for
-        // platform-level auth (Cloud Run IAM with an ID token, for example)
-        // without collision. Falls back to Authorization: Bearer <key> for
-        // existing clients.
         const apiKey = c.req.header("x-api-key") ??
             c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
         if (!apiKey)
@@ -64,6 +65,10 @@ export function createServer(opts) {
         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)
@@ -96,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));
@@ -126,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;
 }
@@ -139,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,8 +1,15 @@
 {
   "name": "@hexis-ai/engram-server",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Engram server: ingest agent session events, persist via a pluggable adapter, expose search.",
-  "keywords": ["engram", "agents", "search", "hono", "postgres", "server"],
+  "keywords": [
+    "engram",
+    "agents",
+    "search",
+    "hono",
+    "postgres",
+    "server"
+  ],
   "homepage": "https://github.com/hexis-ltd/engram#readme",
   "repository": {
     "type": "git",
@@ -41,15 +48,17 @@
     "dev": "bun --hot src/dev.ts"
   },
   "dependencies": {
-    "@hexis-ai/engram-core": "^0.1.4",
-    "@hexis-ai/engram-sdk": "^0.1.4",
+    "@hexis-ai/engram-core": "^0.1.5",
+    "@hexis-ai/engram-sdk": "^0.1.5",
     "hono": "^4.6.0"
   },
   "peerDependencies": {
     "postgres": "^3.4.0"
   },
   "peerDependenciesMeta": {
-    "postgres": { "optional": true }
+    "postgres": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "postgres": "^3.4.0"