castle-web-sdk 0.4.37 → 0.4.38

package/dist/multiplayer.d.ts

@@ -1,6 +1,7 @@
 import type { MultiplayerDestinationAudience, MultiplayerSoloReason } from "./commands";
 import { CastleError } from "./errors";
-import { type MultiplayerPlayer } from "./multiplayerProtocol";
+import type { Json } from "./types";
+import { type MultiplayerPlayer, type MultiplayerCharacterDisclosure, type MultiplayerCharacterTurnStatus } from "./multiplayerProtocol";
 import { type MultiplayerVoice } from "./multiplayerVoice";
 export type MultiplayerJoinOptions = {
     mode: "named";
@@ -39,6 +40,63 @@ export interface MultiplayerRoster {
     players: MultiplayerPlayer[];
     you: MultiplayerPlayer | null;
 }
+export interface MultiplayerCharacterAudience {
+    disclosure?: MultiplayerCharacterDisclosure;
+    playerIds?: string[];
+    characterIds?: string[];
+}
+export interface MultiplayerCharacterTurnRequest {
+    requestId: string;
+    operationId: string;
+    characterId: string;
+    input: string;
+    audience?: MultiplayerCharacterAudience;
+}
+export interface MultiplayerCharacterTurnAdmission {
+    operationId: string;
+    status: "queued" | "completed" | "interrupted";
+    replayed: boolean;
+}
+export interface MultiplayerCharacterTurnStatusResult {
+    operationId: string;
+    status: MultiplayerCharacterTurnStatus;
+    jobStatus: MultiplayerCharacterTurnStatus;
+    turnStatus: "admitted" | "reply_committed" | "completed" | "interrupted";
+    response?: string;
+    progress?: {
+        response: string;
+    };
+    replayed: boolean;
+}
+export type MultiplayerWorldCharacterCommand = {
+    type: "perform_action";
+    characterId: string;
+    actionId: string;
+    parameters?: Json;
+    consentQuote?: string;
+} | {
+    type: "record_event";
+    eventTypeId: string;
+    data?: Json;
+};
+export type MultiplayerWorldCharacterQuery = {
+    type: "inspect";
+} | {
+    type: "status";
+    operationId: string;
+} | {
+    type: "history";
+    characterId?: string;
+    limit?: number;
+    cursor?: string;
+};
+export interface MultiplayerWorldCharacterCommandResult {
+    operationId: string;
+    status: "applied" | "ineligible";
+    replayed: boolean;
+    result: unknown;
+    worldRevision: string;
+}
 export interface MultiplayerConnection {
     readonly state: MultiplayerConnectionState;
     readonly playerId: string;
@@ -51,6 +109,19 @@ export interface MultiplayerConnection {
     readonly soloReason: MultiplayerSoloReason | null;
     /** Sends byte payloads as binary frames and all other payloads as JSON. */
     send(data: unknown): void;
+    /** Requests one billed character turn through this authenticated world socket. */
+    requestCharacterTurn(request: MultiplayerCharacterTurnRequest): Promise<MultiplayerCharacterTurnAdmission>;
+    /** Recovers the durable status of a prior operation after reconnecting. */
+    getCharacterTurnStatus(operationId: string): Promise<MultiplayerCharacterTurnStatusResult>;
+    requestCharacterCommand(request: {
+        requestId: string;
+        operationId: string;
+        command: MultiplayerWorldCharacterCommand;
+    }): Promise<MultiplayerWorldCharacterCommandResult>;
+    readCharacters<T = unknown>(request: {
+        requestId: string;
+        query: MultiplayerWorldCharacterQuery;
+    }): Promise<T>;
     /** Receives binary payloads as Uint8Array values and JSON payloads otherwise. */
     onMessage(callback: (data: unknown) => void): () => void;
     onRoster(callback: (roster: MultiplayerRoster) => void): () => void;

package/dist/multiplayer.js

@@ -7,6 +7,14 @@ const HELLO_TIMEOUT_MS = 10_000;
 const RECONNECT_BUDGET_MS = 30_000;
 const RECONNECT_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000];
 const INVALID_DEV_RECONNECT_CLOSE_CODE = 4003;
+// The host may spend the full 15-second grant window waiting for author admission,
+// then up to 10 seconds on the fenced control-plane request. Keep the client above
+// that complete lifecycle so it cannot discard a valid durable receipt.
+const CHARACTER_ADMISSION_TIMEOUT_MS = 30_000;
+const WORLD_CHARACTER_OPERATION_ID_MAX_CHARACTERS = 120;
+const WORLD_CHARACTER_ID_MAX_CHARACTERS = 100;
+const WORLD_CHARACTER_INPUT_MAX_CHARACTERS = 2000;
+let nextCharacterStatusRequestId = 1;
 let activeConnection = null;
 let latestJoinAttempt = 0;
 let pendingDestinationJoin = null;
@@ -112,6 +120,8 @@ class MultiplayerConnectionImpl {
     reAcquisitionUsed = false;
     recovering = false;
     roster = null;
+    sharedCharactersSupported = false;
+    pendingCharacterRequests = new Map();
     messages = new Set();
     rosters = new Set();
     states = new Set();
@@ -173,6 +183,60 @@ class MultiplayerConnectionImpl {
             return;
         this.socket.send(payload);
     }
+    requestCharacterTurn(request) {
+        const normalized = normalizeCharacterTurnRequest(request, this.currentPlayerId);
+        return this.sendCharacterRequest(normalized.requestId, normalized.operationId, "admission", JSON.stringify({ t: "worldCharacterTurn", ...normalized }));
+    }
+    getCharacterTurnStatus(operationId) {
+        const normalizedOperationId = boundedCharacterText(operationId, 128, "operationId", WORLD_CHARACTER_OPERATION_ID_MAX_CHARACTERS);
+        const requestId = `status-${Date.now().toString(36)}-${nextCharacterStatusRequestId++}`;
+        return this.sendCharacterRequest(requestId, normalizedOperationId, "status", JSON.stringify({
+            t: "worldCharacterStatus",
+            requestId,
+            operationId: normalizedOperationId,
+        }));
+    }
+    requestCharacterCommand(request) {
+        const normalized = normalizeWorldCharacterCommandRequest(request);
+        return this.sendCharacterRequest(normalized.requestId, normalized.operationId, "command", JSON.stringify({ t: "worldCharacterCommand", ...normalized }));
+    }
+    readCharacters(request) {
+        const normalized = normalizeWorldCharacterReadRequest(request);
+        return this.sendCharacterRequest(normalized.requestId, "", "read", JSON.stringify({ t: "worldCharacterRead", ...normalized }));
+    }
+    sendCharacterRequest(requestId, operationId, kind, frame) {
+        this.assertOpen();
+        if (!this.sharedCharactersSupported) {
+            return Promise.reject(characterError("CAULDRON_CHARACTER_UNAVAILABLE", "This multiplayer session does not support shared characters."));
+        }
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+            return Promise.reject(characterError("MULTIPLAYER_NOT_CONNECTED", "Shared character requests require a connected session."));
+        }
+        if (this.pendingCharacterRequests.has(requestId)) {
+            return Promise.reject(characterError("CAULDRON_CHARACTER_CONFLICT", "A shared character request with this requestId is already pending."));
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingCharacterRequests.delete(requestId);
+                reject(characterError("CAULDRON_CHARACTER_TIMEOUT", "Shared character admission timed out. Retry with the same operationId."));
+            }, CHARACTER_ADMISSION_TIMEOUT_MS);
+            this.pendingCharacterRequests.set(requestId, {
+                operationId,
+                kind,
+                resolve: (value) => resolve(value),
+                reject,
+                timer,
+            });
+            try {
+                this.socket.send(frame);
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.pendingCharacterRequests.delete(requestId);
+                reject(asCastleError(error));
+            }
+        });
+    }
     onMessage(callback) {
         this.messages.add(callback);
         return () => this.messages.delete(callback);
@@ -341,6 +405,7 @@ class MultiplayerConnectionImpl {
         this.currentPlayerId = frame.playerId;
         this.currentSessionId = frame.sessionId;
         this.reconnectToken = frame.reconnectToken;
+        this.sharedCharactersSupported = frame.capabilities?.sharedCharactersV1 === true;
         if (this.devReconnectStorageKey)
             writeDevReconnectToken(this.devReconnectStorageKey, frame.reconnectToken);
         // Re-acquisition is limited to one per outage, not one per session. A phone
@@ -360,6 +425,9 @@ class MultiplayerConnectionImpl {
                 for (const callback of this.messages)
                     callListener(callback, frame.d);
                 break;
+            case "worldCharacterResult":
+                this.acceptWorldCharacterResult(frame);
+                break;
             case "replaced":
                 this.finish({ type: "replaced" });
                 break;
@@ -398,6 +466,7 @@ class MultiplayerConnectionImpl {
         if (this.recovering || this.currentState === "closed")
             return;
         this.recovering = true;
+        this.rejectPendingCharacterRequests("MULTIPLAYER_CONNECTION_LOST", "The connection was lost before shared character admission completed.");
         this.transition("reconnecting", { type: "connectionLost" });
         void this.recover()
             .catch((error) => {
@@ -484,6 +553,7 @@ class MultiplayerConnectionImpl {
             (metadata.type === "left" || metadata.type === "bye" || metadata.type === "replaced"))
             clearDevReconnectToken(this.devReconnectStorageKey, this.reconnectToken);
         this.stopKeepalive();
+        this.rejectPendingCharacterRequests("MULTIPLAYER_CONNECTION_CLOSED", "The multiplayer connection closed before the shared character request completed.");
         const socket = this.socket;
         this.socket = null;
         this.socketAttempt += 1;
@@ -499,6 +569,68 @@ class MultiplayerConnectionImpl {
             throw multiplayerError("MULTIPLAYER_CONNECTION_CLOSED", "The multiplayer connection is closed.");
         }
     }
+    acceptWorldCharacterResult(frame) {
+        const pending = this.pendingCharacterRequests.get(frame.requestId);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.pendingCharacterRequests.delete(frame.requestId);
+        if (!frame.ok) {
+            pending.reject(characterError(frame.error?.code ?? "CAULDRON_CHARACTER_UNAVAILABLE", frame.error?.message ?? "Shared character admission failed."));
+            return;
+        }
+        if (pending.kind === "command" || pending.kind === "read") {
+            if (pending.kind === "command" && frame.operationId !== pending.operationId) {
+                pending.reject(characterError("CAULDRON_CHARACTER_UNAVAILABLE", "The host returned an invalid command receipt."));
+                return;
+            }
+            pending.resolve(frame.value);
+            return;
+        }
+        if (frame.operationId !== pending.operationId || typeof frame.replayed !== "boolean") {
+            pending.reject(characterError("CAULDRON_CHARACTER_UNAVAILABLE", "The host returned an invalid shared character receipt."));
+            return;
+        }
+        if (pending.kind === "admission") {
+            if (frame.status !== "queued" && frame.status !== "completed" && frame.status !== "interrupted") {
+                pending.reject(characterError("CAULDRON_CHARACTER_UNAVAILABLE", "The host returned an invalid admission status."));
+                return;
+            }
+            pending.resolve({ operationId: frame.operationId, status: frame.status, replayed: frame.replayed });
+            return;
+        }
+        if (!frame.status ||
+            !["queued", "running", "completed", "interrupted"].includes(frame.status) ||
+            !frame.jobStatus ||
+            !["queued", "running", "completed", "interrupted"].includes(frame.jobStatus) ||
+            !frame.turnStatus ||
+            !["admitted", "reply_committed", "completed", "interrupted"].includes(frame.turnStatus) ||
+            (frame.response !== undefined && typeof frame.response !== "string") ||
+            (frame.progress !== undefined &&
+                (!isRecord(frame.progress) || typeof frame.progress.response !== "string")) ||
+            (frame.response !== undefined && frame.progress !== undefined)) {
+            pending.reject(characterError("CAULDRON_CHARACTER_UNAVAILABLE", "The host returned an invalid character status."));
+            return;
+        }
+        pending.resolve({
+            operationId: frame.operationId,
+            status: frame.status,
+            jobStatus: frame.jobStatus,
+            turnStatus: frame.turnStatus,
+            ...(frame.response === undefined ? {} : { response: frame.response }),
+            ...(frame.progress === undefined
+                ? {}
+                : { progress: { response: frame.progress.response } }),
+            replayed: frame.replayed,
+        });
+    }
+    rejectPendingCharacterRequests(code, message) {
+        for (const pending of this.pendingCharacterRequests.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(characterError(code, message));
+        }
+        this.pendingCharacterRequests.clear();
+    }
 }
 class SocketClosedError extends Error {
     code;
@@ -581,6 +713,128 @@ function isValidUnicode(value) {
 function invalidJoinOptions() {
     return multiplayerError("INVALID_ARGUMENT", "Multiplayer.join requires named, party, or public options.");
 }
+function normalizeCharacterTurnRequest(request, speakerPlayerId) {
+    if (!request || typeof request !== "object") {
+        throw characterError("INVALID_ARGUMENT", "requestCharacterTurn requires a request object.");
+    }
+    const requestId = boundedCharacterText(request.requestId, 128, "requestId");
+    const operationId = boundedCharacterText(request.operationId, 128, "operationId", WORLD_CHARACTER_OPERATION_ID_MAX_CHARACTERS);
+    const characterId = boundedCharacterText(request.characterId, 128, "characterId", WORLD_CHARACTER_ID_MAX_CHARACTERS);
+    const input = boundedCharacterText(request.input, 8000, "input", WORLD_CHARACTER_INPUT_MAX_CHARACTERS);
+    const disclosure = request.audience?.disclosure ?? "participants";
+    if (disclosure !== "participants" && disclosure !== "world") {
+        throw characterError("INVALID_ARGUMENT", "audience.disclosure must be participants or world.");
+    }
+    const playerIds = boundedCharacterIds(request.audience?.playerIds ?? [], 7, "audience.playerIds");
+    const characterIds = boundedCharacterIds(request.audience?.characterIds ?? [], 3, "audience.characterIds", WORLD_CHARACTER_ID_MAX_CHARACTERS);
+    if (playerIds.includes(speakerPlayerId) || characterIds.includes(characterId)) {
+        throw characterError("INVALID_ARGUMENT", "The speaker and target character are implicit audience members.");
+    }
+    return {
+        requestId,
+        operationId,
+        characterId,
+        input,
+        audience: { disclosure, playerIds, characterIds },
+    };
+}
+function normalizeWorldCharacterCommandRequest(request) {
+    if (!request || typeof request !== "object" || !request.command || typeof request.command !== "object") {
+        throw characterError("INVALID_ARGUMENT", "requestCharacterCommand requires a command request.");
+    }
+    const requestId = boundedCharacterText(request.requestId, 128, "requestId");
+    const operationId = boundedCharacterText(request.operationId, 128, "operationId", WORLD_CHARACTER_OPERATION_ID_MAX_CHARACTERS);
+    const command = request.command;
+    if (command.type === "perform_action") {
+        return {
+            requestId,
+            operationId,
+            command: {
+                type: "perform_action",
+                characterId: boundedCharacterText(command.characterId, 128, "command.characterId", WORLD_CHARACTER_ID_MAX_CHARACTERS),
+                actionId: boundedCharacterText(command.actionId, 128, "command.actionId", WORLD_CHARACTER_ID_MAX_CHARACTERS),
+                ...(command.parameters === undefined ? {} : { parameters: normalizeJson(command.parameters, "command.parameters") }),
+                ...(command.consentQuote === undefined ? {} : {
+                    consentQuote: boundedCharacterText(command.consentQuote, 2 * 1024, "command.consentQuote"),
+                }),
+            },
+        };
+    }
+    if (command.type === "record_event") {
+        return {
+            requestId,
+            operationId,
+            command: {
+                type: "record_event",
+                eventTypeId: boundedCharacterText(command.eventTypeId, 128, "command.eventTypeId", WORLD_CHARACTER_ID_MAX_CHARACTERS),
+                ...(command.data === undefined ? {} : { data: normalizeJson(command.data, "command.data") }),
+            },
+        };
+    }
+    throw characterError("INVALID_ARGUMENT", "Unknown shared character command type.");
+}
+function normalizeWorldCharacterReadRequest(request) {
+    if (!request || typeof request !== "object" || !request.query || typeof request.query !== "object") {
+        throw characterError("INVALID_ARGUMENT", "readCharacters requires a query request.");
+    }
+    const requestId = boundedCharacterText(request.requestId, 128, "requestId");
+    const query = request.query;
+    if (query.type === "inspect")
+        return { requestId, query: { type: "inspect" } };
+    if (query.type === "status") {
+        return { requestId, query: { type: "status", operationId: boundedCharacterText(query.operationId, 128, "character query operationId", WORLD_CHARACTER_OPERATION_ID_MAX_CHARACTERS) } };
+    }
+    if (query.type === "history") {
+        if (query.limit !== undefined && (!Number.isInteger(query.limit) || query.limit < 1 || query.limit > 50)) {
+            throw characterError("INVALID_ARGUMENT", "Character query limit must be an integer from 1 through 50.");
+        }
+        return {
+            requestId,
+            query: {
+                type: "history",
+                ...(query.characterId === undefined ? {} : { characterId: boundedCharacterText(query.characterId, 128, "character query characterId", WORLD_CHARACTER_ID_MAX_CHARACTERS) }),
+                ...(query.limit === undefined ? {} : { limit: query.limit }),
+                ...(query.cursor === undefined ? {} : { cursor: boundedCharacterText(query.cursor, 128, "character query cursor", 128) }),
+            },
+        };
+    }
+    throw characterError("INVALID_ARGUMENT", "Unknown shared character query type.");
+}
+function normalizeJson(value, field) {
+    try {
+        const text = JSON.stringify(value);
+        if (text === undefined)
+            throw new Error("not JSON");
+        return JSON.parse(text);
+    }
+    catch {
+        throw characterError("INVALID_ARGUMENT", `${field} must be JSON-serializable.`);
+    }
+}
+function boundedCharacterIds(value, maxItems, field, maxCharacters = 128) {
+    if (!Array.isArray(value) || value.length > maxItems) {
+        throw characterError("INVALID_ARGUMENT", `${field} may contain at most ${maxItems} ids.`);
+    }
+    const ids = value.map((item) => boundedCharacterText(item, 128, field, maxCharacters));
+    if (new Set(ids).size !== ids.length) {
+        throw characterError("INVALID_ARGUMENT", `${field} may not contain duplicate ids.`);
+    }
+    return ids;
+}
+function boundedCharacterText(value, maxBytes, field, maxCharacters = maxBytes) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > maxCharacters ||
+        value.includes("\0") ||
+        !isValidUnicode(value) ||
+        new TextEncoder().encode(value).byteLength > maxBytes) {
+        throw characterError("INVALID_ARGUMENT", `${field} must be non-empty valid text of at most ${maxCharacters} characters and ${maxBytes} bytes.`);
+    }
+    return value;
+}
+function characterError(code, message) {
+    return new CastleError({ code, message, operation: "Multiplayer.sharedCharacters" });
+}
 function serializeClientMessage(data) {
     let text;
     try {
@@ -663,6 +917,8 @@ function parsePlatformFrame(value) {
             return Object.prototype.hasOwnProperty.call(frame, "d")
                 ? frame
                 : null;
+        case "worldCharacterResult":
+            return isWorldCharacterResultFrame(frame) ? frame : null;
         case "replaced":
         case "pong":
             return frame;
@@ -678,7 +934,19 @@ function isHelloFrame(frame) {
     return (typeof frame.playerId === "string" &&
         typeof frame.reconnectToken === "string" &&
         typeof frame.sessionId === "string" &&
-        isMode(frame.mode));
+        isMode(frame.mode) &&
+        (frame.capabilities === undefined ||
+            (isRecord(frame.capabilities) &&
+                (frame.capabilities.sharedCharactersV1 === undefined ||
+                    typeof frame.capabilities.sharedCharactersV1 === "boolean"))));
+}
+function isWorldCharacterResultFrame(frame) {
+    return (typeof frame.requestId === "string" &&
+        typeof frame.ok === "boolean" &&
+        (frame.ok === true ||
+            (isRecord(frame.error) &&
+                typeof frame.error.code === "string" &&
+                typeof frame.error.message === "string")));
 }
 function isRosterFrame(frame) {
     return Array.isArray(frame.players) && frame.players.every(isPlayer);

package/dist/multiplayerProtocol.d.ts

@@ -19,6 +19,9 @@ export interface ClientHelloFrame {
     reconnectToken: string;
     sessionId: string;
     mode: SessionType;
+    capabilities?: {
+        sharedCharactersV1?: boolean;
+    };
 }
 export interface ClientRosterFrame {
     t: "roster";
@@ -38,7 +41,28 @@ export interface ClientByeFrame {
 export interface ClientPongFrame {
     t: "pong";
 }
-export type PlatformToClientFrame = ClientHelloFrame | ClientRosterFrame | ClientMessageFrame | ClientReplacedFrame | ClientByeFrame | ClientPongFrame;
+export type MultiplayerCharacterDisclosure = "participants" | "world";
+export type MultiplayerCharacterTurnStatus = "queued" | "running" | "completed" | "interrupted";
+export interface ClientWorldCharacterResultFrame {
+    t: "worldCharacterResult";
+    requestId: string;
+    ok: boolean;
+    operationId?: string;
+    status?: MultiplayerCharacterTurnStatus;
+    jobStatus?: MultiplayerCharacterTurnStatus;
+    turnStatus?: "admitted" | "reply_committed" | "completed" | "interrupted";
+    response?: string;
+    progress?: {
+        response: string;
+    };
+    replayed?: boolean;
+    value?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export type PlatformToClientFrame = ClientHelloFrame | ClientRosterFrame | ClientMessageFrame | ClientReplacedFrame | ClientByeFrame | ClientWorldCharacterResultFrame | ClientPongFrame;
 export interface ClientToPlatformMessageFrame {
     t: "m";
     d: unknown;
@@ -46,7 +70,35 @@ export interface ClientToPlatformMessageFrame {
 export interface ClientPingFrame {
     t: "ping";
 }
-export type ClientToPlatformFrame = ClientToPlatformMessageFrame | ClientPingFrame;
+export interface ClientWorldCharacterTurnFrame {
+    t: "worldCharacterTurn";
+    requestId: string;
+    operationId: string;
+    characterId: string;
+    input: string;
+    audience: {
+        disclosure: MultiplayerCharacterDisclosure;
+        playerIds: string[];
+        characterIds: string[];
+    };
+}
+export interface ClientWorldCharacterStatusFrame {
+    t: "worldCharacterStatus";
+    requestId: string;
+    operationId: string;
+}
+export interface ClientWorldCharacterCommandFrame {
+    t: "worldCharacterCommand";
+    requestId: string;
+    operationId: string;
+    command: unknown;
+}
+export interface ClientWorldCharacterReadFrame {
+    t: "worldCharacterRead";
+    requestId: string;
+    query: unknown;
+}
+export type ClientToPlatformFrame = ClientToPlatformMessageFrame | ClientWorldCharacterTurnFrame | ClientWorldCharacterStatusFrame | ClientWorldCharacterCommandFrame | ClientWorldCharacterReadFrame | ClientPingFrame;
 export type MultiplayerMode = SessionType;
 export type MultiplayerPlayer = SessionPlayer;
 export type MultiplayerHelloFrame = ClientHelloFrame;

package/dist/server/platformHandle.d.ts

@@ -34,6 +34,9 @@ export interface PlatformHandle {
     on(event: "binaryMessage", callback: (connId: string, bytes: Uint8Array) => unknown): void;
     on(event: "replaced", callback: () => unknown): void;
     on(event: "shutdown", callback: (reason?: string) => unknown): void;
+    on(event: "worldCharacterTurn", callback: (request: PlatformWorldCharacterTurn) => unknown): void;
+    on(event: "worldCharacterCommand", callback: (request: PlatformWorldCharacterCommand) => unknown): void;
+    on(event: "worldCharacterRead", callback: (request: PlatformWorldCharacterRead) => unknown): void;
     /**
      * Deck storage. Strings in and strings out, like the rest of this handle, so a
      * runtime other than the Node shim can implement it without knowing what storage is.
@@ -47,5 +50,43 @@ export interface PlatformHandle {
     /** Persistent-world checkpoint broker. The host stamps the hidden world binding. */
     worldCheckpointRead?(): Promise<string>;
     worldCheckpointCommit?(argsJson: string): Promise<string>;
+    worldCharacterSend?(grantId: string): Promise<string>;
+    worldCharacterCommand?(grantId: string): Promise<string>;
+    worldCharacterRead?(grantId: string): Promise<string>;
+    worldCharacterReject?(grantId: string, code?: string): void;
     readonly config: PlatformSessionConfig;
 }
+export interface PlatformWorldCharacterCommand {
+    grantId: string;
+    requestId: string;
+    operationId: string;
+    speaker: PlayerIdentity & {
+        playerId: string;
+    };
+    command: unknown;
+}
+export interface PlatformWorldCharacterRead {
+    grantId: string;
+    requestId: string;
+    speaker: PlayerIdentity & {
+        playerId: string;
+    };
+    query: unknown;
+}
+export interface PlatformWorldCharacterTurn {
+    grantId: string;
+    requestId: string;
+    operationId: string;
+    speaker: PlayerIdentity & {
+        playerId: string;
+    };
+    characterId: string;
+    input: string;
+    audience: {
+        disclosure: "participants" | "world";
+        players: Array<PlayerIdentity & {
+            playerId: string;
+        }>;
+        characterIds: string[];
+    };
+}

package/dist/server/wrapper.d.ts

@@ -52,6 +52,52 @@ export interface MultiplayerServerWorld {
     read(): Promise<MultiplayerWorldSnapshot>;
     /** Commits exactly against expectedRevision; conflicts never partially write. */
     commit(input: MultiplayerWorldCommitInput): Promise<MultiplayerWorldCommitReceipt>;
+    readonly characters: MultiplayerServerWorldCharacters;
+}
+export interface MultiplayerServerWorldCharacters {
+    publicInspect<T = unknown>(): Promise<T>;
+    publicRelay(input: {
+        operationId: string;
+        sourceId: string;
+        transmittingCharacterId: string;
+        recipientCharacterIds: string[];
+    }): Promise<unknown>;
+}
+export interface MultiplayerWorldCharacterCommandRequest {
+    readonly requestId: string;
+    readonly operationId: string;
+    readonly speaker: MultiplayerServerPlayer;
+    readonly command: Readonly<Record<string, unknown>>;
+    apply(): Promise<unknown>;
+    reject(code?: string): void;
+}
+export interface MultiplayerWorldCharacterReadRequest {
+    readonly requestId: string;
+    readonly speaker: MultiplayerServerPlayer;
+    readonly query: Readonly<Record<string, unknown>>;
+    read<T = unknown>(): Promise<T>;
+    reject(code?: string): void;
+}
+export interface MultiplayerWorldCharacterAdmission {
+    operationId: string;
+    status: "queued" | "completed" | "interrupted";
+    replayed: boolean;
+}
+export interface MultiplayerWorldCharacterTurn {
+    readonly requestId: string;
+    readonly operationId: string;
+    readonly speaker: MultiplayerServerPlayer;
+    readonly characterId: string;
+    readonly input: string;
+    readonly audience: {
+        readonly disclosure: "participants" | "world";
+        readonly players: readonly MultiplayerServerPlayer[];
+        readonly characterIds: readonly string[];
+    };
+    /** Durably admits the exact host-authorized request. No arguments can broaden it. */
+    send(): Promise<MultiplayerWorldCharacterAdmission>;
+    /** Explicitly rejects the request before admission. */
+    reject(code?: string): void;
 }
 type CallbackResult = unknown;
 export interface MultiplayerServerCallbacks {
@@ -60,6 +106,9 @@ export interface MultiplayerServerCallbacks {
     onPlayerLeave?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
     /** Receives binary messages as Uint8Array values and JSON messages otherwise. */
     onMessage?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, data: unknown) => CallbackResult;
+    onWorldCharacterTurn?: (session: MultiplayerServerSession, turn: MultiplayerWorldCharacterTurn) => CallbackResult;
+    onWorldCharacterCommand?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterCommandRequest) => CallbackResult;
+    onWorldCharacterRead?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterReadRequest) => CallbackResult;
     onTick?: (session: MultiplayerServerSession) => CallbackResult;
     onReplaced?: (session: MultiplayerServerSession) => CallbackResult;
     /**

package/dist/server/wrapper.js

@@ -43,6 +43,109 @@ async function bootSession(platformHandle, callbacks) {
     catch {
         // Older shims may reject event names they do not recognize.
     }
+    if (callbacks.onWorldCharacterTurn &&
+        typeof platformHandle.worldCharacterSend === "function" &&
+        typeof platformHandle.worldCharacterReject === "function") {
+        platformHandle.on("worldCharacterTurn", async (raw) => {
+            const request = assertPlatformWorldCharacterTurn(raw);
+            let settled = false;
+            const turn = Object.freeze({
+                requestId: request.requestId,
+                operationId: request.operationId,
+                speaker: Object.freeze({ ...request.speaker }),
+                characterId: request.characterId,
+                input: request.input,
+                audience: Object.freeze({
+                    disclosure: request.audience.disclosure,
+                    players: Object.freeze(request.audience.players.map((player) => Object.freeze({ ...player }))),
+                    characterIds: Object.freeze([...request.audience.characterIds]),
+                }),
+                async send() {
+                    if (settled)
+                        throw new TypeError("This shared character request is already settled.");
+                    settled = true;
+                    const rawReceipt = await platformHandle.worldCharacterSend(request.grantId);
+                    return parseWorldCharacterAdmission(rawReceipt, request.operationId);
+                },
+                reject(code) {
+                    if (settled)
+                        return;
+                    settled = true;
+                    platformHandle.worldCharacterReject(request.grantId, code);
+                },
+            });
+            try {
+                await callbacks.onWorldCharacterTurn(session, turn);
+            }
+            finally {
+                if (!settled)
+                    turn.reject();
+            }
+        });
+    }
+    if (callbacks.onWorldCharacterCommand &&
+        hasWorldCharacterPlatform(platformHandle, "worldCharacterCommand")) {
+        platformHandle.on("worldCharacterCommand", async (raw) => {
+            const request = assertPlatformWorldCharacterCommand(raw);
+            let settled = false;
+            const command = Object.freeze({
+                requestId: request.requestId,
+                operationId: request.operationId,
+                speaker: Object.freeze({ ...request.speaker }),
+                command: deepFreezeJsonObject(request.command),
+                async apply() {
+                    if (settled)
+                        throw new TypeError("This shared character command is already settled.");
+                    settled = true;
+                    return parseSharedCharacterJson(await platformHandle.worldCharacterCommand(request.grantId));
+                },
+                reject(code) {
+                    if (settled)
+                        return;
+                    settled = true;
+                    platformHandle.worldCharacterReject(request.grantId, code);
+                },
+            });
+            try {
+                await callbacks.onWorldCharacterCommand(session, command);
+            }
+            finally {
+                if (!settled)
+                    command.reject();
+            }
+        });
+    }
+    if (callbacks.onWorldCharacterRead &&
+        hasWorldCharacterPlatform(platformHandle, "worldCharacterRead")) {
+        platformHandle.on("worldCharacterRead", async (raw) => {
+            const request = assertPlatformWorldCharacterRead(raw);
+            let settled = false;
+            const read = Object.freeze({
+                requestId: request.requestId,
+                speaker: Object.freeze({ ...request.speaker }),
+                query: deepFreezeJsonObject(request.query),
+                async read() {
+                    if (settled)
+                        throw new TypeError("This shared character read is already settled.");
+                    settled = true;
+                    return parseSharedCharacterJson(await platformHandle.worldCharacterRead(request.grantId));
+                },
+                reject(code) {
+                    if (settled)
+                        return;
+                    settled = true;
+                    platformHandle.worldCharacterReject(request.grantId, code);
+                },
+            });
+            try {
+                await callbacks.onWorldCharacterRead(session, read);
+            }
+            finally {
+                if (!settled)
+                    read.reject();
+            }
+        });
+    }
     platformHandle.on("replaced", async () => {
         await callbacks.onReplaced?.(session);
     });
@@ -121,6 +224,7 @@ function createServerWorld(platformHandle) {
     const initial = parseWorldSnapshot(platformHandle.config.world, "read");
     return Object.freeze({
         snapshot: initial,
+        characters: createServerWorldCharacters(platformHandle),
         async read() {
             const result = await platformHandle.worldCheckpointRead();
             return parseWorldSnapshot(parsePlatformJson(result, "read"), "read");
@@ -146,6 +250,38 @@ function createServerWorld(platformHandle) {
         },
     });
 }
+function createServerWorldCharacters(platformHandle) {
+    return Object.freeze({
+        async publicInspect() {
+            if (typeof platformHandle.storage !== "function") {
+                throw new TypeError("The shared character broker is unavailable.");
+            }
+            return parseSharedCharacterJson(await platformHandle.storage("worldCharacterPublicInspect", "{}"));
+        },
+        async publicRelay(input) {
+            if (typeof platformHandle.storage !== "function") {
+                throw new TypeError("The shared character broker is unavailable.");
+            }
+            const operationId = assertWorldOperationId(input?.operationId);
+            const sourceId = assertWorldCharacterId(input?.sourceId, "sourceId", 128);
+            const transmittingCharacterId = assertWorldCharacterId(input?.transmittingCharacterId, "transmittingCharacterId");
+            if (!Array.isArray(input?.recipientCharacterIds) ||
+                input.recipientCharacterIds.length > 3) {
+                throw new TypeError("session.world.characters.publicRelay: recipientCharacterIds may contain at most 3 ids.");
+            }
+            const recipientCharacterIds = input.recipientCharacterIds.map((id) => assertWorldCharacterId(id, "recipientCharacterIds"));
+            if (new Set(recipientCharacterIds).size !== recipientCharacterIds.length) {
+                throw new TypeError("session.world.characters.publicRelay: recipientCharacterIds may not contain duplicates.");
+            }
+            return parseSharedCharacterJson(await platformHandle.storage("worldCharacterPublicRelay", JSON.stringify({
+                operationId,
+                sourceId,
+                transmittingCharacterId,
+                recipientCharacterIds: recipientCharacterIds.sort(),
+            })));
+        },
+    });
+}
 function parseWorldSnapshot(value, operation) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw worldError("The platform returned an invalid world checkpoint.", "read");
@@ -158,6 +294,112 @@ function parseWorldSnapshot(value, operation) {
             : assertWorldCheckpoint(raw.checkpoint, operation),
     });
 }
+function assertPlatformWorldCharacterTurn(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.grantId !== "string" ||
+        typeof value.requestId !== "string" ||
+        typeof value.operationId !== "string" ||
+        typeof value.characterId !== "string" ||
+        typeof value.input !== "string" ||
+        !value.speaker ||
+        typeof value.speaker.playerId !== "string" ||
+        !value.audience ||
+        (value.audience.disclosure !== "participants" && value.audience.disclosure !== "world") ||
+        !Array.isArray(value.audience.players) ||
+        !Array.isArray(value.audience.characterIds)) {
+        throw new TypeError("The platform sent an invalid shared character request.");
+    }
+    return value;
+}
+function assertPlatformWorldCharacterCommand(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.grantId !== "string" ||
+        typeof value.requestId !== "string" ||
+        typeof value.operationId !== "string" ||
+        !value.speaker ||
+        typeof value.speaker.playerId !== "string" ||
+        !value.command ||
+        typeof value.command !== "object" ||
+        Array.isArray(value.command)) {
+        throw new TypeError("The platform sent an invalid shared character command.");
+    }
+    return value;
+}
+function assertPlatformWorldCharacterRead(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.grantId !== "string" ||
+        typeof value.requestId !== "string" ||
+        !value.speaker ||
+        typeof value.speaker.playerId !== "string" ||
+        !value.query ||
+        typeof value.query !== "object" ||
+        Array.isArray(value.query)) {
+        throw new TypeError("The platform sent an invalid shared character read.");
+    }
+    return value;
+}
+function hasWorldCharacterPlatform(platformHandle, operation) {
+    return (typeof platformHandle[operation] === "function" &&
+        typeof platformHandle.worldCharacterReject === "function");
+}
+function deepFreezeJsonObject(value) {
+    const normalized = JSON.parse(JSON.stringify(value));
+    deepFreeze(normalized);
+    return normalized;
+}
+function deepFreeze(value) {
+    if (!value || typeof value !== "object")
+        return;
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+}
+function parseSharedCharacterJson(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        throw new TypeError("The platform returned an invalid shared character response.");
+    }
+}
+function assertWorldCharacterId(value, field, maxCharacters = 100) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > maxCharacters ||
+        value.includes("\0") ||
+        new TextEncoder().encode(value).byteLength > 128) {
+        throw new TypeError(`session.world.characters: ${field} must be non-empty text of at most ${maxCharacters} characters and 128 bytes.`);
+    }
+    return value;
+}
+function parseWorldCharacterAdmission(json, operationId) {
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch {
+        throw new TypeError("The platform returned an invalid shared character receipt.");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("The platform returned an invalid shared character receipt.");
+    }
+    const receipt = value;
+    if (receipt.operationId !== operationId ||
+        (receipt.status !== "queued" &&
+            receipt.status !== "completed" &&
+            receipt.status !== "interrupted") ||
+        typeof receipt.replayed !== "boolean") {
+        throw new TypeError("The platform returned an invalid shared character receipt.");
+    }
+    return Object.freeze({
+        operationId,
+        status: receipt.status,
+        replayed: receipt.replayed,
+    });
+}
 function assertWorldCheckpoint(value, operation = "commit") {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw worldError("A world checkpoint requires version and value.", operation);

package/package.json

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