castle-web-sdk 0.4.38 → 0.4.40

package/dist/multiplayer.d.ts

@@ -90,6 +90,21 @@ export type MultiplayerWorldCharacterQuery = {
     limit?: number;
     cursor?: string;
 };
+/** Authenticated, participant-scoped projection of a shared character world. */
+export interface MultiplayerWorldCharacterInspectResult<Gameplay = unknown, SharedState = unknown, PrivateState = unknown, Source = unknown> {
+    /** Durable identity used by gameplay holders and promise debtors. */
+    participantId: string;
+    worldRevision: string;
+    gameplay: Gameplay;
+    characters: Array<{
+        characterId: string;
+        npcRevision: string;
+        sharedState: SharedState;
+        privateState: PrivateState;
+        privateRevision: string;
+    }>;
+    sources: Source[];
+}
 export interface MultiplayerWorldCharacterCommandResult {
     operationId: string;
     status: "applied" | "ineligible";
@@ -118,6 +133,12 @@ export interface MultiplayerConnection {
         operationId: string;
         command: MultiplayerWorldCharacterCommand;
     }): Promise<MultiplayerWorldCharacterCommandResult>;
+    readCharacters(request: {
+        requestId: string;
+        query: {
+            type: "inspect";
+        };
+    }): Promise<MultiplayerWorldCharacterInspectResult>;
     readCharacters<T = unknown>(request: {
         requestId: string;
         query: MultiplayerWorldCharacterQuery;

package/dist/server/platformHandle.d.ts

@@ -53,6 +53,8 @@ export interface PlatformHandle {
     worldCharacterSend?(grantId: string): Promise<string>;
     worldCharacterCommand?(grantId: string): Promise<string>;
     worldCharacterRead?(grantId: string): Promise<string>;
+    worldCharacterRuntimeCreate?(argsJson: string): Promise<string>;
+    worldCharacterRuntimeList?(): Promise<string>;
     worldCharacterReject?(grantId: string, code?: string): void;
     readonly config: PlatformSessionConfig;
 }

package/dist/server/wrapper.d.ts

@@ -55,6 +55,8 @@ export interface MultiplayerServerWorld {
     readonly characters: MultiplayerServerWorldCharacters;
 }
 export interface MultiplayerServerWorldCharacters {
+    create(input: MultiplayerWorldRuntimeCharacterCreateInput): Promise<MultiplayerWorldRuntimeCharacterCreateReceipt>;
+    list(): Promise<MultiplayerWorldCharacterList>;
     publicInspect<T = unknown>(): Promise<T>;
     publicRelay(input: {
         operationId: string;
@@ -63,6 +65,38 @@ export interface MultiplayerServerWorldCharacters {
         recipientCharacterIds: string[];
     }): Promise<unknown>;
 }
+export interface MultiplayerWorldRuntimeCharacterKnowledge {
+    kind: "belief";
+    text: string;
+}
+export interface MultiplayerWorldRuntimeCharacterDefinition {
+    name: string;
+    instructions: string;
+    background?: string;
+    initialKnowledge?: readonly MultiplayerWorldRuntimeCharacterKnowledge[];
+}
+export interface MultiplayerWorldRuntimeCharacterCreateInput {
+    operationId: string;
+    definition: MultiplayerWorldRuntimeCharacterDefinition;
+    capabilities: {
+        actionIds: readonly string[];
+    };
+}
+export interface MultiplayerWorldCharacterSummary {
+    id: string;
+    name: string;
+    source: "published" | "runtime";
+}
+export interface MultiplayerWorldRuntimeCharacterCreateReceipt {
+    operationId: string;
+    character: MultiplayerWorldCharacterSummary & {
+        source: "runtime";
+    };
+    replayed: boolean;
+}
+export interface MultiplayerWorldCharacterList {
+    characters: readonly MultiplayerWorldCharacterSummary[];
+}
 export interface MultiplayerWorldCharacterCommandRequest {
     readonly requestId: string;
     readonly operationId: string;

package/dist/server/wrapper.js

@@ -49,6 +49,7 @@ async function bootSession(platformHandle, callbacks) {
         platformHandle.on("worldCharacterTurn", async (raw) => {
             const request = assertPlatformWorldCharacterTurn(raw);
             let settled = false;
+            const brokerFailure = { rejection: null };
             const turn = Object.freeze({
                 requestId: request.requestId,
                 operationId: request.operationId,
@@ -64,7 +65,14 @@ async function bootSession(platformHandle, callbacks) {
                     if (settled)
                         throw new TypeError("This shared character request is already settled.");
                     settled = true;
-                    const rawReceipt = await platformHandle.worldCharacterSend(request.grantId);
+                    let rawReceipt;
+                    try {
+                        rawReceipt = await platformHandle.worldCharacterSend(request.grantId);
+                    }
+                    catch (error) {
+                        brokerFailure.rejection = { error };
+                        throw error;
+                    }
                     return parseWorldCharacterAdmission(rawReceipt, request.operationId);
                 },
                 reject(code) {
@@ -77,6 +85,10 @@ async function bootSession(platformHandle, callbacks) {
             try {
                 await callbacks.onWorldCharacterTurn(session, turn);
             }
+            catch (error) {
+                if (brokerFailure.rejection === null || brokerFailure.rejection.error !== error)
+                    throw error;
+            }
             finally {
                 if (!settled)
                     turn.reject();
@@ -88,6 +100,7 @@ async function bootSession(platformHandle, callbacks) {
         platformHandle.on("worldCharacterCommand", async (raw) => {
             const request = assertPlatformWorldCharacterCommand(raw);
             let settled = false;
+            const brokerFailure = { rejection: null };
             const command = Object.freeze({
                 requestId: request.requestId,
                 operationId: request.operationId,
@@ -97,7 +110,15 @@ async function bootSession(platformHandle, callbacks) {
                     if (settled)
                         throw new TypeError("This shared character command is already settled.");
                     settled = true;
-                    return parseSharedCharacterJson(await platformHandle.worldCharacterCommand(request.grantId));
+                    let rawResult;
+                    try {
+                        rawResult = await platformHandle.worldCharacterCommand(request.grantId);
+                    }
+                    catch (error) {
+                        brokerFailure.rejection = { error };
+                        throw error;
+                    }
+                    return parseSharedCharacterJson(rawResult);
                 },
                 reject(code) {
                     if (settled)
@@ -109,6 +130,10 @@ async function bootSession(platformHandle, callbacks) {
             try {
                 await callbacks.onWorldCharacterCommand(session, command);
             }
+            catch (error) {
+                if (brokerFailure.rejection === null || brokerFailure.rejection.error !== error)
+                    throw error;
+            }
             finally {
                 if (!settled)
                     command.reject();
@@ -120,6 +145,7 @@ async function bootSession(platformHandle, callbacks) {
         platformHandle.on("worldCharacterRead", async (raw) => {
             const request = assertPlatformWorldCharacterRead(raw);
             let settled = false;
+            const brokerFailure = { rejection: null };
             const read = Object.freeze({
                 requestId: request.requestId,
                 speaker: Object.freeze({ ...request.speaker }),
@@ -128,7 +154,15 @@ async function bootSession(platformHandle, callbacks) {
                     if (settled)
                         throw new TypeError("This shared character read is already settled.");
                     settled = true;
-                    return parseSharedCharacterJson(await platformHandle.worldCharacterRead(request.grantId));
+                    let rawResult;
+                    try {
+                        rawResult = await platformHandle.worldCharacterRead(request.grantId);
+                    }
+                    catch (error) {
+                        brokerFailure.rejection = { error };
+                        throw error;
+                    }
+                    return parseSharedCharacterJson(rawResult);
                 },
                 reject(code) {
                     if (settled)
@@ -140,6 +174,10 @@ async function bootSession(platformHandle, callbacks) {
             try {
                 await callbacks.onWorldCharacterRead(session, read);
             }
+            catch (error) {
+                if (brokerFailure.rejection === null || brokerFailure.rejection.error !== error)
+                    throw error;
+            }
             finally {
                 if (!settled)
                     read.reject();
@@ -252,16 +290,28 @@ 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.");
+        async create(input) {
+            if (typeof platformHandle.worldCharacterRuntimeCreate !== "function") {
+                throw new TypeError("The runtime character broker is unavailable.");
+            }
+            const operationId = assertWorldOperationId(input?.operationId);
+            const definition = assertRuntimeCharacterDefinition(input?.definition);
+            const capabilities = assertRuntimeCharacterCapabilities(input?.capabilities);
+            const result = parseSharedCharacterJson(await platformHandle.worldCharacterRuntimeCreate(JSON.stringify({ operationId, definition, capabilities })));
+            return parseRuntimeCharacterCreateReceipt(result, operationId);
+        },
+        async list() {
+            if (typeof platformHandle.worldCharacterRuntimeList !== "function") {
+                throw new TypeError("The runtime character broker is unavailable.");
             }
+            return parseRuntimeCharacterList(parseSharedCharacterJson(await platformHandle.worldCharacterRuntimeList()));
+        },
+        async publicInspect() {
+            requireSharedCharacterBroker(platformHandle);
             return parseSharedCharacterJson(await platformHandle.storage("worldCharacterPublicInspect", "{}"));
         },
         async publicRelay(input) {
-            if (typeof platformHandle.storage !== "function") {
-                throw new TypeError("The shared character broker is unavailable.");
-            }
+            requireSharedCharacterBroker(platformHandle);
             const operationId = assertWorldOperationId(input?.operationId);
             const sourceId = assertWorldCharacterId(input?.sourceId, "sourceId", 128);
             const transmittingCharacterId = assertWorldCharacterId(input?.transmittingCharacterId, "transmittingCharacterId");
@@ -282,6 +332,142 @@ function createServerWorldCharacters(platformHandle) {
         },
     });
 }
+const RUNTIME_CHARACTER_MAX_COUNT = 16;
+const RUNTIME_CHARACTER_MAX_KNOWLEDGE = 8;
+const RUNTIME_CHARACTER_PROMPT_MAX_CHARACTERS = 8_000;
+const RUNTIME_CHARACTER_ID = /^runtime_[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const SAFE_RUNTIME_ACTION_ID = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const FORBIDDEN_RUNTIME_ACTION_IDS = new Set(["__proto__", "prototype", "constructor"]);
+function requireSharedCharacterBroker(platformHandle) {
+    if (typeof platformHandle.storage !== "function") {
+        throw new TypeError("The shared character broker is unavailable.");
+    }
+}
+function assertRuntimeCharacterDefinition(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("session.world.characters.create: definition must be an object.");
+    }
+    const definition = value;
+    if (Object.keys(definition).some((key) => !["name", "instructions", "background", "initialKnowledge"].includes(key))) {
+        throw new TypeError("session.world.characters.create: definition contains an unsupported field.");
+    }
+    const name = assertRuntimeCharacterText(definition.name, "definition.name", 100, 400);
+    const instructions = assertRuntimeCharacterText(definition.instructions, "definition.instructions", 8_000, 32_000);
+    if (JSON.stringify(instructions).length - 2 > 10_000) {
+        throw new TypeError("session.world.characters.create: definition.instructions is too large when serialized.");
+    }
+    const background = definition.background === undefined
+        ? undefined
+        : assertRuntimeCharacterText(definition.background, "definition.background", 2_000, 8_000);
+    let initialKnowledge;
+    if (definition.initialKnowledge !== undefined) {
+        if (!Array.isArray(definition.initialKnowledge) ||
+            definition.initialKnowledge.length > RUNTIME_CHARACTER_MAX_KNOWLEDGE) {
+            throw new TypeError(`session.world.characters.create: definition.initialKnowledge may contain at most ${RUNTIME_CHARACTER_MAX_KNOWLEDGE} beliefs.`);
+        }
+        initialKnowledge = definition.initialKnowledge.map((entry, index) => {
+            if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+                throw new TypeError(`session.world.characters.create: definition.initialKnowledge[${index}] must be a belief.`);
+            }
+            const knowledge = entry;
+            if (Object.keys(knowledge).some((key) => key !== "kind" && key !== "text") ||
+                knowledge.kind !== "belief") {
+                throw new TypeError(`session.world.characters.create: definition.initialKnowledge[${index}] must contain only kind "belief" and text.`);
+            }
+            return {
+                kind: "belief",
+                text: assertRuntimeCharacterText(knowledge.text, `definition.initialKnowledge[${index}].text`, 500, 2_000),
+            };
+        });
+    }
+    const promptCharacters = instructions.length + (background?.length ?? 0) +
+        (initialKnowledge?.reduce((sum, item) => sum + item.text.length, 0) ?? 0);
+    if (promptCharacters > RUNTIME_CHARACTER_PROMPT_MAX_CHARACTERS) {
+        throw new TypeError(`session.world.characters.create: definition prompt fields may total at most ${RUNTIME_CHARACTER_PROMPT_MAX_CHARACTERS} characters.`);
+    }
+    return Object.freeze({
+        name,
+        instructions,
+        ...(background === undefined ? {} : { background }),
+        ...(initialKnowledge === undefined
+            ? {}
+            : { initialKnowledge: Object.freeze(initialKnowledge.map((item) => Object.freeze(item))) }),
+    });
+}
+function assertRuntimeCharacterCapabilities(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        Object.keys(value).some((key) => key !== "actionIds")) {
+        throw new TypeError("session.world.characters.create: capabilities must contain only actionIds.");
+    }
+    const actionIds = value.actionIds;
+    if (!Array.isArray(actionIds) || actionIds.length > RUNTIME_CHARACTER_MAX_COUNT) {
+        throw new TypeError(`session.world.characters.create: capabilities.actionIds may contain at most ${RUNTIME_CHARACTER_MAX_COUNT} ids.`);
+    }
+    const normalized = actionIds.map((id, index) => {
+        if (typeof id !== "string" ||
+            !SAFE_RUNTIME_ACTION_ID.test(id) ||
+            FORBIDDEN_RUNTIME_ACTION_IDS.has(id)) {
+            throw new TypeError(`session.world.characters.create: capabilities.actionIds[${index}] is invalid.`);
+        }
+        return id;
+    });
+    if (new Set(normalized).size !== normalized.length) {
+        throw new TypeError("session.world.characters.create: capabilities.actionIds may not contain duplicates.");
+    }
+    return Object.freeze({ actionIds: Object.freeze([...normalized].sort()) });
+}
+function assertRuntimeCharacterText(value, field, maxCharacters, maxBytes) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > maxCharacters ||
+        value.includes("\0") ||
+        /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(value) ||
+        new TextEncoder().encode(value).byteLength > maxBytes) {
+        throw new TypeError(`session.world.characters.create: ${field} must be valid non-empty text of at most ${maxCharacters} characters.`);
+    }
+    return value;
+}
+function parseRuntimeCharacterCreateReceipt(value, operationId) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("The platform returned an invalid runtime character receipt.");
+    }
+    const receipt = value;
+    const character = parseRuntimeCharacterSummary(receipt.character, true);
+    if (receipt.operationId !== operationId || typeof receipt.replayed !== "boolean") {
+        throw new TypeError("The platform returned an invalid runtime character receipt.");
+    }
+    return Object.freeze({ operationId, character, replayed: receipt.replayed });
+}
+function parseRuntimeCharacterList(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("The platform returned an invalid runtime character list.");
+    }
+    const characters = value.characters;
+    if (!Array.isArray(characters) || characters.length > RUNTIME_CHARACTER_MAX_COUNT) {
+        throw new TypeError("The platform returned an invalid runtime character list.");
+    }
+    const normalized = characters.map((character) => parseRuntimeCharacterSummary(character));
+    if (new Set(normalized.map((character) => character.id)).size !== normalized.length) {
+        throw new TypeError("The platform returned an invalid runtime character list.");
+    }
+    return Object.freeze({ characters: Object.freeze(normalized) });
+}
+function parseRuntimeCharacterSummary(value, requireRuntime = false) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("The platform returned an invalid runtime character summary.");
+    }
+    const summary = value;
+    const id = assertWorldCharacterId(summary.id, "character.id");
+    const name = assertRuntimeCharacterText(summary.name, "character.name", 100, 400);
+    if ((summary.source !== "runtime" && summary.source !== "published") ||
+        (requireRuntime && summary.source !== "runtime") ||
+        (summary.source === "runtime" && !RUNTIME_CHARACTER_ID.test(id))) {
+        throw new TypeError("The platform returned an invalid runtime character summary.");
+    }
+    return Object.freeze({ id, name, source: summary.source });
+}
 function parseWorldSnapshot(value, operation) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw worldError("The platform returned an invalid world checkpoint.", "read");

package/package.json

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