@playcraft/cli 0.1.52 → 0.1.53-beta

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

@@ -0,0 +1,100 @@
+import { constants, promises as fs } from 'node:fs';
+import { extractBundleArchive } from '@playcraft/common/project-skills';
+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',
+]);
+/** Preserve native manifest bytes; the server remains the authoritative bundle validator. */
+export function inspectNativePlatformArchive(archive) {
+    const invalid = () => {
+        throw new RegistryError('invalid_platform_bundle', message('invalidPlatformBundle'));
+    };
+    if (archive.length > MAX_BUNDLE_BYTES)
+        invalid();
+    const extracted = extractBundleArchive(archive, {
+        maxArchiveBytes: MAX_BUNDLE_BYTES,
+        maxExpandedBytes: MAX_BUNDLE_BYTES + 8 * 1024 * 1024,
+    });
+    if (extracted.issues.length || extracted.files.length > 512)
+        invalid();
+    let total = 0;
+    for (const file of extracted.files) {
+        total += file.data.length;
+        if (file.data.length > 16 * 1024 * 1024 || total > MAX_BUNDLE_BYTES)
+            invalid();
+    }
+    let manifest;
+    let frontmatter;
+    try {
+        manifest = JSON.parse(extracted.files.find((file) => file.path === 'manifest.json').data.toString('utf8'));
+        const markdown = extracted.files
+            .find((file) => file.path === 'SKILL.md')
+            .data.toString('utf8');
+        const block = markdown.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---/);
+        frontmatter = yaml.load(block[1]);
+    }
+    catch {
+        return invalid();
+    }
+    const standalone = (value) => Array.isArray(value) && value.length === 1 && value[0] === 'sandbox-agent';
+    if (!manifest ||
+        !frontmatter ||
+        typeof manifest.skillRef !== 'string' ||
+        !NATIVE_REFS.has(manifest.skillRef) ||
+        typeof manifest.version !== 'string' ||
+        manifest.schemaVersion !== 2 ||
+        manifest.kind !== 'platform' ||
+        manifest.name !== manifest.skillRef.split('/')[1] ||
+        !standalone(manifest.surfaces) ||
+        !standalone(frontmatter.surfaces) ||
+        frontmatter.name !== manifest.name ||
+        frontmatter.version !== manifest.version ||
+        [manifest.imports, manifest.relationships].some((value) => value !== undefined && (!Array.isArray(value) || value.length !== 0)))
+        invalid();
+    const { skillRef, version } = parseSkillReference(`${manifest.skillRef}@${manifest.version}`, true);
+    return {
+        skillRef,
+        version: version,
+        archive,
+        uploadHash: sha256(archive),
+        files: extracted.files.map((file) => ({ path: file.path, size: file.data.length })),
+    };
+}
+export async function packNativePlatformSource(source, options = {}) {
+    const stat = await fs.lstat(source);
+    if (stat.isSymbolicLink())
+        throw new RegistryError('invalid_platform_bundle', message('invalidPlatformBundle'));
+    if (stat.isDirectory()) {
+        const bundle = await packSkillDirectory(source, { ...options, preserveManifest: true });
+        return inspectNativePlatformArchive(bundle.archive);
+    }
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > MAX_BUNDLE_BYTES)
+        throw new RegistryError('invalid_platform_bundle', message('invalidPlatformBundle'));
+    const handle = await fs.open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const opened = await handle.stat();
+        if (opened.ino !== stat.ino || opened.dev !== stat.dev || opened.size !== stat.size)
+            throw new RegistryError('invalid_platform_bundle', message('invalidPlatformBundle'));
+        const archive = Buffer.alloc(stat.size + 1);
+        let length = 0;
+        while (length < archive.length) {
+            const read = await handle.read(archive, length, archive.length - length, null);
+            if (!read.bytesRead)
+                break;
+            length += read.bytesRead;
+        }
+        if (length !== stat.size)
+            throw new RegistryError('invalid_platform_bundle', message('invalidPlatformBundle'));
+        const bundle = inspectNativePlatformArchive(archive.subarray(0, length));
+        if ((options.ref && options.ref !== bundle.skillRef) ||
+            (options.version && options.version !== bundle.version))
+            throw new RegistryError('manifest_conflict', message('manifestConflict'));
+        return bundle;
+    }
+    finally {
+        await handle.close();
+    }
+}

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

