@playcraft/cli 0.1.60-beta → 0.1.62-beta

package/dist/workspace-runtime/workspaces/skill-execution-context.js

@@ -0,0 +1,69 @@
+import { realpath } from 'node:fs/promises';
+import { PROCEDURAL_3D_SKILL_REF, resolveWorkspaceSkillExecutionPolicy, workspaceComposerSelectionSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { assertOperationDirectoryAccess } from '../server/directory-access.js';
+import { sessionWorkspaceRoot } from './registry.js';
+import { readWorkspaceSkillSnapshot } from './skills.js';
+/** Read-only preflight. It must precede the directory gate and cannot install or freeze files. */
+export async function preflightSkillExecution(state, request) {
+    if (request.kind !== 'session.turn')
+        return undefined;
+    const body = request.payload && typeof request.payload === 'object'
+        ? request.payload
+        : {};
+    if ('directoryAccessMode' in body || 'skillExecutionPolicyVersion' in body)
+        throw new Error('untrusted_runtime_field');
+    const selection = workspaceComposerSelectionSchema.safeParse({
+        context: body.context,
+        workMode: body.workMode,
+    });
+    if (!selection.success)
+        throw new Error('invalid_composer_context');
+    if (!selection.data.context?.skills.length)
+        return undefined;
+    if (request.directoryName === 'root')
+        throw new Error('context_directory_mismatch');
+    const root = await sessionWorkspaceRoot(state, request.workspaceId, request.directoryName);
+    return resolveWorkspaceSkillExecutionPolicy(await readWorkspaceSkillSnapshot(root), selection.data.context.skills);
+}
+/** Native tool callers supply the actual thread/turn binding, never shell-provided identity. */
+export async function resolveActiveSkillExecutionContext(state, input) {
+    const skillRef = input.skillRef ?? PROCEDURAL_3D_SKILL_REF;
+    if (state.journal.destroyed())
+        throw new Error('skill_execution_identity_mismatch');
+    if (skillRef !== PROCEDURAL_3D_SKILL_REF)
+        throw new Error('context_skill_unavailable');
+    const session = state.journal.getSession(input.sessionId);
+    const matches = state.journal
+        .listOperations()
+        .map((item) => item.operation)
+        .filter((operation) => operation.kind === 'session.turn' &&
+        ['dispatched', 'accepted'].includes(operation.status) &&
+        operation.sessionId === input.sessionId &&
+        operation.nativeThreadId === input.nativeThreadId &&
+        operation.nativeTurnId === input.nativeTurnId &&
+        operation.generation === state.config.generation &&
+        operation.runtimeEpoch === state.runtimeEpoch &&
+        operation.userId === state.config.userId &&
+        operation.environment === state.config.environment);
+    const operation = matches.length === 1 ? matches[0] : undefined;
+    if (!operation ||
+        !session ||
+        session.threadId !== input.nativeThreadId ||
+        (session.activeTurnId !== undefined && session.activeTurnId !== input.nativeTurnId) ||
+        session.workspaceId !== operation.workspaceId ||
+        (session.directoryName ?? 'basic') !== (operation.directoryName ?? 'basic'))
+        throw new Error('skill_execution_identity_mismatch');
+    if (operation.directoryAccessMode !== 'exclusive' || operation.skillExecutionPolicyVersion !== 1)
+        throw new Error('requires-exclusive-turn');
+    if (operation.workMode === 'plan' || operation.permissionMode === 'read-only')
+        throw new Error('skill_execution_readonly');
+    await assertOperationDirectoryAccess(state, operation, 'exclusive');
+    const root = await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName);
+    if ((await realpath(root)) !== (await realpath(input.root)))
+        throw new Error('skill_execution_identity_mismatch');
+    const policy = resolveWorkspaceSkillExecutionPolicy(await readWorkspaceSkillSnapshot(root), operation.context?.skills ?? []);
+    const entry = policy.entries.find((item) => item.revision.skillRef === skillRef);
+    if (!entry || policy.directoryAccessMode !== 'exclusive')
+        throw new Error('requires-exclusive-turn');
+    return { operation, entry, lockHash: policy.lockHash, declarationHash: policy.declarationHash };
+}

