@usewhisper/sdk 3.10.0 → 3.11.0

package/router/memory-router.mjs

@@ -0,0 +1,3131 @@
+// ../src/sdk/errors.ts
+var WhisperError = class extends Error {
+  code;
+  status;
+  retryable;
+  hint;
+  requestId;
+  details;
+  constructor(args) {
+    super(args.message, args.cause ? { cause: args.cause } : void 0);
+    this.name = "WhisperError";
+    this.code = args.code;
+    this.status = args.status;
+    this.retryable = args.retryable ?? false;
+    this.hint = args.hint;
+    this.requestId = args.requestId;
+    this.details = args.details;
+  }
+};
+
+// ../src/sdk/core/telemetry.ts
+var DiagnosticsStore = class {
+  maxEntries;
+  records = [];
+  subscribers = /* @__PURE__ */ new Set();
+  constructor(maxEntries = 1e3) {
+    this.maxEntries = Math.max(1, maxEntries);
+  }
+  add(record) {
+    this.records.push(record);
+    if (this.records.length > this.maxEntries) {
+      this.records.splice(0, this.records.length - this.maxEntries);
+    }
+    for (const fn of this.subscribers) {
+      try {
+        fn(record);
+      } catch {
+      }
+    }
+  }
+  getLast(limit = 25) {
+    const count = Math.max(1, limit);
+    return this.records.slice(-count);
+  }
+  snapshot() {
+    const total = this.records.length;
+    const success = this.records.filter((r) => r.success).length;
+    const failure = total - success;
+    const duration = this.records.reduce((acc, item) => acc + item.durationMs, 0);
+    return {
+      total,
+      success,
+      failure,
+      avgDurationMs: total > 0 ? duration / total : 0,
+      lastTraceId: this.records[this.records.length - 1]?.traceId
+    };
+  }
+  subscribe(fn) {
+    this.subscribers.add(fn);
+    return () => {
+      this.subscribers.delete(fn);
+    };
+  }
+};
+
+// ../src/sdk/core/utils.ts
+function normalizeBaseUrl(url) {
+  let normalized = url.trim().replace(/\/+$/, "");
+  normalized = normalized.replace(/\/api\/v1$/i, "");
+  normalized = normalized.replace(/\/v1$/i, "");
+  normalized = normalized.replace(/\/api$/i, "");
+  return normalized;
+}
+function normalizeEndpoint(endpoint) {
+  const withLeadingSlash = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+  if (/^\/api\/v1(\/|$)/i.test(withLeadingSlash)) {
+    return withLeadingSlash.replace(/^\/api/i, "");
+  }
+  return withLeadingSlash;
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function stableHash(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function normalizeQuery(query) {
+  return query.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function randomId(prefix = "id") {
+  return `${prefix}_${stableHash(`${Date.now()}_${Math.random()}`)}`;
+}
+
+// ../src/sdk/core/client.ts
+var DEFAULT_TIMEOUTS = {
+  searchMs: 3e3,
+  writeAckMs: 2e3,
+  bulkMs: 1e4,
+  profileMs: 2500,
+  sessionMs: 2500
+};
+var DEFAULT_RETRYABLE_STATUS = [408, 429, 500, 502, 503, 504];
+var DEFAULT_API_KEY_ONLY_PREFIXES = ["/v1/memory", "/v1/context/query"];
+var DEFAULT_RETRY_ATTEMPTS = {
+  search: 3,
+  writeAck: 2,
+  bulk: 2,
+  profile: 2,
+  session: 2,
+  query: 3,
+  get: 2
+};
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function toMessage(payload, status, statusText) {
+  if (typeof payload === "string" && payload.trim()) return payload;
+  if (isObject(payload)) {
+    const maybeError = payload.error;
+    const maybeMessage = payload.message;
+    if (typeof maybeError === "string" && maybeError.trim()) return maybeError;
+    if (typeof maybeMessage === "string" && maybeMessage.trim()) return maybeMessage;
+    if (isObject(maybeError) && typeof maybeError.message === "string") return maybeError.message;
+  }
+  return `HTTP ${status}: ${statusText}`;
+}
+var RuntimeClientError = class extends Error {
+  status;
+  retryable;
+  code;
+  details;
+  traceId;
+  hint;
+  requestId;
+  constructor(args) {
+    super(args.message);
+    this.name = "RuntimeClientError";
+    this.status = args.status;
+    this.retryable = args.retryable;
+    this.code = args.code;
+    this.details = args.details;
+    this.traceId = args.traceId;
+    this.hint = args.hint;
+    this.requestId = args.requestId;
+  }
+};
+var RuntimeClient = class {
+  apiKey;
+  baseUrl;
+  sdkVersion;
+  compatMode;
+  retryPolicy;
+  timeouts;
+  diagnostics;
+  inFlight = /* @__PURE__ */ new Map();
+  sendApiKeyHeader;
+  fetchImpl;
+  constructor(options, diagnostics) {
+    if (!options.apiKey) {
+      throw new RuntimeClientError({
+        code: "INVALID_API_KEY",
+        message: "API key is required",
+        retryable: false
+      });
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = normalizeBaseUrl(options.baseUrl || "https://context.usewhisper.dev");
+    this.sdkVersion = options.sdkVersion || "2.x-runtime";
+    this.compatMode = options.compatMode || "fallback";
+    this.retryPolicy = {
+      retryableStatusCodes: options.retryPolicy?.retryableStatusCodes || DEFAULT_RETRYABLE_STATUS,
+      retryOnNetworkError: options.retryPolicy?.retryOnNetworkError ?? true,
+      maxBackoffMs: options.retryPolicy?.maxBackoffMs ?? 1200,
+      baseBackoffMs: options.retryPolicy?.baseBackoffMs ?? 250,
+      maxAttemptsByOperation: options.retryPolicy?.maxAttemptsByOperation || {}
+    };
+    this.timeouts = {
+      ...DEFAULT_TIMEOUTS,
+      ...options.timeouts || {}
+    };
+    this.sendApiKeyHeader = process.env.WHISPER_SEND_X_API_KEY === "1";
+    this.fetchImpl = options.fetchImpl || fetch;
+    this.diagnostics = diagnostics || new DiagnosticsStore(1e3);
+  }
+  getDiagnosticsStore() {
+    return this.diagnostics;
+  }
+  getCompatMode() {
+    return this.compatMode;
+  }
+  timeoutFor(operation) {
+    switch (operation) {
+      case "search":
+        return this.timeouts.searchMs;
+      case "writeAck":
+        return this.timeouts.writeAckMs;
+      case "bulk":
+        return this.timeouts.bulkMs;
+      case "profile":
+        return this.timeouts.profileMs;
+      case "session":
+        return this.timeouts.sessionMs;
+      case "query":
+      case "get":
+      default:
+        return this.timeouts.searchMs;
+    }
+  }
+  maxAttemptsFor(operation) {
+    const override = this.retryPolicy.maxAttemptsByOperation?.[operation];
+    return Math.max(1, override ?? DEFAULT_RETRY_ATTEMPTS[operation]);
+  }
+  shouldRetryStatus(status) {
+    return status !== void 0 && this.retryPolicy.retryableStatusCodes?.includes(status) === true;
+  }
+  backoff(attempt) {
+    const base = this.retryPolicy.baseBackoffMs ?? 250;
+    const max = this.retryPolicy.maxBackoffMs ?? 1200;
+    const jitter = 0.8 + Math.random() * 0.4;
+    return Math.min(max, Math.floor(base * Math.pow(2, attempt) * jitter));
+  }
+  runtimeName() {
+    const maybeWindow = globalThis.window;
+    return maybeWindow && typeof maybeWindow === "object" ? "browser" : "node";
+  }
+  apiKeyOnlyPrefixes() {
+    const raw = process.env.WHISPER_API_KEY_ONLY_PREFIXES;
+    if (!raw || !raw.trim()) return DEFAULT_API_KEY_ONLY_PREFIXES;
+    return raw.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+  }
+  shouldAttachApiKeyHeader(endpoint) {
+    if (this.sendApiKeyHeader) return true;
+    const prefixes = this.apiKeyOnlyPrefixes();
+    return prefixes.some((prefix) => endpoint === prefix || endpoint.startsWith(`${prefix}/`));
+  }
+  createRequestFingerprint(options) {
+    const normalizedEndpoint = normalizeEndpoint(options.endpoint);
+    const authFingerprint = stableHash(this.apiKey.replace(/^Bearer\s+/i, ""));
+    const payload = JSON.stringify({
+      method: options.method || "GET",
+      endpoint: normalizedEndpoint,
+      body: options.body || null,
+      extra: options.dedupeKeyExtra || "",
+      authFingerprint
+    });
+    return stableHash(payload);
+  }
+  async request(options) {
+    const dedupeKey = options.idempotent ? this.createRequestFingerprint(options) : null;
+    if (dedupeKey) {
+      const inFlight = this.inFlight.get(dedupeKey);
+      if (inFlight) {
+        const data = await inFlight;
+        this.diagnostics.add({
+          id: randomId("diag"),
+          startedAt: nowIso(),
+          endedAt: nowIso(),
+          traceId: data.traceId,
+          spanId: randomId("span"),
+          operation: options.operation,
+          method: options.method || "GET",
+          endpoint: normalizeEndpoint(options.endpoint),
+          status: data.status,
+          durationMs: 0,
+          success: true,
+          deduped: true
+        });
+        const cloned = {
+          data: data.data,
+          status: data.status,
+          traceId: data.traceId
+        };
+        return cloned;
+      }
+    }
+    const runner = this.performRequest(options).then((data) => {
+      if (dedupeKey) this.inFlight.delete(dedupeKey);
+      return data;
+    }).catch((error) => {
+      if (dedupeKey) this.inFlight.delete(dedupeKey);
+      throw error;
+    });
+    if (dedupeKey) {
+      this.inFlight.set(dedupeKey, runner);
+    }
+    return runner;
+  }
+  async performRequest(options) {
+    const method = options.method || "GET";
+    const normalizedEndpoint = normalizeEndpoint(options.endpoint);
+    const operation = options.operation;
+    const maxAttempts = this.maxAttemptsFor(operation);
+    const timeoutMs = this.timeoutFor(operation);
+    const traceId = options.traceId || randomId("trace");
+    let lastError = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      const spanId = randomId("span");
+      const startedAt = Date.now();
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const attachApiKeyHeader = this.shouldAttachApiKeyHeader(normalizedEndpoint);
+        const response = await this.fetchImpl(`${this.baseUrl}${normalizedEndpoint}`, {
+          method,
+          signal: controller.signal,
+          keepalive: method !== "GET",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`,
+            ...attachApiKeyHeader ? { "X-API-Key": this.apiKey.replace(/^Bearer\s+/i, "") } : {},
+            "x-trace-id": traceId,
+            "x-span-id": spanId,
+            "x-sdk-version": this.sdkVersion,
+            "x-sdk-runtime": this.runtimeName(),
+            ...options.headers || {}
+          },
+          body: method === "GET" || method === "DELETE" ? void 0 : JSON.stringify(options.body || {})
+        });
+        clearTimeout(timeout);
+        let payload = null;
+        try {
+          payload = await response.json();
+        } catch {
+          payload = await response.text().catch(() => "");
+        }
+        const durationMs = Date.now() - startedAt;
+        const record = {
+          id: randomId("diag"),
+          startedAt: new Date(startedAt).toISOString(),
+          endedAt: nowIso(),
+          traceId,
+          spanId,
+          operation,
+          method,
+          endpoint: normalizedEndpoint,
+          status: response.status,
+          durationMs,
+          success: response.ok
+        };
+        this.diagnostics.add(record);
+        if (response.ok) {
+          return {
+            data: payload,
+            status: response.status,
+            traceId
+          };
+        }
+        const message = toMessage(payload, response.status, response.statusText);
+        const payloadObject = isObject(payload) ? payload : {};
+        const payloadCode = typeof payloadObject.code === "string" ? payloadObject.code : void 0;
+        const payloadHint = typeof payloadObject.hint === "string" ? payloadObject.hint : void 0;
+        const payloadRequestId = typeof payloadObject.requestId === "string" ? payloadObject.requestId : typeof payloadObject.request_id === "string" ? payloadObject.request_id : void 0;
+        const payloadRetryable = typeof payloadObject.retryable === "boolean" ? payloadObject.retryable : void 0;
+        const statusRetryable = this.shouldRetryStatus(response.status);
+        const retryable = payloadRetryable ?? statusRetryable;
+        const error = new RuntimeClientError({
+          message,
+          status: response.status,
+          retryable,
+          code: payloadCode || (response.status === 404 ? "NOT_FOUND" : "REQUEST_FAILED"),
+          details: payload,
+          traceId: payloadRequestId || traceId,
+          requestId: payloadRequestId || traceId,
+          hint: payloadHint
+        });
+        lastError = error;
+        if (!retryable || attempt === maxAttempts - 1) {
+          throw error;
+        }
+      } catch (error) {
+        clearTimeout(timeout);
+        const durationMs = Date.now() - startedAt;
+        const isAbort = isObject(error) && error.name === "AbortError";
+        const mapped = error instanceof RuntimeClientError ? error : new RuntimeClientError({
+          message: isAbort ? "Request timed out" : error instanceof Error ? error.message : "Network error",
+          retryable: this.retryPolicy.retryOnNetworkError ?? true,
+          code: isAbort ? "TIMEOUT" : "NETWORK_ERROR",
+          traceId,
+          requestId: traceId
+        });
+        lastError = mapped;
+        this.diagnostics.add({
+          id: randomId("diag"),
+          startedAt: new Date(startedAt).toISOString(),
+          endedAt: nowIso(),
+          traceId,
+          spanId,
+          operation,
+          method,
+          endpoint: normalizedEndpoint,
+          durationMs,
+          success: false,
+          errorCode: mapped.code,
+          errorMessage: mapped.message
+        });
+        if (!mapped.retryable || attempt === maxAttempts - 1) {
+          throw mapped;
+        }
+      }
+      await new Promise((resolve) => setTimeout(resolve, this.backoff(attempt)));
+    }
+    throw lastError || new RuntimeClientError({
+      message: "Request failed",
+      retryable: false,
+      code: "REQUEST_FAILED"
+    });
+  }
+};
+
+// ../src/sdk/core/cache.ts
+var SearchResponseCache = class {
+  ttlMs;
+  capacity;
+  byKey = /* @__PURE__ */ new Map();
+  scopeIndex = /* @__PURE__ */ new Map();
+  constructor(ttlMs = 7e3, capacity = 500) {
+    this.ttlMs = Math.max(1e3, ttlMs);
+    this.capacity = Math.max(10, capacity);
+  }
+  makeScopeKey(project, userId, sessionId) {
+    return `${project}:${userId || "_"}:${sessionId || "_"}`;
+  }
+  makeKey(input) {
+    const normalized = {
+      project: input.project,
+      userId: input.userId || "",
+      sessionId: input.sessionId || "",
+      query: normalizeQuery(input.query),
+      topK: input.topK,
+      profile: input.profile,
+      includePending: input.includePending
+    };
+    return `search:${stableHash(JSON.stringify(normalized))}`;
+  }
+  get(key) {
+    const found = this.byKey.get(key);
+    if (!found) return null;
+    if (found.expiresAt <= Date.now()) {
+      this.deleteByKey(key);
+      return null;
+    }
+    found.touchedAt = Date.now();
+    return found.value;
+  }
+  set(key, scopeKey, value) {
+    this.byKey.set(key, {
+      value,
+      scopeKey,
+      touchedAt: Date.now(),
+      expiresAt: Date.now() + this.ttlMs
+    });
+    if (!this.scopeIndex.has(scopeKey)) {
+      this.scopeIndex.set(scopeKey, /* @__PURE__ */ new Set());
+    }
+    this.scopeIndex.get(scopeKey).add(key);
+    this.evictIfNeeded();
+  }
+  invalidateScope(scopeKey) {
+    const keys = this.scopeIndex.get(scopeKey);
+    if (!keys || keys.size === 0) {
+      return 0;
+    }
+    const toDelete = Array.from(keys);
+    for (const key of toDelete) {
+      this.deleteByKey(key);
+    }
+    this.scopeIndex.delete(scopeKey);
+    return toDelete.length;
+  }
+  evictIfNeeded() {
+    if (this.byKey.size <= this.capacity) return;
+    const ordered = Array.from(this.byKey.entries()).sort((a, b) => a[1].touchedAt - b[1].touchedAt);
+    const removeCount = this.byKey.size - this.capacity;
+    for (let i = 0; i < removeCount; i += 1) {
+      this.deleteByKey(ordered[i][0]);
+    }
+  }
+  deleteByKey(key) {
+    const found = this.byKey.get(key);
+    if (!found) return;
+    this.byKey.delete(key);
+    const scopeKeys = this.scopeIndex.get(found.scopeKey);
+    if (!scopeKeys) return;
+    scopeKeys.delete(key);
+    if (scopeKeys.size === 0) {
+      this.scopeIndex.delete(found.scopeKey);
+    }
+  }
+};
+
+// ../src/sdk/core/queue.ts
+var InMemoryQueueStore = class {
+  items = [];
+  async load() {
+    return [...this.items];
+  }
+  async save(items) {
+    this.items = [...items];
+  }
+};
+var WriteQueue = class {
+  flushHandler;
+  store;
+  maxBatchSize;
+  flushIntervalMs;
+  maxAttempts;
+  queue = [];
+  flushTimer = null;
+  flushing = false;
+  lastFlushAt;
+  lastFlushCount = 0;
+  constructor(args) {
+    this.flushHandler = args.flushHandler;
+    this.store = args.store || new InMemoryQueueStore();
+    this.maxBatchSize = Math.max(1, args.maxBatchSize ?? 50);
+    this.flushIntervalMs = Math.max(10, args.flushIntervalMs ?? 100);
+    this.maxAttempts = Math.max(1, args.maxAttempts ?? 2);
+  }
+  async start() {
+    const pending = await this.store.load();
+    if (pending.length > 0) {
+      this.queue.push(...pending);
+    }
+    if (!this.flushTimer) {
+      this.flushTimer = setInterval(() => {
+        void this.flush();
+      }, this.flushIntervalMs);
+      const timer = this.flushTimer;
+      if (typeof timer.unref === "function") {
+        timer.unref();
+      }
+    }
+    this.bindProcessHooks();
+  }
+  async stop() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+  }
+  status() {
+    return {
+      queued: this.queue.length,
+      flushing: this.flushing,
+      lastFlushAt: this.lastFlushAt,
+      lastFlushCount: this.lastFlushCount
+    };
+  }
+  async enqueue(input) {
+    const eventId = input.eventId || this.makeEventId(input);
+    const item = {
+      ...input,
+      eventId,
+      createdAt: nowIso()
+    };
+    this.queue.push(item);
+    await this.store.save(this.queue);
+    if (this.queue.length >= this.maxBatchSize) {
+      void this.flush();
+    }
+    return item;
+  }
+  async flush() {
+    if (this.flushing || this.queue.length === 0) return;
+    this.flushing = true;
+    try {
+      while (this.queue.length > 0) {
+        const batch = this.queue.slice(0, this.maxBatchSize);
+        let done = false;
+        let error = null;
+        for (let attempt = 0; attempt < this.maxAttempts; attempt += 1) {
+          try {
+            await this.flushHandler(batch);
+            done = true;
+            break;
+          } catch (err) {
+            error = err;
+            await new Promise((resolve) => setTimeout(resolve, (attempt + 1) * 180));
+          }
+        }
+        if (!done) {
+          throw error instanceof Error ? error : new Error("Queue flush failed");
+        }
+        this.queue.splice(0, batch.length);
+        this.lastFlushAt = nowIso();
+        this.lastFlushCount = batch.length;
+        await this.store.save(this.queue);
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+  makeEventId(input) {
+    const source = JSON.stringify({
+      project: input.project,
+      userId: input.userId || "",
+      sessionId: input.sessionId || "",
+      payload: input.payload
+    });
+    return `evt_${stableHash(source)}`;
+  }
+  bindProcessHooks() {
+    if (typeof process === "undefined") return;
+    const proc = process;
+    const flushOnExit = () => {
+      void this.flush();
+    };
+    proc.once("beforeExit", flushOnExit);
+    proc.once("SIGINT", flushOnExit);
+    proc.once("SIGTERM", flushOnExit);
+  }
+};
+function createStorageQueueStore(key = "whisper_sdk_queue") {
+  const getStorage = () => {
+    const maybeStorage = globalThis.localStorage;
+    if (!maybeStorage || typeof maybeStorage !== "object") return null;
+    const candidate = maybeStorage;
+    if (typeof candidate.getItem !== "function" || typeof candidate.setItem !== "function") {
+      return null;
+    }
+    return {
+      getItem: candidate.getItem,
+      setItem: candidate.setItem
+    };
+  };
+  return {
+    async load() {
+      const storage = getStorage();
+      if (!storage) return [];
+      const raw = storage.getItem(key);
+      if (!raw) return [];
+      try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+      } catch {
+        return [];
+      }
+    },
+    async save(items) {
+      const storage = getStorage();
+      if (!storage) return;
+      storage.setItem(key, JSON.stringify(items));
+    }
+  };
+}
+function createFileQueueStore(filePath) {
+  return {
+    async load() {
+      if (typeof process === "undefined") return [];
+      const fs = await import("fs/promises");
+      try {
+        const raw = await fs.readFile(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+      } catch (error) {
+        const nodeError = error;
+        if (nodeError?.code === "ENOENT") {
+          return [];
+        }
+        return [];
+      }
+    },
+    async save(items) {
+      if (typeof process === "undefined") return;
+      const fs = await import("fs/promises");
+      const path = await import("path");
+      const dir = path.dirname(filePath);
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(filePath, JSON.stringify(items), "utf8");
+    }
+  };
+}
+
+// ../src/sdk/modules/memory.ts
+function isEndpointNotFound(error) {
+  return error instanceof RuntimeClientError && error.status === 404;
+}
+function toSotaType(memoryType) {
+  if (!memoryType) return void 0;
+  switch (memoryType) {
+    case "episodic":
+      return "event";
+    case "semantic":
+      return "factual";
+    case "procedural":
+      return "instruction";
+    default:
+      return memoryType;
+  }
+}
+function toLegacyType(memoryType) {
+  if (!memoryType) return void 0;
+  switch (memoryType) {
+    case "event":
+      return "episodic";
+    case "instruction":
+      return "procedural";
+    case "preference":
+    case "relationship":
+    case "opinion":
+    case "goal":
+      return "semantic";
+    default:
+      return memoryType;
+  }
+}
+var MemoryModule = class {
+  constructor(client, cache, queue, options = {}) {
+    this.client = client;
+    this.cache = cache;
+    this.queue = queue;
+    this.options = options;
+  }
+  resolveProject(project) {
+    const value = project || this.options.defaultProject;
+    if (!value) {
+      throw new RuntimeClientError({
+        code: "MISSING_PROJECT",
+        message: "Project is required",
+        retryable: false
+      });
+    }
+    return value;
+  }
+  invalidate(project, userId, sessionId) {
+    if (this.options.cacheEnabled === false) {
+      return;
+    }
+    const scope = this.cache.makeScopeKey(project, userId, sessionId);
+    this.cache.invalidateScope(scope);
+  }
+  async add(params) {
+    const project = this.resolveProject(params.project);
+    const queueEnabled = this.options.queueEnabled !== false;
+    const useQueue = queueEnabled && (params.write_mode === "async" || params.async === true);
+    if (useQueue) {
+      const queued = await this.queue.enqueue({
+        project,
+        userId: params.user_id,
+        sessionId: params.session_id,
+        payload: {
+          content: params.content,
+          memory_type: toSotaType(params.memory_type),
+          user_id: params.user_id,
+          session_id: params.session_id,
+          agent_id: params.agent_id,
+          importance: params.importance,
+          confidence: params.confidence,
+          metadata: params.metadata,
+          document_date: params.document_date,
+          event_date: params.event_date
+        }
+      });
+      this.invalidate(project, params.user_id, params.session_id);
+      return {
+        success: true,
+        mode: "async",
+        queued: true,
+        event_id: queued.eventId,
+        accepted_at: queued.createdAt
+      };
+    }
+    try {
+      const response = await this.client.request({
+        endpoint: "/v1/memory",
+        method: "POST",
+        operation: "writeAck",
+        body: {
+          project,
+          content: params.content,
+          memory_type: toSotaType(params.memory_type),
+          user_id: params.user_id,
+          session_id: params.session_id,
+          agent_id: params.agent_id,
+          importance: params.importance,
+          confidence: params.confidence,
+          metadata: params.metadata,
+          document_date: params.document_date,
+          event_date: params.event_date,
+          write_mode: params.write_mode === "async" || params.async === true ? "async" : "sync"
+        }
+      });
+      this.invalidate(project, params.user_id, params.session_id);
+      return {
+        success: true,
+        mode: "sync",
+        trace_id: response.trace_id || response.traceId,
+        memory_id: response.memory_id || response.memory?.id,
+        semantic_status: response.semantic_status || response.memory?.semantic_status,
+        pending_visibility: Boolean(response.pending_visibility),
+        visibility_sla_ms: response.visibility_sla_ms
+      };
+    } catch (error) {
+      if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
+        throw error;
+      }
+      await this.client.request({
+        endpoint: "/v1/memories",
+        method: "POST",
+        operation: "writeAck",
+        body: {
+          project,
+          content: params.content,
+          memory_type: toLegacyType(params.memory_type),
+          user_id: params.user_id,
+          session_id: params.session_id,
+          agent_id: params.agent_id,
+          importance: params.importance,
+          metadata: params.metadata
+        }
+      });
+      this.invalidate(project, params.user_id, params.session_id);
+      return {
+        success: true,
+        mode: "sync"
+      };
+    }
+  }
+  async addBulk(params) {
+    const project = this.resolveProject(params.project);
+    if (!Array.isArray(params.memories) || params.memories.length === 0) {
+      throw new RuntimeClientError({
+        code: "VALIDATION_ERROR",
+        message: "memories is required",
+        retryable: false
+      });
+    }
+    const queueEnabled = this.options.queueEnabled !== false;
+    const useQueue = queueEnabled && (params.write_mode === "async" || params.async === true);
+    if (useQueue) {
+      const queued = await Promise.all(
+        params.memories.map(
+          (memory) => this.queue.enqueue({
+            project,
+            userId: memory.user_id,
+            sessionId: memory.session_id,
+            payload: {
+              content: memory.content,
+              memory_type: toSotaType(memory.memory_type),
+              user_id: memory.user_id,
+              session_id: memory.session_id,
+              agent_id: memory.agent_id,
+              importance: memory.importance,
+              confidence: memory.confidence,
+              metadata: memory.metadata,
+              document_date: memory.document_date,
+              event_date: memory.event_date
+            }
+          })
+        )
+      );
+      for (const memory of params.memories) {
+        this.invalidate(project, memory.user_id, memory.session_id);
+      }
+      return {
+        success: true,
+        mode: "async",
+        queued: true,
+        created: queued.length
+      };
+    }
+    try {
+      const response = await this.client.request({
+        endpoint: "/v1/memory/bulk",
+        method: "POST",
+        operation: "bulk",
+        body: {
+          project,
+          memories: params.memories.map((memory) => ({
+            ...memory,
+            memory_type: toSotaType(memory.memory_type)
+          })),
+          write_mode: params.write_mode === "async" || params.async === true ? "async" : "sync"
+        }
+      });
+      for (const memory of params.memories) {
+        this.invalidate(project, memory.user_id, memory.session_id);
+      }
+      return {
+        success: true,
+        mode: "sync",
+        trace_id: response.traceId
+      };
+    } catch (error) {
+      if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
+        throw error;
+      }
+      await Promise.all(
+        params.memories.map(
+          (memory) => this.add({
+            project,
+            ...memory,
+            write_mode: "sync"
+          })
+        )
+      );
+      return {
+        success: true,
+        mode: "sync"
+      };
+    }
+  }
+  async search(params) {
+    const project = this.resolveProject(params.project);
+    const topK = params.top_k || 10;
+    const profile = params.profile || "fast";
+    const includePending = params.include_pending !== false;
+    const cacheKey = this.cache.makeKey({
+      project,
+      userId: params.user_id,
+      sessionId: params.session_id,
+      query: params.query,
+      topK,
+      profile,
+      includePending
+    });
+    if (this.options.cacheEnabled !== false) {
+      const cached = this.cache.get(cacheKey);
+      if (cached) {
+        return {
+          ...cached,
+          cache_hit: true
+        };
+      }
+    }
+    try {
+      const response = await this.client.request({
+        endpoint: "/v1/memory/search",
+        method: "POST",
+        operation: "search",
+        idempotent: true,
+        body: {
+          project,
+          query: params.query,
+          user_id: params.user_id,
+          session_id: params.session_id,
+          top_k: topK,
+          profile,
+          include_pending: includePending,
+          memory_types: params.memory_type ? [toSotaType(params.memory_type)] : void 0
+        }
+      });
+      const data = {
+        ...response.data || {},
+        cache_hit: false
+      };
+      if (this.options.cacheEnabled !== false) {
+        const scope = this.cache.makeScopeKey(project, params.user_id, params.session_id);
+        this.cache.set(cacheKey, scope, data);
+      }
+      return data;
+    } catch (error) {
+      if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
+        throw error;
+      }
+      const legacy = await this.client.request({
+        endpoint: "/v1/memories/search",
+        method: "POST",
+        operation: "search",
+        idempotent: true,
+        body: {
+          project,
+          query: params.query,
+          user_id: params.user_id,
+          session_id: params.session_id,
+          top_k: topK,
+          memory_type: toLegacyType(params.memory_type)
+        }
+      });
+      const data = {
+        ...legacy.data || {},
+        cache_hit: false
+      };
+      if (this.options.cacheEnabled !== false) {
+        const scope = this.cache.makeScopeKey(project, params.user_id, params.session_id);
+        this.cache.set(cacheKey, scope, data);
+      }
+      return data;
+    }
+  }
+  async getUserProfile(params) {
+    const project = this.resolveProject(params.project);
+    const query = new URLSearchParams({
+      project,
+      ...params.include_pending !== void 0 ? { include_pending: String(params.include_pending) } : {},
+      ...params.memory_types ? { memory_types: params.memory_types } : {}
+    });
+    try {
+      const response = await this.client.request({
+        endpoint: `/v1/memory/profile/${params.user_id}?${query}`,
+        method: "GET",
+        operation: "profile",
+        idempotent: true
+      });
+      return response.data;
+    } catch (error) {
+      if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
+        throw error;
+      }
+      const legacyQuery = new URLSearchParams({
+        project,
+        user_id: params.user_id,
+        limit: "200"
+      });
+      const legacy = await this.client.request({
+        endpoint: `/v1/memories?${legacyQuery}`,
+        method: "GET",
+        operation: "profile",
+        idempotent: true
+      });
+      const memories = Array.isArray(legacy.data?.memories) ? legacy.data.memories : [];
+      return {
+        user_id: params.user_id,
+        memories,
+        count: memories.length
+      };
+    }
+  }
+  async getSessionMemories(params) {
+    const project = this.resolveProject(params.project);
+    const query = new URLSearchParams({
+      project,
+      ...params.limit ? { limit: String(params.limit) } : {},
+      ...params.include_pending !== void 0 ? { include_pending: String(params.include_pending) } : {}
+    });
+    const response = await this.client.request({
+      endpoint: `/v1/memory/session/${params.session_id}?${query}`,
+      method: "GET",
+      operation: "profile",
+      idempotent: true
+    });
+    return response.data;
+  }
+  async get(memoryId) {
+    try {
+      const response = await this.client.request({
+        endpoint: `/v1/memory/${memoryId}`,
+        method: "GET",
+        operation: "get",
+        idempotent: true
+      });
+      return response.data;
+    } catch (error) {
+      if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
+        throw error;
+      }
+      const legacy = await this.client.request({
+        endpoint: `/v1/memories/${memoryId}`,
+        method: "GET",
+        operation: "get",
+        idempotent: true
+      });
+      return legacy.data;
+    }
+  }
+  async update(memoryId, params) {
+    try {
+      await this.client.request({
+        endpoint: `/v1/memory/${memoryId}`,
+        method: "PUT",
+        operation: "writeAck",
+        body: params
+      });
+      return { success: true };
+    } catch (error) {
+      if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
+        throw error;
+      }
+      await this.client.request({
+        endpoint: `/v1/memories/${memoryId}`,
+        method: "PUT",
+        operation: "writeAck",
+        body: { content: params.content }
+      });
+      return { success: true };
+    }
+  }
+  async delete(memoryId) {
+    try {
+      await this.client.request({
+        endpoint: `/v1/memory/${memoryId}`,
+        method: "DELETE",
+        operation: "writeAck"
+      });
+      return { success: true, deleted: memoryId };
+    } catch (error) {
+      if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
+        throw error;
+      }
+      await this.client.request({
+        endpoint: `/v1/memories/${memoryId}`,
+        method: "DELETE",
+        operation: "writeAck"
+      });
+      return { success: true, deleted: memoryId };
+    }
+  }
+  async flag(params) {
+    try {
+      await this.client.request({
+        endpoint: `/v1/memory/${params.memoryId}/flag`,
+        method: "POST",
+        operation: "writeAck",
+        body: {
+          reason: params.reason,
+          severity: params.severity || "medium"
+        }
+      });
+      return { success: true };
+    } catch (error) {
+      if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
+        throw error;
+      }
+      await this.client.request({
+        endpoint: `/v1/memory/${params.memoryId}`,
+        method: "PUT",
+        operation: "writeAck",
+        body: {
+          content: `[FLAGGED:${params.severity || "medium"}] ${params.reason}`
+        }
+      });
+      return { success: true };
+    }
+  }
+};
+
+// ../src/sdk/modules/session.ts
+function randomSessionId() {
+  return `sess_${stableHash(`${Date.now()}_${Math.random()}`)}`;
+}
+function assertTransition(current, next) {
+  const allowed = {
+    created: ["active", "ended", "archived"],
+    active: ["suspended", "ended", "archived"],
+    suspended: ["resumed", "ended", "archived"],
+    resumed: ["suspended", "ended", "archived"],
+    ended: ["archived"],
+    archived: []
+  };
+  if (!allowed[current].includes(next)) {
+    throw new RuntimeClientError({
+      code: "INVALID_SESSION_STATE",
+      message: `Invalid session transition ${current} -> ${next}`,
+      retryable: false
+    });
+  }
+}
+var SessionModule = class {
+  constructor(memory, defaultProject) {
+    this.memory = memory;
+    this.defaultProject = defaultProject;
+  }
+  sessions = /* @__PURE__ */ new Map();
+  resolveProject(project) {
+    const value = project || this.defaultProject;
+    if (!value) {
+      throw new RuntimeClientError({
+        code: "MISSING_PROJECT",
+        message: "Project is required",
+        retryable: false
+      });
+    }
+    return value;
+  }
+  ensure(sessionId) {
+    const found = this.sessions.get(sessionId);
+    if (!found) {
+      throw new RuntimeClientError({
+        code: "SESSION_NOT_FOUND",
+        message: `Unknown session ${sessionId}`,
+        retryable: false
+      });
+    }
+    return found;
+  }
+  async start(params) {
+    const project = this.resolveProject(params.project);
+    const sessionId = params.sessionId || randomSessionId();
+    const now = nowIso();
+    const record = {
+      sessionId,
+      project,
+      userId: params.userId,
+      state: "active",
+      sequence: 0,
+      metadata: params.metadata,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.sessions.set(sessionId, record);
+    return {
+      sessionId,
+      state: record.state,
+      createdAt: now
+    };
+  }
+  async event(params) {
+    const session = this.ensure(params.sessionId);
+    if (session.state !== "active" && session.state !== "resumed") {
+      throw new RuntimeClientError({
+        code: "INVALID_SESSION_STATE",
+        message: `Cannot append event in ${session.state} state`,
+        retryable: false
+      });
+    }
+    session.sequence += 1;
+    session.updatedAt = nowIso();
+    const eventId = `evt_${stableHash(JSON.stringify({
+      sessionId: session.sessionId,
+      seq: session.sequence,
+      type: params.type,
+      content: params.content,
+      parent: params.parentEventId || ""
+    }))}`;
+    await this.memory.add({
+      project: session.project,
+      content: `${params.type}: ${params.content}`,
+      memory_type: "event",
+      user_id: session.userId,
+      session_id: session.sessionId,
+      metadata: {
+        session_event: true,
+        event_id: eventId,
+        sequence: session.sequence,
+        parent_event_id: params.parentEventId,
+        ...session.metadata,
+        ...params.metadata || {}
+      },
+      write_mode: "async"
+    });
+    return {
+      success: true,
+      eventId,
+      sequence: session.sequence
+    };
+  }
+  async suspend(params) {
+    const session = this.ensure(params.sessionId);
+    assertTransition(session.state, "suspended");
+    session.state = "suspended";
+    session.updatedAt = nowIso();
+    return { sessionId: session.sessionId, state: session.state };
+  }
+  async resume(params) {
+    const session = this.ensure(params.sessionId);
+    const target = session.state === "suspended" ? "resumed" : "active";
+    assertTransition(session.state, target);
+    session.state = target;
+    session.updatedAt = nowIso();
+    return { sessionId: session.sessionId, state: session.state };
+  }
+  async end(params) {
+    const session = this.ensure(params.sessionId);
+    assertTransition(session.state, "ended");
+    session.state = "ended";
+    session.updatedAt = nowIso();
+    return { sessionId: session.sessionId, state: session.state };
+  }
+  async archive(params) {
+    const session = this.ensure(params.sessionId);
+    assertTransition(session.state, "archived");
+    session.state = "archived";
+    session.updatedAt = nowIso();
+    return { sessionId: session.sessionId, state: session.state };
+  }
+};
+
+// ../src/sdk/modules/profile.ts
+var ProfileModule = class {
+  constructor(memory) {
+    this.memory = memory;
+  }
+  async getUserProfile(params) {
+    return this.memory.getUserProfile(params);
+  }
+  async getSessionMemories(params) {
+    return this.memory.getSessionMemories(params);
+  }
+};
+
+// ../src/sdk/modules/analytics.ts
+var AnalyticsModule = class {
+  constructor(diagnostics, queue) {
+    this.diagnostics = diagnostics;
+    this.queue = queue;
+  }
+  diagnosticsSnapshot() {
+    return this.diagnostics.snapshot();
+  }
+  queueStatus() {
+    return this.queue.status();
+  }
+};
+
+// ../src/sdk/agent-runtime.ts
+function detectBrowserStorage() {
+  const maybeStorage = globalThis.localStorage;
+  if (!maybeStorage || typeof maybeStorage !== "object") return null;
+  const candidate = maybeStorage;
+  if (typeof candidate.getItem !== "function" || typeof candidate.setItem !== "function") {
+    return null;
+  }
+  return {
+    getItem: candidate.getItem,
+    setItem: candidate.setItem
+  };
+}
+function createBindingStore(filePath) {
+  const storage = detectBrowserStorage();
+  if (storage) {
+    const key = "whisper_agent_runtime_bindings";
+    return {
+      async load() {
+        const raw = storage.getItem(key);
+        if (!raw) return {};
+        try {
+          const parsed = JSON.parse(raw);
+          return parsed && typeof parsed === "object" ? parsed : {};
+        } catch {
+          return {};
+        }
+      },
+      async save(bindings) {
+        storage.setItem(key, JSON.stringify(bindings));
+      }
+    };
+  }
+  return {
+    async load() {
+      if (typeof process === "undefined") return {};
+      const fs = await import("fs/promises");
+      const path = filePath || `${process.env.USERPROFILE || process.env.HOME || "."}/.whisper/sdk/agent-bindings.json`;
+      try {
+        const raw = await fs.readFile(path, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+      } catch {
+        return {};
+      }
+    },
+    async save(bindings) {
+      if (typeof process === "undefined") return;
+      const fs = await import("fs/promises");
+      const pathMod = await import("path");
+      const path = filePath || `${process.env.USERPROFILE || process.env.HOME || "."}/.whisper/sdk/agent-bindings.json`;
+      await fs.mkdir(pathMod.dirname(path), { recursive: true });
+      await fs.writeFile(path, JSON.stringify(bindings), "utf8");
+    }
+  };
+}
+function normalizeWorkspacePath(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+  return trimmed.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}
+function pathBase(value) {
+  const normalized = value.replace(/\\/g, "/");
+  const parts = normalized.split("/").filter(Boolean);
+  return parts[parts.length - 1] || normalized;
+}
+function defaultSalience(kind, success) {
+  if (kind === "decision" || kind === "constraint" || kind === "failure") return "high";
+  if (kind === "outcome" || kind === "task_update") return "medium";
+  if (kind === "tool_result" && success === false) return "high";
+  return "low";
+}
+function toMemoryType(kind) {
+  if (kind === "decision" || kind === "constraint") return "instruction";
+  return "event";
+}
+function summarizeLowSalience(events) {
+  const lines = events.slice(-10).map((event) => {
+    const fileSuffix = event.filePaths?.length ? ` [files: ${event.filePaths.join(", ")}]` : "";
+    const toolSuffix = event.toolName ? ` [tool: ${event.toolName}]` : "";
+    return `- ${event.kind}: ${event.summary}${fileSuffix}${toolSuffix}`;
+  });
+  return `Recent low-salience work:
+${lines.join("\n")}`;
+}
+function compactWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function normalizeSummary(value) {
+  return compactWhitespace(String(value || "").toLowerCase());
+}
+function tokenize(value) {
+  return normalizeSummary(value).split(/[^a-z0-9_./-]+/i).map((token) => token.trim()).filter(Boolean);
+}
+function jaccardOverlap(left, right) {
+  const leftTokens = new Set(tokenize(left));
+  const rightTokens = new Set(tokenize(right));
+  if (leftTokens.size === 0 || rightTokens.size === 0) return 0;
+  let intersection = 0;
+  for (const token of leftTokens) {
+    if (rightTokens.has(token)) intersection += 1;
+  }
+  const union = (/* @__PURE__ */ new Set([...leftTokens, ...rightTokens])).size;
+  return union > 0 ? intersection / union : 0;
+}
+function clamp01(value) {
+  if (!Number.isFinite(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+function withTimeout(promise, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error("timeout"));
+    }, timeoutMs);
+    promise.then(
+      (value) => {
+        clearTimeout(timeout);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      }
+    );
+  });
+}
+function extractTimestamp(metadata) {
+  const candidates = [
+    metadata?.updatedAt,
+    metadata?.createdAt,
+    metadata?.timestamp,
+    metadata?.event_date,
+    metadata?.eventDate
+  ];
+  for (const value of candidates) {
+    if (typeof value === "string") {
+      const parsed = Date.parse(value);
+      if (!Number.isNaN(parsed)) return parsed;
+    }
+  }
+  return 0;
+}
+var DEFAULT_RANK_WEIGHTS = {
+  focusedPassBonus: 0.2,
+  sourceMatchBonus: 0.18,
+  touchedFileBonus: 0.12,
+  clientMatchBonus: 0.1,
+  highSalienceBonus: 0.12,
+  mediumSalienceBonus: 0.06,
+  staleBroadPenalty: -0.1,
+  unrelatedClientPenalty: -0.18,
+  lowSaliencePenalty: -0.12
+};
+var DEFAULT_SOURCE_ACTIVITY = {
+  maxTurns: 10,
+  maxIdleMs: 30 * 60 * 1e3,
+  decayAfterTurns: 5,
+  decayAfterIdleMs: 15 * 60 * 1e3,
+  evictOnTaskSwitch: true
+};
+var WhisperAgentRuntime = class {
+  constructor(args) {
+    this.args = args;
+    this.bindingStore = createBindingStore(args.options.bindingStorePath);
+    const retrieval = args.options.retrieval || {};
+    this.focusedTopK = retrieval.focusedTopK ?? args.options.topK ?? 6;
+    this.broadTopK = retrieval.broadTopK ?? Math.max(args.options.topK ?? 6, 10);
+    this.maxTokens = args.options.maxTokens ?? 4e3;
+    this.targetRetrievalMs = args.options.targetRetrievalMs ?? 2500;
+    this.hardRetrievalTimeoutMs = args.options.hardRetrievalTimeoutMs ?? 4e3;
+    this.recentWorkLimit = args.options.recentWorkLimit ?? 40;
+    this.baseContext = args.baseContext;
+    this.clientName = args.baseContext.clientName || "whisper-agent-runtime";
+    this.minFocusedResults = retrieval.minFocusedResults ?? 3;
+    this.minFocusedTopScore = retrieval.minFocusedTopScore ?? 0.55;
+    this.minProjectScore = retrieval.minProjectScore ?? 0.5;
+    this.minMemoryScore = retrieval.minMemoryScore ?? 0.6;
+    this.rankWeights = { ...DEFAULT_RANK_WEIGHTS, ...retrieval.rankWeights || {} };
+    this.sourceActivityOptions = { ...DEFAULT_SOURCE_ACTIVITY, ...retrieval.sourceActivity || {} };
+  }
+  bindingStore;
+  focusedTopK;
+  broadTopK;
+  maxTokens;
+  targetRetrievalMs;
+  hardRetrievalTimeoutMs;
+  recentWorkLimit;
+  baseContext;
+  clientName;
+  minFocusedResults;
+  minFocusedTopScore;
+  minProjectScore;
+  minMemoryScore;
+  rankWeights;
+  sourceActivityOptions;
+  bindings = null;
+  touchedFiles = [];
+  recentWork = [];
+  recentSourceActivity = [];
+  bufferedLowSalience = [];
+  lastPreparedTurn = null;
+  mergedCount = 0;
+  droppedCount = 0;
+  focusedPassHits = 0;
+  fallbackTriggers = 0;
+  floorDroppedCount = 0;
+  injectedItemCount = 0;
+  sourceScopedTurns = 0;
+  broadScopedTurns = 0;
+  totalTurns = 0;
+  currentTurn = 0;
+  lastTaskSummary = "";
+  lastScope = {};
+  async getBindings() {
+    if (!this.bindings) {
+      this.bindings = await this.bindingStore.load();
+    }
+    return this.bindings;
+  }
+  pushTouchedFiles(paths) {
+    if (!paths || paths.length === 0) return;
+    for (const path of paths) {
+      if (!path) continue;
+      this.touchedFiles = [...this.touchedFiles.filter((entry) => entry !== path), path].slice(-20);
+    }
+  }
+  pushWorkEvent(event) {
+    this.recentWork = [...this.recentWork, event].slice(-this.recentWorkLimit);
+  }
+  noteSourceActivity(sourceIds) {
+    const now = Date.now();
+    for (const sourceId of [...new Set((sourceIds || []).map((value) => String(value || "").trim()).filter(Boolean))]) {
+      this.recentSourceActivity = [
+        ...this.recentSourceActivity.filter((entry) => entry.sourceId !== sourceId),
+        { sourceId, turn: this.currentTurn, at: now }
+      ].slice(-24);
+    }
+  }
+  refreshTaskSummary(taskSummary) {
+    const next = normalizeSummary(taskSummary);
+    if (!next) return;
+    if (this.sourceActivityOptions.evictOnTaskSwitch && this.lastTaskSummary && this.lastTaskSummary !== next && jaccardOverlap(this.lastTaskSummary, next) < 0.6) {
+      this.recentSourceActivity = [];
+    }
+    this.lastTaskSummary = next;
+  }
+  activeSourceIds() {
+    const now = Date.now();
+    const active = /* @__PURE__ */ new Map();
+    const maxTurns = this.sourceActivityOptions.maxTurns;
+    const maxIdleMs = this.sourceActivityOptions.maxIdleMs;
+    const decayAfterTurns = this.sourceActivityOptions.decayAfterTurns;
+    const decayAfterIdleMs = this.sourceActivityOptions.decayAfterIdleMs;
+    const fresh = [];
+    for (const entry of this.recentSourceActivity) {
+      const turnDelta = this.currentTurn - entry.turn;
+      const idleDelta = now - entry.at;
+      if (turnDelta > maxTurns || idleDelta > maxIdleMs) continue;
+      fresh.push(entry);
+      let weight = 1;
+      if (turnDelta > decayAfterTurns || idleDelta > decayAfterIdleMs) {
+        weight = 0.5;
+      }
+      const current = active.get(entry.sourceId) || 0;
+      active.set(entry.sourceId, Math.max(current, weight));
+    }
+    this.recentSourceActivity = fresh.slice(-24);
+    return [...active.entries()].sort((left, right) => right[1] - left[1]).map(([sourceId]) => sourceId).slice(0, 4);
+  }
+  focusedScope(input) {
+    const sourceIds = this.activeSourceIds();
+    const fileHints = [...new Set([
+      ...input.touchedFiles || [],
+      ...this.touchedFiles,
+      ...this.recentWork.flatMap((event) => event.filePaths || [])
+    ].map((value) => String(value || "").trim()).filter(Boolean))].slice(-4);
+    return {
+      sourceIds,
+      fileHints,
+      clientName: this.clientName || void 0
+    };
+  }
+  exactFileMetadataFilter(fileHints) {
+    const exact = fileHints.find((value) => /[\\/]/.test(value));
+    if (!exact) return void 0;
+    return { filePath: exact };
+  }
+  makeTaskFrameQuery(input) {
+    const task = compactWhitespace(input.taskSummary || "");
+    const salient = this.recentWork.filter((event) => event.salience === "high").slice(-3).map((event) => `${event.kind}: ${event.summary}`);
+    const files = [...input.touchedFiles || [], ...this.touchedFiles].slice(-3).map((file) => pathBase(file));
+    const parts = [
+      task ? `task ${task}` : "",
+      salient.length > 0 ? `recent ${salient.join(" ; ")}` : "",
+      files.length > 0 ? `files ${files.join(" ")}` : "",
+      input.toolContext ? `tool context ${compactWhitespace(input.toolContext)}` : ""
+    ].filter(Boolean);
+    if (parts.length === 0) return null;
+    return parts.join(" | ");
+  }
+  async resolveScope(overrides) {
+    const merged = {
+      ...this.baseContext,
+      ...overrides
+    };
+    const normalizedWorkspace = normalizeWorkspacePath(merged.workspacePath);
+    const bindings = await this.getBindings();
+    const workspaceProject = normalizedWorkspace ? bindings[normalizedWorkspace] : void 0;
+    const configuredProject = merged.project;
+    let projectRef = configuredProject;
+    let projectSource = overrides?.project ? "explicit" : "generated";
+    let warning;
+    if (workspaceProject) {
+      projectRef = workspaceProject;
+      projectSource = "workspace";
+      if (configuredProject && workspaceProject !== configuredProject) {
+        warning = `workspace mapping '${workspaceProject}' overrides configured project '${configuredProject}'`;
+      }
+    } else if (configuredProject) {
+      projectRef = configuredProject;
+      projectSource = overrides?.project ? "explicit" : "config";
+    }
+    const project = (await this.args.adapter.resolveProject(projectRef)).id;
+    if (normalizedWorkspace) {
+      bindings[normalizedWorkspace] = project;
+      await this.bindingStore.save(bindings);
+    }
+    const scope = {
+      ...merged,
+      project,
+      userId: merged.userId || `${this.clientName}-user`,
+      sessionId: merged.sessionId || `sess_${stableHash(`${this.clientName}_${normalizedWorkspace || "default"}`)}`
+    };
+    this.lastScope = {
+      project: scope.project,
+      userId: scope.userId,
+      sessionId: scope.sessionId,
+      source: projectSource,
+      warning
+    };
+    return { scope, projectSource, warning };
+  }
+  async runBranch(name, task) {
+    const startedAt = Date.now();
+    try {
+      const value = await withTimeout(task(), this.hardRetrievalTimeoutMs);
+      return {
+        name,
+        status: "ok",
+        durationMs: Date.now() - startedAt,
+        value
+      };
+    } catch (error) {
+      const durationMs = Date.now() - startedAt;
+      const reason = error instanceof Error ? error.message : String(error);
+      return {
+        name,
+        status: reason === "timeout" ? "timeout" : "error",
+        durationMs,
+        reason
+      };
+    }
+  }
+  contextItems(result, sourceQuery, pass) {
+    const sourceScope = result.meta?.source_scope;
+    if (sourceScope?.mode === "auto" || sourceScope?.mode === "explicit") {
+      this.noteSourceActivity(sourceScope.source_ids || []);
+    }
+    return (result.results || []).map((item) => ({
+      id: item.id,
+      content: item.content,
+      type: "project",
+      score: item.score ?? 0,
+      sourceQuery,
+      pass,
+      metadata: item.metadata || {}
+    }));
+  }
+  memoryItems(result, sourceQuery, pass) {
+    return (result.results || []).map((item, index) => ({
+      id: item.memory?.id || item.chunk?.id || `${sourceQuery}_memory_${index}`,
+      content: item.chunk?.content || item.memory?.content || "",
+      type: "memory",
+      score: item.similarity ?? 0,
+      sourceQuery,
+      pass,
+      metadata: {
+        ...item.chunk?.metadata || {},
+        ...item.memory?.temporal || {},
+        confidence: item.memory?.confidence
+      }
+    })).filter((item) => item.content);
+  }
+  stableItemKey(item) {
+    const metadata = item.metadata || {};
+    const sourceId = String(metadata.source_id || "");
+    const documentId = String(metadata.document_id || metadata.documentId || "");
+    const chunkId = String(metadata.chunk_id || metadata.chunkId || item.id || "");
+    return stableHash(`${sourceId}|${documentId}|${chunkId}|${item.content.slice(0, 256)}`);
+  }
+  metadataStrings(item) {
+    const metadata = item.metadata || {};
+    return [
+      metadata.filePath,
+      metadata.file_path,
+      metadata.path,
+      metadata.section_path,
+      metadata.parent_section_path,
+      metadata.web_url,
+      metadata.url
+    ].map((value) => String(value || "").toLowerCase()).filter(Boolean);
+  }
+  hasSourceMatch(item, scope) {
+    const sourceId = String(item.metadata?.source_id || "");
+    return Boolean(sourceId && scope.sourceIds.includes(sourceId));
+  }
+  hasFileMatch(item, scope) {
+    if (scope.fileHints.length === 0) return false;
+    const metadata = this.metadataStrings(item);
+    const lowerHints = scope.fileHints.map((hint) => hint.toLowerCase());
+    return lowerHints.some((hint) => {
+      const base = pathBase(hint).toLowerCase();
+      return metadata.some((value) => value.includes(hint) || value.endsWith(base));
+    });
+  }
+  hasClientMatch(item, scope) {
+    const itemClient = String(item.metadata?.client_name || "");
+    return Boolean(scope.clientName && itemClient && itemClient === scope.clientName);
+  }
+  salienceAdjustment(item) {
+    const salience = item.metadata?.salience;
+    if (salience === "high") return this.rankWeights.highSalienceBonus;
+    if (salience === "medium") return this.rankWeights.mediumSalienceBonus;
+    if (salience === "low") return this.rankWeights.lowSaliencePenalty;
+    return 0;
+  }
+  narrowFocusedMemories(items, scope) {
+    const hasSignals = scope.sourceIds.length > 0 || scope.fileHints.length > 0 || Boolean(scope.clientName);
+    if (!hasSignals) return items;
+    const narrowed = items.filter((item) => {
+      const matchesClient = this.hasClientMatch(item, scope);
+      const matchesFile = this.hasFileMatch(item, scope);
+      const matchesSource = this.hasSourceMatch(item, scope);
+      const salience = item.metadata?.salience;
+      if (scope.clientName && item.metadata?.client_name && !matchesClient) {
+        return false;
+      }
+      if (salience === "low" && !matchesFile && !matchesSource) {
+        return false;
+      }
+      return matchesClient || matchesFile || matchesSource || !scope.clientName;
+    });
+    return narrowed.length > 0 ? narrowed : items;
+  }
+  applyRelevanceFloor(items) {
+    const filtered = items.filter(
+      (item) => item.type === "project" ? item.score >= this.minProjectScore : item.score >= this.minMemoryScore
+    );
+    return { items: filtered, dropped: Math.max(0, items.length - filtered.length) };
+  }
+  rerank(items, scope) {
+    const deduped = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      const key = this.stableItemKey(item);
+      const recency = extractTimestamp(item.metadata) > 0 ? 0.04 : 0;
+      const queryBonus = item.sourceQuery === "primary" ? 0.08 : item.sourceQuery === "task_frame" ? 0.04 : 0.03;
+      const sourceMatch = this.hasSourceMatch(item, scope);
+      const fileMatch = this.hasFileMatch(item, scope);
+      const clientMatch = this.hasClientMatch(item, scope);
+      const broadPenalty = item.pass === "broad" && !sourceMatch && !fileMatch && !clientMatch ? this.rankWeights.staleBroadPenalty : 0;
+      const clientPenalty = scope.clientName && item.metadata?.client_name && !clientMatch ? this.rankWeights.unrelatedClientPenalty : 0;
+      const next = {
+        ...item,
+        score: clamp01(
+          item.score + queryBonus + recency + (item.pass === "focused" ? this.rankWeights.focusedPassBonus : 0) + (sourceMatch ? this.rankWeights.sourceMatchBonus : 0) + (fileMatch ? this.rankWeights.touchedFileBonus : 0) + (clientMatch ? this.rankWeights.clientMatchBonus : 0) + this.salienceAdjustment(item) + broadPenalty + clientPenalty
+        )
+      };
+      const existing = deduped.get(key);
+      if (!existing || next.score > existing.score) {
+        deduped.set(key, next);
+      }
+    }
+    return {
+      items: [...deduped.values()].sort((left, right) => right.score - left.score),
+      dedupedCount: Math.max(0, items.length - deduped.size)
+    };
+  }
+  buildContext(items) {
+    const maxChars = this.maxTokens * 4;
+    const lines = [];
+    let used = 0;
+    for (const item of items) {
+      const label = item.type === "memory" ? "memory" : "context";
+      const content = compactWhitespace(item.content);
+      if (!content) continue;
+      const line = `[${label}] ${content}`;
+      if (used + line.length > maxChars) break;
+      lines.push(line);
+      used += line.length;
+    }
+    if (lines.length === 0) return "";
+    return `Relevant context:
+${lines.join("\n")}`;
+  }
+  async bootstrap(context = {}) {
+    const { scope, warning } = await this.resolveScope(context);
+    const warnings = warning ? [warning] : [];
+    const startedAt = Date.now();
+    const branches = await Promise.all([
+      this.runBranch("session_recent", () => this.args.adapter.getSessionMemories({
+        project: scope.project,
+        session_id: scope.sessionId,
+        include_pending: true,
+        limit: 12
+      })),
+      this.runBranch("user_profile", () => scope.userId ? this.args.adapter.getUserProfile({
+        project: scope.project,
+        user_id: scope.userId,
+        include_pending: true,
+        memory_types: "preference,instruction,goal"
+      }) : Promise.resolve({ user_id: scope.userId, memories: [], count: 0 })),
+      this.runBranch("project_rules", () => this.args.adapter.query({
+        project: scope.project,
+        query: "project rules instructions constraints conventions open threads",
+        top_k: this.focusedTopK,
+        include_memories: false,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        max_tokens: this.maxTokens,
+        compress: true,
+        compression_strategy: "adaptive"
+      }))
+    ]);
+    const items = [];
+    const branchStatus = {};
+    for (const branch of branches) {
+      branchStatus[branch.name] = branch.status;
+      if (branch.status !== "ok") {
+        if (branch.reason) warnings.push(`${branch.name}:${branch.reason}`);
+        continue;
+      }
+      if (branch.name === "project_rules") {
+        items.push(...this.contextItems(branch.value, "bootstrap", "bootstrap"));
+        continue;
+      }
+      const records = branch.value.memories || [];
+      items.push(...records.map((memory, index) => ({
+        id: String(memory.id || `${branch.name}_${index}`),
+        content: String(memory.content || ""),
+        type: "memory",
+        score: 0.4,
+        sourceQuery: "bootstrap",
+        pass: "bootstrap",
+        metadata: memory
+      })).filter((item) => item.content));
+    }
+    const reranked = this.rerank(items, { sourceIds: [], fileHints: [], clientName: this.clientName });
+    const ranked = reranked.items.slice(0, this.broadTopK * 2);
+    const prepared = {
+      scope,
+      retrieval: {
+        primaryQuery: "bootstrap",
+        taskFrameQuery: null,
+        warnings,
+        degraded: warnings.length > 0,
+        degradedReason: warnings.length > 0 ? "partial_bootstrap" : void 0,
+        durationMs: Date.now() - startedAt,
+        targetBudgetMs: this.targetRetrievalMs,
+        hardTimeoutMs: this.hardRetrievalTimeoutMs,
+        branchStatus,
+        focusedScopeApplied: false,
+        focusedSourceIds: [],
+        focusedFileHints: [],
+        clientScoped: false,
+        fallbackUsed: false,
+        droppedBelowFloor: 0,
+        dedupedCount: reranked.dedupedCount
+      },
+      context: this.buildContext(ranked),
+      items: ranked
+    };
+    this.lastPreparedTurn = prepared.retrieval;
+    return prepared;
+  }
+  async beforeTurn(input, context = {}) {
+    this.currentTurn += 1;
+    this.pushTouchedFiles(input.touchedFiles);
+    this.refreshTaskSummary(input.taskSummary);
+    const { scope, warning } = await this.resolveScope(context);
+    const primaryQuery = compactWhitespace(input.userMessage);
+    const taskFrameQuery = this.makeTaskFrameQuery(input);
+    const focusedScope = this.focusedScope(input);
+    const focusedMetadataFilter = this.exactFileMetadataFilter(focusedScope.fileHints);
+    const focusedScopeApplied = focusedScope.sourceIds.length > 0 || focusedScope.fileHints.length > 0 || Boolean(focusedScope.clientName);
+    const warnings = warning ? [warning] : [];
+    const startedAt = Date.now();
+    const branchStatus = {};
+    const collectFromBranches = (branches, pass) => {
+      const collected = [];
+      let okCount = 0;
+      for (const branch of branches) {
+        branchStatus[branch.name] = branch.status;
+        if (branch.status !== "ok") {
+          if (branch.status !== "skipped" && branch.reason) warnings.push(`${branch.name}:${branch.reason}`);
+          continue;
+        }
+        okCount += 1;
+        if (branch.name.startsWith("context")) {
+          collected.push(...this.contextItems(
+            branch.value,
+            branch.name.includes("task_frame") ? "task_frame" : "primary",
+            pass
+          ));
+        } else {
+          const memoryItems = this.memoryItems(
+            branch.value,
+            branch.name.includes("task_frame") ? "task_frame" : "primary",
+            pass
+          );
+          collected.push(...pass === "focused" ? this.narrowFocusedMemories(memoryItems, focusedScope) : memoryItems);
+        }
+      }
+      return { collected, okCount };
+    };
+    const focusedBranches = await Promise.all([
+      this.runBranch("context_primary_focused", () => this.args.adapter.query({
+        project: scope.project,
+        query: primaryQuery,
+        top_k: this.focusedTopK,
+        include_memories: false,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        source_ids: focusedScope.sourceIds.length > 0 ? focusedScope.sourceIds : void 0,
+        metadata_filter: focusedMetadataFilter,
+        max_tokens: this.maxTokens,
+        compress: true,
+        compression_strategy: "adaptive"
+      })),
+      this.runBranch("memory_primary_focused", () => this.args.adapter.searchMemories({
+        project: scope.project,
+        query: primaryQuery,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        top_k: this.focusedTopK,
+        include_pending: true,
+        profile: "balanced"
+      })),
+      taskFrameQuery ? this.runBranch("context_task_frame_focused", () => this.args.adapter.query({
+        project: scope.project,
+        query: taskFrameQuery,
+        top_k: this.focusedTopK,
+        include_memories: false,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        source_ids: focusedScope.sourceIds.length > 0 ? focusedScope.sourceIds : void 0,
+        metadata_filter: focusedMetadataFilter,
+        max_tokens: this.maxTokens,
+        compress: true,
+        compression_strategy: "adaptive"
+      })) : Promise.resolve({ name: "context_task_frame_focused", status: "skipped", durationMs: 0 }),
+      taskFrameQuery ? this.runBranch("memory_task_frame_focused", () => this.args.adapter.searchMemories({
+        project: scope.project,
+        query: taskFrameQuery,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        top_k: this.focusedTopK,
+        include_pending: true,
+        profile: "balanced"
+      })) : Promise.resolve({ name: "memory_task_frame_focused", status: "skipped", durationMs: 0 })
+    ]);
+    const focusedCollected = collectFromBranches(focusedBranches, "focused");
+    const focusedRanked = this.rerank(focusedCollected.collected, focusedScope);
+    const focusedFloored = this.applyRelevanceFloor(focusedRanked.items);
+    let allCollected = [...focusedFloored.items];
+    let totalOkCount = focusedCollected.okCount;
+    let dedupedCount = focusedRanked.dedupedCount;
+    let droppedBelowFloor = focusedFloored.dropped;
+    const focusedTopScore = focusedFloored.items[0]?.score ?? 0;
+    const fallbackUsed = focusedFloored.items.length < this.minFocusedResults || focusedTopScore < this.minFocusedTopScore;
+    if (focusedScopeApplied) {
+      this.sourceScopedTurns += 1;
+    }
+    if (!fallbackUsed) {
+      this.focusedPassHits += 1;
+    }
+    const broadBranches = fallbackUsed ? await Promise.all([
+      this.runBranch("context_primary_broad", () => this.args.adapter.query({
+        project: scope.project,
+        query: primaryQuery,
+        top_k: this.broadTopK,
+        include_memories: false,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        max_tokens: this.maxTokens,
+        compress: true,
+        compression_strategy: "adaptive"
+      })),
+      this.runBranch("memory_primary_broad", () => this.args.adapter.searchMemories({
+        project: scope.project,
+        query: primaryQuery,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        top_k: this.broadTopK,
+        include_pending: true,
+        profile: "balanced"
+      })),
+      taskFrameQuery ? this.runBranch("context_task_frame_broad", () => this.args.adapter.query({
+        project: scope.project,
+        query: taskFrameQuery,
+        top_k: this.broadTopK,
+        include_memories: false,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        max_tokens: this.maxTokens,
+        compress: true,
+        compression_strategy: "adaptive"
+      })) : Promise.resolve({ name: "context_task_frame_broad", status: "skipped", durationMs: 0 }),
+      taskFrameQuery ? this.runBranch("memory_task_frame_broad", () => this.args.adapter.searchMemories({
+        project: scope.project,
+        query: taskFrameQuery,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        top_k: this.broadTopK,
+        include_pending: true,
+        profile: "balanced"
+      })) : Promise.resolve({ name: "memory_task_frame_broad", status: "skipped", durationMs: 0 })
+    ]) : [
+      { name: "context_primary_broad", status: "skipped", durationMs: 0 },
+      { name: "memory_primary_broad", status: "skipped", durationMs: 0 },
+      { name: "context_task_frame_broad", status: "skipped", durationMs: 0 },
+      { name: "memory_task_frame_broad", status: "skipped", durationMs: 0 }
+    ];
+    const broadCollected = collectFromBranches(broadBranches, "broad");
+    totalOkCount += broadCollected.okCount;
+    if (fallbackUsed) {
+      this.fallbackTriggers += 1;
+      this.broadScopedTurns += 1;
+      allCollected = [...allCollected, ...broadCollected.collected];
+    }
+    const ranked = this.rerank(allCollected, focusedScope);
+    dedupedCount += ranked.dedupedCount;
+    const floored = this.applyRelevanceFloor(ranked.items);
+    droppedBelowFloor += floored.dropped;
+    this.floorDroppedCount += droppedBelowFloor;
+    this.droppedCount += droppedBelowFloor;
+    const finalItems = floored.items.slice(0, this.broadTopK);
+    this.injectedItemCount += finalItems.length;
+    this.totalTurns += 1;
+    const executedBranches = [...focusedBranches, ...broadBranches].filter((branch) => branch.status !== "skipped");
+    for (const branch of [...focusedBranches, ...broadBranches]) {
+      branchStatus[branch.name] = branch.status;
+    }
+    const prepared = {
+      scope,
+      retrieval: {
+        primaryQuery,
+        taskFrameQuery,
+        warnings,
+        degraded: totalOkCount < executedBranches.length,
+        degradedReason: totalOkCount === 0 ? "all_retrieval_failed" : warnings.length > 0 ? "partial_retrieval_failed" : void 0,
+        durationMs: Date.now() - startedAt,
+        targetBudgetMs: this.targetRetrievalMs,
+        hardTimeoutMs: this.hardRetrievalTimeoutMs,
+        branchStatus,
+        focusedScopeApplied,
+        focusedSourceIds: focusedScope.sourceIds,
+        focusedFileHints: focusedScope.fileHints.map((value) => pathBase(value)),
+        clientScoped: Boolean(focusedScope.clientName),
+        fallbackUsed,
+        droppedBelowFloor,
+        dedupedCount
+      },
+      context: this.buildContext(finalItems),
+      items: finalItems
+    };
+    this.lastPreparedTurn = prepared.retrieval;
+    return prepared;
+  }
+  async recordWork(event, context = {}) {
+    const normalized = {
+      ...event,
+      salience: event.salience || defaultSalience(event.kind, event.success),
+      timestamp: event.timestamp || nowIso()
+    };
+    this.pushTouchedFiles(normalized.filePaths);
+    this.pushWorkEvent(normalized);
+    if (normalized.salience === "low") {
+      this.bufferedLowSalience = [...this.bufferedLowSalience, normalized].slice(-20);
+      return { success: true, buffered: true };
+    }
+    const { scope } = await this.resolveScope(context);
+    return this.args.adapter.addMemory({
+      project: scope.project,
+      user_id: scope.userId,
+      session_id: scope.sessionId,
+      content: `${normalized.kind}: ${normalized.summary}${normalized.details ? ` (${normalized.details})` : ""}`,
+      memory_type: toMemoryType(normalized.kind),
+      event_date: normalized.timestamp,
+      write_mode: "async",
+      metadata: {
+        runtime_auto: true,
+        client_name: this.clientName,
+        work_event_kind: normalized.kind,
+        salience: normalized.salience,
+        file_paths: normalized.filePaths || [],
+        tool_name: normalized.toolName,
+        success: normalized.success
+      }
+    });
+  }
+  async resolveLearningScope(overrides) {
+    const merged = {
+      ...this.baseContext,
+      ...overrides
+    };
+    const { scope } = await this.resolveScope(overrides);
+    return {
+      project: scope.project,
+      sessionId: merged.sessionId || scope.sessionId,
+      userId: merged.userId
+    };
+  }
+  async afterTurn(input, context = {}) {
+    this.pushTouchedFiles(input.touchedFiles);
+    if (input.auto_learn === false) {
+      return {
+        success: true,
+        sessionIngested: false,
+        memoriesCreated: 0,
+        relationsCreated: 0,
+        invalidatedCount: 0,
+        mergedCount: 0,
+        droppedCount: 0,
+        warnings: []
+      };
+    }
+    const scope = await this.resolveLearningScope(context);
+    const result = await this.args.adapter.ingestSession({
+      project: scope.project,
+      session_id: scope.sessionId,
+      user_id: scope.userId,
+      messages: [
+        { role: "user", content: input.userMessage, timestamp: nowIso() },
+        { role: "assistant", content: input.assistantMessage, timestamp: nowIso() }
+      ],
+      write_mode: "async"
+    });
+    this.mergedCount += result.memories_invalidated || 0;
+    return {
+      success: Boolean(result.success),
+      sessionIngested: true,
+      memoriesCreated: result.memories_created || 0,
+      relationsCreated: result.relations_created || 0,
+      invalidatedCount: result.memories_invalidated || 0,
+      mergedCount: result.memories_invalidated || 0,
+      droppedCount: 0,
+      warnings: result.errors || []
+    };
+  }
+  async flush(reason = "manual", context = {}) {
+    if (this.bufferedLowSalience.length > 0) {
+      const { scope } = await this.resolveScope(context);
+      const summary = summarizeLowSalience(this.bufferedLowSalience);
+      await this.args.adapter.addMemory({
+        project: scope.project,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        content: summary,
+        memory_type: "event",
+        write_mode: "async",
+        metadata: {
+          runtime_auto: true,
+          client_name: this.clientName,
+          flush_reason: reason,
+          salience: "low",
+          summarized_count: this.bufferedLowSalience.length
+        }
+      });
+      this.bufferedLowSalience = [];
+    }
+    await this.args.adapter.flushQueue();
+    return this.status();
+  }
+  status() {
+    return {
+      clientName: this.clientName,
+      scope: this.lastScope,
+      queue: this.args.adapter.queueStatus(),
+      retrieval: this.lastPreparedTurn,
+      counters: {
+        mergedCount: this.mergedCount,
+        droppedCount: this.droppedCount,
+        bufferedLowSalience: this.bufferedLowSalience.length,
+        focusedPassHits: this.focusedPassHits,
+        fallbackTriggers: this.fallbackTriggers,
+        floorDroppedCount: this.floorDroppedCount,
+        injectedItemCount: this.injectedItemCount,
+        sourceScopedTurns: this.sourceScopedTurns,
+        broadScopedTurns: this.broadScopedTurns,
+        totalTurns: this.totalTurns
+      }
+    };
+  }
+};
+
+// ../src/sdk/whisper.ts
+var PROJECT_CACHE_TTL_MS = 3e4;
+var IDENTITY_WARNINGS = /* @__PURE__ */ new Set();
+function isLikelyProjectId(projectRef) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(projectRef);
+}
+function randomRequestId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `req_${Math.random().toString(36).slice(2, 11)}`;
+}
+function parseIdentityMode(value) {
+  return value === "app-identity" ? "app-identity" : "demo-local";
+}
+function parseEnvironment(value) {
+  if (value === "staging" || value === "production") return value;
+  return "local";
+}
+function classifyRuntimeErrorCode(error) {
+  if (error.code === "MISSING_PROJECT") return "MISSING_PROJECT";
+  if (error.code === "TIMEOUT") return "TIMEOUT";
+  if (error.code === "NETWORK_ERROR") return "NETWORK_ERROR";
+  if (error.code === "VALIDATION_ERROR") return "VALIDATION_ERROR";
+  if (error.status === 401 || error.status === 403) return "INVALID_API_KEY";
+  if (error.status === 408) return "TIMEOUT";
+  if (error.status === 429) return "RATE_LIMITED";
+  if (error.status && error.status >= 500) return "TEMPORARY_UNAVAILABLE";
+  if (error.code === "PROJECT_NOT_FOUND" || error.code === "NOT_FOUND") return "PROJECT_NOT_FOUND";
+  return "REQUEST_FAILED";
+}
+function detectSourceType(url) {
+  const ghMatch = url.match(/github\.com\/([^/?#]+)\/([^/?#]+)/);
+  if (ghMatch) {
+    const [, owner, repo] = ghMatch;
+    return { type: "github", owner, repo: repo.replace(/\.git$/, "") };
+  }
+  if (/youtube\.com|youtu\.be|loom\.com/.test(url)) return { type: "video" };
+  if (/\.pdf(\?|$)/.test(url)) return { type: "pdf" };
+  return { type: "web" };
+}
+var WhisperClient = class _WhisperClient {
+  constructor(config) {
+    this.config = config;
+    const env = typeof process !== "undefined" ? process.env : {};
+    this.identityMode = parseIdentityMode(config.identityMode || env.WHISPER_IDENTITY_MODE);
+    this.environment = parseEnvironment(config.environment || env.WHISPER_ENV || (env.NODE_ENV === "production" ? "production" : "local"));
+    this.strictIdentityMode = config.strictIdentityMode ?? env.WHISPER_DEMO_LOCAL_STRICT === "true";
+    this.getIdentity = config.getIdentity;
+    this.enforceIdentityModeGuardrail();
+    this.diagnosticsStore = new DiagnosticsStore(config.telemetry?.maxEntries || 1e3);
+    this.runtimeClient = new RuntimeClient(
+      {
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+        compatMode: config.compatMode || "fallback",
+        timeouts: config.timeouts,
+        retryPolicy: config.retryPolicy,
+        fetchImpl: config.fetch
+      },
+      this.diagnosticsStore
+    );
+    this.searchCache = new SearchResponseCache(
+      config.cache?.ttlMs ?? 7e3,
+      config.cache?.capacity ?? 500
+    );
+    const queueStore = this.createQueueStore(config);
+    this.writeQueue = new WriteQueue({
+      store: queueStore,
+      maxBatchSize: config.queue?.maxBatchSize ?? 50,
+      flushIntervalMs: config.queue?.flushIntervalMs ?? 100,
+      maxAttempts: config.queue?.maxAttempts ?? 2,
+      flushHandler: async (items) => {
+        if (items.length === 0) return;
+        const project = items[0].project;
+        const memories = items.map((item) => ({
+          ...item.payload,
+          user_id: item.payload.user_id ?? item.userId,
+          session_id: item.payload.session_id ?? item.sessionId,
+          metadata: {
+            ...item.payload.metadata || {},
+            event_id: item.eventId,
+            queued_at: item.createdAt
+          }
+        }));
+        try {
+          await this.runtimeClient.request({
+            endpoint: "/v1/memory/bulk",
+            method: "POST",
+            operation: "bulk",
+            body: {
+              project,
+              write_mode: "async",
+              memories
+            }
+          });
+        } catch (error) {
+          if (this.runtimeClient.getCompatMode() !== "fallback" || !(error instanceof RuntimeClientError) || error.status !== 404) {
+            throw error;
+          }
+          await Promise.all(
+            memories.map(async (memory) => {
+              try {
+                await this.runtimeClient.request({
+                  endpoint: "/v1/memory",
+                  method: "POST",
+                  operation: "writeAck",
+                  body: {
+                    project,
+                    ...memory,
+                    write_mode: "sync"
+                  }
+                });
+              } catch (fallbackError) {
+                if (this.runtimeClient.getCompatMode() !== "fallback" || !(fallbackError instanceof RuntimeClientError) || fallbackError.status !== 404) {
+                  throw fallbackError;
+                }
+                await this.runtimeClient.request({
+                  endpoint: "/v1/memories",
+                  method: "POST",
+                  operation: "writeAck",
+                  body: {
+                    project,
+                    ...memory,
+                    memory_type: memory.memory_type === "event" ? "episodic" : memory.memory_type
+                  }
+                });
+              }
+            })
+          );
+        }
+      }
+    });
+    if (config.queue?.enabled !== false) {
+      void this.writeQueue.start();
+    }
+    this.memoryModule = new MemoryModule(
+      this.runtimeClient,
+      this.searchCache,
+      this.writeQueue,
+      {
+        defaultProject: config.project,
+        cacheEnabled: config.cache?.enabled !== false,
+        queueEnabled: config.queue?.enabled !== false
+      }
+    );
+    this.sessionModule = new SessionModule(this.memoryModule, config.project);
+    this.profileModule = new ProfileModule(this.memoryModule);
+    this.analyticsModule = new AnalyticsModule(this.diagnosticsStore, this.writeQueue);
+    this.diagnostics = {
+      getLast: (limit) => this.diagnosticsStore.getLast(limit),
+      subscribe: (fn) => this.diagnosticsStore.subscribe(fn),
+      snapshot: () => this.diagnosticsStore.snapshot()
+    };
+    this.queue = {
+      flush: () => this.writeQueue.flush(),
+      status: () => this.writeQueue.status()
+    };
+    this.memory = {
+      add: (params) => this.runOrThrow(async () => this.memoryModule.add(await this.withIdentity(params))),
+      addBulk: (params) => this.runOrThrow(async () => this.memoryModule.addBulk({
+        ...params,
+        memories: await Promise.all(params.memories.map((memory) => this.withIdentity(memory)))
+      })),
+      search: (params) => this.runOrThrow(async () => this.memoryModule.search(await this.withIdentity(params))),
+      get: (memoryId) => this.runOrThrow(async () => this.memoryModule.get(memoryId)),
+      getUserProfile: (params) => this.runOrThrow(async () => this.profileModule.getUserProfile(await this.withIdentity(params, true))),
+      getSessionMemories: (params) => this.runOrThrow(async () => this.profileModule.getSessionMemories(await this.withIdentity(params))),
+      update: (memoryId, params) => this.runOrThrow(async () => this.memoryModule.update(memoryId, params)),
+      delete: (memoryId) => this.runOrThrow(async () => this.memoryModule.delete(memoryId)),
+      flag: (params) => this.runOrThrow(async () => this.memoryModule.flag(params))
+    };
+    this.session = {
+      start: (params) => this.runOrThrow(async () => this.sessionModule.start(await this.withSessionIdentity(params))),
+      event: (params) => this.runOrThrow(async () => this.sessionModule.event(params)),
+      suspend: (params) => this.runOrThrow(async () => this.sessionModule.suspend(params)),
+      resume: (params) => this.runOrThrow(async () => this.sessionModule.resume(params)),
+      end: (params) => this.runOrThrow(async () => this.sessionModule.end(params))
+    };
+    this.profile = {
+      getUserProfile: (params) => this.runOrThrow(async () => this.profileModule.getUserProfile(await this.withIdentity(params, true))),
+      getSessionMemories: (params) => this.runOrThrow(async () => this.profileModule.getSessionMemories(await this.withIdentity(params)))
+    };
+    this.analytics = {
+      diagnosticsSnapshot: () => this.analyticsModule.diagnosticsSnapshot(),
+      queueStatus: () => this.analyticsModule.queueStatus()
+    };
+  }
+  diagnostics;
+  queue;
+  memory;
+  session;
+  profile;
+  analytics;
+  runtimeClient;
+  diagnosticsStore;
+  searchCache;
+  writeQueue;
+  memoryModule;
+  sessionModule;
+  profileModule;
+  analyticsModule;
+  projectRefToId = /* @__PURE__ */ new Map();
+  identityMode;
+  environment;
+  strictIdentityMode;
+  getIdentity;
+  projectCache = [];
+  projectCacheExpiresAt = 0;
+  enforceIdentityModeGuardrail(requestId = randomRequestId()) {
+    if (this.identityMode !== "demo-local") return;
+    if (this.environment === "local") return;
+    const message = "[Whisper SDK] WHISPER_IDENTITY_MODE=demo-local is intended only for local development. Switch to app-identity and provide getIdentity() or per-call user_id/session_id.";
+    if (this.strictIdentityMode || this.environment === "production") {
+      throw new WhisperError({
+        code: "MISCONFIGURED_IDENTITY_MODE",
+        message,
+        retryable: false,
+        hint: "Set identityMode: 'app-identity' and provide a getIdentity() function that returns { userId, sessionId? }. To override for testing, set environment: 'local' explicitly."
+      });
+    }
+    const warningKey = `${this.environment}:${this.identityMode}`;
+    if (!IDENTITY_WARNINGS.has(warningKey)) {
+      IDENTITY_WARNINGS.add(warningKey);
+      if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn(`${message} requestId=${requestId}`);
+      }
+    }
+  }
+  toWhisperError(error, hint) {
+    if (error instanceof WhisperError) return error;
+    if (error instanceof RuntimeClientError) {
+      return new WhisperError({
+        code: classifyRuntimeErrorCode(error),
+        message: error.message,
+        status: error.status,
+        retryable: error.retryable,
+        hint: error.hint || hint,
+        requestId: error.requestId || error.traceId,
+        details: error.details,
+        cause: error
+      });
+    }
+    if (error instanceof Error) {
+      return new WhisperError({
+        code: "REQUEST_FAILED",
+        message: error.message,
+        retryable: false,
+        hint,
+        cause: error
+      });
+    }
+    return new WhisperError({
+      code: "REQUEST_FAILED",
+      message: "Unknown SDK error",
+      retryable: false,
+      hint,
+      details: error
+    });
+  }
+  async runOrThrow(work, hint) {
+    try {
+      return await work();
+    } catch (error) {
+      throw this.toWhisperError(error, hint);
+    }
+  }
+  async resolveIdentityOverride() {
+    if (!this.getIdentity) return null;
+    const resolved = await this.getIdentity();
+    const userId = String(resolved?.userId || "").trim();
+    const sessionId = resolved?.sessionId ? String(resolved.sessionId).trim() : void 0;
+    if (!userId) {
+      throw new WhisperError({
+        code: "AUTH_IDENTITY_INVALID",
+        message: "getIdentity() returned an invalid identity payload.",
+        retryable: false,
+        hint: "Return { userId, sessionId? } from getIdentity()."
+      });
+    }
+    return {
+      userId,
+      sessionId: sessionId || void 0
+    };
+  }
+  async withIdentity(params, requireUser = false) {
+    const currentUser = params.user_id ? String(params.user_id).trim() : "";
+    const currentSession = params.session_id ? String(params.session_id).trim() : "";
+    if (currentUser) {
+      return {
+        ...params,
+        user_id: currentUser,
+        session_id: currentSession || params.session_id
+      };
+    }
+    const resolved = await this.resolveIdentityOverride();
+    if (resolved) {
+      return {
+        ...params,
+        user_id: resolved.userId,
+        session_id: currentSession || resolved.sessionId
+      };
+    }
+    if (requireUser || this.identityMode === "app-identity") {
+      throw new WhisperError({
+        code: "AUTH_IDENTITY_REQUIRED",
+        message: "A user identity is required in app-identity mode.",
+        retryable: false,
+        hint: "Provide user_id/session_id per call or configure getIdentity() in WhisperClient."
+      });
+    }
+    return params;
+  }
+  async withSessionIdentity(params) {
+    const userId = params.userId ? String(params.userId).trim() : "";
+    const sessionId = params.sessionId ? String(params.sessionId).trim() : "";
+    if (userId) {
+      return {
+        ...params,
+        userId,
+        sessionId: sessionId || params.sessionId
+      };
+    }
+    const resolved = await this.resolveIdentityOverride();
+    if (resolved?.userId) {
+      return {
+        ...params,
+        userId: resolved.userId,
+        sessionId: sessionId || resolved.sessionId
+      };
+    }
+    throw new WhisperError({
+      code: "AUTH_IDENTITY_REQUIRED",
+      message: "Session operations require a user identity.",
+      retryable: false,
+      hint: "Pass userId explicitly or configure getIdentity() in WhisperClient."
+    });
+  }
+  static fromEnv(overrides = {}) {
+    const env = typeof process !== "undefined" ? process.env : {};
+    const apiKey = overrides.apiKey || env.WHISPER_API_KEY || env.USEWHISPER_API_KEY || env.API_KEY;
+    if (!apiKey) {
+      throw new WhisperError({
+        code: "INVALID_API_KEY",
+        message: "Missing API key. Set WHISPER_API_KEY / USEWHISPER_API_KEY / API_KEY.",
+        retryable: false
+      });
+    }
+    return new _WhisperClient({
+      apiKey,
+      baseUrl: overrides.baseUrl || env.WHISPER_BASE_URL || env.API_BASE_URL || "https://context.usewhisper.dev",
+      project: overrides.project || env.WHISPER_PROJECT || env.PROJECT,
+      identityMode: overrides.identityMode || parseIdentityMode(env.WHISPER_IDENTITY_MODE),
+      environment: overrides.environment || parseEnvironment(env.WHISPER_ENV || (env.NODE_ENV === "production" ? "production" : "local")),
+      strictIdentityMode: overrides.strictIdentityMode ?? env.WHISPER_DEMO_LOCAL_STRICT === "true",
+      ...overrides
+    });
+  }
+  createQueueStore(config) {
+    const persistence = config.queue?.persistence || this.defaultQueuePersistence();
+    if (persistence === "storage") {
+      return createStorageQueueStore();
+    }
+    if (persistence === "file") {
+      const filePath = config.queue?.filePath || this.defaultQueueFilePath();
+      if (filePath) {
+        return createFileQueueStore(filePath);
+      }
+    }
+    return new InMemoryQueueStore();
+  }
+  defaultQueuePersistence() {
+    const maybeWindow = globalThis.window;
+    if (maybeWindow && typeof maybeWindow === "object") {
+      const maybeStorage = globalThis.localStorage;
+      return maybeStorage && typeof maybeStorage === "object" ? "storage" : "memory";
+    }
+    return "file";
+  }
+  defaultQueueFilePath() {
+    if (typeof process === "undefined") return void 0;
+    const path = process.env.WHISPER_QUEUE_FILE_PATH;
+    if (path) return path;
+    const home = process.env.USERPROFILE || process.env.HOME;
+    if (!home) return void 0;
+    const normalizedHome = home.replace(/[\\\/]+$/, "");
+    return `${normalizedHome}/.whisper/sdk/queue.json`;
+  }
+  getRequiredProject(project) {
+    const resolved = project || this.config.project;
+    if (!resolved) {
+      throw new WhisperError({
+        code: "MISSING_PROJECT",
+        message: "Project is required",
+        retryable: false,
+        hint: "Pass project in the call or configure a default project in WhisperClient."
+      });
+    }
+    return resolved;
+  }
+  async refreshProjectCache(force = false) {
+    if (!force && Date.now() < this.projectCacheExpiresAt && this.projectCache.length > 0) {
+      return this.projectCache;
+    }
+    const response = await this.runtimeClient.request({
+      endpoint: "/v1/projects",
+      method: "GET",
+      operation: "get",
+      idempotent: true
+    });
+    this.projectRefToId.clear();
+    this.projectCache = response.data?.projects || [];
+    for (const project of this.projectCache) {
+      this.projectRefToId.set(project.id, project.id);
+      this.projectRefToId.set(project.slug, project.id);
+      this.projectRefToId.set(project.name, project.id);
+    }
+    this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
+    return this.projectCache;
+  }
+  async fetchResolvedProject(projectRef) {
+    try {
+      const response = await this.runtimeClient.request({
+        endpoint: `/v1/projects/resolve?project=${encodeURIComponent(projectRef)}`,
+        method: "GET",
+        operation: "get",
+        idempotent: true
+      });
+      return response.data?.resolved || null;
+    } catch (error) {
+      if (error instanceof RuntimeClientError && error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async resolveProject(projectRef) {
+    return this.runOrThrow(async () => {
+      const resolvedRef = this.getRequiredProject(projectRef);
+      const cachedProjects = await this.refreshProjectCache(false);
+      const cachedProject = cachedProjects.find(
+        (project) => project.id === resolvedRef || project.slug === resolvedRef || project.name === resolvedRef
+      );
+      if (cachedProject) {
+        return cachedProject;
+      }
+      const resolvedProject = await this.fetchResolvedProject(resolvedRef);
+      if (resolvedProject) {
+        this.projectRefToId.set(resolvedProject.id, resolvedProject.id);
+        this.projectRefToId.set(resolvedProject.slug, resolvedProject.id);
+        this.projectRefToId.set(resolvedProject.name, resolvedProject.id);
+        this.projectCache = [
+          ...this.projectCache.filter((project) => project.id !== resolvedProject.id),
+          resolvedProject
+        ];
+        this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
+        return resolvedProject;
+      }
+      if (isLikelyProjectId(resolvedRef)) {
+        return {
+          id: resolvedRef,
+          orgId: "",
+          name: resolvedRef,
+          slug: resolvedRef,
+          createdAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+          updatedAt: (/* @__PURE__ */ new Date(0)).toISOString()
+        };
+      }
+      throw new WhisperError({
+        code: "PROJECT_NOT_FOUND",
+        message: `Project '${resolvedRef}' not found`,
+        retryable: false
+      });
+    });
+  }
+  async preflight(options) {
+    const requestId = randomRequestId();
+    const checks = [];
+    try {
+      this.enforceIdentityModeGuardrail(requestId);
+    } catch (error) {
+      throw this.toWhisperError(error, "Update identity mode before running preflight.");
+    }
+    const apiKeyOk = typeof this.config.apiKey === "string" && this.config.apiKey.trim().length > 0;
+    checks.push({
+      check: "api_key",
+      ok: apiKeyOk,
+      message: apiKeyOk ? "API key is configured." : "Missing API key.",
+      hint: apiKeyOk ? void 0 : "Set WHISPER_API_KEY or pass apiKey to WhisperClient."
+    });
+    try {
+      await this.runtimeClient.request({
+        endpoint: "/v1/projects",
+        method: "GET",
+        operation: "get",
+        idempotent: true,
+        traceId: requestId
+      });
+      checks.push({
+        check: "api_connectivity",
+        ok: true,
+        message: "Connected to Whisper API."
+      });
+    } catch (error) {
+      const mapped = this.toWhisperError(error, "Confirm WHISPER_BASE_URL and API key permissions.");
+      checks.push({
+        check: "api_connectivity",
+        ok: false,
+        message: mapped.message,
+        hint: mapped.hint
+      });
+    }
+    const projectRef = options?.project || this.config.project;
+    if (projectRef) {
+      try {
+        await this.resolveProject(projectRef);
+        checks.push({
+          check: "project_access",
+          ok: true,
+          message: `Project '${projectRef}' is reachable.`
+        });
+      } catch (error) {
+        const mapped = this.toWhisperError(error, "Create or grant access to the configured project.");
+        checks.push({
+          check: "project_access",
+          ok: false,
+          message: mapped.message,
+          hint: mapped.hint
+        });
+      }
+    } else {
+      checks.push({
+        check: "project_access",
+        ok: true,
+        message: "No default project configured (project will be required per call)."
+      });
+    }
+    if (options?.requireIdentity || this.identityMode === "app-identity") {
+      try {
+        const identity = await this.resolveIdentityOverride();
+        const ok = Boolean(identity?.userId);
+        checks.push({
+          check: "identity_resolution",
+          ok,
+          message: ok ? "Identity resolver is configured." : "Identity resolver is missing.",
+          hint: ok ? void 0 : "Provide getIdentity() or pass user_id/session_id per call."
+        });
+      } catch (error) {
+        const mapped = this.toWhisperError(error, "Fix identity resolver output before production usage.");
+        checks.push({
+          check: "identity_resolution",
+          ok: false,
+          message: mapped.message,
+          hint: mapped.hint
+        });
+      }
+    }
+    return {
+      ok: checks.every((check) => check.ok),
+      checks,
+      requestId,
+      identityMode: this.identityMode,
+      environment: this.environment
+    };
+  }
+  async query(params) {
+    return this.runOrThrow(async () => {
+      const { q, userId, ...rest } = params;
+      const normalized = {
+        ...rest,
+        query: rest.query ?? q ?? "",
+        user_id: rest.user_id ?? userId,
+        include_memories: rest.include_memories ?? true
+      };
+      const identityParams = await this.withIdentity(normalized);
+      const project = (await this.resolveProject(identityParams.project)).id;
+      const response = await this.runtimeClient.request({
+        endpoint: "/v1/context/query",
+        method: "POST",
+        operation: "search",
+        body: {
+          ...identityParams,
+          project
+        },
+        idempotent: true
+      });
+      return response.data;
+    });
+  }
+  async remember(params) {
+    if (!params.userId && !this.getIdentity) {
+      throw new WhisperError({
+        code: "AUTH_IDENTITY_REQUIRED",
+        message: "remember() requires userId or a getIdentity() resolver on the client.",
+        retryable: false,
+        hint: "Pass userId in the call or configure getIdentity() in WhisperClient."
+      });
+    }
+    const sessionId = params.sessionId ?? (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `session_${Math.random().toString(36).slice(2, 11)}`);
+    return this.learn({
+      mode: "conversation",
+      project: params.project,
+      user_id: params.userId,
+      session_id: sessionId,
+      messages: params.messages
+    });
+  }
+  async ingest(params) {
+    const detected = detectSourceType(params.url);
+    return this.learn({
+      mode: "source",
+      project: params.project,
+      type: detected.type,
+      url: params.url,
+      name: params.name,
+      token: params.token,
+      ...detected.owner ? { owner: detected.owner } : {},
+      ...detected.repo ? { repo: detected.repo } : {}
+    });
+  }
+  async userProfile(userId) {
+    return this.memory.getUserProfile({ user_id: userId });
+  }
+  async ingestSession(params) {
+    return this.runOrThrow(async () => {
+      const identityParams = await this.withIdentity(params);
+      const project = (await this.resolveProject(identityParams.project)).id;
+      const response = await this.runtimeClient.request({
+        endpoint: "/v1/memory/ingest/session",
+        method: "POST",
+        operation: "session",
+        body: {
+          ...identityParams,
+          project
+        }
+      });
+      return response.data;
+    });
+  }
+  async learn(params) {
+    return this.runOrThrow(async () => {
+      const identityParams = params.mode === "conversation" ? await this.withIdentity(params) : params;
+      const project = (await this.resolveProject(identityParams.project)).id;
+      const response = await this.runtimeClient.request({
+        endpoint: "/v1/learn",
+        method: "POST",
+        operation: params.mode === "conversation" ? "session" : "bulk",
+        body: {
+          ...identityParams,
+          project
+        }
+      });
+      return response.data;
+    });
+  }
+  createAgentRuntime(options = {}) {
+    const baseContext = {
+      workspacePath: options.workspacePath,
+      project: options.project || this.config.project,
+      userId: options.userId,
+      sessionId: options.sessionId,
+      traceId: options.traceId,
+      clientName: options.clientName
+    };
+    return new WhisperAgentRuntime({
+      baseContext,
+      options,
+      adapter: {
+        resolveProject: (project) => this.resolveProject(project),
+        query: (params) => this.query(params),
+        ingestSession: (params) => this.ingestSession(params),
+        getSessionMemories: (params) => this.memory.getSessionMemories(params),
+        getUserProfile: (params) => this.memory.getUserProfile(params),
+        searchMemories: (params) => this.memory.search(params),
+        addMemory: (params) => this.memory.add(params),
+        queueStatus: () => this.queue.status(),
+        flushQueue: () => this.queue.flush()
+      }
+    });
+  }
+  withRunContext(context) {
+    const base = this;
+    return {
+      memory: {
+        add: (params) => base.memory.add({
+          ...params,
+          project: params.project || context.project || base.config.project,
+          user_id: params.user_id || context.userId,
+          session_id: params.session_id || context.sessionId
+        }),
+        search: (params) => base.memory.search({
+          ...params,
+          project: params.project || context.project || base.config.project,
+          user_id: params.user_id || context.userId,
+          session_id: params.session_id || context.sessionId
+        })
+      },
+      session: {
+        event: (params) => base.session.event({
+          ...params,
+          sessionId: params.sessionId || context.sessionId || ""
+        })
+      },
+      learn: (params) => base.learn({
+        ...params,
+        project: params.project || context.project || base.config.project,
+        ...params.mode === "conversation" ? {
+          user_id: params.user_id ?? context.userId,
+          session_id: params.session_id || context.sessionId || ""
+        } : {}
+      }),
+      queue: base.queue,
+      diagnostics: base.diagnostics
+    };
+  }
+  async deleteSource(sourceId) {
+    return this.runOrThrow(async () => {
+      const response = await this.runtimeClient.request({
+        endpoint: `/v1/sources/${sourceId}`,
+        method: "DELETE",
+        operation: "writeAck"
+      });
+      return response.data;
+    });
+  }
+  async extractMemories(params) {
+    return this.runOrThrow(async () => {
+      const project = (await this.resolveProject(params.project)).id;
+      const response = await this.runtimeClient.request({
+        endpoint: "/v1/memory/extract",
+        method: "POST",
+        operation: "writeAck",
+        body: { project, message: params.message }
+      });
+      return response.data;
+    });
+  }
+  async shutdown() {
+    await this.writeQueue.stop();
+  }
+};
+
+// ../src/sdk/router/memory-router.ts
+function randomRequestId2() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `req_${Math.random().toString(36).slice(2, 11)}`;
+}
+function normalizeProviderUrl(baseUrl, routePath) {
+  const trimmedBase = baseUrl.replace(/\/+$/, "");
+  const normalizedPath = routePath.startsWith("/") ? routePath : `/${routePath}`;
+  return `${trimmedBase}${normalizedPath}`;
+}
+function trimText(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function extractUserPrompt(messages) {
+  if (!Array.isArray(messages)) return "";
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const item = messages[i];
+    if (!item || typeof item !== "object") continue;
+    if (trimText(item.role).toLowerCase() !== "user") continue;
+    const content = item.content;
+    if (typeof content === "string" && content.trim()) return content.trim();
+    if (Array.isArray(content)) {
+      const text = content.map((part) => {
+        if (typeof part === "string") return part;
+        if (!part || typeof part !== "object") return "";
+        const record = part;
+        if (trimText(record.type).toLowerCase() !== "text") return "";
+        return trimText(record.text);
+      }).filter((part) => part.length > 0).join("\n");
+      if (text) return text;
+    }
+  }
+  return "";
+}
+function buildClient(config) {
+  if (config.client) return config.client;
+  const env = typeof process !== "undefined" ? process.env : {};
+  const apiKey = config.apiKey || env.WHISPER_API_KEY || env.USEWHISPER_API_KEY || env.API_KEY;
+  if (!apiKey) {
+    throw new WhisperError({
+      code: "INVALID_API_KEY",
+      message: "Missing API key. Pass apiKey to createMemoryRouter(...) or set WHISPER_API_KEY.",
+      retryable: false
+    });
+  }
+  return new WhisperClient({
+    apiKey,
+    baseUrl: config.baseUrl,
+    project: config.project,
+    identityMode: config.identityMode,
+    getIdentity: config.getIdentity,
+    environment: config.environment,
+    strictIdentityMode: config.strictIdentityMode,
+    compatMode: config.compatMode,
+    fetch: config.fetch,
+    timeouts: config.timeouts,
+    retryPolicy: config.retryPolicy,
+    cache: config.cache,
+    queue: config.queue,
+    telemetry: config.telemetry
+  });
+}
+function ensureBetaEnabled(_explicitBeta) {
+}
+var WhisperMemoryRouter = class {
+  config;
+  providerUrl;
+  fetchImpl;
+  client = null;
+  lastTrace = null;
+  constructor(config) {
+    ensureBetaEnabled(config.beta);
+    this.config = config;
+    this.providerUrl = normalizeProviderUrl(
+      config.providerBaseUrl,
+      config.routePath || "/v1/chat/completions"
+    );
+    this.fetchImpl = config.fetch || fetch;
+  }
+  getClient() {
+    if (!this.client) this.client = buildClient(this.config);
+    return this.client;
+  }
+  getLastTrace() {
+    return this.lastTrace ? { ...this.lastTrace } : null;
+  }
+  async chatCompletions(payload) {
+    const requestId = randomRequestId2();
+    const messages = Array.isArray(payload.messages) ? payload.messages : [];
+    const prompt = extractUserPrompt(messages);
+    const contextPrefix = this.config.contextPrefix || "Relevant memory context:";
+    let usedMemory = false;
+    let fallbackReason = "none";
+    let contextText = "";
+    if (!prompt) {
+      fallbackReason = "no_user_prompt";
+    } else {
+      try {
+        const queryResult = await this.getClient().query({
+          query: prompt,
+          project: this.config.project,
+          user_id: trimText(payload.user) || void 0
+        });
+        if (queryResult.context && queryResult.context.trim()) {
+          contextText = queryResult.context.trim();
+          usedMemory = true;
+        }
+      } catch (error) {
+        if (this.config.bestEffort === false) {
+          throw error;
+        }
+        fallbackReason = "memory_query_failed";
+      }
+    }
+    const providerPayload = {
+      ...payload,
+      messages: usedMemory ? [
+        {
+          role: "system",
+          content: `${contextPrefix}
+${contextText}`
+        },
+        ...messages
+      ] : messages
+    };
+    const env = typeof process !== "undefined" ? process.env : {};
+    const providerApiKey = this.config.providerApiKey || env.MEMORY_ROUTER_PROVIDER_API_KEY || "";
+    const headers = {
+      "content-type": "application/json",
+      "x-whisper-memory-router": "beta",
+      "x-whisper-request-id": requestId,
+      ...this.config.providerHeaders || {}
+    };
+    if (providerApiKey) {
+      headers.Authorization = providerApiKey.startsWith("Bearer ") ? providerApiKey : `Bearer ${providerApiKey}`;
+    }
+    const response = await this.fetchImpl(this.providerUrl, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(providerPayload)
+    });
+    const parsed = await response.json().catch(async () => await response.text().catch(() => null));
+    const trace = {
+      providerUrl: this.providerUrl,
+      requestId,
+      usedMemory,
+      fallbackReason,
+      providerStatus: response.status,
+      model: trimText(payload.model) || void 0
+    };
+    this.lastTrace = trace;
+    if (this.config.logger) this.config.logger(trace);
+    if (!response.ok) {
+      throw new WhisperError({
+        code: response.status >= 500 ? "TEMPORARY_UNAVAILABLE" : "REQUEST_FAILED",
+        status: response.status,
+        message: typeof parsed === "object" && parsed && "error" in parsed ? String(parsed.error?.message || "Provider request failed") : "Provider request failed",
+        retryable: response.status >= 500 || response.status === 429,
+        requestId,
+        details: {
+          providerUrl: this.providerUrl,
+          body: parsed,
+          trace
+        }
+      });
+    }
+    return {
+      status: response.status,
+      data: parsed,
+      trace
+    };
+  }
+};
+function createMemoryRouter(config) {
+  return new WhisperMemoryRouter(config);
+}
+export {
+  WhisperMemoryRouter,
+  createMemoryRouter
+};