@hexis-ai/engram-sdk 0.4.0 → 0.6.0

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import type { ScoredSession, SearchOptions, Session, SessionStep } from "@hexis-ai/engram-core";
 import { type RefCandidate } from "./extract";
-import type { AliasInfo, AliasUpsert, EventBatch, PersonCreate, PersonInfo, PersonMap, PersonUpdate, SessionEvent, SessionInit } from "./types";
+import type { AliasInfo, AliasUpsert, EventBatch, IdentityInfo, IdentityUpsert, MessageContentBlock, PersonCreate, PersonInfo, PersonMap, PersonUpdate, SessionEvent, SessionInit } from "./types";
 /**
  * Envelope returned by session endpoints. The persons map is deduped
  * across whatever sessions the response carries so display info isn't
@@ -151,6 +151,20 @@ export declare class Engram {
         aliases: (id: string) => Promise<{
             aliases: AliasInfo[];
         }>;
+        /** This person's identities, newest-linked-first. */
+        identities: (id: string) => Promise<{
+            identities: IdentityInfo[];
+        }>;
+    };
+    /** Identity operations — resolve a global ref (`slack:U…`, `email:…`)
+     *  to its identity record + person id. */
+    readonly identities: {
+        /** Upsert by ref. Refs are reassignable — writing with a new
+         *  `person_id` reroutes the ref. Returns 404 if `person_id` is
+         *  unknown. */
+        upsert: (ref: string, input: IdentityUpsert) => Promise<IdentityInfo>;
+        /** Look up by ref. Returns 404 if the ref is unknown. */
+        get: (ref: string) => Promise<IdentityInfo>;
     };
     /** Internal: ship an event batch to the server. */
     sendBatch(sessionId: string, batch: EventBatch): Promise<void>;
@@ -176,6 +190,28 @@ export declare class EngramSession {
      *  resolved by the host (engram-server does not resolve platform identities). */
     addParticipant(personId: string): void;
     setTitle(title: string): void;
+    /**
+     * Append a turn to the session. `content` is an Anthropic-shaped
+     * block array — the same shape monet stores in
+     * `conversation_messages.trace`, with `text` + `tool_use` +
+     * `tool_result` blocks. Re-emitting with the same `message_id` is
+     * intentional: the host may want to refresh content (e.g. after
+     * summarisation rewrites the user-visible text).
+     */
+    recordMessage(input: {
+        role: string;
+        content: MessageContentBlock[];
+        message_id?: string;
+        model?: string;
+        tokens?: {
+            input: number;
+            output: number;
+        };
+        /** When omitted, the SDK stamps `at` to the wall-clock moment of
+         *  enqueue — appropriate for live agent emission. Pass an explicit
+         *  ISO string to mirror an existing host record's timestamp. */
+        at?: string;
+    }): void;
     /** Mark the session ended and flush buffered events. */
     end(): Promise<void>;
     /**

package/dist/client.js

@@ -104,6 +104,18 @@ export class Engram {
         upsertAlias: (id, name, input) => this.request("PUT", `/v1/persons/${encodeURIComponent(id)}/aliases/${encodeURIComponent(name)}`, input),
         /** This person's aliases, newest-used-first. */
         aliases: (id) => this.request("GET", `/v1/persons/${encodeURIComponent(id)}/aliases`),
+        /** This person's identities, newest-linked-first. */
+        identities: (id) => this.request("GET", `/v1/persons/${encodeURIComponent(id)}/identities`),
+    };
+    /** Identity operations — resolve a global ref (`slack:U…`, `email:…`)
+     *  to its identity record + person id. */
+    identities = {
+        /** Upsert by ref. Refs are reassignable — writing with a new
+         *  `person_id` reroutes the ref. Returns 404 if `person_id` is
+         *  unknown. */
+        upsert: (ref, input) => this.request("PUT", `/v1/identities/${encodeURIComponent(ref)}`, input),
+        /** Look up by ref. Returns 404 if the ref is unknown. */
+        get: (ref) => this.request("GET", `/v1/identities/${encodeURIComponent(ref)}`),
     };
     /** Internal: ship an event batch to the server. */
     async sendBatch(sessionId, batch) {
@@ -187,6 +199,27 @@ export class EngramSession {
         };
         this.enqueue(ev);
     }
