@hexis-ai/engram-sdk 0.5.0 → 0.7.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, SessionUpdate } from "./types";
 /**
  * Envelope returned by session endpoints. The persons map is deduped
  * across whatever sessions the response carries so display info isn't
@@ -111,6 +111,12 @@ export declare class Engram {
     getSessionEvents(id: string): Promise<{
         events: SessionEvent[];
     }>;
+    /**
+     * Patch session-level metadata (title / channel / status / summary /
+     * model / trigger_*). `undefined` fields are left alone; explicit
+     * `null` clears. Returns the materialized session post-update.
+     */
+    updateSession(id: string, patch: SessionUpdate): Promise<SessionEnvelope>;
     /** List recent sessions plus the deduped persons map across them. */
     listSessions(opts?: {
         limit?: number;
@@ -190,6 +196,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

@@ -49,6 +49,14 @@ export class Engram {
     async getSessionEvents(id) {
         return this.request("GET", `/v1/sessions/${encodeURIComponent(id)}/events`);
     }
+    /**
+     * Patch session-level metadata (title / channel / status / summary /
+     * model / trigger_*). `undefined` fields are left alone; explicit
+     * `null` clears. Returns the materialized session post-update.
+     */
+    async updateSession(id, patch) {
+        return this.request("PATCH", `/v1/sessions/${encodeURIComponent(id)}`, patch);
+    }
     /** List recent sessions plus the deduped persons map across them. */
     async listSessions(opts = {}) {
         const qs = new URLSearchParams();
@@ -199,6 +207,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, SessionUpdate, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, MessageContentBlock, MessageEvent, EventBatch, PersonInfo, PersonCreate, PersonUpdate, PersonMap, AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, } from "./types";

package/dist/types.d.ts

@@ -25,6 +25,30 @@ export interface SessionInit {
      * `participants ⊆ viewable_by`.
      */
     viewable_by?: string[];
+    /**
+     * Lifecycle state. `active` (default) → in progress; `idle` →
+     * inactive but resumable; `completed` → terminal. Pass at create time
+     * or update later with `updateSession`.
+     */
+    status?: "active" | "idle" | "completed";
+    /** LLM-generated summary of the session's outcome. */
+    summary?: string | null;
+    /** Model the host used for this session (e.g. `claude-opus-4-7`). */
+    model?: string | null;
+    /** Causal lineage — the conversation that triggered this one. */
+    trigger_conversation_id?: string | null;
+    /** Causal lineage — an external event (e.g. calendar event id). */
+    trigger_event_id?: string | null;
+}
+/** Patch for `updateSession`. */
+export interface SessionUpdate {
+    title?: string | null;
+    channel?: string | null;
+    status?: "active" | "idle" | "completed";
+    summary?: string | null;
+    model?: string | null;
+    trigger_conversation_id?: string | null;
+    trigger_event_id?: string | null;
 }
 export interface SessionAck {
     id: string;
@@ -54,27 +78,103 @@ 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[];
 }
 /**
- * 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.
+ * The canonical record for one person in a workspace. Now that engram
+ * is the host's primary memory store, this carries the organizational
+ * facts (role / team / source) too — not just the minimal display
+ * surface earlier versions exposed. Older fields stay, new fields are
+ * additive and optional so existing clients aren't disturbed.
  */
 export interface PersonInfo {
     id: string;
     display_name: string | null;
+    /** Free-form job title, e.g. "engineer", "designer". */
+    role?: string | null;
+    /** Free-form team name, e.g. "engineering", "design". */
+    team?: string | null;
+    /**
+     * How this row was authored. Mirrors monet's enum:
+     *   - `user_provided` — entered by a human via the UI.
+     *   - `auto` — synthesised by identity-resolver from an external
+     *     identity (slack profile, gcal attendee, …).
+     * Server-side defaults to `auto` when omitted.
+     */
+    source?: string;
     created_at: string;
     updated_at: string;
 }
 export interface PersonCreate {
     display_name?: string;
+    role?: string | null;
+    team?: string | null;
+    source?: string;
 }
 export interface PersonUpdate {
     display_name?: string | null;
+    role?: string | null;
+    team?: string | null;
+    source?: string;
 }
 /**
  * One alias (alternate name) for a person, mirrored from monet's
@@ -121,8 +221,16 @@ export interface IdentityInfo {
     source: string | null;
     is_primary: boolean | null;
     picture: string | null;
-    /** `YYYY-MM-DD`. */
+    /** ISO 8601 timestamp (post-migration 0004) or `YYYY-MM-DD` from
+     *  pre-migration rows. Treat as a parseable date string either way. */
     linked_at: string;
+    /**
+     * ISO 8601 timestamp of when the link was revoked. Null while the
+     * identity is active; non-null means callers should not treat it as
+     * an authoritative source for this person → external mapping.
+     * Available only after migration 0004.
+     */
+    unlinked_at?: string | null;
     created_at: string;
     updated_at: string;
 }
@@ -134,8 +242,14 @@ export interface IdentityUpsert {
     source?: string | null;
     is_primary?: boolean | null;
     picture?: string | null;
-    /** `YYYY-MM-DD`. */
+    /** ISO 8601 timestamp or `YYYY-MM-DD`. */
     linked_at: string;
+    /**
+     * Setting non-null marks the identity as revoked. Most upsert calls
+     * leave this undefined (no change); pass `null` to explicitly clear
+     * a previous revoke.
+     */
+    unlinked_at?: string | null;
 }
 /**
  * Map of person_id → PersonInfo, deduped across whatever `Session`s the

package/package.json

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