@hexis-ai/engram-server 0.8.0 → 0.10.0

package/dist/adapters/memory.d.ts

@@ -29,6 +29,7 @@ export declare class InMemoryAdapter implements StorageAdapter {
     listSessions(opts: {
         limit: number;
         channel?: string;
+        status?: "active" | "idle" | "completed";
     }): Promise<Session[]>;
     sessionsForPerson(personId: string, opts: {
         limit: number;
@@ -48,6 +49,7 @@ export declare class InMemoryAdapter implements StorageAdapter {
         name: string;
     } & AliasUpsert): Promise<AliasInfo | null>;
     listAliases(personId: string): Promise<AliasInfo[]>;
+    findAliasesByName(name: string): Promise<AliasInfo[]>;
     upsertIdentity(ref: string, input: IdentityUpsert): Promise<IdentityInfo | null>;
     getIdentityByRef(ref: string): Promise<IdentityInfo | null>;
     listIdentitiesByPerson(personId: string): Promise<IdentityInfo[]>;

package/dist/adapters/memory.js

@@ -37,6 +37,7 @@ export class InMemoryAdapter {
                 participants,
                 viewable_by,
                 createdAt: init.createdAt,
+                updatedAt: init.createdAt,
                 // status defaults to 'active' to match the Postgres column default.
                 status: init.status ?? "active",
                 ...(init.summary != null ? { summary: init.summary } : {}),
@@ -69,6 +70,13 @@ export class InMemoryAdapter {
                 };
             }
         }
+        if (events.length > 0) {
+            const latestAt = events[events.length - 1].at;
+            // Bump updated_at to the latest event's `at` (monotonic).
+            if (latestAt > s.row.updatedAt) {
+                s.row = { ...s.row, updatedAt: latestAt };
+            }
+        }
     }
     async getSession(sessionId) {
         const s = this.sessions.get(sessionId);
@@ -123,6 +131,7 @@ export class InMemoryAdapter {
             else
                 next.trigger_event_id = patch.trigger_event_id;
         }
+        next.updatedAt = new Date().toISOString();
         s.row = next;
         return foldEvents(s.row, [...s.events.values()], new Date());
     }
