castle-web-sdk 0.4.42 → 0.4.43

package/README.md

@@ -250,20 +250,48 @@ A deck's session server can submit any player's score, which is how a
 leaderboard becomes something a player cannot fake. See the multiplayer
 guide.
 
+### `Store.usage(): Promise<StoreUsage>`
+
+How much the current player and the deck have stored, against the
+limits below, so a deck can warn a player or clear out old saves before a
+write is refused instead of after.
+
+```js
+const { player, shared } = await Store.usage();
+if (player.byteCount > player.byteLimit * 0.9) {
+  // Nearly full: offer to delete old saves.
+}
+```
+
+- `player` is the current player's own allowance in this deck: their
+  `Store.me` and `Store.private` keys, their board scores, and what the
+  deck's `Characters` keep for them in their playthrough.
+- `shared` is `Store.deck`, one allowance for every player together.
+
+Each has `byteCount`, `byteLimit`, `keyCount` and `keyLimit`. A board
+score counts as a key. The answer includes the `set` and `remove` calls
+the page made before calling it, even ones still being batched; await an
+`increment` or a board `submit` first if the answer should include it. A player can only ever see their own usage, not
+another player's.
+
+An app too old to know `usage` rejects with a `CastleError` whose `code`
+is `UNKNOWN_COMMAND`.
+
 ### Limits
 
 The platform caps key length, value size, how many keys one read may
-name, and how much a deck may store in total, and it limits how fast a
+name, and how much each player may store, and it limits how fast a
 player may read and write. Going over one of these rejects with a
 `CastleError` whose `code` says which, so a deck can tell a player it is
-saving too fast apart from a deck that is out of space:
+saving too fast apart from a player who is out of space:
 
 | limit | value |
 |---|---|
 | key | 128 bytes |
 | value | 256 KB |
 | keys in one `get` | 32 |
-| whole deck | 50 MB, 500,000 keys |
+| one player's data in a deck | 50 MB, 50,000 keys |
+| the deck's shared data (`Store.deck`) | 500 MB, 1,000,000 keys |
 | one player's calls | 20 a second, 512 KB a second |
 | every player of a deck together | 500 calls a second, 8 MB a second |
 
@@ -273,6 +301,14 @@ A `list` page holds at most 1,000 entries (a larger `limit` is lowered to
 it) and ends early once it reaches 1 MB; take the next page with its
 `cursor`.
 
+A player's data is everything stored for them: their `Store.private`
+keys, their `Store.user(id)` keys, their scores on every board, and
+their `Characters` playthrough.
+Each player has their own allowance, so a deck with more
+players can hold more, and one player filling theirs does not stop
+anyone else. A write that shrinks what a player stores always succeeds,
+so a player who is full can always free space.
+
 A value is JSON, so binary data such as a picture or a video clip costs
 about a third more once encoded, and a clip of more than a few seconds
 does not fit in one. Ship media with the deck instead.
@@ -747,9 +783,10 @@ limited to Castle admins for now; every other player gets `'refused'`.
 - `tools` — optional function tools, in the OpenAI function-tool schema.
 - `toolChoice` — optional: `'auto'` (the default), `'none'`, `'required'`,
   or `{ type: 'function', function: { name } }` to force one tool.
-- `model` — optional OpenRouter model id: `'meta/muse-spark-1.3-contributor'`
-  (the default), `'meta/muse-spark-1.3'` or `'openai/gpt-4.1-mini'`. Any
-  other model resolves `'error'`.
+- `model` — optional OpenRouter model id, `'meta/muse-spark-1.3-contributor'`
+  by default. Any model OpenRouter lists with a per-token price works; one it
+  does not list, or one with a variable price (`'openrouter/auto'`), resolves
+  `'error'`.
 - `maxTokens` — optional cap on the reply's length. Defaults to 4096; the
   service caps it at 16384.
 - `reasoning` — optional `{ effort: 'minimal' | 'low' | 'medium' | 'high' }`,
@@ -817,7 +854,10 @@ for (let round = 0; round < 8; round++) {
 `AgentChatResult` has a `status`:
 
 - `'ok'` — `message` is the assistant's reply: `{ role, content,
-  tool_calls? }`, with `content` null when the reply is only tool calls.
+  tool_calls?, reasoning_details? }`, with `content` null when the reply is
+  only tool calls. `reasoning_details` holds the model's reasoning blocks
+  (some encrypted) when it returned any; append the message unchanged so the
+  model can pick its reasoning back up on the next call.
   `reasoning` is the model's reasoning summary when it gave one, for
   display; it is not part of `message`. `finishReason` is `'stop'`,
   `'tool_calls'` or `'length'`. `usage` carries `prompt_tokens`,

