castle-web-sdk 0.4.33 → 0.4.35

package/README.md

@@ -24,7 +24,9 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
 - [Pass](#pass)
 - [Snapshot](#snapshot)
 - [Portal](#portal)
+- [Decks](#decks)
 - [Haptics](#haptics)
+- [Agent](#agent)
 - [Lifecycle](#lifecycle)
 - [Multiplayer](#multiplayer)
 - [Setup](#setup)
@@ -616,6 +618,38 @@ if (info.status === "ok") {
 
 Answers are kept per deck for the session, so asking again is cheap.
 
+## Decks
+
+`Decks` lists decks the player can point a portal at: their own published
+decks, and the decks they saved. A deck can offer these as a picker rather
+than asking for a pasted link.
+Decks is limited to Castle admins for now; for every other player both calls
+reject with a `PERMISSION_DENIED` error.
+
+### `Decks.mine(options?): Promise<DecksListResult>`
+
+The player's own decks, newest first, leaving out private ones.
+
+### `Decks.saved(options?): Promise<DecksListResult>`
+
+The decks the player bookmarked, then the decks in their playlists, each
+once.
+
+Both take `{ limit }`, from 1 through 50 (default 20), and both leave out
+decks whose creator turned portals off. The result is
+`{ status: 'ok', decks }`, where each deck is
+`{ deckId, title, creator: { userId, username } | null, coverUrl }` — the
+same shape as `Portal.info`. `coverUrl` is a `data:` url, since a deck may
+not load remote images; it is null when the deck has no cover. A player
+who is not signed in gets an empty list.
+
+```js
+const { decks } = await Decks.mine({ limit: 12 });
+for (const deck of decks) {
+  addPickerTile(deck.title, deck.coverUrl, () => placePortal(deck.deckId));
+}
+```
+
 ## Haptics
 
 `Haptics` plays a short device vibration ("buzz") for tactile feedback —
@@ -651,6 +685,103 @@ Haptics respect the player's settings — if a player has muted haptics,
 `play` does nothing and resolves `'unavailable'`. Rapid repeated calls may
 be coalesced, so it's safe to call on frequent events.
 
+## Agent
+
+`Agent` asks a language model for one chat completion. The host sends it
+through Castle's oracle on the player's own Castle account, so the deck
+holds no key. Agent.chat is limited to Castle admins for now; every other
+player gets `'refused'`.
+
+### `Agent.chat(params): Promise<AgentChatResult>`
+
+`params`:
+
+- `messages` — the conversation, in the OpenAI chat format
+  (`{ role, content }`, plus `tool_calls` on an assistant message and
+  `tool_call_id` on a `'tool'` message).
+- `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. Defaults to
+  `'meta/muse-spark-1.3'`.
+- `maxTokens` — optional cap on the reply's length.
+- `reasoning` — optional `{ effort: 'minimal' | 'low' | 'medium' | 'high' }`,
+  how hard the model thinks before it answers. Lower effort answers sooner.
+  Left out, the model uses its own default. Muse can't turn reasoning off;
+  `'minimal'` is its least.
+- `onDelta` — optional callback for the reply as it streams in. It gets
+  `{ type: 'text', text }` and `{ type: 'reasoning', text }` pieces, and
+  `{ type: 'toolCall', toolCall }` once for each tool call, when its
+  arguments are complete. Pieces come in the order the model wrote them.
+- `signal` — optional `AbortSignal`. Aborting it stops the model and
+  resolves the call with `'cancelled'` at once.
+
+The promise resolves with the whole message when the model finishes. A deck
+runs any tool calls itself, appends the message and one `'tool'` message per
+call, and calls Agent.chat again, until a reply has no tool calls:
+
+```js
+import { Agent } from "castle-web-sdk";
+
+const tools = [
+  {
+    type: "function",
+    function: {
+      name: "roll_dice",
+      description: "Roll six-sided dice.",
+      parameters: {
+        type: "object",
+        properties: { count: { type: "integer" } },
+        required: ["count"],
+      },
+    },
+  },
+];
+const messages = [{ role: "user", content: "Roll two dice and add them." }];
+const stop = new AbortController();
+
+for (let round = 0; round < 8; round++) {
+  const result = await Agent.chat({
+    messages,
+    tools,
+    signal: stop.signal,
+    onDelta: (delta) => {
+      if (delta.type === "text") {
+        showText(delta.text);
+      }
+    },
+  });
+  if (result.status !== "ok") {
+    break;
+  }
+  messages.push(result.message);
+  const calls = result.message.tool_calls ?? [];
+  if (calls.length === 0) {
+    break;
+  }
+  for (const call of calls) {
+    const { count } = JSON.parse(call.function.arguments);
+    const faces = Array.from({ length: count }, () => 1 + Math.floor(Math.random() * 6));
+    messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(faces) });
+  }
+}
+```
+
+`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.
+  `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`,
+  `completion_tokens` and `total_tokens`.
+- `'refused'` — the player is not a Castle admin. The model was not called.
+- `'unavailable'` — this host has no route to the oracle.
+- `'cancelled'` — the call's `signal` was aborted.
+- `'error'` — the oracle or the model failed; `reason` says how.
+
+Every status but `'ok'` carries a `reason`.
+
 ## Lifecycle
 
 `Lifecycle` tells the host when the deck has painted its first frame, so

package/dist/agent.d.ts

@@ -0,0 +1,6 @@
+import type { AgentChatParams, AgentChatResult } from "./commands";
+export type { AgentChatDelta, AgentChatParams, AgentChatResult, AgentMessage, AgentReasoning, AgentTool, AgentToolCall, AgentToolChoice, AgentUsage, } from "./commands";
+export interface CastleAgentApi {
+    chat(params: AgentChatParams): Promise<AgentChatResult>;
+}
+export declare const Agent: CastleAgentApi;

package/dist/agent.js

@@ -0,0 +1,70 @@
+// Agent — one chat completion from a language model, run by the host through
+// Castle's oracle with the player's own Castle account. Messages and tools
+// follow the OpenAI chat completions format. The reply streams: `onDelta` gets
+// text and reasoning as they arrive and each tool call once its arguments are
+// complete, and the promise resolves with the whole message. A deck runs any
+// tool calls itself and calls Agent.chat again with the results.
+//
+// Agent.chat is limited to Castle admins for now: every other player gets
+// `refused`. A host with no route to the oracle answers `unavailable`.
+import { CastleError } from "./errors";
+import { hostRequest } from "./transport";
+async function chat(params) {
+    validate(params);
+    const onDelta = params.onDelta;
+    try {
+        return await hostRequest("agent.chat", {
+            messages: params.messages,
+            tools: params.tools,
+            toolChoice: params.toolChoice,
+            model: params.model,
+            maxTokens: params.maxTokens,
+            reasoning: params.reasoning,
+        }, {
+            onStream: onDelta ? (event) => deliverDelta(onDelta, event) : undefined,
+            signal: params.signal,
+        });
+    }
+    catch (error) {
+        if (error instanceof CastleError && error.code === "CANCELLED") {
+            return { status: "cancelled", reason: "Agent.chat was cancelled." };
+        }
+        throw error;
+    }
+}
+const REASONING_EFFORTS = ["minimal", "low", "medium", "high"];
+function validate(params) {
+    if (!params || typeof params !== "object") {
+        invalid("Agent.chat requires { messages }.");
+    }
+    if (!Array.isArray(params.messages) || params.messages.length === 0) {
+        invalid("Agent.chat messages must be a non-empty array.");
+    }
+    if (params.tools !== undefined && !Array.isArray(params.tools)) {
+        invalid("Agent.chat tools must be an array.");
+    }
+    if (params.model !== undefined && (typeof params.model !== "string" || params.model === "")) {
+        invalid("Agent.chat model must be a model id.");
+    }
+    if (params.maxTokens !== undefined &&
+        (!Number.isSafeInteger(params.maxTokens) || params.maxTokens < 1)) {
+        invalid("Agent.chat maxTokens must be a positive integer.");
+    }
+    if (params.reasoning !== undefined && !REASONING_EFFORTS.includes(params.reasoning?.effort)) {
+        invalid("Agent.chat reasoning must be { effort: 'minimal' | 'low' | 'medium' | 'high' }.");
+    }
+    if (params.onDelta !== undefined && typeof params.onDelta !== "function") {
+        invalid("Agent.chat onDelta must be a function.");
+    }
+}
+// Keepalives only restart the wait in transport.ts; the deck never sees them.
+function deliverDelta(onDelta, event) {
+    const type = event?.type;
+    if (type === "text" || type === "reasoning" || type === "toolCall") {
+        onDelta(event);
+    }
+}
+function invalid(message) {
+    throw new CastleError({ code: "INVALID_ARGUMENT", message, operation: "Agent.chat" });
+}
+export const Agent = Object.freeze({ chat });

package/dist/castle.d.ts

@@ -1,6 +1,10 @@
 export { isEdit } from "./context";
+export { Agent } from "./agent";
+export type { AgentChatDelta, AgentChatParams, AgentChatResult, AgentMessage, AgentReasoning, AgentTool, AgentToolCall, AgentToolChoice, AgentUsage, CastleAgentApi, } from "./agent";
 export { Characters } from "./characters";
 export type { CastleCharactersApi, CharacterHandle, CharacterHistoryOptions, CharacterSendInput, } from "./characters";
+export { Decks } from "./decks";
+export type { CastleDecksApi, DeckSummary, DecksListParams, DecksListResult } from "./decks";
 export { CastleError } from "./errors";
 export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
 export { Haptics } from "./haptics";

package/dist/castle.js

@@ -1,6 +1,8 @@
 // Castle Web SDK
 export { isEdit } from "./context";
+export { Agent } from "./agent";
 export { Characters } from "./characters";
+export { Decks } from "./decks";
 export { CastleError } from "./errors";
 export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
 export { Haptics } from "./haptics";

package/dist/commands.d.ts

@@ -142,7 +142,97 @@ export interface CharacterHistory {
     operations: CharacterOperation[];
     cursor: string | null;
 }
+export interface AgentToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface AgentMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | Json[] | null;
+    tool_calls?: AgentToolCall[];
+    tool_call_id?: string;
+    name?: string;
+}
+export interface AgentTool {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Json;
+    };
+}
+export type AgentToolChoice = "auto" | "none" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
+export type AgentChatDelta = {
+    type: "text";
+    text: string;
+} | {
+    type: "reasoning";
+    text: string;
+} | {
+    type: "toolCall";
+    toolCall: AgentToolCall;
+};
+export type AgentChatStreamEvent = AgentChatDelta | {
+    type: "keepalive";
+};
+export interface AgentReasoning {
+    effort: "minimal" | "low" | "medium" | "high";
+}
+export interface AgentChatParams {
+    messages: AgentMessage[];
+    tools?: AgentTool[];
+    toolChoice?: AgentToolChoice;
+    model?: string;
+    maxTokens?: number;
+    reasoning?: AgentReasoning;
+    onDelta?: (delta: AgentChatDelta) => void;
+    signal?: AbortSignal;
+}
+export type AgentChatRequest = Omit<AgentChatParams, "onDelta" | "signal">;
+export interface AgentUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+export type AgentChatResult = {
+    status: "ok";
+    message: AgentMessage;
+    reasoning?: string;
+    finishReason: string | null;
+    usage?: AgentUsage;
+} | {
+    status: "unavailable" | "refused" | "error" | "cancelled";
+    reason: string;
+};
+export interface DeckSummary {
+    deckId: string;
+    title: string;
+    creator: {
+        userId: string;
+        username: string;
+    } | null;
+    coverUrl: string | null;
+}
+export interface DecksListParams {
+    limit?: number | null;
+}
+export interface DecksListResult {
+    status: "ok";
+    decks: DeckSummary[];
+}
 export interface CommandParams {
+    "agent.chat": AgentChatRequest;
+    "decks.mine": DecksListParams;
+    "decks.saved": DecksListParams;
     "deckStorage.load": Record<string, never>;
     "deckStorage.update": {
         updates: StorageUpdate[];
@@ -279,6 +369,9 @@ export interface CommandParams {
     "lifecycle.restoreState": Record<string, never>;
 }
 export interface CommandResult {
+    "agent.chat": AgentChatResult;
+    "decks.mine": DecksListResult;
+    "decks.saved": DecksListResult;
     "deckStorage.load": {
         blob: StorageBlob;
     };
@@ -365,6 +458,8 @@ export interface UserPayload {
     color: string | null;
 }
 export type CommandName = keyof CommandParams;
+export declare const COMMAND_TIMEOUTS_MS: Partial<Record<CommandName, number>>;
+export declare const STREAM_IDLE_TIMEOUT_MS = 60000;
 export interface SerializedCommandError {
     code: string;
     message: string;
@@ -385,6 +480,17 @@ export interface CommandResponseEnvelope {
     error?: SerializedCommandError;
 }
 export declare function isResponseEnvelope(value: unknown): value is CommandResponseEnvelope;
+export interface CommandStreamEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    requestId: string;
+    stream: unknown;
+}
+export declare function isStreamEnvelope(value: unknown): value is CommandStreamEnvelope;
+export interface CommandCancelEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    requestId: string;
+    cancel: true;
+}
 export type LifecycleEvent = "ready" | "unloadInterest";
 export interface LifecycleEnvelope {
     castleSdk: typeof CASTLE_SDK_PROTOCOL;

package/dist/commands.js

@@ -6,6 +6,18 @@
 // Marker + protocol version. Doubles as a discriminator so host messages can't
 // be confused with embed.js `castlexyz:` strings or RN console messages.
 export const CASTLE_SDK_PROTOCOL = 1;
+// How long the deck waits for a reply to these commands, in place of the
+// data-command timeout. A deck list fetches every cover on the list. A host
+// from before streaming reads a whole model reply before answering agent.chat.
+export const COMMAND_TIMEOUTS_MS = {
+    "agent.chat": 180_000,
+    "decks.mine": 30_000,
+    "decks.saved": 30_000,
+};
+// Once a host streams a command, each stream envelope restarts the wait at this
+// length instead. The oracle sends a heartbeat every 15 seconds, and the host
+// passes each one on.
+export const STREAM_IDLE_TIMEOUT_MS = 60_000;
 export function isResponseEnvelope(value) {
     if (typeof value !== "object" || value === null)
         return false;
@@ -14,6 +26,15 @@ export function isResponseEnvelope(value) {
         typeof record.requestId === "string" &&
         typeof record.ok === "boolean");
 }
+export function isStreamEnvelope(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    return (record.castleSdk === CASTLE_SDK_PROTOCOL &&
+        typeof record.requestId === "string" &&
+        "stream" in record);
+}
 export function unloadRequestId(value) {
     if (typeof value !== "object" || value === null)
         return null;

package/dist/decks.d.ts

@@ -0,0 +1,7 @@
+import type { DecksListParams, DecksListResult } from "./commands";
+export type { DeckSummary, DecksListParams, DecksListResult } from "./commands";
+export interface CastleDecksApi {
+    mine(options?: DecksListParams): Promise<DecksListResult>;
+    saved(options?: DecksListParams): Promise<DecksListResult>;
+}
+export declare const Decks: CastleDecksApi;

package/dist/decks.js

@@ -0,0 +1,31 @@
+// Decks — the player's own published decks and the decks they saved, for
+// picking where a portal leads. Each entry has the same shape as Portal.info:
+// deckId, title, creator and a cover as a data: url.
+//
+// Both lists leave out decks a portal cannot reach: a private deck, or one
+// whose creator turned portals off.
+//
+// Decks is limited to Castle admins for now; other players get a
+// PERMISSION_DENIED error.
+import { CastleError } from "./errors";
+import { hostRequest } from "./transport";
+function mine(options = {}) {
+    return hostRequest("decks.mine", { limit: listLimit(options.limit, "Decks.mine") });
+}
+function saved(options = {}) {
+    return hostRequest("decks.saved", { limit: listLimit(options.limit, "Decks.saved") });
+}
+function listLimit(value, operation) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (Number.isSafeInteger(value) && value >= 1 && value <= 50) {
+        return value;
+    }
+    throw new CastleError({
+        code: "INVALID_ARGUMENT",
+        message: `${operation} limit must be an integer from 1 through 50.`,
+        operation,
+    });
+}
+export const Decks = Object.freeze({ mine, saved });

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import { type CommandName, type CommandParams, type CommandResponseEnvelope } from "./commands";
+import { type CommandName, type CommandParams, type CommandResponseEnvelope, type CommandStreamEnvelope } from "./commands";
 import { type TunedParam } from "./paramsRegistry";
 export declare const CARD_RATIO: number;
 interface LocalResponse {
@@ -43,7 +43,9 @@ export declare function renameFile(from: string, to: string): Promise<void>;
 export declare function deleteFile(path: string): Promise<void>;
 export declare function openFile(path: string): void;
 export declare function initCard(): HTMLDivElement;
-export declare function sendLocalCommand<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResponseEnvelope>;
+export declare function sendLocalCommand<C extends CommandName>(requestId: string, command: C, params: CommandParams[C], listener: (message: CommandResponseEnvelope | CommandStreamEnvelope) => void): Promise<void>;
+export declare function cancelLocalCommand(requestId: string): void;
+export declare function releaseLocalCommand(requestId: string): void;
 /**
  * Notified `true` on every fresh dev-server socket and `false` when one is lost.
  * What lets a queued write know the moment retrying is worth it again.

package/dist/runtime.js

@@ -13,10 +13,9 @@ const pendingRequests = new Map();
 // Local-dev command channel: the `castle-web serve` dev server is the host, so
 // SDK commands ride the same websocket runtime.ts already uses for
 // logs/screenshots/restart. Correlated by requestId, separate from the
-// screenshot/write_file request map above.
-const COMMAND_TIMEOUT_MS = 15000;
+// screenshot/write_file request map above. transport.ts owns the timeouts.
 const SOCKET_WAIT_TIMEOUT_MS = 10000;
-const pendingCommands = new Map();
+const localCommandListeners = new Map();
 const origLog = console.log;
 const origWarn = console.warn;
 const origError = console.error;
@@ -324,38 +323,42 @@ function sendLocalRequest(msg) {
         ws.send(JSON.stringify(request));
     });
 }
-// Send an SDK command to the dev server and resolve with the raw response
-// envelope (ok/data/error). transport.ts interprets it — error reconstruction
-// stays uniform across all three channels there. Waits for the socket to open
-// so a command issued during startup isn't dropped.
-export function sendLocalCommand(command, params) {
-    const requestId = `cmd_${nextRequestId++}`;
-    return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-            pendingCommands.delete(requestId);
-            reject(new Error(`Timed out waiting for command ${command}.`));
-        }, COMMAND_TIMEOUT_MS);
-        pendingCommands.set(requestId, (env) => {
-            clearTimeout(timeout);
-            pendingCommands.delete(requestId);
-            resolve(env);
-        });
-        waitForSocket()
-            .then((socket) => {
-            socket.send(JSON.stringify({
-                type: "castle_command",
-                castleSdk: CASTLE_SDK_PROTOCOL,
-                requestId,
-                command,
-                params,
-            }));
-        })
-            .catch((error) => {
-            clearTimeout(timeout);
-            pendingCommands.delete(requestId);
-            reject(error instanceof Error ? error : new Error(String(error)));
-        });
-    });
+// Send an SDK command to the dev server. Its stream envelopes and its response
+// go to `listener` as they arrive, and the listener is dropped after the
+// response. transport.ts interprets them, so error reconstruction stays uniform
+// across all three channels there. Waits for the socket to open so a command
+// issued during startup isn't dropped; rejects if it never opens.
+export async function sendLocalCommand(requestId, command, params, listener) {
+    localCommandListeners.set(requestId, listener);
+    try {
+        const socket = await waitForSocket();
+        // Cancelled or timed out while the socket was opening.
+        if (!localCommandListeners.has(requestId)) {
+            return;
+        }
+        socket.send(JSON.stringify({
+            type: "castle_command",
+            castleSdk: CASTLE_SDK_PROTOCOL,
+            requestId,
+            command,
+            params,
+        }));
+    }
+    catch (error) {
+        localCommandListeners.delete(requestId);
+        throw error;
+    }
+}
+// Ask the dev server to stop a streaming command, and stop listening for it.
+export function cancelLocalCommand(requestId) {
+    localCommandListeners.delete(requestId);
+    if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: "castle_command_cancel", castleSdk: CASTLE_SDK_PROTOCOL, requestId }));
+    }
+}
+// Stop listening for a command the deck has given up on.
+export function releaseLocalCommand(requestId) {
+    localCommandListeners.delete(requestId);
 }
 function waitForSocket() {
     if (ws && ws.readyState === WebSocket.OPEN)
@@ -374,10 +377,15 @@ function waitForSocket() {
         }, 100);
     });
 }
-function resolveLocalCommand(msg) {
-    const pending = pendingCommands.get(msg.requestId);
-    if (pending)
-        pending(msg);
+function deliverLocalCommand(msg) {
+    const listener = localCommandListeners.get(msg.requestId);
+    if (!listener) {
+        return;
+    }
+    if (!("stream" in msg)) {
+        localCommandListeners.delete(msg.requestId);
+    }
+    listener(msg);
 }
 function resolveLocalRequest(msg) {
     if (!msg.requestId)
@@ -919,7 +927,10 @@ function handleLocalMessage(msg) {
         resolveLocalRequest(msg);
     }
     else if (msg.type === "castle_command_response") {
-        resolveLocalCommand(msg);
+        deliverLocalCommand(msg);
+    }
+    else if (msg.type === "castle_command_stream") {
+        deliverLocalCommand(msg);
     }
 }
 // Files-changed listeners, registered by consumers (the kit engine, editors).

package/dist/server/storage.d.ts

@@ -102,17 +102,101 @@ export interface CompleteCharacterBeatInput {
     eventOccurrenceId: string;
     outcomeId: string;
 }
+export interface EvaluateCharacterInformationInput {
+    operationId: string;
+    maxDeliveries?: number;
+}
+export type CharacterStoryOpportunity = {
+    type: "approach" | "room_entry" | "world_action";
+    id: string;
+};
+export interface EvaluateCharacterBeatsInput {
+    operationId: string;
+    opportunityId: string;
+    opportunity: CharacterStoryOpportunity;
+    presentCharacterIds: string[];
+}
+export interface CharacterBeatSelection {
+    deliveryId: string;
+    beatId: string;
+    characterId: string;
+    openingText: string;
+}
+export interface CharacterBeatEvaluationResult {
+    operationId: string;
+    opportunityId: string;
+    opportunityCount: number;
+    gameTime: number | null;
+    selection: CharacterBeatSelection | null;
+}
+export type CharacterBeatEvaluationOperation = Omit<CharacterOperation, "result"> & {
+    result: CharacterBeatEvaluationResult | null;
+};
+export interface CompleteScheduledCharacterBeatInput {
+    operationId: string;
+    deliveryId: string;
+    outcomeId: string;
+}
+export interface CharacterScheduledBeatCompletionResult {
+    completionId: string;
+    deliveryId: string;
+    beatId: string;
+    characterId: string;
+    outcomeId: string;
+    completedAt: string;
+}
+export type CharacterScheduledBeatCompletionOperation = Omit<CharacterOperation, "result"> & {
+    result: CharacterScheduledBeatCompletionResult | null;
+};
+export interface CharacterInformationEvaluationResult {
+    generation: number;
+    evaluatedAt: string;
+    snapshotCandidateCount: number;
+    deliveries: Array<{
+        ruleId: string;
+        rootId: string;
+        recipientCharacterId: string;
+        status: "delivered" | "already_known";
+    }>;
+    cancelled: Array<{
+        ruleId: string;
+        rootId: string;
+    }>;
+    blocked: Array<{
+        ruleId: string;
+        rootId: string;
+        recipientCharacterId: string;
+        code: "testimony_backlog_full" | "information_limit" | "storage_capacity";
+    }>;
+    remainingCount: number;
+}
+export type CharacterInformationEvaluationOperation = Omit<CharacterOperation, "result"> & {
+    result: CharacterInformationEvaluationResult | null;
+};
+export interface SendCharacterInput {
+    operationId: string;
+    characterId: string;
+    input: string;
+    audience: {
+        listenerCharacterIds: string[];
+    };
+}
 /**
  * Narrative commands do not run a model. They record creator-validated events,
  * knowledge delivery and beat completion inside this immutable playthrough.
  */
 export interface ServerPlaythroughCharacters {
+    /** Queues a funded turn whose admitted listeners are fixed at enqueue time. */
+    send(input: SendCharacterInput): Promise<CharacterOperation>;
     recordEvent(input: RecordCharacterEventInput): Promise<CharacterOperation>;
     setGameState(input: SetCharacterGameStateInput): Promise<CharacterOperation>;
     shareClaim(input: ShareCharacterClaimInput): Promise<CharacterOperation>;
     inspect(): Promise<Json>;
     deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<CharacterOperation>;
     completeBeat(input: CompleteCharacterBeatInput): Promise<CharacterOperation>;
+    evaluateInformation(input: EvaluateCharacterInformationInput): Promise<CharacterInformationEvaluationOperation>;
+    evaluateBeats(input: EvaluateCharacterBeatsInput): Promise<CharacterBeatEvaluationOperation>;
+    completeScheduledBeat(input: CompleteScheduledCharacterBeatInput): Promise<CharacterScheduledBeatCompletionOperation>;
     status(operationId: string): Promise<CharacterOperation>;
     history(options?: ServerCharacterHistoryOptions): Promise<CharacterHistory>;
 }

package/dist/server/storage.js

@@ -84,6 +84,17 @@ export function createServerStorage(platformHandle) {
 }
 function createPlaythrough(call, subject, generation) {
     const characters = Object.freeze({
+        async send(input) {
+            const characterId = assertNarrativeId(input?.characterId, "characterId");
+            return call("characterSendWithAudience", {
+                subject,
+                generation,
+                operationId: assertOperationId(input?.operationId),
+                characterId,
+                input: assertCharacterInput(input?.input),
+                audience: assertCharacterAudience(input?.audience, characterId),
+            });
+        },
         async recordEvent(input) {
             return call("characterRecordEvent", {
                 subject,
@@ -139,6 +150,34 @@ function createPlaythrough(call, subject, generation) {
                 outcomeId: assertNarrativeId(input?.outcomeId, "outcomeId"),
             });
         },
+        async evaluateInformation(input) {
+            const maxDeliveries = assertInformationMaxDeliveries(input?.maxDeliveries);
+            return call("characterEvaluateInformation", {
+                subject,
+                generation,
+                operationId: assertOperationId(input?.operationId),
+                ...(maxDeliveries === undefined ? {} : { maxDeliveries }),
+            });
+        },
+        async evaluateBeats(input) {
+            return call("characterEvaluateBeats", {
+                subject,
+                generation,
+                operationId: assertOperationId(input?.operationId),
+                opportunityId: assertOpportunityId(input?.opportunityId),
+                opportunity: assertStoryOpportunity(input?.opportunity),
+                presentCharacterIds: assertPresentCharacterIds(input?.presentCharacterIds),
+            });
+        },
+        async completeScheduledBeat(input) {
+            return call("characterCompleteScheduledBeat", {
+                subject,
+                generation,
+                operationId: assertOperationId(input?.operationId),
+                deliveryId: assertOpportunityId(input?.deliveryId, "deliveryId"),
+                outcomeId: assertNarrativeId(input?.outcomeId, "outcomeId"),
+            });
+        },
         async status(operationId) {
             return call("characterStatus", {
                 subject,
@@ -323,6 +362,41 @@ function assertOperationId(value) {
     }
     return value;
 }
+function assertOpportunityId(value, field = "opportunityId") {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_OPERATION_ID_CHARACTERS ||
+        value.includes("\0") ||
+        hasUnpairedSurrogate(value) ||
+        utf8Length(value) > MAX_OPERATION_ID_BYTES) {
+        throw characterArgumentError(`${field} must be valid text of at most ${MAX_OPERATION_ID_CHARACTERS} characters and ${MAX_OPERATION_ID_BYTES} bytes.`);
+    }
+    return value;
+}
+function assertStoryOpportunity(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw characterArgumentError("opportunity must contain a type and id.");
+    }
+    const opportunity = value;
+    if (Object.keys(opportunity).some((key) => key !== "type" && key !== "id") ||
+        !["approach", "room_entry", "world_action"].includes(String(opportunity.type))) {
+        throw characterArgumentError("opportunity type is invalid.");
+    }
+    return {
+        type: opportunity.type,
+        id: assertNarrativeId(opportunity.id, "opportunity.id"),
+    };
+}
+function assertPresentCharacterIds(value) {
+    if (!Array.isArray(value) || value.length > 16) {
+        throw characterArgumentError("presentCharacterIds must contain at most 16 character ids.");
+    }
+    const ids = value.map((item) => assertNarrativeId(item, "presentCharacterIds"));
+    if (new Set(ids).size !== ids.length) {
+        throw characterArgumentError("presentCharacterIds must not contain duplicates.");
+    }
+    return ids.sort();
+}
 function assertNarrativeId(value, field) {
     if (typeof value !== "string" ||
         value.length === 0 ||
@@ -351,6 +425,33 @@ function assertNarrativeIds(value, field) {
     }
     return value.map((item) => assertNarrativeId(item, field));
 }
+function assertCharacterInput(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > 2000 ||
+        value.includes("\0") ||
+        hasUnpairedSurrogate(value)) {
+        throw characterArgumentError("input must be valid non-empty text of at most 2000 characters.");
+    }
+    return value;
+}
+function assertCharacterAudience(value, targetCharacterId) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw characterArgumentError("audience must contain listenerCharacterIds.");
+    }
+    const audience = value;
+    if (Object.keys(audience).some((key) => key !== "listenerCharacterIds") ||
+        !Array.isArray(audience.listenerCharacterIds) ||
+        audience.listenerCharacterIds.length > 3) {
+        throw characterArgumentError("audience must contain at most three listener character ids.");
+    }
+    const listenerCharacterIds = audience.listenerCharacterIds.map((id) => assertNarrativeId(id, "audience.listenerCharacterIds"));
+    if (new Set(listenerCharacterIds).size !== listenerCharacterIds.length ||
+        listenerCharacterIds.includes(targetCharacterId)) {
+        throw characterArgumentError("audience listeners must be unique and must not include the target character.");
+    }
+    return { listenerCharacterIds };
+}
 function assertKnowledgeSource(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw storageError("CAULDRON_CHARACTER_INVALID_ARGUMENT", "source must name creator_event or a character.", "session.storage.playthrough.characters.deliverKnowledge");
@@ -402,6 +503,14 @@ function assertStateRevision(value) {
     }
     return value;
 }
+function assertInformationMaxDeliveries(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 1 || value > 32) {
+        throw characterArgumentError("maxDeliveries must be an integer from 1 through 32.");
+    }
+    return value;
+}
 function assertStateChanges(value, hasObjectChanges = false) {
     if (!Array.isArray(value) || value.length > 32 || (!hasObjectChanges && value.length < 1)) {
         throw characterArgumentError(hasObjectChanges

package/dist/transport.d.ts

@@ -1,5 +1,9 @@
 import { type CommandName, type CommandParams, type CommandResult, type LifecycleEvent } from "./commands";
 type PostChannel = "mobile" | "web";
+export interface HostStreamOptions {
+    onStream?: (event: unknown) => void;
+    signal?: AbortSignal;
+}
 interface ReactNativeWebViewBridge {
     postMessage: (message: string) => void;
 }
@@ -11,7 +15,7 @@ declare global {
         };
     }
 }
-export declare function hostRequest<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResult[C]>;
+export declare function hostRequest<C extends CommandName>(command: C, params: CommandParams[C], stream?: HostStreamOptions): Promise<CommandResult[C]>;
 export declare function getCommandChannel(): PostChannel | "local";
 export declare function hostNotify(event: LifecycleEvent): void;
 export declare function postUnloadDone(unloadId: string, state?: string): void;

package/dist/transport.js

@@ -7,10 +7,14 @@
 //   - web     → window.parent.postMessage; responses via 'message' events
 //   - local   → the castle-web serve dev server, over runtime.ts's websocket
 // Error reconstruction is uniform here so callers always get a CastleError.
-import { CASTLE_SDK_PROTOCOL, isResponseEnvelope, unloadRequestId, } from "./commands";
+//
+// A streaming command (agent.chat) gets stream envelopes on its requestId before
+// its response. Each one goes to the caller's onStream and restarts the wait,
+// and the caller's AbortSignal sends the host a cancel envelope.
+import { CASTLE_SDK_PROTOCOL, COMMAND_TIMEOUTS_MS, STREAM_IDLE_TIMEOUT_MS, isResponseEnvelope, isStreamEnvelope, unloadRequestId, } from "./commands";
 import { getCastleEmbed } from "./context";
 import { CastleError } from "./errors";
-import { sendLocalCommand } from "./runtime";
+import { cancelLocalCommand, releaseLocalCommand, sendLocalCommand } from "./runtime";
 const REQUEST_TIMEOUT_MS = 15000;
 // Interactive platform commands hold the screen while the player interacts with
 // a host-native sheet (e.g. a pass purchase), so the flat data-command timeout
@@ -20,16 +24,16 @@ const INTERACTIVE_COMMANDS = new Set([
     "snapshot.offer",
     "portal.open",
 ]);
+// Request ids carry a per-page prefix so that a host serving several decks at
+// once can key a cancel by requestId alone.
+const requestIdPrefix = `csdk_${Math.random().toString(36).slice(2, 10)}_`;
 let nextRequestId = 1;
 const pending = new Map();
 let listenersInstalled = false;
 let unloadHandler = null;
-export async function hostRequest(command, params) {
+export async function hostRequest(command, params, stream = {}) {
     try {
-        const channel = resolveChannel();
-        const env = channel === "local"
-            ? await sendLocalCommand(command, params)
-            : await postCommand(channel, command, params);
+        const env = await sendCommand(resolveChannel(), command, params, stream);
         return interpretResponse(command, env);
     }
     catch (error) {
@@ -103,20 +107,84 @@ function resolveChannel() {
     // local dev server (top-level page served by `castle-web serve`).
     return window.parent && window.parent !== window ? "web" : "local";
 }
-function postCommand(channel, command, params) {
-    installHostListener();
-    const requestId = `csdk_${nextRequestId++}`;
+function sendCommand(channel, command, params, stream) {
+    const requestId = `${requestIdPrefix}${nextRequestId++}`;
     return new Promise((resolve, reject) => {
-        const timeout = INTERACTIVE_COMMANDS.has(command)
-            ? undefined
-            : setTimeout(() => {
-                pending.delete(requestId);
-                reject(new Error(`Castle host did not respond to ${command}.`));
-            }, REQUEST_TIMEOUT_MS);
-        pending.set(requestId, { resolve, reject, timeout });
+        if (stream.signal?.aborted) {
+            reject(cancelledError(command));
+            return;
+        }
+        const entry = { command, channel, resolve, reject, onStream: stream.onStream };
+        pending.set(requestId, entry);
+        restartTimeout(requestId, entry, COMMAND_TIMEOUTS_MS[command] ?? REQUEST_TIMEOUT_MS);
+        watchAbort(requestId, entry, stream.signal);
+        if (channel === "local") {
+            sendLocalCommand(requestId, command, params, receive).catch((error) => {
+                forget(requestId);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            });
+            return;
+        }
+        installHostListener();
         sendEnvelope(channel, { castleSdk: CASTLE_SDK_PROTOCOL, requestId, command, params });
     });
 }
+// Interactive commands have no timeout; they resolve only when the host replies.
+function restartTimeout(requestId, entry, ms) {
+    if (entry.timeout) {
+        clearTimeout(entry.timeout);
+    }
+    if (INTERACTIVE_COMMANDS.has(entry.command)) {
+        return;
+    }
+    entry.timeout = setTimeout(() => {
+        forget(requestId);
+        entry.reject(new Error(`Castle host did not respond to ${entry.command}.`));
+    }, ms);
+}
+function watchAbort(requestId, entry, signal) {
+    if (!signal) {
+        return;
+    }
+    const onAbort = () => {
+        forget(requestId);
+        if (entry.channel === "local") {
+            cancelLocalCommand(requestId);
+        }
+        else {
+            const envelope = {
+                castleSdk: CASTLE_SDK_PROTOCOL,
+                requestId,
+                cancel: true,
+            };
+            sendEnvelope(entry.channel, envelope);
+        }
+        entry.reject(cancelledError(entry.command));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    entry.stopWatchingAbort = () => signal.removeEventListener("abort", onAbort);
+}
+function forget(requestId) {
+    const entry = pending.get(requestId);
+    if (!entry) {
+        return;
+    }
+    pending.delete(requestId);
+    if (entry.timeout) {
+        clearTimeout(entry.timeout);
+    }
+    entry.stopWatchingAbort?.();
+    if (entry.channel === "local") {
+        releaseLocalCommand(requestId);
+    }
+}
+function cancelledError(command) {
+    return new CastleError({
+        code: "CANCELLED",
+        message: `${command} was cancelled.`,
+        operation: command,
+    });
+}
 function sendEnvelope(channel, envelope) {
     const json = JSON.stringify(envelope);
     if (channel === "mobile") {
@@ -146,21 +214,36 @@ function receive(message) {
         settle(message);
         return;
     }
+    if (isStreamEnvelope(message)) {
+        deliverStream(message.requestId, message.stream);
+        return;
+    }
     const unloadId = unloadRequestId(message);
     if (unloadId !== null)
         unloadHandler?.(unloadId);
 }
 function settle(message) {
-    if (!isResponseEnvelope(message))
-        return;
     const entry = pending.get(message.requestId);
-    if (!entry)
+    if (!entry) {
         return;
-    if (entry.timeout)
-        clearTimeout(entry.timeout);
-    pending.delete(message.requestId);
+    }
+    forget(message.requestId);
     entry.resolve(message);
 }
+// A throwing onStream is logged, and the stream goes on.
+function deliverStream(requestId, event) {
+    const entry = pending.get(requestId);
+    if (!entry) {
+        return;
+    }
+    restartTimeout(requestId, entry, STREAM_IDLE_TIMEOUT_MS);
+    try {
+        entry.onStream?.(event);
+    }
+    catch (error) {
+        console.error(`Castle ${entry.command} stream handler threw:`, error);
+    }
+}
 function interpretResponse(command, env) {
     if (env.ok)
         return env.data;

package/package.json

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