@onlyworlds/sdk 4.12.0 → 4.14.0

package/AGENTS.md

@@ -40,6 +40,9 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Images: `uploadImage(bytes)` returns `{ url, ... }`; set `url` as `image_url`. The bytes go
   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.
 - 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.14.0] — 2026-10-12
+
+### Fixed
+- **The co-builder role is `co_builder` on the wire.** `OwJoinPreview.role` and
+  `OwJoinedMembership.role` listed `'co-builder'`, which is only the label keel shows (keel
+  `MemberRole.CO_BUILDER = "co_builder"`). The types were open, so nothing broke at runtime, but
+  a comparison written from them would never match. Caught by Temper from Lantern's fakes.
+
+### Added
+- `OwMemberRole` (`'co_builder' | 'contributor' | 'guest'`, open), the type both now use.
+
+## [4.13.0] — 2026-10-12
+
+### Added
+- **Ask your world (keel #159).** `client.ask({ worldId, question, context })` sends a
+  question to keel's AI proxy with the account's `ow_a_` token (a world key is a `TypeError`
+  before sending) and returns `OwAskAnswer` (`answer`, `model`, `stop_reason`, `usage`,
+  `remaining`). The answer comes from `context` only, or is "The world doesn't say.".
+  `buildAskContext(items, index)` turns the elements the user sees (lookup hits or plain
+  elements, in the caller's order, never re-looked-up) into that `context` within keel's
+  limits (`ASK_LIMITS`: 8 items, 2,000 characters each, 12,000 in all, counted in characters
+  as keel counts them) and says what it did: `kept`, `dropped` (past the 8th, or from the first
+  one the total cannot hold, so what is sent is always the top of the list) and `truncated`.
+  New getters: `isQuotaExceeded` (429; `retryAfter` runs to midnight UTC), `isAskUnavailable`
+  (503), `isAskFailed` (502). keel's document gives no request schema for `/account/ask`, so
+  the body (`world_id`, `question`, `context`) is read from keel's code (`accounts/ask.py`).
+  Not yet run live: no crew session holds an account token.
+
 ## [4.12.0] — 2026-10-12
 
 ### Added

package/README.md

@@ -161,7 +161,16 @@ hits[0].element; hits[0].reasons;                 // best first, with why each m
 renderElement(hits[0].element, index);            // a short text card, links by name
 ```
 
-Names come first, then supertype and subtype, then one link step in either direction, then the elements' other text. To have a model phrase an answer, give it the cards of the top hits and ask it to answer only from them.
+Names come first, then supertype and subtype, then one link step in either direction, then the elements' other text.
+
+To have an answer written from what you found, OnlyWorlds runs a small AI proxy for signed-in accounts (50 questions a day):
+
+```typescript
+const shown = hits.slice(0, 8);                          // what your screen lists
+const { context, kept } = buildAskContext(shown, index); // within the proxy's limits; kept = what was sent
+const reply = await account.ask({ worldId, question, context }); // account: a client with an ow_a_ token
+reply.answer;                                            // from those elements only, or "The world doesn't say."
+```
 
 ## World files
 

package/dist/index.d.ts

@@ -1988,6 +1988,25 @@ interface OwRemovalTicket {
     referenced: number;
 }
 /** The edge's 200 for one removal. */
+/**
+ * A member's role as the wire sends it (keel `MemberRole`, accounts/models.py). `co_builder`
+ * is the value; "co-builder" is only its label in prose. Open, so a new role still types.
+ */
+type OwMemberRole = 'co_builder' | 'contributor' | 'guest' | (string & {});
+/** POST /account/ask: keel's AI proxy's answer (keel #159). */
+interface OwAskAnswer {
+    /** The answer, from the context only; "The world doesn't say." when it does not hold one. */
+    answer: string;
+    model: string;
+    stop_reason: string | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    /** Questions the account has left today. */
+    remaining: number;
+    [k: string]: unknown;
+}
 /** POST /join/preview: what a join code holds, read without using it (keel #212). */
 interface OwJoinPreview {
     /** `person`: an invite link, accepted with acceptJoin. `agent`: redeemed by an AI agent at POST /join. */
@@ -2000,7 +2019,7 @@ interface OwJoinPreview {
     invited_by: string | null;
     /** The world owner's chosen Character's name, never a username; null when none is set. */
     owner_character: string | null;
-    role: 'co-builder' | 'contributor' | 'guest' | (string & {});
+    role: OwMemberRole;
     /** Whether joining gives the joiner a Character of their own (agent links). */
     with_character: boolean | null;
     /** ISO 8601, UTC. */
@@ -2013,7 +2032,7 @@ interface OwJoinedMembership {
     id: string;
     world_id: string;
     world_name: string;
-    role: 'co-builder' | 'contributor' | 'guest' | (string & {});
+    role: OwMemberRole;
     joined_at: string | null;
     /** The id of the joiner's roster Character, or null. */
     roster_character: string | null;
@@ -2176,6 +2195,12 @@ declare class OwApiError extends Error {
     get isAlreadyMember(): boolean;
     /** acceptJoin: the account has no PIN yet, and a member writes with their own (409 `pin_required`). The code is not spent. */
     get isPinRequired(): boolean;
+    /** A daily allowance is used up (429 `quota_exceeded`): the world's image tickets, or the account's asks. See retryAfter. */
+    get isQuotaExceeded(): boolean;
+    /** ask: the proxy is switched off, or paused for the day by the server-wide cap (503 `ask_unavailable`). Not counted. */
+    get isAskUnavailable(): boolean;
+    /** ask: the model gave no answer (502 `ask_failed`). Not counted; try again in a moment. */
+    get isAskFailed(): boolean;
 }
 /**
  * 412 `precondition_failed` (keel #210): the element changed since the `change_seq` sent as
@@ -2422,6 +2447,21 @@ declare class OwV2Client {
      * before anything is sent.
      */
     acceptJoin(code: string): Promise<OwJoinedMembership>;
+    /**
+     * POST /account/ask -- a question about a world the account owns or is in, answered by
+     * keel's AI proxy from `context` only (build it with buildAskContext from the elements
+     * the user sees). The answer is "The world doesn't say." when the context does not hold
+     * it. Needs the client's `ow_a_` token (a world key is a TypeError before sending).
+     * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's daily allowance;
+     * Retry-After runs to midnight UTC), 503 `ask_unavailable` (`err.isAskUnavailable`:
+     * switched off, or paused for the day), 502 `ask_failed` (`err.isAskFailed`); none of
+     * them counts. 422 for a question over 500 characters or context past its limits.
+     */
+    ask(req: {
+        worldId: string;
+        question: string;
+        context: string[];
+    }): Promise<OwAskAnswer>;
     /**
      * Raw authenticated request against this client's baseUrl. Public since 4.0
      * so auxiliary resources can ride the same transport — it structurally
@@ -2714,6 +2754,45 @@ declare function lookupWorld<T extends OwLookupElement>(index: OwWorldIndex<T>,
  */
 declare function renderElement<T extends OwLookupElement>(element: T, index: OwWorldIndex<T>, { descMax, linkMax, incomingMax }?: OwRenderOptions): string;
 
+/**
+ * Context for keel's AI proxy (POST /api/v2/account/ask, Keel #159): the elements a
+ * question is about, as text, within the proxy's limits. The caller passes the
+ * elements it shows the user, in its own order, and gets back exactly which were sent:
+ * the answer's sources are what the user saw, never a second lookup's.
+ *
+ *   const hits = lookupWorld(index, question).slice(0, 8);   // what the screen lists
+ *   const { context, kept } = buildAskContext(hits, index);
+ *   const reply = await account.ask({ worldId, question, context });
+ *
+ * The limits are keel's (accounts/ask.py), counted the way keel counts (characters,
+ * not UTF-16 units): at most 8 items, 2,000 characters each, 12,000 in all.
+ */
+
+/** keel's limits on one ask. */
+declare const ASK_LIMITS: {
+    readonly questionMax: 500;
+    readonly itemsMax: 8;
+    readonly itemMax: 2000;
+    readonly totalMax: 12000;
+};
+interface OwAskContext {
+    /** The texts to send as `context`, in the order given. */
+    context: string[];
+    /** Ids of the elements sent, in order (one per `context` item). */
+    kept: string[];
+    /** Ids of the elements left out: past the 8th, or from the first one the 12,000 total could not hold. */
+    dropped: string[];
+    /** Ids among `kept` whose text was cut to 2,000 characters. */
+    truncated: string[];
+}
+/**
+ * Turn the elements on screen into the proxy's `context`. Takes lookup hits or plain
+ * elements, keeps their order, renders each with `renderElement`, cuts a text over
+ * 2,000 characters, and stops at the 8th or at the first one the 12,000 total cannot
+ * hold, so what is sent is always the top of the list as shown.
+ */
+declare function buildAskContext<T extends OwLookupElement>(items: Array<OwLookupHit<T> | T>, index: OwWorldIndex<T>): OwAskContext;
+
 /**
  * Photo preparation: make a picture from a phone's camera or files ready for
  * `uploadImage` (webp, png, jpeg or avif, at most 15 MB), in the browser,
@@ -3063,4 +3142,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwJoinPreview, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMediaTicket, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldMeta, PHOTO_MAX_BYTES, PHOTO_TYPES, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, buildWorldIndex, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, lookupWorld, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readWorldFile, renderElement, writeWorldFile };
+export { ASK_LIMITS, type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwJoinPreview, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMediaTicket, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldMeta, PHOTO_MAX_BYTES, PHOTO_TYPES, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, buildAskContext, buildWorldIndex, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, lookupWorld, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readWorldFile, renderElement, writeWorldFile };

package/dist/index.js

@@ -87,6 +87,18 @@ var OwApiError = class extends Error {
   get isPinRequired() {
     return this.status === 409 && this.code === "pin_required";
   }
+  /** A daily allowance is used up (429 `quota_exceeded`): the world's image tickets, or the account's asks. See retryAfter. */
+  get isQuotaExceeded() {
+    return this.status === 429 && this.code === "quota_exceeded";
+  }
+  /** ask: the proxy is switched off, or paused for the day by the server-wide cap (503 `ask_unavailable`). Not counted. */
+  get isAskUnavailable() {
+    return this.status === 503 && this.code === "ask_unavailable";
+  }
+  /** ask: the model gave no answer (502 `ask_failed`). Not counted; try again in a moment. */
+  get isAskFailed() {
+    return this.status === 502 && this.code === "ask_failed";
+  }
 };
 var OwPreconditionFailedError = class extends OwApiError {
   constructor(status, code, message, docUrl, detail, type = null, param = null, retryAfter = null) {
@@ -447,6 +459,25 @@ var OwV2Client = class {
     }
     return this.request("POST", "/account/join", { body: { code } });
   }
+  // -- Ask your world (keel #159) -------------------------------------------
+  /**
+   * POST /account/ask -- a question about a world the account owns or is in, answered by
+   * keel's AI proxy from `context` only (build it with buildAskContext from the elements
+   * the user sees). The answer is "The world doesn't say." when the context does not hold
+   * it. Needs the client's `ow_a_` token (a world key is a TypeError before sending).
+   * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's daily allowance;
+   * Retry-After runs to midnight UTC), 503 `ask_unavailable` (`err.isAskUnavailable`:
+   * switched off, or paused for the day), 502 `ask_failed` (`err.isAskFailed`); none of
+   * them counts. 422 for a question over 500 characters or context past its limits.
+   */
+  async ask(req) {
+    if (this.keyKind !== "account") {
+      throw new TypeError("ask needs an account token (ow_a_): the proxy meters per account");
+    }
+    return this.request("POST", "/account/ask", {
+      body: { world_id: req.worldId, question: req.question, context: req.context }
+    });
+  }
   // -- Core request machinery ----------------------------------------------
   /**
    * Raw authenticated request against this client's baseUrl. Public since 4.0
@@ -1871,6 +1902,38 @@ function renderElement(element, index, { descMax = 500, linkMax = 12, incomingMa
   return lines.join("\n");
 }
 
+// src/ask.ts
+var ASK_LIMITS = { questionMax: 500, itemsMax: 8, itemMax: 2e3, totalMax: 12e3 };
+var chars = (s) => [...s].length;
+var cut = (s, n) => [...s].slice(0, n).join("");
+function buildAskContext(items, index) {
+  const out = { context: [], kept: [], dropped: [], truncated: [] };
+  let total = 0;
+  let full = false;
+  for (const item of items) {
+    const el = item && typeof item === "object" && "element" in item ? item.element : item;
+    if (full || out.context.length >= ASK_LIMITS.itemsMax) {
+      out.dropped.push(el.id);
+      continue;
+    }
+    let text = renderElement(el, index);
+    if (chars(text) > ASK_LIMITS.itemMax) {
+      text = cut(text, ASK_LIMITS.itemMax);
+      out.truncated.push(el.id);
+    }
+    if (total + chars(text) > ASK_LIMITS.totalMax) {
+      full = true;
+      out.truncated = out.truncated.filter((id) => id !== el.id);
+      out.dropped.push(el.id);
+      continue;
+    }
+    total += chars(text);
+    out.context.push(text);
+    out.kept.push(el.id);
+  }
+  return out;
+}
+
 // src/photo.ts
 var PHOTO_TYPES = ["image/webp", "image/png", "image/jpeg", "image/avif"];
 var PHOTO_MAX_BYTES = 15 * 1024 * 1024;
@@ -2105,6 +2168,7 @@ var GameTier = /* @__PURE__ */ ((GameTier2) => {
   return GameTier2;
 })(GameTier || {});
 export {
+  ASK_LIMITS,
   ELEMENT_FAMILIES,
   ELEMENT_ICONS,
   ELEMENT_LABELS,
@@ -2126,6 +2190,7 @@ export {
   TokenResource,
   WORLD_FILE_MAX_BYTES,
   WORLD_FILE_MAX_ENTRIES,
+  buildAskContext,
   buildWorldIndex,
   detectKeyKind,
   elementColor,

package/package.json

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