@@ -1,8 +1,13 @@
 import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
+import { dirname, join } from 'path';
 import { homedir } from 'os';
 import { loadGlobalConfig } from '../config.js';
 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 } from './tool-operation-journal.js';
+import { businessEndpoint } from './environment-endpoints.js';
+import { redactDiagnosticText } from './error-diagnostics.js';
+import { AccountActivationError, parseErrorPayload, pendingAccountActivationError, } from '../auth/account-activation.js';
 /**
  * 判断 token 是否为用户 PAT（Personal Access Token）。
  * PAT 以 "playcraft_pat_" 开头；沙箱 JWT 为三段式 base64。
@@ -15,8 +20,8 @@ function isPatToken(token) {
  * or from the CLI after `playcraft login`.
  *
  * 凭证解析优先级：
- *   API URL : PLAYCRAFT_API_URL → .playcraft.json → ~/.playcraft/config.json → DEFAULT_PLAYCRAFT_CLOUD_BASE
- *   Token   : PLAYCRAFT_SANDBOX_TOKEN → .playcraft.json token → ~/.playcraft/config.json token (PAT)
+ *   API URL : PLAYCRAFT_API_URL → sandbox global .playcraft.json → project .playcraft.json → ~/.playcraft/config.json → DEFAULT_PLAYCRAFT_CLOUD_BASE
+ *   Token   : PLAYCRAFT_SANDBOX_TOKEN → sandbox global .playcraft.json → project .playcraft.json → ~/.playcraft/config.json token (PAT)
  *
  * 鉴权 header 自动选择：
  *   - 沙箱 JWT (非 PAT) → X-Sandbox-Token: <token>（后端 @SandboxToken 路由的沙箱分支）
@@ -25,7 +30,7 @@ function isPatToken(token) {
 export class AgentApiClient {
     apiUrl;
     token;
-    isPat;
+    credentialFile;
     playcraftEnv;
     constructor() {
         const localConfig = AgentApiClient.loadLocalConfig();
@@ -36,7 +41,7 @@ export class AgentApiClient {
             globalConfig.backendUrl ||
             globalConfig.url ||
             DEFAULT_PLAYCRAFT_CLOUD_BASE).replace(/\/+$/, '');
-        // Token: 沙箱 token 环境变量 → 本地 .playcraft.json → 全局 login 配置（PAT）
+        // Token: 环境变量 → 沙箱全局配置 → 项目配置 → 用户登录配置
         const token = process.env.PLAYCRAFT_SANDBOX_TOKEN ||
             localConfig.token ||
             globalConfig.token ||
@@ -47,43 +52,149 @@ export class AgentApiClient {
         }
         this.apiUrl = apiUrl;
         this.token = token;
-        this.isPat = isPatToken(token);
-        this.playcraftEnv = (process.env.PLAYCRAFT_ENV ||
-            localConfig.env ||
-            '').trim();
+        this.credentialFile = localConfig.credentialFile;
+        this.playcraftEnv = (process.env.PLAYCRAFT_ENV || localConfig.env || '').trim();
     }
     /** 根据 token 类型构造鉴权 headers */
     authHeaders() {
-        const headers = this.isPat
-            ? { Authorization: `Bearer ${this.token}` }
-            : { 'X-Sandbox-Token': this.token };
+        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) {
+            try {
+                token = JSON.parse(readFileSync(this.credentialFile, 'utf8')).token || token;
+            }
+            catch { /* Keep the last credential if a local file is temporarily unavailable. */ }
+        }
+        const headers = isPatToken(token)
+            ? { Authorization: `Bearer ${token}` }
+            : { 'X-Sandbox-Token': token };
         if (this.playcraftEnv) {
             headers['playcraft-env'] = this.playcraftEnv;
         }
         return headers;
     }
-    /** Absolute pathname under /api/agent/tools (path may omit leading slash). */
+    /** Deployment-relative pathname under /api/agent/tools (path may omit leading slash). */
     toolsRequestUrl(path) {
         const p = path.startsWith('/') ? path : `/${path}`;
-        return new URL(`/api/agent/tools${p}`, this.apiUrl);
+        return businessEndpoint(this.apiUrl, `/api/agent/tools${p}`);
     }
