@actiondock/core 2.7.0 → 2.8.0

package/dist/process/process-executor.js

@@ -0,0 +1,296 @@
+import { PROCESS_CANCELLED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_TIMEOUT, UNSUPPORTED_CAPABILITY, ProcessError, } from "../errors.js";
+import { NodeProcessDriver, killProcessGroup } from "./process-driver.js";
+import { RunExecutor } from "./run-executor.js";
+export { killProcessGroup };
+/**
+ * 基于 NodeProcessDriver 实现的兼容命令执行器。
+ * 核心 OS 进程派生与生命周期管理统一由 NodeProcessDriver 承担，不再重复派生与调度。
+ */
+export class NodeProcessExecutor {
+    driver;
+    gracePeriodMs;
+    constructor(options) {
+        if (typeof options === "number") {
+            this.gracePeriodMs = options;
+            this.driver = new NodeProcessDriver();
+        }
+        else {
+            this.gracePeriodMs = options?.gracePeriodMs ?? 500;
+            this.driver =
+                options?.driver ??
+                    new NodeProcessDriver({
+                        spawnFn: options?.spawnFn,
+                    });
+        }
+    }
+    /**
+     * 执行外部系统命令，完整支持标准输入管道、超时控制、取消信号、输出容量截断及错误拦截。
+     *
+     * @param command 执行命令
+     * @param args 参数列表
+     * @param options 执行选项
+     * @param internal 内部专用参数：envAlreadyResolved 为 true 时 options.env 视为已完整解析
+     */
+    async exec(command, args = [], options = {}, internal) {
+        const startTime = Date.now();
+        const maxOutputBytes = options.maxOutputBytes ?? 10 * 1024 * 1024;
+        const encoding = options.encoding || "utf8";
+        const processId = `exec-${crypto.randomUUID()}`;
+        return new Promise(async (resolve, reject) => {
+            let settled = false;
+            let timedOut = false;
+            let cancelled = false;
+            let outputLimitExceeded = false;
+            let error;
+            let writeErr;
+            const stdoutChunks = [];
+            const stderrChunks = [];
+            let totalBytes = 0;
+            let timeoutTimer;
+            let graceTimer;
+            let abortHandler;
+            let handle;
+            /** 子进程是否已退出：grace 宽限期 SIGKILL 升级前的存活二闪确认依据 */
+            let childExited = false;
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeoutTimer) {
+                    clearTimeout(timeoutTimer);
+                    timeoutTimer = undefined;
+                }
+                // 结算时同步清理 grace 宽限定时器：子进程已退出（或已故障），
+                // 后续 SIGKILL 升级不再必要，且可避免定时器泄漏与 pid 复用误杀
+                if (graceTimer) {
+                    clearTimeout(graceTimer);
+                    graceTimer = undefined;
+                }
+                if (options.signal && abortHandler) {
+                    options.signal.removeEventListener("abort", abortHandler);
+                }
+                if (!result.ok && options.throwOnError) {
+                    const errMsg = result.error?.message || result.stderr || `Process exited with code ${result.exitCode}`;
+                    reject(new Error(errMsg));
+                }
+                else {
+                    resolve(result);
+                }
+            };
+            const terminateChild = (sig = "SIGTERM") => {
+                const pid = handle?.pid;
+                if (pid) {
+                    killProcessGroup(pid, sig, this.driver.spawnFn);
+                }
+                if (timeoutTimer) {
+                    clearTimeout(timeoutTimer);
+                    timeoutTimer = undefined;
+                }
+                if (sig === "SIGKILL") {
+                    if (graceTimer) {
+                        clearTimeout(graceTimer);
+                        graceTimer = undefined;
+                    }
+                }
+                else if (!graceTimer) {
+                    graceTimer = setTimeout(() => {
+                        graceTimer = undefined;
+                        // 宽限期到时二次确认子进程句柄仍存活：已退出则跳过 SIGKILL，
+                        // 杜绝对已复用 pid 的无关进程组误杀
+                        if (childExited) {
+                            return;
+                        }
+                        const targetPid = handle?.pid;
+                        if (targetPid) {
+                            killProcessGroup(targetPid, "SIGKILL", this.driver.spawnFn);
+                        }
+                    }, this.gracePeriodMs);
+                    graceTimer.unref?.();
+                }
+            };
+            const callbacks = {
+                onOutput: (stream, data) => {
+                    if (outputLimitExceeded)
+                        return;
+                    const chunk = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+                    totalBytes += chunk.length;
+                    if (totalBytes > maxOutputBytes) {
+                        outputLimitExceeded = true;
+                        if (!error) {
+                            error = {
+                                code: PROCESS_OUTPUT_LIMIT,
+                                message: `Process output exceeded limit of ${maxOutputBytes} bytes`,
+                            };
+                        }
+                        terminateChild("SIGTERM");
+                        return;
+                    }
+                    if (stream === "stdout")
+                        stdoutChunks.push(chunk);
+                    else if (stream === "stderr")
+                        stderrChunks.push(chunk);
+                },
+                onExit: (exit) => {
+                    childExited = true;
+                    const durationMs = Date.now() - startTime;
+                    const stdoutBuf = Buffer.concat(stdoutChunks);
+                    const stderrBuf = Buffer.concat(writeErr
+                        ? [...stderrChunks, Buffer.from(`\n[stdin write failed: ${writeErr.message}]`)]
+                        : stderrChunks);
+                    const stdoutStr = stdoutBuf.toString(encoding);
+                    const stderrStr = stderrBuf.toString(encoding);
+                    const ok = exit.code === 0 && !timedOut && !cancelled && !error;
+                    finish({
+                        ok,
+                        exitCode: exit.code,
+                        signal: exit.signal || undefined,
+                        stdout: stdoutStr.trim(),
+                        stderr: stderrStr.trim(),
+                        raw: new Uint8Array(stdoutBuf),
+                        timedOut,
+                        cancelled,
+                        durationMs,
+                        error,
+                    });
+                },
+                onError: (err) => {
+                    childExited = true;
+                    const durationMs = Date.now() - startTime;
+                    const spawnError = error || {
+                        code: PROCESS_SPAWN_ERROR,
+                        message: err.message || "Failed to spawn process",
+                    };
+                    const stdoutBuf = Buffer.concat(stdoutChunks);
+                    const stderrBuf = Buffer.concat(writeErr
+                        ? [...stderrChunks, Buffer.from(`\n[stdin write failed: ${writeErr.message}]`)]
+                        : stderrChunks);
+                    finish({
+                        ok: false,
+                        exitCode: null,
+                        signal: undefined,
+                        stdout: stdoutBuf.toString(encoding).trim(),
+                        stderr: stderrBuf.toString(encoding).trim() || spawnError.message,
+                        raw: new Uint8Array(stdoutBuf),
+                        timedOut,
+                        cancelled,
+                        durationMs,
+                        error: spawnError,
+                    });
+                },
+            };
+            const effectiveEnv = internal?.envAlreadyResolved
+                ? { inherit: "none", set: options.env }
+                : options.env
+                    ? { inherit: "allowlisted", set: options.env }
+                    : undefined;
+            const spec = {
+                executable: command,
+                args,
+                cwd: options.cwd,
+                env: effectiveEnv,
+                io: { mode: "pipe" },
+            };
+            if (options.signal) {
+                abortHandler = () => {
+                    cancelled = true;
+                    if (!error) {
+                        error = {
+                            code: PROCESS_CANCELLED,
+                            message: "Process was cancelled by AbortSignal",
+                        };
+                    }
+                    terminateChild("SIGTERM");
+                };
+                if (options.signal.aborted) {
+                    abortHandler();
+                }
+                else {
+                    options.signal.addEventListener("abort", abortHandler, { once: true });
+                }
+            }
+            if (options.timeoutMs && options.timeoutMs > 0) {
+                timeoutTimer = setTimeout(() => {
+                    timedOut = true;
+                    if (!error) {
+                        error = {
+                            code: PROCESS_TIMEOUT,
+                            message: `Process timed out after ${options.timeoutMs}ms`,
+                        };
+                    }
+                    terminateChild("SIGTERM");
+                }, options.timeoutMs);
+            }
+            try {
+                const observer = {
+                    output: (stream, data) => callbacks.onOutput(stream, data),
+                    exited: (exit) => callbacks.onExit(exit),
+                    outputClosed: (reason) => callbacks.onOutputClosed?.(reason),
+                    fault: (err) => callbacks.onError(err),
+                };
+                handle = (await this.driver.spawn(spec, observer));
+                if (cancelled || timedOut || outputLimitExceeded) {
+                    terminateChild("SIGTERM");
+                }
+            }
+            catch (spawnErr) {
+                callbacks.onError(spawnErr);
+                return;
+            }
+            if (options.input !== undefined && options.input !== null && handle) {
+                const inputBytes = typeof options.input === "string"
+                    ? new TextEncoder().encode(options.input)
+                    : options.input;
+                handle
+                    .write(inputBytes)
+                    .then(() => handle?.sendInputEOF?.())
+                    .catch((err) => {
+                    writeErr = err;
+                });
+            }
+        });
+    }
+    async spawn(command, args = [], options = {}) {
+        return this.exec(command, args, options);
+    }
+    async run(input, call) {
+        const runExecutor = new RunExecutor(this.driver);
+        return runExecutor.execute(input, call);
+    }
+    async start(_input, _call) {
+        throw new ProcessError(UNSUPPORTED_CAPABILITY, "NodeProcessExecutor does not support managed process start; use ProcessManager with NodeProcessDriver");
+    }
+    async inspect(_id, _call) {
+        throw new ProcessError(UNSUPPORTED_CAPABILITY, "NodeProcessExecutor does not support managed process inspect");
+    }
+    async list(_input, _call) {
+        return { processes: [] };
+    }
+    async acquire(_id, _input, _call) {
+        throw new ProcessError(UNSUPPORTED_CAPABILITY, "NodeProcessExecutor does not support managed process acquire");
+    }
+    async renew(_id, _token, _ttlMs, _call) {
+        throw new ProcessError(UNSUPPORTED_CAPABILITY, "NodeProcessExecutor does not support managed process renew");
+    }
+    async release(_id, _token, _call) {
+        throw new ProcessError(UNSUPPORTED_CAPABILITY, "NodeProcessExecutor does not support managed process release");
+    }
+    async write(_id, _input, _call) {
+        throw new ProcessError(UNSUPPORTED_CAPABILITY, "NodeProcessExecutor does not support managed process write");
+    }
+    async operation(_id, _requestId, _call) {
+        throw new ProcessError(UNSUPPORTED_CAPABILITY, "NodeProcessExecutor does not support managed process operation");
+    }
+    async read(_id, _input, _call) {
+        throw new ProcessError(UNSUPPORTED_CAPABILITY, "NodeProcessExecutor does not support managed process read");
+    }
+    async control(_id, _input, _call) {
+        throw new ProcessError(UNSUPPORTED_CAPABILITY, "NodeProcessExecutor does not support managed process control");
+    }
+    async stop(_id, _input, _call) {
+        throw new ProcessError(UNSUPPORTED_CAPABILITY, "NodeProcessExecutor does not support managed process stop");
+    }
+}
+/**
+ * 兼容原有类名导出。
+ */
+export { NodeProcessExecutor as ExecaProcessExecutor };

