@actiondock/core 2.10.0 → 2.12.0

package/dist/schema/validator.js

@@ -18,15 +18,8 @@ const validatorCache = new WeakMap();
 /**
  * 递归检查数据中是否包含危险的原型污染属性键名（__proto__、constructor、prototype）。
  */
-import { validateActionInputValue } from "../json/value-validator.js";
-/**
- * 递归检查数据中是否包含危险的原型污染属性键名（__proto__、constructor、prototype）。
- * 内部委托 validateActionInputValue 执行迭代遍历，确保环路安全、有向无环图安全且无调用栈溢出风险。
- */
-export function hasDangerousKeys(data) {
-    const result = validateActionInputValue(data);
-    return !result.valid && result.kind === "input-policy";
-}
+import { hasDangerousKeys } from "../value-validator.js";
+export { hasDangerousKeys };
 /**
  * 内部纯 Schema 校验器。
  * 仅处理布尔 Schema 与 Ajv 规则校验，严禁执行 dangerous-key 遍历。

package/dist/server/index.d.ts

@@ -5,7 +5,6 @@ export * from "./body.js";
 export * from "./routes/index.js";
 export * from "./server.js";
 export * from "./mcp-endpoint.js";
-export * from "./dispatcher.js";
 export * from "./http-server.js";
 export { serveParentIpc } from "../ipc/host.js";
 export { IpcActionDockService } from "../ipc/service.js";
@@ -13,6 +12,5 @@ export type { IpcServiceOptions } from "../ipc/types.js";
 export { parseDuration } from "../utils/index.js";
 export type { ActionDockHost, ActionDockHostOptions, } from "../host/types.js";
 export { createActionDockHost, DefaultActionDockHost, } from "../host/host.js";
-export { LocalActionDockService, } from "../service/local.js";
 export { RemoteActionDockService, } from "../service/remote.js";
 export { ExitCode, StandaloneDispatcher, type StandaloneDispatcherOptions, type InvocationControl, runStandaloneProcess, } from "../runtime/standalone.js";

package/dist/server/index.js

@@ -5,13 +5,11 @@ export * from "./body.js";
 export * from "./routes/index.js";
 export * from "./server.js";
 export * from "./mcp-endpoint.js";
-export * from "./dispatcher.js";
 export * from "./http-server.js";
 export { serveParentIpc } from "../ipc/host.js";
 export { IpcActionDockService } from "../ipc/service.js";
 export { parseDuration } from "../utils/index.js";
 export { createActionDockHost, DefaultActionDockHost, } from "../host/host.js";
-export { LocalActionDockService, } from "../service/local.js";
 export { RemoteActionDockService, } from "../service/remote.js";
 // 独立进程分发器与退出控制
 export { ExitCode, StandaloneDispatcher, runStandaloneProcess, } from "../runtime/standalone.js";

package/dist/server/routes/actions.js

@@ -1,5 +1,5 @@
 import { parseActionRef } from "../../catalog/resolve-action.js";
-import { filterByIntent } from "../../filter/index.js";
+import { filterByIntent } from "../../utils/intent.js";
 import { ACTION_EXECUTION_ERROR, ACTION_FORBIDDEN, ACTION_NOT_FOUND, ACTION_START_FAILED, ACTION_TIMEOUT, ACTIONS_LIST_ERROR, IDEMPOTENCY_CONFLICT, INPUT_VALIDATION_FAILED, INVALID_JSON, PACKAGE_FORBIDDEN, PACKAGE_NOT_FOUND, REQUEST_TOO_LARGE, } from "../../errors.js";
 import { InvalidJsonError, readJsonBody, RequestTooLargeError } from "../body.js";
 import { filterActionsByPolicy, getSubPath, isActionAllowedByPolicy, isPackageAllowedByPolicy, jsonResponse, } from "./common.js";

package/dist/server/routes/info.js

@@ -1,4 +1,4 @@
-import { filterWithFallbackInfo } from "../../filter/index.js";
+import { filterWithFallbackInfo } from "../../utils/intent.js";
 import { INFO_ERROR, PACKAGE_NOT_ALLOWED, PACKAGE_NOT_FOUND, PACKAGES_INFO_ERROR } from "../../errors.js";
 import { ACTIONDOCK_VERSION } from "../../version.js";
 import { sanitizeConfigDefinitions } from "../../storage/index.js";

package/dist/server/routes/playbooks.js

@@ -1,4 +1,4 @@
-import { filterByIntent } from "../../filter/index.js";
+import { filterByIntent } from "../../utils/intent.js";
 import { PACKAGE_NOT_ALLOWED, PLAYBOOK_NOT_FOUND, PLAYBOOKS_LIST_ERROR } from "../../errors.js";
 import { assertPackageAllowed, getSubPath, isPackageAllowedByPolicy, jsonResponse } from "./common.js";
 /**

package/dist/server/routes/runs.js

@@ -1,5 +1,6 @@
-import { ACTION_FORBIDDEN, CAPABILITY_UNAVAILABLE, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, EXECUTION_FAILED, PACKAGE_FORBIDDEN, RUN_ALREADY_FINISHED, RUN_INTERRUPTED, RUN_NOT_FOUND, RUNS_CLEAR_ERROR, RUNS_LIST_ERROR, } from "../../errors.js";
+import { ACTION_FORBIDDEN, CAPABILITY_UNAVAILABLE, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, EXECUTION_FAILED, INVALID_ARGUMENT, PACKAGE_FORBIDDEN, RUN_ALREADY_FINISHED, RUN_INTERRUPTED, RUN_NOT_FOUND, RUNS_CLEAR_ERROR, RUNS_LIST_ERROR, } from "../../errors.js";
 import { isTerminalRunStatus } from "../../storage/types.js";
+import { createAbortError } from "../../ipc/service.js";
 import { parseDuration } from "../../utils/index.js";
 import { readJsonBody } from "../body.js";
 import { getSubPath, isActionAllowedByPolicy, isPackageAllowedByPolicy, jsonResponse } from "./common.js";
@@ -16,11 +17,36 @@ export async function handleRunsRoutes(ctx) {
             const actionId = url.searchParams.get("actionId") || undefined;
             const packageId = url.searchParams.get("packageId") || undefined;
             const intent = url.searchParams.get("intent") || undefined;
-            // limit 边界防护：非法或超界值回退默认 50，并夹紧到 1 至 500 区间
-            const parsedLimit = parseInt(url.searchParams.get("limit") || "50", 10);
-            const limit = Number.isFinite(parsedLimit) && parsedLimit > 0
-                ? Math.min(parsedLimit, 500)
-                : 50;
+            // requestId 反查：支持 requestId 与 requestIds 重复查询参数，将每一个参数值作为原样字符串保存
+            const requestIds = [
+                ...url.searchParams.getAll("requestId"),
+                ...url.searchParams.getAll("requestIds"),
+            ].filter((id) => id.length > 0);
+            // offset 校验：非负安全整数，默认为 0，上限 100000 防止滥用
+            const rawOffset = url.searchParams.get("offset");
+            let offset = 0;
+            if (rawOffset !== null && rawOffset !== "") {
+                const parsedOffset = Number(rawOffset);
+                if (!Number.isSafeInteger(parsedOffset) || parsedOffset < 0 || parsedOffset > 100_000) {
+                    return jsonResponse({
+                        ok: false,
+                        error: {
+                            code: INVALID_ARGUMENT,
+                            message: `Invalid offset '${rawOffset}': must be a non-negative safe integer <= 100000`,
+                        },
+                    }, 400, corsHeaders);
+                }
+                offset = parsedOffset;
+            }
+            // limit 边界防护：未提供保持默认值 50，提供则夹紧在 1 至 500 区间
+            const rawLimit = url.searchParams.get("limit");
+            let limit = 50;
+            if (rawLimit !== null) {
+                const parsedLimit = parseInt(rawLimit, 10);
+                if (Number.isFinite(parsedLimit)) {
+                    limit = Math.min(Math.max(parsedLimit, 1), 500);
+                }
+            }
             if (packageId && !isPackageAllowedByPolicy(packageId, policy)) {
                 return jsonResponse({
                     ok: false,
@@ -39,23 +65,104 @@ export async function handleRunsRoutes(ctx) {
                     },
                 }, 403, corsHeaders);
             }
-            let allRuns = await service.runs.list({
+            const queryOptions = {
                 actionId,
                 status,
                 packageId,
                 intent,
-                limit,
-            });
-            if (policy.packageAllowlist && policy.packageAllowlist.length > 0) {
-                allRuns = allRuns.filter((r) => isPackageAllowedByPolicy(r.packageId, policy));
+                requestIds: requestIds.length > 0 ? requestIds : undefined,
+                signal: req.signal,
+                packageAllowlist: policy.packageAllowlist && policy.packageAllowlist.length > 0
+                    ? policy.packageAllowlist
+                    : undefined,
+            };
+            const hasPolicyFilter = Boolean((policy.packageAllowlist && policy.packageAllowlist.length > 0) ||
+                (policy.actionAllowlist && policy.actionAllowlist.length > 0));
+            let runs;
+            let total;
+            if (hasPolicyFilter) {
+                const BATCH_SIZE = 100;
+                let cursorOffset = 0;
+                let matchedCount = 0;
+                const pagedRuns = [];
+                while (true) {
+                    if (req.signal?.aborted) {
+                        throw createAbortError(req.signal.reason);
+                    }
+                    const batch = await service.runs.list({
+                        ...queryOptions,
+                        limit: BATCH_SIZE,
+                        offset: cursorOffset,
+                        signal: req.signal,
+                    }, { signal: req.signal });
+                    if (req.signal?.aborted) {
+                        throw createAbortError(req.signal.reason);
+                    }
+                    if (batch.length === 0) {
+                        break;
+                    }
+                    for (const run of batch) {
+                        const packageAllowed = isPackageAllowedByPolicy(run.packageId, policy);
+                        const actionAllowed = isActionAllowedByPolicy({ packageId: run.packageId, actionId: run.actionId }, policy);
+                        if (packageAllowed && actionAllowed) {
+                            if (matchedCount >= offset && pagedRuns.length < limit) {
+                                pagedRuns.push(run);
+                            }
+                            matchedCount++;
+                        }
+                    }
+                    cursorOffset += batch.length;
+                    if (batch.length < BATCH_SIZE) {
+                        break;
+                    }
+                }
+                runs = pagedRuns;
+                total = matchedCount;
+            }
+            else {
+                // 当 hasPolicyFilter 为 false 时：下推 limit 与 offset 到底层查询
+                if (req.signal?.aborted) {
+                    throw createAbortError(req.signal.reason);
+                }
+                runs = await service.runs.list({
+                    ...queryOptions,
+                    limit,
+                    offset,
+                    signal: req.signal,
+                }, { signal: req.signal });
+                if (req.signal?.aborted) {
+                    throw createAbortError(req.signal.reason);
+                }
+                // 统计总数 total 的可靠处理：
+                if (typeof service.runs.count === "function") {
+                    total = await service.runs.count({
+                        ...queryOptions,
+                        signal: req.signal,
+                    }, { signal: req.signal });
+                }
+                else if (runs.length === 0 && offset === 0) {
+                    total = 0;
+                }
+                else if (runs.length > 0 && runs.length < limit) {
+                    total = offset + runs.length;
+                }
+                else {
+                    total = undefined;
+                }
             }
-            if (policy.actionAllowlist && policy.actionAllowlist.length > 0) {
-                allRuns = allRuns.filter((r) => isActionAllowedByPolicy({ packageId: r.packageId, actionId: r.actionId }, policy));
+            const responseData = {
+                ok: true,
+                items: runs,
+            };
+            if (typeof total === "number") {
+                responseData.total = total;
             }
-            const sliced = allRuns.slice(0, limit);
-            return jsonResponse({ ok: true, total: allRuns.length, items: sliced }, 200, corsHeaders);
+            return jsonResponse(responseData, 200, corsHeaders);
         }
         catch (err) {
+            if (req.signal?.aborted || err?.name === "AbortError") {
+                throw err;
+            }
             return jsonResponse({ ok: false, error: { code: RUNS_LIST_ERROR, message: err.message } }, 500, corsHeaders);
         }
     }
@@ -310,7 +417,7 @@ export async function handleRunsRoutes(ctx) {
     const runShowMatch = subpath.match(/^\/runs\/([^/]+)$/);
     if (runShowMatch && req.method === "GET") {
         const runId = decodeURIComponent(runShowMatch[1]);
-        const run = await service.runs.get(runId);
+        const run = await service.runs.get(runId, { signal: req.signal });
         if (!run) {
             return jsonResponse({
                 ok: false,

package/dist/server/routes/state.js

@@ -38,7 +38,8 @@ export async function handleStateRoutes(ctx) {
     if (subpath === "/state" && req.method === "GET") {
         try {
             const pkgParam = url.searchParams.get("package") || url.searchParams.get("packageId") || undefined;
-            const actionParam = url.searchParams.get("action") || url.searchParams.get("actionId") || "";
+            const rawAction = url.searchParams.get("action") ?? url.searchParams.get("actionId");
+            const actionParam = rawAction !== null ? rawAction : undefined;
             const nsParam = url.searchParams.get("namespace") ?? undefined;
             const prefix = url.searchParams.get("prefix") || "";
             const pkgs = await service.discovery.listPackages();
@@ -68,8 +69,13 @@ export async function handleStateRoutes(ctx) {
         try {
             const body = await readJsonBody(req, { maxBytes: options.maxBodyBytes }).catch(() => ({}));
             const pkgParam = url.searchParams.get("package") || url.searchParams.get("packageId") || body.package || undefined;
-            const actionParam = url.searchParams.get("action") || url.searchParams.get("actionId") || body.action || body.actionId || "";
-            const baseNs = body.namespace ?? (url.searchParams.get("namespace") || undefined);
+            const rawAction = url.searchParams.get("action") ??
+                url.searchParams.get("actionId") ??
+                body.action ??
+                body.actionId;
+            const actionParam = rawAction !== null && rawAction !== undefined ? rawAction : undefined;
+            const rawNs = body.namespace ?? url.searchParams.get("namespace");
+            const baseNs = rawNs !== null && rawNs !== undefined ? rawNs : undefined;
             const pkgs = await service.discovery.listPackages();
             const targetPackageId = resolveTargetPackageId(pkgs, pkgParam, policy);
             const clearedCount = await service.management.state.clear(targetPackageId, actionParam, {
@@ -99,13 +105,21 @@ export async function handleStateRoutes(ctx) {
         try {
             const key = decodeURIComponent(stateKeyMatch[1]);
             const pkgParam = url.searchParams.get("package") || url.searchParams.get("packageId") || undefined;
-            const actionParam = url.searchParams.get("action") || url.searchParams.get("actionId") || "";
-            const nsParam = url.searchParams.get("namespace") || undefined;
+            const rawAction = url.searchParams.get("action") ?? url.searchParams.get("actionId");
+            const actionParam = rawAction !== null ? rawAction : undefined;
+            const nsParam = url.searchParams.get("namespace") ?? undefined;
             const pkgs = await service.discovery.listPackages();
             const targetPackageId = resolveTargetPackageId(pkgs, pkgParam, policy);
             if (req.method === "GET") {
-                const entry = await service.management.state.get(targetPackageId, actionParam, key, {
-                    namespace: nsParam,
+                let actualKey = key;
+                let ns = nsParam;
+                if (actionParam === undefined && nsParam === undefined) {
+                    const decoded = decodeStateKey(key);
+                    ns = decoded.namespace;
+                    actualKey = decoded.key;
+                }
+                const entry = await service.management.state.get(targetPackageId, actionParam ?? "", actualKey, {
+                    namespace: ns,
                     detail: true,
                 });
                 if (!entry || (typeof entry === "object" && entry.value === undefined)) {
@@ -113,12 +127,12 @@ export async function handleStateRoutes(ctx) {
                 }
                 const data = typeof entry === "object" && "value" in entry
                     ? entry
-                    : { key, namespace: nsParam || "", value: entry, expiresAt: undefined };
+                    : { key: actualKey, namespace: ns ?? "", value: entry, expiresAt: undefined };
                 return jsonResponse({
                     ok: true,
                     packageId: targetPackageId,
-                    key: data.key || key,
-                    namespace: data.namespace ?? nsParam ?? "",
+                    key: data.key ?? actualKey,
+                    namespace: data.namespace ?? ns ?? "",
                     value: data.value,
                     expiresAt: data.expiresAt,
                 }, 200, corsHeaders);
@@ -127,29 +141,40 @@ export async function handleStateRoutes(ctx) {
                 const body = await readJsonBody(req, { maxBytes: options.maxBodyBytes });
                 const val = body.value !== undefined ? body.value : body;
                 const ttl = typeof body.ttl === "number" ? body.ttl : undefined;
-                const bodyAction = body.action || body.actionId || actionParam;
-                const explicitNs = body.namespace || nsParam;
+                const rawActionFromReq = url.searchParams.get("action") ??
+                    url.searchParams.get("actionId") ??
+                    body.action ??
+                    body.actionId;
+                const bodyAction = rawActionFromReq !== null && rawActionFromReq !== undefined ? rawActionFromReq : undefined;
+                const explicitNs = body.namespace ?? nsParam;
                 let actualKey = key;
                 let ns = explicitNs;
-                if (!bodyAction && !explicitNs) {
+                if (bodyAction === undefined && explicitNs === undefined) {
                     const decoded = decodeStateKey(key);
                     ns = decoded.namespace;
                     actualKey = decoded.key;
                 }
-                await service.management.state.set(targetPackageId, bodyAction, actualKey, val, {
+                await service.management.state.set(targetPackageId, bodyAction ?? "", actualKey, val, {
                     namespace: ns,
                     ttl,
                 });
-                return jsonResponse({ ok: true, packageId: targetPackageId, key: actualKey, namespace: ns || bodyAction || "", message: "updated" }, 200, corsHeaders);
+                return jsonResponse({ ok: true, packageId: targetPackageId, key: actualKey, namespace: ns ?? bodyAction ?? "", message: "updated" }, 200, corsHeaders);
             }
             if (req.method === "DELETE") {
-                const deleted = await service.management.state.delete(targetPackageId, actionParam, key, {
-                    namespace: nsParam,
+                let actualKey = key;
+                let ns = nsParam;
+                if (actionParam === undefined && nsParam === undefined) {
+                    const decoded = decodeStateKey(key);
+                    ns = decoded.namespace;
+                    actualKey = decoded.key;
+                }
+                const deleted = await service.management.state.delete(targetPackageId, actionParam ?? "", actualKey, {
+                    namespace: ns,
                 });
                 if (!deleted) {
                     return jsonResponse({ ok: false, error: { code: STATE_KEY_NOT_FOUND, message: `State key '${key}' not found` } }, 404, corsHeaders);
                 }
-                return jsonResponse({ ok: true, packageId: targetPackageId, key, deleted: true }, 200, corsHeaders);
+                return jsonResponse({ ok: true, packageId: targetPackageId, key: actualKey, deleted: true }, 200, corsHeaders);
             }
         }
         catch (err) {

package/dist/server/security.d.ts

@@ -1,4 +1,4 @@
-export { isLoopbackHost } from "../utils/net.js";
+export { isLoopbackHost } from "../utils/index.js";
 /**
  * 恒定时间字符串比较（Constant-time comparison）。
  * 使用底层的 `crypto.timingSafeEqual` 防范时序攻击（Timing Attack）。

package/dist/server/security.js

@@ -1,6 +1,6 @@
 import { timingSafeEqual } from "node:crypto";
-// isLoopbackHost 已上移至 utils/net.ts（通用谓词单一事实源），此处仅保留 re-export 兼容旧引用路径
-export { isLoopbackHost } from "../utils/net.js";
+// isLoopbackHost 已上移至 utils（通用谓词单一事实源），此处仅保留 re-export 兼容旧引用路径
+export { isLoopbackHost } from "../utils/index.js";
 /**
  * 恒定时间字符串比较（Constant-time comparison）。
  * 使用底层的 `crypto.timingSafeEqual` 防范时序攻击（Timing Attack）。

package/dist/server/server.js

@@ -1,9 +1,8 @@
 import { posix, resolve } from "node:path";
 import { NodeHttpServer } from "./http-server.js";
 import { createActionDock } from "../service/factory.js";
-import { NOT_FOUND, UNAUTHORIZED } from "../errors.js";
+import { ActionDockError, ACCESS_DENIED, NOT_FOUND, SERVICE_ERROR, UNAUTHORIZED } from "../errors.js";
 import { parseActionRef } from "../catalog/resolve-action.js";
-import { ensureDependencyClosure } from "../project/closure.js";
 import { findProjectRoot } from "../project/loader.js";
 import { listLinkedPackages, resolvePackageRoot } from "../registry/registry.js";
 import { handleActionsRoutes, handleConfigRoutes, handleDoctorRoute, handleHealthRoute, handleInfoRoute, handlePlaybooksRoutes, handleRunsRoutes, handleStateRoutes, jsonResponse, } from "./routes/index.js";
@@ -57,7 +56,7 @@ export async function startActionDockServer(options = {}) {
         defaultView.policy.token ||
         Array.from(views.values()).some((v) => Boolean(v.policy.token)));
     if (!isLoopbackHost(host) && !hasTokenConfigured && !options.allowInsecureNoAuth) {
-        throw new Error("Authentication token is required when binding to a non-loopback address. Use --allow-insecure-no-auth to override.");
+        throw new ActionDockError(ACCESS_DENIED, "Authentication token is required when binding to a non-loopback address. Use --allow-insecure-no-auth to override.");
     }
     let serviceInstance = options.service;
     // 若未传 service，服务端统一通过 createActionDock() 实例化，不再接受或处理外部传入的 Host 实体
@@ -74,7 +73,7 @@ export async function startActionDockServer(options = {}) {
         });
     }
     if (!serviceInstance) {
-        throw new Error("Failed to initialize ActionDockService for server");
+        throw new ActionDockError(SERVICE_ERROR, "Failed to initialize ActionDockService for server");
     }
     // 2. 聚合所有 views 声明的依赖包与动作，确保依赖闭包满足
     const roots = [];
@@ -124,9 +123,6 @@ export async function startActionDockServer(options = {}) {
             catch { }
         }
     }
-    if (roots.length > 0) {
-        await ensureDependencyClosure(roots, { customHome });
-    }
     // 3. 为每个启用 MCP 的视图独立装配 MCP 处理器
     if (options.enableMcp !== false) {
         for (const v of views.values()) {

package/dist/service/factory.js

@@ -1,5 +1,4 @@
 import { createActionDockHost } from "../host/host.js";
-import { LocalActionDockService } from "./local.js";
 import { RemoteActionDockService } from "./remote.js";
 import { ActionDockError, INVALID_ARGUMENT, NOT_FOUND } from "../errors.js";
 /**
@@ -21,16 +20,18 @@ export async function createActionDock(options = {}) {
             process: options.runtimeOptions.process,
             logger: options.runtimeOptions.logger,
             recoverOrphans: options.recoverOrphans,
+            enableManagement: options.enableManagement,
         });
-        return new LocalActionDockService(host, { enableManagement: options.enableManagement });
+        return host;
     }
     const host = await createActionDockHost({
         scanLinkedPackages: options.scanLinkedPackages ?? true,
         ...options,
         recoverOrphans: options.recoverOrphans ?? true,
+        enableManagement: options.enableManagement,
         ...(options.hostOptions || {}),
     });
-    return new LocalActionDockService(host, { enableManagement: options.enableManagement });
+    return host;
 }
 /**
  * 工厂函数：连接远端 ActionDock 服务实例。

package/dist/service/index.d.ts

@@ -1,4 +1,4 @@
 export * from "./types.js";
-export * from "./local.js";
 export * from "./remote.js";
 export * from "./factory.js";
+export { DefaultActionDockHost, DefaultActionDockHost as DefaultActionDockService } from "../host/host.js";

package/dist/service/index.js

@@ -1,4 +1,4 @@
 export * from "./types.js";
-export * from "./local.js";
 export * from "./remote.js";
 export * from "./factory.js";
+export { DefaultActionDockHost, DefaultActionDockHost as DefaultActionDockService } from "../host/host.js";

package/dist/service/remote-errors.d.ts

@@ -1,7 +1,7 @@
 /**
  * 远端通信错误翻译层。
  *
- * 职责单一：将 profile/client 传输层抛出的底层异常翻译为统一的
+ * 职责单一：将 client 传输层抛出的底层异常翻译为统一的
  * 结构化异常，供 RemoteActionDockService 各操作边界复用；
  * 优先读取传输层透传的结构化错误码，无法识别时原样透传。
  */

