@playcraft/cli 0.0.59 → 0.1.1

package/README.md

@@ -192,13 +192,25 @@ echo '{"token":"<sandbox-jwt>","apiUrl":"https://..."}' > .playcraft.json
 
 业务工具写请求要求服务支持持久操作协议。命令行先保存请求编号、路径和输入摘要到 `~/.playcraft/tool-requests/`，再发送请求；记录不包含凭证或请求正文。可用绝对路径环境变量 `PLAYCRAFT_TOOL_REQUEST_DIR` 指定可持久保留的目录。
 
-如果请求超时或连接中断，错误会显示请求编号。使用相同参数重跑命令，并设置该编号，只查询原操作的确定结果：
+原样重跑同一条命令（路径与参数都相同）时，命令行按上一次的结果决定是否沿用原请求编号：
+
+| 上一次的结果                                                         | 原样重跑时                                               |
+| -------------------------------------------------------------------- | -------------------------------------------------------- |
+| 成功（2xx）                                                          | 新操作                                                   |
+| 请求被拒绝（4xx，下列 409 除外）：请求没有被执行                     | 新操作                                                   |
+| 服务端错误（5xx）、超时或连接中断：结果未知                          | 沿用原编号，不会另起一次操作；服务端按下文的恢复方式处理 |
+| 409 `business_operation_in_progress`：原操作仍在执行                 | 沿用原编号，稍后重跑取得结果                             |
+| 409 `business_operation_requires_reconciliation`：结果未知，需要核对 | 沿用原编号，不会再执行                                   |
+
+沿用原编号时，服务端按原操作的状态处理：已完成则返回原结果；仍在执行则返回 409 `business_operation_in_progress`；没有拿到结果就结束时，按该工具声明的恢复方式决定，可以安全重做的工具（生图、构建、发布到 COS 等）用原编号再执行一次，其余返回 409 `business_operation_requires_reconciliation`。原调用的执行租约有效期间（执行中每 20 秒续期，60 秒未续即过期），同一编号不会被再次执行；续期因服务或数据库故障中断超过 60 秒时，重做可能与仍在运行的原调用重叠。
+
+需要核对的操作，只有确认它没有生效后，才可设置 `PLAYCRAFT_TOOL_NEW_REQUEST=1` 强制发起新操作；不要删除记录来绕过。也可以显式指定编号，只查询原操作的确定结果（不会重新执行；声明了恢复方式的工具若上次报错，返回那次的错误）。只查询时即使是可以安全重做的工具，没有结果也返回需要核对；去掉 `PLAYCRAFT_TOOL_REQUEST_ID` 原样重跑即可续做：
 
 ```bash
 PLAYCRAFT_TOOL_REQUEST_ID=<错误中显示的请求编号> playcraft tools build-project --project-id <原项目编号>
 ```
 
-恢复不会重新构建。操作尚未完成、结果未知或没有回执时会明确失败；不要换编号或删除记录来强行重试。只有错误明确说明能力检查失败且尚未发送操作时，才可在服务恢复后发起新的正常命令。服务不兼容时命令会在发送业务请求前停止；沙箱命令行与 Business 须排空旧调用后同步升级。
+能力检查失败时命令会明确说明尚未发送操作。服务不兼容时命令会在发送业务请求前停止；沙箱命令行与 Business 须排空旧调用后同步升级。
 
 ### 构建相关
 

package/dist/agent/local-backend.js

@@ -2,7 +2,7 @@ import express from 'express';
 import crypto from 'node:crypto';
 import path from 'node:path';
 import fs from 'node:fs/promises';
-import { eq, inArray } from 'drizzle-orm';
+import { eq, inArray } from '@playcraft/common/database/operators';
 import pc from 'picocolors';
 import { createSqliteAdapter } from '@playcraft/common/database';
 import { AssetModel, ProjectModel, SceneModel } from '@playcraft/common/models';

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

