@hexis-ai/engram-sdk 0.10.0 → 0.11.0

package/dist/buffered.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Buffered / fire-and-forget telemetry layer for `Engram`.
+ *
+ * Modelled after the Langfuse SDK ergonomics so existing observability
+ * code translates one-for-one:
+ *
+ *   import { Engram } from "@hexis-ai/engram-sdk";
+ *   const engram = new Engram({ baseUrl, apiKey, flushIntervalMs: 5000 });
+ *
+ *   engram.session({ id: convId, channel: "slack_dm" });
+ *   engram.message({ sessionId: convId, role: "user", content: "hi" });
+ *   engram.message({ sessionId: convId, role: "assistant", content: out, model });
+ *   engram.event({ sessionId: convId, type: "title", title: "Trip planning" });
+ *
+ *   await engram.flush();   // process exit
+ *   await engram.shutdown();
+ *
+ * Guarantees:
+ *   - Every method returns synchronously (no `await` required at the call site).
+ *   - Errors are surfaced via the `onError` hook configured on the Engram
+ *     client; nothing throws to the caller.
+ *   - The first message() for a session implicitly waits for the
+ *     corresponding POST /v1/sessions to complete (per-session ready
+ *     promise), so the host doesn't need to await session() before
+ *     starting to record events.
+ *   - When `baseUrl` is unset on the parent Engram, the buffer is a
+ *     no-op (the Engram constructor would have thrown earlier, so this
+ *     is enforced upstream; here we just document the intent).
+ */
+import type { Engram } from "./client";
+import type { MessageContentBlock, SessionEvent, SessionInit } from "./types";
+export interface TelemetrySession extends Omit<SessionInit, "id"> {
+    /** Host-supplied session id. Required for telemetry mode. */
+    id: string;
+}
+export interface TelemetryMessage {
+    sessionId: string;
+    role: string;
+    /** Plain string is wrapped into a single `text` block; arrays pass through. */
+    content: string | MessageContentBlock[];
+    at?: string;
+    model?: string;
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    /** Stable host-side id (mirrors engram's MessageEvent.message_id). */
+    message_id?: string;
+}
+export type TelemetryEvent = {
+    sessionId: string;
+    type: "participant";
+    personId: string;
+    at?: string;
+} | {
+    sessionId: string;
+    type: "title";
+    title: string;
+    at?: string;
+} | {
+    sessionId: string;
+    type: "step";
+    tool: string;
+    input?: Record<string, unknown>;
+    result?: unknown;
+    resources?: string[];
+    at?: string;
+} | {
+    sessionId: string;
+    type: "end";
+    at?: string;
+};
+/**
+ * Internal coordinator that owns per-session buffers and gates flushes
+ * on session-creation acks. Exposed on the parent Engram via
+ * `engram.session() / .message() / .event() / .flush() / .shutdown()`.
+ */
+export declare class BufferedTelemetry {
+    private readonly engram;
+    private readonly handles;
+    constructor(engram: Engram);
+    /**
+     * Observe a new (or already-known) session. Idempotent for the same
+     * id — subsequent calls with new metadata are folded into an
+     * updateSession() rather than re-creating.
+     */
+    session(input: TelemetrySession): void;
+    /**
+     * Observe a message turn. Lazily creates a session handle if none
+     * exists yet — but without a prior `session({id, ...})` call the
+     * subsequent flush will fail (engram-server returns 404) and the
+     * error surfaces via onError. Pass session() first.
+     */
+    message(input: TelemetryMessage): void;
+    /** Observe an arbitrary session event (participant / title / step / end). */
+    event(input: TelemetryEvent): void;
+    /**
+     * Drain every per-session buffer in parallel. Safe to call at any
+     * point; failures route to onError, never thrown.
+     */
+    flush(): Promise<void>;
+    /**
+     * Final flush + stop timers. After shutdown the buffer is closed and
+     * further telemetry calls drop with onError.
+     */
+    shutdown(): Promise<void>;
+    /** Test helper. Drops all in-memory state without flushing. */
+    resetForTests(): void;
+}
+export type { SessionEvent };

package/dist/buffered.js

