@nodetool-ai/agents 0.8.1 → 0.8.2

package/dist/capabilities/game.js

@@ -1,15 +1,20 @@
 import { createHash, randomUUID } from "node:crypto";
 import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
 import { join } from "node:path";
-import { getManagedWorkspaceDir, managedWorkspaceKey, workspaceStorageKind } from "@nodetool-ai/config";
+import { createLogger, getManagedWorkspaceDir, managedWorkspaceKey, workspaceStorageKind } from "@nodetool-ai/config";
 import { AmbiguousGameIdError, Asset, Game, Prediction, Project, Workspace } from "@nodetool-ai/models";
-import { gameAssetBinding, gameDocument, gameInputFrame, shortResourceId } from "@nodetool-ai/protocol";
-import { autoplayNativeGame, MAX_GAME_ROUTE_TICKS, createScriptedGameSession, createTopDownRoomGame, validateGame, gameDocumentOp, GameOpError } from "@nodetool-ai/game-runtime";
+import { anyGameAssetBinding as gameAssetBinding, gameAssetBinding as legacyAssetBinding, gameAssetBinding3D, anyGameDocument as gameDocument, gameInputFrame, shortResourceId } from "@nodetool-ai/protocol";
+import { autoplayNativeGame, MAX_GAME_ROUTE_TICKS, createScriptedGameSession, createTopDownRoomGame, createNative3DGame, decodePreparedGameCollider3D, validateAnyGame, trackGameAuthoringEdits, anyGameDocumentOp as gameDocumentOp, GameOpError } from "@nodetool-ai/game-runtime";
 import { workspaceFromRow } from "@nodetool-ai/execution/service";
 import { assetKeyCandidates, assetObjectKey } from "@nodetool-ai/storage";
+import { gameOutline3D, inputFrames3D, playtestGame3D, captureFrames3D, colliderBinding3D, stageModelGameAsset3D } from "./game3d.js";
 import { gameSpecs } from "./game.specs.js";
 import { persistOutput } from "../tools/asset-persist.js";
 import { getExampleGameBundle, installExampleGameAssets, listExampleGames } from "../game-examples.js";
+import { previewGameAuthoring, applyGameAuthoring } from "../game-authoring.js";
+import { gameDocumentDigest } from "../game-code-bake.js";
+import { previewGameAuthoringSpec, applyGameAuthoringSpec } from "./game.specs.js";
+const log = createLogger("capabilities.game");
 const MAX_PLAYTEST_TICKS = MAX_GAME_ROUTE_TICKS;
 const MAX_CAPTURE_FRAMES = 8;
 const MAX_BUILD_ASSETS = 128;
