@actiondock/core 2.19.0 → 2.20.0

package/dist/input/input-resolver.js

@@ -2,7 +2,7 @@ import { inputConflict, inputLimitExceeded, inputPathConflict, invalidFlatArgume
 import { isFlatPathPropertyName, isForbiddenActionInputPropertyName, } from "./flat-predicates.js";
 import { decodeFlatInput } from "./flat-decode.js";
 import { assertTopLevelLeafAvailable, assertMaterializedInputWithinLimits, } from "./flat-materializer.js";
-import { validateJsonValue, DEFAULT_MAX_JSON_DEPTH, } from "../value-validator.js";
+import { validateJsonValue, hasDangerousKeys, DEFAULT_MAX_JSON_DEPTH, } from "../value-validator.js";
 import { scanJsonDepth } from "./json-depth-scanner.js";
 import { decodeUtf8Strict, stripBom } from "./utf8.js";
 import { readRegularFileBounded, DEFAULT_MAX_INPUT_BYTES, } from "./file-input.js";
@@ -203,8 +203,29 @@ export function parseJson(text, source, policy) {
     }
     return parsed;
 }
+function checkValueProperties(value) {
+    if (hasDangerousKeys(value)) {
+        throw invalidJson("Input value contains prohibited prototype pollution properties", { reason: "FORBIDDEN_PROPERTY" });
+    }
+    return value;
+}
 /**
- * 统一解析 Action 执行入参。
+ * 解析一个完整值：合法 JSON 解码为对应类型，非 JSON 文本保留为字符串。
+ * 只有语法错误允许回退；大小、深度、有限数和危险属性校验失败必须透传。
+ */
+export function parseValueLiteral(text, policy) {
+    try {
+        return checkValueProperties(parseJson(text, "value", policy));
+    }
+    catch (error) {
+        if (error instanceof InputError && error.code === "INVALID_JSON" && !Array.isArray(error.details) && error.details?.reason === "SYNTAX_ERROR") {
+            return text;
+        }
+        throw policy?.sanitizeInputErrors ? sanitizeError(error, "inline-json") : error;
+    }
+}
+/**
+ * 统一解析 JSON 值及结构化输入，不承担 Action、配置或状态的业务校验。
  *
  * 输入模式仲裁规则（Input Mode Arbitration）：
  * - effectiveFlat: flatArgs 存在且 length > 0
@@ -221,16 +242,16 @@ export function parseJson(text, source, policy) {
  * - stdinField 的 stdin 读取为原始文本绑定：不做 JSON 解析、不剥 BOM、保留首尾空白，空 stdin 得到空字符串。
  *
  * @param options 输入解析选项
- * @returns 解析后的 JSON 对象
+ * @returns 解析后的 JSON 值
  */
-export async function resolveActionInput(options) {
+export async function resolveInput(options) {
     const effectiveFlat = (options.flatArgs?.length ?? 0) > 0;
     const hasInlineJson = options.input !== undefined;
     const hasFileJson = options.inputFile !== undefined;
     const hasStdinField = options.stdinField !== undefined;
     // stdin 字段绑定与完整 JSON 来源（内联 / 文件 / stdin JSON）严格互斥
     if (hasStdinField && (hasInlineJson || hasFileJson)) {
-        const err = inputConflict("Input options conflict: --stdin-field binds raw stdin text to an action input field and cannot be combined with inline JSON (-i/--input) or file input (-f/--input-file).", {
+        const err = inputConflict("Input options conflict: --stdin-field binds raw stdin text to a top-level field and cannot be combined with inline JSON (-i/--input) or file input (-f/--input-file).", {
             reason: "MULTIPLE_INPUT_MODES",
             hasFlatArgs: effectiveFlat,
             hasInput: hasInlineJson,
@@ -371,3 +392,50 @@ export async function resolveActionInput(options) {
     }
     return {};
 }
+/** Action 入参复用同一解码器，避免各命令的扁平路径与 stdin 绑定语义漂移。 */
+export const resolveActionInput = resolveInput;
+export function hasValueInput(input) {
+    return input.value !== undefined || input.flatArgs !== undefined || Boolean(input.fromStdin) || input.stdinField !== undefined;
+}
+/** 先仲裁来源再读流，配置、状态及独立运行入口使用同一完整值解码规则。 */
+export async function resolveValueInput(options) {
+    options.signal?.throwIfAborted();
+    const wholeModes = Number(options.value !== undefined) + Number(Boolean(options.fromStdin));
+    const structured = options.flatArgs !== undefined || options.stdinField !== undefined;
+    if (wholeModes + Number(structured) > 1) {
+        throw inputConflict("Complete value, --stdin, and structured input are mutually exclusive; --stdin-field may only be combined with flat assignments.", { reason: "MULTIPLE_INPUT_MODES" });
+    }
+    if (structured) {
+        if (options.stdinField === undefined && options.flatArgs?.length === 0) {
+            throw invalidFlatArgument("At least one flat assignment is required after '--'.", { reason: "MISSING_ASSIGNMENT" });
+        }
+        const value = checkValueProperties(await resolveInput(options));
+        options.signal?.throwIfAborted();
+        return value;
+    }
+    let text = options.value;
+    if (options.fromStdin) {
+        try {
+            text = await readStdinBounded(options.stdin || process.stdin, {
+                maxInputBytes: options.policy?.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES,
+                signal: options.signal,
+                strictUtf8: options.policy?.strictUtf8 ?? false,
+                rawText: true,
+                byteStreamOnly: options.policy?.byteStreamOnly,
+            });
+            // 完整 stdin 值保留原配置命令的末尾换行裁剪；字段绑定则原样保留文本。
+            text = text.replace(/[\r\n]+$/, "");
+        }
+        catch (error) {
+            throw options.policy?.sanitizeInputErrors ? sanitizeError(error, "stdin") : error;
+        }
+        if (text.length === 0)
+            throw invalidFlatArgument("No data received from standard input", { reason: "MISSING_VALUE" });
+    }
+    if (text === undefined) {
+        throw invalidFlatArgument("A complete value, flat assignments, --stdin, or --stdin-field is required.", { reason: "MISSING_VALUE" });
+    }
+    const value = parseValueLiteral(text, options.policy);
+    options.signal?.throwIfAborted();
+    return value;
+}

package/dist/invocation/bindings.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 动作绑定目标描述。
+ */
+export type ActionBindingTarget = {
+    type: "local";
+} | {
+    type: "remote";
+    profile: string;
+};
+/**
+ * 动作命名绑定字典单一事实源类型。
+ */
+export type ActionBindings = Readonly<Record<string, Readonly<Record<string, ActionBindingTarget>>>>;
+/** 绑定文件名与目录常量 */
+export declare const BINDINGS_DIR_NAME = ".actiondock";
+export declare const BINDINGS_FILE_NAME = "bindings.json";
+/** 绑定名称正则约束（稳定简单标识符） */
+export declare const ACTION_BINDING_NAME_REGEX: RegExp;
+/** 环境配置名称正则约束 */
+export declare const PROFILE_NAME_REGEX: RegExp;
+/**
+ * 校验并规范化完全限定的动作引用字符串。
+ * 铁律：必须为完全限定包与动作，禁止通配符、路径逃逸、空白与冒号。
+ */
+export declare function validateCanonicalActionRef(ref: unknown): string;
+/**
+ * 校验绑定名称合法性。
+ */
+export declare function validateBindingName(name: unknown, actionRef?: string): string;
+/**
+ * 校验单个绑定目标对象的合法性并返回深拷贝冻结快照。
+ */
+export declare function validateBindingTarget(target: unknown, bindingName: string, actionRef: string): ActionBindingTarget;
+/**
+ * 校验并深拷贝冻结动作绑定配置快照。
+ */
+export declare function validateActionBindings(value: unknown): ActionBindings;
+/**
+ * 从调用方项目目录读取动作绑定配置。
+ * 若文件不存在则返回空冻结映射，其余 IO 或 JSON 异常统一转换为 ActionDockError 透传。
+ */
+export declare function loadActionBindings(projectRoot: string): ActionBindings;
+/**
+ * 解析目标动作引用在当前项目中的具体绑定。
+ * 未显式传入 binding 则仅检索 default；若 default 亦不存在则返回 undefined。
+ * 若显式传入的 binding 不存在，抛出 ActionDockError(NOT_FOUND) 并在 details 中携带 action 与 binding。
+ */
+export declare function resolveActionBinding(bindings: ActionBindings, ref: string, binding?: string): ActionBindingTarget | undefined;
+/**
+ * 检测指定动作是否存在任意 remote 类型的命名绑定。
+ * 仅做完全限定精确匹配，供构建工具快速识别可外置的跨节点依赖。
+ */
+export declare function hasRemoteActionBinding(bindings: ActionBindings, ref: string): boolean;

package/dist/invocation/bindings.js

@@ -0,0 +1,248 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ActionDockError, INVALID_ACTION_REF, INVALID_ARGUMENT, INVALID_JSON, NOT_FOUND, } from "../errors.js";
+import { parseActionRef } from "../catalog/resolve-action.js";
+import { PACKAGE_ID_REGEX } from "../utils/index.js";
+import { ACTION_ID_REGEX } from "../project/manifest.js";
+/** 绑定文件名与目录常量 */
+export const BINDINGS_DIR_NAME = ".actiondock";
+export const BINDINGS_FILE_NAME = "bindings.json";
+/** 绑定名称正则约束（稳定简单标识符） */
+export const ACTION_BINDING_NAME_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/** 环境配置名称正则约束 */
+export const PROFILE_NAME_REGEX = /^[a-zA-Z0-9_\-\.]+$/;
+/** 空冻结绑定快照单一事实源 */
+const EMPTY_ACTION_BINDINGS = Object.freeze(Object.create(null));
+/**
+ * 校验并规范化完全限定的动作引用字符串。
+ * 铁律：必须为完全限定包与动作，禁止通配符、路径逃逸、空白与冒号。
+ */
+export function validateCanonicalActionRef(ref) {
+    if (typeof ref !== "string") {
+        throw new ActionDockError(INVALID_ACTION_REF, "Invalid action reference: must be a string");
+    }
+    if (ref.length === 0 || /\s/.test(ref)) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': cannot be empty or contain whitespace`);
+    }
+    if (ref.includes(":")) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': colon syntax is not permitted, use '/'`);
+    }
+    if (ref.includes("*") || ref.includes("?")) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': wildcards are not permitted`);
+    }
+    if (ref.includes("..")) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': path traversal is not permitted`);
+    }
+    if (!ref.includes("/")) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': must be fully qualified with package and action (e.g. 'pkg/action')`);
+    }
+    const parsed = parseActionRef(ref);
+    if (!parsed.packageId || !parsed.actionId) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': must be fully qualified with package and action`);
+    }
+    const isScoped = /^@[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(parsed.packageId);
+    if (!PACKAGE_ID_REGEX.test(parsed.packageId) && !isScoped) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid package ID '${parsed.packageId}' in action reference '${ref}'`);
+    }
+    if (!ACTION_ID_REGEX.test(parsed.actionId)) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action ID '${parsed.actionId}' in action reference '${ref}'`);
+    }
+    return `${parsed.packageId}/${parsed.actionId}`;
+}
+/**
+ * 校验绑定名称合法性。
+ */
+export function validateBindingName(name, actionRef) {
+    if (typeof name !== "string") {
+        throw new ActionDockError(INVALID_ARGUMENT, "Invalid binding name: must be a string");
+    }
+    if (name.length === 0 || /\s/.test(name)) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid binding name '${name}': cannot be empty or contain whitespace`);
+    }
+    if (name === "__proto__" || name === "constructor" || name === "prototype") {
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid binding name '${name}': prototype property names are forbidden`);
+    }
+    if (!ACTION_BINDING_NAME_REGEX.test(name)) {
+        const actionMsg = actionRef ? ` for action '${actionRef}'` : "";
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid binding name '${name}'${actionMsg}: must match ${ACTION_BINDING_NAME_REGEX}`);
+    }
+    return name;
+}
+/**
+ * 校验单个绑定目标对象的合法性并返回深拷贝冻结快照。
+ */
+export function validateBindingTarget(target, bindingName, actionRef) {
+    if (target === null || typeof target !== "object" || Array.isArray(target)) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid binding target for action '${actionRef}' binding '${bindingName}': expected a JSON object`);
+    }
+    if (!Object.prototype.hasOwnProperty.call(target, "type")) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Missing 'type' in binding '${bindingName}' for action '${actionRef}'`);
+    }
+    const keys = Object.keys(target);
+    const type = target.type;
+    if (type === "local") {
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(target, key))
+                continue;
+            if (key !== "type") {
+                throw new ActionDockError(INVALID_ARGUMENT, `Invalid property '${key}' in local binding '${bindingName}' for action '${actionRef}': local targets do not permit extra properties`);
+            }
+        }
+        return Object.freeze({ type: "local" });
+    }
+    if (type === "remote") {
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(target, key))
+                continue;
+            if (key !== "type" && key !== "profile") {
+                throw new ActionDockError(INVALID_ARGUMENT, `Invalid property '${key}' in remote binding '${bindingName}' for action '${actionRef}': remote targets only permit 'type' and 'profile'`);
+            }
+        }
+        if (!Object.prototype.hasOwnProperty.call(target, "profile")) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Missing 'profile' in remote binding '${bindingName}' for action '${actionRef}'`);
+        }
+        const profile = target.profile;
+        if (typeof profile !== "string" ||
+            profile.length === 0 ||
+            /\s/.test(profile) ||
+            !PROFILE_NAME_REGEX.test(profile)) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Invalid profile '${String(profile)}' in remote binding '${bindingName}' for action '${actionRef}': profile must be non-empty and cannot contain whitespace`);
+        }
+        return Object.freeze({ type: "remote", profile });
+    }
+    throw new ActionDockError(INVALID_ARGUMENT, `Invalid target type '${String(type)}' in binding '${bindingName}' for action '${actionRef}': expected 'local' or 'remote'`);
+}
+/**
+ * 校验并深拷贝冻结动作绑定配置快照。
+ */
+export function validateActionBindings(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new ActionDockError(INVALID_ARGUMENT, "Invalid action bindings: expected a JSON object");
+    }
+    const result = Object.create(null);
+    for (const rawRef of Object.keys(value)) {
+        if (!Object.prototype.hasOwnProperty.call(value, rawRef)) {
+            continue;
+        }
+        const canonicalRef = validateCanonicalActionRef(rawRef);
+        const rawGroup = value[rawRef];
+        if (rawGroup === null || typeof rawGroup !== "object" || Array.isArray(rawGroup)) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Invalid bindings group for action '${canonicalRef}': expected a JSON object`);
+        }
+        const group = Object.create(null);
+        for (const rawBindingName of Object.keys(rawGroup)) {
+            if (!Object.prototype.hasOwnProperty.call(rawGroup, rawBindingName)) {
+                continue;
+            }
+            const bindingName = validateBindingName(rawBindingName, canonicalRef);
+            const rawTarget = rawGroup[rawBindingName];
+            const target = validateBindingTarget(rawTarget, bindingName, canonicalRef);
+            group[bindingName] = target;
+        }
+        result[canonicalRef] = Object.freeze(group);
+    }
+    return Object.freeze(result);
+}
+/**
+ * 从调用方项目目录读取动作绑定配置。
+ * 若文件不存在则返回空冻结映射，其余 IO 或 JSON 异常统一转换为 ActionDockError 透传。
+ */
+export function loadActionBindings(projectRoot) {
+    if (typeof projectRoot !== "string" || projectRoot.length === 0) {
+        throw new ActionDockError(INVALID_ARGUMENT, "Invalid projectRoot: must be a non-empty string");
+    }
+    const filePath = join(projectRoot, BINDINGS_DIR_NAME, BINDINGS_FILE_NAME);
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        if (err?.code === "ENOENT") {
+            return EMPTY_ACTION_BINDINGS;
+        }
+        throw new ActionDockError(INVALID_ARGUMENT, `Failed to read action bindings at ${filePath}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ActionDockError(INVALID_JSON, `Failed to parse action bindings JSON at ${filePath}: ${err.message}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid action bindings format in ${filePath}: expected a JSON object`);
+    }
+    const rootKeys = Object.keys(parsed);
+    for (const key of rootKeys) {
+        if (!Object.prototype.hasOwnProperty.call(parsed, key)) {
+            continue;
+        }
+        if (key === "bindings") {
+            continue;
+        }
+        if (key === "schemaVersion") {
+            const v = parsed.schemaVersion;
+            if (v !== 1) {
+                throw new ActionDockError(INVALID_ARGUMENT, `Invalid schemaVersion '${String(v)}' in ${filePath}: only schemaVersion 1 is supported`);
+            }
+            continue;
+        }
+        throw new ActionDockError(INVALID_ARGUMENT, `Unknown property '${key}' in ${filePath}: only 'bindings' is allowed`);
+    }
+    if (!Object.prototype.hasOwnProperty.call(parsed, "bindings")) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Missing 'bindings' property in ${filePath}`);
+    }
+    return validateActionBindings(parsed.bindings);
+}
+/**
+ * 解析目标动作引用在当前项目中的具体绑定。
+ * 未显式传入 binding 则仅检索 default；若 default 亦不存在则返回 undefined。
+ * 若显式传入的 binding 不存在，抛出 ActionDockError(NOT_FOUND) 并在 details 中携带 action 与 binding。
+ */
+export function resolveActionBinding(bindings, ref, binding) {
+    const canonicalRef = validateCanonicalActionRef(ref);
+    const group = bindings &&
+        typeof bindings === "object" &&
+        Object.prototype.hasOwnProperty.call(bindings, canonicalRef)
+        ? bindings[canonicalRef]
+        : undefined;
+    if (binding === undefined) {
+        if (!group) {
+            return undefined;
+        }
+        return Object.prototype.hasOwnProperty.call(group, "default")
+            ? group["default"]
+            : undefined;
+    }
+    if (!group || !Object.prototype.hasOwnProperty.call(group, binding)) {
+        throw new ActionDockError(NOT_FOUND, `Action binding '${binding}' not found for action '${canonicalRef}'`, { action: canonicalRef, binding });
+    }
+    return group[binding];
+}
+/**
+ * 检测指定动作是否存在任意 remote 类型的命名绑定。
+ * 仅做完全限定精确匹配，供构建工具快速识别可外置的跨节点依赖。
+ */
+export function hasRemoteActionBinding(bindings, ref) {
+    const canonicalRef = validateCanonicalActionRef(ref);
+    if (!bindings || typeof bindings !== "object") {
+        return false;
+    }
+    if (!Object.prototype.hasOwnProperty.call(bindings, canonicalRef)) {
+        return false;
+    }
+    const group = bindings[canonicalRef];
+    if (!group || typeof group !== "object") {
+        return false;
+    }
+    for (const name of Object.keys(group)) {
+        if (!Object.prototype.hasOwnProperty.call(group, name)) {
+            continue;
+        }
+        const target = group[name];
+        if (target?.type === "remote") {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/invocation/policy.d.ts

@@ -1,5 +1,7 @@
 import { type ErrorCode } from "../errors.js";
 import type { PackageGraph } from "../catalog/graph.js";
+/** 动作调用栈键的单一事实源，执行目标作用域不占用额外深度。 */
+export declare function createActionCallKey(actionId: string, packageId?: string, targetScope?: string): string;
 /**
  * 调用治理策略初始化选项。
  */
@@ -32,6 +34,8 @@ export interface CallerActionInfo {
 export interface TargetActionInfo {
     packageId: string;
     actionId: string;
+    /** 跨执行目标时，即使同名包也必须显式声明依赖。 */
+    requiresExplicitUses?: boolean;
 }
 /**
  * 调用治理策略错误描述。
@@ -127,7 +131,7 @@ export declare class InvocationPolicy {
      * @param currentPackageId 当前执行发起方包标识
      * @returns 包含规范化 callKey 与可选错误的结构体
      */
-    checkCycle(callStack: readonly string[], targetActionId: string, targetPackageId?: string, currentPackageId?: string): CycleCheckResult;
+    checkCycle(callStack: readonly string[], targetActionId: string, targetPackageId?: string, currentPackageId?: string, targetScope?: string): CycleCheckResult;
     /**
      * 并发活跃子任务配额检查（Sub-Run Quota Policy）。
      *

package/dist/invocation/policy.js

@@ -1,5 +1,10 @@
 import { ACTION_CALL_CYCLE, ACTION_SUBRUN_LIMIT, UNDECLARED_ACTION_DEPENDENCY, ActionDockError, } from "../errors.js";
 import { isUsesDeclared } from "../catalog/graph.js";
+/** 动作调用栈键的单一事实源，执行目标作用域不占用额外深度。 */
+export function createActionCallKey(actionId, packageId, targetScope) {
+    const logicalKey = packageId ? `${packageId}/${actionId}` : actionId;
+    return targetScope ? `${targetScope}::${logicalKey}` : logicalKey;
+}
 /**
  * 全局统一调用治理策略服务（InvocationPolicy）。
  *
@@ -77,7 +82,7 @@ export class InvocationPolicy {
      */
     checkUsesAuthorization(caller, target, graph) {
         // 同包调用完全自由开放，不作限制
-        if (!caller.packageId || !target.packageId || caller.packageId === target.packageId) {
+        if (!target.requiresExplicitUses && (!caller.packageId || !target.packageId || caller.packageId === target.packageId)) {
             return undefined;
         }
         const targetRef = `${target.packageId}/${target.actionId}`;
@@ -89,9 +94,12 @@ export class InvocationPolicy {
             callerNode?.manifest?.actions?.[shortActionId]?.uses ||
             callerNode?.manifest?.actions?.[caller.actionId]?.uses ||
             [];
-        const isAllowed = graph
-            ? graph.canCascadeCall(caller.packageId, caller.actionId, target.packageId, target.actionId)
-            : usesList.some((u) => isUsesDeclared(u, target.packageId, target.actionId));
+        const isAllowed = target.requiresExplicitUses
+            ? usesList.some((u) => isUsesDeclared(u, target.packageId, target.actionId) ||
+                (caller.packageId === target.packageId && u === target.actionId))
+            : graph && caller.declaredUses === undefined
+                ? graph.canCascadeCall(caller.packageId, caller.actionId, target.packageId, target.actionId)
+                : usesList.some((u) => isUsesDeclared(u, target.packageId, target.actionId));
         if (!isAllowed) {
             const hint = `Hint: Add '${targetRef}' to the 'uses' array of action '${caller.actionId}' in actiondock.json, then run 'ad validate'.`;
             return {
@@ -144,11 +152,10 @@ export class InvocationPolicy {
      * @param currentPackageId 当前执行发起方包标识
      * @returns 包含规范化 callKey 与可选错误的结构体
      */
-    checkCycle(callStack, targetActionId, targetPackageId, currentPackageId) {
-        const isExternal = Boolean(targetPackageId && currentPackageId && targetPackageId !== currentPackageId);
-        const callKey = targetPackageId
-            ? `${targetPackageId}/${targetActionId}`
-            : targetActionId;
+    checkCycle(callStack, targetActionId, targetPackageId, currentPackageId, targetScope) {
+        const isExternal = Boolean(targetScope ||
+            (targetPackageId && currentPackageId && targetPackageId !== currentPackageId));
+        const callKey = createActionCallKey(targetActionId, targetPackageId, targetScope);
         let hasCycle = false;
         if (isExternal) {
             hasCycle = callStack.includes(callKey);

package/dist/invocation/remote.d.ts

@@ -0,0 +1,40 @@
+import type { ActionContract, ActionRef, Logger } from "@actiondock/sdk";
+import type { RemoteServiceOptions } from "../service/types.js";
+import type { InvocationContext } from "./types.js";
+/**
+ * 远端调用绑定与 Profile 元信息。
+ */
+export interface RemoteInvocationMetadata {
+    /** 宿主绑定的逻辑标识 */
+    binding: string;
+    /** 目标 Profile 标识 */
+    profile: string;
+}
+/**
+ * 安全的远端嵌套调用适配执行器。
+ *
+ * 遵循原则：
+ * - 目标 target 由 Host 预先根据 profile 解析并冻结传入，不自作路由决断。
+ * - 连接缓存按 target 对象身份隔离复用，并在 close() 时全量释放。
+ * - 严格防范凭证与本地私有上下文泄漏，仅透传必要控制字段。
+ * - 取消与清理全链路有界且透传远端 runs.cancel，严禁静默吞没未确认终态。
+ */
+export declare class RemoteInvocationExecutor {
+    private readonly logger?;
+    private readonly services;
+    private isClosed;
+    private readonly closeController;
+    private readonly pending;
+    constructor(options?: {
+        logger?: Logger;
+    });
+    /**
+     * 触发执行远端 Action 动作。
+     */
+    invoke(target: RemoteServiceOptions, ref: ActionRef | string, input: unknown, context: InvocationContext, metadata: RemoteInvocationMetadata, expectedContract?: ActionContract): Promise<unknown>;
+    private execute;
+    /**
+     * 关闭所有持有的远端服务连接并释放关联资源，对外拒绝后续调用。
+     */
+    close(): Promise<void>;
+}