@@ -72,7 +72,13 @@ export class AgentApiClient {
         const serializedBody = JSON.stringify(body);
         if (serializedBody === undefined)
             throw new Error('Tool request body is required');
-        const operation = beginToolOperation(url.pathname, serializedBody, options?.requestId ?? process.env.PLAYCRAFT_TOOL_REQUEST_ID);
+        const recoverId = options?.requestId ?? process.env.PLAYCRAFT_TOOL_REQUEST_ID;
+        const operation = beginToolOperation(url.pathname, serializedBody, recoverId, {
+            newRequest: options?.newRequest ?? process.env.PLAYCRAFT_TOOL_NEW_REQUEST === '1',
+        });
+        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 ` +
+            `the tool can be safely redone; it never starts a second operation. Record: ${operation.file}.`;
         try {
             const capabilityResponse = await fetch(this.toolsRequestUrl(AGENT_TOOL_OPERATION_CAPABILITIES_PATH), {
                 headers: this.authHeaders(),
@@ -81,12 +87,12 @@ export class AgentApiClient {
             });
             if (!capabilityResponse.ok) {
                 await capabilityResponse.body?.cancel();
-                throw new Error(`Business tool protocol unavailable (${capabilityResponse.status}); no operation was sent`);
+                throw new ToolRequestError(`Business tool protocol unavailable (${capabilityResponse.status}); no operation was sent`);
             }
             const capabilities = (await capabilityResponse.json());
             if (capabilities.protocol !== AGENT_TOOL_OPERATION_PROTOCOL ||
                 capabilities.settledOnly !== true)
-                throw new Error('Business tool protocol is incompatible; no operation was sent');
+                throw new ToolRequestError('Business tool protocol is incompatible; no operation was sent');
             const res = await fetch(url, {
                 method: 'POST',
                 redirect: 'error',
@@ -103,10 +109,31 @@ export class AgentApiClient {
             if (res.headers.get(AGENT_TOOL_OPERATION_HEADERS.protocol) !== AGENT_TOOL_OPERATION_PROTOCOL ||
                 res.headers.get(AGENT_TOOL_OPERATION_HEADERS.requestId) !== operation.requestId) {
                 await res.body?.cancel();
+                // Possibly an instance that ignores identities: a rerun may only read the receipt.
+                operation.requireReceipt();
                 throw new Error('Business did not acknowledge a durable receipt; outcome remains unconfirmed');
             }
             if (!res.ok) {
                 const text = await res.text().catch(() => res.statusText);
+                const code = errorCode(text);
+                if (res.status === 409 && code === 'business_operation_in_progress')
+                    throw new ToolRequestError(`API 409: ${text}\nTool request ${operation.requestId} is still running. Rerun the ` +
+                        'same command later to get its result.');
+                if (res.status === 409 && code === 'business_operation_requires_reconciliation')
+                    throw new ToolRequestError(recoverId !== undefined
+                        ? // A receipt query never runs the request, even for a tool that can be safely redone.
+                            `API 409: ${text}\nTool request ${operation.requestId} has no settled result yet. ` +
+                                'Rerun the same command without PLAYCRAFT_TOOL_REQUEST_ID: a tool that can be ' +
+                                'safely redone continues this request; any other tool then needs reconciliation.'
+                        : `API 409: ${text}\nTool request ${operation.requestId} needs reconciliation: its ` +
+                            'outcome is unknown, and rerunning the same command will not run it again. Only ' +
+                            'after confirming it had no effect, rerun with PLAYCRAFT_TOOL_NEW_REQUEST=1 to ' +
+                            'start a new operation.');
+                if (res.status >= 400 && res.status < 500) {
+                    // The request itself was refused and not carried out: a rerun is a new operation.
+                    operation.reject();
+                    throw new ToolRequestError(`API ${res.status}: ${text}`);
+                }
                 throw new Error(`API ${res.status}: ${text}`);
             }
             const result = (await res.json());
@@ -114,10 +141,14 @@ export class AgentApiClient {
             return result;
         }
         catch (error) {
-            throw new Error(`${error instanceof Error ? error.message : String(error)}\n` +
-                `Tool request ${operation.requestId}; record: ${operation.file}. ` +
-                `To query its settled result, rerun the same command with PLAYCRAFT_TOOL_REQUEST_ID=${operation.requestId}. ` +
-                'This recovery does not start another operation.');
+            if (error instanceof ToolRequestError)
+                throw error;
+            throw new Error(`${error instanceof Error ? error.message : String(error)}\n${operation.settledOnly
+                ? `Tool request ${operation.requestId}; record: ${operation.file}. Its settled result is not available yet.`
+                : unknownOutcome}`);
+        }
+        finally {
+            operation.release();
         }
     }
     async get(path, params) {
@@ -160,3 +191,15 @@ export class AgentApiClient {
         return { apiUrl: '', token: '' };
     }
 }
+/** A failure whose meaning is settled; no recovery hint applies. */
+class ToolRequestError extends Error {
+}
+function errorCode(text) {
+    try {
+        const message = JSON.parse(text).message;
+        return typeof message === 'string' ? message : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/utils/tool-operation-journal.js

@@ -1,31 +1,61 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join } from 'node:path';
 import { isAgentToolRequestId } from '@playcraft/common/agent-tools';
+/** Operations this process is sending now; never continued by another call of this process. */
+const inFlight = new Set();
+/** Linux start time of a process, so a reused pid is not taken for the process that held it. */
+function startOf(pid) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function holderAlive(holder) {
+    if (!holder || holder.pid === process.pid)
+        return false;
+    try {
+        process.kill(holder.pid, 0);
+    }
+    catch (error) {
+        if (error.code !== 'EPERM')
+            return false;
+    }
+    return holder.start === null || startOf(holder.pid) === holder.start;
+}
 /** Persist an identity before sending. Store neither credentials nor request/response bodies. */
-export function beginToolOperation(path, serializedBody, recoverId) {
-    const identifier = recoverId ?? randomUUID();
-    if (!isAgentToolRequestId(identifier))
-        throw new Error('Invalid PLAYCRAFT_TOOL_REQUEST_ID');
-    const requestId = identifier.toLowerCase();
+export function beginToolOperation(path, serializedBody, recoverId, options = {}) {
     const directory = process.env.PLAYCRAFT_TOOL_REQUEST_DIR ?? join(homedir(), '.playcraft', 'tool-requests');
     if (!isAbsolute(directory))
         throw new Error('PLAYCRAFT_TOOL_REQUEST_DIR must be an absolute path');
     mkdirSync(directory, { recursive: true, mode: 0o700 });
-    const file = join(directory, `${requestId}.json`);
     const inputHash = createHash('sha256').update(serializedBody).digest('hex');
+    // Rerunning the same command while its outcome is unknown continues that operation: the server
+    // answers the same identity with its receipt instead of running it again.
+    const unconfirmed = recoverId === undefined && !options.newRequest
+        ? findUnconfirmed(directory, path, inputHash)
+        : undefined;
+    const identifier = recoverId ?? unconfirmed?.requestId ?? randomUUID();
+    if (!isAgentToolRequestId(identifier))
+        throw new Error('Invalid PLAYCRAFT_TOOL_REQUEST_ID');
+    const requestId = identifier.toLowerCase();
+    const file = join(directory, `${requestId}.json`);
     const now = new Date().toISOString();
+    const holder = { pid: process.pid, start: startOf(process.pid) };
     const entry = {
         version: 1,
         requestId,
         path,
         inputHash,
         state: 'unconfirmed',
+        holder,
         createdAt: now,
         updatedAt: now,
     };
-    let settledOnly = recoverId !== undefined;
     try {
         writeFileSync(file, JSON.stringify(entry), { flag: 'wx', mode: 0o600 });
     }
@@ -38,17 +68,53 @@ export function beginToolOperation(path, serializedBody, recoverId) {
             previous.path !== path ||
             previous.inputHash !== inputHash)
             throw new Error(`Tool request ${requestId} conflicts with its durable local record`);
-        settledOnly = true;
     }
+    const update = (change) => {
+        const current = JSON.parse(readFileSync(file, 'utf8'));
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, JSON.stringify({ ...current, ...change, updatedAt: new Date().toISOString() }), { flag: 'wx', mode: 0o600 });
+        renameSync(temporary, file);
+    };
+    // Only the sender holds an operation; a concurrent run of the same command gets its own.
+    inFlight.add(requestId);
+    if (unconfirmed || recoverId !== undefined)
+        update({ holder });
     return {
         requestId,
-        settledOnly,
+        /** An explicit recovery, or a server that did not acknowledge the identity, reads only. */
+        settledOnly: recoverId !== undefined || unconfirmed?.receiptOnly === true,
         file,
-        complete() {
-            const current = JSON.parse(readFileSync(file, 'utf8'));
-            const temporary = `${file}.${randomUUID()}.tmp`;
-            writeFileSync(temporary, JSON.stringify({ ...current, state: 'completed', updatedAt: new Date().toISOString() }), { flag: 'wx', mode: 0o600 });
-            renameSync(temporary, file);
-        },
+        complete: () => update({ state: 'completed' }),
+        /** A definite refusal: the request was not carried out, so a rerun is a new operation. */
+        reject: () => update({ state: 'rejected' }),
+        /** The outcome stays unknown and a rerun may only read the receipt. */
+        requireReceipt: () => update({ receiptOnly: true }),
+        /** This call is done with the operation; a later run of the command may continue it. */
+        release: () => inFlight.delete(requestId),
     };
 }
+function findUnconfirmed(directory, path, inputHash) {
+    let latest;
+    for (const name of readdirSync(directory)) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const entry = JSON.parse(readFileSync(join(directory, name), 'utf8'));
+            if (entry.version === 1 &&
+                entry.state === 'unconfirmed' &&
+                entry.path === path &&
+                entry.inputHash === inputHash &&
+                isAgentToolRequestId(entry.requestId) &&
+                (!latest || entry.updatedAt > latest.updatedAt) &&
+                // Still being sent, here or by another live process: that run is not interrupted.
+                // Checked last, so only this command's candidates cost a process probe.
+                !inFlight.has(entry.requestId) &&
+                !holderAlive(entry.holder))
+                latest = entry;
+        }
+        catch {
+            // A torn or foreign file is not an operation of this command.
+        }
+    }
+    return latest;
+}