castle-web-sdk 0.4.34 → 0.4.36

package/dist/server/storage.js

@@ -159,6 +159,25 @@ function createPlaythrough(call, subject, generation) {
                 ...(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,
@@ -343,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 ||

package/dist/transport.d.ts

@@ -1,5 +1,9 @@
-import { type CommandName, type CommandParams, type CommandResult, type LifecycleEvent } from "./commands";
+import { type CommandName, type CommandParams, type CommandResult, type LifecycleEvent, type VoiceEvent } from "./commands";
 type PostChannel = "mobile" | "web";
+export interface HostStreamOptions {
+    onStream?: (event: unknown) => void;
+    signal?: AbortSignal;
+}
 interface ReactNativeWebViewBridge {
     postMessage: (message: string) => void;
 }
@@ -11,10 +15,11 @@ 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;
 export declare function setUnloadHandler(handler: (unloadId: string) => void): void;
+export declare function setVoiceEventHandler(handler: ((event: VoiceEvent) => void) | null): void;
 export declare function installHostListener(): void;
 export {};

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, voiceEventFrom, } 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
@@ -19,17 +23,20 @@ const INTERACTIVE_COMMANDS = new Set([
     "pass.offer",
     "snapshot.offer",
     "portal.open",
+    // The host's voice prompt and the browser's microphone permission.
+    "voice.requestJoin",
 ]);
+// 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) {
+let voiceEventHandler = null;
+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) {
@@ -89,6 +96,12 @@ export function postUnloadDone(unloadId, state) {
 export function setUnloadHandler(handler) {
     unloadHandler = handler;
 }
+// Registered by multiplayerVoice.ts, the same way, for host voice events.
+export function setVoiceEventHandler(handler) {
+    voiceEventHandler = handler;
+    if (handler)
+        installHostListener();
+}
 function resolveChannel() {
     if (typeof window === "undefined")
         return "local";
@@ -103,20 +116,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 +223,41 @@ function receive(message) {
         settle(message);
         return;
     }
+    if (isStreamEnvelope(message)) {
+        deliverStream(message.requestId, message.stream);
+        return;
+    }
+    const voiceEvent = voiceEventFrom(message);
+    if (voiceEvent) {
+        voiceEventHandler?.(voiceEvent);
+        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.34",
+  "version": "0.4.36",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"