@maximem/synap-js-sdk 0.4.0 → 0.4.1

package/dist/index.js

@@ -32,7 +32,7 @@ import {
   isRecallQuery,
   stem,
   tokenize
-} from "./chunk-TCEP5OVR.js";
+} from "./chunk-6LDUDKHS.js";
 import {
   getEnv
 } from "./chunk-QBCVMPGK.js";
@@ -525,10 +525,19 @@ function buildFetchRequest(scope, options) {
   }
   return { endpoint: ENDPOINT_BY_SCOPE[scope], body };
 }
-async function fetchContext(transport, scope, options = {}) {
+async function fetchContext(transport, scope, options = {}, hooks = {}) {
+  const startedAt = Date.now();
+  const anticipated = hooks.beforeFetch?.(scope, options) ?? null;
+  if (anticipated !== null) {
+    hooks.onServedFromCache?.(scope, options, anticipated);
+    hooks.onAssembled?.(scope, options, anticipated.response, startedAt);
+    return anticipated.response;
+  }
   const { endpoint, body } = buildFetchRequest(scope, options);
   const result = await transport.request(endpoint, { body });
-  return result?.["context"] ?? {};
+  const response = result?.["context"] ?? {};
+  hooks.onAssembled?.(scope, options, response, startedAt);
+  return response;
 }
 
 // src/context/normalize.ts
@@ -1031,6 +1040,8 @@ var CompactionSubscribers = class {
   }
 };
 function createConversationNamespace(transport, subscribers = new CompactionSubscribers(), onWrite = () => {
+}, onTurn = () => {
+}, onFetched = () => {
 }) {
   const convId = (v) => {
     const id = typeof v === "string" ? v : v.conversation_id ?? v.conversationId;
@@ -1042,6 +1053,12 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
     async record_message(options) {
       const body = buildRecordMessageBody(options);
       const result = await transport.request("conversations_messages", { body });
+      onTurn({
+        conversationId: String(body["conversation_id"] ?? ""),
+        role: String(body["role"] ?? "user"),
+        content: String(body["content"] ?? ""),
+        timestamp: body["timestamp"]
+      });
       onWrite({
         userId: body["user_id"],
         customerId: body["customer_id"]
@@ -1056,6 +1073,14 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
       const result = await transport.request("conversations_messages_batch", {
         body: { messages: bodies }
       });
+      for (const body of bodies) {
+        onTurn({
+          conversationId: String(body["conversation_id"] ?? ""),
+          role: String(body["role"] ?? "user"),
+          content: String(body["content"] ?? ""),
+          timestamp: body["timestamp"]
+        });
+      }
       for (const body of bodies) {
         onWrite({
           userId: body["user_id"],
@@ -1075,10 +1100,15 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
     },
     context: {
       async fetch(options = {}) {
-        validateConversationId(
-          options.conversation_id ?? options.conversationId
+        const id = options.conversation_id ?? options.conversationId;
+        validateConversationId(id);
+        const response = await fetchContext(transport, "conversation", options);
+        onFetched(
+          response,
+          id,
+          options.user_id ?? options.userId
         );
-        return fetchContext(transport, "conversation", options);
+        return response;
       },
       get_context_for_prompt: async (options = {}) => {
         const id = convId(options);
@@ -1134,7 +1164,7 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
 }
 
 // src/user/interface.ts
-function createUserNamespace(transport) {
+function createUserNamespace(transport, hooks = {}) {
   return {
     async get_profile(options) {
       const userId = typeof options === "string" ? options : options.user_id ?? options.userId;
@@ -1148,7 +1178,7 @@ function createUserNamespace(transport) {
       });
     },
     context: { async fetch(options = {}) {
-      return fetchContext(transport, "user", options);
+      return fetchContext(transport, "user", options, hooks);
     } }
   };
 }
@@ -1212,13 +1242,24 @@ function envTls() {
   if (raw === void 0 || raw === "") return void 0;
   return !["0", "false", "no", "off"].includes(raw.trim().toLowerCase());
 }
-function createInstanceNamespace(credentials, cache) {
+function createInstanceNamespace(credentials, cache, onTurn) {
   let client = null;
   let dispatchCompaction = null;
+  let applyCompaction = null;
   const internals = {
     onCompactionUpdate(conversationId, bundle) {
+      applyCompaction?.(bundle);
       dispatchCompaction?.(conversationId, bundle);
     },
+    setCompactionApplier(apply) {
+      applyCompaction = apply;
+    },
+    sendContextUsed(event) {
+      client?.sendContextUsed(event);
+    },
+    sendContextAssembled(event) {
+      client?.sendContextAssembled(event);
+    },
     setCompactionDispatcher(dispatch) {
       dispatchCompaction = dispatch;
     },
@@ -1275,6 +1316,12 @@ function createInstanceNamespace(credentials, cache) {
       if (options.content === void 0) {
         throw new ListeningNotActiveError("content is required");
       }
+      const conversationId = options.conversation_id ?? options.conversationId ?? "";
+      onTurn?.({
+        conversationId,
+        role: options.role ?? "user",
+        content: options.content
+      });
       client.sendConversationEvent({
         event_type: options.event_type ?? options.eventType ?? "user_message",
         content: options.content,
@@ -1315,6 +1362,403 @@ function createInstanceNamespace(credentials, cache) {
 // src/version.ts
 var SDK_VERSION = "1.0.0-beta.0";
 
+// src/registry.ts
+var instances = /* @__PURE__ */ new Map();
+function buildRegistryKey(instanceId, apiKey) {
+  if (instanceId) return instanceId;
+  const key = apiKey ?? "";
+  if (!key) return "";
+  return `apikey:${digest(key)}`;
+}
+function digest(value) {
+  const PRIME = 1099511628211n;
+  const MASK = 0xffffffffffffffffn;
+  let hash = 14695981039346656037n;
+  for (let i = 0; i < value.length; i += 1) {
+    hash ^= BigInt(value.charCodeAt(i));
+    hash = hash * PRIME & MASK;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+function get(key) {
+  return instances.get(key);
+}
+function registerIfAbsent(key, client) {
+  const existing = instances.get(key);
+  if (existing !== void 0) return existing;
+  instances.set(key, client);
+  return void 0;
+}
+function aliasIfAbsent(key, client) {
+  if (!key || instances.has(key)) return false;
+  instances.set(key, client);
+  return true;
+}
+function unregisterIfOwner(key, client) {
+  if (instances.get(key) === client) instances.delete(key);
+}
+
+// src/cache/short-term-store.ts
+var DEFAULT_MAX_CONVERSATIONS = 100;
+var DEFAULT_MAX_AGE_MS = 12 * 60 * 60 * 1e3;
+function parseIso(value) {
+  if (value === null || value === void 0 || value === "") return null;
+  if (value instanceof Date) return value.getTime();
+  if (typeof value !== "string") return null;
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+function isAfter(turnTimestamp, cutoffMs) {
+  const parsed = parseIso(turnTimestamp);
+  if (parsed === null) return true;
+  return parsed > cutoffMs;
+}
+var ShortTermStore = class {
+  // Insertion order IS the LRU order: re-inserting on touch moves an entry to
+  // the end, so the first key Map yields is the least recently used.
+  #entries = /* @__PURE__ */ new Map();
+  #maxConversations;
+  #maxAgeMs;
+  #now;
+  constructor(options = {}) {
+    this.#maxConversations = options.maxConversations ?? DEFAULT_MAX_CONVERSATIONS;
+    this.#maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    this.#now = options.now ?? (() => Date.now());
+  }
+  /** The entry, or null. Age-evicts on read, as Python does. */
+  get(conversationId) {
+    if (!conversationId) return null;
+    const entry = this.#entries.get(conversationId);
+    if (entry === void 0) return null;
+    if (this.#now() - entry.lastActivityAt > this.#maxAgeMs) {
+      this.#entries.delete(conversationId);
+      return null;
+    }
+    this.#touch(conversationId, entry);
+    return entry;
+  }
+  has(conversationId) {
+    return this.get(conversationId) !== null;
+  }
+  get size() {
+    return this.#entries.size;
+  }
+  /**
+   * Append a raw turn.
+   *
+   * Called from `record_message` and the stream's `send_message`. When no entry
+   * exists yet (the first turn, before any compaction has arrived) a fresh one
+   * is created with an empty summary; the next `compaction_update` fills the
+   * summary fields in and prunes the turns it covers.
+   */
+  appendTurn(conversationId, role, content, timestamp) {
+    if (!conversationId) return;
+    const stamp = timestamp ?? new Date(this.#now()).toISOString();
+    const entry = this.#entries.get(conversationId) ?? this.#blank(conversationId);
+    entry.recentTurns.push({ role, content, timestamp: stamp });
+    entry.lastActivityAt = parseIso(stamp) ?? this.#now();
+    this.#touch(conversationId, entry);
+    this.#evict();
+  }
+  /**
+   * Apply a `compaction_update` bundle.
+   *
+   * Replaces the summary fields from the bundle's `conversation_context` and
+   * prunes locally buffered turns at or before its `end_timestamp`. Turns that
+   * arrived DURING the compaction window are kept by design: the server has not
+   * seen them yet, which is the whole reason the local tail exists.
+   */
+  applyCompaction(bundle) {
+    if (typeof bundle !== "object" || bundle === null) return;
+    const cc = bundle["conversation_context"] ?? {};
+    const conversationId = String(
+      cc["conversation_id"] ?? bundle["anticipation_conversation_id"] ?? bundle["conversation_id"] ?? ""
+    );
+    if (!conversationId) return;
+    const endTs = parseIso(cc["end_timestamp"] ?? cc["compacted_at"]);
+    const entry = this.#entries.get(conversationId) ?? this.#blank(conversationId);
+    entry.summary = cc["summary"] || entry.summary;
+    entry.factualParagraph = cc["factual_paragraph"] || entry.factualParagraph;
+    entry.conversationalParagraph = cc["conversational_paragraph"] || entry.conversationalParagraph;
+    entry.currentState = { ...cc["current_state"] ?? {} };
+    entry.keyExtractions = { ...cc["key_extractions"] ?? {} };
+    entry.compactionId = cc["compaction_id"] || entry.compactionId;
+    entry.compactedAt = cc["compacted_at"] || entry.compactedAt;
+    entry.endTimestamp = cc["end_timestamp"] || entry.endTimestamp;
+    if (endTs !== null && entry.recentTurns.length > 0) {
+      entry.recentTurns = entry.recentTurns.filter((t) => isAfter(t.timestamp, endTs));
+    }
+    entry.lastActivityAt = this.#now();
+    this.#touch(conversationId, entry);
+    this.#evict();
+  }
+  invalidate(conversationId) {
+    this.#entries.delete(conversationId);
+  }
+  clear() {
+    this.#entries.clear();
+  }
+  #blank(conversationId) {
+    return {
+      conversationId,
+      summary: null,
+      factualParagraph: null,
+      conversationalParagraph: null,
+      currentState: {},
+      keyExtractions: {},
+      compactionId: null,
+      compactedAt: null,
+      endTimestamp: null,
+      recentTurns: [],
+      lastActivityAt: this.#now()
+    };
+  }
+  /** Re-insert so this key becomes the most recently used. */
+  #touch(conversationId, entry) {
+    this.#entries.delete(conversationId);
+    this.#entries.set(conversationId, entry);
+  }
+  #evict() {
+    while (this.#entries.size > this.#maxConversations) {
+      const oldest = this.#entries.keys().next();
+      if (oldest.done === true) break;
+      this.#entries.delete(oldest.value);
+    }
+  }
+};
+
+// src/context/overlay.ts
+var MAX_TURNS = 20;
+var TOKEN_BUDGET = 2e3;
+function verbatimOverlayEnabled() {
+  const raw = (getEnv("SYNAP_ST_VERBATIM_OVERLAY") ?? "").trim().toLowerCase();
+  if (["0", "false", "no", "off"].includes(raw)) return false;
+  if (["1", "true", "yes", "on"].includes(raw)) return true;
+  return true;
+}
+function estimateTokens(turn) {
+  return Math.max(1, Math.floor(String(turn.content ?? "").length / 4));
+}
+function budgetRecentTurns(turns) {
+  const windowed = turns.slice(-MAX_TURNS);
+  let total = windowed.reduce((n2, t) => n2 + estimateTokens(t), 0);
+  while (windowed.length > 0 && total > TOKEN_BUDGET) {
+    const dropped = windowed.shift();
+    total -= estimateTokens(dropped);
+  }
+  return windowed;
+}
+function overlayLocalRecentTurns(response, store, conversationId) {
+  if (conversationId === void 0 || conversationId === "") return;
+  try {
+    const entry = store.get(conversationId);
+    if (entry === null) return;
+    const existing = response.conversation_context ?? null;
+    if (existing !== null && !verbatimOverlayEnabled()) return;
+    const localTurns = budgetRecentTurns(entry.recentTurns);
+    const serverField = (name) => existing === null ? void 0 : existing[name];
+    const orLocal = (name, local) => {
+      const value = serverField(name);
+      if (value === void 0 || value === null || value === "") return local;
+      if (typeof value === "object" && Object.keys(value).length === 0) return local;
+      return value;
+    };
+    response.conversation_context = {
+      summary: orLocal("summary", entry.summary),
+      current_state: orLocal("current_state", { ...entry.currentState }),
+      key_extractions: orLocal("key_extractions", { ...entry.keyExtractions }),
+      recent_turns: localTurns,
+      compaction_id: orLocal("compaction_id", entry.compactionId),
+      compacted_at: orLocal("compacted_at", entry.compactedAt),
+      conversation_id: conversationId
+    };
+  } catch {
+  }
+}
+
+// src/context/user-summary.ts
+var USER_SUMMARY_INTERVAL = 5;
+var MAX_SUMMARY_ITEMS = 3;
+var COLLECTIONS = ["facts", "preferences", "episodes", "emotions", "temporal_events"];
+var TurnCounter = class {
+  #counts = /* @__PURE__ */ new Map();
+  /** Increment and return the new count. Python buckets a missing id under `_global`. */
+  increment(conversationId) {
+    const key = conversationId !== void 0 && conversationId !== "" ? conversationId : "_global";
+    const next = (this.#counts.get(key) ?? 0) + 1;
+    this.#counts.set(key, next);
+    return next;
+  }
+  /**
+   * True on every Nth turn, and never on the first.
+   *
+   * Python: `count > 0 and count % interval == 0`. Turn 5 injects, turn 1 does
+   * not, which matters because the first turn is usually the one that just
+   * triggered a fresh retrieval anyway.
+   */
+  shouldInject(conversationId) {
+    const key = conversationId !== void 0 && conversationId !== "" ? conversationId : "_global";
+    const count = this.#counts.get(key) ?? 0;
+    return count > 0 && count % USER_SUMMARY_INTERVAL === 0;
+  }
+  clear() {
+    this.#counts.clear();
+  }
+};
+function itemId(item) {
+  return String(item["item_id"] ?? item["id"] ?? "");
+}
+function pick2(item, ...names) {
+  for (const name of names) {
+    const value = item[name];
+    if (value !== void 0 && value !== null) return value;
+  }
+  return void 0;
+}
+function normalise(item) {
+  const content = pick2(item, "content") ?? "";
+  const confidence = pick2(item, "confidence") ?? 0;
+  const extractedAt = pick2(item, "extracted_at", "created_at") ?? null;
+  return {
+    id: itemId(item),
+    content: String(content),
+    confidence: Number(confidence),
+    source: String(pick2(item, "source") ?? ""),
+    category: String(pick2(item, "context_type", "category") ?? ""),
+    emotion_type: String(pick2(item, "context_type", "emotion_type") ?? ""),
+    strength: Number(pick2(item, "strength", "confidence") ?? 0),
+    summary: String(pick2(item, "summary", "content") ?? ""),
+    significance: Number(pick2(item, "significance", "confidence") ?? 0),
+    intensity: Number(pick2(item, "intensity", "confidence") ?? 0),
+    context: String(pick2(item, "context", "content") ?? ""),
+    participants: pick2(item, "participants") ?? [],
+    extracted_at: extractedAt,
+    occurred_at: pick2(item, "occurred_at", "extracted_at", "created_at") ?? null,
+    detected_at: pick2(item, "detected_at", "extracted_at", "created_at") ?? null,
+    metadata: pick2(item, "metadata") ?? {},
+    event_date: pick2(item, "event_date") ?? null,
+    valid_until: pick2(item, "valid_until") ?? null,
+    temporal_category: pick2(item, "temporal_category") ?? null,
+    temporal_confidence: Number(pick2(item, "temporal_confidence") ?? 0)
+  };
+}
+function mergeUserSummary(response, bundle) {
+  const itemsByType = bundle["items_by_type"] ?? {};
+  for (const collection of COLLECTIONS) {
+    const items = itemsByType[collection];
+    if (!Array.isArray(items)) continue;
+    const existing = response[collection] ?? [];
+    const existingIds = new Set(existing.map((i) => String(i.id ?? i.item_id ?? "")));
+    const fresh = items.filter((i) => typeof i === "object" && i !== null && !existingIds.has(itemId(i))).slice(0, MAX_SUMMARY_ITEMS).map(normalise);
+    if (fresh.length === 0) continue;
+    response[collection] = [...existing, ...fresh];
+  }
+  return response;
+}
+
+// src/context/anticipated.ts
+function scopeLookupParams(scope, params) {
+  const { searchQuery, entityId, customerId, clientId, conversationId } = params;
+  switch (scope) {
+    case "conversation":
+      return { searchQuery, entityId, customerId, clientId, conversationId };
+    case "user":
+      return { searchQuery, entityId, customerId, clientId };
+    case "customer":
+      return { searchQuery, entityId: null, customerId, clientId };
+    case "client":
+      return { searchQuery, entityId: null, customerId: null, clientId };
+  }
+}
+function buildAnticipationResponse(hit) {
+  const response = {};
+  for (const [type, items] of Object.entries(hit.itemsByType)) {
+    response[type] = items;
+  }
+  response.metadata = {
+    source: "anticipation",
+    ttl_seconds: 0,
+    cache_hit: true,
+    retrieved_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return response;
+}
+function servedItemIds(hit) {
+  const ids = [];
+  for (const items of Object.values(hit.itemsByType)) {
+    for (const item of items) {
+      const id = item.item_id ?? item["id"];
+      if (typeof id === "string" && id !== "") ids.push(id);
+    }
+  }
+  return ids;
+}
+function tryServeFromCache(cache, scope, params, maxItems) {
+  try {
+    const scoped = scopeLookupParams(scope, params);
+    const hit = cache.lookup({
+      searchQuery: scoped.searchQuery ?? null,
+      entityId: scoped.entityId ?? null,
+      customerId: scoped.customerId ?? null,
+      clientId: scoped.clientId ?? null,
+      conversationId: scoped.conversationId ?? null,
+      maxItems
+    });
+    if (hit === null) return { response: null, hit: null };
+    return { response: buildAnticipationResponse(hit), hit };
+  } catch {
+    return { response: null, hit: null };
+  }
+}
+
+// src/context/assembled.ts
+var COLLECTIONS2 = ["facts", "preferences", "episodes", "emotions", "temporal_events"];
+function finalItemIds(response) {
+  const ids = [];
+  for (const collection of COLLECTIONS2) {
+    const items = response[collection];
+    if (!Array.isArray(items)) continue;
+    for (const item of items) {
+      const id = item["id"] ?? item["item_id"];
+      if (typeof id === "string" && id !== "") ids.push(id);
+    }
+  }
+  return ids;
+}
+function resolveSource(response, override) {
+  const metadata = response.metadata ?? {};
+  let source = override ?? String(metadata["source"] ?? "") ?? "";
+  if (source === "") source = "cloud";
+  if (source === "cache") source = "http_cache";
+  const impliesHit = ["anticipation", "anticipation_cache", "http_cache", "sdk_authoritative"];
+  const cacheHit = impliesHit.includes(source) ? true : Boolean(metadata["cache_hit"]);
+  return { source, cacheHit };
+}
+function buildAssembledEvent(params) {
+  const { response } = params;
+  const { source, cacheHit } = resolveSource(response, params.sourceOverride);
+  const conversationContext = response.conversation_context ?? {};
+  const recentTurns = conversationContext["recent_turns"];
+  const metadata = response.metadata ?? {};
+  return {
+    correlation_id: params.correlationId,
+    conversation_id: params.conversationId ?? "",
+    user_id: params.userId ?? "",
+    customer_id: params.customerId ?? "",
+    final_item_ids: finalItemIds(response),
+    final_total_tokens: Number(metadata["total_tokens"] ?? 0),
+    compaction_id: String(conversationContext["compaction_id"] ?? ""),
+    recent_turn_count: Array.isArray(recentTurns) ? recentTurns.length : 0,
+    compaction_end_timestamp: String(
+      conversationContext["end_timestamp"] ?? conversationContext["compacted_at"] ?? ""
+    ),
+    assembly_source: source,
+    assembly_duration_ms: Math.max(0, Date.now() - params.startedAt),
+    cache_hit: cacheHit,
+    sdk_version: params.sdkVersion
+  };
+}
+
 // src/context/unified.ts
 var ITEM_COLLECTIONS = [
   "facts",
@@ -1323,7 +1767,7 @@ var ITEM_COLLECTIONS = [
   "emotions",
   "temporal_events"
 ];
-function itemId(item) {
+function itemId2(item) {
   const id = item.id ?? item.item_id;
   return typeof id === "string" && id !== "" ? id : void 0;
 }
@@ -1359,7 +1803,7 @@ function mergeScopeResults(scopeResults) {
       const items = response[collection];
       if (!Array.isArray(items)) continue;
       for (const item of items) {
-        const id = itemId(item);
+        const id = itemId2(item);
         if (id !== void 0) {
           if (seen.has(id)) continue;
           seen.add(id);
@@ -1385,7 +1829,7 @@ function numberOf(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 function scopeOf(ctx, item) {
-  const id = itemId(item);
+  const id = itemId2(item);
   return (id !== void 0 ? ctx.scope_map[id] : void 0) ?? "unknown";
 }
 function bulletWithExtras(text, extras) {
@@ -1700,6 +2144,11 @@ var SynapClient = class {
   // can still reach it. These two were public and made `client.transport
   // .credentials.apiKey` and the raw cache's `now`/`fire`/`invalidateEntity`
   // reachable, which is exactly what `client.cache` exists to prevent.
+  // Definite-assignment assertions (`!`) because the constructor can RETURN an
+  // existing client from the registry before reaching any of these. TypeScript
+  // cannot follow a constructor return, so it sees a path where the fields are
+  // unassigned. On that path the object is discarded and the incumbent is
+  // handed back instead, so nothing observes them.
   #transport;
   #anticipationCache;
   user;
@@ -1712,10 +2161,28 @@ var SynapClient = class {
   instance;
   #closed = false;
   #initialized = false;
+  #registryKeys;
   #compactionSubscribers;
+  #shortTerm;
+  #turns;
+  #fetchHooks;
   constructor(options = {}) {
     const credentials = resolveCredentials(options);
     validateInstanceId(credentials.instanceId);
+    const registryKey = buildRegistryKey(credentials.instanceId, credentials.apiKey);
+    if (options._force_new !== true) {
+      const existing = get(registryKey);
+      if (existing !== void 0) {
+        const incumbent = existing.#transport.currentCredentials().apiKey;
+        if (credentials.apiKey && incumbent && credentials.apiKey !== incumbent) {
+          existing.#warn(
+            `Instance ${registryKey} is already running in this process on a different API key. The key passed here is ignored; this client will authenticate as the existing one. Rotating a key this way has no effect. Construct with apiKey and no instanceId to get a client on your own credential.`
+          );
+        }
+        return existing;
+      }
+    }
+    this.#registryKeys = options._force_new === true ? [] : [registryKey];
     this.#transport = new HttpTransport({
       credentials,
       ...options.baseUrl !== void 0 ? { baseUrl: options.baseUrl } : {},
@@ -1727,10 +2194,41 @@ var SynapClient = class {
     });
     if (options.heartbeat) this.#transport.startHeartbeat();
     this.#anticipationCache = new AnticipationCache();
-    this.user = createUserNamespace(this.#transport);
-    this.customer = { context: { fetch: async (o2 = {}) => fetchContext(this.#transport, "customer", o2) } };
-    this.client = { context: { fetch: async (o2 = {}) => fetchContext(this.#transport, "client", o2) } };
+    this.#fetchHooks = {
+      beforeFetch: (scope, options2) => {
+        const o2 = options2;
+        const attempt = tryServeFromCache(
+          this.#anticipationCache,
+          scope,
+          {
+            searchQuery: o2["search_query"] ?? o2["searchQuery"],
+            entityId: o2["user_id"] ?? o2["userId"],
+            customerId: o2["customer_id"] ?? o2["customerId"],
+            clientId: this.#transport.currentCredentials().clientId || null,
+            conversationId: o2["conversation_id"] ?? o2["conversationId"]
+          },
+          Number(o2["max_results"] ?? o2["maxResults"] ?? 10)
+        );
+        if (attempt.response === null || attempt.hit === null) return null;
+        return {
+          response: attempt.response,
+          servedItemIds: servedItemIds(attempt.hit),
+          bundleId: attempt.hit.bundleIds[0] ?? ""
+        };
+      },
+      onAssembled: (scope, options2, response, startedAt) => {
+        this.#emitContextAssembled(scope, options2, response, startedAt);
+      },
+      onServedFromCache: (_scope, options2, served) => {
+        this.#emitContextUsed(options2, _scope, served);
+      }
+    };
+    this.user = createUserNamespace(this.#transport, this.#fetchHooks);
+    this.customer = { context: { fetch: async (o2 = {}) => fetchContext(this.#transport, "customer", o2, this.#fetchHooks) } };
+    this.client = { context: { fetch: async (o2 = {}) => fetchContext(this.#transport, "client", o2, this.#fetchHooks) } };
     this.#compactionSubscribers = new CompactionSubscribers();
+    this.#shortTerm = new ShortTermStore();
+    this.#turns = new TurnCounter();
     this.conversation = createConversationNamespace(
       this.#transport,
       this.#compactionSubscribers,
@@ -1743,6 +2241,15 @@ var SynapClient = class {
         for (const id of /* @__PURE__ */ new Set([userId, customerId])) {
           if (id) this.#anticipationCache.invalidateEntity(id);
         }
+      },
+      // Buffer the turn locally so the next fetch sees it, ahead of the server
+      // having persisted and compacted it.
+      ({ conversationId, role, content, timestamp }) => {
+        this.#shortTerm.appendTurn(conversationId, role, content, timestamp);
+      },
+      (response, conversationId, userId) => {
+        overlayLocalRecentTurns(response, this.#shortTerm, conversationId);
+        this.#injectUserSummary(response, conversationId, userId);
       }
     );
     this.memories = createMemoriesInterface(this.#transport);
@@ -1750,8 +2257,18 @@ var SynapClient = class {
     this.cache = createCacheNamespace(this.#anticipationCache);
     this.instance = createInstanceNamespace(
       () => this.#transport.currentCredentials(),
-      this.#anticipationCache
+      this.#anticipationCache,
+      ({ conversationId, role, content }) => {
+        this.#shortTerm.appendTurn(conversationId, role, content);
+      }
     );
+    this.instance._internal.setCompactionApplier((bundle) => {
+      this.#shortTerm.applyCompaction(bundle);
+    });
+    if (options._force_new !== true) {
+      const incumbent = registerIfAbsent(registryKey, this);
+      if (incumbent !== void 0) return incumbent;
+    }
     this.instance._internal.setCompactionDispatcher((conversationId, bundle) => {
       this.#compactionSubscribers.dispatch(conversationId, bundle, (error) => {
         this.#warn(`compaction subscriber threw: ${String(error)}`);
@@ -1789,10 +2306,10 @@ var SynapClient = class {
     }
     const context = await fetchContext(this.#transport, "user", {
       user_id: userId,
-      ...pick2(options, "customer_id", "customerId") !== void 0 ? { customer_id: pick2(options, "customer_id", "customerId") } : {},
-      ...pick2(options, "conversation_id", "conversationId") !== void 0 ? { conversation_id: pick2(options, "conversation_id", "conversationId") } : {},
+      ...pick3(options, "customer_id", "customerId") !== void 0 ? { customer_id: pick3(options, "customer_id", "customerId") } : {},
+      ...pick3(options, "conversation_id", "conversationId") !== void 0 ? { conversation_id: pick3(options, "conversation_id", "conversationId") } : {},
       search_query: [options.query],
-      max_results: pick2(options, "max_results", "maxResults") ?? 10,
+      max_results: pick3(options, "max_results", "maxResults") ?? 10,
       types: options.types ?? ["all"],
       ...options.mode !== void 0 ? { mode: options.mode } : {}
     });
@@ -1809,10 +2326,10 @@ var SynapClient = class {
     if (!userId) throw new InvalidInputError("user_id is required");
     const context = await fetchContext(this.#transport, "user", {
       user_id: userId,
-      ...pick2(options, "customer_id", "customerId") !== void 0 ? { customer_id: pick2(options, "customer_id", "customerId") } : {},
-      ...pick2(options, "conversation_id", "conversationId") !== void 0 ? { conversation_id: pick2(options, "conversation_id", "conversationId") } : {},
+      ...pick3(options, "customer_id", "customerId") !== void 0 ? { customer_id: pick3(options, "customer_id", "customerId") } : {},
+      ...pick3(options, "conversation_id", "conversationId") !== void 0 ? { conversation_id: pick3(options, "conversation_id", "conversationId") } : {},
       search_query: [],
-      max_results: pick2(options, "max_results", "maxResults") ?? 100,
+      max_results: pick3(options, "max_results", "maxResults") ?? 100,
       types: options.types ?? ["all"],
       ...options.mode !== void 0 ? { mode: options.mode } : {}
     });
@@ -1858,6 +2375,11 @@ var SynapClient = class {
         ...resolvedClientId !== "" && credentials.clientId === "" ? { clientId: resolvedClientId } : {},
         ...resolvedInstanceId !== "" && credentials.instanceId === "" ? { instanceId: resolvedInstanceId } : {}
       });
+      if (resolvedInstanceId !== "" && this.#registryKeys.length > 0) {
+        if (aliasIfAbsent(resolvedInstanceId, this)) {
+          this.#registryKeys.push(resolvedInstanceId);
+        }
+      }
     } catch {
     }
   }
@@ -1994,6 +2516,9 @@ var SynapClient = class {
       this.#warn(`Scope '${label}' fetch failed in unified fetch (non-fatal): ${String(result.reason)}`);
     }
     const merged = mergeScopeResults(successful);
+    for (const [, response] of successful) {
+      overlayLocalRecentTurns(response, this.#shortTerm, conversationId);
+    }
     if (includeConversationContext && conversationId !== void 0 && conversationId !== "") {
       try {
         merged.conversation_context = await this.conversation.context.get_context_for_prompt({
@@ -2026,6 +2551,69 @@ var SynapClient = class {
   anticipation_cache_snapshot() {
     return this.#anticipationCache.snapshot();
   }
+  /**
+   * Report a locally served fetch back to the server.
+   *
+   * Only while listening: the event rides the Listen stream, and there is
+   * nowhere to put it otherwise. Never throws, because a telemetry failure
+   * must not fail a retrieval that already succeeded.
+   */
+  #emitContextUsed(options, scope, served) {
+    try {
+      if (!this.instance.is_listening) return;
+      this.instance._internal.sendContextUsed({
+        bundle_id: served.bundleId,
+        conversation_id: String(options["conversation_id"] ?? options["conversationId"] ?? ""),
+        user_id: String(options["user_id"] ?? options["userId"] ?? ""),
+        customer_id: String(options["customer_id"] ?? options["customerId"] ?? ""),
+        served_item_ids: served.servedItemIds,
+        scope,
+        source_bundle_ids: served.bundleId ? [served.bundleId] : [],
+        timestamp_ms: Date.now()
+      });
+    } catch {
+    }
+  }
+  /**
+   * Report what was actually composed for this turn.
+   *
+   * Fires whether the fetch was served from the cache or the network, because
+   * the audit needs to distinguish them. Like the other stream events it is
+   * fire-and-forget and only goes anywhere while listening.
+   */
+  #emitContextAssembled(scope, options, response, startedAt) {
+    try {
+      if (!this.instance.is_listening) return;
+      this.instance._internal.sendContextAssembled({
+        ...buildAssembledEvent({
+          correlationId: newCorrelationId(),
+          response,
+          conversationId: options["conversation_id"] ?? options["conversationId"],
+          userId: options["user_id"] ?? options["userId"],
+          customerId: options["customer_id"] ?? options["customerId"],
+          startedAt,
+          sdkVersion: SDK_VERSION
+        }),
+        scope
+      });
+    } catch {
+    }
+  }
+  /**
+   * Fold a cached user summary in, every Nth turn.
+   *
+   * Only when the caller supplied a user_id. Without one the summary lookup
+   * cannot be scoped, and an unscoped lookup is how user A's summary ends up in
+   * user B's response.
+   */
+  #injectUserSummary(response, conversationId, userId) {
+    this.#turns.increment(conversationId);
+    if (userId === void 0 || userId === "") return;
+    if (!this.#turns.shouldInject(conversationId)) return;
+    const summary = this.#anticipationCache.lookupUserSummary(userId);
+    if (summary === null) return;
+    mergeUserSummary(response, summary);
+  }
   /** Python logs via `logger.warning`; here it is one overridable seam. */
   #warn(message) {
     console.warn(`[synap] ${message}`);
@@ -2034,13 +2622,16 @@ var SynapClient = class {
   async shutdown() {
     if (this.#closed) return;
     this.#closed = true;
+    this.#shortTerm.clear();
+    this.#turns.clear();
+    for (const key of this.#registryKeys) unregisterIfOwner(key, this);
     await this.instance.stop_listening();
     this.#compactionSubscribers.removeAll();
     this.#transport.close();
     this.#anticipationCache.clear();
   }
 };
-function pick2(o2, snake, camel) {
+function pick3(o2, snake, camel) {
   const a = o2[snake];
   return a !== void 0 ? a : o2[camel];
 }