@hexis-ai/engram-sdk 0.1.2 → 0.1.4

package/dist/client.d.ts

@@ -16,6 +16,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;
@@ -54,6 +73,10 @@ 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);
     /** Begin a new session. Returns a handle for buffering events. */
     startSession(init?: SessionInit): Promise<EngramSession>;
@@ -90,7 +113,12 @@ export declare class EngramSession {
     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,6 +22,10 @@ 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;
     }
     /** Begin a new session. Returns a handle for buffering events. */
     async startSession(init = {}) {
@@ -53,12 +61,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) {
@@ -128,7 +142,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 +158,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,5 @@
 export { Engram, EngramSession, type EngramOptions, type RecordStepInput, type SearchRequest, type SearchResponse, } from "./client";
 export { extractReferences, encodeResourceId, type RefCandidate, type ReferenceService, type ReferenceAction, } from "./extract";
 export { parseToolName, type ParsedToolName } from "./tool-name";
+export { fetchIdToken, cloudRunIdTokenAuth } from "./id-token";
 export type { SessionInit, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, EventBatch, } from "./types";

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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.4"
   },
   "publishConfig": {
     "access": "public"