@maximem/synap-js-sdk 0.3.0 → 0.4.1

package/dist/index.js

@@ -0,0 +1,2702 @@
+import {
+  AgentUnavailableError,
+  AuthenticationError,
+  ConflictError,
+  ConnectionError,
+  ContextNotFoundError,
+  InsufficientCreditsError,
+  InvalidConversationIdError,
+  InvalidInputError,
+  InvalidInstanceIdError,
+  ListeningAlreadyActiveError,
+  ListeningNotActiveError,
+  NetworkTimeoutError,
+  PermanentError,
+  RateLimitError,
+  SDKError,
+  ServiceUnavailableError,
+  SessionExpiredError,
+  SynapError,
+  SynapPermanentError,
+  SynapTransientError,
+  TranscriptConflictError,
+  TransientError,
+  isSynapError
+} from "./chunk-T3NZBIV2.js";
+import {
+  ANY_SCOPE,
+  AnticipationCache,
+  BM25,
+  CONTRACT,
+  THRESHOLDS,
+  isRecallQuery,
+  stem,
+  tokenize
+} from "./chunk-6LDUDKHS.js";
+import {
+  getEnv
+} from "./chunk-QBCVMPGK.js";
+
+// src/util/correlation.ts
+function newCorrelationId() {
+  const c = globalThis.crypto;
+  if (typeof c?.randomUUID === "function") return c.randomUUID();
+  if (typeof c?.getRandomValues === "function") {
+    const b = c.getRandomValues(new Uint8Array(16));
+    b[6] = (b[6] ?? 0) & 15 | 64;
+    b[8] = (b[8] ?? 0) & 63 | 128;
+    const h = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
+    const r = Math.random() * 16 | 0;
+    return (ch === "x" ? r : r & 3 | 8).toString(16);
+  });
+}
+
+// src/transport/endpoints.ts
+var ENDPOINTS = {
+  whoami: { method: "GET", path: "/api/v1/auth/whoami", idempotent: true },
+  memories_create: { method: "POST", path: "/api/v1/memories/create", idempotent: false },
+  memories_batch: { method: "POST", path: "/api/v1/memories/batch", idempotent: false },
+  memories_upload: { method: "POST", path: "/api/v1/memories/upload", idempotent: false },
+  memories_status: { method: "GET", path: "/api/v1/memories/status/{ingestion_id}", idempotent: true },
+  memories_get: { method: "GET", path: "/api/v1/memories/{memory_id}", idempotent: true },
+  memories_update: { method: "PATCH", path: "/api/v1/memories/{memory_id}", idempotent: false },
+  memories_delete: { method: "DELETE", path: "/api/v1/memories/{memory_id}", idempotent: true },
+  context_fetch_user: { method: "POST", path: "/v1/context/user/fetch", idempotent: true },
+  context_fetch_customer: { method: "POST", path: "/v1/context/customer/fetch", idempotent: true },
+  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 },
+  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 },
+  conversations_compact: { method: "POST", path: "/v1/conversations/compact", idempotent: false },
+  conversations_compacted: { method: "GET", path: "/v1/conversations/{conversation_id}/compacted", idempotent: true },
+  conversations_compaction_status: { method: "GET", path: "/v1/conversations/{conversation_id}/compaction/status", idempotent: true },
+  user_profile: { method: "GET", path: "/v1/users/{user_id}/profile", idempotent: true },
+  credits_balance: { method: "GET", path: "/v1/credits/balance", idempotent: true },
+  credits_ledger: { method: "GET", path: "/v1/credits/ledger", idempotent: true },
+  credits_estimate: { method: "POST", path: "/v1/credits/estimate", idempotent: true },
+  credits_redeem: { method: "POST", path: "/v1/credits/redeem", idempotent: false },
+  telemetry_batch: { method: "POST", path: "/v1/telemetry/batch", idempotent: false }
+};
+function resolvePath(name, params = {}) {
+  return ENDPOINTS[name].path.replace(/\{(\w+)\}/g, (_m, key) => {
+    const value = params[key];
+    if (value === void 0 || value === null || value === "") {
+      throw new Error(
+        `Endpoint ${name} requires path parameter '${key}'.`
+      );
+    }
+    return encodeURIComponent(String(value));
+  });
+}
+
+// src/transport/retry.ts
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "HEAD",
+  "OPTIONS",
+  "PUT",
+  "DELETE"
+]);
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 3,
+  backoffBase: 1,
+  backoffMax: 10,
+  backoffJitter: true
+};
+function shouldRetry(input) {
+  const { error, attempt, policy, method, outcomeUnknown } = input;
+  if (attempt >= policy.maxAttempts) {
+    return { retry: false, delaySeconds: 0, reason: "max_attempts_exhausted" };
+  }
+  if (!isSynapError(error) || !error.transient) {
+    return { retry: false, delaySeconds: 0, reason: "not_transient" };
+  }
+  const idempotent = input.idempotent ?? IDEMPOTENT_METHODS.has(method.toUpperCase());
+  if (outcomeUnknown && !idempotent) {
+    return {
+      retry: false,
+      delaySeconds: 0,
+      reason: "non_idempotent_outcome_unknown"
+    };
+  }
+  return {
+    retry: true,
+    delaySeconds: backoffDelay(error, attempt, policy),
+    reason: "transient_retryable"
+  };
+}
+function backoffDelay(error, attempt, policy) {
+  if (error instanceof RateLimitError && error.retryAfterSeconds != null) {
+    return Math.min(error.retryAfterSeconds, policy.backoffMax);
+  }
+  const exponential = policy.backoffBase * 2 ** (attempt - 1);
+  const capped = Math.min(exponential, policy.backoffMax);
+  if (!policy.backoffJitter) return capped;
+  return Math.random() * capped;
+}
+
+// src/transport/keepalive.ts
+var KEEPALIVE_EXPIRY_MS = 3e5;
+var HEARTBEAT_INTERVAL_MS = 24e4;
+var MAX_CONNECTIONS = 20;
+var cached;
+function supportsDispatcher() {
+  return typeof process !== "undefined" && process.versions?.node !== void 0 && // Edge builds of Next expose a partial `process` shim, but no real Node.
+  typeof globalThis.EdgeRuntime === "undefined";
+}
+async function getKeepAliveDispatcher(options = {}) {
+  if (cached !== void 0) return cached;
+  if (!supportsDispatcher()) {
+    cached = null;
+    return cached;
+  }
+  try {
+    const undici = await import(
+      /* @vite-ignore */
+      "undici"
+    );
+    cached = new undici.Agent({
+      keepAliveTimeout: options.keepAliveExpiryMs ?? KEEPALIVE_EXPIRY_MS,
+      // undici will not honour a keepAliveTimeout above this ceiling.
+      keepAliveMaxTimeout: options.keepAliveExpiryMs ?? KEEPALIVE_EXPIRY_MS,
+      connections: options.maxConnections ?? MAX_CONNECTIONS
+    });
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+var Heartbeat = class {
+  constructor(ping, intervalMs = HEARTBEAT_INTERVAL_MS) {
+    this.ping = ping;
+    this.intervalMs = intervalMs;
+  }
+  ping;
+  intervalMs;
+  timer = null;
+  start() {
+    if (this.timer !== null) return;
+    if (this.intervalMs <= 0) return;
+    if (typeof setInterval !== "function") return;
+    this.timer = setInterval(() => {
+      void Promise.resolve(this.ping()).catch(() => {
+      });
+    }, this.intervalMs);
+    this.timer.unref?.();
+  }
+  stop() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  get running() {
+    return this.timer !== null;
+  }
+};
+
+// src/transport/http.ts
+var DEFAULT_BASE_URL = "https://synap-cloud-prod.maximem.ai";
+var DEFAULT_TIMEOUTS = { connect: 5, read: 30, write: 10 };
+var HttpTransport = class {
+  baseUrl;
+  // Mutable so `configure()` can adjust them before the first request, and so
+  // `initialize()` can write back the identity resolved from whoami.
+  timeouts;
+  retryPolicy;
+  #credentials;
+  userAgent;
+  fetchImpl;
+  keepAliveOptions;
+  heartbeat;
+  closed = false;
+  constructor(options) {
+    this.#credentials = options.credentials;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeouts = { ...DEFAULT_TIMEOUTS, ...options.timeouts };
+    this.retryPolicy = { ...DEFAULT_RETRY_POLICY, ...options.retryPolicy };
+    this.userAgent = options.userAgent ?? "@maximem/synap-js-sdk";
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.keepAliveOptions = options.keepAlive ?? {};
+    this.heartbeat = new Heartbeat(
+      () => this.pingHealth(),
+      options.keepAlive?.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS
+    );
+  }
+  /** Start keeping the connection warm. Opt-in: it is pointless in serverless. */
+  startHeartbeat() {
+    if (!this.closed) this.heartbeat.start();
+  }
+  /**
+   * Release timers. Safe to call more than once.
+   *
+   * This is the supported shutdown path, deliberately explicit rather than
+   * hooked to `process.on('exit')`: those handlers leak a listener per client,
+   * never fire in Lambda, and `process` does not exist in Workers (gotcha G-I).
+   */
+  /**
+   * A COPY of the current credentials.
+   *
+   * A copy, not the live object: handing out the internal reference is how
+   * `client.transport.credentials.apiKey` became readable and mutable from
+   * outside in the first place.
+   */
+  currentCredentials() {
+    return { ...this.#credentials };
+  }
+  /** Write back identity resolved from `GET /api/v1/auth/whoami`. */
+  updateCredentials(patch) {
+    this.#credentials = { ...this.#credentials, ...patch };
+  }
+  setTimeouts(timeouts) {
+    this.timeouts = { ...this.timeouts, ...timeouts };
+  }
+  /** `null` restores the default policy, matching Python's `retry_policy=None`. */
+  setRetryPolicy(policy) {
+    this.retryPolicy = policy === null ? { ...DEFAULT_RETRY_POLICY } : { ...this.retryPolicy, ...policy };
+  }
+  close() {
+    this.closed = true;
+    this.heartbeat.stop();
+  }
+  async request(name, options = {}) {
+    const spec = ENDPOINTS[name];
+    const correlationId = options.correlationId ?? newCorrelationId();
+    const idempotent = options.idempotent ?? spec.idempotent;
+    let attempt = 0;
+    let last = null;
+    while (attempt < this.retryPolicy.maxAttempts) {
+      attempt += 1;
+      try {
+        return await this.attempt(name, options, correlationId);
+      } catch (error) {
+        last = { error, outcomeUnknown: isOutcomeUnknown(error) };
+        const decision = shouldRetry({
+          error,
+          attempt,
+          policy: this.retryPolicy,
+          method: spec.method,
+          outcomeUnknown: last.outcomeUnknown,
+          idempotent
+        });
+        if (!decision.retry) throw error;
+        await sleep(decision.delaySeconds * 1e3, options.signal);
+      }
+    }
+    throw last?.error ?? new SynapError("Request failed with no recorded error");
+  }
+  async attempt(name, options, correlationId) {
+    const spec = ENDPOINTS[name];
+    const url = this.buildUrl(resolvePath(name, options.pathParams), options.query);
+    const dispatcher = await getKeepAliveDispatcher(this.keepAliveOptions);
+    const signal = withTimeout(this.timeouts.read * 1e3, options.signal);
+    const init = {
+      method: spec.method,
+      headers: this.buildHeaders(correlationId, { json: options.rawBody !== true }),
+      signal: signal.signal
+    };
+    if (options.body !== void 0 && spec.method !== "GET") {
+      init.body = options.rawBody === true ? options.body : JSON.stringify(options.body);
+    }
+    if (dispatcher) init["dispatcher"] = dispatcher;
+    let response;
+    try {
+      response = await this.fetchImpl(url, init);
+    } catch (error) {
+      throw toTransportError(error, correlationId);
+    } finally {
+      signal.dispose();
+    }
+    if (!response.ok) {
+      throw await toHttpError(response, correlationId);
+    }
+    if (response.status === 204) return void 0;
+    const text = await response.text();
+    if (!text) return void 0;
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new SynapError(`Malformed JSON in response from ${url}`, { correlationId });
+    }
+  }
+  buildUrl(path, query) {
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(query ?? {})) {
+      if (v !== void 0) url.searchParams.set(k, String(v));
+    }
+    return url.toString();
+  }
+  buildHeaders(correlationId, options = {}) {
+    return {
+      Authorization: `Bearer ${this.#credentials.apiKey}`,
+      "X-Client-ID": this.#credentials.clientId,
+      "X-Instance-ID": this.#credentials.instanceId,
+      "X-Correlation-ID": correlationId,
+      ...options.json === false ? {} : { "Content-Type": "application/json" },
+      "User-Agent": this.userAgent
+    };
+  }
+  /** Unauthenticated and unmetered, exactly like the Python heartbeat. */
+  async pingHealth() {
+    const signal = withTimeout(1e4);
+    try {
+      const dispatcher = await getKeepAliveDispatcher(this.keepAliveOptions);
+      const init = { signal: signal.signal };
+      if (dispatcher) init["dispatcher"] = dispatcher;
+      await this.fetchImpl(`${this.baseUrl}/health`, init);
+    } finally {
+      signal.dispose();
+    }
+  }
+};
+function isOutcomeUnknown(error) {
+  if (error instanceof RateLimitError) return false;
+  if (error instanceof ServiceUnavailableError) return false;
+  if (error instanceof AuthenticationError) return false;
+  if (error instanceof InvalidInputError) return false;
+  if (error instanceof ConflictError) return false;
+  if (error instanceof InsufficientCreditsError) return false;
+  if (error instanceof ContextNotFoundError) return false;
+  if (error instanceof NetworkTimeoutError) return true;
+  if (isConnectionRefusal(error)) return false;
+  return true;
+}
+function isConnectionRefusal(error) {
+  const code = error?.cause?.code ?? error?.code;
+  return code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EAI_AGAIN" || code === "ECONNRESET" || code === "EHOSTUNREACH";
+}
+function toTransportError(error, correlationId) {
+  if (error instanceof SynapError) return error;
+  const name = error?.name;
+  if (name === "AbortError" || name === "TimeoutError") {
+    return new NetworkTimeoutError("Request timed out", { correlationId, cause: error });
+  }
+  return new ServiceUnavailableError(
+    `Network request failed: ${error?.message ?? String(error)}`,
+    { correlationId, cause: error }
+  );
+}
+async function toHttpError(response, correlationId) {
+  const body = await response.text().catch(() => "");
+  let parsed = {};
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+  }
+  const rawDetail = parsed["detail"] ?? parsed["message"] ?? body ?? "";
+  const detailObject = typeof rawDetail === "object" && rawDetail !== null ? rawDetail : null;
+  const detail = detailObject !== null ? String(detailObject["message"] ?? JSON.stringify(detailObject)) : String(rawDetail);
+  const message = `HTTP ${response.status}: ${detail || response.statusText}`;
+  const opts = { correlationId };
+  switch (response.status) {
+    case 400:
+    case 422:
+      return new InvalidInputError(message, opts);
+    case 401:
+    case 403:
+      return new AuthenticationError(message, opts);
+    case 404:
+      return new ContextNotFoundError(message, opts);
+    case 402:
+      return new InsufficientCreditsError(message, {
+        ...opts,
+        balanceCredits: numberOrNull(parsed["balance_credits"]),
+        requiredCredits: numberOrNull(parsed["required_credits"])
+      });
+    case 409:
+      if (detailObject !== null && detailObject["code"] === "transcript_conflict") {
+        return new TranscriptConflictError(message, opts);
+      }
+      return new ConflictError(message, opts);
+    case 429: {
+      const header = response.headers.get("retry-after");
+      const retryAfter = header !== null && header.trim() !== "" ? Number(header) : null;
+      return new RateLimitError(message, {
+        ...opts,
+        retryAfterSeconds: retryAfter !== null && Number.isFinite(retryAfter) ? retryAfter : null
+      });
+    }
+    case 503:
+      return new ServiceUnavailableError(message, opts);
+    case 504:
+      return new AgentUnavailableError(message, opts);
+    default:
+      if (response.status >= 500) return new ServiceUnavailableError(message, opts);
+      return new SynapError(message, opts);
+  }
+}
+function numberOrNull(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function withTimeout(ms, external) {
+  const controller = new AbortController();
+  const onExternalAbort = () => controller.abort(external?.reason);
+  const timer = setTimeout(() => {
+    controller.abort(new NetworkTimeoutError(`Timed out after ${ms}ms`));
+  }, ms);
+  timer.unref?.();
+  if (external) {
+    if (external.aborted) onExternalAbort();
+    else external.addEventListener("abort", onExternalAbort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    dispose() {
+      clearTimeout(timer);
+      external?.removeEventListener("abort", onExternalAbort);
+    }
+  };
+}
+function sleep(ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("Aborted"));
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/context/fetch.ts
+var ENDPOINT_BY_SCOPE = {
+  user: "context_fetch_user",
+  customer: "context_fetch_customer",
+  client: "context_fetch_client",
+  conversation: "context_fetch_conversation"
+};
+function opt(options, snake, camel) {
+  const a = options[snake];
+  if (a !== void 0) return a;
+  const b = options[camel];
+  return b === void 0 ? void 0 : b;
+}
+function buildFetchRequest(scope, options) {
+  const userId = opt(options, "user_id", "userId");
+  const customerId = opt(options, "customer_id", "customerId");
+  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 mode = options.mode ?? "fast";
+  if (searchQuery !== void 0 && !Array.isArray(searchQuery)) {
+    throw new InvalidInputError("search_query must be an array when provided");
+  }
+  if (options.types !== void 0 && !Array.isArray(options.types)) {
+    throw new InvalidInputError("types must be an array when provided");
+  }
+  const body = {
+    conversation_id: conversationId ?? null,
+    search_query: searchQuery ?? [],
+    max_results: maxResults,
+    types: options.types ?? ["all"],
+    mode
+  };
+  if (precisionLevel !== "high") body["precision_level"] = precisionLevel;
+  if (options.include_conversation_context === false) {
+    body["include_conversation_context"] = false;
+  }
+  switch (scope) {
+    case "user":
+      if (!userId) throw new InvalidInputError("user_id is required");
+      body["user_id"] = userId;
+      if (customerId !== void 0) body["customer_id"] = customerId;
+      break;
+    case "customer":
+      if (!customerId) throw new InvalidInputError("customer_id is required");
+      body["customer_id"] = customerId;
+      break;
+    case "conversation":
+      if (!conversationId) throw new InvalidInputError("conversation_id is required");
+      if (userId !== void 0) body["user_id"] = userId;
+      if (customerId !== void 0) body["customer_id"] = customerId;
+      break;
+    case "client":
+      break;
+  }
+  return { endpoint: ENDPOINT_BY_SCOPE[scope], body };
+}
+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 });
+  const response = result?.["context"] ?? {};
+  hooks.onAssembled?.(scope, options, response, startedAt);
+  return response;
+}
+
+// src/context/normalize.ts
+function pickDefined(...values) {
+  for (const v of values) if (v !== void 0) return v;
+  return void 0;
+}
+function pick(...values) {
+  return pickDefined(...values);
+}
+var obj = (v) => v ?? {};
+function normalizeTemporalFields(item = {}) {
+  return {
+    eventDate: pick(item["eventDate"], item.event_date, null),
+    validUntil: pick(item["validUntil"], item.valid_until, null),
+    temporalCategory: pick(item["temporalCategory"], item.temporal_category, null),
+    temporalConfidence: pick(item["temporalConfidence"], item.temporal_confidence, 0)
+  };
+}
+function normalizeFact(item = {}) {
+  return {
+    id: item.id || "",
+    content: item.content || "",
+    confidence: pick(item.confidence, 0),
+    source: item.source || "",
+    extractedAt: pick(item["extractedAt"], item.extracted_at, null),
+    metadata: obj(item.metadata),
+    ...normalizeTemporalFields(item)
+  };
+}
+function normalizePreference(item = {}) {
+  return {
+    id: item.id || "",
+    category: item["category"] || "",
+    content: item.content || "",
+    strength: pick(item["strength"], item.confidence, 0),
+    source: item.source || "",
+    extractedAt: pick(item["extractedAt"], item.extracted_at, null),
+    metadata: obj(item.metadata),
+    ...normalizeTemporalFields(item)
+  };
+}
+function normalizeEpisode(item = {}) {
+  return {
+    id: item.id || "",
+    summary: pick(item["summary"], item.content, ""),
+    occurredAt: pick(item["occurredAt"], item["occurred_at"], null),
+    significance: pick(item["significance"], item.confidence, 0),
+    participants: item["participants"] || [],
+    metadata: obj(item.metadata),
+    ...normalizeTemporalFields(item)
+  };
+}
+function normalizeEmotion(item = {}) {
+  return {
+    id: item.id || "",
+    emotionType: pick(item["emotionType"], item["emotion_type"], ""),
+    intensity: pick(item["intensity"], item.confidence, 0),
+    detectedAt: pick(item["detectedAt"], item["detected_at"], null),
+    context: item["context"] || "",
+    metadata: obj(item.metadata),
+    ...normalizeTemporalFields(item)
+  };
+}
+function normalizeTemporalEvent(item = {}) {
+  return {
+    id: item.id || "",
+    content: item.content || "",
+    eventDate: pick(item["eventDate"], item.event_date, null),
+    validUntil: pick(item["validUntil"], item.valid_until, null),
+    temporalCategory: pick(item["temporalCategory"], item.temporal_category, ""),
+    temporalConfidence: pick(item["temporalConfidence"], item.temporal_confidence, 0),
+    confidence: pick(item.confidence, 0),
+    source: item.source || "",
+    extractedAt: pick(item["extractedAt"], item.extracted_at, null),
+    metadata: obj(item.metadata)
+  };
+}
+function normalizeContextMetadata(metadata = {}) {
+  return {
+    correlationId: pick(metadata["correlationId"], metadata["correlation_id"], ""),
+    ttlSeconds: pick(metadata["ttlSeconds"], metadata["ttl_seconds"], 0),
+    source: metadata["source"] || "unknown",
+    retrievedAt: pick(metadata["retrievedAt"], metadata["retrieved_at"], null),
+    compactionApplied: pick(
+      metadata["compactionApplied"],
+      metadata["compaction_applied"],
+      null
+    )
+  };
+}
+function normalizeConversationContext(value) {
+  if (!value) return null;
+  return {
+    summary: value.summary || null,
+    currentState: pick(value["currentState"], value.current_state, {}),
+    keyExtractions: pick(value["keyExtractions"], value.key_extractions, {}),
+    recentTurns: pick(value["recentTurns"], value.recent_turns, []),
+    compactionId: pick(value["compactionId"], value.compaction_id, null),
+    compactedAt: pick(value["compactedAt"], value.compacted_at, null),
+    conversationId: pick(value["conversationId"], value.conversation_id, null)
+  };
+}
+function normalizeContextResponse(result = {}) {
+  const context = result["context"] ?? result;
+  return {
+    facts: (context.facts || []).map((i) => normalizeFact(i)),
+    preferences: (context.preferences || []).map((i) => normalizePreference(i)),
+    episodes: (context.episodes || []).map((i) => normalizeEpisode(i)),
+    emotions: (context.emotions || []).map((i) => normalizeEmotion(i)),
+    temporalEvents: (pick(context["temporalEvents"], context.temporal_events, []) || []).map((i) => normalizeTemporalEvent(i)),
+    conversationContext: normalizeConversationContext(
+      pick(
+        context["conversationContext"],
+        context.conversation_context,
+        null
+      )
+    ),
+    metadata: normalizeContextMetadata(obj(context.metadata)),
+    rawResponse: pick(context["rawResponse"], context["raw_response"], {})
+  };
+}
+
+// src/context/flatten.ts
+var s = (v) => typeof v === "string" ? v : v == null ? "" : String(v);
+var n = (v, d = 0) => typeof v === "number" ? v : d;
+var o = (v) => v ?? {};
+var dt = (v) => v ? String(v) : null;
+function temporal(item) {
+  return {
+    event_date: dt(item["event_date"]),
+    valid_until: dt(item["valid_until"]),
+    temporal_category: item["temporal_category"] ?? null,
+    temporal_confidence: n(item["temporal_confidence"], 0)
+  };
+}
+function flattenContextItems(context) {
+  const items = [];
+  for (const f of context.facts ?? []) {
+    items.push({
+      id: s(f["id"]),
+      memory: s(f["content"]),
+      score: n(f["confidence"]),
+      source: s(f["source"]),
+      metadata: o(f["metadata"]),
+      context_type: "fact",
+      ...temporal(f)
+    });
+  }
+  for (const p of context.preferences ?? []) {
+    items.push({
+      id: s(p["id"]),
+      memory: s(p["content"]),
+      score: n(p["strength"]),
+      source: s(p["source"]),
+      metadata: o(p["metadata"]),
+      context_type: "preference",
+      ...temporal(p)
+    });
+  }
+  for (const e of context.episodes ?? []) {
+    items.push({
+      id: s(e["id"]),
+      memory: s(e["summary"]),
+      score: n(e["significance"]),
+      metadata: o(e["metadata"]),
+      context_type: "episode",
+      ...temporal(e)
+    });
+  }
+  for (const m of context.emotions ?? []) {
+    items.push({
+      id: s(m["id"]),
+      memory: s(m["context"]),
+      score: n(m["intensity"]),
+      metadata: o(m["metadata"]),
+      context_type: "emotion",
+      ...temporal(m)
+    });
+  }
+  for (const t of context.temporal_events ?? []) {
+    items.push({
+      id: s(t["id"]),
+      memory: s(t["content"]),
+      score: n(t["temporal_confidence"]),
+      source: s(t["source"]),
+      metadata: o(t["metadata"]),
+      context_type: "temporal_event",
+      ...temporal(t)
+    });
+  }
+  return items;
+}
+
+// src/memories/interface.ts
+var DOCUMENT_TYPES = [
+  "ai-chat-conversation",
+  "document",
+  "email",
+  "pdf",
+  "image",
+  "audio",
+  "meeting-transcript"
+];
+var INGEST_MODES = ["fast", "long-range"];
+var DEFAULT_DOCUMENT_TYPE = "ai-chat-conversation";
+var DEFAULT_INGEST_MODE = "long-range";
+function either(o2, snake, camel) {
+  const a = o2[snake];
+  if (a !== void 0) return a;
+  const b = o2[camel];
+  return b === void 0 ? void 0 : b;
+}
+function isoOrNull(v) {
+  if (v === void 0 || v === null) return null;
+  return v instanceof Date ? v.toISOString() : v;
+}
+function buildCreateBody(options) {
+  if (!options.document) throw new InvalidInputError("document is required");
+  const o2 = options;
+  const documentType = either(o2, "document_type", "documentType") ?? DEFAULT_DOCUMENT_TYPE;
+  const mode = options.mode ?? DEFAULT_INGEST_MODE;
+  if (!DOCUMENT_TYPES.includes(documentType)) {
+    throw new InvalidInputError(
+      `Invalid document_type '${documentType}'. Expected one of: ${DOCUMENT_TYPES.join(", ")}`
+    );
+  }
+  if (!INGEST_MODES.includes(mode)) {
+    throw new InvalidInputError(
+      `Invalid mode '${mode}'. Expected one of: ${INGEST_MODES.join(", ")}`
+    );
+  }
+  return {
+    document: options.document,
+    document_type: documentType,
+    document_id: either(o2, "document_id", "documentId") ?? null,
+    document_created_at: isoOrNull(
+      either(o2, "document_created_at", "documentCreatedAt")
+    ),
+    user_id: either(o2, "user_id", "userId") ?? null,
+    customer_id: either(o2, "customer_id", "customerId") ?? null,
+    mode,
+    metadata: options.metadata ?? {}
+  };
+}
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "error", "cancelled"]);
+function createMemoriesInterface(transport) {
+  return {
+    async create(options) {
+      return transport.request("memories_create", { body: buildCreateBody(options) });
+    },
+    async batch_create(options) {
+      const docs = options.documents;
+      if (!Array.isArray(docs) || docs.length === 0) {
+        throw new InvalidInputError("documents must be a non-empty array");
+      }
+      const failFast = options.fail_fast ?? options.failFast ?? false;
+      return transport.request("memories_batch", {
+        body: { documents: docs.map(buildCreateBody), fail_fast: failFast }
+      });
+    },
+    async create_from_file(options) {
+      const userId = options.user_id ?? options.userId;
+      const customerId = options.customer_id ?? options.customerId;
+      if (!userId) throw new InvalidInputError("user_id is required");
+      if (!customerId) throw new InvalidInputError("customer_id is required");
+      const filePath = options.file_path ?? options.filePath;
+      const sources = [filePath, options.file, options.text].filter((v) => v !== void 0);
+      if (sources.length === 0) {
+        throw new InvalidInputError("One of file_path, file, or text must be provided.");
+      }
+      if (sources.length > 1) {
+        throw new InvalidInputError(
+          "Provide exactly one of file_path, file, or text, not several."
+        );
+      }
+      const form = new FormData();
+      form.set("user_id", userId);
+      form.set("customer_id", customerId);
+      form.set("relationship_type", options.relationship_type ?? options.relationshipType ?? "b2c");
+      form.set("mode", String(options.mode ?? DEFAULT_INGEST_MODE));
+      const documentType = options.document_type ?? options.documentType;
+      if (documentType) form.set("document_type", String(documentType));
+      if (options.metadata !== void 0 && Object.keys(options.metadata).length > 0) {
+        form.set("metadata", JSON.stringify(options.metadata));
+      }
+      if (filePath !== void 0) {
+        const { readFile } = await import("fs/promises");
+        const { basename } = await import("path");
+        const bytes = await readFile(filePath);
+        form.set("file", new Blob([bytes]), basename(filePath));
+      } else if (options.file !== void 0) {
+        const blob = options.file instanceof Blob ? options.file : new Blob([options.file]);
+        form.set("file", blob, options.filename ?? "upload");
+      } else {
+        form.set("text", String(options.text));
+      }
+      return transport.request("memories_upload", {
+        body: form,
+        rawBody: true
+      });
+    },
+    async get(memoryId) {
+      if (!memoryId) throw new InvalidInputError("memory_id is required");
+      return transport.request("memories_get", { pathParams: { memory_id: memoryId } });
+    },
+    async update(options) {
+      const memoryId = options.memory_id ?? options.memoryId;
+      if (!memoryId) throw new InvalidInputError("memory_id is required");
+      if (!options.document) throw new InvalidInputError("document is required");
+      const body = {
+        document: options.document,
+        merge_strategy: options.merge_strategy ?? options.mergeStrategy ?? "smart-merge"
+      };
+      const dt2 = options.document_type ?? options.documentType;
+      if (dt2 !== void 0) body["document_type"] = dt2;
+      if (options.metadata !== void 0) body["metadata"] = options.metadata;
+      return transport.request("memories_update", {
+        pathParams: { memory_id: memoryId },
+        body
+      });
+    },
+    async delete(memoryId) {
+      if (!memoryId) {
+        throw new InvalidInputError(
+          "memory_id is required. Deleting by user is no longer supported: the previous implementation tracked ids in process memory, so it silently deleted nothing in any serverless or multi-process deployment while reporting success."
+        );
+      }
+      return transport.request("memories_delete", { pathParams: { memory_id: memoryId } });
+    },
+    async status(ingestionId) {
+      if (!ingestionId) throw new InvalidInputError("ingestion_id is required");
+      return transport.request("memories_status", {
+        pathParams: { ingestion_id: ingestionId }
+      });
+    },
+    async wait_for_completion(ingestionId, options = {}) {
+      if (!ingestionId) throw new InvalidInputError("ingestion_id is required");
+      const timeoutMs = (options.timeout_seconds ?? options.timeoutSeconds ?? 300) * 1e3;
+      const pollMs = (options.poll_interval_seconds ?? options.pollIntervalSeconds ?? 2) * 1e3;
+      const deadline = Date.now() + timeoutMs;
+      let last = {};
+      for (; ; ) {
+        last = await this.status(ingestionId);
+        const status = String(last["status"] ?? "").toLowerCase();
+        if (TERMINAL_STATUSES.has(status)) return last;
+        if (Date.now() >= deadline) {
+          return last;
+        }
+        await sleep2(Math.min(pollMs, Math.max(0, deadline - Date.now())), options.signal);
+      }
+    }
+  };
+}
+function sleep2(ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("Aborted"));
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/util/validators.ts
+var INSTANCE_ID_RE = /^inst_[0-9a-fA-F]{16}$/;
+var UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function validateConversationId(conversationId) {
+  if (conversationId === void 0 || conversationId === null || conversationId === "") return;
+  if (typeof conversationId !== "string" || !UUID_RE.test(conversationId)) {
+    throw new InvalidConversationIdError(`Invalid conversation ID: ${String(conversationId)}`);
+  }
+}
+function validateInstanceId(instanceId) {
+  if (instanceId === void 0 || instanceId === null || instanceId === "") return;
+  if (typeof instanceId !== "string" || !INSTANCE_ID_RE.test(instanceId)) {
+    throw new InvalidInstanceIdError(`Invalid instance ID: ${String(instanceId)}`);
+  }
+}
+
+// src/conversation/interface.ts
+function either2(o2, snake, camel) {
+  const a = o2[snake];
+  if (a !== void 0) return a;
+  const b = o2[camel];
+  return b === void 0 ? void 0 : b;
+}
+function iso(v) {
+  if (v === void 0) return void 0;
+  return v instanceof Date ? v.toISOString() : v;
+}
+function buildRecordMessageBody(options) {
+  const o2 = options;
+  const conversationId = either2(o2, "conversation_id", "conversationId");
+  const userId = either2(o2, "user_id", "userId");
+  const customerId = either2(o2, "customer_id", "customerId");
+  if (!conversationId) throw new InvalidInputError("conversation_id is required");
+  validateConversationId(conversationId);
+  if (!options.role) throw new InvalidInputError("role is required");
+  if (options.content === void 0 || options.content === null) {
+    throw new InvalidInputError("content is required");
+  }
+  if (!userId) throw new InvalidInputError("user_id is required");
+  if (!customerId) throw new InvalidInputError("customer_id is required");
+  const body = {
+    conversation_id: conversationId,
+    role: options.role,
+    content: options.content,
+    user_id: userId,
+    customer_id: customerId,
+    // Python always sends this, defaulting to {}.
+    metadata: options.metadata ?? {}
+  };
+  const sessionId = either2(o2, "session_id", "sessionId");
+  if (sessionId !== void 0) body["session_id"] = sessionId;
+  return body;
+}
+function buildIngestTranscriptBody(options) {
+  const o2 = options;
+  const conversationId = either2(o2, "conversation_id", "conversationId");
+  const userId = either2(o2, "user_id", "userId");
+  if (!conversationId) throw new InvalidInputError("conversation_id is required");
+  if (!userId) throw new InvalidInputError("user_id is required");
+  if (options.transcript === void 0 || options.transcript === null) {
+    throw new InvalidInputError("transcript is required");
+  }
+  const body = {
+    conversation_id: conversationId,
+    user_id: userId,
+    transcript: options.transcript
+  };
+  const customerId = either2(o2, "customer_id", "customerId");
+  const conversationType = either2(o2, "conversation_type", "conversationType");
+  const startedAt = iso(either2(o2, "started_at", "startedAt"));
+  const endedAt = iso(either2(o2, "ended_at", "endedAt"));
+  if (customerId !== void 0) body["customer_id"] = customerId;
+  if (conversationType !== void 0) body["conversation_type"] = conversationType;
+  if (options.analysis !== void 0) body["analysis"] = options.analysis;
+  if (options.metadata !== void 0) body["metadata"] = options.metadata;
+  if (startedAt !== void 0) body["started_at"] = startedAt;
+  if (endedAt !== void 0) body["ended_at"] = endedAt;
+  return body;
+}
+function buildCompactBody(options) {
+  const o2 = options;
+  const conversationId = either2(o2, "conversation_id", "conversationId");
+  if (!conversationId) throw new InvalidInputError("conversation_id is required");
+  validateConversationId(conversationId);
+  const body = { conversation_id: conversationId, force: options.force ?? false };
+  const strategy = options.strategy ?? either2(o2, "compaction_level", "compactionLevel");
+  const targetTokens = either2(o2, "target_tokens", "targetTokens");
+  if (strategy !== void 0) body["strategy"] = strategy;
+  if (targetTokens !== void 0) body["target_tokens"] = targetTokens;
+  return body;
+}
+var CompactionSubscribers = class {
+  #byConversation = /* @__PURE__ */ new Map();
+  add(conversationId, callback) {
+    const list = this.#byConversation.get(conversationId);
+    if (list === void 0) this.#byConversation.set(conversationId, [callback]);
+    else list.push(callback);
+    let unsubscribed = false;
+    return () => {
+      if (unsubscribed) return;
+      unsubscribed = true;
+      const current = this.#byConversation.get(conversationId);
+      if (current === void 0) return;
+      const at = current.indexOf(callback);
+      if (at !== -1) current.splice(at, 1);
+      if (current.length === 0) this.#byConversation.delete(conversationId);
+    };
+  }
+  removeAll(conversationId) {
+    if (conversationId === void 0) {
+      let count = 0;
+      for (const list2 of this.#byConversation.values()) count += list2.length;
+      this.#byConversation.clear();
+      return count;
+    }
+    const list = this.#byConversation.get(conversationId);
+    if (list === void 0) return 0;
+    this.#byConversation.delete(conversationId);
+    return list.length;
+  }
+  /** Fires subscribers in registration order. A throwing listener must not break the stream reader. */
+  dispatch(conversationId, bundle, onError) {
+    for (const callback of [...this.#byConversation.get(conversationId) ?? []]) {
+      try {
+        const result = callback(bundle);
+        if (result instanceof Promise) result.catch(onError);
+      } catch (error) {
+        onError(error);
+      }
+    }
+  }
+};
+function createConversationNamespace(transport, subscribers = new CompactionSubscribers(), onWrite = () => {
+}, onTurn = () => {
+}, onFetched = () => {
+}) {
+  const convId = (v) => {
+    const id = typeof v === "string" ? v : v.conversation_id ?? v.conversationId;
+    if (!id) throw new InvalidInputError("conversation_id is required");
+    validateConversationId(id);
+    return id;
+  };
+  return {
+    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"]
+      });
+      return result;
+    },
+    async record_messages_batch(messages) {
+      if (!Array.isArray(messages) || messages.length === 0) {
+        throw new InvalidInputError("messages must be a non-empty array");
+      }
+      const bodies = messages.map(buildRecordMessageBody);
+      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"],
+          customerId: body["customer_id"]
+        });
+      }
+      return result;
+    },
+    async ingest_transcript(options) {
+      const body = buildIngestTranscriptBody(options);
+      const result = await transport.request("conversations_ingest", { body });
+      onWrite({
+        userId: body["user_id"],
+        customerId: body["customer_id"]
+      });
+      return result;
+    },
+    context: {
+      async fetch(options = {}) {
+        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 response;
+      },
+      get_context_for_prompt: async (options = {}) => {
+        const id = convId(options);
+        const result = await transport.request("context_for_prompt", {
+          pathParams: { conversation_id: id },
+          query: { style: options.style ?? "structured" }
+        });
+        return result?.["context_for_prompt"] ?? result ?? {};
+      },
+      async compact(options) {
+        return transport.request("conversations_compact", { body: buildCompactBody(options) });
+      },
+      get_compacted: async (options) => {
+        const id = convId(options);
+        const query = { format: options.format ?? "structured" };
+        if (options.version !== void 0) query["version"] = options.version;
+        try {
+          return await transport.request("conversations_compacted", {
+            pathParams: { conversation_id: id },
+            query
+          });
+        } catch (error) {
+          if (error.code === "context_not_found") return null;
+          throw error;
+        }
+      },
+      async get_compaction_status(options) {
+        return transport.request("conversations_compaction_status", {
+          pathParams: { conversation_id: convId(options) }
+        });
+      },
+      /**
+       * Fire `callback` whenever a `compaction_update` bundle arrives on the
+       * Listen stream for this conversation.
+       *
+       * Requires an active `client.instance.listen()`; without it no bundles
+       * arrive and the callback never fires. Registering before listening is
+       * fine, which is why this does not throw when the stream is down.
+       *
+       * Returns an idempotent unsubscribe thunk, matching Python.
+       */
+      subscribe_to_compaction_updates(conversationId, callback) {
+        if (!conversationId) throw new InvalidInputError("conversation_id is required");
+        if (typeof callback !== "function") throw new InvalidInputError("callback is required");
+        return subscribers.add(conversationId, callback);
+      },
+      /** Remove subscribers for one conversation, or all of them. Returns the count removed. */
+      unsubscribe_all_compaction_updates(conversationId) {
+        return subscribers.removeAll(conversationId);
+      }
+    }
+  };
+}
+
+// src/user/interface.ts
+function createUserNamespace(transport, hooks = {}) {
+  return {
+    async get_profile(options) {
+      const userId = typeof options === "string" ? options : options.user_id ?? options.userId;
+      if (!userId) throw new InvalidInputError("user_id is required");
+      const customerId = typeof options === "string" ? void 0 : options.customer_id ?? options.customerId;
+      return transport.request("user_profile", {
+        pathParams: { user_id: userId },
+        // Sent only when provided, matching Python. Note the server returns
+        // 500 rather than a clean error if it needs one and does not get it.
+        ...customerId !== void 0 ? { query: { customer_id: customerId } } : {}
+      });
+    },
+    context: { async fetch(options = {}) {
+      return fetchContext(transport, "user", options, hooks);
+    } }
+  };
+}
+
+// src/credits/interface.ts
+function createCreditsNamespace(transport) {
+  return {
+    async get_balance() {
+      return transport.request("credits_balance");
+    },
+    async get_ledger(options = {}) {
+      return transport.request("credits_ledger", {
+        query: { limit: options.limit ?? 50, offset: options.offset ?? 0 }
+      });
+    },
+    async estimate(options) {
+      return transport.request("credits_estimate", {
+        body: {
+          metric_type: options.metric_type ?? options.metricType ?? null,
+          units: options.units ?? null,
+          item_count: options.item_count ?? options.itemCount ?? null,
+          endpoint: options.endpoint ?? null,
+          mode: options.mode ?? null
+        }
+      });
+    },
+    async redeem(code) {
+      if (!code) throw new InvalidInputError("code is required");
+      return transport.request("credits_redeem", { body: { code } });
+    }
+  };
+}
+
+// src/cache/interface.ts
+function createCacheNamespace(cache) {
+  return {
+    clear: () => cache.clear(),
+    clear_user: (userId) => {
+      if (!userId) throw new InvalidInputError("user_id is required");
+      cache.dropEntity(userId);
+    },
+    clear_customer: (customerId) => {
+      if (!customerId) throw new InvalidInputError("customer_id is required");
+      cache.dropEntity(customerId);
+    },
+    stats: () => ({ bundles: cache.size, items: cache.itemCount })
+  };
+}
+
+// src/instance/interface.ts
+var DEFAULT_GRPC_HOST = "synap-cloud-prod.maximem.ai";
+var DEFAULT_GRPC_PORT = 443;
+function envPort() {
+  const raw = getEnv("SYNAP_GRPC_PORT");
+  if (raw === void 0 || raw === "") return void 0;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function envTls() {
+  const raw = getEnv("SYNAP_GRPC_USE_TLS");
+  if (raw === void 0 || raw === "") return void 0;
+  return !["0", "false", "no", "off"].includes(raw.trim().toLowerCase());
+}
+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;
+    },
+    isListening() {
+      return client !== null && client.isConnected;
+    }
+  };
+  const namespace = {
+    async listen(options = {}) {
+      if (client !== null) {
+        throw new ListeningAlreadyActiveError("Listening is already active on this instance");
+      }
+      const { GrpcStreamClient } = await import("./stream-client-ME5N5NK4.js");
+      const onContext = options.on_context ?? options.onContext;
+      const onDisconnect = options.on_disconnect ?? options.onDisconnect;
+      const onReconnect = options.on_reconnect ?? options.onReconnect;
+      let reconnectAttempts = 0;
+      const created = new GrpcStreamClient(credentials(), cache, {
+        host: options.host ?? getEnv("SYNAP_GRPC_HOST") ?? DEFAULT_GRPC_HOST,
+        port: options.port ?? envPort() ?? DEFAULT_GRPC_PORT,
+        useTls: options.use_tls ?? options.useTls ?? envTls() ?? true,
+        ...onContext !== void 0 ? { onContext } : {},
+        onCompactionUpdate: (conversationId, bundle) => {
+          internals.onCompactionUpdate(conversationId, bundle);
+        },
+        onStateChange: (state) => {
+          if (state === "reconnecting") {
+            reconnectAttempts += 1;
+            onReconnect?.(reconnectAttempts);
+          } else if (state === "disconnected") {
+            onDisconnect?.("stream disconnected");
+          }
+        }
+      });
+      try {
+        await created.connect();
+      } catch (error) {
+        if (error instanceof SynapError) throw error;
+        throw new SynapError(
+          `Could not open the Synap anticipation stream: ${error?.message ?? String(error)}`,
+          { cause: error }
+        );
+      }
+      client = created;
+    },
+    async stop_listening() {
+      if (client === null) return;
+      const active = client;
+      client = null;
+      await active.disconnect();
+    },
+    async send_message(options) {
+      if (client === null) throw new ListeningNotActiveError("Listening is not active");
+      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,
+        role: options.role ?? "user",
+        conversation_id: options.conversation_id ?? options.conversationId ?? "",
+        user_id: options.user_id ?? options.userId ?? "",
+        customer_id: options.customer_id ?? options.customerId ?? "",
+        session_id: options.session_id ?? options.sessionId ?? "",
+        metadata: options.metadata ?? {},
+        timestamp_ms: Date.now(),
+        search_queries: options.search_queries ?? options.searchQueries ?? [],
+        context_types: options.context_types ?? options.contextTypes ?? []
+      });
+    },
+    async record_thinking(options) {
+      if (client === null) throw new ListeningNotActiveError("Listening is not active");
+      client.sendConversationEvent({
+        // Python emits reasoning as an `agent_thinking` conversation event.
+        event_type: "agent_thinking",
+        content: options.content,
+        role: "assistant",
+        conversation_id: options.conversation_id ?? options.conversationId ?? "",
+        user_id: options.user_id ?? options.userId ?? "",
+        customer_id: options.customer_id ?? options.customerId ?? "",
+        session_id: options.session_id ?? options.sessionId ?? "",
+        metadata: options.metadata ?? {},
+        timestamp_ms: Date.now()
+      });
+    },
+    get is_listening() {
+      return client !== null && client.isConnected;
+    },
+    _internal: internals
+  };
+  return namespace;
+}
+
+// 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",
+  "preferences",
+  "episodes",
+  "emotions",
+  "temporal_events"
+];
+function itemId2(item) {
+  const id = item.id ?? item.item_id;
+  return typeof id === "string" && id !== "" ? id : void 0;
+}
+function mergeScopeResults(scopeResults) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = {
+    facts: [],
+    preferences: [],
+    episodes: [],
+    emotions: [],
+    temporal_events: [],
+    scope_map: {},
+    conversation_context: null,
+    profile: null,
+    conversations: null,
+    formatted_context: "",
+    scopes_queried: [],
+    total_items: 0,
+    metadata: null
+  };
+  for (const [scopeName, response] of scopeResults) {
+    out.scopes_queried.push(scopeName);
+    if (out.metadata === null && response.metadata !== void 0) {
+      out.metadata = response.metadata;
+    }
+    if (out.profile === null && response["profile"] !== void 0 && response["profile"] !== null) {
+      out.profile = response["profile"];
+    }
+    if (out.conversations === null && response["conversations"] !== void 0 && response["conversations"] !== null) {
+      out.conversations = response["conversations"];
+    }
+    for (const collection of ITEM_COLLECTIONS) {
+      const items = response[collection];
+      if (!Array.isArray(items)) continue;
+      for (const item of items) {
+        const id = itemId2(item);
+        if (id !== void 0) {
+          if (seen.has(id)) continue;
+          seen.add(id);
+          out.scope_map[id] = scopeName;
+        }
+        out[collection].push(item);
+      }
+    }
+  }
+  out.total_items = ITEM_COLLECTIONS.reduce((n2, c) => n2 + out[c].length, 0);
+  return out;
+}
+function oneDecimal(value) {
+  return value.toFixed(1);
+}
+function isoDate(value) {
+  if (typeof value !== "string" || value === "") return null;
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) return null;
+  return parsed.toISOString().slice(0, 10);
+}
+function numberOf(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function scopeOf(ctx, item) {
+  const id = itemId2(item);
+  return (id !== void 0 ? ctx.scope_map[id] : void 0) ?? "unknown";
+}
+function bulletWithExtras(text, extras) {
+  return extras.length > 0 ? `- ${text} [${extras.join(", ")}]` : `- ${text}`;
+}
+function formatForPrompt(ctx, options = {}) {
+  const includeScope = options.includeScope ?? false;
+  const includeConversationContext = options.includeConversationContext ?? true;
+  const sections = [];
+  if (ctx.facts.length > 0) {
+    const lines = ctx.facts.map((f) => {
+      let line = `- ${String(f.content ?? "")}`;
+      if (includeScope) line += ` [scope: ${scopeOf(ctx, f)}]`;
+      return line;
+    });
+    sections.push(`### Facts
+${lines.join("\n")}`);
+  }
+  if (ctx.preferences.length > 0) {
+    const lines = ctx.preferences.map((p) => {
+      const extras = [];
+      if (includeScope) extras.push(`scope: ${scopeOf(ctx, p)}`);
+      const strength = numberOf(p["strength"]);
+      if (strength !== null && strength !== 0 && strength >= 0.7) {
+        extras.push(`strength: ${oneDecimal(strength)}`);
+      }
+      return bulletWithExtras(String(p.content ?? ""), extras);
+    });
+    sections.push(`### Preferences
+${lines.join("\n")}`);
+  }
+  if (ctx.episodes.length > 0) {
+    const lines = ctx.episodes.map((e) => {
+      let line = `- ${String(e["summary"] ?? "")}`;
+      if (includeScope) line += ` [scope: ${scopeOf(ctx, e)}]`;
+      return line;
+    });
+    sections.push(`### Episodes
+${lines.join("\n")}`);
+  }
+  if (ctx.emotions.length > 0) {
+    const lines = ctx.emotions.map((em) => {
+      const extras = [];
+      if (includeScope) extras.push(`scope: ${scopeOf(ctx, em)}`);
+      const intensity = numberOf(em["intensity"]);
+      if (intensity !== null && intensity !== 0 && intensity >= 0.5) {
+        extras.push(`intensity: ${oneDecimal(intensity)}`);
+      }
+      const text = `${String(em["emotion_type"] ?? "")}: ${String(em["context"] ?? "")}`;
+      return bulletWithExtras(text, extras);
+    });
+    sections.push(`### Emotions
+${lines.join("\n")}`);
+  }
+  if (ctx.temporal_events.length > 0) {
+    const lines = ctx.temporal_events.map((te) => {
+      const extras = [];
+      if (includeScope) extras.push(`scope: ${scopeOf(ctx, te)}`);
+      const validUntil = isoDate(te["valid_until"]);
+      if (validUntil !== null) extras.push(`valid until: ${validUntil}`);
+      return bulletWithExtras(String(te.content ?? ""), extras);
+    });
+    sections.push(`### Temporal Events
+${lines.join("\n")}`);
+  }
+  if (includeConversationContext && ctx.conversation_context !== null) {
+    const formatted = ctx.conversation_context["formatted_context"];
+    if (typeof formatted === "string" && formatted !== "") {
+      sections.push(`### Conversation History
+${formatted}`);
+    }
+  }
+  const blocks = [];
+  if (sections.length > 0) blocks.push(`## User Context
+${sections.join("\n\n")}`);
+  const profileBlock = formatProfileBlock(ctx.profile);
+  if (profileBlock !== null) blocks.push(profileBlock);
+  const conversationsBlock = formatConversationsBlock(ctx.conversations);
+  if (conversationsBlock !== null) blocks.push(conversationsBlock);
+  return blocks.length > 0 ? blocks.join("\n\n") : "";
+}
+function formatProfileBlock(profile) {
+  if (profile === null) return null;
+  const attributes = profile["attributes"];
+  const lines = [];
+  if (typeof attributes === "object" && attributes !== null) {
+    for (const [name, attr] of Object.entries(attributes)) {
+      const value = typeof attr === "object" && attr !== null ? attr["value"] : void 0;
+      let valueStr;
+      if (Array.isArray(value)) valueStr = value.map((v) => String(v)).join(", ");
+      else if (value === null || value === void 0) valueStr = "";
+      else valueStr = String(value);
+      lines.push(`- ${name}: ${valueStr}`.replace(/\s+$/, ""));
+    }
+  }
+  const bodyParts = [];
+  if (lines.length > 0) bodyParts.push(lines.join("\n"));
+  const overview = profile["overview"];
+  if (typeof overview === "string" && overview !== "") bodyParts.push(overview);
+  if (bodyParts.length === 0) return null;
+  return `## Caller Profile
+${bodyParts.join("\n\n")}`;
+}
+function formatConversationsBlock(conversations) {
+  if (conversations === null || conversations.length === 0) return null;
+  const callBlocks = conversations.map((conv) => {
+    const when = isoDate(conv["started_at"]) ?? isoDate(conv["last_message_at"]) ?? isoDate(conv["ended_at"]);
+    let header = `### Call on ${when ?? "unknown date"}`;
+    const convType = conv["conversation_type"];
+    if (typeof convType === "string" && convType !== "") header += ` (${convType})`;
+    const callLines = [header];
+    const overview = overviewText(conv);
+    if (overview !== null) callLines.push(`Overview: ${overview}`);
+    const outcome = outcomeText(conv);
+    if (outcome !== null) callLines.push(`Outcome: ${outcome}`);
+    if (overview === null && outcome === null) {
+      callLines.push(`Status: ${String(conv["summary_status"] ?? "pending")}`);
+    }
+    return callLines.join("\n");
+  });
+  return `## Previous Conversations
+${callBlocks.join("\n\n")}`;
+}
+function overviewText(conv) {
+  const summary = conv["summary"];
+  if (typeof summary !== "object" || summary === null || Array.isArray(summary)) return null;
+  for (const key of ["narrative_summary", "overview", "narrative", "summary"]) {
+    const val = summary[key];
+    if (typeof val === "string" && val.trim() !== "") return val.trim();
+  }
+  return null;
+}
+function outcomeText(conv) {
+  const classification = conv["classification"];
+  if (typeof classification !== "object" || classification === null || Array.isArray(classification)) {
+    return null;
+  }
+  const c = classification;
+  const parts = [c["primary_category"], c["subcategory"], c["objective"]].filter((p) => typeof p === "string" && p.trim() !== "");
+  return parts.length > 0 ? parts.join(" / ") : null;
+}
+
+// src/tool/as-tool.ts
+var VALID_SCOPES = ["conversation", "user", "customer", "client", "unified"];
+var BASE_DESCRIPTION = "Retrieve stored context (facts, preferences, recent episodes, emotions, temporal events) from Synap memory.";
+function defaultToolDescription(scope) {
+  switch (scope) {
+    case "conversation":
+      return BASE_DESCRIPTION + " Scoped to a specific conversation. Call this when you need facts already established in the current conversation, or to reload context after a topic shift.";
+    case "user":
+      return BASE_DESCRIPTION + " Scoped to the user's long-term memory. Call this when you need to recall who the user is, their preferences, or their history across conversations.";
+    case "customer":
+      return BASE_DESCRIPTION + " Scoped to the customer/organization. Call this when you need facts about the customer org rather than an individual.";
+    case "client":
+      return BASE_DESCRIPTION + " Scoped to the integrating client/product. Call this for product-level knowledge (e.g. policies, documentation).";
+    default:
+      return BASE_DESCRIPTION + " Cross-scope: merges conversation, user, customer, and client memory in one call. Call this at the start of a turn when you need general grounding before responding.";
+  }
+}
+function toolInputSchema(scope, options) {
+  const props = {
+    search_query: {
+      type: "array",
+      items: { type: "string" },
+      description: "Optional list of search queries describing what context you need. Free-form natural language is fine. Omit to retrieve the most relevant recent context."
+    },
+    max_results: {
+      type: "integer",
+      minimum: 1,
+      maximum: 50,
+      description: "Maximum items to return (default 10)."
+    },
+    types: {
+      type: "array",
+      items: {
+        type: "string",
+        enum: ["facts", "preferences", "episodes", "emotions", "temporal_events"]
+      },
+      description: "Filter to specific memory categories. Omit to retrieve all."
+    },
+    mode: {
+      type: "string",
+      enum: ["fast", "accurate"],
+      description: "Retrieval mode. 'fast' = low-latency (~50ms); 'accurate' = LLM-decomposed multi-query (~200-500ms). Default 'fast'."
+    },
+    precision_level: {
+      type: "string",
+      enum: ["high", "medium"],
+      description: "Result filtering precision. 'high' (default) applies an extra relevance-refinement pass; 'medium' skips it for faster, less precisely filtered results (recall unaffected)."
+    }
+  };
+  let required = [];
+  if (scope === "conversation" && !options.hasConversationId) {
+    props["conversation_id"] = {
+      type: "string",
+      description: "The conversation id to fetch context for."
+    };
+    required = ["conversation_id"];
+  }
+  return { type: "object", properties: props, required, additionalProperties: false };
+}
+var RESULT_COLLECTIONS = ["facts", "preferences", "episodes", "emotions", "temporal_events"];
+async function invokeScopeFetch(params) {
+  const { target, scope, userId, customerId, conversationId, callArgs } = params;
+  const searchQuery = callArgs["search_query"];
+  const rawMax = callArgs["max_results"];
+  const maxResults = typeof rawMax === "number" && rawMax !== 0 ? Math.trunc(rawMax) : 10;
+  const types = callArgs["types"];
+  const mode = String(callArgs["mode"] ?? "") || "fast";
+  const precisionLevel = String(callArgs["precision_level"] ?? "") || "high";
+  const callConvId = (typeof callArgs["conversation_id"] === "string" && callArgs["conversation_id"] !== "" ? callArgs["conversation_id"] : void 0) ?? conversationId;
+  const shared = {
+    search_query: searchQuery,
+    max_results: maxResults,
+    types,
+    mode,
+    precision_level: precisionLevel
+  };
+  if (scope === "unified") {
+    const response2 = await target.fetch({
+      conversation_id: callConvId,
+      user_id: userId,
+      customer_id: customerId,
+      ...shared
+    });
+    return {
+      formatted_context: response2.formatted_context,
+      scopes_queried: response2.scopes_queried,
+      total_items: response2.total_items
+    };
+  }
+  let response;
+  if (scope === "conversation") {
+    if (callConvId === void 0 || callConvId === "") {
+      return { error: "conversation_id is required", items: [] };
+    }
+    response = await target.conversation.context.fetch({
+      conversation_id: callConvId,
+      ...shared,
+      user_id: userId
+    });
+  } else if (scope === "user") {
+    response = await target.user.context.fetch({
+      user_id: userId,
+      conversation_id: callConvId,
+      ...shared,
+      customer_id: customerId
+    });
+  } else if (scope === "customer") {
+    response = await target.customer.context.fetch({
+      customer_id: customerId,
+      conversation_id: callConvId,
+      ...shared
+    });
+  } else {
+    response = await target.client.context.fetch({
+      conversation_id: callConvId,
+      ...shared
+    });
+  }
+  const out = {};
+  for (const collection of RESULT_COLLECTIONS) {
+    out[collection] = Array.isArray(response[collection]) ? response[collection] : [];
+  }
+  return out;
+}
+function buildTool(target, options = {}, onWarning = () => {
+}) {
+  const scope = String(options.scope ?? "user").toLowerCase();
+  if (!VALID_SCOPES.includes(scope)) {
+    const sorted = [...VALID_SCOPES].sort();
+    throw new InvalidInputError(
+      `scope must be one of ['${sorted.join("', '")}'], got '${String(options.scope)}'`
+    );
+  }
+  const userId = options.user_id ?? options.userId;
+  const customerId = options.customer_id ?? options.customerId;
+  const conversationId = options.conversation_id ?? options.conversationId;
+  if (scope === "user" && (userId === void 0 || userId === "")) {
+    throw new InvalidInputError("scope='user' requires user_id");
+  }
+  if (scope === "customer" && (customerId === void 0 || customerId === "")) {
+    throw new InvalidInputError("scope='customer' requires customer_id");
+  }
+  if (scope === "conversation" && (userId === void 0 || userId === "")) {
+    onWarning(
+      "as_tool(scope='conversation') without user_id: the SDK anticipation cache cannot apply per-user filtering. Pass user_id to enable the Section 15 privacy guarantee."
+    );
+  }
+  const style = String(options.style ?? "openai");
+  if (style !== "openai" && style !== "anthropic") {
+    throw new InvalidInputError(`style must be 'openai' or 'anthropic', got '${style}'`);
+  }
+  const toolName = options.name ?? `synap_fetch_${scope}_context`;
+  const toolDesc = options.description ?? defaultToolDescription(scope);
+  const schema = toolInputSchema(scope, { hasConversationId: conversationId !== void 0 });
+  const handler = (callArgs = {}) => invokeScopeFetch({ target, scope, userId, customerId, conversationId, callArgs });
+  if (style === "openai") {
+    return {
+      type: "function",
+      function: { name: toolName, description: toolDesc, parameters: schema },
+      handler
+    };
+  }
+  return { name: toolName, description: toolDesc, input_schema: schema, handler };
+}
+
+// src/client.ts
+var SynapClient = class {
+  // 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
+  // .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;
+  customer;
+  client;
+  conversation;
+  memories;
+  credits;
+  cache;
+  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 } : {},
+      ...options.timeouts !== void 0 ? { timeouts: options.timeouts } : {},
+      ...options.retryPolicy !== void 0 ? { retryPolicy: options.retryPolicy } : {},
+      ...options.keepAlive !== void 0 ? { keepAlive: options.keepAlive } : {},
+      ...options.fetchImpl !== void 0 ? { fetchImpl: options.fetchImpl } : {},
+      userAgent: `@maximem/synap-js-sdk/${SDK_VERSION}`
+    });
+    if (options.heartbeat) this.#transport.startHeartbeat();
+    this.#anticipationCache = new AnticipationCache();
+    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,
+      // Mirrors Python's `_invalidate_anticipation_on_write`, including its
+      // gate: `invalidateEntity` is a no-op unless
+      // SYNAP_SDK_CACHE_INVALIDATE_ON_WRITE is set, so default behaviour is
+      // unchanged. Over-invalidating after a failed write is safe; it only
+      // costs the next lookup a cold fetch.
+      ({ userId, customerId }) => {
+        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);
+    this.credits = createCreditsNamespace(this.#transport);
+    this.cache = createCacheNamespace(this.#anticipationCache);
+    this.instance = createInstanceNamespace(
+      () => this.#transport.currentCredentials(),
+      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)}`);
+      });
+    });
+  }
+  // ── Deprecated camelCase surface, carried over from the 0.3.x wrapper ───────
+  // These return the NORMALISED shape, unlike their namespaced equivalents.
+  /** @deprecated Use `client.user.context.fetch()`. Note it returns raw snake_case. */
+  async fetchUserContext(options = {}) {
+    return normalizeContextResponse(await fetchContext(this.#transport, "user", options));
+  }
+  /** @deprecated Use `client.customer.context.fetch()`. */
+  async fetchCustomerContext(options = {}) {
+    return normalizeContextResponse(await fetchContext(this.#transport, "customer", options));
+  }
+  /** @deprecated Use `client.client.context.fetch()`. */
+  async fetchClientContext(options = {}) {
+    return normalizeContextResponse(await fetchContext(this.#transport, "client", options));
+  }
+  /** @deprecated Use `client.conversation.context.get_context_for_prompt()`. */
+  async getContextForPrompt(options = {}) {
+    return this.conversation.context.get_context_for_prompt(options);
+  }
+  /**
+   * @deprecated Use `client.user.context.fetch()` and read the typed collections.
+   *
+   * Flattens every context type into one list, exactly as the 0.3.x bridge did.
+   */
+  async searchMemory(options) {
+    const userId = options.user_id ?? options.userId;
+    if (!userId) throw new InvalidInputError("user_id is required");
+    if (options.query === void 0 || options.query === null) {
+      throw new InvalidInputError("query is required");
+    }
+    const context = await fetchContext(this.#transport, "user", {
+      user_id: userId,
+      ...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: pick3(options, "max_results", "maxResults") ?? 10,
+      types: options.types ?? ["all"],
+      ...options.mode !== void 0 ? { mode: options.mode } : {}
+    });
+    const results = flattenContextItems(context);
+    return { results, count: results.length };
+  }
+  /**
+   * @deprecated Use `client.user.context.fetch()` with an empty `search_query`.
+   *
+   * Note the default of 100, not 10: it matches the 0.3.x bridge.
+   */
+  async getMemories(options) {
+    const userId = options.user_id ?? options.userId;
+    if (!userId) throw new InvalidInputError("user_id is required");
+    const context = await fetchContext(this.#transport, "user", {
+      user_id: userId,
+      ...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: pick3(options, "max_results", "maxResults") ?? 100,
+      types: options.types ?? ["all"],
+      ...options.mode !== void 0 ? { mode: options.mode } : {}
+    });
+    const results = flattenContextItems(context);
+    return { results, count: results.length };
+  }
+  /** @deprecated Use `client.memories.create()`. */
+  async addMemory(options) {
+    return this.memories.create(options);
+  }
+  /**
+   * @deprecated Use `client.memories.delete(memoryId)`.
+   *
+   * The `{ userId }` form is gone: it relied on a process-local id list and so
+   * deleted nothing in serverless while reporting success (gotcha G-F).
+   */
+  async deleteMemory(options) {
+    return this.memories.delete(options.memory_id ?? options.memoryId ?? "");
+  }
+  /**
+   * 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.
+   *
+   * 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;
+    const credentials = this.#transport.currentCredentials();
+    if (credentials.clientId !== "" && credentials.instanceId !== "") return;
+    try {
+      const whoami = await this.#transport.request("whoami", {});
+      const resolvedClientId = String(whoami["client_id"] ?? "");
+      const resolvedInstanceId = String(whoami["instance_id"] ?? "");
+      this.#transport.updateCredentials({
+        ...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 {
+    }
+  }
+  /**
+   * @deprecated Use `initialize()`, which is the Python name. `init()` was a
+   * JS-only spelling with no Python counterpart; it now forwards, so a 0.3.x
+   * startup script keeps working.
+   */
+  async init() {
+    return this.initialize();
+  }
+  /** The resolved instance id. Empty until `initialize()` resolves it. */
+  get instance_id() {
+    return this.#transport.currentCredentials().instanceId;
+  }
+  /** The resolved client id. Empty until `initialize()` resolves it. */
+  get client_id() {
+    return this.#transport.currentCredentials().clientId;
+  }
+  /**
+   * Update configuration before `initialize()`.
+   *
+   * Mirrors Python's `configure()`, including its refusal to reconfigure after
+   * initialization: the transport and cache are already built by then and a
+   * half-applied config is worse than a rejected one.
+   *
+   * The Python-only keys (`storage_path`, `cache_backend`,
+   * `session_timeout_minutes`, `logger`) are accepted and ignored rather than
+   * rejected, because this SDK has no SQLite cache backend and no global
+   * logger to swap. Ignoring them keeps a shared config object portable
+   * between the two SDKs.
+   */
+  configure(options = {}) {
+    if (this.#initialized) {
+      throw new InvalidInputError("Cannot reconfigure after initialization");
+    }
+    if (options.timeouts !== void 0) this.#transport.setTimeouts(options.timeouts);
+    if (options.retryPolicy !== void 0 || options.retry_policy !== void 0) {
+      this.#transport.setRetryPolicy(options.retryPolicy ?? options.retry_policy ?? null);
+    }
+  }
+  /**
+   * Fetch and merge context across every scope with an identifier, in one call.
+   *
+   * Mirrors Python's `sdk.fetch()`. The three behaviours worth knowing:
+   *
+   *  - Scope fetches run in parallel and a FAILED scope is dropped with a
+   *    warning rather than failing the call, so partial context still gets
+   *    returned. The one exception is `InvalidInputError`: a bad request must
+   *    surface instead of degrading into a silently-empty context.
+   *  - `user_id` is threaded into the conversation-scope sub-fetch so the
+   *    anticipation cache can apply its per-user filter.
+   *  - The summary-mode parameters go ONLY to the user-scope sub-fetch. The
+   *    other three routes return 422 for `context_mode="conversation-summary"`,
+   *    and that rejection would be swallowed by the drop-failed-scope rule.
+   */
+  async fetch(options = {}) {
+    const {
+      conversation_id: conversationId,
+      user_id: userId,
+      customer_id: customerId,
+      search_query: searchQuery,
+      max_results: maxResults = 20,
+      types,
+      mode = "fast",
+      precision_level: precisionLevel = "high",
+      include_conversation_context: includeConversationContext = true,
+      scopes,
+      include_scope_labels: includeScopeLabels = false,
+      context_mode: contextMode = "in-conversation",
+      include_profile: includeProfile = true,
+      last_n_conversations: lastNConversations = 1
+    } = options;
+    validateConversationId(conversationId);
+    const wants = (scope) => scopes === void 0 || scopes.includes(scope);
+    const shared = {
+      search_query: searchQuery,
+      max_results: maxResults,
+      types,
+      mode,
+      precision_level: precisionLevel
+    };
+    const labels = [];
+    const tasks = [];
+    if (conversationId !== void 0 && conversationId !== "" && wants("conversation")) {
+      labels.push("conversation");
+      tasks.push(this.conversation.context.fetch({
+        conversation_id: conversationId,
+        ...shared,
+        user_id: userId,
+        customer_id: customerId
+      }));
+    }
+    if (userId !== void 0 && userId !== "" && wants("user")) {
+      labels.push("user");
+      tasks.push(this.user.context.fetch({
+        user_id: userId,
+        conversation_id: conversationId,
+        ...shared,
+        customer_id: customerId,
+        context_mode: contextMode,
+        include_profile: includeProfile,
+        last_n_conversations: lastNConversations
+      }));
+    }
+    if (customerId !== void 0 && customerId !== "" && wants("customer")) {
+      labels.push("customer");
+      tasks.push(this.customer.context.fetch({
+        customer_id: customerId,
+        conversation_id: conversationId,
+        ...shared
+      }));
+    }
+    if (scopes !== void 0 && scopes.includes("client")) {
+      labels.push("client");
+      tasks.push(this.client.context.fetch({
+        conversation_id: conversationId,
+        ...shared
+      }));
+    }
+    if (tasks.length === 0) {
+      const empty = mergeScopeResults([]);
+      return empty;
+    }
+    const settled = await Promise.allSettled(tasks);
+    const successful = [];
+    for (const [i, result] of settled.entries()) {
+      const label = labels[i];
+      if (result.status === "fulfilled") {
+        successful.push([label, result.value]);
+        continue;
+      }
+      if (result.reason instanceof InvalidInputError) throw result.reason;
+      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({
+          conversation_id: conversationId
+        });
+      } catch {
+      }
+    }
+    merged.formatted_context = formatForPrompt(merged, {
+      includeScope: includeScopeLabels,
+      includeConversationContext
+    });
+    return merged;
+  }
+  /**
+   * An LLM-ready tool definition that fetches Synap context.
+   *
+   * Mirrors Python's `as_tool()`. The scope identifiers are closed over, so
+   * the model cannot choose whose memory to read.
+   */
+  as_tool(options = {}) {
+    return buildTool(this, options, (message) => this.#warn(message));
+  }
+  /**
+   * A read-only diagnostic view of the in-process anticipation cache.
+   *
+   * Mirrors Python's `anticipation_cache_snapshot()`. Returns the same
+   * snake_case shape, since this output gets logged and compared across SDKs.
+   */
+  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}`);
+  }
+  /** Release timers and connections. Safe to call more than once. */
+  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 pick3(o2, snake, camel) {
+  const a = o2[snake];
+  return a !== void 0 ? a : o2[camel];
+}
+function resolveCredentials(options) {
+  const apiKey = options.apiKey ?? getEnv("SYNAP_API_KEY");
+  if (!apiKey) {
+    throw new InvalidInputError(
+      "No Synap API key found. Set SYNAP_API_KEY in your environment, or pass apiKey to the SynapClient constructor."
+    );
+  }
+  return {
+    apiKey,
+    clientId: options.clientId ?? getEnv("SYNAP_CLIENT_ID") ?? "",
+    instanceId: options.instanceId ?? getEnv("SYNAP_INSTANCE_ID") ?? ""
+  };
+}
+export {
+  ANY_SCOPE,
+  AgentUnavailableError,
+  AnticipationCache,
+  AuthenticationError,
+  BM25,
+  CONTRACT,
+  ConflictError,
+  ConnectionError,
+  ContextNotFoundError,
+  DEFAULT_BASE_URL,
+  DEFAULT_DOCUMENT_TYPE,
+  DEFAULT_INGEST_MODE,
+  DEFAULT_RETRY_POLICY,
+  DEFAULT_TIMEOUTS,
+  DOCUMENT_TYPES,
+  ENDPOINTS,
+  HttpTransport,
+  INGEST_MODES,
+  ITEM_COLLECTIONS,
+  InsufficientCreditsError,
+  InvalidConversationIdError,
+  InvalidInputError,
+  InvalidInstanceIdError,
+  ListeningAlreadyActiveError,
+  ListeningNotActiveError,
+  NetworkTimeoutError,
+  PermanentError,
+  RateLimitError,
+  SDKError,
+  SDK_VERSION,
+  ServiceUnavailableError,
+  SessionExpiredError,
+  SynapClient,
+  SynapError,
+  SynapPermanentError,
+  SynapTransientError,
+  THRESHOLDS,
+  TranscriptConflictError,
+  TransientError,
+  flattenContextItems,
+  formatForPrompt,
+  isOutcomeUnknown,
+  isRecallQuery,
+  isSynapError,
+  mergeScopeResults,
+  resolvePath,
+  shouldRetry,
+  stem,
+  tokenize
+};
+//# sourceMappingURL=index.js.map