wontopos 2.2.34 → 2.2.36

package/dist/wontopos.d.ts

@@ -15,12 +15,15 @@
  * so with no `userId` anywhere the zero-setup path just works.
  *
  * The API key picks *which memory* (your account); `model` picks *which engine*
- * reads it. All models share one memory, so you can store
- * with one and recall with another. Set a default in the constructor, or override
- * a single call with `mem.withModel("tablet-1").recall(...)`.
+ * reads it. Models on the shared pool read the same memory, so you can store with
+ * one and recall with another; `listModels()` reports each model's `memory` as
+ * `"shared"` or `"isolated"`, and an isolated one starts empty. Set a default in
+ * the constructor, or override a single call with
+ * `mem.withModel("tablet-1").recall(...)`.
  *
- * Pure semantic retrieval — no keyword/BM25 matching, so it works the SAME in every
- * language. Storing and searching call no LLM; you only pay for embeddings.
+ * Recall quality does not depend on which language a memory was written in: a
+ * memory stored in one language is found by a question asked in another. Storing
+ * and searching call no LLM.
  *
  * Reliability: every call retries transient failures with exponential backoff +
  * jitter, honoring `Retry-After` — 429 always; 502/503 and connection errors only
@@ -39,6 +42,11 @@
  */
 /** Test hook — the warn-once set is process-global by design. */
 export declare function _resetStoreIdWarnings(): void;
+export declare const SEARCH_LIMIT_MIN = 5;
+export declare const SEARCH_LIMIT_MAX = 20;
+/** `recall`'s surrounding-context count. 0 to 20 inclusive; 0 attaches none. */
+export declare const CONTEXT_LIMIT_MIN = 0;
+export declare const CONTEXT_LIMIT_MAX = 20;
 /** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
 export interface RateLimit {
     limit: number | null;
@@ -104,7 +112,7 @@ export interface Memory {
      *  re-sorting by `similarity` overrides the ranking and makes results worse. Take the
      *  list in the order given. There is no `score` field. */
     similarity?: number;
-    /** Learned importance weight of the memory. */
+    /** Importance weight the service assigns to the memory. */
     importance?: number;
     /** Month bucket the memory belongs to (e.g. "2026-07"). Omitted when temporal fields are stripped. */
     time_bucket?: string;
