@actiondock/core 2.8.0 → 2.9.1

package/README.md

@@ -56,7 +56,7 @@ Service -> Resolution -> PackageRuntime -> ExecutionService -> ActionRunner -> A
 
 - 发现端口 `DiscoveryPort`：负责包与动作的元数据发现、清单检索、全文过滤与规程查询。
 - 执行端口 `ExecutionPort`：负责动作的同步阻塞执行（`run`）与异步启动执行（`start`）。
-- 运行端口 `RunsPort`：负责任务运行历史列表、单次详情查询与协同取消（`cancel`）。
+- 运行端口 `RunsPort`：负责任务运行历史列表、单次详情查询、协同取消（`cancel`）以及历史记录清理与保留策略淘汰（`clearRuns`、`cleanExpiredRuns`）。
 - 事件端口 `EventsPort`：负责任务执行实时事件流订阅。
 - 配置端口 `ConfigPort`：负责运行时分层配置读取、持久化配置管理与环境变量满足度体检。
 - 状态端口 `StatePort`：负责包级与动作级持久化键值存取、前缀列举与过期清理。
@@ -87,6 +87,26 @@ ActionDock 2.x 全面贯彻单一事实源设计，彻底杜绝各模块私自
 
 ---
 
+## 微服务启动与访问控制
+
+通过 `startActionDockServer` 启动 Node.js 原生 HTTP/HTTPS 微服务，提供标准 RESTful API 与统一内嵌 `/mcp` 端点：
+
+- 服务配置参数（`ServerOptions`）：
+  - `port`：监听端口（默认 5177）。
+  - `host`：监听地址（默认 127.0.0.1，监听非回环地址时强制要求配置 token）。
+  - `token`：服务访问鉴权令牌。
+  - `packageAllowlist`：允许访问执行的包标识白名单列表（为空允许全部）。
+  - `actionAllowlist`：允许访问执行的动作标识白名单列表（为空允许全部，支持短名 actionId 与全限定名 packageId/actionId）。
+  - `tls`：HTTPS 证书与私钥配置。
+  - `corsOrigins`：允许的跨域来源白名单。
+- 权限交集与安全拦截：
+  - 同时配置 `packageAllowlist` 与 `actionAllowlist` 时取两者交集。
+  - 未在白名单中的动作详情调阅与执行请求均被严格拦截，返回 HTTP 403 状态码与 `ACTION_FORBIDDEN` 结构化错误。
+  - 历史运行记录查询、单次详情与取消操作同步实施白名单校验。
+  - 统一内嵌的 MCP 协议端点工具注册与任务扩展同样受白名单联动过滤。
+
+---
+
 ## 数据目录锁与故障自愈
 
 通过 `DataDirLock` 在数据目录下维护 `.actiondock.data.lock` 排他文件锁，记录宿主进程与受管子进程状态：

package/dist/errors.d.ts

@@ -98,6 +98,8 @@ export declare const SERVER_ERROR = "SERVER_ERROR";
 export declare const BAD_REQUEST = "BAD_REQUEST";
 /** 目标包未列入允许白名单（403 禁止访问） */
 export declare const PACKAGE_FORBIDDEN = "PACKAGE_FORBIDDEN";
+/** 目标动作未列入允许白名单（403 禁止访问） */
+export declare const ACTION_FORBIDDEN = "ACTION_FORBIDDEN";
 /** 目标规程未找到 */
 export declare const PLAYBOOK_NOT_FOUND = "PLAYBOOK_NOT_FOUND";
 /** 请求体体积超出安全限制 */
