@hexis-ai/engram-server 0.9.0 → 0.10.0

package/dist/adapters/memory.d.ts

@@ -49,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

@@ -287,6 +287,12 @@ 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))

package/dist/adapters/postgres.d.ts

@@ -62,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

@@ -367,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

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

@@ -90,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-server",
-  "version": "0.9.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.8.0",
+    "@hexis-ai/engram-sdk": "^0.9.0",
     "hono": "^4.6.0",
     "zod": "^4.0.0"
   },