@actiondock/core 2.19.0 → 2.20.0

package/dist/invocation/remote.js

@@ -0,0 +1,489 @@
+import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { ActionDockError, ACTION_CANCELLED, EXECUTION_FAILED, INVALID_ARGUMENT, NETWORK_ERROR, SERVICE_CLOSED, SERVICE_RESULT_UNKNOWN, TIMEOUT, } from "../errors.js";
+import { parseActionRef } from "../catalog/resolve-action.js";
+import { RemoteActionDockService } from "../service/remote.js";
+/**
+ * 清理、反查与发现默认有界等待时限（毫秒）。
+ */
+const DEFAULT_CLEANUP_TIMEOUT_MS = 5000;
+const DEFAULT_LOOKUP_TIMEOUT_MS = 3000;
+const DEFAULT_DISCOVERY_TIMEOUT_MS = 10000;
+/**
+ * 过滤 URL 中携带的用户、密码凭据与敏感查询参数，防止泄漏至日志或异常元数据。
+ */
+function sanitizeServerUrl(urlStr) {
+    try {
+        const parsed = new URL(urlStr);
+        parsed.username = "";
+        parsed.password = "";
+        if (parsed.searchParams.has("token")) {
+            parsed.searchParams.set("token", "[REDACTED]");
+        }
+        return parsed.origin;
+    }
+    catch {
+        return "[invalid-url]";
+    }
+}
+/**
+ * 脱敏字符串中的敏感 Token 与 URL 凭据。
+ */
+function sanitizeString(str, token) {
+    let result = str;
+    if (token && token.length > 0) {
+        result = result.replaceAll(token, "[REDACTED]");
+    }
+    // 脱敏 URL 用户密码凭据 (http://user:pass@host)
+    result = result.replace(/(https?:\/\/)([^/@\s]+)@/g, "$1[REDACTED]@");
+    // 脱敏查询参数中的 token / key / secret / password
+    result = result.replace(/([?&](?:token|key|secret|password)=)[^&\s]+/gi, "$1[REDACTED]");
+    return result;
+}
+/**
+ * 格式化脱敏错误信息。
+ */
+function sanitizeErrorMessage(msg, token) {
+    if (typeof msg !== "string") {
+        return "";
+    }
+    return sanitizeString(msg, token);
+}
+/**
+ * 深度脱敏错误元数据与原始对象，防止 Token 与 URL 凭据泄漏。
+ */
+function sanitizeDetails(val, token) {
+    if (val === null || val === undefined) {
+        return val;
+    }
+    if (typeof val === "string") {
+        return sanitizeString(val, token);
+    }
+    if (val instanceof Error) {
+        return sanitizeString(val.message, token);
+    }
+    if (Array.isArray(val)) {
+        return val.map((item) => sanitizeDetails(item, token));
+    }
+    if (typeof val === "object") {
+        const sanitizedObj = {};
+        for (const [k, v] of Object.entries(val)) {
+            if (k.toLowerCase().includes("token") ||
+                k.toLowerCase().includes("secret") ||
+                k.toLowerCase().includes("password")) {
+                sanitizedObj[k] = "[REDACTED]";
+            }
+            else {
+                sanitizedObj[k] = sanitizeDetails(v, token);
+            }
+        }
+        return sanitizedObj;
+    }
+    return val;
+}
+/**
+ * 构造统一且剔除敏感凭据的错误详情信封。
+ */
+function buildErrorDetails(action, metadata, requestId, resultUnknown, remoteRunId, extra) {
+    return {
+        action,
+        binding: metadata.binding,
+        profile: metadata.profile,
+        requestId,
+        remoteRunId,
+        resultUnknown,
+        ...extra,
+    };
+}
+/**
+ * 针对指定唯一 requestId 执行有界反查。
+ */
+async function queryRunByRequestId(service, requestId, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const runs = await service.runs.list({ requestIds: [requestId], limit: 1 }, { signal: controller.signal });
+        return { record: runs && runs.length > 0 ? runs[0] : undefined };
+    }
+    catch (err) {
+        return { error: err };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * 针对远端任务执行有界取消调用，避免无限阻塞与定时器泄漏。
+ */
+async function cancelRunWithBoundedTimeout(service, runId, timeoutMs) {
+    let timer;
+    try {
+        const res = await Promise.race([
+            service.runs.cancel(runId, "Parent invocation cancelled"),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Cancellation timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+        if (res.outcome === "not_found" || res.outcome === "not_owner") {
+            return {
+                ok: false,
+                outcome: res.outcome,
+                resultUnknown: true,
+                error: new Error(`Cancellation failed with outcome: ${res.outcome}`),
+            };
+        }
+        if (res.outcome === "already_terminal") {
+            return {
+                ok: true,
+                outcome: "already_terminal",
+                resultUnknown: false,
+            };
+        }
+        // res.outcome === "requested"
+        // requested 仅表示已请求，不可宣称终态已停止，resultUnknown 要诚实
+        return {
+            ok: true,
+            outcome: "requested",
+            resultUnknown: true,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            resultUnknown: true,
+            error: err,
+        };
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
+/** 等待必须响应调用方取消，不能依赖服务实现主动结束结果 Promise。 */
+function waitWithSignal(operation, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? new Error("Invocation cancelled"));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason ?? new Error("Invocation cancelled"));
+        signal.addEventListener("abort", onAbort, { once: true });
+        operation.then((value) => { signal.removeEventListener("abort", onAbort); resolve(value); }, (error) => { signal.removeEventListener("abort", onAbort); reject(error); });
+    });
+}
+/**
+ * 安全的远端嵌套调用适配执行器。
+ *
+ * 遵循原则：
+ * - 目标 target 由 Host 预先根据 profile 解析并冻结传入，不自作路由决断。
+ * - 连接缓存按 target 对象身份隔离复用，并在 close() 时全量释放。
+ * - 严格防范凭证与本地私有上下文泄漏，仅透传必要控制字段。
+ * - 取消与清理全链路有界且透传远端 runs.cancel，严禁静默吞没未确认终态。
+ */
+export class RemoteInvocationExecutor {
+    logger;
+    services = new Map();
+    isClosed = false;
+    closeController = new AbortController();
+    pending = new Set();
+    constructor(options) {
+        this.logger = options?.logger;
+    }
+    /**
+     * 触发执行远端 Action 动作。
+     */
+    invoke(target, ref, input, context, metadata, expectedContract) {
+        const operation = this.execute(target, ref, input, {
+            ...context,
+            signal: AbortSignal.any([context.signal, this.closeController.signal]),
+        }, metadata, expectedContract);
+        this.pending.add(operation);
+        const settled = () => { this.pending.delete(operation); };
+        operation.then(settled, settled);
+        return operation;
+    }
+    async execute(target, ref, input, context, metadata, expectedContract) {
+        const childRequestId = randomUUID();
+        let parsedRef;
+        try {
+            parsedRef = parseActionRef(ref);
+        }
+        catch {
+            parsedRef = typeof ref === "object" && ref !== null ? ref : { actionId: String(ref) };
+        }
+        const actionStr = parsedRef.packageId
+            ? `${parsedRef.packageId}/${parsedRef.actionId}`
+            : parsedRef.actionId;
+        const logger = context.logger ?? this.logger;
+        const sanitizedTarget = sanitizeServerUrl(target.serverUrl);
+        const makeDetails = (resultUnknown, remoteRunId, extra) => buildErrorDetails(actionStr, metadata, childRequestId, resultUnknown, remoteRunId, extra);
+        // 1. 检查执行器生命周期状态
+        if (this.isClosed) {
+            const err = new ActionDockError(SERVICE_CLOSED, "RemoteInvocationExecutor is closed", makeDetails(false, undefined));
+            logger?.error?.(`[RemoteInvocation] Executor closed: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}`);
+            throw err;
+        }
+        // 2. 检查前置取消信号，阻止任何网络通信
+        if (context.signal.aborted) {
+            const err = new ActionDockError(ACTION_CANCELLED, "Action execution was cancelled before start", makeDetails(false, undefined));
+            logger?.warn?.(`[RemoteInvocation] Pre-cancelled: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}`);
+            throw err;
+        }
+        // 3. 复用或建立 target 对应的远端服务连接
+        let service = this.services.get(target);
+        if (!service) {
+            if (this.isClosed) {
+                throw new ActionDockError(SERVICE_CLOSED, "RemoteInvocationExecutor is closed", makeDetails(false, undefined));
+            }
+            service = new RemoteActionDockService(target);
+            this.services.set(target, service);
+        }
+        // 4. 远端契约发现与校验（使用有界 / AbortSignal race 确保响应父级取消，避免无限等待或取消后仍继续执行）
+        let remoteSpec;
+        const discoveryTimeoutMs = Math.min(DEFAULT_DISCOVERY_TIMEOUT_MS, Math.max(1000, context.timeoutMs ?? DEFAULT_DISCOVERY_TIMEOUT_MS));
+        try {
+            if (context.signal.aborted) {
+                throw new ActionDockError(ACTION_CANCELLED, "Action execution was cancelled before discovery", makeDetails(false, undefined));
+            }
+            let abortListener;
+            let discoveryTimer;
+            try {
+                remoteSpec = await Promise.race([
+                    service.discovery.describeAction(ref),
+                    new Promise((_, reject) => {
+                        abortListener = () => {
+                            reject(new ActionDockError(ACTION_CANCELLED, "Action execution was cancelled during discovery", makeDetails(false, undefined)));
+                        };
+                        context.signal.addEventListener("abort", abortListener, { once: true });
+                        discoveryTimer = setTimeout(() => {
+                            reject(new ActionDockError(NETWORK_ERROR, `Discovery timed out after ${discoveryTimeoutMs}ms for action '${actionStr}'`, makeDetails(false, undefined)));
+                        }, discoveryTimeoutMs);
+                    }),
+                ]);
+            }
+            finally {
+                if (discoveryTimer !== undefined) {
+                    clearTimeout(discoveryTimer);
+                }
+                if (abortListener !== undefined) {
+                    context.signal.removeEventListener("abort", abortListener);
+                }
+            }
+        }
+        catch (err) {
+            if (context.signal.aborted) {
+                throw new ActionDockError(ACTION_CANCELLED, "Action execution was cancelled during discovery", makeDetails(false, undefined));
+            }
+            const code = err?.code || NETWORK_ERROR;
+            const sanitizedMsg = sanitizeErrorMessage(err?.message, target.token);
+            const wrappedErr = new ActionDockError(code, `Failed to describe remote action '${actionStr}': ${sanitizedMsg}`, makeDetails(false, undefined, {
+                originalError: sanitizeDetails(err?.details ?? err?.message, target.token),
+            }));
+            logger?.error?.(`[RemoteInvocation] Discovery failed: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, error=${sanitizedMsg}`);
+            throw wrappedErr;
+        }
+        if (expectedContract) {
+            const expectedInput = expectedContract.inputSchema ?? {};
+            const actualInput = remoteSpec.inputSchema ?? {};
+            const expectedOutput = expectedContract.outputSchema ?? {};
+            const actualOutput = remoteSpec.outputSchema ?? {};
+            if (!isDeepStrictEqual(expectedInput, actualInput) || !isDeepStrictEqual(expectedOutput, actualOutput)) {
+                const err = new ActionDockError(INVALID_ARGUMENT, `Remote action contract schema mismatch for action '${actionStr}'`, makeDetails(false, undefined, {
+                    expectedInput,
+                    actualInput,
+                    expectedOutput,
+                    actualOutput,
+                }));
+                logger?.error?.(`[RemoteInvocation] Contract schema mismatch: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}`);
+                throw err;
+            }
+        }
+        // 5. 校验通过，准备发起远端异步执行
+        if (context.signal.aborted) {
+            throw new ActionDockError(ACTION_CANCELLED, "Action execution was cancelled before start", makeDetails(false, undefined));
+        }
+        const cleanupTimeoutMs = Math.min(DEFAULT_CLEANUP_TIMEOUT_MS, Math.max(1000, context.timeoutMs ?? DEFAULT_CLEANUP_TIMEOUT_MS));
+        const lookupTimeoutMs = Math.min(DEFAULT_LOOKUP_TIMEOUT_MS, Math.max(1000, context.timeoutMs ?? DEFAULT_LOOKUP_TIMEOUT_MS));
+        const startOptions = {
+            timeoutMs: context.timeoutMs,
+            requestId: childRequestId,
+            signal: context.signal,
+        };
+        let ticket;
+        let startError;
+        try {
+            ticket = await service.execution.start(ref, input, startOptions);
+        }
+        catch (err) {
+            startError = err;
+        }
+        // 检查 ticket 是否代表确定性拒绝（如鉴权失败、入参校验失败等）：
+        // execution.start 可能返回 { status: 'failed', runId: '', result: Promise.resolve({ ok: false, error: ... }) }
+        // 必须先读取 failed ticket 保留确定拒绝 code，不能误判为 SERVICE_RESULT_UNKNOWN。
+        if (ticket && (ticket.status === "failed" || !ticket.runId)) {
+            if (ticket.result) {
+                try {
+                    const res = await ticket.result;
+                    if (res && !res.ok && res.error) {
+                        const errCode = res.error.code;
+                        const isTransportUnknown = errCode === NETWORK_ERROR ||
+                            errCode === "ACTION_TIMEOUT" ||
+                            errCode === "TIMEOUT" ||
+                            errCode === ACTION_CANCELLED;
+                        if (!isTransportUnknown) {
+                            const sanitizedErrMsg = sanitizeErrorMessage(res.error.message, target.token) || "Remote execution rejected";
+                            logger?.warn?.(`[RemoteInvocation] Remote start rejected deterministically: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, code=${errCode}, error=${sanitizedErrMsg}`);
+                            throw new ActionDockError(errCode || EXECUTION_FAILED, sanitizedErrMsg, makeDetails(false, undefined, {
+                                remoteError: sanitizeDetails(res.error.details ?? res.error, target.token),
+                            }));
+                        }
+                    }
+                }
+                catch (readErr) {
+                    if (readErr instanceof ActionDockError) {
+                        throw readErr;
+                    }
+                    startError = readErr;
+                }
+            }
+            if (!ticket.runId) {
+                ticket = undefined;
+            }
+        }
+        // 6. 接受前中断处理（远端可能已受理执行，进行有界反查与补发取消）
+        if (!ticket || !ticket.runId) {
+            const lookupRes = await queryRunByRequestId(service, childRequestId, lookupTimeoutMs);
+            const foundRun = lookupRes.record;
+            if (foundRun) {
+                // 使用 RunRecord 的唯一标识 id（不可使用 runId）
+                const cancelRes = await cancelRunWithBoundedTimeout(service, foundRun.id, cleanupTimeoutMs);
+                if (!cancelRes.ok) {
+                    const sanitizedCancelMsg = sanitizeErrorMessage(cancelRes.error?.message, target.token);
+                    logger?.error?.(`[RemoteInvocation] Cancel cleanup failed for accepted run '${foundRun.id}': ${sanitizedCancelMsg}`);
+                    throw new ActionDockError(SERVICE_RESULT_UNKNOWN, `Interrupted before acceptance, and cancel cleanup failed for run '${foundRun.id}': ${sanitizedCancelMsg}`, makeDetails(true, foundRun.id, {
+                        cancelOutcome: cancelRes.outcome,
+                        originalError: sanitizedCancelMsg,
+                    }));
+                }
+                if (context.signal.aborted) {
+                    throw new ActionDockError(ACTION_CANCELLED, "Action execution was cancelled", makeDetails(cancelRes.resultUnknown, foundRun.id, {
+                        cancelOutcome: cancelRes.outcome,
+                    }));
+                }
+                const sanitizedStartMsg = sanitizeErrorMessage(startError?.message, target.token);
+                throw new ActionDockError(SERVICE_RESULT_UNKNOWN, `Action execution was interrupted before acceptance and cancelled on remote: ${sanitizedStartMsg}`, makeDetails(cancelRes.resultUnknown, foundRun.id, {
+                    cancelOutcome: cancelRes.outcome,
+                    originalError: sanitizedStartMsg,
+                }));
+            }
+            // 反查若发生错误，必须提供可观测错误元信息，不可宣称无记录
+            if (lookupRes.error) {
+                const sanitizedLookupMsg = sanitizeErrorMessage(lookupRes.error?.message, target.token);
+                const sanitizedStartMsg = sanitizeErrorMessage(startError?.message, target.token);
+                logger?.warn?.(`[RemoteInvocation] Interrupted before acceptance and run lookup failed: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, lookupError=${sanitizedLookupMsg}`);
+                throw new ActionDockError(SERVICE_RESULT_UNKNOWN, `Action execution interrupted before acceptance; query run by requestId failed: ${sanitizedLookupMsg}`, makeDetails(true, undefined, {
+                    lookupError: sanitizedLookupMsg,
+                    originalError: sanitizedStartMsg,
+                }));
+            }
+            // 反查成功但无记录：未能确认终态应使用 SERVICE_RESULT_UNKNOWN
+            const sanitizedStartMsg = sanitizeErrorMessage(startError?.message, target.token);
+            logger?.warn?.(`[RemoteInvocation] Interrupted before acceptance with unknown remote status: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}`);
+            throw new ActionDockError(SERVICE_RESULT_UNKNOWN, `Action execution interrupted before acceptance; remote execution status is unknown: ${sanitizedStartMsg}`, makeDetails(true, undefined, {
+                lookupRecordFound: false,
+                originalError: sanitizedStartMsg,
+            }));
+        }
+        // 7. 远端已成功接受调用并返回 runId
+        const remoteRunId = ticket.runId;
+        logger?.info(`[RemoteInvocation] Accepted: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, remoteRunId=${remoteRunId}`);
+        // 显式检查 ticket.result 是否存在，缺失应抛出 EXECUTION_FAILED 且不可触发 TypeError
+        if (!ticket.result) {
+            const err = new ActionDockError(EXECUTION_FAILED, `Execution ticket missing result Promise for remote run '${remoteRunId}'`, makeDetails(true, remoteRunId));
+            logger?.error?.(`[RemoteInvocation] Missing ticket.result: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, remoteRunId=${remoteRunId}`);
+            throw err;
+        }
+        // 防止未处理的 Promise Rejection
+        ticket.result.catch(() => { });
+        let cancelPromise;
+        const abortHandler = () => {
+            cancelPromise = cancelRunWithBoundedTimeout(service, remoteRunId, cleanupTimeoutMs);
+        };
+        if (context.signal.aborted) {
+            abortHandler();
+        }
+        else {
+            context.signal.addEventListener("abort", abortHandler, { once: true });
+        }
+        try {
+            let execResult;
+            try {
+                execResult = await waitWithSignal(ticket.result, context.signal);
+            }
+            catch (waitErr) {
+                if (context.signal.aborted) {
+                    const cancelRes = await (cancelPromise ?? cancelRunWithBoundedTimeout(service, remoteRunId, cleanupTimeoutMs));
+                    if (!cancelRes.ok) {
+                        const sanitizedCancelMsg = sanitizeErrorMessage(cancelRes.error?.message, target.token);
+                        logger?.error?.(`[RemoteInvocation] Cancellation cleanup failed: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, remoteRunId=${remoteRunId}, error=${sanitizedCancelMsg}`);
+                        throw new ActionDockError(SERVICE_RESULT_UNKNOWN, `Cancellation cleanup failed: ${sanitizedCancelMsg}`, makeDetails(true, remoteRunId, { cancelOutcome: cancelRes.outcome }));
+                    }
+                    throw new ActionDockError(ACTION_CANCELLED, "Action execution was cancelled", makeDetails(cancelRes.resultUnknown, remoteRunId, { cancelOutcome: cancelRes.outcome }));
+                }
+                const sanitizedWaitMsg = sanitizeErrorMessage(waitErr?.message, target.token);
+                logger?.error?.(`[RemoteInvocation] Network failure while waiting: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, remoteRunId=${remoteRunId}, error=${sanitizedWaitMsg}`);
+                throw new ActionDockError(SERVICE_RESULT_UNKNOWN, `Communication lost while waiting for remote run '${remoteRunId}': ${sanitizedWaitMsg}`, makeDetails(true, remoteRunId, { originalError: sanitizedWaitMsg }));
+            }
+            // 若在此期间已被信号取消，必须等待远端 runs.cancel 发送完成
+            if (context.signal.aborted) {
+                const cancelRes = await (cancelPromise ?? cancelRunWithBoundedTimeout(service, remoteRunId, cleanupTimeoutMs));
+                if (!cancelRes.ok) {
+                    const sanitizedCancelMsg = sanitizeErrorMessage(cancelRes.error?.message, target.token);
+                    logger?.error?.(`[RemoteInvocation] Cancellation cleanup failed: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, remoteRunId=${remoteRunId}, error=${sanitizedCancelMsg}`);
+                    throw new ActionDockError(SERVICE_RESULT_UNKNOWN, `Cancellation cleanup failed: ${sanitizedCancelMsg}`, makeDetails(true, remoteRunId, { cancelOutcome: cancelRes.outcome }));
+                }
+                logger?.info?.(`[RemoteInvocation] Cancellation requested: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, remoteRunId=${remoteRunId}`);
+                throw new ActionDockError(ACTION_CANCELLED, "Action execution was cancelled", makeDetails(cancelRes.resultUnknown, remoteRunId, { cancelOutcome: cancelRes.outcome }));
+            }
+            if (execResult.ok) {
+                logger?.info?.(`[RemoteInvocation] Succeeded: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, remoteRunId=${remoteRunId}, target=${sanitizedTarget}`);
+                return execResult.data;
+            }
+            // 执行终态失败分支
+            const errCode = execResult.error?.code;
+            const rawErrMsg = execResult.error?.message || "Remote action execution failed";
+            const sanitizedErrMsg = sanitizeErrorMessage(rawErrMsg, target.token);
+            if (errCode === NETWORK_ERROR || errCode === TIMEOUT || errCode === SERVICE_RESULT_UNKNOWN) {
+                logger?.error?.(`[RemoteInvocation] Network error during execution wait: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, remoteRunId=${remoteRunId}`);
+                throw new ActionDockError(SERVICE_RESULT_UNKNOWN, `Network error while waiting for remote run '${remoteRunId}': ${sanitizedErrMsg}`, makeDetails(true, remoteRunId, {
+                    remoteError: sanitizeDetails(execResult.error, target.token),
+                }));
+            }
+            if (errCode === SERVICE_CLOSED) {
+                throw new ActionDockError(SERVICE_CLOSED, `Remote service closed: ${sanitizedErrMsg}`, makeDetails(true, remoteRunId));
+            }
+            // 确定业务失败：保留原错误码
+            logger?.warn?.(`[RemoteInvocation] Business error: action=${actionStr}, binding=${metadata.binding}, profile=${metadata.profile}, requestId=${childRequestId}, remoteRunId=${remoteRunId}, code=${errCode}`);
+            throw new ActionDockError(errCode || "ACTION_FAILED", sanitizedErrMsg, makeDetails(false, remoteRunId, {
+                remoteError: sanitizeDetails(execResult.error?.details ?? execResult.error, target.token),
+            }));
+        }
+        finally {
+            context.signal.removeEventListener("abort", abortHandler);
+        }
+    }
+    /**
+     * 关闭所有持有的远端服务连接并释放关联资源，对外拒绝后续调用。
+     */
+    async close() {
+        if (this.isClosed) {
+            return;
+        }
+        this.isClosed = true;
+        this.closeController.abort(new ActionDockError(SERVICE_CLOSED, "Remote invocation executor is closing"));
+        // 先让在途调用完成有界反查与协作取消，再关闭其依赖的服务连接。
+        await Promise.allSettled(Array.from(this.pending));
+        const servicesToClose = Array.from(this.services.values());
+        this.services.clear();
+        await Promise.all(servicesToClose.map((s) => s.close()));
+    }
+}

package/dist/invocation/types.d.ts

@@ -49,6 +49,8 @@ export interface InvocationContext {
     readonly caller?: InvocationCaller;
     /** 调用栈数组快照（用于环路检测与调用深度限制） */
     readonly callStack: readonly string[];
+    /** 已解析目标的调用栈作用域，仅用于宿主内部执行，不跨网络透传。 */
+    readonly targetScope?: string;
     /** 目标包物理与快照身份标识 */
     readonly package: PackageIdentity;
     /** 取消信号 */

package/dist/invocation/types.js

@@ -31,6 +31,7 @@ export function createInvocationContext(options) {
         parentRunId: options.parentRunId,
         caller: options.caller,
         callStack: options.callStack ? [...options.callStack] : [],
+        targetScope: options.targetScope,
         package: pkg,
         signal: options.signal ?? new AbortController().signal,
         timeoutMs: options.timeoutMs,

package/dist/package/index.d.ts

@@ -10,7 +10,7 @@ export { createPackageRuntime, DefaultPackageRuntime, } from "./runtime.js";
 export { createNonClosingStorageView } from "./storage-view.js";
 export { findExecutable } from "../utils/index.js";
 export type { PackageRuntime, PackageRuntimeOptions, PackageInfo, ActionSpec, ActionSummary, PlaybookSpec, PlaybookSummary, } from "./types.js";
-export type { RuntimePlatform, StorageFactory, StorageFactoryOptions, GlobalStorageFactoryOptions, } from "../platform/types.js";
+export type { RuntimePlatform, StorageFactory, StorageFactoryOptions, GlobalStorageFactoryOptions, InvocationTargetResolution, InvocationCallerInfo, InvocationTargetResolver, } from "../platform/types.js";
 export { type Clock, SystemClock, } from "../storage/clock.js";
 export type { ModuleLoader } from "../platform/module-loader.js";
 export { InMemoryEventSink, type EventSink, } from "../runtime/events.js";

package/dist/package/runtime.js

@@ -5,7 +5,8 @@ import { createNodePlatform } from "../platform/index.js";
 import { findProjectRoot, loadProjectConfig } from "../project/loader.js";
 import { RuntimeConfig } from "../runtime/context.js";
 import { normalizeActionCollection } from "../runtime/action-collection.js";
-import { isSecretConfigKey, sanitizeConfigDefinitions } from "../storage/mask.js";
+import { redactConfigValue, sanitizeConfigDefinitions } from "../storage/mask.js";
+import { assertConcreteConfigKey, assertValidConfigDeclarations, isConfigTemplate, resolveConfigDeclaration, validateConfigValue, } from "../project/config-declarations.js";
 import { decodeStateKey, SqliteRuntimeStorage } from "../storage/sqlite.js";
 import { createPackageIdentity } from "../runtime/identity.js";
 import { ACTION_NOT_FOUND, ActionDockError, CAPABILITY_UNAVAILABLE, INVALID_ARGUMENT, INVOCATION_UNSUPPORTED, NOT_FOUND, SERVICE_CLOSED, } from "../errors.js";
@@ -127,6 +128,9 @@ export class DefaultPackageRuntime {
             };
         }
         this.packageRoot = packageRoot;
+        if (projectConfig.config !== undefined) {
+            assertValidConfigDeclarations(projectConfig.config);
+        }
         this.projectConfig = projectConfig;
         // 兼容未在公开选项契约中显式声明的包实例标识与代系标识内部参数透传
         this.identity = options.identity || createPackageIdentity({
@@ -679,9 +683,18 @@ export class DefaultPackageRuntime {
     }
     async listConfig() {
         this.assertOpen();
-        const declared = this.projectConfig.config || {};
-        const stored = (await this.prepareStorageAsync()).listConfig();
-        const allKeys = Array.from(new Set([...Object.keys(declared), ...Object.keys(stored)]));
+        const packageStorage = await this.prepareStorageAsync();
+        const globalStorage = await this.ensureGlobalStorage();
+        const declaredKeys = Object.keys(this.projectConfig.config || {}).filter((k) => !isConfigTemplate(k));
+        const packageStoredKeys = Object.keys(packageStorage.listConfig());
+        const globalStoredKeys = Object.keys(globalStorage.listConfig());
+        const overrideKeys = Object.keys(this.options.configOverrides || {});
+        const allKeys = Array.from(new Set([
+            ...declaredKeys,
+            ...packageStoredKeys,
+            ...globalStoredKeys,
+            ...overrideKeys,
+        ])).filter((k) => !isConfigTemplate(k));
         const views = [];
         for (const key of allKeys) {
             const item = await this.getConfig(key);
@@ -693,27 +706,33 @@ export class DefaultPackageRuntime {
     }
     async getConfig(key) {
         this.assertOpen();
-        const itemDef = this.projectConfig.config?.[key];
-        const isSecret = isSecretConfigKey(key, itemDef);
+        assertConcreteConfigKey(key);
+        const decl = resolveConfigDeclaration(this.projectConfig.config, key);
         // 委托 RuntimeConfig 五层优先级链单一事实源，避免重复实现解析链
         const resolved = this.ensureRuntimeConfig().describe(key);
-        // overrides 来源对外统一星现为包级覆盖视角
-        const source = resolved.source === "overrides" ? "package" : resolved.source;
-        const configured = resolved.source !== "default";
+        // configured 显式判定：仅真实显式来源（override/package/global/env）为 true，
+        // default 与整链未命中（source null）均为 false，不得依赖与 "default" 的不等比较
+        const configured = resolved.source !== null && resolved.source !== "default";
+        const redacted = redactConfigValue(resolved.value, decl?.item);
         return {
             key,
             configured,
-            secret: isSecret,
-            source,
-            value: isSecret ? undefined : resolved.value,
+            secret: redacted.secret,
+            source: resolved.source,
+            value: redacted.value,
+            redactedPaths: redacted.redactedPaths,
         };
     }
     async setConfig(key, value) {
         this.assertOpen();
+        assertConcreteConfigKey(key);
+        const decl = resolveConfigDeclaration(this.projectConfig.config, key);
+        validateConfigValue(key, value, decl?.item);
         await (await this.prepareStorageAsync()).setConfig(key, value);
     }
     async deleteConfig(key) {
         this.assertOpen();
+        assertConcreteConfigKey(key);
         return await (await this.prepareStorageAsync()).deleteConfig(key);
     }
     /**

package/dist/platform/types.d.ts

@@ -1,8 +1,9 @@
-import type { ProcessAPI } from "@actiondock/sdk";
+import type { ActionInvokeOptions, ProcessAPI } from "@actiondock/sdk";
 import type { Clock } from "../storage/clock.js";
 import type { ModuleLoader } from "./module-loader.js";
 import type { RunsRetentionPolicy, RuntimeStorage } from "../storage/types.js";
 import type { EventSink } from "../runtime/events.js";
+import type { PackageRuntime } from "../package/types.js";
 /**
  * 跨运行时持久化存储工厂配置选项。
  */
@@ -42,6 +43,48 @@ export interface StorageFactory {
      */
     createGlobalStorage(options?: GlobalStorageFactoryOptions): RuntimeStorage;
 }
+/**
+ * 动作调用目标解析结果。
+ */
+export interface InvocationTargetResolution {
+    /** 目标 PackageRuntime 实例 */
+    readonly runtime: PackageRuntime;
+    /** 可选调用作用域，用于区分调用目标与环路死锁检测身份 */
+    readonly scope?: string;
+    /** 是否强制要求调用方显式声明 uses 依赖 */
+    readonly requiresExplicitUses?: boolean;
+}
+/**
+ * 动作调用发起方元数据信息。
+ */
+export interface InvocationCallerInfo {
+    /** 调用发起方包标识 */
+    readonly packageId: string;
+    /** 调用发起方 Action 动作标识 */
+    readonly actionId?: string;
+}
+/**
+ * 运行时平台调用目标解析器端口契约。
+ * 允许底层运行时平台在 Host 选择执行目标阶段介入目标解析，提供自定义 PackageRuntime。
+ */
+export interface InvocationTargetResolver {
+    /**
+     * 解析指定 Action 引用与调用选项对应的目标 PackageRuntime。
+     *
+     * @param action 规范化 Action 引用元数据
+     * @param options 动作调用选项（包含命名 binding 等）
+     * @param caller 发起调用的调用方元数据
+     * @returns 目标解析结果；返回的 Runtime 由 Host 接管生命周期；未命中返回 undefined 交由默认主链处理
+     */
+    resolve(action: {
+        packageId: string;
+        actionId: string;
+    }, options: ActionInvokeOptions | undefined, caller: InvocationCallerInfo): InvocationTargetResolution | undefined;
+    /**
+     * 清理端口缓存和附属资源，不重复关闭已移交 Host 的 Runtime。
+     */
+    close?(): Promise<void>;
+}
 /**
  * 运行时底层环境核心标准契约。
  * 提供统一的运行时契约，屏蔽宿主平台与测试沙箱环境的实现差异。
@@ -61,4 +104,8 @@ export interface RuntimePlatform {
      * 可选执行事件接收器，宿主可注入，缺省由上层默认构造。
      */
     readonly eventSink?: EventSink;
+    /**
+     * 可选动作调用目标解析器端口，用于宿主环境自定义动作调用路由（例如测试具名 Mock 模拟目标）。
+     */
+    readonly invocationTargets?: InvocationTargetResolver;
 }