+    /**
+     * Append a turn to the session. `content` is an Anthropic-shaped
+     * block array — the same shape monet stores in
+     * `conversation_messages.trace`, with `text` + `tool_use` +
+     * `tool_result` blocks. Re-emitting with the same `message_id` is
+     * intentional: the host may want to refresh content (e.g. after
+     * summarisation rewrites the user-visible text).
+     */
+    recordMessage(input) {
+        const ev = {
+            type: "message",
+            seq: this.seq++,
+            at: input.at ?? new Date().toISOString(),
+            role: input.role,
+            content: input.content,
+            ...(input.message_id !== undefined ? { message_id: input.message_id } : {}),
+            ...(input.model !== undefined ? { model: input.model } : {}),
+            ...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
+        };
+        this.enqueue(ev);
+    }
     /** Mark the session ended and flush buffered events. */
     async end() {
         if (this.ended)

package/dist/index.d.ts

@@ -3,4 +3,4 @@ export { extractReferences, encodeResourceId, type RefCandidate, type ReferenceS
 export { parseToolName, type ParsedToolName } from "./tool-name";
 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, AliasInfo, AliasUpsert, } from "./types";
+export type { SessionInit, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, MessageContentBlock, MessageEvent, EventBatch, PersonInfo, PersonCreate, PersonUpdate, PersonMap, AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, } from "./types";

package/dist/types.d.ts

@@ -54,7 +54,64 @@ export interface EndEvent {
     seq: number;
     at: string;
 }
-export type SessionEvent = StepEvent | ParticipantEvent | TitleEvent | EndEvent;
+/**
+ * One block within a message's content. Modelled after Anthropic's
+ * Messages API content blocks so SDK callers can pass agent runtime
+ * output through with zero translation. The discriminated union covers
+ * the standard block types; unknown `type` values pass through
+ * untouched so future Anthropic / vendor blocks don't require an SDK
+ * upgrade to ingest.
+ */
+export type MessageContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: unknown;
+    is_error?: boolean;
+} | {
+    type: "thinking";
+    thinking: string;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+/**
+ * One turn in a session — the canonical record of what someone or the
+ * agent actually said/did. Carries the full Anthropic-shaped content
+ * (text + tool_use + tool_result + thinking + …) so engram is lossless
+ * relative to monet's PG transcript.
+ *
+ * `role` is intentionally `string` rather than `user|assistant` because
+ * monet-style channel-originated turns use richer role labels (`system`,
+ * `resume`, identity refs like `slack:U…`). Tighten to a union on the
+ * read side if a consumer needs it; the wire stays permissive.
+ */
+export interface MessageEvent {
+    type: "message";
+    seq: number;
+    at: string;
+    /** Stable host-side id (monet's `conversation_messages` row id). The
+     *  same logical message can be re-emitted idempotently if the host
+     *  needs to update content (e.g. summarisation rewrite). */
+    message_id?: string;
+    role: string;
+    content: MessageContentBlock[];
+    /** Model + usage metadata captured at write time. Optional because
+     *  inbound channel messages (slack, calendar) don't have these. */
+    model?: string;
+    tokens?: {
+        input: number;
+        output: number;
+    };
+}
+export type SessionEvent = StepEvent | ParticipantEvent | TitleEvent | EndEvent | MessageEvent;
 export interface EventBatch {
     events: SessionEvent[];
 }
@@ -105,6 +162,38 @@ export interface AliasUpsert {
      */
     increment?: boolean;
 }
+/**
+ * One external identity mapped to an engram person. Hosts (monet) use
+ * the same ref convention they always have — `slack:U12345`,
+ * `email:foo@bar.com`, `google:1234567890` — so engram can serve as
+ * the resolver for any system that already speaks that vocabulary.
+ */
+export interface IdentityInfo {
+    /** Stable global handle, e.g. `slack:U12345`. */
+    ref: string;
+    person_id: string;
+    service: string;
+    external_id: string;
+    display_name: string | null;
+    source: string | null;
+    is_primary: boolean | null;
+    picture: string | null;
+    /** `YYYY-MM-DD`. */
+    linked_at: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface IdentityUpsert {
+    person_id: string;
+    service: string;
+    external_id: string;
+    display_name?: string | null;
+    source?: string | null;
+    is_primary?: boolean | null;
+    picture?: string | null;
+    /** `YYYY-MM-DD`. */
+    linked_at: string;
+}
 /**
  * Map of person_id → PersonInfo, deduped across whatever `Session`s the
  * response contains. Returned at the envelope level so list responses

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Host SDK for engram. Records agent session steps and ships them to an engram server.",
   "keywords": [
     "engram",