wontopos 2.2.42 → 2.2.44

package/README.md

@@ -180,6 +180,10 @@ try {
 }
 ```
 
+A retired model answers `410`, thrown as `GoneError`: retrying cannot succeed, so name a
+live model (`listModels()` lists them, with `retires_at` on one that is scheduled to
+retire). `deleteStore` still works under a retired model.
+
 ## A different API host
 
 Point the client somewhere other than the default endpoint - a dedicated region,

package/dist/cjs/wontopos.d.cts

@@ -106,6 +106,11 @@ export declare class ConflictError extends WosError {
     readonly conflictsWith?: string;
     constructor(status: number, message: string, requestId?: string, init?: WosErrorInit);
 }
+/** 410 — the model this call named is retired. Retrying cannot succeed: name a live
+ *  model instead (`listModels()` lists them). `deleteStore` still works under a
+ *  retired model. */
+export declare class GoneError extends WosError {
+}
 /** 429 — too many requests. Back off and retry (the client already retries these,
  *  unless `Retry-After` asks for more than 30 seconds). */
 export declare class RateLimitError extends WosError {
@@ -156,13 +161,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
@@ -324,6 +332,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;
@@ -381,10 +391,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. */
@@ -404,7 +420,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?: {
@@ -464,6 +480,10 @@ export interface ModelInfo {
     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 {
@@ -931,9 +951,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.
      *
@@ -1093,8 +1113,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;
@@ -1105,7 +1125,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.

package/dist/cjs/wontopos.js

@@ -1,9 +1,9 @@
 "use strict";
 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.WME = exports.Client = exports.ServerError = exports.RateLimitError = exports.GoneError = 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.42";
+const VERSION = "2.2.44";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -456,6 +456,9 @@ class ConflictError extends WosError {
     }
 }
 exports.ConflictError = ConflictError;
+class GoneError extends WosError {
+}
+exports.GoneError = GoneError;
 class RateLimitError extends WosError {
     retryAfter;
     constructor(status, message, requestId, init) {
@@ -468,6 +471,7 @@ exports.RateLimitError = RateLimitError;
 class ServerError extends WosError {
 }
 exports.ServerError = ServerError;
+const GONE_HINT = "This model is retired; listModels() lists the ones you can use.";
 const STATUS_ERRORS = {
     400: BadRequestError,
     401: AuthenticationError,
@@ -475,6 +479,7 @@ const STATUS_ERRORS = {
     403: PermissionDeniedError,
     404: NotFoundError,
     409: ConflictError,
+    410: GoneError,
     413: BadRequestError,
     422: BadRequestError,
     429: RateLimitError,
@@ -1072,6 +1077,8 @@ class Client {
     errorFromAnswer(res, body, retryAfter, mayBeDeleted = false, unread) {
         const e = parseErrorText(new TextDecoder().decode(body));
         let msg = cleanServerText(e.message) || `HTTP ${res.status}`;
+        if (res.status === 410)
+            msg += ` ${GONE_HINT}`;
         if (unread)
             msg += ` (the error body could not be read: ${cleanServerText(unread, 512)})`;
         const requestId = e.requestId === undefined ? undefined : cleanServerText(e.requestId, 256) || undefined;

package/dist/wontopos.d.ts

@@ -106,6 +106,11 @@ export declare class ConflictError extends WosError {
     readonly conflictsWith?: string;
     constructor(status: number, message: string, requestId?: string, init?: WosErrorInit);
 }
+/** 410 — the model this call named is retired. Retrying cannot succeed: name a live
+ *  model instead (`listModels()` lists them). `deleteStore` still works under a
+ *  retired model. */
+export declare class GoneError extends WosError {
+}
 /** 429 — too many requests. Back off and retry (the client already retries these,
  *  unless `Retry-After` asks for more than 30 seconds). */
 export declare class RateLimitError extends WosError {
@@ -156,13 +161,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
@@ -324,6 +332,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;
@@ -381,10 +391,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. */
@@ -404,7 +420,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?: {
@@ -464,6 +480,10 @@ export interface ModelInfo {
     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 {
@@ -931,9 +951,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.
      *
@@ -1093,8 +1113,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;
@@ -1105,7 +1125,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.

package/dist/wontopos.js

@@ -1,4 +1,4 @@
-const VERSION = "2.2.42";
+const VERSION = "2.2.44";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -443,6 +443,8 @@ export class ConflictError extends WosError {
         this.conflictsWith = typeof c === "string" ? c : undefined;
     }
 }
+export class GoneError extends WosError {
+}
 export class RateLimitError extends WosError {
     retryAfter;
     constructor(status, message, requestId, init) {
@@ -453,6 +455,7 @@ export class RateLimitError extends WosError {
 }
 export class ServerError extends WosError {
 }
+const GONE_HINT = "This model is retired; listModels() lists the ones you can use.";
 const STATUS_ERRORS = {
     400: BadRequestError,
     401: AuthenticationError,
@@ -460,6 +463,7 @@ const STATUS_ERRORS = {
     403: PermissionDeniedError,
     404: NotFoundError,
     409: ConflictError,
+    410: GoneError,
     413: BadRequestError,
     422: BadRequestError,
     429: RateLimitError,
@@ -1057,6 +1061,8 @@ export class Client {
     errorFromAnswer(res, body, retryAfter, mayBeDeleted = false, unread) {
         const e = parseErrorText(new TextDecoder().decode(body));
         let msg = cleanServerText(e.message) || `HTTP ${res.status}`;
+        if (res.status === 410)
+            msg += ` ${GONE_HINT}`;
         if (unread)
             msg += ` (the error body could not be read: ${cleanServerText(unread, 512)})`;
         const requestId = e.requestId === undefined ? undefined : cleanServerText(e.requestId, 256) || undefined;

package/package.json

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