@playcraft/cli 0.1.85-beta → 0.1.87

package/dist/commands/tools-generation.js

@@ -3,8 +3,8 @@ import { writeFileSync, mkdirSync } from 'fs';
 import { dirname, parse, join } from 'path';
 import sharp from 'sharp';
 import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifact-receipts.js';
-import { resolveImageBackgroundRequirement, validateImageDeliveryOptions } from '@playcraft/common/prefab';
-import { assertImageAssetOutputPaths, readImageAssetContext } from '../utils/image-asset-context.js';
+import { resolveImageBackgroundRequirement, validateImageDeliveryOptions, } from '@playcraft/common/prefab';
+import { assertImageAssetOutputPaths, readImageAssetContext, } from '../utils/image-asset-context.js';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 import { isUnsafeImageRetryError } from '../utils/image-generation-retry.js';
 import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, parseImageTargetFieldPath, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, raceWithTimeout, } from './tools-utils.js';
@@ -73,7 +73,8 @@ async function verifyMasterCompositeStripSize(imgBuf, target) {
 }
 export function registerGenerationCommands(tools) {
     // ─── Image Models ────────────────────────────────────────────
-    tools.command('list-image-models')
+    tools
+        .command('list-image-models')
         .description('列出后端已配置的可用生图模型，按模型名分组展示所有 provider（多个 provider 时按优先级自动 fallback）')
         .option('--json', '以 JSON 格式输出（默认为人类可读表格）')
         .action(async (opts) => {
@@ -150,7 +151,8 @@ export function registerGenerationCommands(tools) {
         }
     });
     // ─── Generation ─────────────────────────────────────────────
-    tools.command('generate-image')
+    tools
+        .command('generate-image')
         .description('AI 生成图片（支持多张参考图图生图；gpt-image-2 支持 --count N 批量出图）')
         .requiredOption('--prompt <text>', '图片描述')
         .option('--aspect-ratio <ratio>', '宽高比 (1:1|45:16|16:9|9:16|3:4|4:3|2:3|3:2|21:9)', '1:1')
@@ -174,8 +176,12 @@ export function registerGenerationCommands(tools) {
         .option('--count <n>', '一次 API 调用生成多少张图片（默认 1，最多 10；仅 gpt-image-2 实际支持批量）', (v) => parseInt(v, 10), 1)
         .action(async (opts) => {
         try {
-            const explicitBackground = opts.background === undefined ? opts.removeBackground : opts.background === 'transparent';
-            if (opts.background !== undefined && opts.removeBackground !== undefined && opts.removeBackground !== explicitBackground) {
+            const explicitBackground = opts.background === undefined
+                ? opts.removeBackground
+                : opts.background === 'transparent';
+            if (opts.background !== undefined &&
+                opts.removeBackground !== undefined &&
+                opts.removeBackground !== explicitBackground) {
                 throw new Error('Conflicting background options. Use --background transparent or --background opaque; no image request was sent.');
             }
             opts = { ...opts, removeBackground: explicitBackground };
@@ -184,28 +190,46 @@ export function registerGenerationCommands(tools) {
             }
             const explicitOutputFormat = opts.outputFormat;
             const { dir: outputDir, name: outputName, ext: outputExt } = parse(opts.output);
-            const outputCandidates = [opts.output, ...Array.from({ length: opts.count > 1 ? Math.min(opts.count, 10) : 0 }, (_, i) => join(outputDir, `${outputName}_${i + 1}${outputExt}`))];
-            const assetContext = opts.targetAsset ? await readImageAssetContext(opts.targetAsset, process.cwd(), {
-                referenceImagePaths: opts.referenceImage, useTargetReference: opts.targetReference,
-                ...(opts.targetFieldPath ? { targetFieldPath: opts.targetFieldPath } : {}),
-                outputPaths: outputCandidates,
-                prompt: opts.prompt, removeBackground: opts.removeBackground,
-            }) : undefined;
-            opts = { ...opts,
+            const outputCandidates = [
+                opts.output,
+                ...Array.from({ length: opts.count > 1 ? Math.min(opts.count, 10) : 0 }, (_, i) => join(outputDir, `${outputName}_${i + 1}${outputExt}`)),
+            ];
+            const assetContext = opts.targetAsset
+                ? await readImageAssetContext(opts.targetAsset, process.cwd(), {
+                    referenceImagePaths: opts.referenceImage,
+                    useTargetReference: opts.targetReference,
+                    ...(opts.targetFieldPath ? { targetFieldPath: opts.targetFieldPath } : {}),
+                    outputPaths: outputCandidates,
+                    prompt: opts.prompt,
+                    removeBackground: opts.removeBackground,
+                })
+                : undefined;
+            opts = {
+                ...opts,
                 aspectRatio: assetContext?.aspectRatio ?? opts.aspectRatio,
-                width: assetContext?.width ?? opts.width, height: assetContext?.height ?? opts.height,
-                outputFormat: assetContext?.outputFormatFromSchema ? assetContext.outputFormat : opts.outputFormat ?? assetContext?.outputFormat,
+                width: assetContext?.width ?? opts.width,
+                height: assetContext?.height ?? opts.height,
+                outputFormat: assetContext?.outputFormatFromSchema
+                    ? assetContext.outputFormat
+                    : (opts.outputFormat ?? assetContext?.outputFormat),
                 fitMode: assetContext?.fitMode ?? opts.fitMode,
-                removeBackground: resolveImageBackgroundRequirement({ prompt: opts.prompt,
-                    schemaRemoveBackground: assetContext?.removeBackgroundFromSchema ? assetContext.removeBackground : undefined,
-                    removeBackground: opts.removeBackground, fallbackRemoveBackground: assetContext?.removeBackground }),
+                removeBackground: resolveImageBackgroundRequirement({
+                    prompt: opts.prompt,
+                    schemaRemoveBackground: assetContext?.removeBackgroundFromSchema
+                        ? assetContext.removeBackground
+                        : undefined,
+                    removeBackground: opts.removeBackground,
+                    fallbackRemoveBackground: assetContext?.removeBackground,
+                }),
                 paddingColor: assetContext?.paddingColor ?? opts.paddingColor,
                 imageModel: opts.imageModel || assetContext?.imageModelRef,
             };
             const invalidDelivery = validateImageDeliveryOptions(opts);
             if (invalidDelivery)
                 throw new Error(invalidDelivery);
-            const paths = opts.referenceImage?.length ? opts.referenceImage : assetContext?.referenceImagePaths ?? [];
+            const paths = opts.referenceImage?.length
+                ? opts.referenceImage
+                : (assetContext?.referenceImagePaths ?? []);
             if (paths.length > MAX_REFERENCE_IMAGES) {
                 console.error(`Error: Too many reference images: ${paths.length} paths given; maximum is ${MAX_REFERENCE_IMAGES}.`);
                 process.exit(1);
@@ -230,14 +254,26 @@ export function registerGenerationCommands(tools) {
                     width: assetContext?.width ?? opts.width,
                     height: assetContext?.height ?? opts.height,
                     outputFormat: opts.outputFormat,
-                    outputFormatSource: assetContext?.outputFormatFromSchema ? 'schema'
-                        : explicitOutputFormat ? 'explicit' : assetContext ? 'inferred' : undefined,
+                    outputFormatSource: assetContext?.outputFormatFromSchema
+                        ? 'schema'
+                        : explicitOutputFormat
+                            ? 'explicit'
+                            : assetContext
+                                ? 'inferred'
+                                : undefined,
                     fitMode: assetContext?.fitMode ?? opts.fitMode,
                     paddingColor: assetContext?.paddingColor ?? opts.paddingColor,
-                    background: opts.background === undefined ? undefined : opts.removeBackground ? 'transparent' : 'opaque',
+                    background: opts.background === undefined
+                        ? undefined
+                        : opts.removeBackground
+                            ? 'transparent'
+                            : 'opaque',
                     removeBackground: opts.removeBackground,
-                    backgroundRequirementSource: assetContext?.removeBackgroundFromSchema ? 'schema'
-                        : explicitBackground !== undefined ? 'explicit' : 'inferred',
+                    backgroundRequirementSource: assetContext?.removeBackgroundFromSchema
+                        ? 'schema'
+                        : explicitBackground !== undefined
+                            ? 'explicit'
+                            : 'inferred',
                     referenceImages,
                     ...(modelRef ? { imageModelRef: modelRef } : {}),
                     ...(imageCount > 1 ? { imageCount } : {}),
@@ -265,7 +301,8 @@ export function registerGenerationCommands(tools) {
                     lines.push('  → Try --image-size 1K to reduce generation time');
                     lines.push('  → Or increase timeout with --timeout <seconds> (current default: 1800s)');
                 }
-                else if (hasReferenceImages && (msg.includes('reference') || msg.includes('image input'))) {
+                else if (hasReferenceImages &&
+                    (msg.includes('reference') || msg.includes('image input'))) {
                     lines.push('');
                     lines.push('Hint: Reference image error — the selected model may not support --reference-image.');
                     lines.push('  → Run: playcraft tools list-image-models');
@@ -313,7 +350,11 @@ export function registerGenerationCommands(tools) {
             }
             // 收集所有待保存图片（第 1 张 + 批量额外图）
             const allImages = [
-                { imageBase64: result.imageBase64, mimeType: result.mimeType, previewUrl: result.previewUrl },
+                {
+                    imageBase64: result.imageBase64,
+                    mimeType: result.mimeType,
+                    previewUrl: result.previewUrl,
+                },
                 ...(result.additionalImages ?? []),
             ];
             const isBatch = allImages.length > 1;
@@ -324,12 +365,14 @@ export function registerGenerationCommands(tools) {
             const savedPaths = [];
             if (result.transparencySource)
                 console.log(`Transparency source: ${result.transparencySource}`);
-            const stripTarget = opts.targetAsset || result.transparentBackground ? null : resolveStripTargetDimensions({
-                aspectRatio: opts.aspectRatio,
-                width: opts.width,
-                height: opts.height,
-                imageSize: opts.imageSize,
-            });
+            const stripTarget = opts.targetAsset || result.transparentBackground
+                ? null
+                : resolveStripTargetDimensions({
+                    aspectRatio: opts.aspectRatio,
+                    width: opts.width,
+                    height: opts.height,
+                    imageSize: opts.imageSize,
+                });
             for (let i = 0; i < allImages.length; i++) {
                 const img = allImages[i];
                 let imgBuf = Buffer.from(img.imageBase64, 'base64');
@@ -347,8 +390,7 @@ export function registerGenerationCommands(tools) {
                     generatedHeight = metaBefore.height;
                     if (metaBefore.width != null &&
                         metaBefore.height != null &&
-                        (metaBefore.width !== stripTarget.width ||
-                            metaBefore.height !== stripTarget.height)) {
+                        (metaBefore.width !== stripTarget.width || metaBefore.height !== stripTarget.height)) {
                         imgBuf = Buffer.from(await letterboxToTarget(imgBuf, stripTarget.width, stripTarget.height));
                         console.log(`↑ Letterbox ${generatedWidth}×${generatedHeight} → ${stripTarget.width}×${stripTarget.height}（等比 + 白边，不拉伸）`);
                     }
@@ -404,10 +446,11 @@ export function registerGenerationCommands(tools) {
                     referenceImageStatus: result.referenceImageStatus ?? null,
                     generatedAt: new Date().toISOString(),
                 };
-                const sidecarPath = resolvedPath.replace(/\.[^.]+$/, '.json');
+                const sidecarPath = `${resolvedPath}.generation.json`;
                 writeFileSync(sidecarPath, JSON.stringify(sidecar, null, 2));
                 await captureGeneratedArtifact(resolvedPath, 'generate-image', {
-                    ...(actualWidth ? { width: actualWidth } : {}), ...(actualHeight ? { height: actualHeight } : {}),
+                    ...(actualWidth ? { width: actualWidth } : {}),
+                    ...(actualHeight ? { height: actualHeight } : {}),
                 });
                 console.log(`  └─ Generation metadata: ${sidecarPath}`);
             }
@@ -431,7 +474,8 @@ export function registerGenerationCommands(tools) {
             handleError(e);
         }
     });
-    tools.command('generate-sfx')
+    tools
+        .command('generate-sfx')
         .description('AI 生成音效（SFX），使用 ElevenLabs Sound Effects')
         .requiredOption('--prompt <text>', '音效描述，仅英文，如 "crisp UI click, short tail, no voice"')
         .option('--duration <seconds>', '时长（秒，0.5-22；省略时由供应商自动决定）', parseFloat)
@@ -451,9 +495,14 @@ export function registerGenerationCommands(tools) {
             const sizeKB = Math.round(buf.length / 1024);
             console.log(`SFX saved to ${opts.output} (${sizeKB}KB, ${result.duration.toFixed(2)}s, provider=${result.provider})`);
             const sfxSidecar = {
-                type: 'sfx', prompt: opts.prompt, duration: opts.duration ?? null,
-                loop: opts.loop ?? false, provider: result.provider, actualDuration: result.duration,
-                output: opts.output, generatedAt: new Date().toISOString(),
+                type: 'sfx',
+                prompt: opts.prompt,
+                duration: opts.duration ?? null,
+                loop: opts.loop ?? false,
+                provider: result.provider,
+                actualDuration: result.duration,
+                output: opts.output,
+                generatedAt: new Date().toISOString(),
             };
             writeFileSync(opts.output.replace(/\.[^.]+$/, '.json'), JSON.stringify(sfxSidecar, null, 2));
             await captureGeneratedArtifact(opts.output, 'generate-sfx', { duration: result.duration });
@@ -463,7 +512,8 @@ export function registerGenerationCommands(tools) {
             handleError(e);
         }
     });
-    tools.command('generate-bgm')
+    tools
+        .command('generate-bgm')
         .description('AI 生成 BGM（30s 循环），使用 Google Lyria 3')
         .requiredOption('--prompt <text>', 'BGM 描述，如 "轻快休闲游戏配乐"')
         .option('--style <style>', '音乐风格，如 casual / epic / sci-fi / retro')
@@ -484,9 +534,14 @@ export function registerGenerationCommands(tools) {
             const sizeKB = Math.round(buf.length / 1024);
             console.log(`BGM saved to ${opts.output} (${sizeKB}KB, ${result.duration.toFixed(2)}s, provider=${result.provider})`);
             const bgmSidecar = {
-                type: 'bgm', prompt: opts.prompt, style: opts.style ?? null,
-                bpm: opts.bpm ?? null, provider: result.provider, actualDuration: result.duration,
-                output: opts.output, generatedAt: new Date().toISOString(),
+                type: 'bgm',
+                prompt: opts.prompt,
+                style: opts.style ?? null,
+                bpm: opts.bpm ?? null,
+                provider: result.provider,
+                actualDuration: result.duration,
+                output: opts.output,
+                generatedAt: new Date().toISOString(),
             };
             writeFileSync(opts.output.replace(/\.[^.]+$/, '.json'), JSON.stringify(bgmSidecar, null, 2));
             await captureGeneratedArtifact(opts.output, 'generate-bgm', { duration: result.duration });
@@ -517,7 +572,8 @@ export function registerGenerationCommands(tools) {
         }
     });
     // ─── Search Image ──────────────────────────────────────────
-    tools.command('search-image')
+    tools
+        .command('search-image')
         .description('搜索参考图片（Unsplash / Pexels），结果 URL 可直接用于 --reference-image')
         .requiredOption('--query <query>', '搜索关键词（建议英文）')
         .option('--source <source>', '图源：unsplash | pexels | auto（默认 auto）', 'auto')

package/dist/commands/tools-request.js

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+export async function toolRequestCommand(operation, serializedBody) {
+    if (!['generate-image', 'generate-bgm', 'generate-sfx'].includes(operation))
+        throw new Error('Unsupported generation operation');
+    const body = JSON.parse(serializedBody);
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        throw new Error('Generation request must be a JSON object');
+    return new AgentApiClient({
+        configFile: process.env.PLAYCRAFT_SANDBOX_CONFIG_PATH || join(process.cwd(), '.playcraft.json'),
+        operationNamespace: 'opencode',
+    }).post(`/${operation}`, body);
+}
+/** Static sandbox plugins cannot import command-line modules; use this client for transport. */
+export function registerToolRequestCommand(tools) {
+    tools
+        .command('request <operation>', { hidden: true })
+        .description('Send a generation request from JSON on stdin and print its durable result as JSON')
+        .action(async (operation) => {
+        const result = await toolRequestCommand(operation, readFileSync(0, 'utf8'));
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+    });
+}

package/dist/commands/tools-utils.js

@@ -1,5 +1,5 @@
 import { writeFileSync, mkdirSync, readFileSync } from 'fs';
-import { join, parse } from 'path';
+import { join, parse, resolve } from 'path';
 import { tmpdir } from 'os';
 import { InvalidArgumentError } from 'commander';
 export const TMP_DIR = join(tmpdir(), 'playcraft');
@@ -9,8 +9,12 @@ export function parseImageTargetFieldPath(value) {
     try {
         parsed = JSON.parse(value);
     }
-    catch { /* Report the expected shape below. */ }
-    if (!Array.isArray(parsed) || !parsed.length || parsed.some(key => typeof key !== 'string' || !key.length)) {
+    catch {
+        /* Report the expected shape below. */
+    }
+    if (!Array.isArray(parsed) ||
+        !parsed.length ||
+        parsed.some((key) => typeof key !== 'string' || !key.length)) {
         throw new InvalidArgumentError('Expected an array of field names, e.g. ["endUI","playButton"].');
     }
     return parsed;
@@ -74,11 +78,7 @@ export function extensionForImageMime(mimeType) {
  * Detect container from decoded bytes (magic). Prefer this over MIME alone.
  */
 export function sniffImageExtension(buf) {
-    if (buf.length >= 8 &&
-        buf[0] === 0x89 &&
-        buf[1] === 0x50 &&
-        buf[2] === 0x4e &&
-        buf[3] === 0x47) {
+    if (buf.length >= 8 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
         return '.png';
     }
     if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
@@ -133,12 +133,14 @@ export function mimeTypeForImagePath(filePath) {
         return 'image/png';
     if (ext === 'webp')
         return 'image/webp';
+    if (ext === 'gif')
+        return 'image/gif';
     if (ext === 'jpg' || ext === 'jpeg')
         return 'image/jpeg';
     if (ext === undefined || ext === '') {
         throw new Error(`Reference image path has no file extension: ${filePath}. Use .png, .webp, .jpg, or .jpeg.`);
     }
-    throw new Error(`Unsupported reference image extension ".${ext}" in ${filePath}. Only png, webp, jpg, and jpeg are allowed.`);
+    throw new Error(`Unsupported reference image extension ".${ext}" in ${filePath}. Only png, webp, jpg, jpeg, and gif are allowed.`);
 }
 async function downloadImageFromUrl(url) {
     let res;
@@ -155,7 +157,8 @@ async function downloadImageFromUrl(url) {
     const contentType = res.headers.get('content-type') ?? '';
     const mimeType = contentType.split(';')[0].trim() || 'image/png';
     const allowed = ['image/png', 'image/jpeg', 'image/webp', 'image/gif'];
-    if (!allowed.some((t) => mimeType.startsWith(t.split('/')[0]) && mimeType.includes('/')) || !mimeType.startsWith('image/')) {
+    if (!allowed.some((t) => mimeType.startsWith(t.split('/')[0]) && mimeType.includes('/')) ||
+        !mimeType.startsWith('image/')) {
         throw new Error(`参考图 URL 返回的 Content-Type 不是图片（${mimeType}）：${url}\n  只支持 PNG / JPG / WEBP / GIF。`);
     }
     const buf = await res.arrayBuffer();
@@ -178,18 +181,13 @@ export async function collectReferenceImagePayloads(paths) {
             }
             else {
                 const mimeType = mimeTypeForImagePath(p);
-                out.push({ base64: readFileSync(p).toString('base64'), mimeType });
+                out.push({ base64: readFileSync(resolve(process.cwd(), p)).toString('base64'), mimeType });
             }
         }
         catch (e) {
             const detail = e instanceof Error ? e.message : String(e);
-            const code = !isUrl && e && typeof e === 'object' && 'code' in e ? String(e.code) : '';
-            const hint = code ? ` (${code})` : '';
-            console.warn(`Skipping reference image (load failed): ${p}${hint}\n  ${detail}`);
+            throw new Error(`Could not load reference image "${p}": ${detail}. No image request was sent.`);
         }
     }
-    if (paths.length > 0 && out.length === 0) {
-        console.warn('All reference images failed to load; continuing with text-only generation.');
-    }
     return out.length > 0 ? out : undefined;
 }

package/dist/commands/tools.js

@@ -6,11 +6,13 @@ import { registerDetectCommand } from './tools-detect.js';
 import { registerVideoReviewCommand } from './tools-video-review.js';
 import { registerImageContextCommand } from './tools-image-context.js';
 import { registerContextCommands } from './tools-context.js';
+import { registerToolRequestCommand } from './tools-request.js';
 export function registerToolsCommands(program) {
     const tools = program
         .command('tools')
         .description('后端 /api/agent/tools；运行 playcraft login 后即可直接使用，也支持 .playcraft.json 或 PLAYCRAFT_SANDBOX_TOKEN 环境变量');
     registerGenerationCommands(tools);
+    registerToolRequestCommand(tools);
     registerImageContextCommand(tools);
     registerProjectCommands(tools);
     registerBatchCommands(tools);

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

@@ -1,10 +1,10 @@
 import { readFileSync, existsSync } from 'fs';
 import { createWriteStream } from 'node:fs';
 import { link, mkdir, stat, unlink } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { dirname, join } from 'path';
+import { dirname, join, resolve } from 'path';
 import { homedir } from 'os';
 import { loadGlobalConfig } from '../config.js';
 import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
@@ -41,20 +41,28 @@ export class AgentApiClient {
     credentialFile;
     playcraftEnv;
     cloudRuntimeCredential;
-    constructor() {
-        const localConfig = AgentApiClient.loadLocalConfig();
-        const globalConfig = loadGlobalConfig();
+    explicitConfig;
+    operationDirectory;
+    constructor(options = {}) {
+        const localConfig = options.configFile
+            ? AgentApiClient.requireLocalConfig(options.configFile)
+            : AgentApiClient.loadLocalConfig();
+        const globalConfig = options.configFile ? {} : loadGlobalConfig();
         // URL: 环境变量 → 本地 .playcraft.json → 全局 login 配置 → 公有云默认地址
-        const apiUrl = (process.env.PLAYCRAFT_API_URL ||
-            localConfig.apiUrl ||
-            globalConfig.backendUrl ||
-            globalConfig.url ||
-            DEFAULT_PLAYCRAFT_CLOUD_BASE).replace(/\/+$/, '');
+        const apiUrl = (options.configFile
+            ? localConfig.apiUrl
+            : process.env.PLAYCRAFT_API_URL ||
+                localConfig.apiUrl ||
+                globalConfig.backendUrl ||
+                globalConfig.url ||
+                DEFAULT_PLAYCRAFT_CLOUD_BASE).replace(/\/+$/, '');
         // Token: 环境变量 → 沙箱全局配置 → 项目配置 → 用户登录配置
-        const token = process.env.PLAYCRAFT_SANDBOX_TOKEN ||
-            localConfig.token ||
-            globalConfig.token ||
-            '';
+        const token = options.configFile
+            ? localConfig.token
+            : process.env.PLAYCRAFT_SANDBOX_TOKEN ||
+                localConfig.token ||
+                globalConfig.token ||
+                '';
         if (!token) {
             throw new Error('Missing PlayCraft API credentials. ' +
                 'Run `playcraft login` to authenticate, or set PLAYCRAFT_SANDBOX_TOKEN / create a .playcraft.json file.');
@@ -62,14 +70,29 @@ export class AgentApiClient {
         this.apiUrl = apiUrl;
         this.token = token;
         this.credentialFile = localConfig.credentialFile;
-        this.playcraftEnv = (process.env.PLAYCRAFT_ENV || localConfig.env || '').trim();
+        this.explicitConfig = Boolean(options.configFile);
+        this.playcraftEnv = (options.configFile
+            ? localConfig.env || process.env.PLAYCRAFT_ENV || ''
+            : process.env.PLAYCRAFT_ENV || localConfig.env || '').trim();
         this.cloudRuntimeCredential = cloudRuntimeCredentialHint(token, token === localConfig.token ? localConfig : undefined);
+        if (options.operationNamespace) {
+            if (!options.configFile)
+                throw new Error('Operation namespace requires an explicit sandbox configuration');
+            const scope = JSON.stringify([
+                resolve(options.configFile),
+                apiUrl,
+                this.playcraftEnv,
+                localConfig.projectId,
+                localConfig.branch,
+            ]);
+            this.operationDirectory = join(process.env.PLAYCRAFT_TOOL_REQUEST_DIR ?? join(homedir(), '.playcraft', 'tool-requests'), options.operationNamespace, createHash('sha256').update(scope).digest('hex'));
+        }
     }
     /** 根据 token 类型构造鉴权 headers */
     authHeaders() {
         let token = this.token;
         // Polling commands can outlive a credential: read the atomically refreshed file per request.
-        if (this.credentialFile && !process.env.PLAYCRAFT_SANDBOX_TOKEN) {
+        if (this.credentialFile && (this.explicitConfig || !process.env.PLAYCRAFT_SANDBOX_TOKEN)) {
             try {
                 token = JSON.parse(readFileSync(this.credentialFile, 'utf8')).token || token;
             }
@@ -96,12 +119,12 @@ export class AgentApiClient {
         const recoverId = options?.requestId ?? process.env.PLAYCRAFT_TOOL_REQUEST_ID;
         const newRequest = options?.newRequest ?? process.env.PLAYCRAFT_TOOL_NEW_REQUEST === '1';
         const originalReceipt = recoverId !== undefined && !newRequest && isWorkspaceGenerationPath(path)
-            ? findToolOperation(url.pathname, originalBody, recoverId) : undefined;
+            ? findToolOperation(url.pathname, originalBody, recoverId, this.operationDirectory) : undefined;
         let serializedBody = originalReceipt ? originalBody : JSON.stringify(await withGenerationWorkspaceScope(path, body, this.cloudRuntimeCredential));
         if (serializedBody === undefined)
             throw new Error('Tool request body is required');
         if (serializedBody !== originalBody && !newRequest) {
-            const previous = findToolOperation(url.pathname, originalBody, recoverId);
+            const previous = findToolOperation(url.pathname, originalBody, recoverId, this.operationDirectory);
             if (previous && recoverId !== undefined)
                 serializedBody = originalBody;
             else if (previous)
@@ -110,6 +133,7 @@ export class AgentApiClient {
         }
         const operation = beginToolOperation(url.pathname, serializedBody, recoverId, {
             newRequest,
+            directory: this.operationDirectory,
         });
         const unknownOutcome = `Tool request ${operation.requestId}: the outcome is unknown. Rerun the same command to ` +
             `continue this request: it returns the result if the request finished, or finishes it if ` +
@@ -384,6 +408,21 @@ export class AgentApiClient {
         }
         return { apiUrl: '', token: '' };
     }
+    /** A static plugin's slot must never fall back to another workspace or a global login. */
+    static requireLocalConfig(file) {
+        try {
+            const config = JSON.parse(readFileSync(file, 'utf8'));
+            if (typeof config?.apiUrl !== 'string' ||
+                !config.apiUrl.trim() ||
+                typeof config.token !== 'string' ||
+                !config.token.trim())
+                throw new Error('invalid');
+            return { ...config, credentialFile: file };
+        }
+        catch {
+            throw new Error('A valid project .playcraft.json with apiUrl and token is required; no generation request was sent');
+        }
+    }
 }
 /** A failure whose meaning is settled; no recovery hint applies. */
 class ToolRequestError extends Error {