@maximem/synap-js-sdk 0.5.8 → 0.5.10

package/dist/index.js

@@ -3,12 +3,14 @@ import {
   AnticipationCache,
   BM25,
   CONTRACT,
+  HISTORY_SEARCH,
+  SEMANTIC_MATCH,
   THRESHOLDS,
   isRecallQuery,
   rungKey,
   stem,
   tokenize
-} from "./chunk-ODVOQOSO.js";
+} from "./chunk-R72YL6Q4.js";
 import {
   getEnv
 } from "./chunk-QBCVMPGK.js";
@@ -55,6 +57,7 @@ var ENDPOINTS = {
   context_fetch_client: { method: "POST", path: "/v1/context/client/fetch", idempotent: true },
   context_fetch_conversation: { method: "POST", path: "/v1/context/conversation/fetch", idempotent: true },
   context_for_prompt: { method: "GET", path: "/v1/conversations/{conversation_id}/context-for-prompt", idempotent: true },
+  conversation_turns: { method: "GET", path: "/v1/conversations/{conversation_id}/messages", idempotent: true },
   conversations_ingest: { method: "POST", path: "/v1/conversations/ingest", idempotent: false },
   conversations_messages: { method: "POST", path: "/v1/conversations/messages", idempotent: false },
   conversations_messages_batch: { method: "POST", path: "/v1/conversations/messages/batch", idempotent: false },
@@ -264,6 +267,17 @@ var HttpTransport = class {
    * deployment older than the field, and must mean "enforce nothing".
    */
   userContextIsolation = void 0;
+  /**
+   * Set by the client to its identity resolution (`initialize()`'s whoami).
+   * Python refuses every call before `initialize()`; here the first request
+   * runs it instead, so a caller who skips it gets the same identity-dependent
+   * behaviour (client-scope cache hits, the B2C check) rather than an error.
+   */
+  identityResolver = void 0;
+  /** Resolve identity once, before the first request. Never throws. */
+  async ready() {
+    if (this.identityResolver !== void 0) await this.identityResolver();
+  }
   /** Refuse a customer_id on a B2C instance, at the call site. */
   checkCustomerId(customerId, where) {
     checkCustomerId(
@@ -295,6 +309,7 @@ var HttpTransport = class {
     const spec = ENDPOINTS[name];
     const correlationId = options.correlationId ?? newCorrelationId();
     const idempotent = options.idempotent ?? spec.idempotent;
+    if (name !== "whoami") await this.ready();
     let attempt = 0;
     let last = null;
     while (attempt < this.retryPolicy.maxAttempts) {
@@ -517,6 +532,86 @@ function sleep(ms, signal) {
   });
 }
 
+// src/context/ranked.ts
+var RESPONSE_SHAPES = ["by_type", "ranked"];
+var MEMORY_TYPES = [
+  "facts",
+  "preferences",
+  "episodes",
+  "emotions",
+  "temporal_events"
+];
+var EXCERPT_CATEGORY = "excerpts";
+function wireRankScore(item) {
+  const md = item.metadata;
+  let raw = md !== null && typeof md === "object" ? md["rank_score"] : void 0;
+  if (raw === void 0 || raw === null) raw = item["rank_score"];
+  return typeof raw === "number" && Number.isFinite(raw) ? raw : null;
+}
+function wireCategory(item, fallback = "") {
+  if (item.source === "chunks") return EXCERPT_CATEGORY;
+  const category = item["category"];
+  if (typeof category === "string" && category !== "") return category;
+  const contextType = item["context_type"];
+  if (typeof contextType === "string" && contextType !== "") return contextType;
+  return fallback;
+}
+function byRankScore(a, b) {
+  const sa = wireRankScore(a);
+  const sb = wireRankScore(b);
+  if (sa === null && sb === null) return 0;
+  if (sa === null) return 1;
+  if (sb === null) return -1;
+  return sb - sa;
+}
+function rankItems(byType) {
+  const flat = [];
+  for (const type of MEMORY_TYPES) {
+    const list = byType[type];
+    if (!Array.isArray(list)) continue;
+    for (const it of list) {
+      if (it === null || typeof it !== "object") continue;
+      flat.push({
+        ...it,
+        category: wireCategory(it, type),
+        id: it.id || it.item_id || ""
+      });
+    }
+  }
+  flat.sort(byRankScore);
+  return flat.map((it, n2) => ({ ...it, rank: n2 + 1 }));
+}
+function applyResponseShape(raw, shape = "by_type") {
+  const wire = raw["items"];
+  if (shape !== "ranked" && !Array.isArray(wire)) return raw;
+  const source = Array.isArray(wire) ? wire : rankItems(raw);
+  const items = source.map((it) => ({
+    ...it,
+    id: it.id || it.item_id || "",
+    category: wireCategory(it)
+  }));
+  const out = { ...raw, items };
+  for (const type of MEMORY_TYPES) {
+    out[type] = items.filter((it) => it["category"] === type);
+  }
+  out["excerpts"] = items.filter((it) => it["category"] === EXCERPT_CATEGORY);
+  return out;
+}
+var RANKED_LABELS = {
+  facts: "fact",
+  preferences: "preference",
+  episodes: "episode",
+  emotions: "emotion",
+  temporal_events: "temporal event",
+  [EXCERPT_CATEGORY]: "excerpt"
+};
+function rankedLabel(category) {
+  return RANKED_LABELS[category] ?? (category !== "" ? category : "item");
+}
+function sortByRankScore(items) {
+  return [...items].sort(byRankScore);
+}
+
 // src/context/fetch.ts
 var ENDPOINT_BY_SCOPE = {
   user: "context_fetch_user",
@@ -536,10 +631,10 @@ function buildFetchRequest(scope, options) {
   const conversationId = opt(options, "conversation_id", "conversationId");
   const searchQuery = opt(options, "search_query", "searchQuery");
   const maxResults = opt(options, "max_results", "maxResults") ?? 10;
-  const precisionLevel = opt(options, "precision_level", "precisionLevel") ?? "high";
   const queryDate = opt(options, "query_date", "queryDate");
   const perQuery = opt(options, "max_results_per_query", "maxResultsPerQuery");
-  const mode = options.mode ?? "fast";
+  const responseShape = responseShapeOf(options);
+  const { mode, precisionLevel } = retrievalOptionsOf(options);
   if (searchQuery !== void 0 && !Array.isArray(searchQuery)) {
     throw new InvalidInputError("search_query must be an array when provided");
   }
@@ -556,16 +651,19 @@ function buildFetchRequest(scope, options) {
   if (precisionLevel !== "high") body["precision_level"] = precisionLevel;
   if (queryDate) body["query_date"] = queryDate;
   if (perQuery) body["max_results_per_query"] = perQuery;
+  if (responseShape !== "by_type") body["response_shape"] = responseShape;
   if (options.include_conversation_context === false) {
     body["include_conversation_context"] = false;
   }
+  const scopePath = opt(options, "scope_path", "scopePath");
+  if (scopePath !== void 0 && scopePath !== null && Object.keys(scopePath).length > 0) {
+    body["scope"] = scopePath;
+  }
   switch (scope) {
     case "user":
       {
         if (!userId) throw new InvalidInputError("user_id is required");
         body["user_id"] = userId;
-        const scopePath = opt(options, "scope_path", "scopePath");
-        if (scopePath !== void 0) body["scope"] = scopePath;
         const contextMode = opt(options, "context_mode", "contextMode") ?? "in-conversation";
         if (!VALID_CONTEXT_MODES.includes(contextMode)) {
           throw new InvalidInputError(
@@ -603,21 +701,67 @@ function buildFetchRequest(scope, options) {
   return { endpoint: ENDPOINT_BY_SCOPE[scope], body };
 }
 var VALID_CONTEXT_MODES = ["in-conversation", "conversation-summary"];
+function responseShapeOf(options) {
+  const shape = opt(options, "response_shape", "responseShape") ?? "by_type";
+  if (!RESPONSE_SHAPES.includes(shape)) {
+    throw new InvalidInputError(
+      `Invalid response_shape '${shape}'. Must be one of: ${RESPONSE_SHAPES.join(", ")}`
+    );
+  }
+  return shape;
+}
+var VALID_MODES = ["fast", "accurate"];
+var VALID_PRECISION = ["high", "medium"];
+function retrievalOptionsOf(options) {
+  const mode = options.mode ?? "fast";
+  if (!VALID_MODES.includes(mode)) {
+    throw new InvalidInputError(
+      `Invalid mode '${mode}'. Must be one of: ${VALID_MODES.join(", ")}`
+    );
+  }
+  const precisionLevel = opt(options, "precision_level", "precisionLevel") ?? "high";
+  if (!VALID_PRECISION.includes(precisionLevel)) {
+    throw new InvalidInputError(
+      `Invalid precision_level '${precisionLevel}'. Must be one of: ${VALID_PRECISION.join(", ")}`
+    );
+  }
+  return { mode, precisionLevel };
+}
 async function fetchContext(transport, scope, options = {}, hooks = {}) {
   const startedAt = Date.now();
+  await transport.ready?.();
   transport.checkCustomerId(
     opt(options, "customer_id", "customerId"),
     `${scope}.context.fetch`
   );
-  const anticipated = hooks.beforeFetch?.(scope, options) ?? null;
+  const responseShape = responseShapeOf(options);
+  retrievalOptionsOf(options);
+  const network = async () => {
+    const { endpoint, body } = buildFetchRequest(scope, options);
+    const result = await transport.request(endpoint, { body });
+    return applyResponseShape(result?.["context"] ?? {}, responseShape);
+  };
+  const anticipated = await hooks.beforeFetch?.(scope, options) ?? null;
+  if (anticipated !== null && anticipated.borderline) {
+    const pending = network();
+    pending.catch(() => void 0);
+    let timer;
+    const late = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(null), anticipated.raceDeadlineMs ?? 250);
+    });
+    const won = await Promise.race([pending.then((r) => r, () => null), late]);
+    if (timer !== void 0) clearTimeout(timer);
+    if (won !== null) {
+      hooks.onAssembled?.(scope, options, won, startedAt);
+      return won;
+    }
+  }
   if (anticipated !== null) {
     hooks.onServedFromCache?.(scope, options, anticipated);
     hooks.onAssembled?.(scope, options, anticipated.response, startedAt);
-    return anticipated.response;
+    return applyResponseShape(anticipated.response, responseShape);
   }
-  const { endpoint, body } = buildFetchRequest(scope, options);
-  const result = await transport.request(endpoint, { body });
-  const response = result?.["context"] ?? {};
+  const response = await network();
   hooks.onAssembled?.(scope, options, response, startedAt);
   return response;
 }
@@ -738,6 +882,17 @@ function normalizeConversationContext(value) {
     conversationId: pick(value["conversationId"], value.conversation_id, null)
   };
 }
+function normalizeRetrievalHealth(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw;
+  const warnings = r["warnings"];
+  return {
+    degraded: r["degraded"] === void 0 ? true : Boolean(r["degraded"]),
+    level: r["level"] ?? null,
+    code: r["code"] ?? null,
+    warnings: Array.isArray(warnings) ? warnings.map((w) => String(w)) : []
+  };
+}
 function normalizeContextResponse(result = {}) {
   const context = result["context"] ?? result;
   return {
@@ -754,7 +909,15 @@ function normalizeContextResponse(result = {}) {
       )
     ),
     metadata: normalizeContextMetadata(obj(context.metadata)),
-    rawResponse: pick(context["rawResponse"], context["raw_response"], {})
+    // `retrieval` is a SIBLING of `context` in the body, so it is read off the
+    // envelope first and only then off a bare context. Reading it from
+    // `context` alone is how the Python SDK dropped it.
+    retrieval: normalizeRetrievalHealth(
+      pick(result["retrieval"], context["retrieval"], null)
+    ),
+    rawResponse: pick(context["rawResponse"], context["raw_response"], {}),
+    // Only for a ranked fetch, so a by-type result has exactly the keys it had.
+    ...Array.isArray(context.items) ? { items: context.items, excerpts: Array.isArray(context.excerpts) ? context.excerpts : [] } : {}
   };
 }
 
@@ -1069,6 +1232,27 @@ function validateInstanceId(instanceId) {
   }
 }
 
+// src/agent-model.ts
+var AGENT_MODEL_KEY = "agent_model";
+var AGENT_CONTEXT_WINDOW_KEY = "agent_context_window";
+function agentModelOf(options) {
+  const o2 = options ?? {};
+  const window = o2["context_window"] ?? o2["contextWindow"];
+  return {
+    model: typeof o2["model"] === "string" ? o2["model"] : void 0,
+    contextWindow: typeof window === "number" ? window : void 0
+  };
+}
+function withAgentModel(metadata, perCall, defaults, asStrings = false) {
+  const model = perCall.model || defaults.model;
+  const window = perCall.contextWindow || defaults.contextWindow;
+  if (!model && !window) return metadata;
+  const out = { ...metadata ?? {} };
+  if (model) out[AGENT_MODEL_KEY] = String(model);
+  if (window) out[AGENT_CONTEXT_WINDOW_KEY] = asStrings ? String(Math.trunc(window)) : Math.trunc(window);
+  return out;
+}
+
 // src/conversation/interface.ts
 var COMPACTION_LEVELS = [
   "low",
@@ -1197,10 +1381,50 @@ var CompactionSubscribers = class {
     }
   }
 };
+function storedBatchRows(bodies, result) {
+  const r = result ?? {};
+  const results = Array.isArray(r["results"]) ? r["results"] : [];
+  const errors = Array.isArray(r["errors"]) ? r["errors"] : [];
+  const failed = new Set(errors.map((e) => e?.["index"]));
+  const stored = bodies.filter((_, index) => !failed.has(index));
+  if (stored.length !== results.length) return [];
+  const pairs = [];
+  stored.forEach((body, i) => {
+    const row = results[i];
+    if (row && typeof row === "object" && row["message_id"]) pairs.push([body, row]);
+  });
+  return pairs;
+}
 function createConversationNamespace(transport, subscribers = new CompactionSubscribers(), onWrite = () => {
 }, onTurn = () => {
 }, onFetched = () => {
-}, localShortTerm = { prompt: () => null, compacted: () => null }) {
+}, localShortTerm = { prompt: () => null, compacted: () => null }, agentModel = () => ({})) {
+  const writesInFlight = /* @__PURE__ */ new Map();
+  const withTurnModel = (body, options) => {
+    const metadata = withAgentModel(
+      body["metadata"],
+      agentModelOf(options),
+      agentModel()
+    );
+    return metadata === void 0 ? body : { ...body, metadata };
+  };
+  const writeStarted = (conversationId) => {
+    writesInFlight.set(conversationId, (writesInFlight.get(conversationId) ?? 0) + 1);
+  };
+  const writeLanded = (conversationId) => {
+    const remaining = (writesInFlight.get(conversationId) ?? 0) - 1;
+    if (remaining > 0) writesInFlight.set(conversationId, remaining);
+    else writesInFlight.delete(conversationId);
+  };
+  const confirmation = (result, conversationId) => {
+    const r = result ?? {};
+    const count = r["conversation_message_count"];
+    return {
+      ...typeof r["message_id"] === "string" ? { messageId: r["message_id"] } : {},
+      serverMessageCount: typeof count === "number" ? count : null,
+      inFlight: writesInFlight.get(conversationId) ?? 0
+    };
+  };
   const convId = (v) => {
     const id = typeof v === "string" ? v : v.conversation_id ?? v.conversationId;
     if (!id) throw new InvalidInputError("conversation_id is required");
@@ -1213,13 +1437,21 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
         options["customer_id"] ?? options["customerId"],
         "conversation.record_message"
       );
-      const body = buildRecordMessageBody(options);
-      const result = await transport.request("conversations_messages", { body });
+      const body = withTurnModel(buildRecordMessageBody(options), options);
+      const conversationId = String(body["conversation_id"] ?? "");
+      writeStarted(conversationId);
+      let result;
+      try {
+        result = await transport.request("conversations_messages", { body });
+      } finally {
+        writeLanded(conversationId);
+      }
       onTurn({
-        conversationId: String(body["conversation_id"] ?? ""),
+        conversationId,
         role: String(body["role"] ?? "user"),
         content: String(body["content"] ?? ""),
-        timestamp: body["timestamp"]
+        timestamp: body["timestamp"],
+        ...confirmation(result, conversationId)
       });
       onWrite({
         userId: body["user_id"],
@@ -1238,16 +1470,18 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
           "conversation.record_messages_batch"
         );
       }
-      const bodies = messages.map(buildRecordMessageBody);
+      const bodies = messages.map((m) => withTurnModel(buildRecordMessageBody(m), m));
       const result = await transport.request("conversations_messages_batch", {
         body: { messages: bodies }
       });
-      for (const body of bodies) {
+      for (const [body, row] of storedBatchRows(bodies, result)) {
+        const conversationId = String(body["conversation_id"] ?? "");
         onTurn({
-          conversationId: String(body["conversation_id"] ?? ""),
+          conversationId,
           role: String(body["role"] ?? "user"),
           content: String(body["content"] ?? ""),
-          timestamp: body["timestamp"]
+          timestamp: body["timestamp"],
+          ...confirmation(row, conversationId)
         });
       }
       for (const body of bodies) {
@@ -1282,13 +1516,24 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
       },
       get_context_for_prompt: async (options = {}) => {
         const id = convId(options);
+        const search = (options.search_history ?? options.searchHistory ?? true) && localShortTerm.historyExcerpts;
+        const withHistory = async (response2) => {
+          if (!search) return response2;
+          try {
+            return await localShortTerm.historyExcerpts(id, response2, options.query);
+          } catch {
+            return response2;
+          }
+        };
         const local = localShortTerm.prompt(id, options.style ?? "structured");
-        if (local !== null) return local;
+        if (local !== null) return withHistory(local);
         const result = await transport.request("context_for_prompt", {
           pathParams: { conversation_id: id },
           query: { style: options.style ?? "structured" }
         });
-        return result?.["context_for_prompt"] ?? result ?? {};
+        const response = result?.["context_for_prompt"] ?? result ?? {};
+        localShortTerm.reseed?.(id, response);
+        return withHistory(response);
       },
       async compact(options) {
         return transport.request("conversations_compact", { body: buildCompactBody(options) });
@@ -1471,11 +1716,13 @@ function jsonOrText(value) {
     }
   }
 }
-function createInstanceNamespace(credentials, cache, onTurn) {
+function createInstanceNamespace(credentials, cache, onTurn, agentModel = () => ({}), onToolResult) {
   let client = null;
   const openSessions = /* @__PURE__ */ new Map();
   let dispatchCompaction = null;
   let applyCompaction = null;
+  let onListen = null;
+  let onConversationState = null;
   const internals = {
     onCompactionUpdate(conversationId, bundle) {
       applyCompaction?.(bundle);
@@ -1484,6 +1731,12 @@ function createInstanceNamespace(credentials, cache, onTurn) {
     setCompactionApplier(apply) {
       applyCompaction = apply;
     },
+    setOnListen(handle) {
+      onListen = handle;
+    },
+    setConversationStateHandler(handle) {
+      onConversationState = handle;
+    },
     sendContextUsed(event) {
       client?.sendContextUsed(event);
     },
@@ -1518,7 +1771,11 @@ function createInstanceNamespace(credentials, cache, onTurn) {
       if (client !== null) {
         throw new ListeningAlreadyActiveError("Listening is already active on this instance");
       }
-      const { GrpcStreamClient } = await import("./stream-client-VWKINE47.js");
+      try {
+        onListen?.();
+      } catch {
+      }
+      const { GrpcStreamClient } = await import("./stream-client-3WHXGW4U.js");
       const onContext = options.on_context ?? options.onContext;
       const onDisconnect = options.on_disconnect ?? options.onDisconnect;
       const onReconnect = options.on_reconnect ?? options.onReconnect;
@@ -1532,6 +1789,9 @@ function createInstanceNamespace(credentials, cache, onTurn) {
         onCompactionUpdate: (conversationId, bundle) => {
           internals.onCompactionUpdate(conversationId, bundle);
         },
+        onConversationState: (conversationId, messageCount) => {
+          onConversationState?.(conversationId, messageCount);
+        },
         onStateChange: (state) => {
           if (state !== "connected") openSessions.clear();
           if (state === "reconnecting") {
@@ -1610,7 +1870,7 @@ function createInstanceNamespace(credentials, cache, onTurn) {
         user_id: options.user_id ?? options.userId ?? "",
         customer_id: options.customer_id ?? options.customerId ?? "",
         session_id: options.session_id ?? options.sessionId ?? openSessions.get(conversationId) ?? "",
-        metadata: options.metadata ?? {},
+        metadata: withAgentModel(options.metadata, agentModelOf(options), agentModel(), true) ?? {},
         timestamp_ms: Date.now(),
         tool_name: options.tool_name ?? options.toolName ?? "",
         // Python serialises tool_args with json.dumps into tool_args_json.
@@ -1640,6 +1900,10 @@ function createInstanceNamespace(credentials, cache, onTurn) {
       });
     },
     async record_tool_result(options) {
+      const conversationId = options.conversation_id ?? options.conversationId ?? "";
+      if (conversationId) {
+        onToolResult?.({ conversationId, result: options.result, toolName: options.tool_name ?? options.toolName ?? "" });
+      }
       await namespace.send_message({
         content: "",
         role: "tool",
@@ -1690,7 +1954,7 @@ function createInstanceNamespace(credentials, cache, onTurn) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.8";
+var SDK_VERSION = "0.5.10";
 
 // src/registry.ts
 var instances = /* @__PURE__ */ new Map();
@@ -1731,6 +1995,34 @@ function unregisterIfOwner(key, client) {
 // src/cache/short-term-store.ts
 var DEFAULT_MAX_CONVERSATIONS = 100;
 var DEFAULT_MAX_AGE_MS = 12 * 60 * 60 * 1e3;
+var CONTEXT_BLOCK_PREFIX = "## Conversation so far (compacted";
+function contextBlockOf(cc) {
+  const block = cc["context_block"];
+  if (typeof block === "string" && block) return block;
+  const summary = cc["summary"];
+  if (typeof summary === "string" && summary.startsWith(CONTEXT_BLOCK_PREFIX)) return summary;
+  return null;
+}
+function localMessageCount(entry) {
+  return entry.compactedMessageCount + entry.recentTurns.length;
+}
+function isComplete(entry) {
+  return entry.participant && entry.synced && !entry.shared && entry.serverMessageCount !== null && entry.serverMessageCount <= localMessageCount(entry);
+}
+function heldIn(turn, turns) {
+  return turns.some(
+    (held) => turn.message_id && held.message_id ? held.message_id === turn.message_id : held.role === turn.role && held.content === turn.content
+  );
+}
+function turnsAfter(localTurns, serverTurns) {
+  const newer = [];
+  for (let i = localTurns.length - 1; i >= 0; i -= 1) {
+    const turn = localTurns[i];
+    if (heldIn(turn, serverTurns)) break;
+    newer.unshift(turn);
+  }
+  return newer;
+}
 function parseIso(value) {
   if (value === null || value === void 0 || value === "") return null;
   if (value instanceof Date) return value.getTime();
@@ -1750,11 +2042,23 @@ var ShortTermStore = class {
   #maxConversations;
   #maxAgeMs;
   #now;
+  /**
+   * Every turn appended here is also kept in the archive (a TurnStore), which
+   * a compaction does not prune: the turns it covers stay searchable locally
+   * (history-search.ts). Python: `ShortTermContextStore.attach_archive`.
+   */
+  #archive = null;
   constructor(options = {}) {
     this.#maxConversations = options.maxConversations ?? DEFAULT_MAX_CONVERSATIONS;
     this.#maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
     this.#now = options.now ?? (() => Date.now());
   }
+  attachArchive(archive) {
+    this.#archive = archive;
+  }
+  get archive() {
+    return this.#archive;
+  }
   /** The entry, or null. Age-evicts on read, as Python does. */
   get(conversationId) {
     if (!conversationId) return null;
@@ -1780,23 +2084,88 @@ var ShortTermStore = class {
    * 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.
+   *
+   * `confirmation` is what the write learned from the server. See
+   * `TurnConfirmation` and `noteServerCount`.
    */
-  appendTurn(conversationId, role, content, timestamp) {
+  appendTurn(conversationId, role, content, timestamp, confirmation = {}) {
     if (!conversationId) return;
     const stamp = timestamp ?? new Date(this.#now()).toISOString();
+    if (this.#archive !== null) {
+      try {
+        this.#archive.add(conversationId, role, content, stamp, { messageId: confirmation.messageId ?? null });
+      } catch {
+      }
+    }
     const entry = this.#entries.get(conversationId) ?? this.#blank(conversationId);
-    entry.recentTurns.push({ role, content, timestamp: stamp });
+    const messageId = confirmation.messageId;
+    const alreadyHeld = Boolean(messageId) && entry.recentTurns.some((t) => t.message_id === messageId);
+    if (!alreadyHeld) {
+      const turn = { role, content, timestamp: stamp };
+      if (messageId) turn.message_id = messageId;
+      entry.recentTurns.push(turn);
+    }
+    const count = confirmation.serverMessageCount;
+    if (count !== null && count !== void 0) {
+      this.#noteCount(entry, Number(count), confirmation.inFlight ?? 0);
+    }
     entry.lastActivityAt = parseIso(stamp) ?? this.#now();
     this.#touch(conversationId, entry);
     this.#evict();
   }
+  /**
+   * Record the server's message count for a conversation.
+   *
+   * The streamed write path's half of `appendTurn`'s confirmation: a streamed
+   * turn is appended when it is sent, and the count arrives later, once the
+   * server has written it. A count for a conversation this process holds
+   * nothing for is ignored.
+   */
+  noteServerCount(conversationId, count) {
+    if (!conversationId) return;
+    const entry = this.#entries.get(conversationId);
+    if (entry !== void 0) this.#noteCount(entry, Number(count), 0);
+  }
+  /**
+   * Compare the server's count with what the entry holds.
+   *
+   * The count is taken after one of this process's own writes, so it proves
+   * the process takes part in the conversation.
+   *
+   * Server ahead of an entry that was in sync: something else wrote, and the
+   * entry is marked shared for good. Server ahead of an entry that was never
+   * in sync: this process joined late (a restart, an eviction), and `reseed`
+   * will fix it. `inFlight` covers this process's own writes that the server
+   * has counted and the entry has not appended yet, so two concurrent writes
+   * do not look like a second writer.
+   */
+  #noteCount(entry, count, inFlight) {
+    entry.participant = true;
+    if (count > localMessageCount(entry) + inFlight) {
+      if (entry.synced) entry.shared = true;
+    } else if (entry.serverMessageCount === null) {
+      entry.synced = true;
+    }
+    entry.serverMessageCount = Math.max(entry.serverMessageCount ?? 0, count);
+  }
   /**
    * 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.
+   * drops the buffered turns the new summary covers.
+   *
+   * Which turns those are is decided by count, not by clock. The bundle says
+   * how many messages the summary covers and how many the conversation held
+   * when the bundle was built, so the last `total - compacted` of its
+   * `recent_turns` are exactly the uncovered messages. Turns this process
+   * appended after the server took that count are kept behind them. Timestamps
+   * cannot do this job: the REST write returns the time of the response and
+   * not of the stored row, a caller may supply its own message time, and a
+   * streamed turn is stamped when a background write runs.
+   *
+   * A bundle from a server that sends no counts falls back to the older
+   * timestamp prune, and the entry is left out of sync so it is never used to
+   * answer on its own.
    */
   applyCompaction(bundle) {
     if (typeof bundle !== "object" || bundle === null) return;
@@ -1806,22 +2175,84 @@ var ShortTermStore = class {
     );
     if (!conversationId) return;
     const endTs = parseIso(cc["end_timestamp"] ?? cc["compacted_at"]);
+    const compactedAt = parseIso(cc["compacted_at"]);
+    const compactedCount = Number(cc["compacted_message_count"] ?? 0) || 0;
+    const totalCount = Number(cc["total_message_count"] ?? 0) || 0;
     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;
+    const heldAt = parseIso(entry.compactedAt);
+    if (compactedAt !== null && heldAt !== null && compactedAt < heldAt) return;
+    const block = contextBlockOf(cc);
+    if (block) {
+      entry.contextBlock = block;
+      entry.summary = cc["summary"] || block;
+      entry.factualParagraph = null;
+      entry.conversationalParagraph = null;
+    } else {
+      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));
+    if (compactedCount > 0 && compactedCount <= totalCount) {
+      const uncovered = totalCount - compactedCount;
+      const serverTurns = Array.isArray(cc["recent_turns"]) ? cc["recent_turns"] : [];
+      const tail = uncovered > 0 ? serverTurns.slice(-uncovered).map((t) => ({ ...t })) : [];
+      const ahead = localMessageCount(entry) - totalCount;
+      const newer = entry.synced && ahead > 0 ? entry.recentTurns.slice(-ahead).filter((t) => !heldIn(t, tail)) : [];
+      entry.recentTurns = [...tail, ...newer];
+      entry.compactedMessageCount = compactedCount;
+      entry.serverMessageCount = Math.max(entry.serverMessageCount ?? 0, totalCount);
+      entry.synced = tail.length === uncovered;
+    } else {
+      if (endTs !== null && entry.recentTurns.length > 0) {
+        entry.recentTurns = entry.recentTurns.filter((t) => isAfter(t.timestamp, endTs));
+      }
+      entry.synced = false;
     }
     entry.lastActivityAt = this.#now();
     this.#touch(conversationId, entry);
     this.#evict();
   }
+  /**
+   * Bring an entry back in step from a `/context-for-prompt` response.
+   *
+   * Called after the server was asked because the entry was not complete. The
+   * response lists every message the server's summary does not cover, which is
+   * what `recentTurns` is meant to hold.
+   *
+   * Only an entry that already exists is reseeded. Creating one here would let
+   * a process that never writes to the conversation answer from a snapshot it
+   * has no way to refresh.
+   *
+   * If the server's summary is not the one cached here, the entry cannot
+   * render it, so it stays out of sync until the next bundle brings the
+   * summary itself.
+   *
+   * Turns held locally and absent from the response are kept when they come
+   * after everything the response has: they were written or sent after the
+   * server read its messages.
+   */
+  reseed(conversationId, state) {
+    if (!conversationId) return;
+    const entry = this.#entries.get(conversationId);
+    if (entry === void 0 || entry.shared) return;
+    entry.serverMessageCount = Math.max(
+      entry.serverMessageCount ?? 0,
+      Number(state.totalMessageCount) || 0
+    );
+    if ((state.compactionId || null) !== entry.compactionId) {
+      entry.synced = false;
+      return;
+    }
+    const serverTurns = state.recentMessages.map((m) => ({ ...m }));
+    entry.recentTurns = [...serverTurns, ...turnsAfter(entry.recentTurns, serverTurns)];
+    entry.compactedMessageCount = Number(state.compactedMessageCount) || 0;
+    entry.synced = true;
+  }
   invalidate(conversationId) {
     this.#entries.delete(conversationId);
   }
@@ -1832,6 +2263,7 @@ var ShortTermStore = class {
     return {
       conversationId,
       summary: null,
+      contextBlock: null,
       factualParagraph: null,
       conversationalParagraph: null,
       currentState: {},
@@ -1840,7 +2272,12 @@ var ShortTermStore = class {
       compactedAt: null,
       endTimestamp: null,
       recentTurns: [],
-      lastActivityAt: this.#now()
+      lastActivityAt: this.#now(),
+      compactedMessageCount: 0,
+      serverMessageCount: null,
+      participant: false,
+      synced: false,
+      shared: false
     };
   }
   /** Re-insert so this key becomes the most recently used. */
@@ -1857,6 +2294,520 @@ var ShortTermStore = class {
   }
 };
 
+// src/cache/turn-store.ts
+var SWEEP_EVERY_WRITES = 50;
+function bytesOf(text) {
+  return new TextEncoder().encode(text).length;
+}
+var TurnStore = class {
+  limits;
+  onDisk = false;
+  #now;
+  #seq = 0;
+  #writes = 0;
+  #conversations = /* @__PURE__ */ new Map();
+  #vectors = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.limits = options.limits ?? { ...HISTORY_SEARCH.store_limits };
+    this.#now = options.now ?? (() => Date.now() / 1e3);
+  }
+  add(conversationId, role, content, timestamp, options = {}) {
+    this.addMany(conversationId, [
+      { role, content, timestamp: timestamp ?? "", message_id: options.messageId ?? null, position: options.position ?? null }
+    ]);
+  }
+  /**
+   * Insert turns not held yet; returns how many were new. A turn held without
+   * an id or position (a streamed write) gets them when the same role and
+   * text come back from the server.
+   */
+  addMany(conversationId, turns) {
+    if (!conversationId) return 0;
+    const conv = this.#conversations.get(conversationId) ?? { lastActivity: 0, turns: [] };
+    let added = 0;
+    for (const turn of turns) {
+      const role = String(turn.role || "user");
+      const content = String(turn.content ?? "");
+      if (!content) continue;
+      const messageId = turn.message_id ? String(turn.message_id) : null;
+      const raw = turn.position;
+      const position = typeof raw === "number" && Number.isInteger(raw) ? raw : /^\d+$/.test(String(raw ?? "")) ? Number(raw) : null;
+      const ts = turn.timestamp instanceof Date ? turn.timestamp.toISOString() : String(turn.timestamp ?? "");
+      if (messageId !== null) {
+        const held = conv.turns.find((t) => t.message_id === messageId);
+        if (held !== void 0) {
+          if (position !== null) held.position = position;
+          continue;
+        }
+      }
+      const same = conv.turns.find(
+        (t) => t.role === role && t.content === content && (t.message_id === null || t.position === null)
+      );
+      if (same !== void 0) {
+        same.message_id = same.message_id ?? messageId;
+        same.position = position ?? same.position;
+        continue;
+      }
+      conv.turns.push({ seq: ++this.#seq, role, content, timestamp: ts, message_id: messageId, position });
+      added += 1;
+    }
+    conv.lastActivity = this.#now();
+    this.#conversations.set(conversationId, conv);
+    this.#trim(conv);
+    this.#writes += 1;
+    if (this.#writes % SWEEP_EVERY_WRITES === 0) this.sweep();
+    return added;
+  }
+  #trim(conv) {
+    const limits = this.limits;
+    let size = conv.turns.reduce((n2, t) => n2 + bytesOf(t.content), 0);
+    while (conv.turns.length > limits.max_turns_per_conversation || size > limits.max_bytes_per_conversation) {
+      const excess = Math.max(conv.turns.length - limits.max_turns_per_conversation, 1);
+      const order = [...conv.turns].sort(
+        (a, b) => (a.position ?? Number.MAX_SAFE_INTEGER) - (b.position ?? Number.MAX_SAFE_INTEGER) || a.seq - b.seq
+      );
+      const gone = new Set(order.slice(0, excess).map((t) => t.seq));
+      if (gone.size === 0) break;
+      for (const t of conv.turns) if (gone.has(t.seq)) size -= bytesOf(t.content);
+      conv.turns = conv.turns.filter((t) => !gone.has(t.seq));
+      for (const vectors of this.#vectors.values()) for (const seq of gone) vectors.delete(seq);
+    }
+  }
+  /** Idle conversations, then the least recently used beyond the count, then more until the bytes fit. */
+  sweep() {
+    const limits = this.limits;
+    const now = this.#now();
+    for (const [id, conv] of this.#conversations) {
+      if (conv.lastActivity < now - limits.idle_ttl_seconds) this.drop(id);
+    }
+    const byRecent = [...this.#conversations.entries()].sort((a, b) => b[1].lastActivity - a[1].lastActivity);
+    for (const [id] of byRecent.slice(limits.max_conversations)) this.drop(id);
+    while (this.sizeBytes() > limits.max_file_bytes) {
+      const oldest = this.conversations()[0];
+      if (oldest === void 0) break;
+      this.drop(oldest);
+    }
+  }
+  drop(conversationId) {
+    const conv = this.#conversations.get(conversationId);
+    if (conv === void 0) return;
+    for (const vectors of this.#vectors.values()) for (const t of conv.turns) vectors.delete(t.seq);
+    this.#conversations.delete(conversationId);
+  }
+  clear() {
+    this.#conversations.clear();
+    this.#vectors.clear();
+  }
+  close() {
+  }
+  /** In conversation order: by server position where known, else as written here. */
+  turns(conversationId) {
+    const conv = this.#conversations.get(conversationId);
+    if (conv === void 0) return [];
+    const bySeq = [...conv.turns].sort((a, b) => a.seq - b.seq);
+    const key = /* @__PURE__ */ new Map();
+    let top = 0;
+    let step = 0;
+    for (const t of bySeq) {
+      if (t.position !== null) {
+        key.set(t.seq, t.position);
+        top = Math.max(top, t.position);
+        step = 0;
+      } else {
+        step += 1;
+        key.set(t.seq, top + step * 1e-6);
+      }
+    }
+    return bySeq.sort((a, b) => (key.get(a.seq) ?? 0) - (key.get(b.seq) ?? 0) || a.seq - b.seq).map((t) => ({ ...t }));
+  }
+  /** Turns the server also holds: archived tool results are local only. Python: `count`. */
+  count(conversationId) {
+    return (this.#conversations.get(conversationId)?.turns ?? []).filter((t) => t.role !== "tool").length;
+  }
+  sizeBytes() {
+    let n2 = 0;
+    for (const conv of this.#conversations.values()) for (const t of conv.turns) n2 += bytesOf(t.content);
+    return n2;
+  }
+  /** Conversation ids, least recently active first. */
+  conversations() {
+    return [...this.#conversations.entries()].sort((a, b) => a[1].lastActivity - b[1].lastActivity).map(([id]) => id);
+  }
+  vectors(seqs, model) {
+    const held = this.#vectors.get(model);
+    const out = /* @__PURE__ */ new Map();
+    if (held === void 0) return out;
+    for (const seq of seqs) {
+      const v = held.get(seq);
+      if (v !== void 0) out.set(seq, v);
+    }
+    return out;
+  }
+  putVectors(model, items) {
+    const held = this.#vectors.get(model) ?? /* @__PURE__ */ new Map();
+    for (const [seq, vec] of items) held.set(seq, vec);
+    this.#vectors.set(model, held);
+  }
+};
+
+// src/cache/history-search.ts
+var WORD_RE = /[\p{L}\p{N}\p{M}]+/gu;
+var FORMS = HISTORY_SEARCH.irregular_forms ?? {};
+function tokenize2(text) {
+  const out = [];
+  for (const word of (text || "").toLowerCase().match(WORD_RE) ?? []) {
+    if (/^[\x00-\x7f]+$/.test(word)) out.push(...tokenize(FORMS[word] ?? word));
+    else out.push(word);
+  }
+  return out;
+}
+var LITERAL_SOURCE = String.raw`"([^"]{3,})"|\b([A-Z0-9][A-Z0-9-]{3,})\b|(\d[\d,.:/-]*\d|\d)`;
+var SENTENCE_RE = /(?<=[.!?])\s+/;
+function literalsOf(query) {
+  const out = [];
+  for (const m of (query || "").matchAll(new RegExp(LITERAL_SOURCE, "g"))) {
+    const quoted = m[1];
+    const value = quoted || m[2] || m[3];
+    if (value && (quoted || /\d/.test(value))) out.push(value.toLowerCase());
+  }
+  return out;
+}
+function cosine(a, b) {
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  const n2 = Math.min(a.length, b.length);
+  for (let i = 0; i < n2; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  return na && nb ? dot / (Math.sqrt(na) * Math.sqrt(nb)) : 0;
+}
+function words(text) {
+  return text.split(/\s+/).filter(Boolean);
+}
+function excerptOf(content, terms, literals, maxWords) {
+  let sentences = content.trim().split(SENTENCE_RE).filter((s2) => s2.trim());
+  if (sentences.length === 0) sentences = [content.trim()];
+  const score = (sentence) => {
+    const low = sentence.toLowerCase();
+    const held = new Set(tokenize2(sentence));
+    let n2 = 0;
+    for (const t of terms) if (held.has(t)) n2 += 1;
+    for (const lit of literals) if (low.includes(lit)) n2 += 2;
+    return n2;
+  };
+  let best = 0;
+  for (let i = 1; i < sentences.length; i++) if (score(sentences[i]) > score(sentences[best])) best = i;
+  let lo = best;
+  let hi = best;
+  let count = words(sentences[best]).length;
+  for (; ; ) {
+    let grew = false;
+    for (const j of [hi + 1, lo - 1]) {
+      if (j >= 0 && j < sentences.length && count + words(sentences[j]).length <= maxWords) {
+        count += words(sentences[j]).length;
+        lo = Math.min(lo, j);
+        hi = Math.max(hi, j);
+        grew = true;
+      }
+    }
+    if (!grew) break;
+  }
+  let text = sentences.slice(lo, hi + 1).join(" ");
+  if (words(text).length > maxWords) text = words(text).slice(0, maxWords).join(" ") + " ...";
+  return (lo > 0 ? "... " : "") + text + (hi < sentences.length - 1 && !text.endsWith("...") ? " ..." : "");
+}
+var FENCE = /^\s*(?:```|~~~)/;
+var TABLE_RULE = /^\s*\|?\s*:?-{2,}/;
+var SENTENCE = /(?<=[.!?])\s+/;
+function splitPassages(content, maxWords) {
+  const text = (content ?? "").trim();
+  if (words(text).length <= maxWords) return text ? [text] : [];
+  const out = [];
+  const lines = text.split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (FENCE.test(line)) {
+      let j2 = i + 1;
+      while (j2 < lines.length && !FENCE.test(lines[j2])) j2 += 1;
+      out.push(...windowsOf(lines.slice(i + 1, j2), maxWords));
+      i = j2 + 1;
+      continue;
+    }
+    if (line.trim().startsWith("|")) {
+      let j2 = i;
+      while (j2 < lines.length && lines[j2].trim().startsWith("|")) j2 += 1;
+      const rows = lines.slice(i, j2).filter((r) => !TABLE_RULE.test(r)).map((r) => r.trim());
+      const [header, body] = rows.length > 1 ? [rows[0], rows.slice(1)] : ["", rows];
+      for (const row of body) {
+        const both = `${header} ${row}`.trim();
+        out.push(words(both).length <= Math.trunc(maxWords * 3 / 2) ? both : row);
+      }
+      i = j2;
+      continue;
+    }
+    let j = i;
+    while (j < lines.length && lines[j].trim() && !FENCE.test(lines[j]) && !lines[j].trim().startsWith("|")) j += 1;
+    if (j === i) {
+      i += 1;
+      continue;
+    }
+    const block = lines.slice(i, j);
+    if (block.length > 1 && block.every((b) => words(b).length <= 25)) {
+      out.push(...windowsOf(block, maxWords));
+    } else {
+      const sentences = block.map((b) => b.trim()).join(" ").split(SENTENCE).filter((x) => x.trim());
+      out.push(...windowsOf(sentences, maxWords));
+    }
+    i = j;
+  }
+  const kept = out.filter((x) => x.trim());
+  return kept.length ? kept : [text];
+}
+function windowsOf(pieces, maxWords) {
+  const out = [];
+  let cur = [];
+  let used = 0;
+  for (const raw of pieces) {
+    const piece = raw.trim();
+    if (!piece) continue;
+    const n2 = words(piece).length;
+    if (cur.length && used + n2 > maxWords) {
+      out.push(cur.join(" "));
+      cur = [];
+      used = 0;
+    }
+    if (n2 > maxWords) {
+      const w = words(piece);
+      for (let k = 0; k < w.length; k += maxWords) out.push(w.slice(k, k + maxWords).join(" "));
+      continue;
+    }
+    cur.push(piece);
+    used += n2;
+  }
+  if (cur.length) out.push(cur.join(" "));
+  return out;
+}
+function askedKinds(query) {
+  const out = [];
+  for (const [name, spec] of Object.entries(HISTORY_SEARCH.asked_kinds ?? {})) {
+    if (name.startsWith("$") || typeof spec !== "object") continue;
+    if (new RegExp(spec.query, "i").test(query ?? "")) out.push(new RegExp(spec.value));
+  }
+  return out;
+}
+function asksHowItStarted(query) {
+  const spec = HISTORY_SEARCH.early_query;
+  if (!spec?.pattern) return false;
+  return new RegExp(spec.pattern, (spec.flags ?? "").includes("i") ? "i" : "").test(query ?? "");
+}
+async function searchTurns(turns, query, options = {}) {
+  const params = HISTORY_SEARCH;
+  const k = params.max_excerpts;
+  const skip = new Set(options.exclude ?? []);
+  const pool = turns.filter((t) => t.content && !skip.has(t.content) && !skip.has(t.message_id ?? ""));
+  const terms = new Set(tokenize2(query || ""));
+  const literals = literalsOf(query);
+  if (pool.length === 0 || terms.size === 0 && literals.length === 0 && !options.encoder) return [];
+  const maxWords = params.max_words_per_excerpt;
+  const units = [];
+  pool.forEach((t, ti) => {
+    if (!params.passages) {
+      units.push({ seq: t.seq, content: t.content, turn: ti, first: true, last: true, part: -1 });
+      return;
+    }
+    const parts = splitPassages(t.content, maxWords);
+    parts.forEach((part, pi) => {
+      units.push({
+        seq: t.seq,
+        content: part,
+        turn: ti,
+        first: pi === 0,
+        last: pi === parts.length - 1,
+        part: parts.length > 1 ? pi : -1
+      });
+    });
+  });
+  const docs = units.map((u) => tokenize2(u.content));
+  const bm = new BM25(docs);
+  const termList = [...terms];
+  const rows = units.map((turn, i) => {
+    const held = new Set(docs[i]);
+    let matched = 0;
+    for (const t of terms) if (held.has(t)) matched += 1;
+    const low = turn.content.toLowerCase();
+    let literal = 0;
+    for (const lit of literals) if (low.includes(lit)) literal += 1;
+    return { i, bm25: matched ? bm.score(termList, i) : 0, matched, literal };
+  });
+  const need = Math.min(params.min_matched_terms, Math.max(1, terms.size));
+  const rareCap = Math.max(1, Math.trunc((params.rare_term_max_share ?? 0) * units.length));
+  const rare = /* @__PURE__ */ new Set();
+  for (const t of terms) {
+    let n3 = 0;
+    for (const doc of docs) if (doc.includes(t)) n3 += 1;
+    if (n3 > 0 && n3 <= rareCap) rare.add(t);
+  }
+  let eligible;
+  if (params.passages) {
+    const turnTerms = /* @__PURE__ */ new Map();
+    for (const r of rows) {
+      const held = turnTerms.get(units[r.i].turn) ?? /* @__PURE__ */ new Set();
+      for (const t of docs[r.i]) if (terms.has(t)) held.add(t);
+      turnTerms.set(units[r.i].turn, held);
+    }
+    eligible = rows.filter(
+      (r) => r.literal > 0 || r.matched > 0 && (turnTerms.get(units[r.i].turn).size >= need || docs[r.i].some((t) => rare.has(t)))
+    );
+  } else {
+    eligible = rows.filter(
+      (r) => r.literal > 0 || r.matched >= need || r.matched > 0 && docs[r.i].some((t) => rare.has(t))
+    );
+  }
+  const rrf = params.rrf_k;
+  const fused = /* @__PURE__ */ new Map();
+  const via = /* @__PURE__ */ new Map();
+  for (const r of eligible) fused.set(r.i, 0);
+  const add = (i, rank, how) => {
+    fused.set(i, (fused.get(i) ?? 0) + 1 / (rrf + rank + 1));
+    if (!via.has(i)) via.set(i, how);
+  };
+  eligible.filter((r) => r.literal > 0).sort((a, b) => b.literal - a.literal || a.i - b.i).forEach((r, rank) => add(r.i, rank, "literal"));
+  eligible.filter((r) => r.bm25 > 0).sort((a, b) => b.bm25 - a.bm25 || a.i - b.i).forEach((r, rank) => add(r.i, rank, "bm25"));
+  const kinds = askedKinds(query);
+  if (kinds.length) {
+    rows.filter((r) => r.matched > 0 && kinds.some((k2) => k2.test(units[r.i].content))).sort((a, b) => b.bm25 - a.bm25 || a.i - b.i).forEach((r, rank) => add(r.i, rank, "kind"));
+  }
+  if (options.encoder) {
+    const ranked2 = await embeddingRanks(units, query, options.encoder, options.store ?? null, params.min_cosine ?? 0.4);
+    ranked2.forEach(([i], rank) => add(i, rank, "embedding"));
+  }
+  if (fused.size === 0) return [];
+  const n2 = Math.max(pool.length - 1, 1);
+  const weight = asksHowItStarted(query) ? 0 : params.recency_weight;
+  const top = /* @__PURE__ */ new Map();
+  const ranked = /* @__PURE__ */ new Map();
+  for (const [u, v] of fused) {
+    const ti = units[u].turn;
+    const score = v + weight * (ti / n2) / (rrf + 1);
+    ranked.set(ti, [...ranked.get(ti) ?? [], [score, u]]);
+    const held = top.get(ti);
+    if (!held || score > held[0]) top.set(ti, [score, u]);
+  }
+  const best = [...top.keys()].sort((a, b) => top.get(b)[0] - top.get(a)[0] || a - b).slice(0, k);
+  const perTurn = params.passages_per_turn ?? 1;
+  const shown = (ti) => {
+    const unit = units[top.get(ti)[1]];
+    if (!params.passages || unit.first && unit.last) return excerptOf(pool[ti].content, terms, literals, maxWords);
+    const picked = [...ranked.get(ti)].sort((a, b) => b[0] - a[0] || b[1] - a[1]).slice(0, perTurn).map(([, u]) => u).sort((a, b) => a - b);
+    const parts = [];
+    for (const u of picked) parts.push((units[u].first || parts.length ? "" : "... ") + units[u].content);
+    return parts.join(" ... ") + (units[picked[picked.length - 1]].last ? "" : " ...");
+  };
+  const found = /* @__PURE__ */ new Map();
+  for (const ti of best) {
+    found.set(ti, {
+      position: pool[ti].position,
+      role: pool[ti].role,
+      timestamp: pool[ti].timestamp,
+      score: top.get(ti)[0],
+      via: via.get(top.get(ti)[1]) ?? "",
+      text: shown(ti)
+    });
+  }
+  const before2 = params.previous_turns ?? 0;
+  const tail = params.previous_turn_words ?? 40;
+  for (const i of best) {
+    for (let j = i - before2; j < i; j++) {
+      if (j < 0 || found.has(j)) continue;
+      const hit = pool[i].position;
+      const prev = pool[j].position;
+      if (hit && prev && hit - prev > before2) continue;
+      const w = words(pool[j].content);
+      found.set(j, {
+        position: prev,
+        role: pool[j].role,
+        timestamp: pool[j].timestamp,
+        score: 0,
+        via: "previous",
+        text: w.length <= tail ? w.join(" ") : "... " + w.slice(-tail).join(" ")
+      });
+    }
+  }
+  return [...found.keys()].sort((a, b) => a - b).map((i) => found.get(i));
+}
+async function embeddingRanks(pool, query, encoder, store, minCosine) {
+  const keyOf = (u) => (u.part ?? -1) < 0 ? encoder.model : `${encoder.model}#p${u.part}`;
+  const vectors = /* @__PURE__ */ new Map();
+  if (store !== null) {
+    const byKey = /* @__PURE__ */ new Map();
+    pool.forEach((u, i) => byKey.set(keyOf(u), [...byKey.get(keyOf(u)) ?? [], i]));
+    for (const [key, idx] of byKey) {
+      const held = store.vectors(idx.map((i) => pool[i].seq), key);
+      for (const i of idx) {
+        const v = held.get(pool[i].seq);
+        if (v) vectors.set(i, v);
+      }
+    }
+  }
+  const missing = pool.map((_, i) => i).filter((i) => !vectors.has(i));
+  if (missing.length > 0) {
+    const fresh = await encoder.encode(missing.map((i) => pool[i].content));
+    const put = /* @__PURE__ */ new Map();
+    missing.forEach((i, j) => {
+      const v = Float32Array.from(fresh[j] ?? []);
+      vectors.set(i, v);
+      const key = keyOf(pool[i]);
+      put.set(key, (put.get(key) ?? /* @__PURE__ */ new Map()).set(pool[i].seq, v));
+    });
+    if (store) for (const [key, items] of put) store.putVectors(key, items);
+  }
+  const q = (await (encoder.encodeQuery ?? encoder.encode).call(encoder, [query]))[0] ?? [];
+  return pool.map((_, i) => [i, cosine(q, vectors.get(i) ?? [])]).filter(([, c]) => c >= minCosine).sort((a, b) => b[1] - a[1]);
+}
+function toolResultText(result, toolName) {
+  let text = typeof result === "string" ? result : JSON.stringify(result) ?? String(result);
+  const limit = HISTORY_SEARCH.tool_result_max_chars ?? 16e3;
+  if (text.length > limit) text = text.slice(0, limit) + " ...[cut]";
+  return `[tool result: ${toolName || "tool"}] ${text}`;
+}
+function renderExcerpts(excerpts, latest = "") {
+  if (excerpts.length === 0) return "";
+  const lines = [HISTORY_SEARCH.heading];
+  for (const e of excerpts) {
+    let where = e.position ? `turn ${e.position}, ${e.role}` : `${e.role}, earlier`;
+    if (e.timestamp) {
+      const ago = before(e.timestamp, latest);
+      where += `, ${e.timestamp}` + (ago ? ` (${ago})` : "");
+    }
+    lines.push(`- ${where}: "${e.text}"`);
+  }
+  return lines.join("\n");
+}
+var ZONED = /(?:Z|[+-]\d{2}:\d{2})$/;
+function instant(stamp) {
+  const text = (stamp ?? "").trim();
+  if (!ZONED.test(text)) return null;
+  const ms = Date.parse(text);
+  return Number.isNaN(ms) ? null : ms / 1e3;
+}
+function before(stamp, latest) {
+  const at = instant(stamp);
+  const now = instant(latest);
+  if (at === null || now === null || now < at) return "";
+  const seconds = Math.trunc(now - at);
+  for (const [unit, size] of [["day", 86400], ["hour", 3600], ["minute", 60]]) {
+    if (seconds >= size) {
+      const n2 = Math.trunc(seconds / size);
+      return `${n2} ${unit}${n2 !== 1 ? "s" : ""} before the latest message`;
+    }
+  }
+  return "less than a minute before the latest message";
+}
+
 // src/context/overlay.ts
 var MAX_TURNS = 20;
 var TOKEN_BUDGET = 2e3;
@@ -1885,7 +2836,23 @@ function overlayLocalRecentTurns(response, store, conversationId, configured) {
     if (entry === null) return;
     const existing = response.conversation_context ?? null;
     if (existing !== null && !verbatimOverlayEnabled(configured)) return;
-    const localTurns = budgetRecentTurns(entry.recentTurns);
+    const serverCompaction = existing === null ? null : existing["compaction_id"];
+    const localIsWhole = isComplete(entry) && (!serverCompaction || serverCompaction === entry.compactionId);
+    let sourceTurns = entry.recentTurns;
+    if (existing !== null && !localIsWhole) {
+      const raw = Array.isArray(existing["recent_turns"]) ? existing["recent_turns"] : [];
+      const serverTurns = raw.map((t) => ({
+        role: String(t["role"] ?? "user"),
+        content: String(t["content"] ?? ""),
+        timestamp: String(t["timestamp"] ?? "")
+      }));
+      sourceTurns = [...serverTurns, ...turnsAfter(entry.recentTurns, serverTurns)];
+    }
+    const localTurns = budgetRecentTurns(sourceTurns).map((t) => ({
+      role: t.role,
+      content: t.content,
+      timestamp: t.timestamp
+    }));
     const serverField = (name) => existing === null ? void 0 : existing[name];
     const orLocal = (name, local) => {
       const value = serverField(name);
@@ -1940,14 +2907,28 @@ function buildRecentMessages(turns) {
     role: t.role || "user",
     content: t.content ?? "",
     timestamp: t.timestamp,
-    message_id: `local-${idx}`
+    message_id: t.message_id || `local-${idx}`
   }));
 }
 function compactedMessageCount(_entry) {
   return 0;
 }
+function blockOf(entry) {
+  if (entry.contextBlock) return entry.contextBlock.trim();
+  if (entry.summary && entry.summary.startsWith(CONTEXT_BLOCK_PREFIX)) return entry.summary.trim();
+  return null;
+}
 function formatStructured(entry, recent) {
   const parts = [];
+  const block = blockOf(entry);
+  if (block) {
+    parts.push(block);
+    if (recent.length > 0) {
+      parts.push(`## Recent Turns (${recent.length})`);
+      for (const m of recent) parts.push(`**${m.role}**: ${m.content}`);
+    }
+    return parts.filter(Boolean).join("\n\n").trim();
+  }
   if (entry.summary) {
     parts.push("## Summary");
     parts.push(entry.summary.trim());
@@ -1982,9 +2963,11 @@ function formatStructured(entry, recent) {
 }
 function formatNarrative(entry, recent) {
   const parts = [];
-  if (entry.summary) parts.push(entry.summary.trim());
-  if (entry.conversationalParagraph) parts.push(entry.conversationalParagraph.trim());
-  else if (entry.factualParagraph) parts.push(entry.factualParagraph.trim());
+  const block = blockOf(entry);
+  if (block) parts.push(block);
+  else if (entry.summary) parts.push(entry.summary.trim());
+  if (!block && entry.conversationalParagraph) parts.push(entry.conversationalParagraph.trim());
+  else if (!block && entry.factualParagraph) parts.push(entry.factualParagraph.trim());
   if (recent.length > 0) {
     const tail = recent.map((m) => `${m.role}: ${m.content}`).join("\n");
     parts.push(`Recent exchanges:
@@ -1994,6 +2977,10 @@ ${tail}`);
 }
 function formatBullets(entry, recent) {
   const parts = [];
+  const block = blockOf(entry);
+  if (block) {
+    return [block, ...recent.map((m) => `- ${m.role}: ${m.content}`)].join("\n").trim();
+  }
   if (entry.summary) parts.push(`- Summary: ${entry.summary.trim()}`);
   for (const [k, v] of Object.entries(entry.currentState ?? {})) {
     parts.push(`- ${k}: ${stringify(v)}`);
@@ -2031,7 +3018,9 @@ function renderForPrompt(entry, style = DEFAULT_STYLE, now = Date.now) {
     recent_messages: recent,
     recent_message_count: recent.length,
     compacted_message_count: compacted,
-    total_message_count: recent.length + compacted
+    total_message_count: recent.length + compacted,
+    context_block: blockOf(entry),
+    compaction_id: entry.compactionId
   };
 }
 function renderCompacted(entry, format = "structured", correlationId = "") {
@@ -2176,10 +3165,10 @@ function servedItemIds(hit) {
   }
   return ids;
 }
-function tryServeFromCache(cache, scope, params, maxItems) {
+async function tryServeFromCache(cache, scope, params, maxItems) {
   try {
     const scoped = scopeLookupParams(scope, params);
-    const hit = cache.lookup({
+    const hit = await cache.lookupAsync({
       searchQuery: scoped.searchQuery ?? null,
       entityId: scoped.entityId ?? null,
       customerId: scoped.customerId ?? null,
@@ -2267,6 +3256,8 @@ function mergeScopeResults(scopeResults) {
     episodes: [],
     emotions: [],
     temporal_events: [],
+    items: [],
+    excerpts: [],
     scope_map: {},
     conversation_context: null,
     profile: null,
@@ -2276,6 +3267,8 @@ function mergeScopeResults(scopeResults) {
     total_items: 0,
     metadata: null
   };
+  const rankedSeen = /* @__PURE__ */ new Set();
+  const rankedItems = [];
   for (const [scopeName, response] of scopeResults) {
     out.scopes_queried.push(scopeName);
     if (out.metadata === null && response.metadata !== void 0) {
@@ -2300,8 +3293,32 @@ function mergeScopeResults(scopeResults) {
         out[collection].push(item);
       }
     }
+    const excerpts = response["excerpts"];
+    if (Array.isArray(excerpts)) {
+      for (const item of excerpts) {
+        const id = itemId2(item);
+        if (id !== void 0) {
+          if (seen.has(id)) continue;
+          seen.add(id);
+          out.scope_map[id] = scopeName;
+        }
+        out.excerpts.push(item);
+      }
+    }
+    const ranked = response["items"];
+    if (Array.isArray(ranked)) {
+      for (const item of ranked) {
+        const id = itemId2(item);
+        if (id !== void 0) {
+          if (rankedSeen.has(id)) continue;
+          rankedSeen.add(id);
+        }
+        rankedItems.push(item);
+      }
+    }
   }
-  out.total_items = ITEM_COLLECTIONS.reduce((n2, c) => n2 + out[c].length, 0);
+  out.items = sortByRankScore(rankedItems).map((item, n2) => ({ ...item, rank: n2 + 1 }));
+  out.total_items = ITEM_COLLECTIONS.reduce((n2, c) => n2 + out[c].length, 0) + out.excerpts.length;
   return out;
 }
 function oneDecimal(value) {
@@ -2327,7 +3344,18 @@ function formatForPrompt(ctx, options = {}) {
   const includeScope = options.includeScope ?? false;
   const includeConversationContext = options.includeConversationContext ?? true;
   const sections = [];
-  if (ctx.facts.length > 0) {
+  const ranked = ctx.items ?? [];
+  if (ranked.length > 0) {
+    const lines = ranked.map((it, n2) => {
+      let label = rankedLabel(String(it["category"] ?? ""));
+      if (includeScope) label += `, scope: ${scopeOf(ctx, it)}`;
+      return `${n2 + 1}. [${label}] ${String(it.content ?? "")}`;
+    });
+    sections.push(`### Memories
+${lines.join("\n")}`);
+  }
+  const typed = ranked.length === 0;
+  if (typed && ctx.facts.length > 0) {
     const lines = ctx.facts.map((f) => {
       let line = `- ${String(f.content ?? "")}`;
       if (includeScope) line += ` [scope: ${scopeOf(ctx, f)}]`;
@@ -2336,7 +3364,7 @@ function formatForPrompt(ctx, options = {}) {
     sections.push(`### Facts
 ${lines.join("\n")}`);
   }
-  if (ctx.preferences.length > 0) {
+  if (typed && ctx.preferences.length > 0) {
     const lines = ctx.preferences.map((p) => {
       const extras = [];
       if (includeScope) extras.push(`scope: ${scopeOf(ctx, p)}`);
@@ -2349,7 +3377,7 @@ ${lines.join("\n")}`);
     sections.push(`### Preferences
 ${lines.join("\n")}`);
   }
-  if (ctx.episodes.length > 0) {
+  if (typed && ctx.episodes.length > 0) {
     const lines = ctx.episodes.map((e) => {
       let line = `- ${String(e["summary"] ?? "")}`;
       if (includeScope) line += ` [scope: ${scopeOf(ctx, e)}]`;
@@ -2358,7 +3386,7 @@ ${lines.join("\n")}`);
     sections.push(`### Episodes
 ${lines.join("\n")}`);
   }
-  if (ctx.emotions.length > 0) {
+  if (typed && ctx.emotions.length > 0) {
     const lines = ctx.emotions.map((em) => {
       const extras = [];
       if (includeScope) extras.push(`scope: ${scopeOf(ctx, em)}`);
@@ -2372,7 +3400,7 @@ ${lines.join("\n")}`);
     sections.push(`### Emotions
 ${lines.join("\n")}`);
   }
-  if (ctx.temporal_events.length > 0) {
+  if (typed && ctx.temporal_events.length > 0) {
     const lines = ctx.temporal_events.map((te) => {
       const extras = [];
       if (includeScope) extras.push(`scope: ${scopeOf(ctx, te)}`);
@@ -2626,7 +3654,10 @@ function buildTool(target, options = {}, onWarning = () => {
 }
 
 // src/client.ts
-var SynapClient = class {
+function localModelOff() {
+  return ["off", "0", "false", "no", "none"].includes((getEnv("SYNAP_SDK_LOCAL_MODEL") ?? "").trim().toLowerCase());
+}
+var SynapClient = class _SynapClient {
   // Native-private (`#`), not TypeScript `private`. TS `private` is erased at
   // compile time, so the field stays enumerable at runtime and a JS consumer
   // can still reach it. These two were public and made `client.transport
@@ -2649,10 +3680,20 @@ var SynapClient = class {
   instance;
   #closed = false;
   #initialized = false;
+  #identity;
   #registryKeys;
   #compactionSubscribers;
   #shortTerm;
+  /** Every raw turn, past compaction, for local history search. */
+  #turnStore;
+  /** A local embedding model for history search; null = keywords only. */
+  #localEncoder = null;
+  /** `history_search_model`: "auto", an "onnx:..." name, or null for none. */
+  #localModelName = "auto";
+  #localModelStarted = false;
+  #backfillAfter = /* @__PURE__ */ new Map();
   #stVerbatimOverlay;
+  #agentModel = {};
   #logger;
   #stAuthoritative;
   #turns;
@@ -2690,13 +3731,14 @@ var SynapClient = class {
       userAgent: `@maximem/synap-js-sdk/${SDK_VERSION}`
     });
     if (options.heartbeat) this.#transport.startHeartbeat();
+    this.#transport.identityResolver = () => this.#resolveIdentity();
     this.#anticipationCache = new AnticipationCache();
     this.#fetchHooks = {
-      beforeFetch: (scope, options2) => {
+      beforeFetch: async (scope, options2) => {
         const o2 = options2;
         if (o2["query_date"] ?? o2["queryDate"]) return null;
         if (o2["max_results_per_query"] ?? o2["maxResultsPerQuery"]) return null;
-        const attempt = tryServeFromCache(
+        const attempt = await tryServeFromCache(
           this.#anticipationCache,
           scope,
           {
@@ -2720,7 +3762,9 @@ var SynapClient = class {
         return {
           response: attempt.response,
           servedItemIds: servedItemIds(attempt.hit),
-          bundleId: attempt.hit.bundleIds[0] ?? ""
+          bundleId: attempt.hit.bundleIds[0] ?? "",
+          borderline: attempt.hit.band === "borderline",
+          raceDeadlineMs: SEMANTIC_MATCH.race_deadline_ms
         };
       },
       onAssembled: (scope, options2, response, startedAt) => {
@@ -2735,9 +3779,19 @@ var SynapClient = class {
     this.client = { context: { fetch: async (o2 = {}) => fetchContext(this.#transport, "client", o2, this.#fetchHooks) } };
     this.#compactionSubscribers = new CompactionSubscribers();
     this.#shortTerm = new ShortTermStore();
+    this.#turnStore = new TurnStore();
+    this.#shortTerm.attachArchive(this.#turnStore);
     this.#stVerbatimOverlay = options.st_verbatim_overlay ?? options.stVerbatimOverlay;
+    this.#agentModel = {
+      model: options.agent_model ?? options.agentModel,
+      contextWindow: options.agent_context_window ?? options.agentContextWindow
+    };
     this.#logger = options.logger;
     this.#stAuthoritative = options.sdk_st_authoritative ?? options.sdkStAuthoritative;
+    this.#localEncoder = options.history_search_encoder ?? options.historySearchEncoder ?? null;
+    const modelOption = options.history_search_model !== void 0 ? options.history_search_model : options.historySearchModel;
+    this.#localModelName = modelOption === void 0 ? "auto" : modelOption;
+    if (this.#localEncoder?.model === SEMANTIC_MATCH.model) this.#anticipationCache.setEncoder(this.#localEncoder);
     this.#turns = new TurnCounter();
     this.conversation = createConversationNamespace(
       this.#transport,
@@ -2754,8 +3808,12 @@ var SynapClient = class {
       },
       // 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);
+      ({ conversationId, role, content, timestamp, messageId, serverMessageCount, inFlight }) => {
+        this.#shortTerm.appendTurn(conversationId, role, content, timestamp, {
+          messageId,
+          serverMessageCount,
+          inFlight
+        });
       },
       (response, conversationId, userId, scopePath) => {
         overlayLocalRecentTurns(response, this.#shortTerm, conversationId, this.#stVerbatimOverlay);
@@ -2763,8 +3821,11 @@ var SynapClient = class {
       },
       {
         prompt: (conversationId, style) => this.#localPrompt(conversationId, style),
-        compacted: (conversationId, format) => this.#localCompacted(conversationId, format)
-      }
+        compacted: (conversationId, format) => this.#localCompacted(conversationId, format),
+        reseed: (conversationId, response) => this.#reseedShortTerm(conversationId, response),
+        historyExcerpts: (conversationId, response, query) => this.#withHistoryExcerpts(conversationId, response, query)
+      },
+      () => this.#agentModel
     );
     this.memories = createMemoriesInterface(this.#transport, ({ userId, customerId }) => {
       for (const id of /* @__PURE__ */ new Set([userId, customerId])) {
@@ -2778,11 +3839,17 @@ var SynapClient = class {
       this.#anticipationCache,
       ({ conversationId, role, content }) => {
         this.#shortTerm.appendTurn(conversationId, role, content);
-      }
+      },
+      () => this.#agentModel,
+      ({ conversationId, result, toolName }) => this.archive_tool_result(conversationId, result, { tool_name: toolName })
     );
+    this.instance._internal.setOnListen(() => this.#startLocalModel());
     this.instance._internal.setCompactionApplier((bundle) => {
       this.#shortTerm.applyCompaction(bundle);
     });
+    this.instance._internal.setConversationStateHandler((conversationId, messageCount) => {
+      this.#shortTerm.noteServerCount(conversationId, messageCount);
+    });
     if (options._force_new !== true) {
       const incumbent = registerIfAbsent(registryKey, this);
       if (incumbent !== void 0) return incumbent;
@@ -2870,19 +3937,30 @@ var SynapClient = class {
   /**
    * Resolve `client_id` and `instance_id` from the API key.
    *
-   * Mirrors Python's `initialize()`. Calling it is optional here (unlike
-   * Python, which raises "SDK not initialized" from `_ensure_initialized`)
-   * because every HTTP route authenticates on the API key alone. It matters
-   * for the anticipation cache: a bundle shared at client scope is filtered on
-   * `client_id`, and an empty one fails that filter for every bundle. That was
-   * a silent cache-scope bug in Python before whoami bootstrapping existed.
+   * Mirrors Python's `initialize()`. Python raises "SDK not initialized" on
+   * any call made before it; here the first request runs the same resolution
+   * instead (`identityResolver` on the transport), so skipping this call costs
+   * nothing and breaks no existing caller. It matters for the anticipation
+   * cache: a bundle shared at client scope is filtered on `client_id`, and an
+   * empty one fails that filter for every bundle.
+   *
+   * Calling it explicitly still locks `configure()`, as in Python. Resolving
+   * on first use does not, because a caller who never called it could always
+   * configure after a request, and that keeps working.
    *
    * Best-effort and idempotent. A whoami failure leaves whatever the
    * constructor resolved and is not fatal.
    */
   async initialize() {
-    if (this.#initialized) return;
     this.#initialized = true;
+    await this.#resolveIdentity();
+  }
+  /** Runs whoami at most once, however many calls arrive together. */
+  #resolveIdentity() {
+    this.#identity ??= this.#whoami();
+    return this.#identity;
+  }
+  async #whoami() {
     const credentials = this.#transport.currentCredentials();
     if (credentials.clientId !== "" && credentials.instanceId !== "") return;
     try {
@@ -2942,6 +4020,14 @@ var SynapClient = class {
       this.#transport.setRetryPolicy(options.retryPolicy ?? options.retry_policy ?? null);
     }
     if (options.logger !== void 0) this.#logger = options.logger;
+    const model = options.agent_model ?? options.agentModel;
+    const window = options.agent_context_window ?? options.agentContextWindow;
+    if (model !== void 0 || window !== void 0) {
+      this.#agentModel = {
+        model: model ?? this.#agentModel.model,
+        contextWindow: window ?? this.#agentModel.contextWindow
+      };
+    }
   }
   /**
    * Fetch and merge context across every scope with an identifier, in one call.
@@ -2975,9 +4061,11 @@ var SynapClient = class {
       include_scope_labels: includeScopeLabels = false,
       context_mode: contextMode = "in-conversation",
       include_profile: includeProfile = true,
-      last_n_conversations: lastNConversations = 1
+      last_n_conversations: lastNConversations = 1,
+      response_shape: responseShape = "by_type"
     } = options;
     validateConversationId(conversationId);
+    responseShapeOf({ response_shape: responseShape });
     const wants = (scope) => scopes === void 0 || scopes.includes(scope);
     const shared = {
       search_query: searchQuery,
@@ -2989,7 +4077,8 @@ var SynapClient = class {
       // threaded three call sites by hand and missed the client branch, which
       // sits one indent deeper; spreading removes that whole class of miss.
       query_date: queryDate,
-      max_results_per_query: maxResultsPerQuery
+      max_results_per_query: maxResultsPerQuery,
+      response_shape: responseShape
     };
     const labels = [];
     const tasks = [];
@@ -3152,25 +4241,139 @@ var SynapClient = class {
   /**
    * Whether the SDK is authoritative for short-term context.
    *
-   * Resolution order matches Python's `_is_st_authoritative`: the explicit
-   * option first, then `SYNAP_SDK_ST_AUTHORITATIVE` (truthy strings only).
-   * Defaults to false, so nothing changes for a caller who never sets it.
+   * Resolution order matches Python's `_is_st_authoritative`:
+   * `SYNAP_SDK_ST_AUTHORITATIVE` first, as an explicit override in either
+   * direction, then the option. Off by default. Being enabled does not mean
+   * the local store is used: that also takes an entry that holds the whole
+   * conversation, see `isComplete`.
    */
   #isStAuthoritative() {
-    if (this.#stAuthoritative === true) return true;
     const raw = (getEnv("SYNAP_SDK_ST_AUTHORITATIVE") ?? "").trim().toLowerCase();
-    return ["1", "true", "yes", "on"].includes(raw);
+    if (["0", "false", "no", "off"].includes(raw)) return false;
+    if (["1", "true", "yes", "on"].includes(raw)) return true;
+    return this.#stAuthoritative === true;
   }
   /**
    * Render `get_context_for_prompt` from the local store, or null to fall
-   * through to the network. Warm means a compaction landed OR raw turns are
-   * buffered: with neither there is nothing to render and the server's answer
-   * is the only real one.
+   * through to the network.
+   *
+   * The store answers only when it holds the whole conversation: the server
+   * has confirmed a count the entry accounts for. An entry that is merely
+   * present is not enough. After a restart or an eviction it holds one turn,
+   * and rendering that as the conversation drops everything said before it.
    */
+  /**
+   * `response` with the earlier turns that best match `query` (by default the
+   * latest user message) appended, when a compaction exists. The search runs
+   * here, over the turn archive. Python: `_with_history_excerpts`.
+   */
+  async #withHistoryExcerpts(conversationId, response, query) {
+    const r = response ?? {};
+    const store = this.#turnStore;
+    const recent = Array.isArray(r["recent_messages"]) ? r["recent_messages"] : [];
+    store.addMany(
+      conversationId,
+      recent.map((m) => ({
+        role: String(m["role"] ?? "user"),
+        content: String(m["content"] ?? ""),
+        timestamp: String(m["timestamp"] ?? ""),
+        message_id: typeof m["message_id"] === "string" ? m["message_id"] : null
+      }))
+    );
+    const entry = this.#shortTerm.get(conversationId);
+    const total = Math.max(Number(r["total_message_count"] ?? 0) || 0, Number(entry?.serverMessageCount ?? 0) || 0);
+    this.#maybeBackfillTurns(conversationId, total);
+    if (!r["context_block"]) return response;
+    const turns = store.turns(conversationId);
+    let q = query;
+    if (!q) {
+      const latest = [...recent].reverse().find((m) => m["role"] === "user");
+      q = latest ? String(latest["content"] ?? "") : [...turns].reverse().find((t) => t.role === "user")?.content ?? "";
+    }
+    if (!q) return response;
+    const exclude = /* @__PURE__ */ new Set();
+    for (const m of recent) {
+      if (typeof m["message_id"] === "string" && m["message_id"]) exclude.add(m["message_id"]);
+      exclude.add(String(m["content"] ?? ""));
+    }
+    this.#startLocalModel();
+    const hits = await searchTurns(turns, q, { exclude, encoder: this.#localEncoder, store });
+    if (hits.length === 0) return response;
+    const block = renderExcerpts(hits, turns.length ? turns[turns.length - 1].timestamp : "");
+    return {
+      ...r,
+      history_excerpts: hits.map((h) => ({ position: h.position, role: h.role, text: h.text })),
+      history_block: block,
+      formatted_context: (String(r["formatted_context"] ?? "").trimEnd() + "\n\n" + block).trim()
+    };
+  }
+  /**
+   * Keep what a tool returned in this process's turn archive, so history search
+   * can find it after a compaction. Never sent anywhere: the server's
+   * conversation holds what people said, and a compaction is made from that.
+   * `instance.record_tool_result` calls this too. Python: `archive_tool_result`.
+   */
+  archive_tool_result(conversationId, result, options = {}) {
+    if (!conversationId || result === null || result === void 0) return;
+    try {
+      this.#turnStore.add(
+        conversationId,
+        "tool",
+        toolResultText(result, options.tool_name ?? options.toolName),
+        options.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+      );
+    } catch {
+    }
+  }
+  static BACKFILL_COOLDOWN_MS = 6e4;
+  static BACKFILL_PAGE = 500;
+  /** Fetch, in the background, turns the server holds and the archive does not. */
+  /**
+   * Load the local embedding model in the background, once. Searches and
+   * lookups before it is ready match by words. Python: `_start_history_encoder`.
+   */
+  #startLocalModel() {
+    if (this.#localModelStarted) return;
+    this.#localModelStarted = true;
+    if (localModelOff()) return;
+    const name = this.#localModelName === "auto" ? SEMANTIC_MATCH.model : this.#localModelName;
+    if (!name) return;
+    const callerEncoder = this.#localEncoder;
+    void import("./onnx-encoder-NP35KH4H.js").then(({ canRunLocalModel, loadOnnxEncoder }) => canRunLocalModel() ? loadOnnxEncoder(name) : null).then((encoder) => {
+      if (encoder === null) return;
+      if (callerEncoder === null) this.#localEncoder = encoder;
+      if (encoder.model === SEMANTIC_MATCH.model) this.#anticipationCache.setEncoder(encoder);
+    }).catch(() => {
+    });
+  }
+  #maybeBackfillTurns(conversationId, total) {
+    if (total <= this.#turnStore.count(conversationId)) return;
+    const now = Date.now();
+    if (now < (this.#backfillAfter.get(conversationId) ?? 0)) return;
+    this.#backfillAfter.set(conversationId, now + _SynapClient.BACKFILL_COOLDOWN_MS);
+    void this.#backfillTurns(conversationId, total);
+  }
+  async #backfillTurns(conversationId, total) {
+    try {
+      let start = 1;
+      while (start <= total) {
+        const result = await this.#transport.request("conversation_turns", {
+          pathParams: { conversation_id: conversationId },
+          query: { start, limit: _SynapClient.BACKFILL_PAGE }
+        });
+        const page = (result ?? {})["turns"] ?? [];
+        this.#turnStore.addMany(conversationId, page);
+        if (page.length < _SynapClient.BACKFILL_PAGE) break;
+        start += _SynapClient.BACKFILL_PAGE;
+      }
+    } catch (error) {
+      this.#warn(`Turn backfill for ${conversationId} failed: ${String(error)}`);
+    }
+  }
   #localPrompt(conversationId, style) {
     if (!this.#isStAuthoritative()) return null;
     const entry = this.#shortTerm.get(conversationId);
-    if (entry === null) return null;
+    if (entry === null || !isComplete(entry)) return null;
     if (entry.compactionId === null && entry.recentTurns.length === 0) return null;
     return renderForPrompt(entry, style);
   }
@@ -3178,9 +4381,29 @@ var SynapClient = class {
   #localCompacted(conversationId, format) {
     if (!this.#isStAuthoritative()) return null;
     const entry = this.#shortTerm.get(conversationId);
-    if (entry === null || entry.compactionId === null) return null;
+    if (entry === null || entry.compactionId === null || !isComplete(entry)) return null;
     return renderCompacted(entry, format);
   }
+  /**
+   * Bring the local store back in step from the server's answer.
+   *
+   * Only for a conversation this process writes to. The server's answer lists
+   * every message its summary does not cover, which is exactly what the entry
+   * was missing.
+   */
+  #reseedShortTerm(conversationId, response) {
+    if (!this.#isStAuthoritative()) return;
+    const entry = this.#shortTerm.get(conversationId);
+    if (entry === null || !entry.participant) return;
+    const r = response ?? {};
+    const recent = Array.isArray(r["recent_messages"]) ? r["recent_messages"] : [];
+    this.#shortTerm.reseed(conversationId, {
+      compactionId: typeof r["compaction_id"] === "string" ? r["compaction_id"] : null,
+      recentMessages: recent,
+      compactedMessageCount: Number(r["compacted_message_count"] ?? 0) || 0,
+      totalMessageCount: Number(r["total_message_count"] ?? 0) || 0
+    });
+  }
   /** Every diagnostic the SDK emits passes through here. */
   #warn(message) {
     if (this.#logger !== void 0) {
@@ -3243,6 +4466,7 @@ export {
   DEFAULT_TIMEOUTS,
   DOCUMENT_TYPES,
   ENDPOINTS,
+  EXCERPT_CATEGORY,
   FORGET_MODES,
   HttpTransport,
   INGEST_MODES,
@@ -3253,8 +4477,10 @@ export {
   InvalidInstanceIdError,
   ListeningAlreadyActiveError,
   ListeningNotActiveError,
+  MEMORY_TYPES,
   NetworkTimeoutError,
   PermanentError,
+  RESPONSE_SHAPES,
   RateLimitError,
   SDKError,
   SDK_VERSION,
@@ -3267,15 +4493,18 @@ export {
   THRESHOLDS,
   TranscriptConflictError,
   TransientError,
+  applyResponseShape,
   flattenContextItems,
   formatForPrompt,
   isOutcomeUnknown,
   isRecallQuery,
   isSynapError,
   mergeScopeResults,
+  rankItems,
   resolvePath,
   shouldRetry,
   stem,
-  tokenize
+  tokenize,
+  wireRankScore
 };
 //# sourceMappingURL=index.js.map