@@ -24,7 +29,9 @@ const MEDIA_EXTENSIONS = {
     "audio/ogg": "ogg",
     "audio/mpeg": "mp3",
     "font/ttf": "ttf",
-    "font/otf": "otf"
+    "font/otf": "otf",
+    "model/gltf-binary": "glb",
+    "application/json": "json"
 };
 function userId(run) {
     return run.context.userId ?? null;
@@ -102,6 +109,9 @@ async function readSource(workspace, game, source, revision) {
     return draft?.document ?? null;
 }
 function outline(document) {
+    if (document.schemaVersion === 3) {
+        return gameOutline3D(document);
+    }
     return {
         settings: {
             schemaVersion: document.schemaVersion,
@@ -308,8 +318,8 @@ function validateSource(source, gameId, revision) {
     const parsed = gameDocument.safeParse(source);
     if (!parsed.success)
         return { error: parsed.error.message };
-    const result = validateGame({ ...parsed.data, id: gameId, revision });
-    return result.document ?? { error: result.errors.join("; ") };
+    const result = validateAnyGame({ ...parsed.data, id: gameId, revision });
+    return result.valid ? result.document : { error: result.diagnostics.map((issue) => `${issue.code} ${issue.path.join(".")}: ${issue.message}`).join("; ") };
 }
 function summary(game) {
     return {
@@ -319,25 +329,52 @@ function summary(game) {
         workspace_id: game.workspace_id
     };
 }
-async function publish(user, game, baseRevision, source, message) {
+async function publish(user, game, request) {
+    const baseRevision = request.base_revision;
     if (game.current_revision !== baseRevision)
         return { error: "Game was modified concurrently", current_revision: game.current_revision };
     const revision = randomUUID().replace(/-/g, "");
-    const document = validateSource(source, game.id, revision);
-    if ("error" in document)
-        return document;
     const workspace = await workspaceOf(user, game);
     if (!workspace)
         return { error: "Game workspace is unavailable" };
     const draft = await Game.readDraft(user, game.id, workspace);
     if (!draft)
         return { error: "Game draft not found" };
+    const draftToken = request.document ? request.base_updated_at : draft.game.draft_updated_at;
+    if (draftToken !== draft.game.draft_updated_at) {
+        return { error: "Game draft was modified concurrently" };
+    }
+    let document = validateSource(request.document ?? draft.document, game.id, revision);
+    if ("error" in document)
+        return document;
+    if ((document.schemaVersion === 3) !== (draft.document.schemaVersion === 3)) {
+        return { error: "A game cannot change dimension" };
+    }
+    if (gameDocumentDigest(document.authoring) !== gameDocumentDigest(draft.document.authoring)) {
+        return { error: "Retained authoring metadata must be updated through construction preview and apply" };
+    }
+    document = trackGameAuthoringEdits(draft.document, document);
+    const checked = validateAnyGame(document);
+    if (!checked.valid) {
+        return { error: "Game publication rejected", diagnostics: checked.diagnostics };
+    }
     await workspace.write(revisionPath(game, revision), JSON.stringify(document), "application/json");
-    const updated = await Game.publish(user, game.id, baseRevision, revision, draft.game.draft_updated_at, workspace, message);
-    if (!updated)
+    const updated = await Game.publish(user, game.id, baseRevision, revision, draftToken, workspace, request.message);
+    if (!updated) {
+        try {
+            await workspace.delete(revisionPath(game, revision));
+        }
+        catch (error) {
+            log.error("Losing game publication revision cleanup failed", { gameId: game.id, revision, error: String(error) });
+        }
         return { error: "Game was modified concurrently" };
-    await workspace.write(`${game.source_root}/drafts/${encodeURIComponent(updated.draft_updated_at)}.json`, JSON.stringify(document), "application/json");
-    await workspace.write(`${game.source_root}/draft.json`, JSON.stringify(document), "application/json");
+    }
+    try {
+        await Game.pruneRevisionFiles(user, game.id, workspace);
+    }
+    catch (error) {
+        log.error("Game publication revision cleanup failed", { gameId: game.id, error: String(error) });
+    }
     return { game: summary(updated), document };
 }
 const create = {
@@ -349,14 +386,26 @@ const create = {
         if (!user || typeof projectId !== "string" || typeof name !== "string" || !name.trim()) {
             return { error: "project_id and name are required in a user session" };
         }
-        const created = await createNativeGame(user, projectId, name.trim());
+        const dimension = args["dimension"];
+        if (dimension !== undefined && dimension !== "2d" && dimension !== "3d") {
+            return { error: "dimension must be 2d or 3d" };
+        }
+        if (args["template"] !== undefined && args["template"] !== "exploration" && args["template"] !== "topdown") {
+            return { error: "Unknown native game template" };
+        }
+        if (args["template"] !== undefined && args["template"] !== (dimension === "3d" ? "exploration" : "topdown")) {
+            return { error: "Template does not match the requested dimension" };
+        }
+        const created = await createNativeGame(user, projectId, name.trim(), undefined, dimension ?? "2d");
         return "error" in created
             ? created
             : { game: summary(created.game), document: created.document };
     }
 };
-/** Shared by explicit game creation and the guided asset workflow builder. */
-export async function createNativeGame(user, projectId, name, source) {
+export async function createNativeGame(user, projectId, name, source, dimension = "2d") {
+    if (source?.authoring) {
+        return { error: "Attach retained construction through preview and apply after creating the game" };
+    }
     const project = await Project.findOwned(user, projectId);
     if (!project)
         return { error: "Project not found" };
@@ -366,9 +415,12 @@ export async function createNativeGame(user, projectId, name, source) {
         return { error: "Project workspace is unavailable" };
     const id = randomUUID().replace(/-/g, "");
     const revision = randomUUID().replace(/-/g, "");
-    const document = validateSource(source ?? { ...createTopDownRoomGame(id), schemaVersion: 2 }, id, revision);
+    const document = validateSource(source ?? (dimension === "3d" ? createNative3DGame(id) : { ...createTopDownRoomGame(id), schemaVersion: 2 }), id, revision);
     if ("error" in document)
         return document;
+    if (source && ((document.schemaVersion === 3) !== (dimension === "3d"))) {
+        return { error: "Supplied document does not match the requested dimension" };
+    }
     const game = new Game({
         id,
         user_id: user,
@@ -395,13 +447,18 @@ const get = {
         const id = args["game_id"];
         if (!user || typeof id !== "string")
             return { error: "game_id is required in a user session" };
-        const game = await ownedGame(user, id);
+        let game = await ownedGame(user, id);
         if (!game)
             return { error: "Game not found" };
         const workspace = await workspaceOf(user, game);
         if (!workspace)
             return { error: "Game workspace is unavailable" };
-        const document = await readSource(workspace, game, args["source"], args["revision"]);
+        const readsDraft = (args["source"] === undefined || args["source"] === "draft") && args["revision"] === undefined;
+        const draft = readsDraft ? await Game.readDraft(user, game.id, workspace) : null;
+        const document = readsDraft ? draft?.document : await readSource(workspace, game, args["source"], args["revision"]);
+        if (draft) {
+            game = draft.game;
+        }
         if (!document)
             return { error: "Game source not found" };
         const view = args["view"] ?? "outline";
@@ -430,11 +487,19 @@ const save = {
         const game = await ownedGame(user, id);
         if (!game)
             return { error: "Game not found" };
-        const workspace = await workspaceOf(user, game);
-        if (!workspace)
-            return { error: "Game workspace is unavailable" };
-        const document = args["document"] ?? await readSource(workspace, game, "draft", undefined);
-        return document ? publish(user, game, base, document, typeof args["message"] === "string" ? args["message"] : undefined) : { error: "Game draft not found" };
+        const request = { game_id: id, base_revision: base, message: typeof args["message"] === "string" ? args["message"] : undefined };
+        if (args["document"] !== undefined) {
+            const token = args["base_updated_at"];
+            if (typeof token !== "string" || !token) {
+                return { error: "base_updated_at is required with an explicit document" };
+            }
+            const parsed = gameDocument.safeParse(args["document"]);
+            if (!parsed.success) {
+                return { error: parsed.error.message };
+            }
+            return publish(user, game, { ...request, document: parsed.data, base_updated_at: token });
+        }
+        return publish(user, game, request);
     }
 };
 const edit = {
@@ -510,11 +575,13 @@ const install = {
                 return { error: "Candidate workspace is unavailable" };
             candidateWorkspace = resolved;
         }
-        const formats = parsed.data.mediaKind === "audio"
-            ? [["wav", "audio/wav"], ["mp3", "audio/mpeg"], ["ogg", "audio/ogg"]]
-            : parsed.data.mediaKind === "font"
-                ? [[parsed.data.fontFormat, `font/${parsed.data.fontFormat}`]]
-                : [["png", "image/png"], ["jpg", "image/jpeg"], ["webp", "image/webp"]];
+        const formats = parsed.data.mediaKind === "model" ? [["glb", "model/gltf-binary"]]
+            : parsed.data.mediaKind === "collider" ? [["json", "application/json"]]
+                : parsed.data.mediaKind === "audio"
+                    ? [["wav", "audio/wav"], ["mp3", "audio/mpeg"], ["ogg", "audio/ogg"]]
+                    : parsed.data.mediaKind === "font"
+                        ? [[parsed.data.fontFormat, `font/${parsed.data.fontFormat}`]]
+                        : [["png", "image/png"], ["jpg", "image/jpeg"], ["webp", "image/webp"]];
         let candidate = null;
         for (const [extension, contentType] of formats) {
             if (!extension)
@@ -536,6 +603,45 @@ const install = {
         if (!draft)
             return { error: "Game draft is missing" };
         const expectedUpdatedAt = typeof args["base_updated_at"] === "string" ? args["base_updated_at"] : draft.game.draft_updated_at;
+        let binding = parsed.data;
+        try {
+            if (binding.mediaKind === "model") {
+                const { prepareGameModelBinding3D } = await import("@nodetool-ai/game-renderer/preparation3d");
+                const prepared = await prepareGameModelBinding3D(bytes, { assetId: binding.assetId, expectedDigest: binding.digest, signal: run.context.signal });
+                if (!prepared.ok) {
+                    return { error: "Model preparation failed", diagnostics: prepared.diagnostics };
+                }
+                const sourceAsset = binding.sourceAssetId ? await Asset.find(user, binding.sourceAssetId) : null;
+                if (binding.sourceAssetId && !sourceAsset) {
+                    return { error: "Model source asset is not owned" };
+                }
+                const canonical = { ...prepared.binding, required: binding.required };
+                if (binding.provenance) {
+                    canonical.provenance = binding.provenance;
+                }
+                if (binding.importSettings) {
+                    canonical.importSettings = binding.importSettings;
+                }
+                if (binding.sourceDigest) {
+                    canonical.sourceDigest = binding.sourceDigest;
+                }
+                if (sourceAsset) {
+                    canonical.sourceAssetId = sourceAsset.id;
+                }
+                binding = canonical;
+            }
+            else if (binding.mediaKind === "collider") {
+                binding = colliderBinding3D(bytes, binding);
+                await decodePreparedGameCollider3D(bytes, gameAssetBinding3D.options[1].parse(binding));
+            }
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : String(error) };
+        }
+        const targetBinding = draft.document.schemaVersion === 3 ? gameAssetBinding3D.safeParse(binding) : legacyAssetBinding.safeParse(binding);
+        if (!targetBinding.success) {
+            return { error: "Asset binding does not match the game dimension" };
+        }
         const storage = run.context.assetStorage;
         if (!storage)
             return { error: "Asset storage is unavailable" };
@@ -558,7 +664,8 @@ const install = {
             uri = await storage.store(key, bytes, contentType);
             let result;
             try {
-                const updated = await Game.updateDraft(user, game.id, expectedUpdatedAt, [{ op: "bind_asset", slot, binding: { ...parsed.data, assetId: installed.id } }], workspace, { actor: "agent", threadId: run.context.threadId ?? undefined, messageId: run.context.get?.("chat_message_id") ?? undefined });
+                const op = gameDocumentOp.parse({ op: "bind_asset", slot, binding: { ...targetBinding.data, assetId: installed.id } });
+                const updated = await Game.updateDraft(user, game.id, expectedUpdatedAt, [op], workspace, { actor: "agent", threadId: run.context.threadId ?? undefined, messageId: run.context.get?.("chat_message_id") ?? undefined });
                 result = updated ? { game: summary(updated.game), draft_updated_at: updated.game.draft_updated_at, document: updated.document } : { error: "Game draft was modified concurrently" };
             }
             catch (error) {
@@ -597,6 +704,15 @@ const playtest = {
         const document = await readSource(workspace, game, args["source"], args["revision"]);
         if (!document)
             return { error: "Game source not found" };
+        if (document.schemaVersion === 3) {
+            try {
+                return await playtestGame3D(run, user, document, args);
+            }
+            catch (error) {
+                run.context.signal?.throwIfAborted();
+                return { error: error instanceof Error ? error.message : String(error), code: "game3d_preparation_failed" };
+            }
+        }
         const captures = captureTicks(args["capture_ticks"], []);
         if ("error" in captures)
             return captures;
@@ -732,6 +848,20 @@ const capture = {
         const ticks = captureTicks(args["ticks"], [0]);
         if ("error" in ticks)
             return ticks;
+        if (document.schemaVersion === 3) {
+            const inputs = inputFrames3D(args["inputs"], Math.max(0, ...ticks));
+            if ("error" in inputs) {
+                return inputs;
+            }
+            const seed = typeof args["seed"] === "number" && Number.isSafeInteger(args["seed"]) ? args["seed"] : 1;
+            try {
+                return await captureFrames3D(run, user, document, ticks, inputs, seed, args);
+            }
+            catch (error) {
+                run.context.signal?.throwIfAborted();
+                return { error: error instanceof Error ? error.message : String(error), code: "game3d_capture_failed" };
+            }
+        }
         const inputs = inputFrames(args["inputs"], Math.max(0, ...ticks));
         if ("error" in inputs)
             return inputs;
@@ -754,7 +884,7 @@ const generateAsset = {
         const kind = args["kind"];
         const prompt = args["prompt"];
         const inputFile = args["input_file"];
-        if (!user || typeof id !== "string" || typeof slot !== "string" || !slot || !["image", "audio", "music", "sfx", "font"].includes(String(kind))) {
+        if (!user || typeof id !== "string" || typeof slot !== "string" || !slot || !["image", "audio", "music", "sfx", "font", "model", "collider"].includes(String(kind))) {
             return { error: "game_id, slot, and kind are required" };
         }
         if (inputFile !== undefined && (typeof inputFile !== "string" || !inputFile.trim())) {
@@ -772,6 +902,21 @@ const generateAsset = {
         if (!draft) {
             return { error: "Game draft not found" };
         }
+        if (kind === "model" || kind === "collider") {
+            if (draft.document.schemaVersion !== 3) {
+                return { error: "Model and collider assets require a 3D game" };
+            }
+            try {
+                return await stageModelGameAsset3D(run, game, workspace, draft.document, args);
+            }
+            catch (error) {
+                run.context.signal?.throwIfAborted();
+                return { error: error instanceof Error ? error.message : String(error) };
+            }
+        }
+        if (draft.document.schemaVersion === 3 && kind === "image") {
+            return { error: "3D games use model assets with embedded textures" };
+        }
         const reference = typeof args["reference_slot"] === "string" ? draft.document.assets[args["reference_slot"]] : undefined;
         if (args["reference_slot"] !== undefined && !reference) {
             return { error: "reference_slot is not bound" };
@@ -791,7 +936,7 @@ const generateAsset = {
         let provider = args["provider"];
         let model = args["model"];
         let generated = {};
-        let sourceBytes = null;
+        let sourceBytes;
         const makeLut = settings?.success && settings.data.lut !== undefined;
         if (makeLut && (inputFile !== undefined || reference || args["generation_id"] !== undefined)) {
             return { error: "LUT preparation creates a color cube directly and cannot use input_file, reference_slot or generation_id" };
@@ -908,7 +1053,7 @@ const generateAsset = {
         let height = 1;
         const previous = draft.document.assets[slot];
         const binding = {
-            width, height, pivot: previous?.pivot ?? { x: 0.5, y: 0.5 }, sampling: previous?.sampling ?? "nearest"
+            width, height, pivot: previous && "pivot" in previous ? previous.pivot : { x: 0.5, y: 0.5 }, sampling: previous && "sampling" in previous ? previous.sampling : "nearest"
         };
         let frames;
         let tiles;
@@ -982,6 +1127,18 @@ const generateAsset = {
             binding.provenance = typeof inputFile === "string" ? `import:${inputFile}`
                 : makeLut ? "generated:color-cube" : kind === "sfx" ? `node:${args["node_type"]}` : `${provider}:${model}:${generated.generation_id ?? ""}`;
         }
+        if (draft.document.schemaVersion === 3) {
+            delete binding.width;
+            delete binding.height;
+            delete binding.pivot;
+            delete binding.sampling;
+            const parsedBinding = gameAssetBinding3D.safeParse(binding);
+            if (!parsedBinding.success) {
+                return { error: "Invalid 3D asset binding", diagnostics: parsedBinding.error.issues };
+            }
+            return { game_id: shortResourceId(game.id), slot, binding: parsedBinding.data, candidate_workspace_id: game.workspace_id,
+                draft_updated_at: draft.game.draft_updated_at, installed: false, next: "Call install_native_game_asset with this binding to install the candidate." };
+        }
         const installed = await install.impl(run, { game_id: game.id, slot, binding, base_updated_at: draft.game.draft_updated_at });
         if (typeof installed !== "object" || installed === null) {
             return { generation_id: generated.generation_id, result: installed };
@@ -1083,8 +1240,14 @@ const buildGame = {
         const scratch = await workspace.scratchDir();
         const staging = await mkdtemp(join(scratch, ".native-game-build-"));
         try {
-            const { buildStandaloneGame } = await import("@nodetool-ai/game-renderer/build");
-            await buildStandaloneGame({ document, outputDir: join(staging, "player"), resolveAsset });
+            if (document.schemaVersion === 3) {
+                const { buildStandaloneGame3D } = await import("@nodetool-ai/game-renderer/build3d");
+                await buildStandaloneGame3D({ document, outputDir: join(staging, "player"), resolveAsset, signal: run.context.signal });
+            }
+            else {
+                const { buildStandaloneGame } = await import("@nodetool-ai/game-renderer/build");
+                await buildStandaloneGame({ document, outputDir: join(staging, "player"), resolveAsset });
+            }
             const files = [];
             const pending = [""];
             let totalBytes = 0;
@@ -1120,7 +1283,9 @@ const buildGame = {
                                                 : file.path.endsWith(".mp3") ? "audio/mpeg"
                                                     : file.path.endsWith(".ttf") ? "font/ttf"
                                                         : file.path.endsWith(".otf") ? "font/otf"
-                                                            : "application/octet-stream";
+                                                            : file.path.endsWith(".glb") ? "model/gltf-binary"
+                                                                : file.path.endsWith(".wasm") ? "application/wasm"
+                                                                    : "application/octet-stream";
                 await workspace.write(`${buildPath}/${file.path}`, file.bytes, contentType);
             }
             const index = files.find((file) => file.path === "index.html");
@@ -1193,7 +1358,7 @@ const installExample = {
             return { error: "Example game not found" };
         const installed = await installExampleGameAssets(user, projectId, {}, slug, storage);
         try {
-            const created = await createNativeGame(user, projectId, typeof name === "string" ? name.trim() : installed.bundle.name, installed.document);
+            const created = await createNativeGame(user, projectId, typeof name === "string" ? name.trim() : installed.bundle.name, installed.document, installed.document.schemaVersion === 3 ? "3d" : "2d");
             if ("error" in created) {
                 await installed.rollback();
                 return created;
@@ -1222,6 +1387,9 @@ const autoplay = {
         const document = await readSource(workspace, game, args["source"], args["revision"]);
         if (!document)
             return { error: "Game source not found" };
+        if (document.schemaVersion === 3) {
+            return { status: "unsupported", dimension: "3d", code: "autoplay_3d_unsupported", message: "Use playtest_native_game with a recorded 3D route" };
+        }
         const targetPrefix = args["target_prefix"];
         const playerId = args["player_id"];
         const win = args["win"];
@@ -1257,6 +1425,8 @@ const autoplay = {
 };
 export const module = {
     module: "game",
-    exports: [create, get, save, install, playtest, buildGame, edit, capture, generateAsset, listExamples, getExample, installExample, autoplay]
+    exports: [create, get, save, install, playtest, buildGame, edit, capture, generateAsset, listExamples, getExample, installExample, autoplay,
+        { spec: previewGameAuthoringSpec, impl: previewGameAuthoring },
+        { spec: applyGameAuthoringSpec, impl: applyGameAuthoring }]
 };
 //# sourceMappingURL=game.js.map