@hexis-ai/engram-sdk 0.5.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, IdentityInfo, IdentityUpsert, 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
@@ -190,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

@@ -199,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, IdentityInfo, IdentityUpsert, } 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[];
 }

package/package.json

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