-    async post(path, body) {
-        const url = this.toolsRequestUrl(path).href;
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                ...this.authHeaders(),
-            },
-            body: JSON.stringify(body),
+    async post(path, body, options) {
+        const url = this.toolsRequestUrl(path);
+        const serializedBody = JSON.stringify(body);
+        if (serializedBody === undefined)
+            throw new Error('Tool request body is required');
+        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',
         });
-        if (!res.ok) {
-            const text = await res.text().catch(() => res.statusText);
-            throw new Error(`API ${res.status}: ${text}`);
+        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 {
+            try {
+                await options?.onPrepared?.({ requestId: operation.requestId, file: operation.file });
+            }
+            catch {
+                operation.reject();
+                throw new ToolRequestError('Tool request preparation failed; no operation was sent');
+            }
+            const capabilityResponse = await fetch(this.toolsRequestUrl(AGENT_TOOL_OPERATION_CAPABILITIES_PATH), {
+                headers: this.authHeaders(),
+                redirect: 'error',
+                signal: options?.signal
+                    ? AbortSignal.any([options.signal, AbortSignal.timeout(30_000)])
+                    : AbortSignal.timeout(30_000),
+            });
+            if (!capabilityResponse.ok) {
+                if (capabilityResponse.status === 403) {
+                    const pending = pendingAccountActivationError(403, parseErrorPayload(await capabilityResponse.clone().text().catch(() => '')));
+                    if (pending) {
+                        if (operation.createdNew && !operation.settledOnly)
+                            operation.reject();
+                        throw pending;
+                    }
+                }
+                await capabilityResponse.body?.cancel();
+                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 ToolRequestError('Business tool protocol is incompatible; no operation was sent');
+            const res = await fetch(url, {
+                method: 'POST',
+                redirect: 'error',
+                signal: options?.signal
+                    ? AbortSignal.any([options.signal, AbortSignal.timeout(30 * 60_000)])
+                    : AbortSignal.timeout(30 * 60_000),
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.authHeaders(),
+                    [AGENT_TOOL_OPERATION_HEADERS.protocol]: AGENT_TOOL_OPERATION_PROTOCOL,
+                    [AGENT_TOOL_OPERATION_HEADERS.requestId]: operation.requestId,
+                    ...(operation.settledOnly ? { [AGENT_TOOL_OPERATION_HEADERS.settledOnly]: 'true' } : {}),
+                },
+                body: serializedBody,
+            });
+            if (res.headers.get(AGENT_TOOL_OPERATION_HEADERS.protocol) !== AGENT_TOOL_OPERATION_PROTOCOL ||
+                res.headers.get(AGENT_TOOL_OPERATION_HEADERS.requestId) !== operation.requestId) {
+                const text = await res.text().catch(() => res.statusText);
+                if (res.status === 403) {
+                    const pending = pendingAccountActivationError(403, parseErrorPayload(text));
+                    if (pending) {
+                        if (operation.createdNew && !operation.settledOnly)
+                            operation.reject();
+                        throw pending;
+                    }
+                }
+                // Possibly an instance that ignores identities: a rerun may only read the receipt.
+                operation.requireReceipt();
+                const reason = responseErrorReason(text) || redactDiagnosticText(res.statusText);
+                throw new Error(`Server response ${res.status}${reason ? `: ${reason}` : ''}; ` +
+                    'Business did not acknowledge a durable receipt; outcome remains unconfirmed');
+            }
+            if (!res.ok) {
+                const text = await res.text().catch(() => res.statusText);
+                const pending = pendingAccountActivationError(res.status, parseErrorPayload(text));
+                if (pending)
+                    throw pending;
+                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());
+            operation.complete();
+            return result;
+        }
+        catch (error) {
+            if (error instanceof ToolRequestError || error instanceof AccountActivationError)
+                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}`, { cause: error });
+        }
+        finally {
+            operation.release();
         }
-        return res.json();
     }
-    async get(path, params) {
+    async get(path, params, options) {
         const url = this.toolsRequestUrl(path);
         if (params) {
             for (const [k, v] of Object.entries(params)) {
@@ -93,27 +204,66 @@ export class AgentApiClient {
         }
         const res = await fetch(url, {
             headers: this.authHeaders(),
+            redirect: 'error',
+            signal: options?.signal ?? AbortSignal.timeout(30_000),
         });
         if (!res.ok) {
             const text = await res.text().catch(() => res.statusText);
+            const pending = pendingAccountActivationError(res.status, parseErrorPayload(text));
+            if (pending)
+                throw pending;
             throw new Error(`API ${res.status}: ${text}`);
         }
         return res.json();
     }
+    /** Stream only to the authenticated, same-service video upload endpoint. */
+    async putVideoMedia(path, body, headers, signal) {
+        if (!/^\/video-media\/[a-f0-9-]{36}\/content\?/.test(path))
+            throw new Error('invalid_video_upload_target');
+        const url = this.toolsRequestUrl(path);
+        const keys = [...url.searchParams.keys()].sort();
+        if (keys.join(',') !== 'expires,signature,workspaceId')
+            throw new Error('invalid_video_upload_target');
+        const allowed = new Set(['content-type', 'content-md5', 'content-length']);
+        if (Object.keys(headers).some(key => !allowed.has(key.toLowerCase())))
+            throw new Error('invalid_video_upload_headers');
+        const response = await fetch(url, {
+            method: 'PUT', redirect: 'error', signal,
+            headers: { ...headers, ...this.authHeaders() },
+            body: body,
+            duplex: 'half',
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => response.statusText);
+            const pending = pendingAccountActivationError(response.status, parseErrorPayload(text));
+            if (pending)
+                throw pending;
+            const reason = responseErrorReason(text) || redactDiagnosticText(response.statusText);
+            throw new Error(`video_upload_failed:${response.status}${reason ? `: ${reason}` : ''}`);
+        }
+        await response.body?.cancel();
+    }
     /**
      * 按顺序搜索本地 .playcraft.json 文件（沙箱内或项目目录）。
      * 与全局 login 配置（~/.playcraft/config.json）不同，前者专用于沙箱 token。
      */
     static loadLocalConfig() {
+        const ancestors = [];
+        for (let directory = process.cwd();; directory = dirname(directory)) {
+            ancestors.push(join(directory, '.playcraft.json'));
+            if (dirname(directory) === directory)
+                break;
+        }
         const searchPaths = [
-            join(process.cwd(), '.playcraft.json'),
+            process.env.PLAYCRAFT_SANDBOX_CONFIG_PATH || '/workspaces/.playcraft.json',
+            ...ancestors,
             '/project/.playcraft.json',
             join(homedir(), '.playcraft.json'),
         ];
         for (const p of searchPaths) {
             if (existsSync(p)) {
                 try {
-                    return JSON.parse(readFileSync(p, 'utf-8'));
+                    return { ...JSON.parse(readFileSync(p, 'utf-8')), credentialFile: p };
                 }
                 catch {
                     continue;
@@ -123,3 +273,33 @@ export class AgentApiClient {
         return { apiUrl: '', token: '' };
     }
 }
+/** A failure whose meaning is settled; no recovery hint applies. */
+class ToolRequestError extends Error {
+}
+function responseErrorReason(text) {
+    const payload = parseErrorPayload(text);
+    const readable = (value, depth = 0) => {
+        if (typeof value === 'string')
+            return value;
+        if (Array.isArray(value))
+            return value.filter(item => typeof item === 'string').join('; ');
+        if (!value || typeof value !== 'object' || depth > 2)
+            return '';
+        const fields = value;
+        const message = readable(fields.message, depth + 1) || readable(fields.reason, depth + 1) ||
+            readable(fields.detail, depth + 1) || readable(fields.error, depth + 1);
+        const code = typeof fields.code === 'string' ? fields.code : '';
+        return code && message && code !== message ? `${code}: ${message}` : message || code;
+    };
+    // Select diagnostic fields instead of printing the response object and its other data.
+    return redactDiagnosticText(payload === undefined ? text : readable(payload)).slice(0, 2_000);
+}
+function errorCode(text) {
+    try {
+        const message = JSON.parse(text).message;
+        return typeof message === 'string' ? message : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/utils/environment-endpoints.js

@@ -0,0 +1,17 @@
+function publicBase(value) {
+    const base = new URL(value);
+    if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash) {
+        throw new Error('invalid_environment_endpoint');
+    }
+    base.pathname = base.pathname.replace(/\/+$/, '');
+    return base;
+}
+function append(base, path) {
+    return new URL(`${base.toString().replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`);
+}
+/** Accept either a public deployment base or its /api endpoint, without duplicating /api. */
+export function businessEndpoint(apiUrl, path) {
+    const base = publicBase(apiUrl);
+    base.pathname = base.pathname.replace(/\/api$/, '');
+    return append(base, path);
+}

package/dist/utils/error-diagnostics.js

@@ -0,0 +1,20 @@
+/** Keep readable error text without credentials, signed queries or terminal controls. */
+export function redactDiagnosticText(value) {
+    return value
+        .replace(/\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\))/g, '')
+        .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, '')
+        .replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"']+/gi, raw => {
+        try {
+            const url = new URL(raw);
+            return `${url.protocol}//${url.host}${url.pathname}${url.search ? '?[redacted]' : ''}${url.hash ? '#[redacted]' : ''}`;
+        }
+        catch {
+            return '[redacted-url]';
+        }
+    })
+        .replace(/((?:["']?)(?:authorization|proxy-authorization|x-sandbox-token|x-playcraft-control-token|x-internal-secret|x-emit-secret|(?:access|refresh|id)[_-]?token|token|api[_-]?key|password|passwd|secret(?:[_-]?(?:id|key|access[_-]?key))?|private[_-]?key|signature|q-signature|x-amz-[a-z-]+)(?:["']?)\s*[:=]\s*)(?:"[^"\n]*"|'[^'\n]*'|(?:Bearer|Basic)\s+[^\s,;}]+|[^\s,;&}\]]+)/gi, '$1[redacted]')
+        .replace(/\b(Bearer|Basic)\s+[a-z0-9._~+/=-]+/gi, '$1 [redacted]')
+        .replace(/\bplaycraft_pat_[a-z0-9_-]+/gi, '[redacted]')
+        .replace(/\beyJ[a-z0-9_-]*\.[a-z0-9_-]+\.[a-z0-9_-]+\b/gi, '[redacted]')
+        .replace(/\s+/g, ' ').trim();
+}