@@ -128,11 +136,11 @@ export interface StoreResult {
     /**
      * Present when `status` is `"duplicate"`: the id of the memory this write collided with.
      *
-     * The match is by MEANING, not by exact text — a genuinely new fact that only varies a
-     * detail of one already stored ("allergic to shellfish" next to "allergic to peanuts")
-     * lands here too. So a duplicate is not always a harmless no-op: read this id, and
-     * either merge the two into one sentence or `update()` the existing memory. Without it
-     * a dropped write gave the caller nothing to act on.
+     * A genuinely new fact that only varies a detail of one already stored ("no meetings
+     * before 10am" next to "no meetings on Fridays") can land here too, so a duplicate is
+     * not always a harmless no-op: read this id, and either store one sentence that states
+     * both or `update()` the existing memory with the combined statement. Without it a
+     * dropped write gave the caller nothing to act on.
      */
     duplicate_of?: string;
     /** Present when the store was a duplicate and something (e.g. a speaker tag) was dropped. */
@@ -153,9 +161,9 @@ export interface StatusResult {
  *
  * What the service keeps is NOT your original. An image whose long edge is over
  * 1568px is downscaled to 1568 before anything else happens, and that smaller
- * picture is what gets embedded, stored, and handed back by `getImage`. Nothing in
- * the retrieval path ever looks above 1568 — the embedder and the reader both
- * shrink to it — so the extra pixels would be bytes nobody reads. This is a memory
+ * picture is what gets stored, and handed back by `getImage`. Nothing on our side
+ * ever uses more than 1568, so the extra pixels would be bytes nobody reads. This
+ * is a memory
  * service, not a photo host: the picture it holds has the resolution of a memory.
  *
  * It can also come back in a different FORMAT. Downscaling means re-encoding, and
@@ -302,14 +310,15 @@ export interface UpdateResult {
 /** `searchFull` → everything one search answered with, not just the merged memories.
  *
  *  `search` returns the memories and nothing else, which is the right answer for
- *  almost every call. Two options make it the wrong one: `max_images` asks for a lane
- *  that is delivered SEPARATELY (Tablet 2 splits photo results from text), and
- *  `verify` is reported on by `verify_used`. Merging away both means paying for a
+ *  almost every call. Two options make it the wrong one: `max_images` asks for
+ *  photos, which arrive in their own field, and `verify` is reported on by
+ *  `verify_used`. Merging away both means paying for a
  *  search you shaped and never seeing what came of it. */
 export interface SearchResult {
-    /** The main lane — what others said / general memories. */
+    /** What others said, and general memories. */
     memories: Memory[];
-    /** The assistant's own words (speaker "me"); `[]` on a model without a self lane. */
+    /** The assistant's own words (speaker "me"); `[]` on a model that does not keep
+     *  them apart. */
     self_memories: Memory[];
     /** Image memories, when `max_images` asked for any; `[]` otherwise. */
     images: Memory[];
@@ -355,7 +364,7 @@ export interface StatsResult {
     short_term_turns?: number;
     [key: string]: unknown;
 }
-/** `listMemories` → one page of a store's raw memories (original text + metadata, no vector). */
+/** `listMemories` → one page of a store's raw memories (the text you stored, and its metadata). */
 export interface MemoryPage {
     memories: Memory[];
     count: number;
@@ -363,9 +372,9 @@ export interface MemoryPage {
     next_cursor: string | null;
     [key: string]: unknown;
 }
-/** `searchSelf` result: the main lane plus the assistant's own words, split. */
+/** `searchSelf` result: general memories and the assistant's own, kept apart. */
 export interface SelfSearchResult {
-    /** Main lane — what others said / general memories. */
+    /** What others said, and general memories. */
     memories: Memory[];
     /** The assistant's own words (stored with speaker "me"); `[]` on non-self models. */
     self_memories: Memory[];
@@ -428,10 +437,11 @@ export interface SpeakersList {
     [key: string]: unknown;
 }
 /**
- * Narrow a search to part of a store — applied BEFORE ranking, so the results are
- * the best matches *within* the filter, not a filtered top-N.
+ * Narrow a search to part of a store. The filter chooses what is searched, not what
+ * is kept afterwards — so a narrow filter still returns your full `limit` when that
+ * many matches sit inside it.
  *
- * Retrieval itself stays purely semantic (no keyword matching), so these behave
+ * Retrieval behaves the same in every language, so these behave
  * identically in every language. Unlisted keys are dropped by the API rather than
  * rejected, so a typo silently widens the search — spell them exactly.
  */
@@ -465,7 +475,7 @@ export interface SearchOptions {
     /**
      * Re-ask passes, 0–3. After the first retrieval the service asks the engine again up
      * to this many times, each time telling it what was already returned so it skips
-     * those and reaches further back. Retrieval stays purely semantic — no LLM at any
+     * those and reaches further back. No LLM runs at any
      * value. Stops early when a pass finds nothing new; `verify_used` in the response
      * says how many actually ran.
      *
@@ -495,8 +505,11 @@ export interface SearchOptions {
  * `idempotencyKey` makes repeating THIS EXACT write safe: the API replays the first
  * response instead of storing again, for 10 minutes, and answers 422 if the same key
  * arrives with a different body. Use it when a retry is your own (a job that died and
- * was re-run, a queue that redelivers) — the SDK never retries writes by itself,
- * because without a key it cannot know whether the first attempt landed.
+ * was re-run, a queue that redelivers). The SDK retries a write on exactly one
+ * status: 429, which the service answers before it processes anything, so nothing
+ * was stored. It never retries a write on 502 / 503 or a dropped body, where the
+ * request may already have been stored and billed — without a key it cannot know
+ * whether that first attempt landed.
  *
  * The key must be UNIQUE PER LOGICAL WRITE — derive it from the thing being stored
  * (`` `import:${row.id}` ``), never a constant, or the second write replays the first
@@ -537,6 +550,22 @@ 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;
+    /** A total budget for one call, in ms, across every attempt.
+     *
+     *  `timeoutMs` bounds ONE attempt. At the defaults — 30s, two retries — a single
+     *  call can hold a connection for 30s + backoff + 30s + backoff + 30s, over a
+     *  minute, and a server handler awaiting it has no way to say "I only have five
+     *  seconds". This is that way. Unset means no overall budget. */
+    deadlineMs?: number;
+    /** The caller's `AbortSignal` — cancel work already in flight.
+     *
+     *  The SDK aborts on its own timeout; this is the seam for the caller's reason.
+     *  When someone closes the chat window, the recall that window asked for should
+     *  end, and the backoff sleep waiting to retry it should end too, instead of
+     *  running to completion and billing for an answer nobody will read.
+     *
+     *  Per call, clone: `mem.withSignal(ctrl.signal).recall(...)`. */
+    signal?: AbortSignal;
     /** The `fetch` used for every request (default: the global `fetch`).
      *
      *  This is the seam for anything the runtime cannot express through options.
@@ -566,6 +595,8 @@ export declare class Client {
     private readonly apiKey;
     private readonly model;
     private readonly maxRetries;
+    private readonly deadlineMs?;
+    private readonly signal?;
     /** 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;
@@ -593,6 +624,18 @@ export declare class Client {
     withModel(model: string): Client;
     /** A client bound to `userId` as its default store (everything else kept). */
     withUser(userId: string): Client;
+    /** A client bound to a caller's `AbortSignal` (everything else kept).
+     *
+     *     const ctrl = new AbortController();
+     *     req.on("close", () => ctrl.abort());
+     *     const r = await mem.withSignal(ctrl.signal).recall(q, user);
+     *
+     * Aborting ends the request in flight AND any backoff sleep waiting to retry it. */
+    withSignal(signal: AbortSignal): Client;
+    /** A client with a total budget per call, across every retry (everything else
+     * kept). `mem.withDeadline(5_000).search(q)` inside a handler that has five
+     * seconds. */
+    withDeadline(deadlineMs: number): Client;
     /** A client with a different per-request timeout in ms (everything else kept).
      * `mem.withTimeout(120_000).addBulk(bigBlob)` — this slow call only. */
     withTimeout(timeoutMs: number): Client;
@@ -610,36 +653,36 @@ export declare class Client {
     store(content: string, userId?: string, metadata?: Record<string, unknown>, opts?: WriteOptions): Promise<StoreResult>;
     /** Store a conversation turn (user + assistant). Payload first, userId last — same shape as add/search. */
     addTurn(userMsg: string, assistantMsg: string, userId?: string, opts?: WriteOptions): Promise<StatusResult>;
-    /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling.
+    /** Bulk-ingest a large blob of text in one call. For backfilling.
      *  The call most worth an `opts.idempotencyKey`: a backfill that dies halfway and is
-     *  re-run would otherwise re-chunk and re-bill the whole blob. */
+     *  re-run would otherwise re-ingest and re-bill the whole blob. */
     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.
-     *
-     *  `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 a store's memories. Returns them most relevant first.
+     *
+     *  `limit` bounds `memories`, not the returned array. On a model that keeps the
+     *  assistant's own words separate (Scroll 1.2+) those come back as well, 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 two 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 /
-     * general memories), `self_memories` is the assistant's OWN words (stored with
-     * speaker "me"), kept separate so the reader never confuses who said what. On a model
-     * without a self lane, `self_memories` is `[]`. `userId` optional (default store). */
+    /** Search a self-memory model (Scroll 1.2+): both fields from ONE call. Returns
+     * `{ memories, self_memories }` — `memories` is what others said and general
+     * memories, `self_memories` is the assistant's OWN words (stored with speaker
+     * "me"), kept apart so whoever reads them never confuses who said what. On a model
+     * that does not keep them apart, `self_memories` is `[]`. `userId` may be omitted. */
     searchSelf(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SelfSearchResult>;
     /**
-     * Search, and keep every lane the answer came in.
+     * Search, and keep every field the answer came with.
      *
      * Same request as {@link Client.search} — reach for this one when the options make
      * the merged array an incomplete answer:
      *
      *     const r = await mem.searchFull("the day we moved", "alice", 10,
      *                                    { max_images: 3, verify: 2 });
-     *     r.images.length;   // the photo lane, which `search` drops
+     *     r.images.length;   // the photos, which `search` drops
      *     r.verify_used;     // how many re-ask passes actually ran (you are billed per pass)
      *
      * Both options need Tablet 2 or newer and are refused (403) on an older engine
@@ -661,11 +704,13 @@ export declare class Client {
          * did not ask for.
          */
         limit?: number;
-        /** Chunks of surrounding context attached around the best match, 0–20. Default 10;
+        /** How much surrounding context is attached around the best match, 0–20. Default 10;
          *  0 attaches none. Same model floor as `limit`. */
         context_limit?: number;
     }): Promise<RecallResult>;
-    /** Run a built-in engram ("deep_recall" | "timeline" | "gather"). Returns the merged result.
+    /** Run a built-in engram ("deep_recall" | "timeline" | "gather" | "equilibrium" |
+     * "tone_stabilizer"; the service is the authority — an unknown name comes back with
+     * the list it accepts). Returns the merged result.
      * `form`/`tz` render memory times (memoir/archive) on Scroll 1.2+, same as search/recall. */
     engram(name: string, query: string, userId?: string, opts?: {
         form?: string;
@@ -675,13 +720,14 @@ export declare class Client {
     history(userId?: string): Promise<HistoryTurn[]>;
     /** Memory counts for a store: { total_memories, short_term_turns }. */
     stats(userId?: string): Promise<StatsResult>;
-    /** Fetch ONE memory by id — the original text + metadata, never the vector.
+    /** Fetch ONE memory by id — the text you stored, and its metadata.
      * The id is what `add`/`store` or `listMemories` returned. Same visibility as
-     * `listMemories`: an id from another store, a decomposed atom sentence, or an
-     * invalidated memory rejects with `NotFoundError`. `userId` optional (default store). */
+     * `listMemories`: an id from another store, an internal record id, or an
+     * invalidated memory rejects with `NotFoundError`. Pass `undefined` as `userId` for
+     * the default store — it is positional here, not omittable as it is in Python. */
     get(userId: string | undefined, memoryId: string): Promise<Memory>;
-    /** List a store's stored memories — the original text plus metadata, never the
-     * vector. Paginated: pass the returned `next_cursor` back as `cursor` for the next
+    /** List a store's stored memories — the text you stored, plus its metadata.
+     * Paginated: pass the returned `next_cursor` back as `cursor` for the next
      * page; a `null` cursor means the last page. Use it to browse or export a store.
      *
      *     let cursor: string | null = null;
@@ -697,14 +743,14 @@ export declare class Client {
         cursor?: string;
     }): Promise<MemoryPage>;
     /** Async-iterate every stored memory in a store, paging under the hood — no cursor
-     * bookkeeping. Original text + metadata only, never vectors.
+     * bookkeeping. The text you stored and its metadata only.
      *
      *     for await (const m of mem.iterMemories()) console.log(m.id, m.content);
      */
     iterMemories(userId?: string, opts?: {
         pageSize?: number;
     }): AsyncGenerator<Memory>;
-    /** Collect ALL of a store's memories into an array (original text + metadata, no vectors). */
+    /** Collect ALL of a store's memories into an array (the text you stored, and its metadata). */
     exportMemories(userId?: string): Promise<Memory[]>;
     /**
      * Fetch the bytes of an image memory — the picture the SERVICE holds.
@@ -712,8 +758,8 @@ export declare class Client {
      * Not necessarily your upload, in size OR in format: an image whose long edge was
      * over 1568px was downscaled to 1568 on the way in and re-encoded — lossless
      * formats as WebP, so a PNG comes back as `image/webp`; JPEG stays JPEG — and that
-     * smaller picture is what was embedded, stored and comes back here. Nothing in the
-     * retrieval path looks above 1568, so the extra pixels would be bytes nobody reads.
+     * smaller picture is what is stored and comes back here. Nothing on our side ever
+     * uses more than 1568, so the extra pixels would be bytes nobody reads.
      * Keep your own copy for the full-resolution file.
      *
      * The type is sniffed from the bytes themselves rather than from whatever the file
@@ -831,9 +877,9 @@ export declare class Client {
      * assistant's own words, otherwise a person's name. Same cursor paging as
      * `listImages`.
      *
-     * `chunks` / `points_to_delete` report the sentence-level fragments behind these
-     * memories, which is what a delete would actually remove — usually larger than
-     * `returned`, and worth showing before anyone confirms one.
+     * `chunks` / `points_to_delete` report how many internal records a delete would
+     * actually remove — usually more than `returned`, and worth showing to whoever is
+     * about to confirm one.
      */
     bySpeaker(speaker: string, userId?: string, opts?: {
         limit?: number;
@@ -875,7 +921,8 @@ export declare class Client {
     listSpeakers(userId?: string): Promise<SpeakersList>;
     /** Unregister a person. Their memories stay; the name tag goes. */
     removeSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
-    /** Delete a single memory by id. `userId` optional (uses the default store). */
+    /** Delete a single memory by id. Pass `undefined` as `userId` for the default
+     *  store — it is positional here, not omittable as it is in Python. */
     delete(userId: string | undefined, memoryId: string): Promise<StatusResult>;
     /** Delete ALL memories for a store (GDPR erase). `userId` is required on purpose -
      * this is destructive, so it never falls back to the default store. */
@@ -893,6 +940,31 @@ export declare class Client {
      * a non-2xx we re-read the body as text and reuse `errorFor`, which keeps 404
      * (`NotFoundError`) and 401 behaving the same as everywhere else.
      */
+    /** Where this call's budget runs out, or `undefined` when it has none. Computed
+     *  once per call, not per attempt — a budget recomputed each attempt is not a
+     *  budget. */
+    private deadlineAt;
+    /** The abort wiring for ONE attempt: this SDK's per-attempt timeout, the caller's
+     *  signal, and whatever is left of the overall deadline — whichever fires first.
+     *
+     *  One function, two callers (`request` and `requestBytes`), because a guard living
+     *  in one of two request paths is exactly how `getImage` ended up with no retry loop
+     *  while the module doc promised every call had one. */
+    private beginAttempt;
+    /** What to say when an attempt was cut short. The three reasons need different
+     *  words: a timeout may have landed server-side, a cancellation certainly did not
+     *  matter to the caller, and an exhausted budget is the caller's own setting. */
+    private abortMessage;
+    /** Sleep between attempts — but wake the moment the caller aborts, and give up
+     *  rather than wait out a backoff the budget cannot cover. A backoff that runs to
+     *  completion after the caller gave up wastes exactly as long as the request it was
+     *  waiting to repeat.
+     *
+     *  Clamping the wait to what is left and retrying anyway is the same answer as
+     *  having no deadline at all: the call still spends the whole allowance, and the one
+     *  attempt it buys has nothing left to finish in. If the wait does not fit, the
+     *  budget is already decided. */
+    private backoffSleep;
     private requestBytes;
     /** Validate an idempotency key BEFORE the network. The API answers a malformed
      *  key with a 400, which on a retry path reads as "my write failed" when in fact