package/dist/castle.d.ts

@@ -33,7 +33,7 @@ export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue
 export type { SaveState } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
 export { Store } from "./store";
-export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreScopeApi, } from "./store";
+export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreAllowance, StoreScopeApi, StoreUsage, } from "./store";
 export { Time } from "./time";
 export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";
 export type { Json } from "./types";

package/dist/commands.d.ts

@@ -11,6 +11,17 @@ export interface StoreUsage {
     rowCount: number;
     byteCount: number;
 }
+/** One storage allowance: what is stored against it, and its limits. */
+export interface StoreAllowance {
+    keyCount: number;
+    keyLimit: number;
+    byteCount: number;
+    byteLimit: number;
+}
+export interface StoreAllowances {
+    player: StoreAllowance;
+    shared: StoreAllowance;
+}
 export interface StoreBoardEntry {
     subject: string;
     score: number;
@@ -201,6 +212,7 @@ export interface AgentMessage {
     tool_calls?: AgentToolCall[];
     tool_call_id?: string;
     name?: string;
+    reasoning_details?: Json[];
 }
 export interface AgentTool {
     type: "function";
@@ -428,6 +440,7 @@ export interface CommandParams {
         board: string;
         subject?: string | null;
     };
+    "cauldronStorage.usage": Record<string, never>;
     "lifecycle.restoreState": Record<string, never>;
 }
 export interface CommandResult {
@@ -525,6 +538,9 @@ export interface CommandResult {
     "cauldronStorage.boardGet": {
         entry: StoreBoardEntry | null;
     };
+    "cauldronStorage.usage": {
+        usage: StoreAllowances;
+    };
     "lifecycle.restoreState": LifecycleRestoreStateResult;
 }
 export interface UserPayload {

package/dist/store.d.ts

@@ -1,3 +1,4 @@
+import type { StoreAllowance } from "./commands";
 import type { Json } from "./types";
 export interface StoreListOptions {
     /** Only keys beginning with this. Omit for every key in the scope. */
@@ -52,6 +53,16 @@ export interface StoreBoardApi {
     /** One player's score, defaulting to the current player. Null if unset. */
     get(userId?: string): Promise<StoreBoardScore | null>;
 }
+export type { StoreAllowance };
+export interface StoreUsage {
+    /**
+     * The current player's own data in this deck: their `Store.me` and
+     * `Store.private` keys, their board scores and their `Characters` playthrough.
+     */
+    player: StoreAllowance;
+    /** `Store.deck`: one allowance shared by every player of the deck. */
+    shared: StoreAllowance;
+}
 export interface CastleStoreApi {
     /** Shared by everyone playing the deck. */
     readonly deck: StoreScopeApi;
@@ -63,5 +74,11 @@ export interface CastleStoreApi {
     readonly private: StoreScopeApi;
     /** A leaderboard. */
     board(name: string): StoreBoardApi;
+    /**
+     * How much of the current player's allowance, and of the deck's shared one, is
+     * used. Includes the `set` and `remove` calls made before it, even ones still
+     * being batched; an `increment` or board `submit` is included once awaited.
+     */
+    usage(): Promise<StoreUsage>;
 }
 export declare const Store: CastleStoreApi;

package/dist/store.js

@@ -300,6 +300,15 @@ function createBoard(name) {
         },
     };
 }
+async function usage() {
+    // Writes still waiting out the coalescing window would otherwise be missing from
+    // the answer, so a deck that saves and then asks would see its old usage. Send
+    // them now; flushBucket never rejects, and a write that fails reports to its own
+    // caller.
+    await Promise.all(Array.from(buckets.values(), (bucket) => flushBucket(bucket, false)));
+    const { usage: allowances } = await hostRequest("cauldronStorage.usage", {});
+    return { player: allowances.player, shared: allowances.shared };
+}
 export const Store = {
     deck: createScope("deck", null),
     me: createScope("user", null),
@@ -310,4 +319,5 @@ export const Store = {
     board(name) {
         return createBoard(name);
     },
+    usage,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.42",
+  "version": "0.4.43",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"