@actiondock/core 2.8.0 → 2.9.1

package/dist/server/security.js

@@ -13,49 +13,66 @@ export function safeEqual(a, b) {
     const aa = Buffer.from(a);
     const bb = Buffer.from(b);
     if (aa.length !== bb.length) {
+        // 长度不等时对自身做一次恒定时间比较，消除因长度不等提前退出带来的时序差
+        timingSafeEqual(aa, aa);
         return false;
     }
     return timingSafeEqual(aa, bb);
 }
 /**
- * 校验 HTTP 请求中的鉴权令牌是否有效。
+ * 从 HTTP 请求中提取 Bearer Token。
  *
  * 默认仅接受 HTTP 请求头: `Authorization: Bearer <token>`。
- * 仅当 options.allowQueryToken 为 true 时才允许解析 URL 查询参数 `?token=<token>`。
+ * 仅当 allowQueryToken 为 true 时才允许解析 URL 查询参数 `?token=<token>`。
  *
  * @param req 传入的 HTTP Request 对象
- * @param expectedToken 服务端预期的正确 Token（若未配置 Token 则默认放行）
- * @param options 校验选项或布尔值 allowQueryToken 开关
- * @returns 是否鉴权成功
+ * @param allowQueryToken 是否允许从 URL 查询参数解析 Token
+ * @returns 提取出的 Token 字符串，若未携带则返回 null
  */
