@onlyworlds/sdk 4.18.0 → 4.19.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # For AI agents using @onlyworlds/sdk
 
-**Current as of**: SDK **4.x** · schema-dist **v0.32.0-dist.20** (canonical 00.32.00).
+**Current as of**: SDK **4.x** · schema-dist **v0.32.0-dist.23** (canonical 00.32.00).
 This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
 re-read against it, the check fails rather than letting this document rot quietly.
 
@@ -43,8 +43,14 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   to the edge with a single-use ticket from keel, never with the API key. `removeImage(urlOrKey)`
   takes one back (its uploader or the world's owner); it leaves `image_url` on elements as is.
 - Ask (since 4.13.0, account token): `buildAskContext(hits, index)` then
-  `account.ask({ worldId, question, context })`; answers only from the context. 50 a day per
-  account (`err.isQuotaExceeded`); `isAskUnavailable`, `isAskFailed` count nothing.
+  `account.ask({ worldId, question, context })`; answers only from the context. Spends from the
+  account's daily token rating (`tokens_remaining`, `token_rating`; `remaining` counts answers of
+  this size still in it); used up → `err.isQuotaExceeded`. `isAskUnavailable`, `isAskFailed`
+  count nothing. Custom fields (`x_*`) are in the lookup and the context; `atlas_*` is not.
+- Sort (since 4.18.0, account token): `account.sort({ worldId, notes, slice })` turns unsorted
+  notes (text, or a picture already uploaded into the world) into rows to review: `make`,
+  `add_to`, `link`, `ask`, plus `not_proposed` with reasons. Ids come only from your `slice`
+  (up to 100 elements your own lookup found); nothing is written. Counts as one ask.
 - Invite links (since 4.12.0): `previewJoin(code)` (no credential sent) shows who invites, to
   which world, in what role; `acceptJoin(code)` with an `ow_a_` account token joins. Bad code:
   `err.isNotFound`; `err.isAlreadyMember`, `err.isPinRequired` for the two 409s.

package/CHANGELOG.md