@@ -138,12 +147,14 @@ export class InMemoryAdapter {
         for (const stored of this.sessions.values()) {
             if (opts.channel && stored.row.channel !== opts.channel)
                 continue;
+            if (opts.status && stored.row.status !== opts.status)
+                continue;
             all.push({
                 s: foldEvents(stored.row, [...stored.events.values()], now),
-                createdAt: stored.row.createdAt,
+                updatedAt: stored.row.updatedAt,
             });
         }
-        all.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        all.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
         return all.slice(0, opts.limit).map((x) => x.s);
     }
     async sessionsForPerson(personId, opts) {
@@ -172,15 +183,17 @@ export class InMemoryAdapter {
     async upsertPerson(id, input) {
         const now = new Date().toISOString();
         const existing = this.persons.get(id);
+        // `PersonCreate` has no notion of "clear" — that's `updatePerson`'s
+        // job. Missing / null in input means "keep what's there", matching
+        // the Postgres adapter's COALESCE-on-conflict.
         const next = {
             id,
-            // `PersonCreate` has no notion of "clear the name" — that is
-            // `updatePerson`'s job. A missing value (and, defensively, an
-            // explicit null that bypasses the schema) means "keep what's
-            // there", matching the Postgres adapter's `COALESCE(EXCLUDED.…)`.
             display_name: input.display_name != null
                 ? input.display_name
                 : existing?.display_name ?? null,
+            role: input.role != null ? input.role : existing?.role ?? null,
+            team: input.team != null ? input.team : existing?.team ?? null,
+            source: input.source ?? existing?.source ?? "auto",
             created_at: existing?.created_at ?? now,
             updated_at: now,
         };
@@ -192,9 +205,13 @@ export class InMemoryAdapter {
         if (!existing)
             return null;
         const now = new Date().toISOString();
+        // undefined = no-op, null = clear (per the SDK contract).
         const next = {
             ...existing,
             display_name: patch.display_name !== undefined ? patch.display_name : existing.display_name,
+            role: patch.role !== undefined ? patch.role : existing.role ?? null,
+            team: patch.team !== undefined ? patch.team : existing.team ?? null,
+            source: patch.source !== undefined ? patch.source : existing.source ?? "auto",
             updated_at: now,
         };
         this.persons.set(id, next);
@@ -215,9 +232,28 @@ export class InMemoryAdapter {
     async listPersons(opts) {
         const q = opts.q?.trim().toLowerCase() ?? "";
         const all = [...this.persons.values()];
+        // Search spans person fields + active identities (matching the
+        // Postgres impl). Slow O(n*m) here is fine — in-memory is for
+        // tests / dev / small single-node deploys.
         const matched = q
-            ? all.filter((p) => p.id.toLowerCase().includes(q) ||
-                (p.display_name?.toLowerCase().includes(q) ?? false))
+            ? all.filter((p) => {
+                if (p.id.toLowerCase().includes(q))
+                    return true;
+                if (p.display_name?.toLowerCase().includes(q))
+                    return true;
+                if (p.role?.toLowerCase().includes(q))
+                    return true;
+                if (p.team?.toLowerCase().includes(q))
+                    return true;
+                for (const i of this.identities.values()) {
+                    if (i.person_id === p.id &&
+                        i.unlinked_at == null &&
+                        i.display_name?.toLowerCase().includes(q)) {
+                        return true;
+                    }
+                }
+                return false;
+            })
             : all;
         matched.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
         return matched.slice(0, opts.limit);
@@ -251,12 +287,22 @@ export class InMemoryAdapter {
         matches.sort((a, b) => b.last_used.localeCompare(a.last_used));
         return matches;
     }
+    async findAliasesByName(name) {
+        const lower = name.toLowerCase();
+        const matches = [...this.aliases.values()].filter((a) => a.name.toLowerCase() === lower);
+        matches.sort((a, b) => b.last_used.localeCompare(a.last_used));
+        return matches;
+    }
     // --- Identities ---------------------------------------------------
     async upsertIdentity(ref, input) {
         if (!this.persons.has(input.person_id))
             return null;
         const now = new Date().toISOString();
         const existing = this.identities.get(ref);
+        // COALESCE-on-conflict for the soft-overlap fields; ref-level
+        // mapping (person_id, service, external_id, linked_at) always
+        // takes the latest input. unlinked_at uses undefined=no-change
+        // semantics so callers can re-link without explicitly clearing.
         const next = {
             ref,
             person_id: input.person_id,
@@ -266,11 +312,12 @@ export class InMemoryAdapter {
                 ? input.display_name
                 : existing?.display_name ?? null,
             source: input.source !== undefined ? input.source : existing?.source ?? null,
-            is_primary: input.is_primary !== undefined
-                ? input.is_primary
-                : existing?.is_primary ?? null,
+            is_primary: input.is_primary ?? existing?.is_primary ?? false,
             picture: input.picture !== undefined ? input.picture : existing?.picture ?? null,
             linked_at: input.linked_at,
+            unlinked_at: input.unlinked_at !== undefined
+                ? input.unlinked_at
+                : existing?.unlinked_at ?? null,
             created_at: existing?.created_at ?? now,
             updated_at: now,
         };

package/dist/adapters/postgres.d.ts

@@ -42,6 +42,7 @@ export declare class PostgresAdapter implements StorageAdapter {
     listSessions(opts: {
         limit: number;
         channel?: string;
+        status?: "active" | "idle" | "completed";
     }): Promise<Session[]>;
     sessionsForPerson(personId: string, opts: {
         limit: number;
@@ -61,6 +62,7 @@ export declare class PostgresAdapter implements StorageAdapter {
         name: string;
     } & AliasUpsert): Promise<AliasInfo | null>;
     listAliases(personId: string): Promise<AliasInfo[]>;
+    findAliasesByName(name: string): Promise<AliasInfo[]>;
     upsertIdentity(ref: string, input: IdentityUpsert): Promise<IdentityInfo | null>;
     getIdentityByRef(ref: string): Promise<IdentityInfo | null>;
     listIdentitiesByPerson(personId: string): Promise<IdentityInfo[]>;

package/dist/adapters/postgres.js

@@ -43,7 +43,7 @@ export class PostgresAdapter {
         await this.sql `
       INSERT INTO engram_sessions (
         workspace_id, id, title, channel, participants, viewable_by,
-        created_at, status, summary, model,
+        created_at, updated_at, status, summary, model,
         trigger_conversation_id, trigger_event_id
       )
       VALUES (
@@ -54,6 +54,7 @@ export class PostgresAdapter {
         ${participants},
         ${viewableBy},
         ${init.createdAt},
+        ${init.createdAt},
         ${init.status ?? "active"},
         ${init.summary ?? null},
         ${init.model ?? null},
@@ -95,11 +96,20 @@ export class PostgresAdapter {
         `;
             }
         }
+        // Bump updated_at once per batch so list-by-recent-activity stays
+        // accurate. Using the latest event's `at` (not now()) keeps the
+        // semantics deterministic for back-dated batches.
+        const latest = events[events.length - 1];
+        await this.sql `
+      UPDATE engram_sessions
+      SET updated_at = GREATEST(updated_at, ${latest.at}::timestamptz)
+      WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
+    `;
     }
     async getSession(sessionId) {
         const rows = await this.sql `
       SELECT id, title, channel, participants, viewable_by, created_at,
-             status, summary, model,
+             updated_at, status, summary, model,
              trigger_conversation_id, trigger_event_id
       FROM engram_sessions
       WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
@@ -137,7 +147,8 @@ export class PostgresAdapter {
           ELSE trigger_conversation_id END,
         trigger_event_id = CASE WHEN ${teIdProvided}
           THEN ${patch.trigger_event_id ?? null}
-          ELSE trigger_event_id END
+          ELSE trigger_event_id END,
+        updated_at = now()
       WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
       RETURNING id
     `;
@@ -162,11 +173,13 @@ export class PostgresAdapter {
     }
     async listSessions(opts) {
         const channelFilter = opts.channel ?? null;
+        const statusFilter = opts.status ?? null;
         const rows = await this.sql `
       SELECT id FROM engram_sessions
       WHERE workspace_id = ${this.workspaceId}
         AND (${channelFilter}::text IS NULL OR channel = ${channelFilter}::text)
-      ORDER BY created_at DESC
+        AND (${statusFilter}::text IS NULL OR status  = ${statusFilter}::text)
+      ORDER BY updated_at DESC
       LIMIT ${opts.limit}
     `;
         const sessions = await Promise.all(rows.map((r) => this.getSession(r.id)));
@@ -204,24 +217,41 @@ export class PostgresAdapter {
     }
     async upsertPerson(id, input) {
         const rows = await this.sql `
-      INSERT INTO engram_persons (workspace_id, id, display_name)
-      VALUES (${this.workspaceId}, ${id}, ${input.display_name ?? null})
+      INSERT INTO engram_persons (workspace_id, id, display_name, role, team, source)
+      VALUES (
+        ${this.workspaceId}, ${id},
+        ${input.display_name ?? null},
+        ${input.role ?? null},
+        ${input.team ?? null},
+        ${input.source ?? "auto"}
+      )
       ON CONFLICT (workspace_id, id) DO UPDATE SET
+        -- COALESCE-on-conflict so partial-info upserts don't clobber
+        -- richer profile data set earlier.
         display_name = COALESCE(EXCLUDED.display_name, engram_persons.display_name),
+        role         = COALESCE(EXCLUDED.role,         engram_persons.role),
+        team         = COALESCE(EXCLUDED.team,         engram_persons.team),
+        source       = COALESCE(EXCLUDED.source,       engram_persons.source),
         updated_at   = now()
-      RETURNING id, display_name, created_at, updated_at
+      RETURNING id, display_name, role, team, source, created_at, updated_at
     `;
         return toPersonInfo(rows[0]);
     }
     async updatePerson(id, patch) {
         // Treat `null` as an explicit clear; `undefined` as no-op.
         const nameProvided = patch.display_name !== undefined;
+        const roleProvided = patch.role !== undefined;
+        const teamProvided = patch.team !== undefined;
+        const sourceProvided = patch.source !== undefined;
         const rows = await this.sql `
-      UPDATE engram_persons
-      SET display_name = CASE WHEN ${nameProvided} THEN ${patch.display_name ?? null} ELSE display_name END,
-          updated_at   = now()
+      UPDATE engram_persons SET
+        display_name = CASE WHEN ${nameProvided}   THEN ${patch.display_name ?? null} ELSE display_name END,
+        role         = CASE WHEN ${roleProvided}   THEN ${patch.role ?? null}         ELSE role         END,
+        team         = CASE WHEN ${teamProvided}   THEN ${patch.team ?? null}         ELSE team         END,
+        source       = CASE WHEN ${sourceProvided} THEN ${patch.source ?? "auto"}     ELSE source       END,
+        updated_at   = now()
       WHERE workspace_id = ${this.workspaceId} AND id = ${id}
-      RETURNING id, display_name, created_at, updated_at
+      RETURNING id, display_name, role, team, source, created_at, updated_at
     `;
         if (rows.length === 0)
             return null;
@@ -229,7 +259,7 @@ export class PostgresAdapter {
     }
     async getPerson(id) {
         const rows = await this.sql `
-      SELECT id, display_name, created_at, updated_at
+      SELECT id, display_name, role, team, source, created_at, updated_at
       FROM engram_persons
       WHERE workspace_id = ${this.workspaceId} AND id = ${id}
       LIMIT 1
@@ -242,7 +272,7 @@ export class PostgresAdapter {
         if (ids.length === 0)
             return [];
         const rows = await this.sql `
-      SELECT id, display_name, created_at, updated_at
+      SELECT id, display_name, role, team, source, created_at, updated_at
       FROM engram_persons
       WHERE workspace_id = ${this.workspaceId}
         AND id = ANY(${ids}::text[])
@@ -253,18 +283,32 @@ export class PostgresAdapter {
         const q = opts.q?.trim() ?? "";
         if (q) {
             const pattern = `%${q.toLowerCase()}%`;
+            // Free-text search spans the person row + active identities so
+            // a query like "design" finds people by role *or* by external
+            // identity display_name (e.g. their Slack profile name).
             const rows = await this.sql `
-        SELECT id, display_name, created_at, updated_at
-        FROM engram_persons
-        WHERE workspace_id = ${this.workspaceId}
-          AND (lower(id) LIKE ${pattern} OR lower(coalesce(display_name, '')) LIKE ${pattern})
-        ORDER BY updated_at DESC
+        SELECT DISTINCT p.id, p.display_name, p.role, p.team, p.source,
+                        p.created_at, p.updated_at
+        FROM engram_persons p
+        LEFT JOIN engram_identities i
+          ON i.workspace_id = p.workspace_id
+         AND i.person_id    = p.id
+         AND i.unlinked_at  IS NULL
+        WHERE p.workspace_id = ${this.workspaceId}
+          AND (
+                lower(p.id)                          LIKE ${pattern}
+             OR lower(coalesce(p.display_name, '')) LIKE ${pattern}
+             OR lower(coalesce(p.role, ''))         LIKE ${pattern}
+             OR lower(coalesce(p.team, ''))         LIKE ${pattern}
+             OR lower(coalesce(i.display_name, '')) LIKE ${pattern}
+              )
+        ORDER BY p.updated_at DESC
         LIMIT ${opts.limit}
       `;
             return rows.map(toPersonInfo);
         }
         const rows = await this.sql `
-      SELECT id, display_name, created_at, updated_at
+      SELECT id, display_name, role, team, source, created_at, updated_at
       FROM engram_persons
       WHERE workspace_id = ${this.workspaceId}
       ORDER BY updated_at DESC
@@ -323,6 +367,19 @@ export class PostgresAdapter {
     `;
         return rows.map(toAliasInfo);
     }
+    async findAliasesByName(name) {
+        // The `name_lower` column is a STORED generated lower(name) backed
+        // by `idx_engram_aliases_name_lower (workspace_id, name_lower)`, so
+        // this lookup is index-only regardless of casing in the input.
+        const rows = await this.sql `
+      SELECT person_id, name, caller, usage_count, last_used, created_at, updated_at
+      FROM engram_aliases
+      WHERE workspace_id = ${this.workspaceId}
+        AND name_lower   = ${name.toLowerCase()}
+      ORDER BY last_used DESC
+    `;
+        return rows.map(toAliasInfo);
+    }
     // --- Identities ---------------------------------------------------
     async upsertIdentity(ref, input) {
         // Pre-check rather than rely on the FK so unknown persons return
@@ -334,17 +391,21 @@ export class PostgresAdapter {
     `;
         if (personExists.length === 0)
             return null;
+        // unlinked_at semantics: undefined = leave alone, null = clear,
+        // value = set. matches the patch contract for the other fields.
+        const unlinkedProvided = input.unlinked_at !== undefined;
         const rows = await this.sql `
       INSERT INTO engram_identities (
         workspace_id, ref, person_id, service, external_id,
-        display_name, source, is_primary, picture, linked_at
+        display_name, source, is_primary, picture, linked_at, unlinked_at
       )
       VALUES (
         ${this.workspaceId}, ${ref}, ${input.person_id},
         ${input.service}, ${input.external_id},
         ${input.display_name ?? null}, ${input.source ?? null},
-        ${input.is_primary ?? null}, ${input.picture ?? null},
-        ${input.linked_at}
+        ${input.is_primary ?? false}, ${input.picture ?? null},
+        ${input.linked_at},
+        ${input.unlinked_at ?? null}
       )
       ON CONFLICT (workspace_id, ref) DO UPDATE SET
         person_id    = EXCLUDED.person_id,
@@ -352,19 +413,24 @@ export class PostgresAdapter {
         external_id  = EXCLUDED.external_id,
         display_name = COALESCE(EXCLUDED.display_name, engram_identities.display_name),
         source       = COALESCE(EXCLUDED.source,       engram_identities.source),
-        is_primary   = COALESCE(EXCLUDED.is_primary,   engram_identities.is_primary),
+        is_primary   = EXCLUDED.is_primary,
         picture      = COALESCE(EXCLUDED.picture,      engram_identities.picture),
         linked_at    = EXCLUDED.linked_at,
+        unlinked_at  = CASE WHEN ${unlinkedProvided}
+                       THEN ${input.unlinked_at ?? null}
+                       ELSE engram_identities.unlinked_at END,
         updated_at   = now()
       RETURNING ref, person_id, service, external_id, display_name, source,
-                is_primary, picture, linked_at, created_at, updated_at
+                is_primary, picture, linked_at, unlinked_at,
+                created_at, updated_at
     `;
         return toIdentityInfo(rows[0]);
     }
     async getIdentityByRef(ref) {
         const rows = await this.sql `
       SELECT ref, person_id, service, external_id, display_name, source,
-             is_primary, picture, linked_at, created_at, updated_at
+             is_primary, picture, linked_at, unlinked_at,
+             created_at, updated_at
       FROM engram_identities
       WHERE workspace_id = ${this.workspaceId} AND ref = ${ref}
       LIMIT 1
@@ -376,7 +442,8 @@ export class PostgresAdapter {
     async listIdentitiesByPerson(personId) {
         const rows = await this.sql `
       SELECT ref, person_id, service, external_id, display_name, source,
-             is_primary, picture, linked_at, created_at, updated_at
+             is_primary, picture, linked_at, unlinked_at,
+             created_at, updated_at
       FROM engram_identities
       WHERE workspace_id = ${this.workspaceId} AND person_id = ${personId}
       ORDER BY linked_at DESC
@@ -389,20 +456,23 @@ function toPersonInfo(r) {
     return {
         id: r.id,
         display_name: r.display_name,
+        role: r.role,
+        team: r.team,
+        source: r.source,
         created_at: toIso(r.created_at),
         updated_at: toIso(r.updated_at),
     };
 }
 function toSessionRow(r) {
+    const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
     return {
         id: r.id,
         ...(r.title ? { title: r.title } : {}),
         ...(r.channel ? { channel: r.channel } : {}),
         participants: r.participants,
         viewable_by: r.viewable_by,
-        createdAt: typeof r.created_at === "string"
-            ? r.created_at
-            : r.created_at.toISOString(),
+        createdAt: toIso(r.created_at),
+        updatedAt: toIso(r.updated_at),
         ...(r.status === "active" || r.status === "idle" || r.status === "completed"
             ? { status: r.status }
             : {}),
@@ -435,9 +505,7 @@ function toAliasInfo(r) {
 }
 function toIdentityInfo(r) {
     const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
-    const linkedAt = typeof r.linked_at === "string"
-        ? r.linked_at.slice(0, 10)
-        : r.linked_at.toISOString().slice(0, 10);
+    // linked_at is now TIMESTAMPTZ (post-migration 0004). Emit full ISO.
     return {
         ref: r.ref,
         person_id: r.person_id,
@@ -447,7 +515,8 @@ function toIdentityInfo(r) {
         source: r.source,
         is_primary: r.is_primary,
         picture: r.picture,
-        linked_at: linkedAt,
+        linked_at: toIso(r.linked_at),
+        unlinked_at: r.unlinked_at === null ? null : toIso(r.unlinked_at),
         created_at: toIso(r.created_at),
         updated_at: toIso(r.updated_at),
     };

package/dist/migrations/0005-session-updated-at.d.ts

@@ -0,0 +1,2 @@
+export declare const name = "0005-session-updated-at";
+export declare const sql = "\n-- Session-level updated_at, so listSessions can sort by \"most recent\n-- activity\" (matching monet's conversations.updated_at semantics) and\n-- callers can filter \"active in the last hour\" without re-folding the\n-- event log. Maintained by appendEvents + updateSession at write time.\nALTER TABLE engram_sessions ADD COLUMN IF NOT EXISTS updated_at TIMESTAMPTZ;\nUPDATE engram_sessions SET updated_at = created_at WHERE updated_at IS NULL;\nALTER TABLE engram_sessions ALTER COLUMN updated_at SET DEFAULT NOW();\nALTER TABLE engram_sessions ALTER COLUMN updated_at SET NOT NULL;\n\n-- Index supporting the most common list-by-recent-activity query and\n-- its status-filtered variant (status filter is cheap once the date\n-- range scan is narrow).\nCREATE INDEX IF NOT EXISTS idx_engram_sessions_workspace_updated\n  ON engram_sessions (workspace_id, updated_at DESC);\n";

package/dist/migrations/0005-session-updated-at.js

@@ -0,0 +1,17 @@
+export const name = "0005-session-updated-at";
+export const sql = `
+-- Session-level updated_at, so listSessions can sort by "most recent
+-- activity" (matching monet's conversations.updated_at semantics) and
+-- callers can filter "active in the last hour" without re-folding the
+-- event log. Maintained by appendEvents + updateSession at write time.
+ALTER TABLE engram_sessions ADD COLUMN IF NOT EXISTS updated_at TIMESTAMPTZ;
+UPDATE engram_sessions SET updated_at = created_at WHERE updated_at IS NULL;
+ALTER TABLE engram_sessions ALTER COLUMN updated_at SET DEFAULT NOW();
+ALTER TABLE engram_sessions ALTER COLUMN updated_at SET NOT NULL;
+
+-- Index supporting the most common list-by-recent-activity query and
+-- its status-filtered variant (status filter is cheap once the date
+-- range scan is narrow).
+CREATE INDEX IF NOT EXISTS idx_engram_sessions_workspace_updated
+  ON engram_sessions (workspace_id, updated_at DESC);
+`;

package/dist/migrations/index.js

@@ -2,6 +2,7 @@ import * as m0001 from "./0001-baseline";
 import * as m0002 from "./0002-aliases";
 import * as m0003 from "./0003-identities";
 import * as m0004 from "./0004-schema-completion";
+import * as m0005 from "./0005-session-updated-at";
 /**
  * Schema migrations, applied in array order. Add a new file under
  * `migrations/NNNN-<slug>.ts` exporting `name` and `sql`, then append it
@@ -14,4 +15,5 @@ export const MIGRATIONS = [
     { name: m0002.name, sql: m0002.sql },
     { name: m0003.name, sql: m0003.sql },
     { name: m0004.name, sql: m0004.sql },
+    { name: m0005.name, sql: m0005.sql },
 ];

package/dist/routes/aliases.d.ts

@@ -0,0 +1,24 @@
+import { Hono } from "hono";
+import type { Env } from "../context";
+import { type RouteConfig } from "./helpers";
+/**
+ * Workspace-wide alias lookup. Mount under `/v1`:
+ *   GET /v1/aliases?name=<name>
+ *
+ * The personal-scoped endpoints (`/v1/persons/:id/aliases`) cover
+ * "what aliases does this person have?". This top-level route covers
+ * the inverse — "which person(s) does this name resolve to?" — which
+ * hosts use to ground a free-text "who is X?" against the alias
+ * registry without pre-knowing the owning person.
+ *
+ * The match is case-insensitive (the alias table is keyed by
+ * `lower(name)`). Multiple persons in the same workspace can share an
+ * alias, so the response is an array ordered by `last_used` desc; the
+ * caller picks the most recently active match (or applies its own
+ * tie-breaker like caller/usage_count).
+ *
+ * Returns 400 when `?name=` is missing — alias lookups have no useful
+ * "list all aliases" semantics, so dropping the query param is treated
+ * as a request error rather than a full scan.
+ */
+export declare function aliasesRoutes(_cfg: RouteConfig): Hono<Env>;

package/dist/routes/aliases.js

@@ -0,0 +1,41 @@
+import { Hono } from "hono";
+import { resolvePersonMap } from "./helpers";
+/**
+ * Workspace-wide alias lookup. Mount under `/v1`:
+ *   GET /v1/aliases?name=<name>
+ *
+ * The personal-scoped endpoints (`/v1/persons/:id/aliases`) cover
+ * "what aliases does this person have?". This top-level route covers
+ * the inverse — "which person(s) does this name resolve to?" — which
+ * hosts use to ground a free-text "who is X?" against the alias
+ * registry without pre-knowing the owning person.
+ *
+ * The match is case-insensitive (the alias table is keyed by
+ * `lower(name)`). Multiple persons in the same workspace can share an
+ * alias, so the response is an array ordered by `last_used` desc; the
+ * caller picks the most recently active match (or applies its own
+ * tie-breaker like caller/usage_count).
+ *
+ * Returns 400 when `?name=` is missing — alias lookups have no useful
+ * "list all aliases" semantics, so dropping the query param is treated
+ * as a request error rather than a full scan.
+ */
+export function aliasesRoutes(_cfg) {
+    const app = new Hono();
+    app.get("/aliases", async (c) => {
+        const name = c.req.query("name");
+        if (!name) {
+            return c.json({
+                error: "name_required",
+                message: "GET /v1/aliases requires a ?name= query parameter",
+            }, 400);
+        }
+        const aliases = await c.var.ctx.storage.findAliasesByName(name);
+        // Inline the persons map so the caller can render a "candidate
+        // picker" UI without a second round-trip per match. Same envelope
+        // shape as the session list endpoints.
+        const persons = await resolvePersonMap(c.var.ctx.storage, aliases.map((a) => ({ participants: [a.person_id], viewable_by: [] })));
+        return c.json({ aliases, persons });
+    });
+    return app;
+}

package/dist/routes/sessions.js

@@ -63,7 +63,15 @@ export function sessionsRoutes(cfg) {
     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 rawStatus = c.req.query("status");
+        const status = rawStatus === "active" || rawStatus === "idle" || rawStatus === "completed"
+            ? rawStatus
+            : undefined;
+        const sessions = await c.var.ctx.storage.listSessions({
+            limit,
+            channel,
+            status,
+        });
         const persons = await resolvePersonMap(c.var.ctx.storage, sessions);
         return c.json({ sessions, persons });
     });

package/dist/server.js

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { log, newRequestId } from "./logger";
 import { createAdminRouter } from "./admin";
+import { aliasesRoutes } from "./routes/aliases";
 import { sessionsRoutes } from "./routes/sessions";
 import { personsRoutes } from "./routes/persons";
 import { identitiesRoutes } from "./routes/identities";
@@ -61,6 +62,7 @@ export function createServer(opts) {
             personSessions: "GET /v1/persons/:id/sessions",
             personAliases: "GET /v1/persons/:id/aliases",
             upsertAlias: "PUT /v1/persons/:id/aliases/:name",
+            findAliasesByName: "GET /v1/aliases?name=…",
             identityByRef: "GET/PUT /v1/identities/:ref",
             personIdentities: "GET /v1/persons/:id/identities",
         },
@@ -88,6 +90,7 @@ export function createServer(opts) {
     app.route("/v1", sessionsRoutes(cfg));
     app.route("/v1", personsRoutes(cfg));
     app.route("/v1", identitiesRoutes(cfg));
+    app.route("/v1", aliasesRoutes(cfg));
     app.route("/v1", searchRoutes(cfg));
     return app;
 }

package/dist/storage.d.ts

@@ -33,10 +33,11 @@ export interface StorageAdapter {
      * events, which returns `[]`).
      */
     getSessionEvents(sessionId: string): Promise<SessionEvent[] | null>;
-    /** List recent sessions. */
+    /** List recent sessions, ordered by `updated_at` desc. */
     listSessions(opts: {
         limit: number;
         channel?: string;
+        status?: "active" | "idle" | "completed";
     }): Promise<Session[]>;
     /**
      * Create a person with a freshly allocated id. The host (e.g. monet)
@@ -53,7 +54,12 @@ export interface StorageAdapter {
     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. */
+    /**
+     * List or search persons in this workspace. The free-text query
+     * matches across id / display_name / role / team / linked identity
+     * display_names — so a search for "design" finds people with that
+     * role even if their display_name doesn't contain it.
+     */
     listPersons(opts: {
         limit: number;
         q?: string;
@@ -84,6 +90,16 @@ export interface StorageAdapter {
     } & AliasUpsert): Promise<AliasInfo | null>;
     /** A person's aliases, ordered newest-used-first. */
     listAliases(personId: string): Promise<AliasInfo[]>;
+    /**
+     * Workspace-wide lookup by alias name (case-insensitive). Returns
+     * every row whose `lower(name)` matches `lower(name)` across all
+     * persons in this workspace. Ordered by `last_used` desc — the
+     * caller can pick the most recently active match without re-sorting.
+     *
+     * Hosts use this to resolve a free-text "who is X?" query into a
+     * person id without pre-knowing which person owns the alias.
+     */
+    findAliasesByName(name: string): Promise<AliasInfo[]>;
     /**
      * Upsert by `ref` (e.g. `slack:U12345`). Idempotent: writing the same
      * ref multiple times converges. If the ref points to a different
@@ -109,6 +125,7 @@ export interface SessionRow {
     participants: string[];
     viewable_by: string[];
     createdAt: string;
+    updatedAt: string;
     status?: "active" | "idle" | "completed";
     summary?: string;
     model?: string;

package/dist/storage.js

@@ -35,5 +35,6 @@ export function foldEvents(row, events, now) {
         ...(row.trigger_event_id !== undefined
             ? { trigger_event_id: row.trigger_event_id }
             : {}),
+        updated_at: row.updatedAt,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-server",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Engram server: ingest agent session events, persist via a pluggable adapter, expose search.",
   "keywords": [
     "engram",
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@hexis-ai/engram-core": "^0.1.5",
-    "@hexis-ai/engram-sdk": "^0.7.0",
+    "@hexis-ai/engram-sdk": "^0.9.0",
     "hono": "^4.6.0",
     "zod": "^4.0.0"
   },