-export function verifyBearerToken(req, expectedToken, options) {
-    if (!expectedToken || !expectedToken.trim()) {
-        return true;
-    }
-    const trimmedExpected = expectedToken.trim();
+export function extractBearerToken(req, allowQueryToken) {
     // 1. 请求头 Authorization: Bearer <token>
     const authHeader = req.headers.get("authorization");
     if (authHeader && authHeader.startsWith("Bearer ")) {
         const token = authHeader.slice(7).trim();
-        if (safeEqual(token, trimmedExpected)) {
-            return true;
-        }
+        if (token)
+            return token;
     }
     // 2. URL 查询参数: ?token=<token>（仅当显式开启 allowQueryToken 时允许）
-    const allowQuery = typeof options === "boolean" ? options : options?.allowQueryToken === true;
-    if (allowQuery) {
+    if (allowQueryToken) {
         try {
             const url = new URL(req.url);
             const tokenParam = url.searchParams.get("token");
-            if (tokenParam && safeEqual(tokenParam.trim(), trimmedExpected)) {
-                return true;
+            if (tokenParam && tokenParam.trim()) {
+                return tokenParam.trim();
             }
         }
         catch {
-            // 畸形 URL 视作鉴权失败
+            // 畸形 URL 忽略
         }
     }
-    return false;
+    return null;
+}
+/**
+ * 校验 HTTP 请求中的鉴权令牌是否有效。
+ *
+ * 默认仅接受 HTTP 请求头: `Authorization: Bearer <token>`。
+ * 仅当 options.allowQueryToken 为 true 时才允许解析 URL 查询参数 `?token=<token>`。
+ *
+ * @param req 传入的 HTTP Request 对象
+ * @param expectedToken 服务端预期的正确 Token（若未配置 Token 则默认放行）
+ * @param options 校验选项或布尔值 allowQueryToken 开关
+ * @returns 是否鉴权成功
+ */
+export function verifyBearerToken(req, expectedToken, options) {
+    if (!expectedToken || !expectedToken.trim()) {
+        return true;
+    }
+    const allowQuery = typeof options === "boolean" ? options : options?.allowQueryToken === true;
+    const token = extractBearerToken(req, allowQuery);
+    if (!token) {
+        return false;
+    }
+    return safeEqual(token, expectedToken.trim());
 }
 /**
  * 根据配置的 CORS 白名单解析并返回跨域响应头。

package/dist/server/server.js

@@ -1,13 +1,15 @@
-import { resolve } from "node:path";
+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 { 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";
 import { isLoopbackHost, resolveCorsHeaders, verifyBearerToken } from "./security.js";
 import { createMcpEndpointHandler } from "./mcp-endpoint.js";
+import { extractBearerToken, matchViewByToken, normalizeServerViews, } from "./policy.js";
 /**
  * 规范化主机地址用于拼接 URL。
  * 若 host 包含冒号 : 且不以 [ 开头，则添加中括号包裹（IPv6 标准格式）。
@@ -48,8 +50,13 @@ export async function startActionDockServer(options = {}) {
     const projectRoot = options.projectRoot
         ? resolve(options.projectRoot)
         : findProjectRoot(process.cwd());
+    // 1. 归一化解析视图配置集合（含默认视图与自定义视图）
+    const { defaultView, views } = normalizeServerViews(options);
     // 非回环地址强制要求配置 Token 鉴权（防裸奔）
-    if (!isLoopbackHost(host) && !token && !options.allowInsecureNoAuth) {
+    const hasTokenConfigured = Boolean(token ||
+        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.");
     }
     let serviceInstance = options.service;
@@ -69,12 +76,27 @@ export async function startActionDockServer(options = {}) {
     if (!serviceInstance) {
         throw new Error("Failed to initialize ActionDockService for server");
     }
+    // 2. 聚合所有 views 声明的依赖包与动作，确保依赖闭包满足
     const roots = [];
     if (projectRoot) {
         roots.push(projectRoot);
     }
-    if (options.packageAllowlist && options.packageAllowlist.length > 0) {
-        for (const pkgId of options.packageAllowlist) {
+    const aggregatedPackageAllowlist = new Set();
+    const aggregatedActionAllowlist = new Set();
+    for (const v of views.values()) {
+        if (v.policy.packageAllowlist) {
+            for (const pkg of v.policy.packageAllowlist) {
+                aggregatedPackageAllowlist.add(pkg);
+            }
+        }
+        if (v.policy.actionAllowlist) {
+            for (const act of v.policy.actionAllowlist) {
+                aggregatedActionAllowlist.add(act);
+            }
+        }
+    }
+    if (aggregatedPackageAllowlist.size > 0) {
+        for (const pkgId of aggregatedPackageAllowlist) {
             const r = resolvePackageRoot(pkgId, projectRoot || undefined, customHome);
             if (r && !roots.includes(r)) {
                 roots.push(r);
@@ -88,18 +110,85 @@ export async function startActionDockServer(options = {}) {
             }
         }
     }
+    if (aggregatedActionAllowlist.size > 0) {
+        for (const actRef of aggregatedActionAllowlist) {
+            try {
+                const parsed = parseActionRef(actRef);
+                if (parsed.packageId) {
+                    const r = resolvePackageRoot(parsed.packageId, projectRoot || undefined, customHome);
+                    if (r && !roots.includes(r)) {
+                        roots.push(r);
+                    }
+                }
+            }
+            catch { }
+        }
+    }
     if (roots.length > 0) {
         await ensureDependencyClosure(roots, { customHome });
     }
-    // MCP 统一网关端点处理器：鉴权、请求体限流与委托序列收敛为共享单一事实源
-    const mcpEndpointHandler = options.mcpHandler
-        ? createMcpEndpointHandler(options.mcpHandler, {
-            token,
-            allowQueryToken: options.allowQueryToken,
-            corsOrigins: options.corsOrigins,
-            maxBodyBytes: options.maxBodyBytes,
-        })
-        : undefined;
+    // 3. 为每个启用 MCP 的视图独立装配 MCP 处理器
+    if (options.enableMcp !== false) {
+        for (const v of views.values()) {
+            if (v.enableMcp !== false) {
+                let delegate;
+                if (v.rawOptions.mcpHandler) {
+                    if (v.rawOptions.mcpHandler.length >= 2) {
+                        delegate = (req) => v.rawOptions.mcpHandler(req, v.policy);
+                    }
+                    else {
+                        let factoryResult;
+                        try {
+                            factoryResult = v.rawOptions.mcpHandler(v.policy);
+                        }
+                        catch {
+                            factoryResult = null;
+                        }
+                        if (typeof factoryResult === "function") {
+                            delegate = factoryResult;
+                        }
+                        else {
+                            delegate = (req) => v.rawOptions.mcpHandler(req, v.policy);
+                        }
+                    }
+                }
+                else if (options.mcpHandlerFactory) {
+                    delegate = options.mcpHandlerFactory(v.policy);
+                }
+                else if (options.mcpHandler) {
+                    if (options.mcpHandler.length >= 2) {
+                        delegate = (req) => options.mcpHandler(req, v.policy);
+                    }
+                    else {
+                        let factoryResult;
+                        try {
+                            factoryResult = options.mcpHandler(v.policy);
+                        }
+                        catch {
+                            factoryResult = null;
+                        }
+                        if (typeof factoryResult === "function") {
+                            delegate = factoryResult;
+                        }
+                        else {
+                            if (factoryResult && typeof factoryResult.catch === "function") {
+                                factoryResult.catch(() => { });
+                            }
+                            delegate = (req) => options.mcpHandler(req, v.policy);
+                        }
+                    }
+                }
+                if (delegate) {
+                    v.mcpEndpointHandler = createMcpEndpointHandler(delegate, {
+                        token: v.policy.token,
+                        allowQueryToken: options.allowQueryToken,
+                        corsOrigins: options.corsOrigins,
+                        maxBodyBytes: options.maxBodyBytes,
+                    });
+                }
+            }
+        }
+    }
     const fetchHandler = async (req) => {
         const origin = req.headers.get("origin");
         const corsHeaders = resolveCorsHeaders(origin, options.corsOrigins);
@@ -110,32 +199,113 @@ export async function startActionDockServer(options = {}) {
             });
         }
         const url = new URL(req.url);
-        const pathname = url.pathname;
+        const rawPathname = url.pathname;
+        let activeView;
+        let effectivePathname;
+        let effectiveReq = req;
+        // 1. 检查是否为 /views/:viewName/... 命名空间路由
+        const viewMatch = rawPathname.match(/^\/views\/([^/]+)(\/.*)?$/);
+        if (viewMatch) {
+            let viewName;
+            try {
+                viewName = decodeURIComponent(viewMatch[1]);
+            }
+            catch {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: NOT_FOUND,
+                        message: `Invalid view name encoding: '${viewMatch[1]}'`,
+                    },
+                }, 400, corsHeaders);
+            }
+            const matched = views.get(viewName);
+            if (!matched) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: NOT_FOUND,
+                        message: `View '${viewName}' not found`,
+                    },
+                }, 404, corsHeaders);
+            }
+            activeView = matched;
+            // 规范化子路径，防范路径穿透与多斜杠混淆
+            let rawEffective = viewMatch[2] || "/";
+            if (!rawEffective.startsWith("/")) {
+                rawEffective = "/" + rawEffective;
+            }
+            const normalizedPath = posix.normalize(rawEffective);
+            effectivePathname = normalizedPath.startsWith("/") ? normalizedPath : "/" + normalizedPath;
+            // 剥离 /views/:viewName 前缀后重构 URL 与 Request
+            const rewrittenUrl = new URL(req.url);
+            rewrittenUrl.pathname = effectivePathname;
+            try {
+                const init = {
+                    method: req.method,
+                    headers: req.headers,
+                    signal: req.signal,
+                };
+                if (req.body && req.method !== "GET" && req.method !== "HEAD") {
+                    init.body = req.body;
+                    init.duplex = "half";
+                }
+                effectiveReq = new Request(rewrittenUrl.toString(), init);
+            }
+            catch {
+                effectiveReq = req;
+            }
+        }
+        else {
+            // 根路径请求：智能根据 Bearer Token 匹配视图或回退默认视图（遍历全量视图以防范时序差异）
+            effectivePathname = rawPathname;
+            const clientToken = extractBearerToken(req, options.allowQueryToken);
+            if (clientToken) {
+                const matchedByToken = matchViewByToken(clientToken, views.values());
+                activeView = matchedByToken ?? defaultView;
+            }
+            else {
+                activeView = defaultView;
+            }
+        }
+        const effectivePolicy = activeView.policy;
+        const effectiveUrl = new URL(effectiveReq.url);
+        effectiveUrl.pathname = effectivePathname;
         const ctx = {
-            req,
-            url,
-            pathname,
+            req: effectiveReq,
+            url: effectiveUrl,
+            pathname: effectivePathname,
             corsHeaders,
             projectRoot,
             customHome,
             service: serviceInstance,
             options,
+            activePolicy: effectivePolicy,
         };
-        // 1. 健康检查路由（内部处理独立鉴权逻辑）
+        // 2. 健康检查路由（内部处理独立鉴权逻辑，使用 activePolicy.token）
         const healthResponse = await handleHealthRoute(ctx);
         if (healthResponse) {
             return healthResponse;
         }
-        // 2. MCP 统一网关端点（委托共享端点处理器）
-        if (options.enableMcp !== false &&
-            mcpEndpointHandler &&
-            (pathname === "/mcp" || pathname.startsWith("/mcp/"))) {
-            const mcpRes = await mcpEndpointHandler(req);
-            if (mcpRes)
-                return mcpRes;
+        // 3. MCP 统一网关端点（委托当前视图的端点处理器）
+        if (effectivePathname === "/mcp" || effectivePathname.startsWith("/mcp/")) {
+            if (activeView.enableMcp === false || options.enableMcp === false) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: NOT_FOUND,
+                        message: `MCP endpoint is disabled for view '${activeView.name}'`,
+                    },
+                }, 404, corsHeaders);
+            }
+            if (activeView.mcpEndpointHandler) {
+                const mcpRes = await activeView.mcpEndpointHandler(effectiveReq);
+                if (mcpRes)
+                    return mcpRes;
+            }
         }
-        // 3. 全局 API 认证鉴权拦截
-        if (!verifyBearerToken(req, token, options)) {
+        // 4. API 认证鉴权拦截（基于当前生效策略中的 Token）
+        if (!verifyBearerToken(effectiveReq, effectivePolicy.token, options)) {
             return jsonResponse({
                 ok: false,
                 error: {
@@ -144,7 +314,7 @@ export async function startActionDockServer(options = {}) {
                 },
             }, 401, corsHeaders);
         }
-        // 4. 业务领域路由分发（完全委托 Service）
+        // 5. 业务领域路由分发（完全委托 Service 与 RouteContext 中的 activePolicy）
         const routeResponse = (await handleInfoRoute(ctx)) ||
             (await handleDoctorRoute(ctx)) ||
             (await handleActionsRoutes(ctx)) ||
@@ -155,12 +325,12 @@ export async function startActionDockServer(options = {}) {
         if (routeResponse) {
             return routeResponse;
         }
-        // 5. 404 路由兜底
+        // 6. 404 路由兜底
         return jsonResponse({
             ok: false,
             error: {
                 code: NOT_FOUND,
-                message: `Route not found: ${req.method} ${pathname}`,
+                message: `Route not found: ${req.method} ${rawPathname}`,
             },
         }, 404, corsHeaders);
     };
@@ -170,6 +340,17 @@ export async function startActionDockServer(options = {}) {
     }
     const actualHost = host === "0.0.0.0" ? "127.0.0.1" : host;
     const protocol = options.tls ? "https" : "http";
+    // 启动后台运行记录定期自动清理巡检定时器（默认 1 小时巡检一次）
+    const runsCleanupIntervalMs = 3600_000;
+    let runsCleanupTimer;
+    if (serviceInstance.runs?.cleanExpired) {
+        runsCleanupTimer = setInterval(() => {
+            serviceInstance?.runs?.cleanExpired?.().catch((err) => {
+                console.warn(`[ActionDockServer] Periodic runs cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }, runsCleanupIntervalMs);
+        runsCleanupTimer.unref();
+    }
     const instance = {
         get port() {
             return server.port ?? port;
@@ -183,6 +364,10 @@ export async function startActionDockServer(options = {}) {
         },
         ready: Promise.resolve(),
         stop: async (stopOptions) => {
+            if (runsCleanupTimer) {
+                clearInterval(runsCleanupTimer);
+                runsCleanupTimer = undefined;
+            }
             await server.stop(true);
             if (serviceInstance) {
                 try {

package/dist/server/types.d.ts

@@ -18,6 +18,40 @@ export interface ServerTlsOptions {
     /** 私钥密码口令（若私钥被密码加密） */
     passphrase?: string;
 }
+/**
+ * 单个虚拟投影视图（Virtual View）的配置选项。
+ */
+export interface ServerViewOptions {
+    /** 视图唯一标识名称（若在 views 对象中配置则键名作为默认名称） */
+    name?: string;
+    /** 该视图独立的 Bearer Token 鉴权令牌 */
+    token?: string;
+    /** 该视图允许访问执行的 Package ID 白名单列表（为空允许全部） */
+    packageAllowlist?: string[];
+    /** 该视图允许访问执行的 Action 标识白名单列表（为空允许全部，支持短名或 packageId/actionId） */
+    actionAllowlist?: string[];
+    /** 该视图是否开启配置与状态管理路由能力（默认关闭） */
+    enableManagement?: boolean;
+    /** 该视图是否启用一体化 MCP 协议支持（默认开启） */
+    enableMcp?: boolean;
+    /** 该视图自定义的 MCP 请求处理器钩子（可选，支持请求处理函数或接收视图策略的工厂函数） */
+    mcpHandler?: ((req: Request, view?: EffectiveServerPolicy) => Promise<Response | null | undefined> | Response | null | undefined) | ((view: EffectiveServerPolicy) => ((req: Request) => Promise<Response | null | undefined> | Response | null | undefined));
+}
+/**
+ * 当前请求上下文生效的统一服务端安全策略。
+ */
+export interface EffectiveServerPolicy {
+    /** 当前生效的视图名称（默认视图为 "default"） */
+    viewName?: string;
+    /** 当前生效的 Bearer Token 鉴权令牌 */
+    token?: string;
+    /** 当前生效的 Package ID 白名单列表 */
+    packageAllowlist?: string[];
+    /** 当前生效的 Action 标识白名单列表 */
+    actionAllowlist?: string[];
+    /** 当前生效的管理能力开关 */
+    enableManagement?: boolean;
+}
 /**
  * 启动 ActionDock HTTP Runner 服务端的配置选项。
  */
@@ -48,14 +82,18 @@ export interface ServerOptions {
     corsOrigins?: string[];
     /** 允许访问执行的 Package ID 白名单列表（为空允许全部） */
     packageAllowlist?: string[];
+    /** 允许访问执行的 Action 标识白名单列表（为空允许全部，支持短名或 packageId/actionId） */
+    actionAllowlist?: string[];
     /** 最大允许的请求体字节限制（默认 1MB，防 DoS） */
     maxBodyBytes?: number;
     /** 是否在 health 和 info 接口中透传本地 projectRoot 等调试路径 */
     exposeDebugInfo?: boolean;
     /** 是否启用一体化 MCP 协议支持（默认开启） */
     enableMcp?: boolean;
-    /** 自定义 MCP 请求处理器钩子（若挂载则 /mcp 路由交由其处理） */
-    mcpHandler?: (req: Request) => Promise<Response | null | undefined> | Response | null | undefined;
+    /** 自定义 MCP 请求处理器钩子（若挂载则 /mcp 路由交由其处理，支持处理函数或接收视图策略的工厂函数） */
+    mcpHandler?: ((req: Request, view?: EffectiveServerPolicy) => Promise<Response | null | undefined> | Response | null | undefined) | ((view: EffectiveServerPolicy) => ((req: Request) => Promise<Response | null | undefined> | Response | null | undefined));
+    /** 自定义 MCP 处理器工厂函数（可选，为每个视图创建独立处理器） */
+    mcpHandlerFactory?: (view: EffectiveServerPolicy) => ((req: Request) => Promise<Response | null | undefined> | Response | null | undefined);
     /** 可选注入的统一运行时底层平台 */
     platform?: import("../platform/types.js").RuntimePlatform;
     /** 是否显式开启配置与状态管理路由能力（默认关闭，关闭时返回 403） */
@@ -64,6 +102,26 @@ export interface ServerOptions {
     scanLinkedPackages?: boolean;
     /** 服务端 TLS/HTTPS 安全传输选项 */
     tls?: ServerTlsOptions;
+    /**
+     * 虚拟投影视图配置。
+     * 支持对象字典形式 Record<string, ServerViewOptions> 或数组形式 ServerViewOptions[]。
+     * 单端口上支持多视图独立隔离 Token、白名单与管理权限。
+     */
+    views?: Record<string, ServerViewOptions> | ServerViewOptions[];
+}
+/**
+ * 路由处理统一上下文对象。
+ */
+export interface RouteContext {
+    req: Request;
+    url: URL;
+    pathname: string;
+    corsHeaders: Record<string, string>;
+    projectRoot: string | null;
+    customHome?: string;
+    service: ActionDockService;
+    options: ServerOptions;
+    activePolicy: EffectiveServerPolicy;
 }
 /**
  * 已启动的 ActionDock HTTP Runner 实例句柄。

package/dist/service/local.js

@@ -67,6 +67,9 @@ export class LocalActionDockService {
             async clear(opts) {
                 return self.host.clearRuns(opts);
             },
+            async cleanExpired(policy) {
+                return self.host.cleanExpiredRuns(policy);
+            },
         };
         this.events = {
             events(runId, opts) {

package/dist/service/remote.js

@@ -1,6 +1,6 @@
 import { parseActionRef } from "../catalog/resolve-action.js";
 import { ActionDockError, ACTION_CANCELLED, CAPABILITY_UNAVAILABLE, INVALID_ARGUMENT, TIMEOUT, } from "../errors.js";
-import { cancelRemoteRun, clearRemoteRuns, clearRemoteState, deleteRemoteConfig, deleteRemoteStateKey, executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteConfig, fetchRemoteInfo, fetchRemotePlaybookShow, fetchRemotePlaybooks, fetchRemoteRun, fetchRemoteRuns, fetchRemoteStateList, getRemoteStateKey, setRemoteConfig, setRemoteStateKey, } from "../profile/client.js";
+import { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, clearRemoteState, deleteRemoteConfig, deleteRemoteStateKey, executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteConfig, fetchRemoteInfo, fetchRemotePlaybookShow, fetchRemotePlaybooks, fetchRemoteRun, fetchRemoteRuns, fetchRemoteStateList, getRemoteStateKey, setRemoteConfig, setRemoteStateKey, } from "../profile/client.js";
 import { isRemoteStateKeyNotFound, wrapRemoteError } from "./remote-errors.js";
 import { formatTerminalRunResult, pollRunCompletion } from "./remote-polling.js";
 import { streamRemoteEvents } from "./sse-stream.js";
@@ -306,6 +306,21 @@ export class RemoteActionDockService {
                     wrapRemoteError(err);
                 }
             },
+            async cleanExpired(policy) {
+                self.assertNotClosed();
+                try {
+                    const res = await cleanExpiredRemoteRuns(self.serverUrl, self.token, {
+                        ...policy,
+                        allowInsecureHttp: self.allowInsecureHttp,
+                        insecure: self.insecure,
+                        dispatcher: self.dispatcher,
+                    });
+                    return res.cleanedCount ?? 0;
+                }
+                catch (err) {
+                    wrapRemoteError(err);
+                }
+            },
         };
         this.events = {
             events(runId, opts) {

package/dist/service/types.d.ts

@@ -170,7 +170,11 @@ export interface RunsPort {
         packageId?: string;
         actionId?: string;
         status?: string;
+        olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    /** 按保留策略清理过期及超额的终态运行记录（基于时间与数量策略） */
+    cleanExpired?(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
 }
 /**
  * 配置项管理服务端口。

package/dist/storage/index.d.ts

@@ -42,6 +42,7 @@ export declare function createStorage(packageId: string, options?: {
     inMemory?: boolean;
     customHome?: string;
     recoverOrphans?: boolean;
+    retentionPolicy?: import("./types.js").RunsRetentionPolicy;
 }): RuntimeStorage;
 /**
  * 解析全局共享数据库（global.db）文件的绝对路径。

package/dist/storage/index.js

@@ -59,7 +59,12 @@ export function resolveDatabasePath(packageId, options = {}) {
  */
 export function createStorage(packageId, options = {}) {
     const dbPath = resolveDatabasePath(packageId, options);
-    return new SqliteRuntimeStorage({ dbPath, packageId, recoverOrphans: options.recoverOrphans });
+    return new SqliteRuntimeStorage({
+        dbPath,
+        packageId,
+        recoverOrphans: options.recoverOrphans,
+        retentionPolicy: options.retentionPolicy,
+    });
 }
 /**
  * 解析全局共享数据库（global.db）文件的绝对路径。

package/dist/storage/sqlite.d.ts

@@ -1,5 +1,5 @@
 import { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, type RuntimeError, type RunRecord } from "@actiondock/sdk";
-import { type IdempotencyCheckResult, type IdempotencyRecord, type RuntimeStorage, type StateEntry, type StorageOptions, type TerminalRunStatus } from "./types.js";
+import { type IdempotencyCheckResult, type IdempotencyRecord, type RunsRetentionPolicy, type RuntimeStorage, type StateEntry, type StorageOptions, type TerminalRunStatus } from "./types.js";
 export { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, };
 /**
  * 统一 SQLite 运行时存储实现。
@@ -25,6 +25,11 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
     private statementCache;
     private dbPath;
     private recoverOrphans;
+    private retentionPolicy?;
+    private lastRunsCleanupAt;
+    private runInsertCount;
+    private static readonly RUNS_CLEANUP_INTERVAL_MS;
+    private static readonly RUNS_CLEANUP_BATCH_THRESHOLD;
     get isOpen(): boolean;
     get closed(): boolean;
     constructor(options: StorageOptions);
@@ -84,7 +89,19 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
     clearRuns(options?: {
         actionId?: string;
         status?: string;
+        olderThanMs?: number;
+        keep?: number;
     }): number;
+    /**
+     * 按保留策略清理过期的终态运行记录与超出容量限制的最旧运行记录。
+     *
+     * 包含：
+     * - 基于时间：删除早于 maxAgeMs 的终态记录（保留 minRetainRuns 保底数量）。
+     * - 基于数量：若终态记录总数超过 maxRuns，按时间由旧至新淘汰超出部分。
+     * - 级联清理孤立的幂等去重记录。
+     */
+    cleanExpiredRuns(policy?: RunsRetentionPolicy): number;
+    private resolveRetentionPolicy;
     checkAndRecordIdempotency(record: IdempotencyRecord): IdempotencyCheckResult;
     getIdempotencyRecord(ownerId: string, actionRef: string, requestId: string): IdempotencyRecord | undefined;
     private mapRunRecord;