package/dist/service/remote-errors.js

@@ -1,12 +1,12 @@
 /**
  * 远端通信错误翻译层。
  *
- * 职责单一：将 profile/client 传输层抛出的底层异常翻译为统一的
+ * 职责单一：将 client 传输层抛出的底层异常翻译为统一的
  * 结构化异常，供 RemoteActionDockService 各操作边界复用；
  * 优先读取传输层透传的结构化错误码，无法识别时原样透传。
  */
-import { CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND } from "../errors.js";
-import { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, ServiceError, } from "./types.js";
+import { ActionDockError, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND } from "../errors.js";
+import { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, } from "./types.js";
 /**
  * 将远端通信异常包装翻译为统一的异常。
  *
@@ -16,16 +16,16 @@ export function wrapRemoteError(err) {
     const code = err?.code || "";
     if (code === "CAPABILITY_UNAVAILABLE" ||
         code === "TARGET_CAPABILITY_UNAVAILABLE") {
-        throw new ServiceError(CAPABILITY_UNAVAILABLE, `CAPABILITY_UNAVAILABLE: Management APIs are not enabled on remote service`, { originalMessage: err?.message });
+        throw new ActionDockError(CAPABILITY_UNAVAILABLE, `CAPABILITY_UNAVAILABLE: Management APIs are not enabled on remote service`, { originalMessage: err?.message });
     }
     if (code === "PROTOCOL_UNSUPPORTED" ||
         code === "TARGET_PROTOCOL_UNSUPPORTED") {
-        throw new ServiceError(PROTOCOL_UNSUPPORTED, `PROTOCOL_UNSUPPORTED: ${err?.message || ""}`, { originalMessage: err?.message });
+        throw new ActionDockError(PROTOCOL_UNSUPPORTED, `PROTOCOL_UNSUPPORTED: ${err?.message || ""}`, { originalMessage: err?.message });
     }
     if (code === "SERVICE_RESULT_UNKNOWN" ||
         code === "TARGET_RESULT_UNKNOWN" ||
         code === "RESULT_UNKNOWN") {
-        throw new ServiceError(SERVICE_RESULT_UNKNOWN, `SERVICE_RESULT_UNKNOWN: ${err?.message || ""}`, { originalMessage: err?.message });
+        throw new ActionDockError(SERVICE_RESULT_UNKNOWN, `SERVICE_RESULT_UNKNOWN: ${err?.message || ""}`, { originalMessage: err?.message });
     }
     throw err;
 }

package/dist/service/remote-polling.d.ts

@@ -6,6 +6,7 @@
  * ExecutionResult 结构。不感知 SSE 通道与门面生命周期。
  */
 import type { ExecutionResult, RunRecord } from "@actiondock/sdk";
