wontopos 2.2.41 → 2.2.43

package/README.md

@@ -209,7 +209,7 @@ data to fix it.
 ## Changelog
 
 The three clients release in lockstep — same version, same surface, same day. Patch
-releases are additive. Seven inside 2.2 were not, deliberately and each with its
+releases are additive. Eight inside 2.2 were not, deliberately and each with its
 reason; the changelog lists them.
 
 See [CHANGELOG.md](https://github.com/wontopos/wontopos-node/blob/main/CHANGELOG.md).

package/dist/cjs/wontopos.d.cts

@@ -15,11 +15,10 @@
  * 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. `listModels()` reports each model's `memory` as `"shared"` or
- * `"isolated"`, and an isolated one starts empty. Every model on the shared pool
- * lists, fetches and deletes the same memories, but a search may not find memories
- * stored through a different model; store and search with the same one. Set a
- * default in the constructor, or override a single call with
+ * 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(...)`.
  *
  * Recall quality does not depend on which language a memory was written in: a
@@ -157,13 +156,16 @@ export interface Memory {
     speaker?: string;
     [key: string]: unknown;
 }
-/** `add` / `store` → `{ id, status }` (`status: "stored" | "stored (async)" | "duplicate"`). */
+/** `add` / `store` → `{ id, status }`. `status` starts with `"stored"` (more text can
+ *  follow) or is `"duplicate"`; match on the prefix. */
 export interface StoreResult {
     id?: string;
-    /** `"stored"`, or `"duplicate"` when nothing was saved. */
+    /** Starts with `"stored"`, or is `"duplicate"` when nothing was saved. */
     status?: string;
     /**
-     * Present when `status` is `"duplicate"`: the id of the memory this write collided with.
+     * On a duplicate, the id of the memory this write collided with, when the reply has
+     * it. A duplicate can arrive with an empty `id` and no `duplicate_of`; then search with
+     * the same text to find the memory it matched.
      *
      * 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
@@ -325,6 +327,8 @@ export interface SpeakerPage {
     memories: Memory[];
     chunks?: number;
     /** The count to show before anyone confirms a delete of this speaker's memories. */
+    records_to_delete?: number;
+    /** @deprecated The same number as `records_to_delete`, under its old name. */
     points_to_delete?: number;
     returned?: number;
     has_more?: boolean;
@@ -382,10 +386,16 @@ export interface EngramResult {
     usage?: Usage;
     [key: string]: unknown;
 }
+/** One turn of the short-term window, as `history()` returns it. */
 export interface HistoryTurn {
+    /** `"user"` or `"assistant"`. */
+    role?: string;
+    content?: string;
+    timestamp?: string;
+    /** @deprecated Not sent: a turn comes back as `role` and `content`. */
     user_msg?: string;
+    /** @deprecated Not sent: a turn comes back as `role` and `content`. */
     assistant_msg?: string;
-    timestamp?: string;
     [key: string]: unknown;
 }
 /** `usage` → what this key has spent, and what is left to spend. */
@@ -405,7 +415,7 @@ export interface UsageResult {
         requests?: number;
         cost_cents?: number;
     };
-    /** Per-store spend over the window, busiest first, and at most 50 rows — a longer
+    /** Per-store spend over the window, highest spend first, and at most 50 rows — a longer
      *  list is cut, so these need not sum to `workspace`. `other`, when present, is an
      *  overflow bucket rather than a store. */
     stores?: {
@@ -461,12 +471,14 @@ export interface ModelInfo {
     id: string;
     name: string;
     available: boolean;
-    /** "shared" — lists, fetches and deletes the common memory pool, though a search
-     *  may not find memories stored through a different model; "isolated" — its own
-     *  dedicated store. */
+    /** "shared" — reads the common memory pool; "isolated" — its own dedicated store. */
     memory: "shared" | "isolated";
     /** What this model can do. Check it before relying on a feature. */
     capabilities?: ModelCapabilities;
+    /** Present on a live model that is scheduled to retire (RFC3339). From that instant
+     *  the model leaves this list and calls naming it are refused. */
+    retires_at?: string;
+    [key: string]: unknown;
 }
 /** One entry of the engram / delivery-form catalogue (`listEngrams`). */
 export interface EngramInfo {
@@ -934,9 +946,9 @@ export declare class Client {
     get(userId: string | undefined, memoryId: string): Promise<Memory>;
     /** 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, and only a cursor the service returned. A `null` cursor means there is no
-     * next page; a non-null one can still be followed by an empty page. Use it to
-     * browse or export a store.
+     * page, and only a cursor the service returned, with the model that returned it. A
+     * `null` cursor means there is no next page; a non-null one can still be followed by
+     * an empty page. Use it to browse or export a store.
      *
      * `limit` is 1-500 (default 100); anything else is refused before the request.
      *
@@ -1096,8 +1108,8 @@ export declare class Client {
      * assistant's own words, otherwise a person's name. Same cursor paging as
      * `listImages`; `limit` is 5-20.
      *
-     * `points_to_delete` is the count to show before anyone confirms a delete of this
-     * speaker's memories.
+     * `records_to_delete` is the count to show before anyone confirms a delete of this
+     * speaker's memories; `points_to_delete` is the same number under its old name.
      */
     bySpeaker(speaker: string, userId?: string, opts?: {
         limit?: number;
@@ -1108,7 +1120,8 @@ export declare class Client {
      * `AuthenticationError` (bad key), `PaymentRequiredError` (valid key but no card /
      * depleted balance), or `APIConnectionError` (unreachable). Makes one metered request. */
     ping(): Promise<boolean>;
-    /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
+    /** Available models: `[{ id, name, available, memory, capabilities, retires_at? }, ...]`.
+     *  Needs no API key. */
     listModels(): Promise<ModelInfo[]>;
     /**
      * The engrams (and delivery forms) the selected model can actually run.
@@ -1194,9 +1207,9 @@ export declare class Client {
      * dropped connections on idempotent methods; connect failures on every method. A
      * retry whose wait is over the cap, or does not fit the deadline, is not made: the
      * call fails with the error of the response it has. So does a retry the deadline
-     * leaves no time to send, and the retry of an idempotent method or `getImage` that
-     * the deadline cuts short. Any other retry cut short stays a status-0 deadline error:
-     * a write may have been applied.
+     * leaves no time to send, and the retry of an idempotent method or of a POST that
+     * only reads that the deadline cuts short. Any other retry cut short stays a status-0
+     * deadline error: a write may have been applied.
      */
     private send;
     /**

package/dist/cjs/wontopos.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WME = exports.Client = exports.ServerError = exports.RateLimitError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.PaymentRequiredError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionError = exports.WosError = exports.CONTEXT_LIMIT_MAX = exports.CONTEXT_LIMIT_MIN = exports.SEARCH_LIMIT_MAX = exports.SEARCH_LIMIT_MIN = void 0;
 exports._resetStoreIdWarnings = _resetStoreIdWarnings;
 exports._resetFilterWarnings = _resetFilterWarnings;
-const VERSION = "2.2.41";
+const VERSION = "2.2.43";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -22,6 +22,20 @@ const MAX_RETRY_WAIT_MS = 30_000;
 const MAX_TIMER_MS = 2_147_483_647;
 const RETRY_IF_IDEMPOTENT = new Set([408, 502, 503, 504]);
 const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+const READ_POSTS = new Set([
+    "/api/v1/memory/search",
+    "/api/v1/memory/recall",
+    "/api/v1/memory/get",
+    "/api/v1/memory/list",
+    "/api/v1/memory/stats",
+    "/api/v1/memory/history",
+    "/api/v1/memory/lineage",
+    "/api/v1/memory/by-speaker",
+    "/api/v1/memory/images",
+    "/api/v1/memory/image",
+    "/api/v1/engram/run",
+    "/api/v1/won/revisions",
+]);
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
 const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
 const MODEL_RE = /^[A-Za-z0-9._-]+$/;
@@ -1099,8 +1113,9 @@ class Client {
             };
             const cutShort = () => {
                 const why = att.why();
-                if (why === "deadline" && (idempotent || reads) && previous)
+                if (why === "deadline" && (idempotent || reads || (upper === "POST" && READ_POSTS.has(logPath))) && previous) {
                     return previous;
+                }
                 return new APIConnectionError(0, this.abortMessage(why));
             };
             let res;

package/dist/wontopos.d.ts

@@ -15,11 +15,10 @@
  * 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. `listModels()` reports each model's `memory` as `"shared"` or
- * `"isolated"`, and an isolated one starts empty. Every model on the shared pool
- * lists, fetches and deletes the same memories, but a search may not find memories
- * stored through a different model; store and search with the same one. Set a
- * default in the constructor, or override a single call with
+ * 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(...)`.
  *
  * Recall quality does not depend on which language a memory was written in: a
@@ -157,13 +156,16 @@ export interface Memory {
     speaker?: string;
     [key: string]: unknown;
 }
-/** `add` / `store` → `{ id, status }` (`status: "stored" | "stored (async)" | "duplicate"`). */
+/** `add` / `store` → `{ id, status }`. `status` starts with `"stored"` (more text can
+ *  follow) or is `"duplicate"`; match on the prefix. */
 export interface StoreResult {
     id?: string;
-    /** `"stored"`, or `"duplicate"` when nothing was saved. */
+    /** Starts with `"stored"`, or is `"duplicate"` when nothing was saved. */
     status?: string;
     /**
-     * Present when `status` is `"duplicate"`: the id of the memory this write collided with.
+     * On a duplicate, the id of the memory this write collided with, when the reply has
+     * it. A duplicate can arrive with an empty `id` and no `duplicate_of`; then search with
+     * the same text to find the memory it matched.
      *
      * 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
@@ -325,6 +327,8 @@ export interface SpeakerPage {
     memories: Memory[];
     chunks?: number;
     /** The count to show before anyone confirms a delete of this speaker's memories. */
+    records_to_delete?: number;
+    /** @deprecated The same number as `records_to_delete`, under its old name. */
     points_to_delete?: number;
     returned?: number;
     has_more?: boolean;
@@ -382,10 +386,16 @@ export interface EngramResult {
     usage?: Usage;
     [key: string]: unknown;
 }
+/** One turn of the short-term window, as `history()` returns it. */
 export interface HistoryTurn {
+    /** `"user"` or `"assistant"`. */
+    role?: string;
+    content?: string;
+    timestamp?: string;
+    /** @deprecated Not sent: a turn comes back as `role` and `content`. */
     user_msg?: string;
+    /** @deprecated Not sent: a turn comes back as `role` and `content`. */
     assistant_msg?: string;
-    timestamp?: string;
     [key: string]: unknown;
 }
 /** `usage` → what this key has spent, and what is left to spend. */
@@ -405,7 +415,7 @@ export interface UsageResult {
         requests?: number;
         cost_cents?: number;
     };
-    /** Per-store spend over the window, busiest first, and at most 50 rows — a longer
+    /** Per-store spend over the window, highest spend first, and at most 50 rows — a longer
      *  list is cut, so these need not sum to `workspace`. `other`, when present, is an
      *  overflow bucket rather than a store. */
     stores?: {
@@ -461,12 +471,14 @@ export interface ModelInfo {
     id: string;
     name: string;
     available: boolean;
-    /** "shared" — lists, fetches and deletes the common memory pool, though a search
-     *  may not find memories stored through a different model; "isolated" — its own
-     *  dedicated store. */
+    /** "shared" — reads the common memory pool; "isolated" — its own dedicated store. */
     memory: "shared" | "isolated";
     /** What this model can do. Check it before relying on a feature. */
     capabilities?: ModelCapabilities;
+    /** Present on a live model that is scheduled to retire (RFC3339). From that instant
+     *  the model leaves this list and calls naming it are refused. */
+    retires_at?: string;
+    [key: string]: unknown;
 }
 /** One entry of the engram / delivery-form catalogue (`listEngrams`). */
 export interface EngramInfo {
@@ -934,9 +946,9 @@ export declare class Client {
     get(userId: string | undefined, memoryId: string): Promise<Memory>;
     /** 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, and only a cursor the service returned. A `null` cursor means there is no
-     * next page; a non-null one can still be followed by an empty page. Use it to
-     * browse or export a store.
+     * page, and only a cursor the service returned, with the model that returned it. A
+     * `null` cursor means there is no next page; a non-null one can still be followed by
+     * an empty page. Use it to browse or export a store.
      *
      * `limit` is 1-500 (default 100); anything else is refused before the request.
      *
@@ -1096,8 +1108,8 @@ export declare class Client {
      * assistant's own words, otherwise a person's name. Same cursor paging as
      * `listImages`; `limit` is 5-20.
      *
-     * `points_to_delete` is the count to show before anyone confirms a delete of this
-     * speaker's memories.
+     * `records_to_delete` is the count to show before anyone confirms a delete of this
+     * speaker's memories; `points_to_delete` is the same number under its old name.
      */
     bySpeaker(speaker: string, userId?: string, opts?: {
         limit?: number;
@@ -1108,7 +1120,8 @@ export declare class Client {
      * `AuthenticationError` (bad key), `PaymentRequiredError` (valid key but no card /
      * depleted balance), or `APIConnectionError` (unreachable). Makes one metered request. */
     ping(): Promise<boolean>;
-    /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
+    /** Available models: `[{ id, name, available, memory, capabilities, retires_at? }, ...]`.
+     *  Needs no API key. */
     listModels(): Promise<ModelInfo[]>;
     /**
      * The engrams (and delivery forms) the selected model can actually run.
@@ -1194,9 +1207,9 @@ export declare class Client {
      * dropped connections on idempotent methods; connect failures on every method. A
      * retry whose wait is over the cap, or does not fit the deadline, is not made: the
      * call fails with the error of the response it has. So does a retry the deadline
-     * leaves no time to send, and the retry of an idempotent method or `getImage` that
-     * the deadline cuts short. Any other retry cut short stays a status-0 deadline error:
-     * a write may have been applied.
+     * leaves no time to send, and the retry of an idempotent method or of a POST that
+     * only reads that the deadline cuts short. Any other retry cut short stays a status-0
+     * deadline error: a write may have been applied.
      */
     private send;
     /**

package/dist/wontopos.js

@@ -1,4 +1,4 @@
-const VERSION = "2.2.41";
+const VERSION = "2.2.43";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -17,6 +17,20 @@ const MAX_RETRY_WAIT_MS = 30_000;
 const MAX_TIMER_MS = 2_147_483_647;
 const RETRY_IF_IDEMPOTENT = new Set([408, 502, 503, 504]);
 const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+const READ_POSTS = new Set([
+    "/api/v1/memory/search",
+    "/api/v1/memory/recall",
+    "/api/v1/memory/get",
+    "/api/v1/memory/list",
+    "/api/v1/memory/stats",
+    "/api/v1/memory/history",
+    "/api/v1/memory/lineage",
+    "/api/v1/memory/by-speaker",
+    "/api/v1/memory/images",
+    "/api/v1/memory/image",
+    "/api/v1/engram/run",
+    "/api/v1/won/revisions",
+]);
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
 const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
 const MODEL_RE = /^[A-Za-z0-9._-]+$/;
@@ -1084,8 +1098,9 @@ export class Client {
             };
             const cutShort = () => {
                 const why = att.why();
-                if (why === "deadline" && (idempotent || reads) && previous)
+                if (why === "deadline" && (idempotent || reads || (upper === "POST" && READ_POSTS.has(logPath))) && previous) {
                     return previous;
+                }
                 return new APIConnectionError(0, this.abortMessage(why));
             };
             let res;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.41",
+  "version": "2.2.43",
   "description": "Wontopos \u2014 long-term memory for AI agents. Identical recall in every language, ~100\u00d7 lower LLM bill.",
   "keywords": [
     "memory",