@hexis-ai/engram-sdk 0.1.2 → 0.1.5

package/dist/admin.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Admin SDK: provisions workspaces and API keys against an engram-server
+ * `/admin/v1/*` mount. Use from privileged contexts only — the admin token
+ * is platform-root and must never reach end-user code paths.
+ */
+export interface AdminClientOptions {
+    baseUrl: string;
+    adminToken: string;
+    fetch?: typeof fetch;
+}
+export interface Workspace {
+    id: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+export interface ApiKey {
+    id: string;
+    workspaceId: string;
+    prefix: string;
+    name?: string;
+    createdAt: string;
+    lastUsedAt?: string;
+    revokedAt?: string;
+}
+export interface IssuedKey extends ApiKey {
+    /** Plaintext key. Stored only by the caller; never retrievable again. */
+    raw: string;
+}
+export interface CreateWorkspaceInput {
+    id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    /** Whether to also issue an initial API key. Default true. */
+    issueKey?: boolean;
+    /** Optional name applied to the initial API key. */
+    keyName?: string;
+}
+export interface CreateWorkspaceResult {
+    workspace: Workspace;
+    /** Present when `issueKey !== false`. */
+    key?: IssuedKey;
+}
+export declare class EngramAdmin {
+    private readonly baseUrl;
+    private readonly adminToken;
+    private readonly fetchImpl;
+    constructor(opts: AdminClientOptions);
+    createWorkspace(input?: CreateWorkspaceInput): Promise<CreateWorkspaceResult>;
+    listWorkspaces(): Promise<Workspace[]>;
+    getWorkspace(id: string): Promise<Workspace>;
+    deleteWorkspace(id: string): Promise<void>;
+    issueKey(workspaceId: string, opts?: {
+        name?: string;
+    }): Promise<IssuedKey>;
+    listKeys(workspaceId: string): Promise<ApiKey[]>;
+    revokeKey(workspaceId: string, keyId: string): Promise<void>;
+    private request;
+}
+export declare function createAdminClient(opts: AdminClientOptions): EngramAdmin;

package/dist/admin.js

@@ -0,0 +1,62 @@
+/**
+ * Admin SDK: provisions workspaces and API keys against an engram-server
+ * `/admin/v1/*` mount. Use from privileged contexts only — the admin token
+ * is platform-root and must never reach end-user code paths.
+ */
+export class EngramAdmin {
+    baseUrl;
+    adminToken;
+    fetchImpl;
+    constructor(opts) {
+        if (!opts.baseUrl)
+            throw new Error("EngramAdmin: baseUrl is required");
+        if (!opts.adminToken)
+            throw new Error("EngramAdmin: adminToken is required");
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.adminToken = opts.adminToken;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async createWorkspace(input = {}) {
+        return this.request("POST", "/admin/v1/workspaces", input);
+    }
+    async listWorkspaces() {
+        const r = await this.request("GET", "/admin/v1/workspaces");
+        return r.workspaces;
+    }
+    async getWorkspace(id) {
+        return this.request("GET", `/admin/v1/workspaces/${encodeURIComponent(id)}`);
+    }
+    async deleteWorkspace(id) {
+        await this.request("DELETE", `/admin/v1/workspaces/${encodeURIComponent(id)}`);
+    }
+    async issueKey(workspaceId, opts = {}) {
+        return this.request("POST", `/admin/v1/workspaces/${encodeURIComponent(workspaceId)}/keys`, opts);
+    }
+    async listKeys(workspaceId) {
+        const r = await this.request("GET", `/admin/v1/workspaces/${encodeURIComponent(workspaceId)}/keys`);
+        return r.keys;
+    }
+    async revokeKey(workspaceId, keyId) {
+        await this.request("DELETE", `/admin/v1/workspaces/${encodeURIComponent(workspaceId)}/keys/${encodeURIComponent(keyId)}`);
+    }
+    async request(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${this.adminToken}`,
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`engram-admin ${method} ${path} ${res.status}: ${text}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+}
+export function createAdminClient(opts) {
+    return new EngramAdmin(opts);
+}

package/dist/client.d.ts

@@ -1,6 +1,23 @@
 import type { ScoredSession, SearchOptions, Session, SessionStep } from "@hexis-ai/engram-core";
 import { type RefCandidate } from "./extract";
-import type { EventBatch, SessionInit } from "./types";
+import type { EventBatch, PersonCreate, PersonInfo, PersonMap, PersonUpdate, SessionInit } from "./types";
+/**
+ * Envelope returned by session endpoints. The persons map is deduped
+ * across whatever sessions the response carries so display info isn't
+ * repeated per row.
+ */
+export interface SessionEnvelope {
+    session: Session;
+    persons: PersonMap;
+}
+export interface SessionListEnvelope {
+    sessions: Session[];
+    persons: PersonMap;
+}
+export interface SearchEnvelope {
+    results: ScoredSession[];
+    persons: PersonMap;
+}
 export interface EngramOptions {
     apiKey: string;
     baseUrl: string;
@@ -16,6 +33,25 @@ export interface EngramOptions {
     batchSize?: number;
     /** Hook invoked on transport errors. Default: console.error. */
     onError?: (err: unknown) => void;
+    /**
+     * Header name to carry the api key. Defaults to "Authorization" with a
+     * `Bearer <key>` value for backward compatibility. Set to "x-api-key"
+     * when the host adds its own `Authorization` (e.g. a Cloud Run ID token
+     * for service-to-service IAM).
+     */
+    apiKeyHeader?: "authorization" | "x-api-key";
+    /**
+     * Async hook resolved per-request that returns headers to attach. Use
+     * for short-lived credentials like Cloud Run identity tokens.
+     */
+    authHeaders?: () => Promise<Record<string, string>> | Record<string, string>;
+    /**
+     * Max retry attempts for a failed event batch (transient transport errors).
+     * Default 4 (~30s total with exponential backoff). 0 disables retries.
+     */
+    maxRetries?: number;
+    /** Base backoff in ms; doubled each attempt. Default 500. */
+    retryBackoffMs?: number;
 }
 export interface RecordStepInput {
     tool: string;
@@ -44,9 +80,8 @@ export interface SearchRequest {
     };
     options?: SearchOptions;
 }
-export interface SearchResponse {
-    results: ScoredSession[];
-}
+/** @deprecated Use `SearchEnvelope` (carries `persons` map too). */
+export type SearchResponse = SearchEnvelope;
 export declare class Engram {
     private readonly apiKey;
     private readonly baseUrl;
@@ -54,18 +89,51 @@ export declare class Engram {
     private readonly flushIntervalMs;
     private readonly batchSize;
     private readonly onError;
+    private readonly apiKeyHeader;
+    private readonly authHeaders?;
+    readonly maxRetries: number;
+    readonly retryBackoffMs: number;
     constructor(opts: EngramOptions);
+    /** Probe identity — returns the workspace the configured key resolves to. */
+    me(): Promise<{
+        workspaceId: string;
+    }>;
     /** Begin a new session. Returns a handle for buffering events. */
     startSession(init?: SessionInit): Promise<EngramSession>;
-    /** Fetch a single Session by id. */
-    getSession(id: string): Promise<Session>;
-    /** List recent sessions (server defines defaults & limits). */
+    /** Fetch a single session by id, plus the persons map for its participants/viewers. */
+    getSession(id: string): Promise<SessionEnvelope>;
+    /** List recent sessions plus the deduped persons map across them. */
     listSessions(opts?: {
         limit?: number;
         channel?: string;
-    }): Promise<Session[]>;
+    }): Promise<SessionListEnvelope>;
     /** Run a search. */
-    search(req: SearchRequest): Promise<SearchResponse>;
+    search(req: SearchRequest): Promise<SearchEnvelope>;
+    /** Person operations. The host (e.g. monet) resolves platform identities
+     *  to person ids before storing sessions; this namespace lets it own the
+     *  underlying person records (display name + canonical id). */
+    readonly persons: {
+        /** Allocate a new person id and return the row. */
+        create: (input: PersonCreate) => Promise<PersonInfo>;
+        /** Upsert at a host-supplied id (backfill / fallback). */
+        upsert: (id: string, input: PersonCreate) => Promise<PersonInfo>;
+        /** Patch profile fields. Returns 404 if id is unknown. */
+        update: (id: string, patch: PersonUpdate) => Promise<PersonInfo>;
+        get: (id: string) => Promise<PersonInfo>;
+        /** Free-text search (substring across id + display_name). */
+        list: (opts?: {
+            limit?: number;
+            q?: string;
+        }) => Promise<{
+            persons: PersonInfo[];
+        }>;
+        /** Sessions where this person appears in participants (default) or viewable_by. */
+        sessions: (id: string, opts?: {
+            limit?: number;
+            channel?: string;
+            scope?: "participant" | "viewable";
+        }) => Promise<SessionListEnvelope>;
+    };
     /** Internal: ship an event batch to the server. */
     sendBatch(sessionId: string, batch: EventBatch): Promise<void>;
     /** Internal accessor used by EngramSession to honor SDK config. */
@@ -86,11 +154,18 @@ export declare class EngramSession {
     private ended;
     constructor(engram: Engram, id: string);
     recordStep(input: RecordStepInput): SessionStep;
-    addParticipant(identityRef: string): void;
+    /** Append a participant to the running session. `personId` must already be
+     *  resolved by the host (engram-server does not resolve platform identities). */
+    addParticipant(personId: string): void;
     setTitle(title: string): void;
     /** Mark the session ended and flush buffered events. */
     end(): Promise<void>;
-    /** Force a flush regardless of batch size / timer. */
+    /**
+     * Force a flush regardless of batch size / timer. Transient failures
+     * are retried with exponential backoff up to `maxRetries`. If every
+     * attempt fails the events are returned to the head of the buffer so
+     * the next flush picks them up.
+     */
     flush(): Promise<void>;
     private enqueue;
 }

package/dist/client.js

@@ -7,6 +7,10 @@ export class Engram {
     flushIntervalMs;
     batchSize;
     onError;
+    apiKeyHeader;
+    authHeaders;
+    maxRetries;
+    retryBackoffMs;
     constructor(opts) {
         if (!opts.apiKey)
             throw new Error("Engram: apiKey is required");
@@ -18,17 +22,25 @@ export class Engram {
         this.flushIntervalMs = opts.flushIntervalMs ?? 2000;
         this.batchSize = opts.batchSize ?? 32;
         this.onError = opts.onError ?? ((e) => console.error("[engram]", e));
+        this.apiKeyHeader = opts.apiKeyHeader ?? "authorization";
+        this.authHeaders = opts.authHeaders;
+        this.maxRetries = opts.maxRetries ?? 4;
+        this.retryBackoffMs = opts.retryBackoffMs ?? 500;
+    }
+    /** Probe identity — returns the workspace the configured key resolves to. */
+    async me() {
+        return this.request("GET", "/v1/me");
     }
     /** Begin a new session. Returns a handle for buffering events. */
     async startSession(init = {}) {
         const ack = await this.request("POST", "/v1/sessions", init);
         return new EngramSession(this, ack.id);
     }
-    /** Fetch a single Session by id. */
+    /** Fetch a single session by id, plus the persons map for its participants/viewers. */
     async getSession(id) {
         return this.request("GET", `/v1/sessions/${encodeURIComponent(id)}`);
     }
-    /** List recent sessions (server defines defaults & limits). */
+    /** List recent sessions plus the deduped persons map across them. */
     async listSessions(opts = {}) {
         const qs = new URLSearchParams();
         if (opts.limit !== undefined)
@@ -42,6 +54,41 @@ export class Engram {
     async search(req) {
         return this.request("POST", "/v1/search", req);
     }
+    // ---- Persons ----
+    /** Person operations. The host (e.g. monet) resolves platform identities
+     *  to person ids before storing sessions; this namespace lets it own the
+     *  underlying person records (display name + canonical id). */
+    persons = {
+        /** Allocate a new person id and return the row. */
+        create: (input) => this.request("POST", "/v1/persons", input),
+        /** Upsert at a host-supplied id (backfill / fallback). */
+        upsert: (id, input) => this.request("PUT", `/v1/persons/${encodeURIComponent(id)}`, input),
+        /** Patch profile fields. Returns 404 if id is unknown. */
+        update: (id, patch) => this.request("PATCH", `/v1/persons/${encodeURIComponent(id)}`, patch),
+        get: (id) => this.request("GET", `/v1/persons/${encodeURIComponent(id)}`),
+        /** Free-text search (substring across id + display_name). */
+        list: (opts = {}) => {
+            const qs = new URLSearchParams();
+            if (opts.limit !== undefined)
+                qs.set("limit", String(opts.limit));
+            if (opts.q)
+                qs.set("q", opts.q);
+            const tail = qs.toString();
+            return this.request("GET", `/v1/persons${tail ? `?${tail}` : ""}`);
+        },
+        /** Sessions where this person appears in participants (default) or viewable_by. */
+        sessions: (id, opts = {}) => {
+            const qs = new URLSearchParams();
+            if (opts.limit !== undefined)
+                qs.set("limit", String(opts.limit));
+            if (opts.channel)
+                qs.set("channel", opts.channel);
+            if (opts.scope)
+                qs.set("scope", opts.scope);
+            const tail = qs.toString();
+            return this.request("GET", `/v1/persons/${encodeURIComponent(id)}/sessions${tail ? `?${tail}` : ""}`);
+        },
+    };
     /** Internal: ship an event batch to the server. */
     async sendBatch(sessionId, batch) {
         if (batch.events.length === 0)
@@ -53,12 +100,18 @@ export class Engram {
         return { flushIntervalMs: this.flushIntervalMs, batchSize: this.batchSize, onError: this.onError };
     }
     async request(method, path, body) {
+        const headers = { "content-type": "application/json" };
+        if (this.apiKeyHeader === "authorization") {
+            headers["authorization"] = `Bearer ${this.apiKey}`;
+        }
+        else {
+            headers["x-api-key"] = this.apiKey;
+        }
+        if (this.authHeaders)
+            Object.assign(headers, await this.authHeaders());
         const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
             method,
-            headers: {
-                "content-type": "application/json",
-                authorization: `Bearer ${this.apiKey}`,
-            },
+            headers,
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
         });
         if (!res.ok) {
@@ -98,12 +151,14 @@ export class EngramSession {
         this.enqueue(ev);
         return { tool, resources };
     }
-    addParticipant(identityRef) {
+    /** Append a participant to the running session. `personId` must already be
+     *  resolved by the host (engram-server does not resolve platform identities). */
+    addParticipant(personId) {
         const ev = {
             type: "participant",
             seq: this.seq++,
             at: new Date().toISOString(),
-            identityRef,
+            personId,
         };
         this.enqueue(ev);
     }
@@ -128,7 +183,12 @@ export class EngramSession {
         });
         await this.flush();
     }
-    /** Force a flush regardless of batch size / timer. */
+    /**
+     * Force a flush regardless of batch size / timer. Transient failures
+     * are retried with exponential backoff up to `maxRetries`. If every
+     * attempt fails the events are returned to the head of the buffer so
+     * the next flush picks them up.
+     */
     async flush() {
         if (this.flushTimer) {
             clearTimeout(this.flushTimer);
@@ -139,14 +199,32 @@ export class EngramSession {
         if (this.buffer.length === 0)
             return;
         const events = this.buffer.splice(0);
-        this.inFlight = this.engram
-            .sendBatch(this.id, { events })
-            .catch((e) => {
-            this.engram.config.onError(e);
+        const { maxRetries, retryBackoffMs, onError } = {
+            maxRetries: this.engram.maxRetries,
+            retryBackoffMs: this.engram.retryBackoffMs,
+            onError: this.engram.config.onError,
+        };
+        this.inFlight = (async () => {
+            let lastErr;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                try {
+                    await this.engram.sendBatch(this.id, { events });
+                    return;
+                }
+                catch (e) {
+                    lastErr = e;
+                    onError(e);
+                    if (attempt < maxRetries) {
+                        const delay = retryBackoffMs * 2 ** attempt;
+                        await new Promise((r) => setTimeout(r, delay));
+                    }
+                }
+            }
+            // All retries exhausted — return events to the buffer head so a
+            // future flush (or session.end()) can take another swing.
             this.buffer.unshift(...events);
-            throw e;
-        })
-            .finally(() => {
+            throw lastErr;
+        })().finally(() => {
             this.inFlight = null;
         });
         await this.inFlight;

package/dist/extract.d.ts

@@ -8,7 +8,7 @@
  *
  * Resource id format follows engram convention: `${service}:${id-or-url}`.
  */
-export type ReferenceService = "linear" | "notion" | "web" | "github";
+export type ReferenceService = "linear" | "notion" | "web" | "github" | "slack" | "gmail";
 export type ReferenceAction = "read" | "write";
 export interface RefCandidate {
     service: ReferenceService;

package/dist/extract.js

@@ -10,13 +10,32 @@
  */
 const isWebSearch = (n) => n === "WebSearch" || n === "web_search";
 const isWebFetch = (n) => n === "WebFetch" || n === "web_fetch";
+/**
+ * Tool names whose effect is a write (mutation). Defaults to read.
+ * Same map for all vendors — names are namespaced enough.
+ */
 const WRITE_TOOLS = {
+    // linear (native + mcp)
     create_issue: "write",
     update_issue: "write",
+    // notion mcp
     "notion-create-pages": "write",
     "notion-update-page": "write",
     "notion-create-database": "write",
     "notion-create-comment": "write",
+    // slack mcp
+    slack_post_message: "write",
+    slack_reply_to_thread: "write",
+    slack_add_reaction: "write",
+    // gmail mcp
+    gmail_send: "write",
+    gmail_send_message: "write",
+    gmail_draft_message: "write",
+    // github mcp
+    github_create_issue: "write",
+    github_create_pull_request: "write",
+    github_create_comment: "write",
+    github_add_pr_review_comment: "write",
 };
 function getAction(toolName) {
     return WRITE_TOOLS[toolName] ?? "read";
@@ -51,6 +70,12 @@ export function extractReferences(vendor, toolName, input, result) {
         return extractLinearRefs(toolName, input, result);
     if (vendor === "notion")
         return extractNotionRefs(toolName, input, result);
+    if (vendor === "slack")
+        return extractSlackRefs(toolName, input, result);
+    if (vendor === "gmail")
+        return extractGmailRefs(toolName, input, result);
+    if (vendor === "github")
+        return extractGithubRefs(toolName, input, result);
     return [];
 }
 /** Convenience: encode RefCandidate to engram resource id (`service:resource_id`). */
@@ -135,3 +160,83 @@ function extractWebRefs(toolName, input) {
     }
     return [];
 }
+/**
+ * Slack MCP: input names follow `channel_id` / `channel` / `user_id` / `thread_ts`.
+ * Resource id encodes "C123" for channels, "U123" for users, "C123:1234.567"
+ * for thread anchors. Read-style tools (list_*, get_history, ...) produce
+ * a channel resource when one is named; post / reply produce write resources.
+ */
+function extractSlackRefs(toolName, input, _result) {
+    const action = getAction(toolName);
+    const out = [];
+    const channel = (input.channel_id ?? input.channel);
+    const thread = (input.thread_ts ?? input.ts);
+    const user = (input.user_id ?? input.user);
+    if (channel && thread) {
+        out.push({ service: "slack", action, resource_id: `${channel}:${thread}` });
+    }
+    else if (channel) {
+        out.push({ service: "slack", action, resource_id: channel });
+    }
+    if (user) {
+        out.push({ service: "slack", action: "read", resource_id: user });
+    }
+    return out;
+}
+/**
+ * Gmail MCP: `messageId`, `threadId`, `query` for search. Threads are the
+ * stable identity in Gmail; we prefer thread id when present, fall back to
+ * message id. Search produces `query:<q>` so two searches for the same
+ * topic dedupe.
+ */
+function extractGmailRefs(toolName, input, _result) {
+    const action = getAction(toolName);
+    const out = [];
+    const threadId = (input.threadId ?? input.thread_id);
+    const messageId = (input.messageId ?? input.message_id);
+    const query = input.query;
+    const to = input.to;
+    if (threadId) {
+        out.push({ service: "gmail", action, resource_id: `thread:${threadId}` });
+    }
+    else if (messageId) {
+        out.push({ service: "gmail", action, resource_id: `msg:${messageId}` });
+    }
+    if (action === "read" && query) {
+        out.push({ service: "gmail", action: "read", resource_id: `query:${query}` });
+    }
+    if (action === "write" && to) {
+        const recipients = Array.isArray(to) ? to : [to];
+        for (const r of recipients) {
+            out.push({ service: "gmail", action: "write", resource_id: `to:${r}` });
+        }
+    }
+    return out;
+}
+/**
+ * GitHub MCP: `owner`, `repo`, `pull_number` / `issue_number` / `path`.
+ * PRs and issues are global identifiers within a repo so we encode as
+ * `<owner>/<repo>#<n>`. File paths become `<owner>/<repo>:<path>`.
+ */
+function extractGithubRefs(toolName, input, _result) {
+    const action = getAction(toolName);
+    const owner = input.owner;
+    const repo = input.repo;
+    if (!owner || !repo)
+        return [];
+    const base = `${owner}/${repo}`;
+    const pullNumber = input.pull_number ?? input.pullNumber;
+    if (pullNumber != null) {
+        return [{ service: "github", action, resource_id: `${base}#${pullNumber}` }];
+    }
+    const issueNumber = input.issue_number ?? input.issueNumber;
+    if (issueNumber != null) {
+        return [{ service: "github", action, resource_id: `${base}#${issueNumber}` }];
+    }
+    const path = input.path;
+    if (path) {
+        return [{ service: "github", action, resource_id: `${base}:${path}` }];
+    }
+    // Just naming the repo (list_prs etc.) — record the repo itself.
+    return [{ service: "github", action, resource_id: base }];
+}

package/dist/id-token.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Identity-token helper for Cloud Run service-to-service auth.
+ *
+ * On Cloud Run / Cloud Functions / GCE / GKE the metadata server hands out
+ * a Google-signed ID token scoped to a single audience (typically the URL
+ * of the target service). Callers can attach this token in `Authorization:
+ * Bearer <id-token>` so the target's IAM check (`roles/run.invoker`)
+ * passes for the calling service account.
+ *
+ * Tokens are cached per audience until ~30s before expiry. The metadata
+ * server itself is rate-limited, so this matters under load.
+ */
+/**
+ * Fetch an identity token for `audience` from the GCE/Cloud Run metadata
+ * server. Throws if not on a GCP environment with a metadata endpoint.
+ * Result is cached until 30s before its embedded `exp` claim.
+ */
+export declare function fetchIdToken(audience: string): Promise<string>;
+/**
+ * Convenience: build an `authHeaders` function suitable for `EngramOptions`.
+ *
+ *   const engram = new Engram({
+ *     apiKey: process.env.ENGRAM_API_KEY!,
+ *     baseUrl: process.env.ENGRAM_BASE_URL!,
+ *     apiKeyHeader: "x-api-key",
+ *     authHeaders: cloudRunIdTokenAuth(process.env.ENGRAM_BASE_URL!),
+ *   });
+ */
+export declare function cloudRunIdTokenAuth(audience: string): () => Promise<Record<string, string>>;

package/dist/id-token.js

@@ -0,0 +1,62 @@
+/**
+ * Identity-token helper for Cloud Run service-to-service auth.
+ *
+ * On Cloud Run / Cloud Functions / GCE / GKE the metadata server hands out
+ * a Google-signed ID token scoped to a single audience (typically the URL
+ * of the target service). Callers can attach this token in `Authorization:
+ * Bearer <id-token>` so the target's IAM check (`roles/run.invoker`)
+ * passes for the calling service account.
+ *
+ * Tokens are cached per audience until ~30s before expiry. The metadata
+ * server itself is rate-limited, so this matters under load.
+ */
+const METADATA_URL = "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity";
+const cache = new Map();
+const SAFETY_WINDOW_MS = 30_000;
+function decodeExp(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const payload = JSON.parse(atob(parts[1]));
+        return typeof payload.exp === "number" ? payload.exp * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch an identity token for `audience` from the GCE/Cloud Run metadata
+ * server. Throws if not on a GCP environment with a metadata endpoint.
+ * Result is cached until 30s before its embedded `exp` claim.
+ */
+export async function fetchIdToken(audience) {
+    const now = Date.now();
+    const cached = cache.get(audience);
+    if (cached && now < cached.expiresAt - SAFETY_WINDOW_MS)
+        return cached.token;
+    const url = `${METADATA_URL}?audience=${encodeURIComponent(audience)}`;
+    const res = await fetch(url, { headers: { "metadata-flavor": "Google" } });
+    if (!res.ok) {
+        throw new Error(`fetchIdToken ${res.status}: ${await res.text().catch(() => "")}`);
+    }
+    const token = (await res.text()).trim();
+    const exp = decodeExp(token);
+    cache.set(audience, { token, expiresAt: exp ?? now + 60 * 60 * 1000 });
+    return token;
+}
+/**
+ * Convenience: build an `authHeaders` function suitable for `EngramOptions`.
+ *
+ *   const engram = new Engram({
+ *     apiKey: process.env.ENGRAM_API_KEY!,
+ *     baseUrl: process.env.ENGRAM_BASE_URL!,
+ *     apiKeyHeader: "x-api-key",
+ *     authHeaders: cloudRunIdTokenAuth(process.env.ENGRAM_BASE_URL!),
+ *   });
+ */
+export function cloudRunIdTokenAuth(audience) {
+    return async () => ({
+        authorization: `Bearer ${await fetchIdToken(audience)}`,
+    });
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-export { Engram, EngramSession, type EngramOptions, type RecordStepInput, type SearchRequest, type SearchResponse, } from "./client";
+export { Engram, EngramSession, type EngramOptions, type RecordStepInput, type SearchRequest, type SearchResponse, type SearchEnvelope, type SessionEnvelope, type SessionListEnvelope, } from "./client";
 export { extractReferences, encodeResourceId, type RefCandidate, type ReferenceService, type ReferenceAction, } from "./extract";
 export { parseToolName, type ParsedToolName } from "./tool-name";
-export type { SessionInit, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, EventBatch, } from "./types";
+export { fetchIdToken, cloudRunIdTokenAuth } from "./id-token";
+export { EngramAdmin, createAdminClient, type AdminClientOptions, type CreateWorkspaceInput, type CreateWorkspaceResult, type Workspace as AdminWorkspace, type ApiKey as AdminApiKey, type IssuedKey as AdminIssuedKey, } from "./admin";
+export type { SessionInit, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, EventBatch, PersonInfo, PersonCreate, PersonUpdate, PersonMap, } from "./types";

package/dist/index.js

@@ -1,3 +1,5 @@
 export { Engram, EngramSession, } from "./client";
 export { extractReferences, encodeResourceId, } from "./extract";
 export { parseToolName } from "./tool-name";
+export { fetchIdToken, cloudRunIdTokenAuth } from "./id-token";
+export { EngramAdmin, createAdminClient, } from "./admin";

package/dist/types.d.ts

@@ -13,7 +13,18 @@ export interface SessionInit {
      * (e.g. `chat_ui`, `slack_dm`, `cron:dailyDigest`).
      */
     channel?: string;
+    /**
+     * Person ids that took part. The host (e.g. monet) is responsible for
+     * resolving platform identities (slack:U..., email:...) to person ids
+     * before calling startSession.
+     */
     participants?: string[];
+    /**
+     * Person ids that may view this session. Defaults to participants when
+     * omitted. engram-server unions this with participants to guarantee
+     * `participants ⊆ viewable_by`.
+     */
+    viewable_by?: string[];
 }
 export interface SessionAck {
     id: string;
@@ -29,7 +40,8 @@ export interface ParticipantEvent {
     type: "participant";
     seq: number;
     at: string;
-    identityRef: string;
+    /** Person id (resolved by the host). */
+    personId: string;
 }
 export interface TitleEvent {
     type: "title";
@@ -46,3 +58,27 @@ export type SessionEvent = StepEvent | ParticipantEvent | TitleEvent | EndEvent;
 export interface EventBatch {
     events: SessionEvent[];
 }
+/**
+ * Minimal representation engram-server returns for any person. Hosts cache
+ * `display_name` for UI rendering; richer profile attributes (role, team,
+ * etc.) are intentionally NOT here — those belong to HR / source-of-truth
+ * systems the host integrates with.
+ */
+export interface PersonInfo {
+    id: string;
+    display_name: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface PersonCreate {
+    display_name?: string;
+}
+export interface PersonUpdate {
+    display_name?: string | null;
+}
+/**
+ * Map of person_id → PersonInfo, deduped across whatever `Session`s the
+ * response contains. Returned at the envelope level so list responses
+ * don't repeat the same person info per row.
+ */
+export type PersonMap = Record<string, PersonInfo>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-sdk",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Host SDK for engram. Records agent session steps and ships them to an engram server.",
   "keywords": ["engram", "agents", "claude", "anthropic", "sdk", "observability"],
   "homepage": "https://github.com/hexis-ltd/engram#readme",
@@ -40,7 +40,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@hexis-ai/engram-core": "^0.1.2"
+    "@hexis-ai/engram-core": "^0.1.5"
   },
   "publishConfig": {
     "access": "public"