package/dist/workspace-runtime/workspaces/skills.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
-import { cp, lstat, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { cp, lstat, open, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { load } from 'js-yaml';
 import { canonicalProjectSkillsJson, createCanonicalBundleArchive, effectiveProjectSkills, extractBundleArchive, inspectProjectSkills, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
@@ -156,13 +157,22 @@ export async function freezeWorkspaceSkills(root, cache, loadArtifact) {
             expectedFiles.add(relative);
             await safeDirectory(generation, dirname(relative));
             // shared
-            await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(async (error) => {
+            await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(error => {
                 if (error.code !== 'EEXIST')
                     throw error;
-                const stat = await lstat(target);
-                if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || !file.data.equals(await readFile(target)))
-                    throw new Error('workspace_skills_digest_mismatch');
             });
+            const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() || stat.nlink !== 1 || !file.data.equals(await handle.readFile()))
+                    throw new Error('workspace_skills_digest_mismatch');
+                // A private controller umask must not remove the developer's read access.
+                // Repair only the verified inode, keeping every frozen byte read-only.
+                await handle.chmod(0o444);
+            }
+            finally {
+                await handle.close();
+            }
         }
         const body = files.find(file => file.path === 'SKILL.md');
         if (!body)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.60-beta",
+  "version": "0.1.62-beta",
   "private": false,
   "type": "module",
   "engines": {
@@ -53,8 +53,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.60-beta",
-    "@playcraft/common": "0.1.60-beta",
+    "@playcraft/build": "0.1.62-beta",
+    "@playcraft/common": "0.1.62-beta",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
@@ -91,6 +91,7 @@
     "@types/update-notifier": "^6.0.8",
     "@types/ws": "^8.18.1",
     "esbuild": "^0.28.1",
+    "three": "^0.183.2",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   }

package/project-template-v2/.playcraft/skills.lock.json

@@ -141,6 +141,13 @@
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-prefab"
     },
+    {
+      "skillRef": "remix/playcraft-remix-references",
+      "version": "1.1.0",
+      "artifactHash": "32d4bb3bb6ed2dc0405997161dc65cd535559a71c227f0425612809ee5c178af",
+      "surface": "sandbox-agent",
+      "mountPath": ".playcraft/skills/remix__playcraft-remix-references"
+    },
     {
       "skillRef": "remix/playcraft-remix-workflow",
       "version": "1.0.0",

package/project-templates/empty/AGENTS.md

@@ -42,6 +42,16 @@ Reference snapshots under `references/remixes/` are fixed source material. Their
 
 Use the built-in CLI (Command Line Interface, 命令行界面) commands for platform assets. Run the relevant command's `--help` to inspect its supported parameters. The workspace supplies credentials; keep them out of commands, files, and chat output.
 
+### Asset sourcing
+
+Follow the user's explicit source choice: reuse specified assets or generate new assets when requested, without asking again. Otherwise, when a task needs images, audio, sprites, animation, models, or video, search the shared library before generating. Cover both authorized team assets and public assets. When the current team is known from verified workspace or project context, search it with `--team-id <teamId>` and search public assets separately with `--visibility public`; a team filter does not include public assets. Without verified team context, omit both filters to search the credential's authorized scopes rather than guessing a team identifier.
+
+Inspect promising candidates with `library get` and `library files`, checking their intended use, style, dimensions, format, and required package contents against the task. Reuse suitable assets directly, preferring team assets when candidates are equally suitable, and download the complete file or package into the project's asset directory. Do not substitute a preview for the production files. If a narrow query finds nothing suitable, broaden the keywords or filters and inspect relevant result pages before concluding there is no match. Generate only the missing assets after these searches find no suitable candidate. A failed or unavailable search is not an empty result: report the limitation and recover the search instead of claiming that the library has no suitable assets.
+
+Do not ask the user to choose reuse versus generation for every asset. Ask only when candidate differences materially affect the requested direction or suitability remains unclear; present the relevant candidates and tradeoffs. An execution without user interaction should pass that ambiguity to its coordinating conversation through the existing workflow. Report which assets were actually reused or generated and why.
+
+### Commands
+
 - Shared library: `playcraft library search "<query>" --json`, `library list`, and `library facets` support type, category, tags, team, and pagination filters. `library get <assetId>` reads metadata; `library files <assetId>` lists a complete package. These identifiers belong to the shared library, separate from project assets returned by `tools list-assets`.
 - Download library content: `playcraft library download <assetId> --output <new-path>` saves a file or a complete package directory. `--output-dir <new-directory>` always saves a directory. Packages retain manifests, nested files, and relative dependencies. Download working assets into the project's asset directory; choose `dist/` for final deliverables. Existing output paths are preserved.
 - Layer separation: `playcraft image decompose-layers --input <image> --output-dir <directory>` uses the current workspace layer pipeline and saves a base, separate layers, and metadata with stacking order and bounds. Optional `--prompt`, `--size`, and `--image-model` guide generation. `--engine qwen` selects the legacy pipeline.
@@ -55,7 +65,7 @@ The artifact panel shows final deliverables under `dist/` at the current project
 
 When a generated asset is ready for delivery, save or copy it into `dist/` with a stable relative path. Keep the resources required by a model or document within `dist/` and preserve their relative links. Reuse the same delivery path for a revised artifact so its versions remain grouped; the platform retains its history. Use different paths for independent candidates or deliverables.
 
-Run playable builds from the project root (`playcraft build --mode full --platform playcraft --format html .`). In a workspace this command builds in an isolated copy, validates the result, and retains the playable at `dist/playable/index.html` while preserving other deliverables. A successful agent command or turn that writes a valid self-contained HTML (HyperText Markup Language, 超文本标记语言) file at this same path is collected as the same playable preview. No separate publish action is required to view it. A base build's `dist/index.html` can still require resource files and remains a document. The page's generate-preview action rebuilds the current project through the same validation. Public sharing is a separate explicit action. Temporary `.playcraft-preview-out/` and `.playcraft-temp/` files are not deliverables. Preserve other artifacts already in `dist/` when rebuilding a playable.
+Run playable builds from the project root (`playcraft build --mode full --platform playcraft --format html .`). In a workspace this command builds in an isolated copy, validates the result, and retains the playable at `dist/playable/index.html` while preserving other deliverables. A successful agent command or turn that writes a valid self-contained HTML (HyperText Markup Language, 超文本标记语言) file at this same path is collected as the same playable preview. No separate publish action is required to view it. A base build's `dist/index.html` can still require resource files and remains a document. The page's generate-preview action rebuilds the current project through the same validation. After a successful build the command also publishes the playable and prints `Public URL: <address>`; when you report the build, link that address as the playable instead of the sandbox path, since it opens directly and can be shared. If the command prints `Public URL unavailable`, report that the build succeeded without a public address and give the reason it printed. Temporary `.playcraft-preview-out/` and `.playcraft-temp/` files are not deliverables. Preserve other artifacts already in `dist/` when rebuilding a playable.
 
 Keep this convention in `AGENTS.md`, the project's standard instruction filename. Do not create a separate `AGENT.md`.