@actiondock/core 2.19.0 → 2.21.0

package/dist/client/config.d.ts

@@ -1,20 +1,23 @@
+import type { ConfigItemDefinition } from "../project/types.js";
 import type { RemoteClientRequestOptions } from "./transport.js";
+export interface FetchRemoteConfigOptions extends RemoteClientRequestOptions {
+    /** 本地声明只可加强远端保护，不能撤销服务端标记。 */
+    localDeclarations?: Record<string, ConfigItemDefinition>;
+    /** 提供当前目录声明时，仅在响应包标识匹配后启用。 */
+    localPackageId?: string;
+}
 /**
- * 远端配置域端点。
- */
-/**
- * 拉取远端配置视图（可定向指定包）。
- */
-export declare function fetchRemoteConfig(serverUrl: string, token?: string, packageId?: string, options?: RemoteClientRequestOptions): Promise<any>;
-/**
- * 写入单个远端配置键值。
+ * 在核心边界归一化配置安全视图；仅接受 configViewVersion:1 新协议。
+ * 旧协议无法证明来源与元数据真实性，统一抛出协议不支持错误，不猜测来源。
  */
+export declare function normalizeRemoteConfigResponse(rawResponse: any, options?: Pick<FetchRemoteConfigOptions, "localDeclarations" | "localPackageId"> & {
+    packageId?: string;
+}): any;
+/** 拉取远端配置；返回值与元数据均已完成安全归一化。 */
+export declare function fetchRemoteConfig(serverUrl: string, token?: string, packageId?: string, options?: FetchRemoteConfigOptions): Promise<any>;
+/** 单键查询可解析仅由环境变量提供的模板实例；服务端必须返回同键完整单项视图。 */
+export declare function fetchRemoteConfigItem(serverUrl: string, key: string, token?: string, packageId?: string, options?: FetchRemoteConfigOptions): Promise<any>;
+/** 写入仍为整键替换；服务端在持久化之前校验。 */
 export declare function setRemoteConfig(serverUrl: string, key: string, value: unknown, token?: string, packageId?: string, options?: RemoteClientRequestOptions): Promise<any>;
-/**
- * 删除单个远端配置键。
- */
 export declare function deleteRemoteConfig(serverUrl: string, key: string, token?: string, packageId?: string, options?: RemoteClientRequestOptions): Promise<any>;
-/**
- * 拉取远端配置环境变量检查结果（可定向指定包）。
- */
 export declare function fetchRemoteConfigEnv(serverUrl: string, token?: string, packageId?: string, options?: RemoteClientRequestOptions): Promise<any>;

package/dist/client/config.js

@@ -1,22 +1,125 @@
+import { CONFIG_SOURCES } from "../service/types.js";
+import { ActionDockError, PROTOCOL_UNSUPPORTED } from "../errors.js";
+import { assertConcreteConfigKey, assertValidConfigDeclarations, resolveConfigDeclaration, } from "../project/config-declarations.js";
+import { redactConfigValueAtPaths, redactConfigValueForDeclarations, sanitizeConfigDefinitions, } from "../storage/mask.js";
 import { buildQueryString, fetchRemoteJson } from "./transport.js";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** 判定远端响应中的 source 是否为合法 ConfigSource（含 null）；合法值单一事实源为 CONFIG_SOURCES 元组。 */
+function isValidConfigSource(source) {
+    return source === null || (typeof source === "string" && CONFIG_SOURCES.includes(source));
+}
+/** 在核心边界校验配置安全视图契约：来源合法、状态与值自洽，不满足即拒绝；诊断不携带配置原文。 */
+function assertValidConfigValueView(item) {
+    if (!isRecord(item) || typeof item.key !== "string" || typeof item.configured !== "boolean" || typeof item.secret !== "boolean" ||
+        !isValidConfigSource(item.source) || !Array.isArray(item.redactedPaths) ||
+        item.redactedPaths.some((path) => typeof path !== "string")) {
+        throw new ActionDockError(PROTOCOL_UNSUPPORTED, "Remote configuration view violates the config view protocol: source must be one of override/package/global/env/default/null and metadata must be complete");
+    }
+    // source null 仅代表未命中：不得携带生效值或隐藏路径，也不得宣称已配置。
+    if (item.source === null) {
+        if (item.configured !== false || item.value !== undefined || item.redactedPaths.length > 0) {
+            throw new ActionDockError(PROTOCOL_UNSUPPORTED, `Remote configuration view for '${item.key}' declares no effective source but carries configured state, a value, or redaction paths`);
+        }
+        return;
+    }
+    // default 与未命中同样不是显式配置；显式来源必须宣称已配置。
+    if (item.source === "default") {
+        if (item.configured !== false) {
+            throw new ActionDockError(PROTOCOL_UNSUPPORTED, `Remote configuration view for '${item.key}' declares a default source but claims configured state`);
+        }
+    }
+    else if (item.configured !== true) {
+        throw new ActionDockError(PROTOCOL_UNSUPPORTED, `Remote configuration view for '${item.key}' declares an explicit source but claims unconfigured state`);
+    }
+    // 声明有来源就必须有实际生效值；整项隐藏可省略 value 但必须携带根隐藏路径。
+    if (item.value === undefined && !item.redactedPaths.includes("")) {
+        throw new ActionDockError(PROTOCOL_UNSUPPORTED, `Remote configuration view for '${item.key}' declares an effective source but omits both the value and the root redaction path`);
+    }
+}
 /**
- * 远端配置域端点。
- */
-/**
- * 拉取远端配置视图（可定向指定包）。
+ * 在核心边界归一化配置安全视图；仅接受 configViewVersion:1 新协议。
+ * 旧协议无法证明来源与元数据真实性，统一抛出协议不支持错误，不猜测来源。
  */
+export function normalizeRemoteConfigResponse(rawResponse, options) {
+    if (!rawResponse || typeof rawResponse !== "object") {
+        throw new ActionDockError(PROTOCOL_UNSUPPORTED, "Remote configuration response violates the config view protocol: response must be an object");
+    }
+    // 新协议门槛提前到一切声明解析之前：缺失 configViewVersion:1 视为旧服务端，
+    // 直接拒绝，避免旧协议因其他字段错误先报清单/参数错误。
+    if (rawResponse.configViewVersion !== 1) {
+        throw new ActionDockError(PROTOCOL_UNSUPPORTED, "Remote server did not declare configViewVersion: 1; legacy configuration responses without safe view metadata are no longer supported");
+    }
+    if (!Array.isArray(rawResponse.items)) {
+        throw new ActionDockError(PROTOCOL_UNSUPPORTED, "Remote configuration response is missing safe views");
+    }
+    const remoteDeclared = isRecord(rawResponse.declared) ? rawResponse.declared : {};
+    const matchesLocalPackage = !options?.localPackageId ||
+        rawResponse.packageId === options.localPackageId || options.packageId === options.localPackageId;
+    const localDeclared = matchesLocalPackage ? options?.localDeclarations ?? {} : {};
+    assertValidConfigDeclarations(remoteDeclared);
+    assertValidConfigDeclarations(localDeclared);
+    const declarationsFor = (key) => [
+        resolveConfigDeclaration(remoteDeclared, key)?.item,
+        resolveConfigDeclaration(localDeclared, key)?.item,
+    ].filter((item) => item !== undefined);
+    const items = rawResponse.items.map((item) => {
+        assertValidConfigValueView(item);
+        assertConcreteConfigKey(item.key);
+        // 路径只是保护策略，不是原值已经被替换的证据；先实际应用服务端路径。
+        const remoteSafe = redactConfigValueAtPaths(item.value, item.redactedPaths);
+        const declaredSafe = redactConfigValueForDeclarations(remoteSafe.value, declarationsFor(item.key));
+        const safe = redactConfigValueAtPaths(declaredSafe.value, [
+            ...remoteSafe.redactedPaths, ...declaredSafe.redactedPaths,
+        ]);
+        return {
+            key: item.key,
+            configured: item.configured,
+            secret: item.secret || remoteSafe.secret || declaredSafe.secret,
+            source: item.source,
+            value: safe.value,
+            redactedPaths: safe.redactedPaths,
+        };
+    });
+    // 只返回已知安全字段，避免 spread 原响应把原始别名重新带出边界。
+    return {
+        ok: rawResponse.ok ?? true,
+        configViewVersion: 1,
+        packageId: rawResponse.packageId ?? options?.packageId,
+        declared: sanitizeConfigDefinitions({ ...localDeclared, ...remoteDeclared }) ?? {},
+        items,
+        values: Object.fromEntries(items.map((item) => [item.key,
+            item.value === undefined && item.redactedPaths.includes("") ? "********" : item.value,
+        ])),
+        masked: Object.fromEntries(items.map((item) => [item.key, item.redactedPaths])),
+    };
+}
+/** 拉取远端配置；返回值与元数据均已完成安全归一化。 */
 export async function fetchRemoteConfig(serverUrl, token, packageId, options) {
-    return fetchRemoteJson(serverUrl, `/api/v2/config${buildQueryString({ package: packageId })}`, token, {
+    const raw = await fetchRemoteJson(serverUrl, `/api/v2/config${buildQueryString({ package: packageId })}`, token, {
         errorPrefix: "Failed to fetch remote config",
         allowInsecureHttp: options?.allowInsecureHttp,
         insecure: options?.insecure,
         dispatcher: options?.dispatcher,
     });
+    return normalizeRemoteConfigResponse(raw, { ...options, packageId });
 }
-/**
- * 写入单个远端配置键值。
- */
+/** 单键查询可解析仅由环境变量提供的模板实例；服务端必须返回同键完整单项视图。 */
+export async function fetchRemoteConfigItem(serverUrl, key, token, packageId, options) {
+    assertConcreteConfigKey(key);
+    const raw = await fetchRemoteJson(serverUrl, `/api/v2/config${buildQueryString({ package: packageId, key })}`, token, { ...options, errorPrefix: "Failed to fetch remote configuration item" });
+    // 严格单项契约：新协议必须提供与请求键一致的完整 item；
+    // 真正未命中由服务端返回同键 source null 视图，不接受列表或空 items 伪装单项。
+    if (!raw || typeof raw !== "object" || raw.configViewVersion !== 1 ||
+        !isRecord(raw.item) || raw.item.key !== key) {
+        throw new ActionDockError(PROTOCOL_UNSUPPORTED, `Remote server did not return a complete single-item config view for key '${key}'; servers that ignore the key query parameter are no longer supported`);
+    }
+    return normalizeRemoteConfigResponse({ ...raw, items: [raw.item] }, { ...options, packageId });
+}
+/** 写入仍为整键替换；服务端在持久化之前校验。 */
 export async function setRemoteConfig(serverUrl, key, value, token, packageId, options) {
+    assertConcreteConfigKey(key);
     return fetchRemoteJson(serverUrl, "/api/v2/config", token, {
         method: "PUT",
         body: { key, value, package: packageId },
@@ -26,10 +129,8 @@ export async function setRemoteConfig(serverUrl, key, value, token, packageId, o
         dispatcher: options?.dispatcher,
     });
 }
-/**
- * 删除单个远端配置键。
- */
 export async function deleteRemoteConfig(serverUrl, key, token, packageId, options) {
+    assertConcreteConfigKey(key);
     return fetchRemoteJson(serverUrl, `/api/v2/config/${encodeURIComponent(key)}${buildQueryString({ package: packageId })}`, token, {
         method: "DELETE",
         errorPrefix: `Failed to delete remote config '${key}'`,
@@ -38,9 +139,6 @@ export async function deleteRemoteConfig(serverUrl, key, token, packageId, optio
         dispatcher: options?.dispatcher,
     });
 }
-/**
- * 拉取远端配置环境变量检查结果（可定向指定包）。
- */
 export async function fetchRemoteConfigEnv(serverUrl, token, packageId, options) {
     return fetchRemoteJson(serverUrl, `/api/v2/config/env${buildQueryString({ package: packageId })}`, token, {
         errorPrefix: "Failed to fetch remote config env checks",

package/dist/client/index.d.ts

@@ -13,4 +13,4 @@ export type { RemoteExecuteOptions, RemoteExecutionResult } from "./actions.js";
 export { fetchRemotePlaybookShow, fetchRemotePlaybooks } from "./playbooks.js";
 export { cancelRemoteRun, cleanExpiredRemoteRuns, clearRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./runs.js";
 export { clearRemoteState, deleteRemoteStateKey, fetchRemoteStateList, getRemoteStateKey, setRemoteStateKey, } from "./state.js";
-export { deleteRemoteConfig, fetchRemoteConfig, fetchRemoteConfigEnv, setRemoteConfig, } from "./config.js";
+export { deleteRemoteConfig, fetchRemoteConfig, fetchRemoteConfigItem, fetchRemoteConfigEnv, setRemoteConfig, normalizeRemoteConfigResponse, type FetchRemoteConfigOptions, } from "./config.js";

package/dist/client/index.js

@@ -17,4 +17,4 @@ export { cancelRemoteRun, cleanExpiredRemoteRuns, clearRemoteRuns, fetchRemoteRu
 // 6. 状态存储管理域
 export { clearRemoteState, deleteRemoteStateKey, fetchRemoteStateList, getRemoteStateKey, setRemoteStateKey, } from "./state.js";
 // 7. 配置管理域
-export { deleteRemoteConfig, fetchRemoteConfig, fetchRemoteConfigEnv, setRemoteConfig, } from "./config.js";
+export { deleteRemoteConfig, fetchRemoteConfig, fetchRemoteConfigItem, fetchRemoteConfigEnv, setRemoteConfig, normalizeRemoteConfigResponse, } from "./config.js";

package/dist/errors.d.ts

@@ -71,6 +71,10 @@ export declare const CAPABILITY_UNAVAILABLE = "CAPABILITY_UNAVAILABLE";
 export declare const STATE_KEY_NOT_FOUND = "STATE_KEY_NOT_FOUND";
 /** SQLite 数据库忙或锁定 */
 export declare const STORAGE_BUSY = "STORAGE_BUSY";
+/** 所需生产依赖未就绪且当前环境不允许或不满足自动首装条件 */
+export declare const DEPENDENCIES_NOT_READY = "DEPENDENCIES_NOT_READY";
+/** 自动依赖安装进程启动失败、超时或非零退出 */
+export declare const DEPENDENCY_INSTALL_FAILED = "DEPENDENCY_INSTALL_FAILED";
 /** 工程事务锁被其他活跃进程持有 */
 export declare const PROJECT_BUSY = "PROJECT_BUSY";
 /** 工程存在未恢复的崩溃事务，需要执行恢复流程 */
@@ -298,6 +302,14 @@ export declare const EXECUTION_CONCURRENCY_LIMIT = "EXECUTION_CONCURRENCY_LIMIT"
 export declare const PROJECT_CONFIG_NOT_FOUND = "PROJECT_CONFIG_NOT_FOUND";
 /** 项目清单加载失败 */
 export declare const MANIFEST_LOAD_FAILED = "MANIFEST_LOAD_FAILED";
+/** 配置项数据值不符合声明的模式规范 */
+export declare const CONFIG_VALUE_INVALID = "CONFIG_VALUE_INVALID";
+/** 配置加密密钥缺失、无效或与存储域身份不符等加密配置错误 */
+export declare const CONFIG_ENCRYPTION_ERROR = "CONFIG_ENCRYPTION_ERROR";
+/** 配置密文解密失败（信封格式非法、版本未知、密钥身份不符或认证校验失败） */
+export declare const CONFIG_DECRYPT_FAILED = "CONFIG_DECRYPT_FAILED";
+/** 配置加密与解密错误按结构化错误码识别，跨模块副本也不得吞没或覆盖。 */
+export declare function isConfigEncryptionError(error: unknown): boolean;
 /** 动作标识符不符合命名规范 */
 export declare const INVALID_ACTION_ID = "INVALID_ACTION_ID";
 /** 规程标识符不符合命名规范 */
@@ -348,7 +360,7 @@ export declare function resolveExecutionHint(targetRef: string, 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 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 | typeof PROFILE_NOT_FOUND | typeof LOCKFILE_READ_FAILED | typeof LOCKFILE_CORRUPTED | typeof LOCKFILE_INVALID | typeof UNSUPPORTED_LOCKFILE_VERSION | typeof MANIFEST_READ_FAILED | typeof MANIFEST_CORRUPTED | typeof MANIFEST_INVALID | typeof UNSUPPORTED_MANIFEST_SCHEMA | typeof MANIFEST_NOT_FOUND | typeof MANIFEST_DIGEST_MISMATCH | typeof REGISTRY_CORRUPTED | typeof ASYNC_TRANSACTION_UNSUPPORTED | typeof STORAGE_CLOSED | typeof PACKAGE_ID_CONFLICT | typeof INVALID_PATH | typeof STORAGE_INIT_FAILED | typeof INVALID_STATE | typeof PROCESS_NOT_FOUND | typeof MODULE_RESOLVE_FAILED | typeof EXECUTION_CONCURRENCY_LIMIT | typeof PROJECT_CONFIG_NOT_FOUND | typeof MANIFEST_LOAD_FAILED | typeof INVALID_ACTION_ID | typeof INVALID_PLAYBOOK_ID | typeof PROJECT_ROOT_NOT_FOUND;
+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 DEPENDENCIES_NOT_READY | typeof DEPENDENCY_INSTALL_FAILED | typeof PROJECT_BUSY | typeof PROJECT_RECOVERY_REQUIRED | 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 | typeof PROFILE_NOT_FOUND | typeof LOCKFILE_READ_FAILED | typeof LOCKFILE_CORRUPTED | typeof LOCKFILE_INVALID | typeof UNSUPPORTED_LOCKFILE_VERSION | typeof MANIFEST_READ_FAILED | typeof MANIFEST_CORRUPTED | typeof MANIFEST_INVALID | typeof UNSUPPORTED_MANIFEST_SCHEMA | typeof MANIFEST_NOT_FOUND | typeof MANIFEST_DIGEST_MISMATCH | typeof REGISTRY_CORRUPTED | typeof ASYNC_TRANSACTION_UNSUPPORTED | typeof STORAGE_CLOSED | typeof PACKAGE_ID_CONFLICT | typeof INVALID_PATH | typeof STORAGE_INIT_FAILED | typeof INVALID_STATE | typeof PROCESS_NOT_FOUND | typeof MODULE_RESOLVE_FAILED | typeof EXECUTION_CONCURRENCY_LIMIT | typeof PROJECT_CONFIG_NOT_FOUND | typeof MANIFEST_LOAD_FAILED | typeof CONFIG_VALUE_INVALID | typeof CONFIG_ENCRYPTION_ERROR | typeof CONFIG_DECRYPT_FAILED | typeof INVALID_ACTION_ID | typeof INVALID_PLAYBOOK_ID | typeof PROJECT_ROOT_NOT_FOUND;
 /** 全仓统一错误码类型别名 */
 export type ActionDockErrorCode = ErrorCode;
 /**

package/dist/errors.js

@@ -71,6 +71,10 @@ export const CAPABILITY_UNAVAILABLE = "CAPABILITY_UNAVAILABLE";
 export const STATE_KEY_NOT_FOUND = "STATE_KEY_NOT_FOUND";
 /** SQLite 数据库忙或锁定 */
 export const STORAGE_BUSY = "STORAGE_BUSY";
+/** 所需生产依赖未就绪且当前环境不允许或不满足自动首装条件 */
+export const DEPENDENCIES_NOT_READY = "DEPENDENCIES_NOT_READY";
+/** 自动依赖安装进程启动失败、超时或非零退出 */
+export const DEPENDENCY_INSTALL_FAILED = "DEPENDENCY_INSTALL_FAILED";
 /** 工程事务锁被其他活跃进程持有 */
 export const PROJECT_BUSY = "PROJECT_BUSY";
 /** 工程存在未恢复的崩溃事务，需要执行恢复流程 */
@@ -299,6 +303,21 @@ export const EXECUTION_CONCURRENCY_LIMIT = "EXECUTION_CONCURRENCY_LIMIT";
 export const PROJECT_CONFIG_NOT_FOUND = "PROJECT_CONFIG_NOT_FOUND";
 /** 项目清单加载失败 */
 export const MANIFEST_LOAD_FAILED = "MANIFEST_LOAD_FAILED";
+/** 配置项数据值不符合声明的模式规范 */
+export const CONFIG_VALUE_INVALID = "CONFIG_VALUE_INVALID";
+/** 配置加密密钥缺失、无效或与存储域身份不符等加密配置错误 */
+export const CONFIG_ENCRYPTION_ERROR = "CONFIG_ENCRYPTION_ERROR";
+/** 配置密文解密失败（信封格式非法、版本未知、密钥身份不符或认证校验失败） */
+export const CONFIG_DECRYPT_FAILED = "CONFIG_DECRYPT_FAILED";
+const CONFIG_ENCRYPTION_ERROR_CODES = new Set([
+    CONFIG_ENCRYPTION_ERROR,
+    CONFIG_DECRYPT_FAILED,
+]);
+/** 配置加密与解密错误按结构化错误码识别，跨模块副本也不得吞没或覆盖。 */
+export function isConfigEncryptionError(error) {
+    const code = error?.code;
+    return typeof code === "string" && CONFIG_ENCRYPTION_ERROR_CODES.has(code);
+}
 /** 动作标识符不符合命名规范 */
 export const INVALID_ACTION_ID = "INVALID_ACTION_ID";
 /** 规程标识符不符合命名规范 */
@@ -372,6 +391,12 @@ export function resolveExecutionHint(targetRef, error) {
     if (error.code === ACTION_TIMEOUT) {
         return "Tip: Increase timeout via '--timeout <duration>', or run in background via '--async' and track with 'ad runs show <runId>'.";
     }
+    if (error.code === DEPENDENCIES_NOT_READY) {
+        return error.hint || error.details?.hint || "Tip: Install missing dependencies using 'npm install' or 'bun install'.";
+    }
+    if (error.code === DEPENDENCY_INSTALL_FAILED) {
+        return error.hint || error.details?.hint || "Tip: Check error output above and try running the package manager manually.";
+    }
     if (error.hint && typeof error.hint === "string") {
         return error.hint;
     }

package/dist/execution/service.js

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import { createActionCallKey } from "../invocation/policy.js";
 import { parseActionRef } from "../catalog/resolve-action.js";
 import { computeDigest } from "../project/digest.js";
 import { loadActions, loadProjectConfig } from "../project/loader.js";
@@ -265,7 +266,7 @@ export class DefaultExecutionService {
             const finalizer = createRunFinalizer(this.storage, runId);
             // 调用栈快照跟踪
             const callStack = context.callStack ? [...context.callStack] : [];
-            const callKey = targetPackageId ? `${targetPackageId}/${targetActionId}` : targetActionId;
+            const callKey = createActionCallKey(targetActionId, targetPackageId, context.targetScope);
             const lastStackItem = callStack[callStack.length - 1];
             const isAlreadyAtTop = lastStackItem === callKey ||
                 (targetActionId && lastStackItem === targetActionId) ||
@@ -288,7 +289,18 @@ export class DefaultExecutionService {
                 }
             }
             if (typeof context.timeoutMs === "number" && context.timeoutMs > 0) {
-                finalizer.startTimeout(controller, context.timeoutMs);
+                if (context.deadline !== undefined) {
+                    const remainingMs = Math.max(0, context.deadline - Date.now());
+                    if (remainingMs <= 0) {
+                        controller.abort(new ActionDockError(ACTION_TIMEOUT, `Action exceeded timeout of ${context.initialTimeoutMs ?? context.timeoutMs}ms`, { timeoutMs: context.initialTimeoutMs ?? context.timeoutMs }));
+                    }
+                    else {
+                        finalizer.startTimeout(controller, remainingMs, context.initialTimeoutMs ?? context.timeoutMs);
+                    }
+                }
+                else {
+                    finalizer.startTimeout(controller, context.timeoutMs, context.initialTimeoutMs);
+                }
             }
             const effectiveOwner = context.owner ||
                 createDefaultProcessOwner({
@@ -312,7 +324,7 @@ export class DefaultExecutionService {
                 owner: effectiveOwner,
                 progress: bridge.progressReporter,
                 logger: bridge.executionLogger,
-                onActionInvoke: (childAction, childInput, parentRunId) => this.invokeChildAction({
+                onActionInvoke: (childAction, childInput, parentRunId, options) => this.invokeChildAction({
                     controller,
                     rootRunId,
                     childAction,
@@ -324,6 +336,8 @@ export class DefaultExecutionService {
                     context,
                     effectiveProcess,
                     effectiveOwner,
+                    logger: bridge.executionLogger,
+                    options,
                 }),
             });
             const executionPromise = this.raceExecution({
@@ -423,6 +437,8 @@ export class DefaultExecutionService {
             package: opts.package || this.identity,
             signal: opts.signal,
             timeoutMs: opts.timeoutMs,
+            initialTimeoutMs: opts.initialTimeoutMs,
+            deadline: opts.deadline,
             maxCallDepth: opts.maxCallDepth,
             config: opts.config || opts.configOverrides,
             tenantId: opts.tenantId || opts.owner?.tenantId,
@@ -480,20 +496,36 @@ export class DefaultExecutionService {
             };
         }
         catch (err) {
-            return this.classifyExecutionError(err, runId, context.timeoutMs, controller, finalizer);
+            return this.classifyExecutionError(err, runId, context, controller, finalizer);
         }
     }
-    classifyExecutionError(err, runId, timeoutMs, controller, finalizer) {
+    classifyExecutionError(err, runId, context, controller, finalizer) {
+        const timeoutBudget = context.initialTimeoutMs ?? context.timeoutMs;
         if (finalizer.isTimeout) {
             const error = {
                 code: ACTION_TIMEOUT,
-                message: `Action exceeded timeout of ${timeoutMs}ms`,
+                message: `Action exceeded timeout of ${timeoutBudget}ms`,
             };
             finalizer.finalize("timed_out", undefined, error);
             return { ok: false, runId, error: finalizer.persistError || error };
         }
         if (controller.signal.aborted) {
             const reason = controller.signal.reason;
+            const reasonCode = reason?.code;
+            const isTimeoutReason = reasonCode === ACTION_TIMEOUT ||
+                (reason?.details && reason.details.code === ACTION_TIMEOUT) ||
+                (reason instanceof Error && reason.message?.includes("exceeded timeout")) ||
+                (typeof reason === "string" && reason.includes("exceeded timeout"));
+            if (isTimeoutReason) {
+                const error = {
+                    code: ACTION_TIMEOUT,
+                    message: (reason instanceof Error && reason.message?.includes("exceeded timeout"))
+                        ? reason.message
+                        : `Action exceeded timeout of ${timeoutBudget}ms`,
+                };
+                finalizer.finalize("timed_out", undefined, error);
+                return { ok: false, runId, error: finalizer.persistError || error };
+            }
             const reasonMsg = reason instanceof Error
                 ? reason.message
                 : typeof reason === "string"
@@ -520,7 +552,7 @@ export class DefaultExecutionService {
         };
     }
     async invokeChildAction(args) {
-        const { controller, rootRunId, childAction, childInput, parentRunId, currentActionId, currentAction, callStack, context, effectiveProcess, effectiveOwner, } = args;
+        const { controller, rootRunId, childAction, childInput, parentRunId, currentActionId, currentAction, callStack, context, effectiveProcess, effectiveOwner, logger, options, } = args;
         const invoker = this.actionInvoker;
         if (!invoker) {
             throw new ActionDockError(INVOCATION_UNSUPPORTED, "Nested action invocation requires a Host ActionInvoker");
@@ -541,18 +573,20 @@ export class DefaultExecutionService {
             package: this.identity,
             signal: controller.signal,
             timeoutMs: context.timeoutMs,
+            initialTimeoutMs: context.initialTimeoutMs,
+            deadline: context.deadline,
             maxCallDepth: context.maxCallDepth,
             config: context.config,
             tenantId: effectiveOwner.tenantId,
             principalId: effectiveOwner.principalId,
             hostSessionId: context.hostSessionId || this.hostSessionId,
-            logger: context.logger,
+            logger: logger ?? context.logger,
             progress: context.progress,
             process: effectiveProcess,
             owner: effectiveOwner,
             origin: context.origin,
         };
-        return await invoker(childAction, childInput, invocationContext);
+        return await invoker(childAction, childInput, invocationContext, options);
     }
     async checkIdempotencyGate(input, context, actionRef, effectiveClock) {
         if (!context.requestId) {
@@ -561,7 +595,7 @@ export class DefaultExecutionService {
         const digestPayload = {
             input,
             config: context.config,
-            timeoutMs: context.timeoutMs,
+            timeoutMs: context.initialTimeoutMs ?? context.timeoutMs,
         };
         const inputDigest = computeDigest(digestPayload);
         const provisionalRunId = crypto.randomUUID();

package/dist/execution/types.d.ts

@@ -1,4 +1,4 @@
-import type { ActionDefinition, ActionRef, ExecutionEvent, ExecutionResult, JsonValue, Logger, ProcessAPI, RunRecord, RunStatus } from "@actiondock/sdk";
+import type { ActionDefinition, ActionInvokeOptions, ActionRef, ExecutionEvent, ExecutionResult, JsonValue, Logger, ProcessAPI, RunRecord, RunStatus } from "@actiondock/sdk";
 import type { ProjectConfig } from "../project/types.js";
 import type { Clock } from "../storage/clock.js";
 import type { EventSink } from "../runtime/events.js";
@@ -6,7 +6,7 @@ import type { RuntimeStorage } from "../storage/types.js";
 import type { ModuleLoader } from "../platform/module-loader.js";
 import { type PackageIdentity, type RunOptions, type InvocationContext, createInvocationContext, createRootInvocationContext } from "../invocation/types.js";
 export { createInvocationContext, createRootInvocationContext };
-export type { PackageIdentity, RunOptions, InvocationContext };
+export type { PackageIdentity, RunOptions, InvocationContext, ActionInvokeOptions };
 /**
  * 局部动作解析器委托函数契约（仅限当前包内部动作）。
  */
@@ -29,7 +29,7 @@ export interface ExecutionHandle {
 /**
  * 跨包动作调用委托函数。
  */
-export type ActionInvoker = (childAction: ActionRef | string, childInput: unknown, context: InvocationContext) => Promise<unknown>;
+export type ActionInvoker = (childAction: ActionRef | string, childInput: unknown, context: InvocationContext, options?: ActionInvokeOptions) => Promise<unknown>;
 /**
  * 统一执行协调服务配置选项。
  */

package/dist/host/host.d.ts

@@ -9,13 +9,20 @@ import type { StateEntry } from "../storage/types.js";
 export declare class DefaultActionDockHost implements ActionDockHost {
     readonly hostSessionId: string;
     readonly options: ActionDockHostOptions;
+    readonly allowInstall?: boolean;
     private runtimes;
+    private extraRuntimes;
+    private extraRuntimeScopes;
     readonly policy: InvocationPolicy;
     private hostPublicPackageIds;
     private maxCallDepth;
     private maxSubRuns;
     private eventSink;
     private isClosed;
+    private readonly prepareLocalPackage?;
+    private readonly closeController;
+    private readonly activePreparations;
+    private closePromise?;
     private dataDirLock?;
     private failedLinkedPackages;
     private failedAutoLoad?;
@@ -26,6 +33,9 @@ export declare class DefaultActionDockHost implements ActionDockHost {
     private globalStorage?;
     private initPromise?;
     private isInitialized;
+    private readonly actionBindings;
+    private readonly remoteTargets;
+    private readonly remoteInvoker;
     readonly discovery: DiscoveryPort;
     readonly execution: ExecutionPort;
     readonly runs: RunsPort;
@@ -60,6 +70,8 @@ export declare class DefaultActionDockHost implements ActionDockHost {
      * 外部注入的 Runtime 保持既有生命周期约定，不在此预热。
      */
     private prewarmManagedRuntimes;
+    /** 返回的 Runtime 由 Host 统一接管，端口只清理自身缓存和附属资源。 */
+    private closeInvocationTargets;
     /**
      * 异步安全回滚初始化失败时所占用的资源。
      */
@@ -106,6 +118,12 @@ export declare class DefaultActionDockHost implements ActionDockHost {
     describePlaybook(id: string): Promise<PlaybookSpec>;
     runAction(ref: ActionRef | string, input: JsonValue, options?: RunOptions): Promise<ExecutionResult>;
     startAction(ref: ActionRef | string, input: JsonValue, options?: RunOptions): Promise<ExecutionTicket>;
+    /**
+     * 私有本地 Action 调度中枢。
+     * 统一处理本地已授权目标的准备（若已注入 prepareLocalPackage 且存在物理包根路径）、
+     * 中断与关闭复核，并分发至目标 Runtime 的 startInvocation。
+     */
+    private dispatchLocalInvocation;
     getRun(runId: string, signal?: AbortSignal): Promise<RunRecord | undefined>;
     listRuns(query?: ListRunsOptions, signal?: AbortSignal): Promise<RunRecord[]>;
     countRuns(query?: ListRunsOptions, signal?: AbortSignal): Promise<number>;
@@ -120,7 +138,8 @@ export declare class DefaultActionDockHost implements ActionDockHost {
     cancelRun(runId: string, reason?: string): Promise<CancelResult>;
     private subscribeEvents;
     private getGlobalStorage;
-    private findDeclaredConfigItem;
+    private findAllDeclaredConfigItems;
+    private protectGlobalConfigView;
     private resolveRuntime;
     /**
      * 解析目标包运行时：未命中时抛出统一的包未找到错误。