@@ -0,0 +1,228 @@
+/**
+ * Buffered / fire-and-forget telemetry layer for `Engram`.
+ *
+ * Modelled after the Langfuse SDK ergonomics so existing observability
+ * code translates one-for-one:
+ *
+ *   import { Engram } from "@hexis-ai/engram-sdk";
+ *   const engram = new Engram({ baseUrl, apiKey, flushIntervalMs: 5000 });
+ *
+ *   engram.session({ id: convId, channel: "slack_dm" });
+ *   engram.message({ sessionId: convId, role: "user", content: "hi" });
+ *   engram.message({ sessionId: convId, role: "assistant", content: out, model });
+ *   engram.event({ sessionId: convId, type: "title", title: "Trip planning" });
+ *
+ *   await engram.flush();   // process exit
+ *   await engram.shutdown();
+ *
+ * Guarantees:
+ *   - Every method returns synchronously (no `await` required at the call site).
+ *   - Errors are surfaced via the `onError` hook configured on the Engram
+ *     client; nothing throws to the caller.
+ *   - The first message() for a session implicitly waits for the
+ *     corresponding POST /v1/sessions to complete (per-session ready
+ *     promise), so the host doesn't need to await session() before
+ *     starting to record events.
+ *   - When `baseUrl` is unset on the parent Engram, the buffer is a
+ *     no-op (the Engram constructor would have thrown earlier, so this
+ *     is enforced upstream; here we just document the intent).
+ */
+import { EngramSession } from "./client";
+// --- BufferedTelemetry ---------------------------------------------------
+/**
+ * Internal coordinator that owns per-session buffers and gates flushes
+ * on session-creation acks. Exposed on the parent Engram via
+ * `engram.session() / .message() / .event() / .flush() / .shutdown()`.
+ */
+export class BufferedTelemetry {
+    engram;
+    handles = new Map();
+    constructor(engram) {
+        this.engram = engram;
+    }
+    /**
+     * Observe a new (or already-known) session. Idempotent for the same
+     * id — subsequent calls with new metadata are folded into an
+     * updateSession() rather than re-creating.
+     */
+    session(input) {
+        const existing = this.handles.get(input.id);
+        if (existing) {
+            existing.update(input);
+            return;
+        }
+        this.handles.set(input.id, new BufferedSession(this.engram, input));
+    }
+    /**
+     * Observe a message turn. Lazily creates a session handle if none
+     * exists yet — but without a prior `session({id, ...})` call the
+     * subsequent flush will fail (engram-server returns 404) and the
+     * error surfaces via onError. Pass session() first.
+     */
+    message(input) {
+        const handle = this.handles.get(input.sessionId);
+        if (!handle) {
+            this.engram.config.onError(new Error(`engram telemetry: message() for unknown session ${input.sessionId}; call session({id}) first`));
+            return;
+        }
+        handle.message(input);
+    }
+    /** Observe an arbitrary session event (participant / title / step / end). */
+    event(input) {
+        const handle = this.handles.get(input.sessionId);
+        if (!handle) {
+            this.engram.config.onError(new Error(`engram telemetry: event() for unknown session ${input.sessionId}; call session({id}) first`));
+            return;
+        }
+        handle.event(input);
+    }
+    /**
+     * Drain every per-session buffer in parallel. Safe to call at any
+     * point; failures route to onError, never thrown.
+     */
+    async flush() {
+        await Promise.all([...this.handles.values()].map((h) => h.flush().catch((e) => this.engram.config.onError(e))));
+    }
+    /**
+     * Final flush + stop timers. After shutdown the buffer is closed and
+     * further telemetry calls drop with onError.
+     */
+    async shutdown() {
+        const all = [...this.handles.values()];
+        this.handles.clear();
+        await Promise.all(all.map((h) => h.shutdown().catch((e) => this.engram.config.onError(e))));
+    }
+    /** Test helper. Drops all in-memory state without flushing. */
+    resetForTests() {
+        this.handles.clear();
+    }
+}
+// --- Per-session buffer --------------------------------------------------
+/**
+ * One BufferedSession per session id. Wraps the existing EngramSession
+ * (which already implements batched flush + retry) and gates the first
+ * flush on the session's create ack.
+ */
+class BufferedSession {
+    engram;
+    id;
+    ready;
+    inner;
+    ended = false;
+    constructor(engram, init) {
+        this.engram = engram;
+        this.id = init.id;
+        this.inner = new EngramSession(engram, init.id);
+        // Fire-and-forget POST /v1/sessions. The ready promise is awaited
+        // before the first flush so messages enqueued before the create
+        // ack don't race.
+        this.ready = engram
+            .startSessionWithoutHandle(init)
+            .catch((e) => {
+            engram.config.onError(e);
+            throw e;
+        });
+    }
+    message(input) {
+        try {
+            this.inner.recordMessage({
+                role: input.role,
+                content: normalizeContent(input.content),
+                ...(input.at !== undefined ? { at: input.at } : {}),
+                ...(input.model !== undefined ? { model: input.model } : {}),
+                ...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
+                ...(input.message_id !== undefined ? { message_id: input.message_id } : {}),
+            });
+        }
+        catch (e) {
+            this.engram.config.onError(e);
+        }
+    }
+    event(input) {
+        try {
+            switch (input.type) {
+                case "participant":
+                    this.inner.addParticipant(input.personId);
+                    break;
+                case "title":
+                    this.inner.setTitle(input.title);
+                    break;
+                case "step":
+                    this.inner.recordStep({
+                        tool: input.tool,
+                        ...(input.resources !== undefined ? { resources: input.resources } : {}),
+                        ...(input.input !== undefined ? { input: input.input } : {}),
+                        ...(input.result !== undefined ? { result: input.result } : {}),
+                    });
+                    break;
+                case "end":
+                    void this.shutdown().catch((e) => this.engram.config.onError(e));
+                    break;
+            }
+        }
+        catch (e) {
+            this.engram.config.onError(e);
+        }
+    }
+    /**
+     * Merge updated session metadata via the patch endpoint. Fire-and-
+     * forget. Useful when a session was observed earlier with partial
+     * info and the host now has more (e.g. resolved channel later).
+     */
+    update(input) {
+        // Only patch the fields callers might actually mutate post-creation;
+        // skip `participants` / `viewable_by` which are append-only via
+        // participant events.
+        const patch = {};
+        if (input.title !== undefined)
+            patch.title = input.title;
+        if (input.channel !== undefined)
+            patch.channel = input.channel;
+        if (input.status !== undefined)
+            patch.status = input.status;
+        if (input.summary !== undefined)
+            patch.summary = input.summary;
+        if (input.model !== undefined)
+            patch.model = input.model;
+        if (input.trigger_conversation_id !== undefined)
+            patch.trigger_conversation_id = input.trigger_conversation_id;
+        if (input.trigger_event_id !== undefined)
+            patch.trigger_event_id = input.trigger_event_id;
+        if (Object.keys(patch).length === 0)
+            return;
+        void this.ready
+            .then(() => this.engram.updateSession(this.id, patch))
+            .catch((e) => this.engram.config.onError(e));
+    }
+    async flush() {
+        // Don't fail downstream flushes if the create eventually succeeds
+        // after a retry — but skip flushing if the create has permanently
+        // failed (ready rejected).
+        try {
+            await this.ready;
+        }
+        catch {
+            return;
+        }
+        await this.inner.flush();
+    }
+    async shutdown() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        try {
+            await this.ready;
+        }
+        catch {
+            return;
+        }
+        await this.inner.end();
+    }
+}
+// --- Helpers --------------------------------------------------------------
+function normalizeContent(content) {
+    if (typeof content === "string") {
+        return content.length > 0 ? [{ type: "text", text: content }] : [];
+    }
+    return content;
+}

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import type { ScoredSession, SearchOptions, Session, SessionStep } from "@hexis-ai/engram-core";
 import { type RefCandidate } from "./extract";
 import type { AliasInfo, AliasUpsert, EventBatch, IdentityInfo, IdentityUpsert, MessageContentBlock, PersonCreate, PersonInfo, PersonMap, PersonUpdate, SessionEvent, SessionInit, SessionUpdate } from "./types";