@@ -5,6 +5,34 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.19.0] — 2026-10-14
+
+### Added
+- **`tokens_remaining` and `token_rating` on `OwAskAnswer` and `OwSortAnswer`**: since keel
+  a6244db (Skeld, h37 #4233) ask and sort spend from the account's daily token rating, one
+  meter with the Council. `remaining` stays a count of answers: how many more calls of this
+  size fit in what is left today (keel 504437b), never tokens. Typed from keel's code
+  (`accounts/ask.py`), since its OpenAPI document gives these answers no schema.
+
+### Changed
+- **Custom fields (`x_*`) are in the lookup and on the card.** `buildWorldIndex` finds an
+  element by its custom text and numbers, and `renderElement` (so `buildAskContext`) shows
+  each one by its own name: `x_eye_colour` reads `eye colour: grey`; an id in one is a link,
+  by name; a long value is cut like a description. `atlas_*` machinery stays out, and so do
+  object values (a tool's state). Lantern shows and edits custom fields now, so Ask can answer
+  what find already could (Temper, h37 #4069). The trial's lookup (`dossiers/lantern-ask`)
+  still skips them; parity holds on its ten questions, whose fixture has no custom text.
+- The lookup's stopword set is an array literal, so bundlers mark it pure and drop it from
+  apps that never call the lookup (451 bytes; Temper, h17 #4247).
+
+## [4.18.1] — 2026-10-12
+
+### Changed
+- **Schema repinned to schema-dist v0.32.0-dist.23** (same canonical 00.32.00). The one
+  generated change is the `id` doc comment: a UUID, new ids minted as uuidv7, earlier uuidv4
+  ids still valid. No type changes. The vendored dist gains `walk/lint_folder.py`.
+- README and AGENTS.md describe `sort()`.
+
 ## [4.18.0] — 2026-10-12
 
 ### Added

package/README.md

@@ -174,6 +174,14 @@ const reply = await account.ask({ worldId, question, context }); // account: a c
 reply.answer;                                            // from those elements only, or "The world doesn't say."
 ```
 
+The same proxy sorts loose notes into changes for the user to review. Send the elements your own lookup found for them as the `slice`; every id in a row comes from it, and nothing is written until your app applies what the user accepts. A sort counts as one question.
+
+```typescript
+const slice = hits.slice(0, 100).map(({ element: e }) => ({ id: e.id, type: e.type, name: e.name }));
+const { rows, not_proposed } = await account.sort({ worldId, notes: ['Mira moved to Ostvik.'], slice });
+// rows: make (a new element), add_to (text for a field), link (one element to another), ask (which one?)
+```
+
 ## World files
 
 A world file is one `.zip` holding a whole world folder (`world.json` and `elements/<type>/*.json`, as Atlas keeps a world on disk), the way Atlas downloads and opens one. It needs no account and works in the browser and in Node.

package/SCHEMA.md

@@ -1,6 +1,6 @@
 # OnlyWorlds Schema Reference
 
-**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.32.0-dist.20** — canonical schema **00.32.00**, published 2026-10-11.
+**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.32.0-dist.23** — canonical schema **00.32.00**, published 2026-10-12.
 
 GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
 Written for both humans and AI agents reading this package locally.

package/dist/index.d.ts

@@ -6,7 +6,7 @@
 interface OwElementBase {
     /** Element type slug (server-managed, read-only). */
     type: string;
-    /** Unique identifier for the element, uuidv7 format. */
+    /** Unique identifier for the element, a UUID. New ids are minted as uuidv7; ids minted earlier as uuidv4 remain valid. */
     id: string;
     /** Name of the element. */
     name: string;
@@ -2009,8 +2009,13 @@ interface OwAskAnswer {
         input_tokens: number;
         output_tokens: number;
     };
-    /** Questions the account has left today. */
+    /** How many more calls of this one's size fit in what the account has left today (a count of
+     *  answers, never tokens; it never over-promises). */
     remaining: number;
+    /** The account's tokens left today after this call (since keel a6244db, 2026-10-14). */
+    tokens_remaining: number;
+    /** The account's daily allowance in tokens, one meter with the Council (since keel a6244db). */
+    token_rating: number;
     [k: string]: unknown;
 }
 /**
@@ -2090,8 +2095,13 @@ interface OwSortAnswer {
         input_tokens: number;
         output_tokens: number;
     };
-    /** Questions the account has left today: a sort counts as one ask. */
+    /** How many more calls of this one's size fit in what the account has left today; ask and
+     *  sort spend from one allowance. */
     remaining: number;
+    /** The account's tokens left today after this call (since keel a6244db, 2026-10-14). */
+    tokens_remaining: number;
+    /** The account's daily allowance in tokens, one meter with the Council (since keel a6244db). */
+    token_rating: number;
     [k: string]: unknown;
 }
 /** POST /join/preview: what a join code holds, read without using it (keel #212). */

package/dist/index.js

@@ -1571,7 +1571,107 @@ function writeWorldFile(files, topDir) {
 }
 
 // src/lookup.ts
-var STOP = new Set("a an the of in on at to for from by with and or is are was were be been who whom whose what which where when why how does do did doesn has have had it its this that these those there their they them he she his her him i me my we our you your about tell know any some all can could would should will not no yes than then so if into out up down over under one two own same other more most much many very just also only s t don isn".split(" "));
+var STOP = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "of",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "from",
+  "by",
+  "with",
+  "and",
+  "or",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "who",
+  "whom",
+  "whose",
+  "what",
+  "which",
+  "where",
+  "when",
+  "why",
+  "how",
+  "does",
+  "do",
+  "did",
+  "doesn",
+  "has",
+  "have",
+  "had",
+  "it",
+  "its",
+  "this",
+  "that",
+  "these",
+  "those",
+  "there",
+  "their",
+  "they",
+  "them",
+  "he",
+  "she",
+  "his",
+  "her",
+  "him",
+  "i",
+  "me",
+  "my",
+  "we",
+  "our",
+  "you",
+  "your",
+  "about",
+  "tell",
+  "know",
+  "any",
+  "some",
+  "all",
+  "can",
+  "could",
+  "would",
+  "should",
+  "will",
+  "not",
+  "no",
+  "yes",
+  "than",
+  "then",
+  "so",
+  "if",
+  "into",
+  "out",
+  "up",
+  "down",
+  "over",
+  "under",
+  "one",
+  "two",
+  "own",
+  "same",
+  "other",
+  "more",
+  "most",
+  "much",
+  "many",
+  "very",
+  "just",
+  "also",
+  "only",
+  "s",
+  "t",
+  "don",
+  "isn"
+]);
 var SPATIAL = /* @__PURE__ */ new Set(["pin", "marker", "zone", "map"]);
 var FIELD_HINTS = {
   where: ["location", "parent_location", "birthplace", "locations", "estates", "element_id"],
@@ -1730,7 +1830,7 @@ function buildWorldIndex(elements) {
     if (!SPATIAL.has(el.type)) {
       const tw = /* @__PURE__ */ new Set();
       for (const [field, v] of Object.entries(el)) {
-        if (TEXT_SKIP.has(field) || linkFields.has(field) || field.startsWith("x_") || field.startsWith("atlas_")) continue;
+        if (TEXT_SKIP.has(field) || linkFields.has(field) || field.startsWith("atlas_")) continue;
         const vals = Array.isArray(v) ? v : [v];
         for (const x of vals) {
           if (typeof x === "number" && Number.isFinite(x)) tw.add(String(x));
@@ -1908,18 +2008,21 @@ function renderElement(element, index, { descMax = 500, linkMax = 12, incomingMa
   const unres = /* @__PURE__ */ new Map();
   for (const { field } of index.unresolved.get(el.id) || []) unres.set(field, (unres.get(field) || 0) + 1);
   for (const [field, v] of Object.entries(el)) {
-    if (RENDER_SKIP.has(field) || field.startsWith("x_") || field.startsWith("atlas_")) continue;
+    if (RENDER_SKIP.has(field) || field.startsWith("atlas_")) continue;
+    const custom = field.startsWith("x_");
+    const label = custom ? field.slice(2).replace(/_/g, " ") : field;
     if (outBy.has(field) || unres.has(field)) {
       const names = outBy.get(field) || [];
-      let s = names.slice(0, linkMax).join(", ");
-      if (names.length > linkMax) s += ` (+${names.length - linkMax} more)`;
+      let s2 = names.slice(0, linkMax).join(", ");
+      if (names.length > linkMax) s2 += ` (+${names.length - linkMax} more)`;
       const u = unres.get(field);
-      if (u) s += `${s ? "; " : ""}${u} linked element(s) not present in the world data`;
-      lines.push(`${field}: ${s}`);
+      if (u) s2 += `${s2 ? "; " : ""}${u} linked element(s) not present in the world data`;
+      lines.push(`${label}: ${s2}`);
       continue;
     }
     if (v === null || v === void 0 || v === "" || Array.isArray(v) && !v.length || typeof v === "object" && !Array.isArray(v)) continue;
-    lines.push(`${field}: ${Array.isArray(v) ? v.join(", ") : v}`);
+    const s = Array.isArray(v) ? v.join(", ") : String(v);
+    lines.push(`${label}: ${custom && s.length > descMax ? s.slice(0, descMax) + "..." : s}`);
   }
   const inBy = /* @__PURE__ */ new Map();
   for (const { field, id } of index.inn.get(el.id) || []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.18.0",
+  "version": "4.19.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {