@actiondock/core 2.19.0 → 2.21.0

package/dist/server/routes/runs.js

@@ -3,7 +3,66 @@ 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";
+import { parseActionRef } from "../../catalog/resolve-action.js";
+import { getSubPath, isActionAllowedByPolicy, isFullAccessGranted, isPackageAllowedByPolicy, isPackageVisibleByPolicy, jsonResponse } from "./common.js";
+/** 清理范围必须落在整包或精确动作授权内，全局清理必须显式拥有全部授权。 */
+function resolveRunCleanupScope(packageId, actionId, policy) {
+    if (isFullAccessGranted(policy)) {
+        if (packageId && !isPackageVisibleByPolicy(packageId, policy)) {
+            return {
+                ok: false,
+                reason: `Package '${packageId}' is not in the allowed package list`,
+            };
+        }
+        return { ok: true, filter: { packageId, actionId } };
+    }
+    // 单动作清理必须解析出完整身份，避免鉴权与实际清理范围不一致。
+    if (actionId) {
+        let parsed;
+        try {
+            parsed = parseActionRef(actionId);
+        }
+        catch {
+            return { ok: false, reason: `Invalid action reference '${actionId}'` };
+        }
+        // 全限定引用与显式 packageId 归一化后不一致必须拒绝，防止鉴权与过滤范围错位
+        if (parsed.packageId && packageId && parsed.packageId !== packageId) {
+            return {
+                ok: false,
+                reason: `Action reference '${parsed.packageId}/${parsed.actionId}' does not match the requested package scope '${packageId}'`,
+            };
+        }
+        const targetPkgId = parsed.packageId || packageId;
+        if (!targetPkgId) {
+            return {
+                ok: false,
+                reason: "Restricted access policy requires a fully qualified 'packageId/actionId' action reference for run cleanup",
+            };
+        }
+        if (!isActionAllowedByPolicy({ packageId: targetPkgId, actionId: parsed.actionId }, policy)) {
+            return {
+                ok: false,
+                reason: `Action '${targetPkgId}/${parsed.actionId}' is not in the allowed action list`,
+            };
+        }
+        // 以归一化完整引用传递，确保底层过滤范围与鉴权引用一致且不扩大
+        return { ok: true, filter: { packageId: targetPkgId, actionId: parsed.actionId } };
+    }
+    // 无 actionId：必须有明确包范围，且该范围必须是整包授权
+    if (!packageId) {
+        return {
+            ok: false,
+            reason: "Restricted access policy requires an explicit 'packageId' or fully qualified 'actionId' scope for run cleanup",
+        };
+    }
+    if (!isPackageAllowedByPolicy(packageId, policy)) {
+        return {
+            ok: false,
+            reason: `Package '${packageId}' is not fully granted; run cleanup requires a fully granted package or an explicitly granted 'packageId/actionId' reference`,
+        };
+    }
+    return { ok: true, filter: { packageId } };
+}
 /**
  * 处理历史运行记录查询、清理、详情及 SSE 流式日志接口。
  */
@@ -54,7 +113,7 @@ export async function handleRunsRoutes(ctx) {
                     limit = Math.min(Math.max(parsedLimit, 1), 500);
                 }
             }
-            if (packageId && !isPackageAllowedByPolicy(packageId, policy)) {
+            if (packageId && !isPackageVisibleByPolicy(packageId, policy)) {
                 return jsonResponse({
                     ok: false,
                     error: {
@@ -63,7 +122,7 @@ export async function handleRunsRoutes(ctx) {
                     },
                 }, 403, corsHeaders);
             }
-            if (actionId && !isActionAllowedByPolicy({ packageId, actionId }, policy)) {
+            if (actionId && (packageId || actionId.includes("/")) && !isActionAllowedByPolicy({ packageId, actionId }, policy)) {
                 return jsonResponse({
                     ok: false,
                     error: {
@@ -72,6 +131,15 @@ export async function handleRunsRoutes(ctx) {
                     },
                 }, 403, corsHeaders);
             }
+            // 下推的是包可见性并集，仍须逐条校验动作，不能丢弃单动作授权包的记录。
+            const visiblePackageIds = new Set([
+                ...(policy.packageAllowlist || []).filter((id) => id !== "*"),
+                ...(policy.actionAllowlist || []).map((ref) => parseActionRef(ref).packageId),
+            ]);
+            const backendPackageFilter = isFullAccessGranted(policy) ? undefined : [...visiblePackageIds];
+            if (backendPackageFilter?.length === 0) {
+                return jsonResponse({ ok: true, items: [], total: 0, limit, offset }, 200, corsHeaders);
+            }
             const queryOptions = {
                 actionId,
                 status,
@@ -86,12 +154,9 @@ export async function handleRunsRoutes(ctx) {
                 intent,
                 requestIds: requestIds.length > 0 ? requestIds : undefined,
                 signal: req.signal,
-                packageAllowlist: policy.packageAllowlist && policy.packageAllowlist.length > 0
-                    ? policy.packageAllowlist
-                    : undefined,
+                packageAllowlist: backendPackageFilter,
             };
-            const hasPolicyFilter = Boolean((policy.packageAllowlist && policy.packageAllowlist.length > 0) ||
-                (policy.actionAllowlist && policy.actionAllowlist.length > 0));
+            const hasPolicyFilter = !isFullAccessGranted(policy);
             let runs;
             let total;
             if (hasPolicyFilter) {
@@ -116,7 +181,9 @@ export async function handleRunsRoutes(ctx) {
                         break;
                     }
                     for (const run of batch) {
-                        const packageAllowed = isPackageAllowedByPolicy(run.packageId, policy);
+                        // 逐条以实际 packageId/actionId 完整引用判定授权：
+                        // 包可见性拦无关包，动作授权保留单动作授权目标（如 B/read）
+                        const packageAllowed = isPackageVisibleByPolicy(run.packageId, policy);
                         const actionAllowed = isActionAllowedByPolicy({ packageId: run.packageId, actionId: run.actionId }, policy);
                         if (packageAllowed && actionAllowed) {
                             if (matchedCount >= offset && pagedRuns.length < limit) {
@@ -218,20 +285,22 @@ export async function handleRunsRoutes(ctx) {
                     keep = parsed;
                 }
             }
-            if (packageId && !isPackageAllowedByPolicy(packageId, policy)) {
+            const scopeCheck = resolveRunCleanupScope(packageId, actionId, policy);
+            if (!scopeCheck.ok) {
                 return jsonResponse({
                     ok: false,
                     error: {
                         code: PACKAGE_FORBIDDEN,
-                        message: `Package '${packageId}' is not in the allowed package list`,
+                        message: scopeCheck.reason,
                     },
                 }, 403, corsHeaders);
             }
+            const clearedScope = scopeCheck.filter;
             let clearedCount = 0;
             if (service.runs.clear) {
                 clearedCount = await service.runs.clear({
-                    packageId,
-                    actionId,
+                    packageId: clearedScope.packageId,
+                    actionId: clearedScope.actionId,
                     status,
                     olderThanMs,
                     keep,
@@ -244,7 +313,17 @@ export async function handleRunsRoutes(ctx) {
         }
     }
     // 2.1 Runs Clean Expired: POST /api/v2/runs/clean-expired, POST /runs/clean-expired
+    // 此操作无法按包或动作收窄范围，只允许显式的全部授权。
     if (subpath === "/runs/clean-expired" && req.method === "POST") {
+        if (!isFullAccessGranted(policy)) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: PACKAGE_FORBIDDEN,
+                    message: "Expired run cleanup cannot be scoped under a restricted access policy",
+                },
+            }, 403, corsHeaders);
+        }
         try {
             let body = {};
             if (req.headers.get("content-type")?.includes("json")) {
@@ -268,7 +347,7 @@ export async function handleRunsRoutes(ctx) {
         if (!run) {
             return jsonResponse({ ok: false, error: { code: RUN_NOT_FOUND, message: `Run '${runId}' not found` } }, 404, corsHeaders);
         }
-        if (!isPackageAllowedByPolicy(run.packageId, policy)) {
+        if (!isPackageVisibleByPolicy(run.packageId, policy)) {
             return jsonResponse({
                 ok: false,
                 error: {
@@ -443,7 +522,7 @@ export async function handleRunsRoutes(ctx) {
                 },
             }, 404, corsHeaders);
         }
-        if (!isPackageAllowedByPolicy(run.packageId, policy)) {
+        if (!isPackageVisibleByPolicy(run.packageId, policy)) {
             return jsonResponse({
                 ok: false,
                 error: {
@@ -467,11 +546,10 @@ export async function handleRunsRoutes(ctx) {
     const runCancelMatch = subpath.match(/^\/runs\/([^/]+)\/cancel$/);
     if (runCancelMatch && req.method === "POST") {
         const runId = decodeURIComponent(runCancelMatch[1]);
-        if ((policy.packageAllowlist && policy.packageAllowlist.length > 0) ||
-            (policy.actionAllowlist && policy.actionAllowlist.length > 0)) {
+        if (!isFullAccessGranted(policy)) {
             const run = await service.runs.get(runId);
             if (run) {
-                if (!isPackageAllowedByPolicy(run.packageId, policy)) {
+                if (!isPackageVisibleByPolicy(run.packageId, policy)) {
                     return jsonResponse({
                         ok: false,
                         error: {

package/dist/server/server.js

@@ -3,8 +3,8 @@ import { NodeHttpServer } from "./http-server.js";
 import { createActionDock } from "../service/factory.js";
 import { ActionDockError, ACCESS_DENIED, NOT_FOUND, SERVICE_ERROR, UNAUTHORIZED } from "../errors.js";
 import { parseActionRef } from "../catalog/resolve-action.js";
-import { findProjectRoot } from "../project/loader.js";
-import { listLinkedPackages, resolvePackageRoot } from "../registry/registry.js";
+import { findProjectRoot, loadProjectConfig } from "../project/loader.js";
+import { 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";
@@ -70,70 +70,42 @@ export async function startActionDockServer(arg1, arg2) {
         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 实体
+    // 包授权与单动作引用都参与自建服务的装载；外部注入服务自行负责能力装配。
     if (!serviceInstance) {
-        const scanLinkedPackages = options.scanLinkedPackages ?? !projectRoot;
+        const declaredId = projectRoot ? loadProjectConfig(projectRoot).id : undefined;
+        const referencedPackages = new Set();
+        for (const view of views.values()) {
+            for (const pkgId of view.policy.packageAllowlist || []) {
+                if (pkgId !== "*")
+                    referencedPackages.add(pkgId);
+            }
+            for (const action of view.policy.actionAllowlist || []) {
+                referencedPackages.add(parseActionRef(action).packageId);
+            }
+        }
+        const extraPackages = [];
+        for (const pkgId of referencedPackages) {
+            if (pkgId === declaredId)
+                continue;
+            const root = resolvePackageRoot(pkgId, projectRoot || undefined, customHome);
+            if (root && !extraPackages.some((pkg) => pkg.packageRoot === root)) {
+                extraPackages.push({ packageRoot: root });
+            }
+        }
         serviceInstance = await createActionDock({
             projectRoot: projectRoot || undefined,
+            packages: extraPackages.length > 0 ? extraPackages : undefined,
             customHome,
             platform: options.platform,
             dataDir: options.dataDir,
             inMemory: options.inMemory,
-            scanLinkedPackages,
+            scanLinkedPackages: options.scanLinkedPackages ?? !projectRoot,
             enableManagement: options.enableManagement,
         });
     }
     if (!serviceInstance) {
         throw new ActionDockError(SERVICE_ERROR, "Failed to initialize ActionDockService for server");
     }
-    // 2. 聚合所有 views 声明的依赖包与动作，确保依赖闭包满足
-    const roots = [];
-    if (projectRoot) {
-        roots.push(projectRoot);
-    }
-    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);
-            }
-        }
-    }
-    else if (!projectRoot) {
-        for (const pkg of listLinkedPackages(customHome)) {
-            if (!roots.includes(pkg.path)) {
-                roots.push(pkg.path);
-            }
-        }
-    }
-    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 { }
-        }
-    }
     // 3. 为每个启用 MCP 的视图独立装配 MCP 处理器
     if (options.enableMcp !== false) {
         for (const v of views.values()) {

package/dist/server/types.d.ts

@@ -26,9 +26,9 @@ export interface ServerViewOptions {
     name?: string;
     /** 该视图独立的 Bearer Token 鉴权令牌 */
     token?: string;
-    /** 该视图允许访问执行的 Package ID 白名单列表（为空允许全部） */
+    /** 整包授权列表，与动作授权取并集；空列表不授予权限，独立 * 显式授权全部 */
     packageAllowlist?: string[];
-    /** 该视图允许访问执行的 Action 标识白名单列表（为空允许全部，支持短名或 packageId/actionId） */
+    /** 全限定 packageId/actionId 精确动作授权列表；空列表不授予权限 */
     actionAllowlist?: string[];
     /** 该视图是否开启配置与状态管理路由能力（默认关闭） */
     enableManagement?: boolean;
@@ -45,9 +45,9 @@ export interface EffectiveServerPolicy {
     viewName?: string;
     /** 当前生效的 Bearer Token 鉴权令牌 */
     token?: string;
-    /** 当前生效的 Package ID 白名单列表 */
+    /** 当前生效的整包授权列表，独立 * 代表全部 */
     packageAllowlist?: string[];
-    /** 当前生效的 Action 标识白名单列表 */
+    /** 当前生效的全限定精确动作授权列表，与整包授权取并集 */
     actionAllowlist?: string[];
     /** 当前生效的管理能力开关 */
     enableManagement?: boolean;
@@ -80,9 +80,9 @@ export interface ServerOptions {
     allowInsecureNoAuth?: boolean;
     /** 允许跨域请求的 CORS Origin 白名单列表 */
     corsOrigins?: string[];
-    /** 允许访问执行的 Package ID 白名单列表（为空允许全部） */
+    /** 整包授权列表，与动作授权取并集；空列表不授予权限，独立 * 显式授权全部 */
     packageAllowlist?: string[];
-    /** 允许访问执行的 Action 标识白名单列表（为空允许全部，支持短名或 packageId/actionId） */
+    /** 全限定 packageId/actionId 精确动作授权列表；空列表不授予权限 */
     actionAllowlist?: string[];
     /** 最大允许的请求体字节限制（默认 1MB，防 DoS） */
     maxBodyBytes?: number;

package/dist/service/factory.js

@@ -10,6 +10,7 @@ export async function createActionDock(options = {}) {
         const inMemory = options.inMemory ?? options.runtimeOptions.inMemory;
         const host = await createActionDockHost({
             packages: [options.runtimeOptions],
+            actionBindings: options.actionBindings ?? options.hostOptions?.actionBindings,
             autoLoadCurrentProject: false,
             scanLinkedPackages: false,
             inMemory,
@@ -21,6 +22,8 @@ export async function createActionDock(options = {}) {
             logger: options.runtimeOptions.logger,
             recoverOrphans: options.recoverOrphans,
             enableManagement: options.enableManagement,
+            allowInstall: options.allowInstall,
+            prepareLocalPackage: options.hostOptions?.prepareLocalPackage ?? options.prepareLocalPackage,
         });
         return host;
     }
@@ -29,6 +32,7 @@ export async function createActionDock(options = {}) {
         ...options,
         recoverOrphans: options.recoverOrphans ?? true,
         enableManagement: options.enableManagement,
+        allowInstall: options.allowInstall,
         ...(options.hostOptions || {}),
     });
     return host;

package/dist/service/remote.js

@@ -1,7 +1,8 @@
 import { parseActionRef } from "../catalog/resolve-action.js";
+import { assertConcreteConfigKey } from "../project/config-declarations.js";
 import { ActionDockError, ACTION_CANCELLED, CAPABILITY_UNAVAILABLE, INVALID_ARGUMENT, TIMEOUT, } from "../errors.js";
 import { createAbortError } from "../ipc/service.js";
-import { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, clearRemoteState, deleteRemoteConfig, deleteRemoteStateKey, executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteConfig, fetchRemoteInfo, fetchRemotePlaybookShow, fetchRemotePlaybooks, fetchRemoteRun, fetchRemoteRuns, fetchRemoteStateList, getRemoteStateKey, setRemoteConfig, setRemoteStateKey, } from "../client/index.js";
+import { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, clearRemoteState, deleteRemoteConfig, deleteRemoteStateKey, executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteConfig, fetchRemoteConfigItem, fetchRemoteInfo, fetchRemotePlaybookShow, fetchRemotePlaybooks, fetchRemoteRun, fetchRemoteRuns, fetchRemoteStateList, getRemoteStateKey, setRemoteConfig, setRemoteStateKey, } from "../client/index.js";
 import { isRemoteStateKeyNotFound, wrapRemoteError } from "./remote-errors.js";
 import { formatTerminalRunResult, pollRunCompletion } from "./remote-polling.js";
 import { streamRemoteEvents } from "./sse-stream.js";
@@ -449,19 +450,15 @@ export class RemoteActionDockService {
                 config: {
                     async get(packageId, key) {
                         self.assertNotClosed();
+                        assertConcreteConfigKey(key);
                         try {
-                            const list = await self.management.config.list(packageId);
-                            const found = list.find((c) => c.key === key);
-                            if (found) {
-                                return found;
-                            }
-                            return {
-                                key,
-                                configured: false,
-                                secret: false,
-                                source: "default",
-                                value: undefined,
-                            };
+                            const response = await fetchRemoteConfigItem(self.serverUrl, key, self.token, packageId || undefined, {
+                                allowInsecureHttp: self.allowInsecureHttp,
+                                insecure: self.insecure,
+                                dispatcher: self.dispatcher,
+                            });
+                            // 严格单项读取已保证恰一项且键匹配，直接消费，不伪造未命中视图掩盖契约错误。
+                            return response.items[0];
                         }
                         catch (err) {
                             wrapRemoteError(err);
@@ -469,6 +466,7 @@ export class RemoteActionDockService {
                     },
                     async set(packageId, key, value) {
                         self.assertNotClosed();
+                        assertConcreteConfigKey(key);
                         try {
                             await setRemoteConfig(self.serverUrl, key, value, self.token, packageId || undefined, {
                                 allowInsecureHttp: self.allowInsecureHttp,
@@ -482,6 +480,7 @@ export class RemoteActionDockService {
                     },
                     async delete(packageId, key) {
                         self.assertNotClosed();
+                        assertConcreteConfigKey(key);
                         try {
                             const res = await deleteRemoteConfig(self.serverUrl, key, self.token, packageId || undefined, {
                                 allowInsecureHttp: self.allowInsecureHttp,
@@ -502,22 +501,8 @@ export class RemoteActionDockService {
                                 insecure: self.insecure,
                                 dispatcher: self.dispatcher,
                             });
-                            if (Array.isArray(res))
-                                return res;
-                            if (Array.isArray(res?.items))
-                                return res.items;
-                            if (Array.isArray(res?.config))
-                                return res.config;
-                            const values = res?.values || {};
-                            const declared = res?.declared || {};
-                            const defaultSource = packageId === "global" ? "global" : "package";
-                            return Object.entries(values).map(([k, v]) => ({
-                                key: k,
-                                configured: v !== undefined,
-                                secret: Boolean(declared[k]?.secret),
-                                source: defaultSource,
-                                value: v,
-                            }));
+                            // 归一化边界已强校验完整视图，直接消费，不再叠加兜底。
+                            return res.items;
                         }
                         catch (err) {
                             wrapRemoteError(err);

package/dist/service/types.d.ts

@@ -2,8 +2,10 @@ import type { ActionRef, ExecutionEvent, ExecutionResult, JsonValue, RunOrigin,
 import type { ActionSpec, ActionSummary, ListActionsOptions, PackageInfo, PackageRuntime, PackageRuntimeOptions, PlaybookSpec, PlaybookSummary } from "../package/types.js";
 import type { CancelResult, ExecutionTicket } from "../execution/types.js";
 import type { ActionDockHostOptions } from "../host/types.js";
+import type { LocalPackagePreparer } from "../invocation/types.js";
 import type { RuntimePlatform } from "../platform/types.js";
 import type { StateEntry } from "../storage/types.js";
+import type { ActionBindings } from "../invocation/bindings.js";
 import { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED } from "../errors.js";
 /**
  * 公开运行控制选项（RunOptions）。
@@ -29,6 +31,16 @@ export declare const ACTIONDOCK_PROTOCOL_VERSION = "2.0";
  * 服务端/通信协议错误码常量（单一事实源引用自 errors.ts）。
  */
 export { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED };
+/**
+ * 配置来源契约（单一事实源）。
+ * 仅表达当前生效配置值的实际来源，不混入传输方式或作用域显示别名：
+ * override 为运行时固定覆盖或单次调用覆盖，package 为包级持久化，global 为全局持久化，
+ * env 为环境变量命中，default 为清单声明且真实生效的默认值。
+ * 无任何生效值时为 null，不得用 default 伪装。
+ */
+export declare const CONFIG_SOURCES: readonly ["override", "package", "global", "env", "default"];
+/** 配置来源类型；由来源元组派生，枚举值单一事实源。 */
+export type ConfigSource = (typeof CONFIG_SOURCES)[number];
 /**
  * 配置项安全视图契约。
  * 屏蔽敏感配置原文，仅暴露是否已配置、是否为秘密及实际解析来源。
@@ -36,14 +48,16 @@ export { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED };
 export interface ConfigValueView {
     /** 配置项键名 */
     key: string;
-    /** 是否已显式配置或存在有效值 */
+    /** 是否来自显式来源（override/package/global/env）；default 与未配置（source null）均为 false */
     configured: boolean;
-    /** 是否为秘密敏感配置 */
+    /** 声明含敏感字段或实际发生保守隐藏；不代表整个值不可见 */
     secret: boolean;
-    /** 配置值实际解析来源 */
-    source: string;
-    /** 非秘密配置的实际数据值 */
+    /** 配置值实际解析来源；无任何生效值时为 null */
+    source: ConfigSource | null;
+    /** 管理侧安全值；顶层敏感时不提供原值 */
     value?: JsonValue;
+    /** 标准 JSON Pointer 隐藏路径；根为 ""，未发生隐藏时为空 */
+    redactedPaths: string[];
 }
 /**
  * 状态作用域与筛选控制选项。
@@ -254,6 +268,8 @@ export interface ActionDockService {
  * 创建 ActionDock 本地服务选项。
  */
 export interface CreateActionDockOptions {
+    /** 按调用方包覆盖运行时命名绑定，不改变动作引用与 uses 声明。 */
+    actionBindings?: Readonly<Record<string, ActionBindings>>;
     /** 模式类型（可选） */
     type?: "local";
     /** 单包 PackageRuntime 初始化配置 */
@@ -280,6 +296,13 @@ export interface CreateActionDockOptions {
     recoverOrphans?: boolean;
     /** 是否开启管理端口（默认 true） */
     enableManagement?: boolean;
+    /**
+     * 是否允许执行依赖自动安装（主要控制启动与事务恢复中的依赖安装；
+     * 本地包运行期准备由 prepareLocalPackage 注入器根据自身配置决定）。
+     */
+    allowInstall?: boolean;
+    /** 本地包准备协调器回调 */
+    prepareLocalPackage?: LocalPackagePreparer;
 }
 /**
  * 连接 ActionDock 远程服务选项。

package/dist/service/types.js

@@ -7,3 +7,11 @@ export const ACTIONDOCK_PROTOCOL_VERSION = "2.0";
  * 服务端/通信协议错误码常量（单一事实源引用自 errors.ts）。
  */
 export { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED };
+/**
+ * 配置来源契约（单一事实源）。
+ * 仅表达当前生效配置值的实际来源，不混入传输方式或作用域显示别名：
+ * override 为运行时固定覆盖或单次调用覆盖，package 为包级持久化，global 为全局持久化，
+ * env 为环境变量命中，default 为清单声明且真实生效的默认值。
+ * 无任何生效值时为 null，不得用 default 伪装。
+ */
+export const CONFIG_SOURCES = ["override", "package", "global", "env", "default"];

package/dist/storage/config-value.d.ts

@@ -0,0 +1,33 @@
+import type { ConfigItemDefinition } from "../project/types.js";
+import { type ConfigEncryptionKey } from "../security/config-cipher.js";
+/**
+ * 密文行内部负载信封：业务值与历史保护声明一同加密。
+ *
+ * 历史保护声明仅保留脱敏所需的结构/类型/secret 信息，供当前声明
+ * 弱化后的管理视图脱敏兜底；业务值透明解密后原样返回。
+ *
+ * 本模块是密文信封编码与保护声明清洗的单一事实源：正常写入路径
+ * （SqliteConfigStore）与版本迁移路径（migrations/v2-to-v3）共用，
+ * 禁止任何一侧复制 envelope 或保护清洗逻辑。
+ */
+export interface ConfigValueEnvelope {
+    value: unknown;
+    protection: ConfigItemDefinition[];
+}
+/**
+ * 合并历史保护声明与当前敏感声明，绝不弱化保护强度。
+ *
+ * - 以规范化 JSON 作为去重标识，防止重复写入导致保护数组无界增长；
+ * - 当前声明中仅并入判定敏感的条目（非敏感声明不产生历史保护义务）；
+ * - 合并结果为空时保守回退为整项敏感，保证密文行始终有脱敏依据。
+ */
+export declare function mergeProtectionDeclarations(stored: readonly ConfigItemDefinition[] | undefined, current: readonly ConfigItemDefinition[], key: string): ConfigItemDefinition[];
+/** 加密业务值与保护声明构成的完整信封，返回规范密文信封字符串。 */
+export declare function encryptConfigEnvelope(value: unknown, protection: readonly ConfigItemDefinition[], scope: string, key: string, material: ConfigEncryptionKey): string;
+/**
+ * 严格解密密文信封并校验负载形态。
+ *
+ * 信封负载必须为含 value 属性的对象；protection 省略或为声明对象数组。
+ * 任何不合规输入抛 CONFIG_DECRYPT_FAILED，绝不把密文降级当作明文返回。
+ */
+export declare function decryptConfigEnvelope(ciphertext: string, scope: string, key: string, material: ConfigEncryptionKey): ConfigValueEnvelope;