package/dist/utils/playcraft-http-client.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { loadGlobalConfig } from '../config.js';
 import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
+import { pendingAccountActivationError } from '../auth/account-activation.js';
 export class PlayCraftApiError extends Error {
     code;
     status;
@@ -95,19 +96,20 @@ export class PlayCraftHttpClient {
                 }
                 if (!response.ok) {
                     const error = payload?.error;
-                    const code = typeof error?.code === 'string' ? error.code : statusCode(response.status);
-                    const message = typeof error?.message === 'string'
+                    const pending = pendingAccountActivationError(response.status, payload);
+                    const code = pending?.code ?? (typeof error?.code === 'string' ? error.code : statusCode(response.status));
+                    const message = pending?.message ?? (typeof error?.message === 'string'
                         ? error.message
                         : typeof payload?.message === 'string'
                             ? payload.message
                             : typeof payload === 'string'
                                 ? payload
-                                : response.statusText || 'PlayCraft request failed';
+                                : response.statusText || 'PlayCraft request failed');
                     throw new PlayCraftApiError({
                         code,
                         message,
                         status: response.status,
-                        details: error?.details ?? payload,
+                        details: pending ? { loginCommand: 'playcraft login --activate' } : error?.details ?? payload,
                         retryable: response.status >= 500,
                     });
                 }

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

@@ -0,0 +1,124 @@
+import { createHash, randomUUID } from 'node:crypto';
+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, 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 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 createdNew = false;
+    try {
+        writeFileSync(file, JSON.stringify(entry), { flag: 'wx', mode: 0o600 });
+        createdNew = true;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const previous = JSON.parse(readFileSync(file, 'utf8'));
+        if (previous.version !== 1 ||
+            previous.requestId !== requestId ||
+            previous.path !== path ||
+            previous.inputHash !== inputHash)
+            throw new Error(`Tool request ${requestId} conflicts with its durable local record`);
+    }
+    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,
+        /** This call created the identity; a refusal cannot settle an older unknown operation. */
+        createdNew,
+        /** An explicit recovery, or a server that did not acknowledge the identity, reads only. */
+        settledOnly: recoverId !== undefined || unconfirmed?.receiptOnly === true,
+        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;
+}