wontopos 2.2.25 → 2.2.27

package/README.md

@@ -52,7 +52,13 @@ registration and never counts against it.
 ## Recall caching
 
 Opt in per search and repeated or extended queries reuse the previous result
-at 10% of the normal rate (Tablet and Scroll models):
+at 10% of the normal rate (Tablet and Scroll models).
+
+It is not free to turn on: the FIRST call writes the cache and bills the query
+tokens at 2x for a `5m` TTL, 3x for `1h`. Only hits inside the TTL bill at 0.1x.
+So it pays for a query you repeat or extend, and costs more for one you issue
+once — do not switch it on globally. Any write to the store invalidates its cache
+at once, so a hit can never predate a new memory.
 
 ```ts
 const hits = await mem.search("...the conversation so far...", "alice", 10,
@@ -74,6 +80,27 @@ Built in, no configuration needed:
   meaning "delete everything"; wiping a store is only ever the explicit
   `deleteAll(userId)` / `deleteStore(userId)`.
 
+### Behind a corporate proxy
+
+Node's global `fetch` (undici) ignores `HTTP_PROXY` / `HTTPS_PROXY`, so behind an
+egress proxy this SDK could not connect at all — while the Python and Rust SDKs went
+through, because `requests` and `reqwest` both read those variables. Pass a
+proxy-aware `fetch` and the three behave the same:
+
+```ts
+import { ProxyAgent } from "undici";
+
+const agent = new ProxyAgent(process.env.HTTPS_PROXY!);
+const mem = new Client({
+  apiKey: process.env.WONTOPOS_API_KEY!,
+  fetch: (url, init) => fetch(url, { ...init, dispatcher: agent } as any),
+});
+```
+
+The same option is how you add instrumentation or drive the client without a
+network in tests. It replaces the transport, not the client's rules — retries,
+timeouts, redirect refusal and the response cap all still apply.
+
 ## Security
 
 Built in, none of it configurable off:

package/dist/wontopos.d.ts

@@ -286,7 +286,9 @@ export interface SearchFilters {
 export declare function _resetFilterWarnings(): void;
 /** Known `search` options; extra fields pass through to the API untouched. */
 export interface SearchOptions {
-    /** Recall caching: repeated/extended queries within the TTL bill at 0.1×. */
+    /** Recall caching. A hit inside the TTL bills at 0.1× — but the FIRST call
+     *  writes the cache and bills the query tokens at 2× (`5m`) or 3× (`1h`), so
+     *  this only pays for a query you repeat or extend. Do not enable it globally. */
     cache_control?: {
         ttl: "5m" | "1h";
     };
@@ -336,6 +338,26 @@ export interface ClientOptions {
      *  key on an options object is not an error in TS at runtime). Both names work;
      *  `maxRetries` wins if somehow both are given. */
     retries?: number;
+    /** The `fetch` used for every request (default: the global `fetch`).
+     *
+     *  This is the seam for anything the runtime cannot express through options.
+     *  The one that matters in practice is a corporate egress proxy: Node's global
+     *  fetch (undici) IGNORES `HTTP_PROXY` / `HTTPS_PROXY`, so behind such a proxy
+     *  this SDK could not connect at all — while the Python and Rust SDKs went
+     *  through, because `requests` and `reqwest` both read those variables. Pass a
+     *  proxy-aware fetch and the three behave the same again:
+     *
+     *      import { ProxyAgent } from "undici";
+     *      const agent = new ProxyAgent(process.env.HTTPS_PROXY!);
+     *      const mem = new Client({
+     *        apiKey,
+     *        fetch: (url, init) => fetch(url, { ...init, dispatcher: agent } as any),
+     *      });
+     *
+     *  It is also how you add instrumentation or drive the client in a test without
+     *  a network. Retries, timeouts, redirect refusal and the size cap all still
+     *  apply — this replaces the transport, not the client's rules. */
+    fetch?: typeof fetch;
 }
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export declare class Client {
@@ -345,6 +367,9 @@ export declare class Client {
     private readonly apiKey;
     private readonly model;
     private readonly maxRetries;
+    /** Transport. Held as a field (not read off `globalThis` per call) so a caller
+     * who passes one gets it for every request, including from cloned clients. */
+    private readonly fetchImpl;
     /** The store every call uses unless one passes `userId`. */
     private readonly defaultUser;
     private _rateLimit;
@@ -393,7 +418,14 @@ export declare class Client {
     addBulk(content: string, userId?: string, category?: string, timestamp?: string, opts?: WriteOptions): Promise<StatusResult>;
     /** Supersede an old memory with new content. Payload first, userId last — same shape as add/search. */
     update(oldMemoryId: string, newContent: string, userId?: string, opts?: WriteOptions): Promise<UpdateResult>;
-    /** Semantic search over a store's memories. Returns memories, most relevant first. */
+    /** Semantic search over a store's memories. Returns memories, most relevant first.
+     *
+     *  `limit` bounds the MAIN lane, not the returned array. On a self-lane model
+     *  (Scroll 1.2+) the service answers in two disjoint lanes — the assistant's own
+     *  words come back separately — and both are returned here, so the array can hold
+     *  more than `limit`. They were retrieved and billed either way; dropping them would
+     *  only hide what you already paid for. Size a prompt window on the array you get
+     *  back, not on `limit`. `searchSelf()` hands the lanes back apart. */
     search(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<Memory[]>;
     /** Search a self-memory model (Scroll 1.2+): both lanes from ONE call. Returns
      * `{ memories, self_memories }` — `memories` is the main lane (what others said /

package/dist/wontopos.js

@@ -37,7 +37,7 @@
  * runtime's (never disabled by this SDK; Node 18+ floors TLS at 1.2). Prefer
  * `Client.fromEnv()` over keys in source code.
  */
-const VERSION = "2.2.25";
+const VERSION = "2.2.27";
 /** Runtime info helps support debug a report ("node 18 on Windows...") —
  * platform only, never anything identifying. Browsers have no `process` (and
  * silently drop the UA header anyway). */
@@ -91,6 +91,17 @@ const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9._:\-]{1,128}$/;
 function normalizeStoreId(id) {
     return id.toLowerCase().replace(/[^a-z0-9_]/g, "_");
 }
+/** Ids already warned about, so each is reported once.
+ *
+ *  Bounded on purpose. The warning fires on ids that fold, and the shape it exists
+ *  to catch is an email — which this SDK's own documented pattern ("one store per
+ *  end user") turns into one entry PER USER, held for the life of the process and
+ *  never released, even when the client is. A server passing 50,000 user ids grew
+ *  this to 50,000 entries, a leak in exactly the case being warned about. A `Set`
+ *  keeps insertion order, so the oldest entry is the one evicted; dropping the
+ *  oldest rather than refusing new ones means a collision that first shows up late
+ *  still gets its one warning. */
+const WARNED_STORE_IDS_MAX = 1024;
 const warnedStoreIds = new Set();
 function warnIfStoreIdCollapses(id) {
     if (!id || warnedStoreIds.has(id))
@@ -99,6 +110,12 @@ function warnIfStoreIdCollapses(id) {
     if (normalized === id)
         return;
     warnedStoreIds.add(id);
+    while (warnedStoreIds.size > WARNED_STORE_IDS_MAX) {
+        const oldest = warnedStoreIds.values().next().value;
+        if (oldest === undefined)
+            break;
+        warnedStoreIds.delete(oldest);
+    }
     console.warn(`wontopos: store id ${JSON.stringify(id)} is stored as ${JSON.stringify(normalized)} ` +
         `(lowercased, and anything outside [a-z0-9_] becomes "_"). Ids that differ only by case or ` +
         `punctuation share ONE store and therefore one set of memories — if these ids come from your ` +
@@ -310,6 +327,9 @@ export class Client {
     apiKey;
     model;
     maxRetries;
+    /** Transport. Held as a field (not read off `globalThis` per call) so a caller
+     * who passes one gets it for every request, including from cloned clients. */
+    fetchImpl;
     /** The store every call uses unless one passes `userId`. */
     defaultUser;
     _rateLimit = null;
@@ -344,6 +364,17 @@ export class Client {
         // "retries exhausted"; Infinity would retry forever.
         const mr = opts.maxRetries ?? opts.retries;
         this.maxRetries = typeof mr === "number" && Number.isFinite(mr) ? Math.max(0, Math.floor(mr)) : 2;
+        // Bind the global so `fetch` is not called as a method of `globalThis`, which
+        // throws "Illegal invocation" on some runtimes. A caller-supplied fetch is
+        // taken as given — it is already whatever they meant to hand us.
+        const f = opts.fetch;
+        if (f !== undefined && typeof f !== "function") {
+            throw new Error("fetch must be a function (a fetch-compatible transport)");
+        }
+        this.fetchImpl = f ?? (globalThis.fetch ? globalThis.fetch.bind(globalThis) : undefined);
+        if (typeof this.fetchImpl !== "function") {
+            throw new Error("no fetch available in this runtime — pass one as `fetch` (Node 18+ has it built in; older Node needs undici)");
+        }
         this.headers = {
             "X-API-Key": this.apiKey,
             "Content-Type": "application/json",
@@ -395,6 +426,10 @@ export class Client {
             model: this.model,
             userId: this.defaultUser,
             maxRetries: this.maxRetries,
+            // Carry the transport across clones. Without this, `withModel(...)` and
+            // friends would silently fall back to the global fetch and a proxy-bound
+            // client would stop connecting the moment it was cloned.
+            fetch: this.fetchImpl,
             ...overrides,
         });
     }
@@ -455,7 +490,14 @@ export class Client {
         return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, opts.idempotencyKey);
     }
     // ----- read -----
-    /** Semantic search over a store's memories. Returns memories, most relevant first. */
+    /** Semantic search over a store's memories. Returns memories, most relevant first.
+     *
+     *  `limit` bounds the MAIN lane, not the returned array. On a self-lane model
+     *  (Scroll 1.2+) the service answers in two disjoint lanes — the assistant's own
+     *  words come back separately — and both are returned here, so the array can hold
+     *  more than `limit`. They were retrieved and billed either way; dropping them would
+     *  only hide what you already paid for. Size a prompt window on the array you get
+     *  back, not on `limit`. `searchSelf()` hands the lanes back apart. */
     async search(query, userId, limit = 10, opts = {}) {
         // Reserved fields win over ...opts: an app that forwards untrusted input as
         // opts must not be able to override the store (user_id), query, or limit.
@@ -710,7 +752,7 @@ export class Client {
             const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
             let res;
             try {
-                res = await fetch(`${this.base}${path}`, {
+                res = await this.fetchImpl(`${this.base}${path}`, {
                     method,
                     headers: extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers,
                     body: body === undefined ? undefined : JSON.stringify(body),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.25",
+  "version": "2.2.27",
   "description": "Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.",
   "keywords": [
     "memory",