+import { type Clock } from "../storage/clock.js";
 /**
  * 轮询依赖上下文：由 RemoteActionDockService 门面注入自身能力，
  * 保持本模块与门面实现解耦。
@@ -17,6 +18,8 @@ export interface RunPollingContext {
     isClosed(): boolean;
     /** 查询远端运行详情（键不存在时返回 undefined） */
     getRun(runId: string): Promise<RunRecord | undefined>;
+    /** 可选注入时钟抽象（缺省使用系统时钟） */
+    clock?: Clock;
 }
 /**
  * 将终态运行记录翻译为统一 ExecutionResult 结构。

package/dist/service/remote-polling.js

@@ -6,8 +6,11 @@
  * ExecutionResult 结构。不感知 SSE 通道与门面生命周期。
  */
 import { ACTION_CANCELLED, EXECUTION_FAILED, RUN_INTERRUPTED, TIMEOUT } from "../errors.js";
+import { SystemClock } from "../storage/clock.js";
 import { isTerminalRunStatus } from "../storage/types.js";
 import { SERVICE_CLOSED } from "./types.js";
+/** 模块级默认时钟实例 */
+const defaultClock = new SystemClock();
 /**
  * 将终态运行记录翻译为统一 ExecutionResult 结构。
  */
@@ -44,12 +47,14 @@ export function formatTerminalRunResult(run, runId) {
  * @param startTime 等待起点时间戳（缺省当前时间）
  * @param totalMaxWaitMs 已消耗等待预算对应的总上限（SSE 阶段已等待时传入）
  */
-export async function pollRunCompletion(ctx, runId, signal, timeoutMs, startTime = Date.now(), totalMaxWaitMs) {
+export async function pollRunCompletion(ctx, runId, signal, timeoutMs, startTime, totalMaxWaitMs) {
+    const clock = ctx.clock ?? defaultClock;
+    const effectiveStartTime = startTime ?? clock.monotonic();
     const maxWaitMs = totalMaxWaitMs ?? Math.max(ctx.baseTimeoutMs, timeoutMs ?? 0);
-    const remainingWaitMs = Math.max(0, maxWaitMs - (Date.now() - startTime));
+    const remainingWaitMs = Math.max(0, maxWaitMs - (clock.monotonic() - effectiveStartTime));
     let delayMs = Math.min(150, Math.max(10, Math.floor((remainingWaitMs || maxWaitMs) / 4)));
     const maxDelayMs = 2000;
-    while (Date.now() - startTime < maxWaitMs) {
+    while (clock.monotonic() - effectiveStartTime < maxWaitMs) {
         if (ctx.isClosed()) {
             return {
                 ok: false,
@@ -89,10 +94,10 @@ export async function pollRunCompletion(ctx, runId, signal, timeoutMs, startTime
             }
             throw err;
         }
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        await clock.sleep(delayMs);
         delayMs = Math.min(delayMs * 2, maxDelayMs);
     }
-    const waitedMs = Date.now() - startTime;
+    const waitedMs = Math.round(clock.monotonic() - effectiveStartTime);
     return {
         ok: false,
         runId,

package/dist/service/remote.d.ts

@@ -1,4 +1,5 @@
 import type { PackageInfo } from "../package/types.js";
+import { type Clock } from "../storage/clock.js";
 import { type RemoteServiceOptions } from "./types.js";
 import type { ActionDockService, ConfigPort, ConnectActionDockOptions, DiscoveryPort, EventsPort, ExecutionPort, RunsPort, StatePort } from "./types.js";
 /**
@@ -14,6 +15,7 @@ export declare class RemoteActionDockService implements ActionDockService {
     readonly allowInsecureHttp?: boolean;
     readonly insecure?: boolean;
     readonly dispatcher?: unknown;
+    readonly clock: Clock;
     private isClosed;
     readonly discovery: DiscoveryPort;
     readonly execution: ExecutionPort;
@@ -23,7 +25,9 @@ export declare class RemoteActionDockService implements ActionDockService {
         config: ConfigPort;
         state: StatePort;
     };
-    constructor(options: ConnectActionDockOptions | RemoteServiceOptions);
+    constructor(options: (ConnectActionDockOptions | RemoteServiceOptions) & {
+        clock?: Clock;
+    });
     private assertNotClosed;
     info(): Promise<PackageInfo[]>;
     private waitForRunCompletion;