@playcraft/cli 0.1.60-beta → 0.1.62-beta

package/dist/commands/build.js

@@ -9,7 +9,8 @@ import inquirer from 'inquirer';
 import { tmpdir } from 'node:os';
 import { generatedWorkspace } from '../workspace-runtime/workspaces/artifact-receipts.js';
 import { isolateWorkspaceForBuild } from '../workspace-runtime/workspaces/delivery-build.js';
-import { finalizeWorkspacePlayable, workspacePlayableSignature } from '../workspace-runtime/previews/finalize.js';
+import { finalizeWorkspacePlayable, readWorkspacePlayable, workspacePlayableSignature } from '../workspace-runtime/previews/finalize.js';
+import { AgentApiClient } from '../utils/agent-api-client.js';
 /**
  * 类型守卫：检查对象是否符合 PlayableScriptsConfig 类型
  */
@@ -268,13 +269,21 @@ export async function buildCommand(projectPath, options) {
                 if (entries.length !== 1 || !entries[0].isFile() || !entries[0].name.endsWith('.html'))
                     throw new Error('preview_not_single_file');
                 await finalizeWorkspacePlayable(workspace.root, await fs.readFile(path.join(output, entries[0].name)), 'playcraft build', { expectedSignature: signature });
+                console.log(path.join(workspace.root, 'dist/playable/index.html'));
+                try {
+                    const { bytes } = await readWorkspacePlayable(workspace.root);
+                    const { previewUrl } = await new AgentApiClient().publishWorkspacePlayable({ workspaceId: workspace.workspaceId, directoryName: path.basename(workspace.root) }, bytes);
+                    console.log(`Public URL: ${previewUrl}`);
+                }
+                catch (error) {
+                    console.warn(`Public URL unavailable: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                return;
             }
-            else {
-                if (options.clean === true)
-                    await fs.rm(requestedOutput, { recursive: true, force: true });
-                await fs.cp(output, requestedOutput, { recursive: true });
-            }
-            console.log(canonicalOutput ? path.join(workspace.root, 'dist/playable/index.html') : requestedOutput);
+            if (options.clean === true)
+                await fs.rm(requestedOutput, { recursive: true, force: true });
+            await fs.cp(output, requestedOutput, { recursive: true });
+            console.log(requestedOutput);
             return;
         }
         finally {

package/dist/project-skills/builtin-import.js

@@ -2,9 +2,9 @@ import { createHash, randomUUID } from 'node:crypto';
 import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { canonicalProjectSkillsJson, declarationDigest, dependencyDigest, extractBundleArchive, readProjectSkillSource, readProjectSkillsLockFile, validateProjectSkillsSnapshot, PROJECT_SKILLS_DECLARATION_PATH, PROJECT_SKILLS_LOCK_PATH, } from '@playcraft/common/project-skills';
-import { LEGACY_VIDEO_SOURCE_HASHES } from '@playcraft/common/cloud-workspace/runtime';
+import { LEGACY_VIDEO_SOURCE_HASHES, WORKSPACE_BUILTIN_SKILL_NAMES } from '@playcraft/common/cloud-workspace/runtime';
 import { projectSkillsCache } from './local-store.js';
-export const IMPORTABLE_BUILTIN_SKILLS = ['playcraft-video-understanding', 'playcraft-replica-validation'];
+export const IMPORTABLE_BUILTIN_SKILLS = WORKSPACE_BUILTIN_SKILL_NAMES;
 export const platformSkillRef = (name) => `remix/${name}`;
 const hash = (value) => createHash('sha256').update(canonicalProjectSkillsJson(value)).digest('hex');
 async function safeDirectory(root, path) {

package/dist/skill-registry/messages.js

@@ -49,7 +49,7 @@ const messages = {
         platform: 'Register native platform skill bundles',
         platformPush: 'Register a native platform draft from a directory or archive without publishing',
         evaluationTemplate: 'Optional evaluation template identifier for the draft',
-        invalidPlatformBundle: 'Expected an unchanged native platform video skill bundle with an aligned manifest and SKILL.md.',
+        invalidPlatformBundle: 'Expected a registered native platform skill bundle with an aligned manifest and SKILL.md.',
         evaluation: 'Configure and run real skill evaluations',
         evaluationTemplates: 'List evaluation runtime templates',
         createTemplate: 'Create an evaluation template draft from a file',
@@ -129,7 +129,7 @@ const messages = {
         platform: '登记原生平台技能包',
         platformPush: '从目录或压缩包登记原生平台草稿，不执行发布',
         evaluationTemplate: '草稿可选使用的评估模板标识',
-        invalidPlatformBundle: '需要原生平台视频技能包，且清单与 SKILL.md 信息一致；不自动改写清单。',
+        invalidPlatformBundle: '需要已登记的原生平台技能包，且清单与 SKILL.md 信息一致；不自动改写清单。',
         evaluation: '配置并执行真实技能评估',
         evaluationTemplates: '列出评估运行模板',
         createTemplate: '根据文件创建评估模板草稿',

package/dist/skill-registry/platform-package.js

@@ -1,12 +1,10 @@
 import { constants, promises as fs } from 'node:fs';
 import { extractBundleArchive } from '@playcraft/common/project-skills';
+import { WORKSPACE_BUILTIN_SKILL_REFS } from '@playcraft/common/cloud-workspace/runtime';
 import yaml from 'js-yaml';
 import { MAX_BUNDLE_BYTES, packSkillDirectory, parseSkillReference, sha256, } from './package.js';
 import { message, RegistryError } from './messages.js';
-const NATIVE_REFS = new Set([
-    'remix/playcraft-video-understanding',
-    'remix/playcraft-replica-validation',
-]);
+const NATIVE_REFS = new Set(WORKSPACE_BUILTIN_SKILL_REFS);
 /** Preserve native manifest bytes; the server remains the authoritative bundle validator. */
 export function inspectNativePlatformArchive(archive) {
     const invalid = () => {

package/dist/utils/agent-api-client.js

@@ -11,6 +11,7 @@ import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
 import { AGENT_TOOL_OPERATION_PROTOCOL, AGENT_TOOL_OPERATION_HEADERS, AGENT_TOOL_OPERATION_CAPABILITIES_PATH, } from '@playcraft/common/agent-tools';
 import { beginToolOperation, findToolOperation } from './tool-operation-journal.js';
 import { businessEndpoint } from './environment-endpoints.js';
+import { PLATFORM_ROUTES } from '@playcraft/common/cloud-workspace/runtime';
 import { cloudRuntimeCredentialHint, isWorkspaceGenerationPath, withGenerationWorkspaceScope } from './generation-workspace-scope.js';
 import { agentGenerationProvenanceHeaders } from './agent-generation-provenance.js';
 import { redactDiagnosticText } from './error-diagnostics.js';
@@ -301,6 +302,27 @@ export class AgentApiClient {
         }
         await response.body?.cancel();
     }
+    /** Publish a workspace's single-file playable through the runtime with the sandbox credential. */
+    async publishWorkspacePlayable(query, html, signal = AbortSignal.timeout(2 * 60_000)) {
+        const url = businessEndpoint(this.apiUrl, PLATFORM_ROUTES.cliPlayablePublications);
+        url.searchParams.set('workspaceId', query.workspaceId);
+        url.searchParams.set('directoryName', query.directoryName);
+        const response = await fetch(url, {
+            method: 'POST', redirect: 'error', signal,
+            headers: { ...this.authHeaders(), 'content-type': 'application/octet-stream' },
+            body: html,
+        });
+        const text = await response.text().catch(() => response.statusText);
+        if (!response.ok) {
+            const reason = responseErrorReason(text) || redactDiagnosticText(response.statusText);
+            throw new Error(`playable_publication_failed:${response.status}${reason ? `: ${reason}` : ''}`);
+        }
+        const previewUrl = JSON.parse(text).previewUrl;
+        if (typeof previewUrl !== 'string' || !/^https?:$/.test(new URL(previewUrl).protocol)) {
+            throw new Error('playable_publication_failed: invalid_public_url');
+        }
+        return { previewUrl };
+    }
     /**
      * 按顺序搜索本地 .playcraft.json 文件（沙箱内或项目目录）。
      * 与全局 login 配置（~/.playcraft/config.json）不同，前者专用于沙箱 token。

package/dist/workspace-runtime/codex/app-server.js

@@ -20,6 +20,7 @@ import { WORKSPACE_UI_TOOLS, WorkspaceUiTools } from './ui-tools.js';
 import { WORKSPACE_DELIVERY_TOOLS, WorkspaceDeliveryTools, isWorkspaceDeliveryTool } from './delivery-tools.js';
 import { WORKSPACE_UI_INSTRUCTIONS } from './ui-instructions.js';
 import { WORKSPACE_SCHEDULED_TASK_TOOLS, WorkspaceScheduledTaskTools, isWorkspaceScheduledTaskTool } from './scheduled-task-tools.js';
+import { PROCEDURAL_3D_TOOL, ProductionSkillTools } from './production-skill-tools.js';
 function withModelShell(config, modelConfigId) {
     if (!modelConfigId || !/^[0-9a-f-]{36}$/i.test(modelConfigId))
         return config;
@@ -195,10 +196,12 @@ export function createCodexAppServerAdapter(options) {
     const scheduledTaskTools = options.scheduledTaskProposals ? new WorkspaceScheduledTaskTools(options.scheduledTaskProposals, (proposalId, source) => emitCollected(collectedEvent('notification', 'scheduled-task.proposal.changed', {
         proposalId, sessionId: threads.get(source.threadId)?.sessionId, threadId: source.threadId, turnId: source.turnId,
     }))) : undefined;
+    const productionSkill = options.productionSkill ? new ProductionSkillTools(options.productionSkill) : undefined;
     const dynamicTools = [
         ...(options.workspaceUi ? WORKSPACE_UI_TOOLS : []),
         ...(deliveryTools ? WORKSPACE_DELIVERY_TOOLS : []),
         ...(scheduledTaskTools ? WORKSPACE_SCHEDULED_TASK_TOOLS : []),
+        ...(productionSkill ? [PROCEDURAL_3D_TOOL] : []),
     ];
     function emitCollected(event) {
         for (const listener of collected)
@@ -599,7 +602,13 @@ export function createCodexAppServerAdapter(options) {
                         approvals.delete(key);
                 }
             }
-            emitCollected(collectedEvent('notification', method, payload));
+            if (method === 'turn/completed' && typeof payload.threadId === 'string'
+                && productionSkill?.hasActive(payload.threadId, String(asRecord(payload.turn).id))) {
+                // Keep the operation's directory lease until the tool's writer has stopped.
+                void productionSkill.cancel(payload.threadId, String(asRecord(payload.turn).id)).then(() => emitCollected(collectedEvent('notification', method, payload)));
+            }
+            else
+                emitCollected(collectedEvent('notification', method, payload));
         });
         rpc.onServerRequest((id, method, params) => {
             const payload = asRecord(params);
@@ -634,6 +643,16 @@ export function createCodexAppServerAdapter(options) {
                     }, 0);
                     return;
                 }
+                if (productionSkill && payload.tool === PROCEDURAL_3D_TOOL.name) {
+                    const trusted = thread?.turnActive && thread.cwd && thread.activeMode === 'execute'
+                        && thread.permissionMode !== 'read-only' && thread.readOnlyConfirmed !== true
+                        && payload.turnId === thread.lastTurnId && typeof payload.threadId === 'string' && typeof payload.turnId === 'string';
+                    void productionSkill.request(id, payload, nativeClient, trusted ? {
+                        sessionId: thread.sessionId, root: thread.cwd,
+                        nativeThreadId: payload.threadId, nativeTurnId: payload.turnId,
+                    } : undefined);
+                    return;
+                }
                 if (deliveryTools && isWorkspaceDeliveryTool(payload.tool)) {
                     void deliveryTools.request(id, payload, nativeClient, {
                         sessionId: thread?.sessionId,
@@ -678,6 +697,7 @@ export function createCodexAppServerAdapter(options) {
             if (live === current) {
                 readyFlag = false;
                 void uiTools.cancel(undefined, 'ui_runtime_disconnected');
+                void productionSkill?.cancel();
                 approvals.clear();
                 // Retain the old handle until its entire execution group is confirmed stopped.
                 rpc = undefined;
@@ -781,6 +801,7 @@ export function createCodexAppServerAdapter(options) {
                 previous.superseded = true;
             readyFlag = false;
             await uiTools.cancel(undefined, 'ui_runtime_disconnected');
+            await productionSkill?.cancel();
             startPromise = undefined;
             threads.clear();
             approvals.clear();
@@ -1267,6 +1288,7 @@ export function createCodexAppServerAdapter(options) {
                 return { outcome: 'failed', error: 'turn_changed' };
             try {
                 await uiTools.cancel(input.threadId);
+                await productionSkill?.cancel(input.threadId, turnId);
                 await rpc.request('turn/interrupt', { threadId: input.threadId, turnId });
                 const cwd = threads.get(input.threadId)?.cwd;
                 if (cwd && (input.expectedTurnId === undefined || threads.get(input.threadId)?.lastTurnId === turnId))
@@ -1327,6 +1349,7 @@ export function createCodexAppServerAdapter(options) {
                 closed = true;
                 readyFlag = false;
                 await uiTools.cancel(undefined, 'ui_runtime_disconnected');
+                await productionSkill?.cancel();
                 approvals.clear();
                 if (live)
                     live.superseded = true;

package/dist/workspace-runtime/codex/config-toml.js

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 const exec = promisify(execFile);
@@ -77,13 +77,17 @@ export async function writePortableCodexCatalog(input) {
     }
     await mkdir(input.directory, { recursive: true });
     const path = join(input.directory, 'portable-models.json');
-    // private
-    await writeFile(path, body, { encoding: 'utf8', mode: 0o644 });
-    // private
-    await writeFile(join(input.directory, 'portable-models.version.json'), JSON.stringify({
+    // shared: public model metadata crosses from the control user to the development user.
+    // Explicit permissions also repair existing files and override a private process umask.
+    await writeFile(path, body, { encoding: 'utf8', mode: 0o644 }); // shared
+    await chmod(path, 0o644);
+    const versionPath = join(input.directory, 'portable-models.version.json');
+    await writeFile(// shared
+    versionPath, JSON.stringify({
         version,
         sha256: createHash('sha256').update(body).digest('hex'),
     }), { encoding: 'utf8', mode: 0o644 });
+    await chmod(versionPath, 0o644);
     return path;
 }
 export async function writePlaycraftCodexConfig(input) {

package/dist/workspace-runtime/codex/delivery-tools.js

@@ -1,11 +1,11 @@
 import { randomUUID } from 'node:crypto';
-import { DELIVERY_CHANNELS, deliveryFormatSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { DELIVERY_CHANNELS, } from '@playcraft/common/cloud-workspace/runtime';
 import { rejectTool, toolContent } from './tool-response.js';
 export const WORKSPACE_DELIVERY_TOOLS = [
     {
         type: 'function',
         name: 'playcraft_build_delivery',
-        description: 'Export channel packages through the PlayCraft platform. This first saves the workspace (commit and push), then exports that commit; each channel reuses the options of its latest export on this branch, or the defaults when it has none. A workspace without a project first gets one, with a private repository, as its first save would. If the result is pending at workspace.save, finish the current turn without polling so the save can run, then continue the export in a later turn. Once build ids are returned, poll playcraft_get_delivery for status, checks and failure details.',
+        description: 'Export channel packages through the PlayCraft platform. This first saves the workspace (commit and push), then exports that commit. Each channel uses the same fixed HTML or ZIP choice as the Export button for that channel and the project engine. Other options reuse the channel\'s latest export on this branch, or the defaults when it has none. A workspace without a project first gets one, with a private repository, as its first save would. If the result is pending at workspace.save, finish the current turn without polling so the save can run, then continue the export in a later turn. Once build ids are returned, poll playcraft_get_delivery for status, checks and failure details.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -16,7 +16,6 @@ export const WORKSPACE_DELIVERY_TOOLS = [
                     maxItems: 8,
                     uniqueItems: true,
                 },
-                format: { type: 'string', enum: ['html', 'zip'] },
             },
             additionalProperties: false,
         },
@@ -71,7 +70,7 @@ export class WorkspaceDeliveryTools {
             await this.reject(client, requestId, 'permission_denied');
             return;
         }
-        const unknown = Object.keys(input).filter(key => key !== 'channels' && key !== 'format');
+        const unknown = Object.keys(input).filter(key => key !== 'channels');
         if (unknown.length) {
             await this.reject(client, requestId, 'invalid_delivery_tool_arguments');
             return;
@@ -83,11 +82,6 @@ export class WorkspaceDeliveryTools {
             await this.reject(client, requestId, 'invalid_delivery_tool_arguments');
             return;
         }
-        const format = input.format === undefined ? undefined : deliveryFormatSchema.safeParse(input.format);
-        if (format && !format.success) {
-            await this.reject(client, requestId, 'invalid_delivery_tool_arguments');
-            return;
-        }
         try {
             const result = await this.handlers.build({
                 ...context,
@@ -95,7 +89,6 @@ export class WorkspaceDeliveryTools {
                     ? payload.callId
                     : randomUUID(),
                 channels: channels,
-                ...(format && format.success ? { format: format.data } : {}),
             });
             await this.respond(client, requestId, result);
         }

package/dist/workspace-runtime/codex/launcher-client.js

@@ -38,18 +38,7 @@ export async function stopLauncherProcess(input) {
     if (!input.instanceId)
         throw new Error('launcher_start_unconfirmed');
     const { socketPath, ...identity } = input;
-    // A new launcher's empty registry cannot confirm an old group's exit.
-    for (const signal of ['SIGTERM', 'SIGKILL']) {
-        await request(socketPath, { ...identity, action: 'stop', signal });
-        const deadline = Date.now() + 3000;
-        while (Date.now() < deadline) {
-            const status = await request(socketPath, { ...identity, action: 'status' });
-            if (status.running === false)
-                return;
-            await delay(50);
-        }
-    }
-    throw new Error('codex_group_stop_unconfirmed');
+    await stopLauncherExecution(socketPath, identity);
 }
 /** The private launcher owns the boundary; development shells never receive its identity. */
 export async function prepareLauncherOrigin(input) {
@@ -69,6 +58,24 @@ export async function verifyLauncherOrigin(input) {
         return false;
     }
 }
+/** Recovered writers need a receipt from the same launcher, not just an absent process id. */
+export async function stopLauncherExecution(socketPath, identity) {
+    if (!identity || typeof identity.processId !== 'string' || !identity.processId ||
+        typeof identity.instanceId !== 'string' || !identity.instanceId ||
+        !Number.isSafeInteger(identity.runtimeEpoch) || identity.runtimeEpoch < 0)
+        throw new Error('launcher_execution_identity_invalid');
+    for (const signal of ['SIGTERM', 'SIGKILL']) {
+        await request(socketPath, { ...identity, action: 'stop', signal });
+        const deadline = Date.now() + 3000;
+        while (Date.now() < deadline) {
+            const status = await request(socketPath, { ...identity, action: 'status' });
+            if (status.running === false)
+                return;
+            await delay(50);
+        }
+    }
+    throw new Error('codex_group_stop_unconfirmed');
+}
 export async function startLauncherProcess(input) {
     const socket = createConnection(input.socketPath);
     const stdout = new PassThrough();
@@ -167,8 +174,13 @@ export async function startLauncherProcess(input) {
         });
     });
     return {
-        identity: identity,
+        identity,
         pid,
+        executionIdentity: {
+            processId: identity.processId,
+            runtimeEpoch: identity.runtimeEpoch,
+            instanceId: identity.instanceId,
+        },
         stdin,
         stdout,
         stderr,

package/dist/workspace-runtime/codex/model-broker.js

@@ -17,6 +17,7 @@ const credentialSchema = z.object({
         generation: z.number().int(), runtimeEpoch: z.number().int(),
     }),
 });
+const MAX_MODEL_REQUEST_BYTES = 128 * 1024 * 1024;
 /** Keeps renewable execution credentials in control memory, outside Codex and project files. */
 export class WorkspaceModelBroker {
     state;
@@ -213,6 +214,16 @@ export class WorkspaceModelBroker {
                 await this.references.forward(request, response, selected.feedback, () => this.valid(entry) && route?.selected === selected);
                 return;
             }
+            const rejectOversizedBody = () => {
+                response.writeHead(413, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+                response.end(JSON.stringify({ error: { message: 'model_request_too_large',
+                        type: 'invalid_request_error', code: 'model_request_too_large', maxBytes: MAX_MODEL_REQUEST_BYTES } }));
+            };
+            const declaredLength = request.headers['content-length'];
+            if (declaredLength !== undefined && /^\d+$/.test(declaredLength) && Number(declaredLength) > MAX_MODEL_REQUEST_BYTES) {
+                rejectOversizedBody();
+                return;
+            }
             activeRoute = route;
             const active = this.sessionRequests.get(route) ?? new Set();
             active.add(abort);
@@ -222,9 +233,8 @@ export class WorkspaceModelBroker {
             let size = 0;
             for await (const chunk of request) {
                 size += chunk.length;
-                if (size > 16 * 1024 * 1024) {
-                    response.writeHead(413);
-                    response.end();
+                if (size > MAX_MODEL_REQUEST_BYTES) {
+                    rejectOversizedBody();
                     return;
                 }
                 chunks.push(Buffer.from(chunk));

package/dist/workspace-runtime/codex/production-skill-tools.js

@@ -0,0 +1,95 @@
+import { rejectTool, toolContent } from './tool-response.js';
+export const PROCEDURAL_3D_TOOL = {
+    type: 'function',
+    name: 'playcraft_procedural_3d',
+    description: 'Run the enabled, explicitly selected procedural 3D skill using its locked tools. Read that skill for action inputs. prepare freezes a local reference; adapter actions operate in the returned run directory; capture freezes and renders a candidate; review records observations against that candidate; adopt copies only the reviewed bytes. Calls require an exclusive execution turn. A requires_exclusive_turn result requires selecting the skill in a new turn.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: [
+                    'describe',
+                    'preflight',
+                    'prepare',
+                    'status',
+                    'recover',
+                    'next',
+                    'run-step',
+                    'request-correction',
+                    'capture',
+                    'review',
+                    'adopt',
+                ],
+            },
+            runId: { type: 'string' },
+            expectedRevision: { type: 'integer', minimum: 0 },
+            input: { type: 'object' },
+        },
+        required: ['action'],
+        additionalProperties: false,
+    },
+};
+/** Only the host may attach a validated workspace-relative diagnostic report. */
+export class ProductionSkillFailure extends Error {
+    reportPath;
+    constructor(reason, reportPath) {
+        super(reason);
+        this.reportPath = reportPath;
+    }
+}
+/** Native turn identity is supplied by the app-server adapter, never by tool arguments. */
+export class ProductionSkillTools {
+    handler;
+    active = new Map();
+    constructor(handler) {
+        this.handler = handler;
+    }
+    hasActive(threadId, turnId) {
+        return [...this.active.values()].some((item) => (!threadId || item.context.nativeThreadId === threadId) &&
+            (!turnId || item.context.nativeTurnId === turnId));
+    }
+    async request(id, payload, client, context) {
+        if (!context)
+            return rejectTool(client, id, 'procedural_skill_inactive_turn');
+        const key = `${context.nativeThreadId}:${context.nativeTurnId}`;
+        if (this.active.has(key))
+            return rejectTool(client, id, 'procedural_skill_busy');
+        const abort = new AbortController();
+        let finish;
+        const done = new Promise((resolve) => {
+            finish = resolve;
+        });
+        this.active.set(key, { context, abort, done });
+        try {
+            const result = await this.handler(payload.arguments, context, abort.signal);
+            await client.respond(id, { success: true, contentItems: toolContent(result) });
+        }
+        catch (error) {
+            const reason = error instanceof Error && /^[a-z][a-z0-9_:\-]{0,160}$/.test(error.message)
+                ? error.message
+                : 'procedural_skill_failed';
+            if (error instanceof ProductionSkillFailure) {
+                await client
+                    .respond(id, {
+                    success: false,
+                    contentItems: toolContent({ status: 'failed', reason, reportPath: error.reportPath }),
+                })
+                    .catch(() => undefined);
+                return;
+            }
+            await rejectTool(client, id, reason);
+        }
+        finally {
+            this.active.delete(key);
+            finish();
+        }
+    }
+    async cancel(threadId, turnId) {
+        const pending = [...this.active.values()].filter((item) => (!threadId || item.context.nativeThreadId === threadId) &&
+            (!turnId || item.context.nativeTurnId === turnId));
+        for (const item of pending)
+            item.abort.abort();
+        await Promise.allSettled(pending.map((item) => item.done));
+    }
+}

package/dist/workspace-runtime/processes/skill-command.js

@@ -0,0 +1,130 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { startLauncherProcess } from '../codex/launcher-client.js';
+import { launcherSocket } from '../workspaces/developer-command.js';
+import { holdDirectoryAccess } from '../server/directory-access.js';
+import { stopBackgroundWriter } from './managed-writes.js';
+/** Structured process invocation under the caller's exclusive directory owner. */
+export async function runSkillCommand(state, input) {
+    if (input.signal.aborted)
+        throw new Error('procedural_skill_cancelled');
+    const writeId = `skill-${randomUUID()}`;
+    const release = await holdDirectoryAccess(state, input.scope, `managed:${writeId}`, 'exclusive');
+    const record = {
+        writeId,
+        workspaceId: state.config.workspaceMode === 'multi'
+            ? `${input.scope.workspaceId}:${input.scope.directoryName ?? 'basic'}`
+            : 'basic',
+        source: 'agent',
+        directoryAccessMode: 'exclusive',
+        startedAt: new Date().toISOString(),
+    };
+    let child;
+    let stopped = true;
+    let timeout = false;
+    let oversized = false;
+    let timer;
+    const abort = () => {
+        void child?.stop().catch(() => undefined);
+    };
+    try {
+        await state.journal.putManagedWrite(record);
+        if (input.signal.aborted)
+            throw new Error('procedural_skill_cancelled');
+        const socketPath = launcherSocket(state);
+        if (socketPath) {
+            stopped = false;
+            child = await startLauncherProcess({
+                socketPath,
+                processId: writeId,
+                runtimeEpoch: state.runtimeEpoch,
+                // Development outputs must remain readable by the workspace control group even when
+                // the private launcher starts with umask 077. Keep arguments literal and this mask local.
+                argv: ['/usr/bin/bash', '-c', 'umask 007; exec "$@"', 'playcraft-skill', ...input.argv],
+                cwd: input.cwd,
+                env: { PYTHONDONTWRITEBYTECODE: '1' },
+            });
+        }
+        else {
+            const local = spawn(input.argv[0], input.argv.slice(1), {
+                cwd: input.cwd,
+                detached: true,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1' },
+            });
+            stopped = !local.pid;
+            child = {
+                pid: local.pid,
+                stdin: local.stdin,
+                stdout: local.stdout,
+                stderr: local.stderr,
+                onExit(listener) {
+                    local.once('error', () => listener(null));
+                    local.once('close', listener);
+                },
+                async stop() {
+                    if (local.pid && !(await stopBackgroundWriter(local.pid)))
+                        throw new Error('procedural_skill_stop_unconfirmed');
+                },
+            };
+        }
+        // Attach exit listeners before asynchronous persistence: short commands can finish immediately.
+        const exit = new Promise((resolve) => child.onExit(resolve));
+        let stdout = '', stderr = '';
+        const collect = (stream, chunk) => {
+            if (stream === 'stdout')
+                stdout += chunk.toString();
+            else
+                stderr += chunk.toString();
+            if (stdout.length > 4 * 1024 * 1024 || stderr.length > 1024 * 1024) {
+                oversized = true;
+                abort();
+            }
+        };
+        child.stdout?.on('data', (chunk) => collect('stdout', chunk));
+        child.stderr?.on('data', (chunk) => collect('stderr', chunk));
+        child.stdin?.on('error', () => undefined);
+        await state.journal.putManagedWrite({ ...record, pid: child.pid });
+        input.signal.addEventListener('abort', abort, { once: true });
+        timer = setTimeout(() => {
+            timeout = true;
+            abort();
+        }, input.timeoutMs ?? 120_000);
+        if (input.signal.aborted)
+            abort();
+        else
+            child.stdin?.end(JSON.stringify(input.input));
+        const code = await exit;
+        await child.stop();
+        stopped = true;
+        if (input.signal.aborted)
+            throw new Error('procedural_skill_cancelled');
+        if (timeout)
+            throw new Error('procedural_skill_timeout');
+        if (oversized)
+            throw new Error('procedural_skill_output_limit');
+        return { stdout, stderr, code };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        input.signal.removeEventListener('abort', abort);
+        if (child && !stopped) {
+            try {
+                await child.stop();
+                stopped = true;
+            }
+            catch {
+                /* retain the writer claim */
+            }
+        }
+        if (stopped) {
+            await state.journal.putManagedWrite({
+                ...record,
+                pid: child?.pid,
+                stoppedAt: new Date().toISOString(),
+            });
+            release();
+        }
+    }
+}

package/dist/workspace-runtime/serve.js

@@ -34,6 +34,8 @@ import { loadWorkspaceMcpConfig } from './codex/mcp-config.js';
 import { startSourceEventUploader, stopSourceEventUploader } from './server/source-uploader.js';
 import { platformExportTarget, readPlatformExport, startPlatformExport } from './workspaces/platform-export.js';
 import { scheduledTaskProposalHandler } from './workspaces/scheduled-task-proposals.js';
+import { proceduralSkillHandler } from './workspaces/procedural-3d/host.js';
+import { recoverModelPreviewOperations } from './workspaces/procedural-3d/model-preview-recovery.js';
 export async function startWorkspaceRuntime(config, options = {}) {
     process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
     const negotiated = negotiateProtocol(config);
@@ -55,7 +57,11 @@ export async function startWorkspaceRuntime(config, options = {}) {
         const previousEpoch = journal.storedRuntimeEpoch();
         const previousGroup = journal.executionGroup();
         const previousIdentityMatches = journal.epochsSnapshot().some((epoch) => epoch.runtime_id === config.runtimeId && epoch.generation === config.generation && epoch.runtime_epoch === previousEpoch);
-        await recoverInterruptedInstalls(journal);
+        await recoverInterruptedInstalls(journal, {
+            runtimeEpoch: config.runtimeEpoch, previousRuntimeEpoch: previousEpoch, identityMatches: previousIdentityMatches,
+            ...(config.workspaceMode === 'multi' && process.env.PLAYCRAFT_LAUNCHER_SOCKET
+                ? { launcherSocket: process.env.PLAYCRAFT_LAUNCHER_SOCKET } : {}),
+        });
         await recoverInterruptedPreviews(journal);
         await recoverInterruptedParameterVerifications(journal);
         await recoverInterruptedDeliveries(config.stateDir);
@@ -74,6 +80,10 @@ export async function startWorkspaceRuntime(config, options = {}) {
             instanceToken: randomUUID(),
         };
         const recoveredImports = new Map();
+        await recoverModelPreviewOperations(state, { identityMatches: previousIdentityMatches,
+            runtimeEpoch: config.runtimeEpoch, previousRuntimeEpoch: previousEpoch,
+            ...(config.workspaceMode === 'multi' && process.env.PLAYCRAFT_LAUNCHER_SOCKET
+                ? { launcherSocket: process.env.PLAYCRAFT_LAUNCHER_SOCKET } : {}) });
         const recoveredChanges = [];
         const recoveredWrites = [];
         const recoverLibraryImports = async (root) => {
@@ -414,6 +424,7 @@ function defaultNativeAdapter(state) {
             workspaceUi: true,
             deliveryTools: deliveryToolHandlers(state),
             scheduledTaskProposals: scheduledTaskProposalHandler(state),
+            productionSkill: proceduralSkillHandler(state),
             ...(multi ? { modelBroker: new WorkspaceModelBroker(state) } : {}),
             ...(multi ? { loadMcpConfig: async (cwd) => {
                     const { workspaceId } = await workspaceContextFromRoot(state, cwd);