+import { type TelemetryEvent, type TelemetryMessage, type TelemetrySession } from "./buffered";
 /**
  * Envelope returned by session endpoints. The persons map is deduped
  * across whatever sessions the response carries so display info isn't
@@ -93,13 +94,48 @@ export declare class Engram {
     private readonly authHeaders?;
     readonly maxRetries: number;
     readonly retryBackoffMs: number;
+    private telemetry;
     constructor(opts: EngramOptions);
+    /**
+     * Langfuse-style fire-and-forget telemetry surface. Lazily initialised
+     * so apps that never observe (search-only consumers) pay no overhead.
+     */
+    private get bufferedTelemetry();
+    /**
+     * Observe a new (or already-known) session. Idempotent for the same id.
+     * Fire-and-forget — returns synchronously, transport failures route
+     * to `onError`.
+     */
+    session(input: TelemetrySession): void;
+    /**
+     * Observe a message turn against an existing session. Call
+     * `session({id})` first so the create ack is queued.
+     */
+    message(input: TelemetryMessage): void;
+    /**
+     * Observe an arbitrary session event (participant added, title set,
+     * tool step, end). Same fire-and-forget contract.
+     */
+    event(input: TelemetryEvent): void;
+    /**
+     * Drain every per-session buffer. Call before short-lived processes
+     * exit; long-lived servers can rely on auto-flush (flushIntervalMs).
+     */
+    flush(): Promise<void>;
+    /** Final flush + stop. Use at process exit. */
+    shutdown(): Promise<void>;
     /** 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>;
+    /**
+     * POST /v1/sessions without constructing a handle. Used by
+     * BufferedTelemetry, which manages its own per-session handles and
+     * just needs the create ack.
+     */
+    startSessionWithoutHandle(init: SessionInit): Promise<void>;
     /** Fetch a single session by id, plus the persons map for its participants/viewers. */
     getSession(id: string): Promise<SessionEnvelope>;
     /**

package/dist/client.js

@@ -1,5 +1,6 @@
 import { encodeResourceId, extractReferences } from "./extract";
 import { parseToolName } from "./tool-name";
+import { BufferedTelemetry, } from "./buffered";
 export class Engram {
     apiKey;
     baseUrl;
@@ -11,6 +12,7 @@ export class Engram {
     authHeaders;
     maxRetries;
     retryBackoffMs;
+    telemetry = null;
     constructor(opts) {
         if (!opts.apiKey)
             throw new Error("Engram: apiKey is required");
@@ -27,6 +29,53 @@ export class Engram {
         this.maxRetries = opts.maxRetries ?? 4;
         this.retryBackoffMs = opts.retryBackoffMs ?? 500;
     }
+    /**
+     * Langfuse-style fire-and-forget telemetry surface. Lazily initialised
+     * so apps that never observe (search-only consumers) pay no overhead.
+     */
+    get bufferedTelemetry() {
+        if (!this.telemetry)
+            this.telemetry = new BufferedTelemetry(this);
+        return this.telemetry;
+    }
+    /**
+     * Observe a new (or already-known) session. Idempotent for the same id.
+     * Fire-and-forget — returns synchronously, transport failures route
+     * to `onError`.
+     */
+    session(input) {
+        this.bufferedTelemetry.session(input);
+    }
+    /**
+     * Observe a message turn against an existing session. Call
+     * `session({id})` first so the create ack is queued.
+     */
+    message(input) {
+        this.bufferedTelemetry.message(input);
+    }
+    /**
+     * Observe an arbitrary session event (participant added, title set,
+     * tool step, end). Same fire-and-forget contract.
+     */
+    event(input) {
+        this.bufferedTelemetry.event(input);
+    }
+    /**
+     * Drain every per-session buffer. Call before short-lived processes
+     * exit; long-lived servers can rely on auto-flush (flushIntervalMs).
+     */
+    async flush() {
+        if (!this.telemetry)
+            return;
+        await this.telemetry.flush();
+    }
+    /** Final flush + stop. Use at process exit. */
+    async shutdown() {
+        if (!this.telemetry)
+            return;
+        await this.telemetry.shutdown();
+        this.telemetry = null;
+    }
     /** Probe identity — returns the workspace the configured key resolves to. */
     async me() {
         return this.request("GET", "/v1/me");
@@ -36,6 +85,14 @@ export class Engram {
         const ack = await this.request("POST", "/v1/sessions", init);
         return new EngramSession(this, ack.id);
     }
+    /**
+     * POST /v1/sessions without constructing a handle. Used by
+     * BufferedTelemetry, which manages its own per-session handles and
+     * just needs the create ack.
+     */
+    async startSessionWithoutHandle(init) {
+        await this.request("POST", "/v1/sessions", init);
+    }
     /** 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)}`);

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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 { BufferedTelemetry, type TelemetrySession, type TelemetryMessage, type TelemetryEvent, } from "./buffered";
 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, SessionUpdate, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, MessageContentBlock, MessageEvent, EventBatch, PersonInfo, PersonCreate, PersonUpdate, PersonMap, AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, } from "./types";

package/dist/index.js

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

package/package.json

@@ -1,27 +1,16 @@
 {
   "name": "@hexis-ai/engram-sdk",
-  "version": "0.10.0",
-  "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",
+  "version": "0.11.0",
+  "author": "hexis ltd.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/hexis-ltd/engram.git",
     "directory": "packages/sdk"
   },
-  "bugs": "https://github.com/hexis-ltd/engram/issues",
-  "author": "hexis ltd.",
-  "license": "MIT",
-  "type": "module",
   "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@hexis-ai/engram-core": "^0.2.0"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -36,19 +25,30 @@
       "default": "./dist/tool-name.js"
     }
   },
+  "bugs": "https://github.com/hexis-ltd/engram/issues",
+  "description": "Host SDK for engram. Records agent session steps and ships them to an engram server.",
   "files": [
     "dist"
   ],
+  "homepage": "https://github.com/hexis-ltd/engram#readme",
+  "keywords": [
+    "engram",
+    "agents",
+    "claude",
+    "anthropic",
+    "sdk",
+    "observability"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "pack": "bun run build && bun pm pack",
     "test": "bun test",
     "type-check": "tsc --noEmit"
   },
-  "dependencies": {
-    "@hexis-ai/engram-core": "^0.2.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
+  "type": "module",
+  "types": "dist/index.d.ts"
 }