@@ -265,7 +267,9 @@ export declare class ActionDockError<T = any> extends Error {
 /**
  * 集中定义的标准结构化错误码联合类型。
  */
-export type ErrorCode = typeof PACKAGE_NOT_FOUND | typeof ACTION_PACKAGE_VERSION_CONFLICT | typeof ACTION_NOT_FOUND | typeof ACTION_LOAD_FAILED | typeof ACTION_FAILED | typeof ACTION_TIMEOUT | typeof ACTION_CANCELLED | typeof INPUT_VALIDATION_FAILED | typeof OUTPUT_VALIDATION_FAILED | typeof INPUT_NOT_JSON | typeof OUTPUT_NOT_JSON | typeof ACTION_SUBRUN_LIMIT | typeof ACTION_CALL_CYCLE | typeof UNDECLARED_ACTION_DEPENDENCY | typeof INVALID_ACTION_REF | typeof IDEMPOTENCY_CONFLICT | typeof EXECUTION_FAILED | typeof UNHANDLED_EXECUTION_ERROR | typeof RUN_REPOSITORY_UNAVAILABLE | typeof RUN_PERSISTENCE_FAILED | typeof STANDALONE_ASYNC_UNSUPPORTED | typeof INVOCATION_UNSUPPORTED | typeof HOST_PROCESS_EXITED | typeof EXECUTION_ABORTED | typeof TIMEOUT | typeof SERVICE_CLOSED | typeof NETWORK_ERROR | typeof INSECURE_TRANSPORT | typeof REMOTE_REQUEST_FAILED | typeof REMOTE_STREAM_UNAVAILABLE | typeof CAPABILITY_UNAVAILABLE | typeof STATE_KEY_NOT_FOUND | typeof STORAGE_BUSY | typeof PROJECT_BUSY | typeof PROJECT_RECOVERY_REQUIRED | typeof STORAGE_WORKER_EXITED | typeof EVENT_BACKPRESSURE_LIMIT | typeof EVENT_CURSOR_EXPIRED | typeof PROCESS_OUTPUT_LIMIT | typeof PROCESS_SPAWN_ERROR | typeof PROCESS_CANCELLED | typeof PROCESS_TIMEOUT | typeof UNAUTHORIZED | typeof NOT_FOUND | typeof SERVER_ERROR | typeof BAD_REQUEST | typeof PACKAGE_FORBIDDEN | typeof PLAYBOOK_NOT_FOUND | typeof REQUEST_TOO_LARGE | typeof ACTION_START_FAILED | typeof ACTION_EXECUTION_ERROR | typeof ACTIONS_LIST_ERROR | typeof PLAYBOOKS_LIST_ERROR | typeof RUNS_LIST_ERROR | typeof RUNS_CLEAR_ERROR | typeof INFO_ERROR | typeof PACKAGES_INFO_ERROR | typeof DOCTOR_ERROR | typeof RUN_INTERRUPTED | typeof CONFIG_ENV_ERROR | typeof CONFIG_LIST_ERROR | typeof CONFIG_SET_ERROR | typeof CONFIG_DELETE_ERROR | typeof STATE_LIST_ERROR | typeof STATE_CLEAR_ERROR | typeof STATE_KEY_ERROR | typeof DATA_DIR_IN_USE | typeof DATA_DIR_RECOVERY_REQUIRED | typeof UNSUPPORTED_STORAGE_SCHEMA | typeof STORED_ERROR_DECODE_FAILED | typeof PROCESS_FAILED | typeof GENERATED_TYPES_OUTDATED | typeof PROTOCOL_UNSUPPORTED | typeof SERVICE_RESULT_UNKNOWN | typeof MCP_TOOL_NAME_COLLISION | typeof ACCESS_DENIED | typeof UNSUPPORTED_CAPABILITY | typeof CONTROL_BUSY | typeof CONTROL_EXPIRED | typeof CONTROL_REVOKED | typeof PROCESS_QUARANTINED | typeof PROCESS_LOST | typeof REQUEST_CONFLICT | typeof INPUT_OUTCOME_UNKNOWN | typeof OUTPUT_GAP | typeof OUTPUT_UNAVAILABLE | typeof INVALID_CURSOR | typeof QUEUE_FULL | typeof QUOTA_EXCEEDED | typeof INPUT_CLOSED | typeof INVALID_FLAT_ARGUMENT | typeof INVALID_JSON | typeof INVALID_JSON_LITERAL | typeof INPUT_PATH_CONFLICT | typeof FLAT_INPUT_LIMIT_EXCEEDED | typeof INPUT_LIMIT_EXCEEDED | typeof INPUT_POLICY_VIOLATION | typeof INPUT_CONFLICT | typeof INPUT_FILE_NOT_FOUND | typeof INPUT_FILE_READ_FAILED | typeof INVALID_ARGUMENT | typeof PACKAGE_NOT_ALLOWED | typeof INVALID_PACKAGE_ID | typeof PATH_TRAVERSAL | typeof AMBIGUOUS_STATE_KEY | typeof RUN_NOT_FOUND | typeof RUN_ALREADY_FINISHED | typeof IPC_ERROR | typeof SERVICE_ERROR;
+export type ErrorCode = typeof PACKAGE_NOT_FOUND | typeof ACTION_PACKAGE_VERSION_CONFLICT | typeof ACTION_NOT_FOUND | typeof ACTION_LOAD_FAILED | typeof ACTION_FAILED | typeof ACTION_TIMEOUT | typeof ACTION_CANCELLED | typeof INPUT_VALIDATION_FAILED | typeof OUTPUT_VALIDATION_FAILED | typeof INPUT_NOT_JSON | typeof OUTPUT_NOT_JSON | typeof ACTION_SUBRUN_LIMIT | typeof ACTION_CALL_CYCLE | typeof UNDECLARED_ACTION_DEPENDENCY | typeof INVALID_ACTION_REF | typeof IDEMPOTENCY_CONFLICT | typeof EXECUTION_FAILED | typeof UNHANDLED_EXECUTION_ERROR | typeof RUN_REPOSITORY_UNAVAILABLE | typeof RUN_PERSISTENCE_FAILED | typeof STANDALONE_ASYNC_UNSUPPORTED | typeof INVOCATION_UNSUPPORTED | typeof HOST_PROCESS_EXITED | typeof EXECUTION_ABORTED | typeof TIMEOUT | typeof SERVICE_CLOSED | typeof NETWORK_ERROR | typeof INSECURE_TRANSPORT | typeof REMOTE_REQUEST_FAILED | typeof REMOTE_STREAM_UNAVAILABLE | typeof CAPABILITY_UNAVAILABLE | typeof STATE_KEY_NOT_FOUND | typeof STORAGE_BUSY | typeof PROJECT_BUSY | typeof PROJECT_RECOVERY_REQUIRED | typeof STORAGE_WORKER_EXITED | typeof EVENT_BACKPRESSURE_LIMIT | typeof EVENT_CURSOR_EXPIRED | typeof PROCESS_OUTPUT_LIMIT | typeof PROCESS_SPAWN_ERROR | typeof PROCESS_CANCELLED | typeof PROCESS_TIMEOUT | typeof UNAUTHORIZED | typeof NOT_FOUND | typeof SERVER_ERROR | typeof BAD_REQUEST | typeof PACKAGE_FORBIDDEN | typeof ACTION_FORBIDDEN | typeof PLAYBOOK_NOT_FOUND | typeof REQUEST_TOO_LARGE | typeof ACTION_START_FAILED | typeof ACTION_EXECUTION_ERROR | typeof ACTIONS_LIST_ERROR | typeof PLAYBOOKS_LIST_ERROR | typeof RUNS_LIST_ERROR | typeof RUNS_CLEAR_ERROR | typeof INFO_ERROR | typeof PACKAGES_INFO_ERROR | typeof DOCTOR_ERROR | typeof RUN_INTERRUPTED | typeof CONFIG_ENV_ERROR | typeof CONFIG_LIST_ERROR | typeof CONFIG_SET_ERROR | typeof CONFIG_DELETE_ERROR | typeof STATE_LIST_ERROR | typeof STATE_CLEAR_ERROR | typeof STATE_KEY_ERROR | typeof DATA_DIR_IN_USE | typeof DATA_DIR_RECOVERY_REQUIRED | typeof UNSUPPORTED_STORAGE_SCHEMA | typeof STORED_ERROR_DECODE_FAILED | typeof PROCESS_FAILED | typeof GENERATED_TYPES_OUTDATED | typeof PROTOCOL_UNSUPPORTED | typeof SERVICE_RESULT_UNKNOWN | typeof MCP_TOOL_NAME_COLLISION | typeof ACCESS_DENIED | typeof UNSUPPORTED_CAPABILITY | typeof CONTROL_BUSY | typeof CONTROL_EXPIRED | typeof CONTROL_REVOKED | typeof PROCESS_QUARANTINED | typeof PROCESS_LOST | typeof REQUEST_CONFLICT | typeof INPUT_OUTCOME_UNKNOWN | typeof OUTPUT_GAP | typeof OUTPUT_UNAVAILABLE | typeof INVALID_CURSOR | typeof QUEUE_FULL | typeof QUOTA_EXCEEDED | typeof INPUT_CLOSED | typeof INVALID_FLAT_ARGUMENT | typeof INVALID_JSON | typeof INVALID_JSON_LITERAL | typeof INPUT_PATH_CONFLICT | typeof FLAT_INPUT_LIMIT_EXCEEDED | typeof INPUT_LIMIT_EXCEEDED | typeof INPUT_POLICY_VIOLATION | typeof INPUT_CONFLICT | typeof INPUT_FILE_NOT_FOUND | typeof INPUT_FILE_READ_FAILED | typeof INVALID_ARGUMENT | typeof PACKAGE_NOT_ALLOWED | typeof INVALID_PACKAGE_ID | typeof PATH_TRAVERSAL | typeof AMBIGUOUS_STATE_KEY | typeof RUN_NOT_FOUND | typeof RUN_ALREADY_FINISHED | typeof IPC_ERROR | typeof SERVICE_ERROR;
+/** 全仓统一错误码类型别名 */
+export type ActionDockErrorCode = ErrorCode;
 /**
  * 进程领域结构化异常类。
  */

package/dist/errors.js

@@ -98,6 +98,8 @@ export const SERVER_ERROR = "SERVER_ERROR";
 export const BAD_REQUEST = "BAD_REQUEST";
 /** 目标包未列入允许白名单（403 禁止访问） */
 export const PACKAGE_FORBIDDEN = "PACKAGE_FORBIDDEN";
+/** 目标动作未列入允许白名单（403 禁止访问） */
+export const ACTION_FORBIDDEN = "ACTION_FORBIDDEN";
 /** 目标规程未找到 */
 export const PLAYBOOK_NOT_FOUND = "PLAYBOOK_NOT_FOUND";
 /** 请求体体积超出安全限制 */

package/dist/host/host.d.ts

@@ -91,7 +91,9 @@ export declare class DefaultActionDockHost implements ActionDockHost {
         actionId?: string;
         status?: string;
         olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    cleanExpiredRuns(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     cancelRun(runId: string, reason?: string): Promise<CancelResult>;
     events(runId: string, options?: {
         after?: number | string;

package/dist/host/host.js

@@ -684,6 +684,16 @@ export class DefaultActionDockHost {
         }
         return total;
     }
+    async cleanExpiredRuns(policy) {
+        let total = 0;
+        for (const runtime of this.listRuntimes()) {
+            if (typeof runtime.cleanExpiredRuns === "function") {
+                const res = await runtime.cleanExpiredRuns(policy);
+                total += res;
+            }
+        }
+        return total;
+    }
     async cancelRun(runId, reason) {
         for (const runtime of this.listRuntimes()) {
             const res = await runtime.cancelRun(runId, reason);

package/dist/host/types.d.ts

@@ -80,7 +80,10 @@ export interface ActionDockHost {
         actionId?: string;
         status?: string;
         olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    /** 按保留策略清理所有运行时中的过期及超额终态运行记录 */
+    cleanExpiredRuns(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     /** 取消指定在运行的任务 */
     cancelRun(runId: string, reason?: string): Promise<CancelResult>;
     /** 订阅指定运行的事件流 */

package/dist/index.d.ts

@@ -8,6 +8,8 @@
 export { ACTIONDOCK_VERSION } from "./version.js";
 export { createActionDock, connectActionDock, } from "./service/factory.js";
 export type { ActionDockService, ActionDockService as ActionDock, DiscoveryPort, ExecutionPort, RunsPort, EventsPort, RunEventSubscriptionOptions, ConfigPort, StatePort, CreateActionDockOptions, ConnectActionDockOptions, RemoteServiceOptions, ConfigValueView, ListRunsOptions, StateScopeOptions, } from "./service/types.js";
+export { DEFAULT_RUNS_RETENTION_MS, DEFAULT_MAX_RUNS_PER_PACKAGE, DEFAULT_MIN_RETAIN_RUNS, type RunsRetentionPolicy, } from "./storage/types.js";
+export { parseDuration } from "./utils/index.js";
 export type { ActionRef, ResolvedActionRef, ExecutionResult, RunRecord, ExecutionEvent, } from "@actiondock/sdk";
 export type { RunOptions, ExecutionTicket, CancelResult, } from "./execution/types.js";
 export type { ActionSpec, ActionSummary, PlaybookSpec, PlaybookSummary, PackageInfo, ListActionsOptions, } from "./package/types.js";
@@ -18,4 +20,4 @@ export { initProject } from "./project/init.js";
 export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
 export type { ProjectConfig, } from "./project/types.js";
 export type { PackageGraph, } from "./catalog/graph.js";
-export { ActionDockError, ProcessError, type ErrorCode, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, INVOCATION_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, REMOTE_STREAM_UNAVAILABLE, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, STORAGE_WORKER_EXITED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, BAD_REQUEST, PACKAGE_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, ACTIONS_LIST_ERROR, PLAYBOOKS_LIST_ERROR, RUNS_LIST_ERROR, RUNS_CLEAR_ERROR, INFO_ERROR, PACKAGES_INFO_ERROR, DOCTOR_ERROR, RUN_INTERRUPTED, CONFIG_ENV_ERROR, CONFIG_LIST_ERROR, CONFIG_SET_ERROR, CONFIG_DELETE_ERROR, STATE_LIST_ERROR, STATE_CLEAR_ERROR, STATE_KEY_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, UNSUPPORTED_STORAGE_SCHEMA, STORED_ERROR_DECODE_FAILED, PROCESS_FAILED, GENERATED_TYPES_OUTDATED, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, UNSUPPORTED_CAPABILITY, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, PROCESS_QUARANTINED, PROCESS_LOST, REQUEST_CONFLICT, INPUT_OUTCOME_UNKNOWN, OUTPUT_GAP, OUTPUT_UNAVAILABLE, INVALID_CURSOR, QUEUE_FULL, QUOTA_EXCEEDED, INPUT_CLOSED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, IPC_ERROR, } from "./errors.js";
+export { ActionDockError, ProcessError, type ErrorCode, type ActionDockErrorCode, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, INVOCATION_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, REMOTE_STREAM_UNAVAILABLE, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, STORAGE_WORKER_EXITED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, BAD_REQUEST, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, ACTIONS_LIST_ERROR, PLAYBOOKS_LIST_ERROR, RUNS_LIST_ERROR, RUNS_CLEAR_ERROR, INFO_ERROR, PACKAGES_INFO_ERROR, DOCTOR_ERROR, RUN_INTERRUPTED, CONFIG_ENV_ERROR, CONFIG_LIST_ERROR, CONFIG_SET_ERROR, CONFIG_DELETE_ERROR, STATE_LIST_ERROR, STATE_CLEAR_ERROR, STATE_KEY_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, UNSUPPORTED_STORAGE_SCHEMA, STORED_ERROR_DECODE_FAILED, PROCESS_FAILED, GENERATED_TYPES_OUTDATED, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, UNSUPPORTED_CAPABILITY, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, PROCESS_QUARANTINED, PROCESS_LOST, REQUEST_CONFLICT, INPUT_OUTCOME_UNKNOWN, OUTPUT_GAP, OUTPUT_UNAVAILABLE, INVALID_CURSOR, QUEUE_FULL, QUOTA_EXCEEDED, INPUT_CLOSED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, IPC_ERROR, } from "./errors.js";

package/dist/index.js

@@ -9,6 +9,8 @@
 export { ACTIONDOCK_VERSION } from "./version.js";
 // 2. 统一服务门面与聚合契约接口
 export { createActionDock, connectActionDock, } from "./service/factory.js";
+export { DEFAULT_RUNS_RETENTION_MS, DEFAULT_MAX_RUNS_PER_PACKAGE, DEFAULT_MIN_RETAIN_RUNS, } from "./storage/types.js";
+export { parseDuration } from "./utils/index.js";
 // 5. 原生平台装配与服务启动
 export { createNodePlatform, } from "./platform/node.js";
 export { startActionDockServer, } from "./server/server.js";
@@ -16,4 +18,4 @@ export { startActionDockServer, } from "./server/server.js";
 export { initProject } from "./project/init.js";
 export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
 // 8. 统一错误模型与核心标准错误码常量
-export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, INVOCATION_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, REMOTE_STREAM_UNAVAILABLE, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, STORAGE_WORKER_EXITED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, BAD_REQUEST, PACKAGE_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, ACTIONS_LIST_ERROR, PLAYBOOKS_LIST_ERROR, RUNS_LIST_ERROR, RUNS_CLEAR_ERROR, INFO_ERROR, PACKAGES_INFO_ERROR, DOCTOR_ERROR, RUN_INTERRUPTED, CONFIG_ENV_ERROR, CONFIG_LIST_ERROR, CONFIG_SET_ERROR, CONFIG_DELETE_ERROR, STATE_LIST_ERROR, STATE_CLEAR_ERROR, STATE_KEY_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, UNSUPPORTED_STORAGE_SCHEMA, STORED_ERROR_DECODE_FAILED, PROCESS_FAILED, GENERATED_TYPES_OUTDATED, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, UNSUPPORTED_CAPABILITY, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, PROCESS_QUARANTINED, PROCESS_LOST, REQUEST_CONFLICT, INPUT_OUTCOME_UNKNOWN, OUTPUT_GAP, OUTPUT_UNAVAILABLE, INVALID_CURSOR, QUEUE_FULL, QUOTA_EXCEEDED, INPUT_CLOSED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, IPC_ERROR, } from "./errors.js";
+export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, INVOCATION_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, REMOTE_STREAM_UNAVAILABLE, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, STORAGE_WORKER_EXITED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, BAD_REQUEST, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, ACTIONS_LIST_ERROR, PLAYBOOKS_LIST_ERROR, RUNS_LIST_ERROR, RUNS_CLEAR_ERROR, INFO_ERROR, PACKAGES_INFO_ERROR, DOCTOR_ERROR, RUN_INTERRUPTED, CONFIG_ENV_ERROR, CONFIG_LIST_ERROR, CONFIG_SET_ERROR, CONFIG_DELETE_ERROR, STATE_LIST_ERROR, STATE_CLEAR_ERROR, STATE_KEY_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, UNSUPPORTED_STORAGE_SCHEMA, STORED_ERROR_DECODE_FAILED, PROCESS_FAILED, GENERATED_TYPES_OUTDATED, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, UNSUPPORTED_CAPABILITY, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, PROCESS_QUARANTINED, PROCESS_LOST, REQUEST_CONFLICT, INPUT_OUTCOME_UNKNOWN, OUTPUT_GAP, OUTPUT_UNAVAILABLE, INVALID_CURSOR, QUEUE_FULL, QUOTA_EXCEEDED, INPUT_CLOSED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, IPC_ERROR, } from "./errors.js";

package/dist/ipc/host.js

@@ -20,6 +20,7 @@ const IPC_METHOD_HANDLERS = {
     getRun: async (service, a) => service.runs.get(a[0]),
     cancelRun: async (service, a) => service.runs.cancel(a[0], a[1]),
     clearRuns: async (service, a) => service.runs.clear ? await service.runs.clear(a[0]) : 0,
+    cleanExpiredRuns: async (service, a) => service.runs.cleanExpired ? await service.runs.cleanExpired(a[0]) : 0,
     getConfig: async (service, a) => service.management?.config.get(a[0], a[1]),
     setConfig: async (service, a) => service.management?.config.set(a[0], a[1], a[2]),
     deleteConfig: async (service, a) => service.management?.config.delete(a[0], a[1]),

package/dist/ipc/service.js

@@ -184,6 +184,9 @@ export class IpcActionDockService {
             async clear(opts) {
                 return forward("clearRuns", [opts]);
             },
+            async cleanExpired(policy) {
+                return forward("cleanExpiredRuns", [policy]);
+            },
         };
         if (options.enableManagement !== false) {
             this.management = {

package/dist/package/runtime.d.ts

@@ -97,7 +97,10 @@ export declare class DefaultPackageRuntime implements HostManagedPackageRuntime
     clearRuns(options?: {
         actionId?: string;
         status?: string;
+        olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    cleanExpiredRuns(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     listStateEntries(options?: any): Promise<import("../storage/types.js").StateEntry[]>;
     close(options?: {
         graceMs?: number;

package/dist/package/runtime.js

@@ -581,8 +581,16 @@ export class DefaultPackageRuntime {
         return this.storage.clearRuns({
             actionId: options?.actionId,
             status: options?.status,
+            olderThanMs: options?.olderThanMs,
+            keep: options?.keep,
         });
     }
+    async cleanExpiredRuns(policy) {
+        if (typeof this.storage.cleanExpiredRuns === "function") {
+            return this.storage.cleanExpiredRuns(policy);
+        }
+        return 0;
+    }
     async listStateEntries(options) {
         if (typeof this.storage.listStateEntries === "function") {
             return this.storage.listStateEntries(options);

package/dist/package/types.d.ts

@@ -268,7 +268,11 @@ export interface PackageRuntime {
     clearRuns(options?: {
         actionId?: string;
         status?: string;
+        olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    /** 按保留策略清理过期及超额的终态运行记录（基于时间与数量策略） */
+    cleanExpiredRuns?(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     /** 订阅指定运行的事件流 */
     events(runId: string, options?: {
         after?: number | string;

package/dist/platform/node.js

@@ -64,6 +64,7 @@ export function createNodePlatform(options = {}) {
                 clock,
                 driver: createDriver(dbPath),
                 recoverOrphans: opts?.recoverOrphans === true,
+                retentionPolicy: opts?.retentionPolicy,
             });
         },
         createGlobalStorage(opts) {

package/dist/platform/types.d.ts

@@ -1,7 +1,7 @@
 import type { ProcessAPI } from "@actiondock/sdk";
 import type { Clock } from "../runtime/clock.js";
 import type { ModuleLoader } from "../runtime/module-loader.js";
-import type { RuntimeStorage } from "../storage/types.js";
+import type { RunsRetentionPolicy, RuntimeStorage } from "../storage/types.js";
 /**
  * 文件元数据信息契约。
  */
@@ -58,6 +58,8 @@ export interface StorageFactoryOptions {
      * 默认 false（旁观查询打开，不触碰在途记录），供 CLI 查询命令与执行宿主并发共存。
      */
     recoverOrphans?: boolean;
+    /** 运行记录保留策略配置 */
+    retentionPolicy?: RunsRetentionPolicy;
 }
 /**
  * 跨运行时全局存储工厂配置选项。

package/dist/profile/client-runs.d.ts

@@ -30,13 +30,22 @@ export declare function fetchRemoteRuns(serverUrl: string, token?: string, optio
     items: RunRecord[];
 }>;
 /**
- * 清空远端运行记录（可按包、Action、状态过滤清除范围）。
+ * 清空远端运行记录（可按包、Action、状态、保留时长、保留数量过滤清除范围）。
  */
 export declare function clearRemoteRuns(serverUrl: string, token?: string, options?: {
     packageId?: string;
     actionId?: string;
     status?: string;
+    olderThanMs?: number;
+    keep?: number;
 } & RemoteClientRequestOptions): Promise<{
     ok: boolean;
     clearedCount: number;
 }>;
+/**
+ * 按保留策略清理远端过期及超额运行记录。
+ */
+export declare function cleanExpiredRemoteRuns(serverUrl: string, token?: string, options?: import("../storage/types.js").RunsRetentionPolicy & RemoteClientRequestOptions): Promise<{
+    ok: boolean;
+    cleanedCount: number;
+}>;

package/dist/profile/client-runs.js

@@ -44,7 +44,7 @@ export async function fetchRemoteRuns(serverUrl, token, options) {
     });
 }
 /**
- * 清空远端运行记录（可按包、Action、状态过滤清除范围）。
+ * 清空远端运行记录（可按包、Action、状态、保留时长、保留数量过滤清除范围）。
  */
 export async function clearRemoteRuns(serverUrl, token, options) {
     return fetchRemoteJson(serverUrl, "/api/v2/runs/clear", token, {
@@ -56,3 +56,16 @@ export async function clearRemoteRuns(serverUrl, token, options) {
         dispatcher: options?.dispatcher,
     });
 }
+/**
+ * 按保留策略清理远端过期及超额运行记录。
+ */
+export async function cleanExpiredRemoteRuns(serverUrl, token, options) {
+    return fetchRemoteJson(serverUrl, "/api/v2/runs/clean-expired", token, {
+        method: "POST",
+        body: options || {},
+        errorPrefix: "Failed to clean expired remote runs",
+        allowInsecureHttp: options?.allowInsecureHttp,
+        insecure: options?.insecure,
+        dispatcher: options?.dispatcher,
+    });
+}

package/dist/profile/client.d.ts

@@ -21,6 +21,6 @@ export { checkRemoteHealth } from "./client-health.js";
 export { executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteDoctor, fetchRemoteInfo, } from "./client-actions.js";
 export type { RemoteExecuteOptions, RemoteExecutionResult } from "./client-actions.js";
 export { fetchRemotePlaybookShow, fetchRemotePlaybooks } from "./client-playbooks.js";
-export { cancelRemoteRun, clearRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
+export { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
 export { clearRemoteState, deleteRemoteStateKey, fetchRemoteStateList, getRemoteStateKey, setRemoteStateKey, } from "./client-state.js";
 export { deleteRemoteConfig, fetchRemoteConfig, fetchRemoteConfigEnv, setRemoteConfig, } from "./client-config.js";

package/dist/profile/client.js

@@ -24,7 +24,7 @@ export { executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRe
 // Playbook 规程查询
 export { fetchRemotePlaybookShow, fetchRemotePlaybooks } from "./client-playbooks.js";
 // 运行记录管理
-export { cancelRemoteRun, clearRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
+export { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
 // 状态存储管理
 export { clearRemoteState, deleteRemoteStateKey, fetchRemoteStateList, getRemoteStateKey, setRemoteStateKey, } from "./client-state.js";
 // 配置管理

package/dist/project/init.js

@@ -86,10 +86,10 @@ export function initProject(targetDir, options = {}) {
             node: ">=24.12.0",
         },
         dependencies: {
-            "@actiondock/sdk": "^2.8.0",
+            "@actiondock/sdk": "^2.9.1",
         },
         devDependencies: {
-            "@actiondock/testing": "^2.8.0",
+            "@actiondock/testing": "^2.9.1",
             "@types/node": "^22.13.0",
             "tsx": "^4.19.0",
             "typescript": "^5.7.0",

package/dist/project/types.d.ts

@@ -83,6 +83,11 @@ export interface ActionDockManifest {
     actionsDir?: string;
     /** Playbook 规程文档存放目录（向后兼容过渡配置） */
     playbooksDir?: string;
+    /** 服务端高级配置（如虚拟投影视图 views 等） */
+    server?: {
+        views?: Record<string, import("../server/types.js").ServerViewOptions> | import("../server/types.js").ServerViewOptions[];
+        [key: string]: unknown;
+    };
 }
 /**
  * ActionDock 项目根配置文件契约（等同于 ActionDockManifest，actiondock.json 为单一事实源）。

package/dist/server/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./security.js";
+export * from "./policy.js";
 export * from "./body.js";
 export * from "./routes/index.js";
 export * from "./server.js";

package/dist/server/index.js

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./security.js";
+export * from "./policy.js";
 export * from "./body.js";
 export * from "./routes/index.js";
 export * from "./server.js";

package/dist/server/policy.d.ts

@@ -0,0 +1,138 @@
+import { ActionDockError } from "../errors.js";
+import type { McpEndpointHandler } from "./mcp-endpoint.js";
+import type { EffectiveServerPolicy, ServerOptions, ServerViewOptions } from "./types.js";
+export { extractBearerToken } from "./security.js";
+/**
+ * 动作未列入白名单拒绝访问异常。
+ */
+export declare class ActionForbiddenError extends ActionDockError {
+    status: number;
+    statusCode: number;
+    constructor(actionRef: string);
+}
+/**
+ * 包未列入白名单拒绝访问异常。
+ */
+export declare class PackageNotAllowedError extends ActionDockError {
+    status: number;
+    statusCode: number;
+    constructor(packageId: string);
+}
+/**
+ * 归一化后的单个服务视图结构。
+ */
+export interface NormalizedServerView {
+    /** 视图唯一标识名称 */
+    name: string;
+    /** 该视图生效的统一安全策略 */
+    policy: EffectiveServerPolicy;
+    /** 该视图是否启用 MCP 端点 */
+    enableMcp: boolean;
+    /** 原始配置选项 */
+    rawOptions: ServerViewOptions;
+    /** 为该视图独立装配的 MCP 端点处理器 */
+    mcpEndpointHandler?: McpEndpointHandler;
+}
+/**
+ * 根据客户端携带的 Token 智能匹配已注册的视图。
+ * 使用 safeEqual 进行恒定时间比较以防范时序攻击。
+ *
+ * @param token 客户端提供的 Bearer Token
+ * @param views 可遍历的视图集合
+ * @returns 匹配成功的视图对象，未命中返回 undefined
+ */
+export declare function matchViewByToken(token: string, views: Iterable<NormalizedServerView>): NormalizedServerView | undefined;
+/**
+ * 归一化解析服务端配置的所有视图集合。
+ * 保证默认视图与显式自定义视图具有统一的数据结构。
+ *
+ * @param options 服务端配置选项
+ * @returns 默认视图与全部视图 Map 映射
+ */
+export declare function normalizeServerViews(options: ServerOptions): {
+    defaultView: NormalizedServerView;
+    views: Map<string, NormalizedServerView>;
+};
+/**
+ * 校验目标动作是否在 actionAllowlist 允许白名单中。
+ * 支持短名 actionId 与全限定名 packageId/actionId 匹配：
+ * - 白名单项若含 '/'（如 pkg/act），则必须 packageId 与 actionId 同时精确匹配。
+ * - 白名单项若不含 '/'（如 act），则只需 actionId 匹配（不限包）。
+ *
+ * @param action 目标动作对象或引用字符串
+ * @param allowlist 允许动作白名单列表
+ * @returns 是否允许访问
+ */
+export declare function isActionAllowed(action: {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string | null | undefined, allowlist?: string[]): boolean;
+/**
+ * 根据生效策略统一判定目标动作是否允许访问。
+ * 同时综合校验策略中的 packageAllowlist 与 actionAllowlist 约束。
+ *
+ * @param action 目标动作对象或引用字符串
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许访问
+ */
+export declare function isActionAllowedByPolicy(action: {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string | null | undefined, policy?: EffectiveServerPolicy): boolean;
+/**
+ * 根据生效策略统一判定目标包标识是否允许访问。
+ *
+ * @param packageId 目标包 ID
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许访问
+ */
+export declare function isPackageAllowedByPolicy(packageId?: string | null, policy?: EffectiveServerPolicy): boolean;
+/**
+ * 根据生效策略统一判定配置与状态管理路由是否开启。
+ *
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许管理操作
+ */
+export declare function isManagementAllowedByPolicy(policy?: EffectiveServerPolicy): boolean;
+/**
+ * 根据生效策略对动作列表进行统一过滤。
+ *
+ * @param actions 待过滤的动作列表
+ * @param policy 当前生效的服务端策略
+ * @returns 过滤后允许访问的动作列表
+ */
+export declare function filterActionsByPolicy<T extends {
+    id: string;
+    packageId?: string;
+    actionId?: string;
+}>(actions: T[], policy?: EffectiveServerPolicy): T[];
+/**
+ * 根据生效策略对包列表进行统一过滤。
+ *
+ * @param packages 待过滤的包列表
+ * @param policy 当前生效的服务端策略
+ * @returns 过滤后允许访问的包列表
+ */
+export declare function filterPackagesByPolicy<T extends {
+    id: string;
+}>(packages: T[], policy?: EffectiveServerPolicy): T[];
+/**
+ * 校验目标动作是否属于允许白名单，不符合则抛出 403 异常。
+ *
+ * @param action 目标动作对象或引用
+ * @param policy 当前生效的服务端策略
+ */
+export declare function assertActionAllowedByPolicy(action: {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string, policy?: EffectiveServerPolicy): void;
+/**
+ * 校验目标包是否属于允许白名单，不符合则抛出 403 异常。
+ *
+ * @param packageId 目标包 ID
+ * @param policy 当前生效的服务端策略
+ */
+export declare function assertPackageAllowedByPolicy(packageId: string, policy?: EffectiveServerPolicy): void;