package/dist/process/process-manager.js

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import { decodeBytes, encodeBytes, } from "@actiondock/sdk";
 import { ACCESS_DENIED, CONTROL_BUSY, CONTROL_REVOKED, INPUT_VALIDATION_FAILED, NOT_FOUND, PROCESS_CANCELLED, PROCESS_LOST, PROCESS_QUARANTINED, PROCESS_SPAWN_ERROR, QUOTA_EXCEEDED, REQUEST_CONFLICT, SERVER_ERROR, UNSUPPORTED_CAPABILITY, INVALID_CURSOR, OUTPUT_UNAVAILABLE, ProcessError, } from "../errors.js";
 import { parseCursor, compareCursorPos } from "./cursor.js";
@@ -145,7 +145,7 @@ export class ProcessManager {
     initPromise;
     isShutdown = false;
     constructor(options) {
-        this.hostEpoch = options.hostEpoch ?? `epoch-${Date.now()}-${randomUUID().slice(0, 8)}`;
+        this.hostEpoch = options.hostEpoch ?? `epoch-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
         this.driver = options.driver;
         this.metadataStore = options.metadataStore ?? new MemoryProcessMetadataStore();
         this.quotas = {
@@ -321,7 +321,7 @@ export class ProcessManager {
      * 为指定所有者与运行上下文创建 ProcessAPI 代理适配器。
      */
     forOwner(owner, runId, signal) {
-        return new ContextProcessAPI(this, owner, runId ?? randomUUID(), signal, Boolean(runId));
+        return new ContextProcessAPI(this, owner, runId ?? crypto.randomUUID(), signal, Boolean(runId));
     }
     /**
      * 启动新的受管进程资源。
@@ -362,7 +362,7 @@ export class ProcessManager {
             if (input.spec.io.mode === "pty" && !caps.pty) {
                 throw new ProcessError(UNSUPPORTED_CAPABILITY, "Driver does not support PTY mode");
             }
-            const processId = `proc-${randomUUID()}`;
+            const processId = `proc-${crypto.randomUUID()}`;
             const effectiveLimits = {
                 idleMs: input.limits?.idleMs ?? this.defaultLimits.idleMs,
                 lifetimeMs: input.limits?.lifetimeMs ?? this.defaultLimits.lifetimeMs,
@@ -402,17 +402,18 @@ export class ProcessManager {
             // 调用驱动派生进程
             let abortListener;
             try {
-                const callbacks = {
-                    onOutput: (stream, data) => {
+                const observer = {
+                    processId,
+                    output: (stream, data) => {
                         procRecord.outputLog.append(stream, data);
                     },
-                    onExit: (exit) => {
+                    exited: (exit) => {
                         this.handleProcessExit(procRecord, exit);
                     },
-                    onOutputClosed: (reason) => {
+                    outputClosed: (reason) => {
                         this.handleOutputClosed(procRecord, reason);
                     },
-                    onError: (err) => {
+                    fault: (err) => {
                         this.handleProcessError(procRecord, err);
                     },
                 };
@@ -421,7 +422,7 @@ export class ProcessManager {
                         ? call.signal.reason
                         : new ProcessError(PROCESS_CANCELLED, "Process start was cancelled");
                 }
-                const spawnPromise = this.driver.spawn(processId, input.spec, callbacks);
+                const spawnPromise = this.driver.spawn(input.spec, observer);
                 if (call?.signal) {
                     const abortPromise = new Promise((_, reject) => {
                         abortListener = () => {
@@ -432,13 +433,13 @@ export class ProcessManager {
                         call.signal?.addEventListener("abort", abortListener, { once: true });
                     });
                     try {
-                        procRecord.handle = await Promise.race([spawnPromise, abortPromise]);
+                        procRecord.handle = (await Promise.race([spawnPromise, abortPromise]));
                     }
                     catch (raceErr) {
                         void spawnPromise
                             .then((h) => {
-                            if (h && typeof h.terminate === "function") {
-                                void h.terminate(0);
+                            if (h) {
+                                void this.driver.terminate(h, 0);
                             }
                         })
                             .catch(() => { });
@@ -451,11 +452,11 @@ export class ProcessManager {
                     }
                 }
                 else {
-                    procRecord.handle = await spawnPromise;
+                    procRecord.handle = (await spawnPromise);
                 }
                 if (call?.signal?.aborted) {
-                    if (procRecord.handle && typeof procRecord.handle.terminate === "function") {
-                        await procRecord.handle.terminate(0);
+                    if (procRecord.handle) {
+                        await this.driver.terminate(procRecord.handle, 0);
                     }
                     throw call.signal.reason instanceof ProcessError
                         ? call.signal.reason
@@ -510,8 +511,14 @@ export class ProcessManager {
             this.commitReservation(key, "start", startResult);
             return startResult;
         }
+        catch (err) {
+            // 失败路径：以原始错误结算预占，等待同 requestId 的并发调用方收到真实失败原因而非固定冲突错误
+            this.rejectReservation(key, "start", err);
+            throw err;
+        }
         finally {
-            // 成功路径已在 commit 中移除预占；此处仅对异常路径释放并唤醒等待方
+            // 成功路径已在 commit 中移除预占；失败路径已在 catch 中以原始错误结算；
+            // 此处仅为既未 commit 也未 reject 的异常逃逸路径释放预占并唤醒等待方
             this.rejectReservation(key, "start", new ProcessError(REQUEST_CONFLICT, "Concurrent start request did not produce a result", { requestId: input.requestId }));
         }
     }
@@ -600,8 +607,14 @@ export class ProcessManager {
             this.commitReservation(key, "acquire", grant);
             return grant;
         }
+        catch (err) {
+            // 失败路径：以原始错误结算预占，等待同 requestId 的并发调用方收到真实失败原因而非固定冲突错误
+            this.rejectReservation(key, "acquire", err);
+            throw err;
+        }
         finally {
-            // 成功路径已在 commit 中移除预占；此处仅对异常路径释放并唤醒等待方
+            // 成功路径已在 commit 中移除预占；失败路径已在 catch 中以原始错误结算；
+            // 此处仅为既未 commit 也未 reject 的异常逃逸路径释放预占并唤醒等待方
             this.rejectReservation(key, "acquire", new ProcessError(REQUEST_CONFLICT, "Concurrent acquire request did not produce a result", { requestId: input.requestId }));
         }
     }
@@ -682,8 +695,14 @@ export class ProcessManager {
             this.commitReservation(key, "write", queued);
             return queued;
         }
+        catch (err) {
+            // 失败路径：以原始错误结算预占，等待同 requestId 的并发调用方收到真实失败原因而非固定冲突错误
+            this.rejectReservation(key, "write", err);
+            throw err;
+        }
         finally {
-            // 成功路径已在 commit 中移除预占；此处仅对异常路径释放并唤醒等待方
+            // 成功路径已在 commit 中移除预占；失败路径已在 catch 中以原始错误结算；
+            // 此处仅为既未 commit 也未 reject 的异常逃逸路径释放预占并唤醒等待方
             this.rejectReservation(key, "write", new ProcessError(REQUEST_CONFLICT, "Concurrent write request did not produce a result", { requestId: input.requestId }));
         }
     }
@@ -741,8 +760,14 @@ export class ProcessManager {
             this.commitReservation(key, "control", queued);
             return queued;
         }
+        catch (err) {
+            // 失败路径：以原始错误结算预占，等待同 requestId 的并发调用方收到真实失败原因而非固定冲突错误
+            this.rejectReservation(key, "control", err);
+            throw err;
+        }
         finally {
-            // 成功路径已在 commit 中移除预占；此处仅对异常路径释放并唤醒等待方
+            // 成功路径已在 commit 中移除预占；失败路径已在 catch 中以原始错误结算；
+            // 此处仅为既未 commit 也未 reject 的异常逃逸路径释放预占并唤醒等待方
             this.rejectReservation(key, "control", new ProcessError(REQUEST_CONFLICT, "Concurrent control request did not produce a result", { requestId: input.requestId }));
         }
     }
@@ -874,10 +899,7 @@ export class ProcessManager {
         // 调用底层驱动终止；真实退出状态与输出流关闭由底层观察者事件收敛
         try {
             if (proc.handle) {
-                await proc.handle.terminate(input.graceMs);
-            }
-            else if (this.driver.terminate) {
-                await this.driver.terminate(id, input.graceMs);
+                await this.driver.terminate(proc.handle, input.graceMs);
             }
         }
         catch (err) {
@@ -981,7 +1003,7 @@ export class ProcessManager {
         }
         proc.info.endReason = "idle";
         this.stop(proc.owner, proc.info.id, {
-            requestId: `idle-${randomUUID()}`,
+            requestId: `idle-${crypto.randomUUID()}`,
             graceMs: 1000,
         }).catch((err) => {
             this.recordDiagnostic(`Idle timeout stop failed for process '${proc.info.id}'`, err);
@@ -998,7 +1020,7 @@ export class ProcessManager {
         }
         proc.info.endReason = "lifetime";
         this.stop(proc.owner, proc.info.id, {
-            requestId: `lifetime-${randomUUID()}`,
+            requestId: `lifetime-${crypto.randomUUID()}`,
             graceMs: 1000,
         }).catch((err) => {
             this.recordDiagnostic(`Lifetime timeout stop failed for process '${proc.info.id}'`, err);

package/dist/process/run-executor.js

@@ -1,4 +1,3 @@
-import { randomUUID } from "node:crypto";
 import { encodeBytes, } from "@actiondock/sdk";
 import { PROCESS_CANCELLED, PROCESS_TIMEOUT, UNSUPPORTED_CAPABILITY, ProcessError, } from "../errors.js";
 /**
@@ -27,7 +26,7 @@ export class RunExecutor {
                 mode: "pipe",
             },
         };
-        const runProcessId = `run-${randomUUID()}`;
+        const runProcessId = `run-${crypto.randomUUID()}`;
         const chunks = [];
         let totalBytes = 0;
         let truncated = false;
@@ -40,8 +39,8 @@ export class RunExecutor {
             rejectError = reject;
         });
         let driverHandle;
-        const callbacks = {
-            onOutput: (stream, data) => {
+        const observer = {
+            output: (stream, data) => {
                 if (truncated)
                     return;
                 if (stream !== "stdout" && stream !== "stderr")
@@ -50,7 +49,7 @@ export class RunExecutor {
                 if (remaining <= 0) {
                     truncated = true;
                     if (driverHandle) {
-                        void driverHandle.terminate(1000);
+                        void this.driver.terminate(driverHandle, 1000);
                     }
                     return;
                 }
@@ -63,7 +62,7 @@ export class RunExecutor {
                     totalBytes += slice.byteLength;
                     truncated = true;
                     if (driverHandle) {
-                        void driverHandle.terminate(1000);
+                        void this.driver.terminate(driverHandle, 1000);
                     }
                 }
                 else {
@@ -74,10 +73,11 @@ export class RunExecutor {
                     totalBytes += data.byteLength;
                 }
             },
-            onExit: (exit) => {
+            exited: (exit) => {
                 resolveExit(exit);
             },
-            onError: (err) => {
+            outputClosed: () => { },
+            fault: (err) => {
                 rejectError(err);
             },
         };
@@ -87,13 +87,13 @@ export class RunExecutor {
                 ? call.signal.reason
                 : new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
         }
-        driverHandle = await this.driver.spawn(runProcessId, effectiveSpec, callbacks);
+        driverHandle = await this.driver.spawn(effectiveSpec, observer);
         let timeoutTimer;
         if (input.timeoutMs > 0) {
             timeoutTimer = setTimeout(() => {
                 timedOut = true;
                 if (driverHandle) {
-                    void driverHandle.terminate(1000);
+                    void this.driver.terminate(driverHandle, 1000);
                 }
             }, input.timeoutMs);
             if (typeof timeoutTimer?.unref === "function") {
@@ -106,7 +106,7 @@ export class RunExecutor {
                 if (timeoutTimer)
                     clearTimeout(timeoutTimer);
                 if (driverHandle)
-                    void driverHandle.terminate(1000);
+                    void this.driver.terminate(driverHandle, 1000);
                 throw call.signal.reason ?? new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
             }
             onAbort = () => {
@@ -114,7 +114,7 @@ export class RunExecutor {
                 if (timeoutTimer)
                     clearTimeout(timeoutTimer);
                 if (driverHandle)
-                    void driverHandle.terminate(1000);
+                    void this.driver.terminate(driverHandle, 1000);
             };
             call.signal.addEventListener("abort", onAbort, { once: true });
         }

package/dist/profile/client-actions.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { ACTION_CANCELLED, ACTION_TIMEOUT, NETWORK_ERROR } from "../errors.js";
 import { getInsecureDispatcher } from "../server/dispatcher.js";
 import { normalizeServerUrl } from "./manager.js";
-import { assertSecureTransport, buildHeaders, fetchWithProtocolFallback, } from "./client-transport.js";
+import { assertSecureTransport, buildHeaders, fetchRemoteRoute, } from "./client-transport.js";
 import { buildQueryString, fetchRemoteJson } from "./client-query.js";
 /**
  * 执行远端 Action：支持幂等标识、异步触发、外部取消信号与本地超时守卫组合。
@@ -101,7 +101,7 @@ export async function executeRemoteAction(serverUrl, actionId, input = {}, confi
         }
         let res;
         try {
-            res = await fetchWithProtocolFallback(normalizeServerUrl(serverUrl), `/api/v2/actions/${encodeURIComponent(actionId)}/run`, fetchInit);
+            res = await fetchRemoteRoute(normalizeServerUrl(serverUrl), `/api/v2/actions/${encodeURIComponent(actionId)}/run`, fetchInit);
         }
         finally {
             if (timeoutTimer !== undefined) {

package/dist/profile/client-health.js

@@ -1,5 +1,5 @@
 import { normalizeServerUrl } from "./manager.js";
-import { assertSecureTransport, buildHeaders, fetchWithProtocolFallback, } from "./client-transport.js";
+import { assertSecureTransport, buildHeaders, fetchRemoteRoute, } from "./client-transport.js";
 import { getInsecureDispatcher } from "../server/dispatcher.js";
 /**
  * 远端健康检查域端点。
@@ -34,7 +34,7 @@ export async function checkRemoteHealth(serverUrl, token, timeoutMs = 5000, opti
             fetchInit.dispatcher = getInsecureDispatcher();
             fetchInit.tls = { rejectUnauthorized: false };
         }
-        const res = await fetchWithProtocolFallback(normalizeServerUrl(serverUrl), "/api/v2/health", fetchInit);
+        const res = await fetchRemoteRoute(normalizeServerUrl(serverUrl), "/api/v2/health", fetchInit);
         const latencyMs = Date.now() - startTime;
         if (!res.ok) {
             const text = await res.text().catch(() => "");

package/dist/profile/client-query.js

@@ -1,4 +1,5 @@
 import { createRemoteFetch } from "./client-transport.js";
+import { ActionDockError, NOT_FOUND, REMOTE_REQUEST_FAILED, UNAUTHORIZED } from "../errors.js";
 /**
  * 远端端点函数共享的请求与查询构造层。
  *
@@ -23,13 +24,11 @@ export async function fetchRemoteJson(serverUrl, path, token, options = {}) {
     if (!res.ok || (options.method === "POST" && data && data.ok === false)) {
         const errorPrefix = options.errorPrefix || "Remote request failed";
         const msg = data?.error?.message || `${errorPrefix} (${res.status}): ${res.statusText}`;
-        const err = new Error(msg);
-        if (data?.error?.code) {
-            err.code = data.error.code;
-        }
-        err.status = res.status;
+        const code = data?.error?.code ||
+            (res.status === 404 ? NOT_FOUND : res.status === 401 ? UNAUTHORIZED : REMOTE_REQUEST_FAILED);
+        const details = data?.error?.details ?? data?.error;
+        const err = new ActionDockError(code, msg, details, res.status);
         err.errorData = data?.error;
-        err.details = data?.error?.details ?? data?.error;
         throw err;
     }
     return data;