@actiondock/core 2.7.0 → 2.8.0

package/dist/invocation/policy.d.ts

@@ -0,0 +1,157 @@
+import { type ErrorCode } from "../errors.js";
+import type { PackageGraph } from "../catalog/graph.js";
+/**
+ * 调用治理策略初始化选项。
+ */
+export interface InvocationPolicyOptions {
+    /** 最大调用嵌套深度限制（默认 16） */
+    maxCallDepth?: number;
+    /** 单个根任务下最大并发活跃子任务数（默认 64） */
+    maxSubRuns?: number;
+}
+/**
+ * 根调用可见性上下文。
+ */
+export interface RootVisibilityContext {
+    /** 宿主公开暴露的包标识集合 */
+    hostPublicPackageIds: ReadonlySet<string>;
+    /** 包依赖拓扑图 */
+    graph?: PackageGraph;
+}
+/**
+ * 调用方声明规范契约。
+ */
+export interface CallerActionInfo {
+    packageId: string;
+    actionId: string;
+    declaredUses?: string[];
+}
+/**
+ * 目标 Action 规范契约。
+ */
+export interface TargetActionInfo {
+    packageId: string;
+    actionId: string;
+}
+/**
+ * 调用治理策略错误描述。
+ */
+export interface PolicyError {
+    code: ErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * 环路检测结果。
+ */
+export interface CycleCheckResult {
+    callKey: string;
+    error?: PolicyError;
+}
+/**
+ * 全局统一调用治理策略服务（InvocationPolicy）。
+ *
+ * 铁律 5 单一事实源：统一负责 root visibility、caller -> callee authorization、
+ * uses 检查、max call depth、cycle detection、subrun quota 与 lineage policy。
+ * 彻底消除 Host、ExecutionService 与 ActionRunner 中分散重复的检查逻辑。
+ */
+export declare class InvocationPolicy {
+    readonly maxCallDepth: number;
+    readonly maxSubRuns: number;
+    private readonly activeSubRunsPerRoot;
+    private visibilityContext?;
+    constructor(options?: InvocationPolicyOptions);
+    /**
+     * 设置路由可见性上下文。
+     */
+    setVisibilityContext(context?: RootVisibilityContext): void;
+    /**
+     * 严格断言根调用可见性（Root Visibility Assertion）。
+     * 若不可见则抛出 ActionDockError(UNDECLARED_ACTION_DEPENDENCY, ...)。
+     */
+    assertRootVisibility(resolved: {
+        package: {
+            id: string;
+        };
+        ref: {
+            actionId: string;
+        };
+    }, context?: RootVisibilityContext): void;
+    /**
+     * 根调用可见性判定与鉴权（Root Visibility Policy）。
+     *
+     * 判定规则：
+     * - 宿主公开注册的包（直接依赖包或显式声明包）允许根调用；
+     * - 传递依赖包必须经由可见 Playbook 委托授权，否则拦截并返回 UNDECLARED_ACTION_DEPENDENCY。
+     *
+     * @param targetPackageId 目标包标识
+     * @param targetActionId 目标 Action 标识
+     * @param context 路由可见性上下文
+     * @returns 若拦截返回标准 RuntimeError，通过则返回 undefined
+     */
+    checkRootVisibility(targetPackageId: string, targetActionId: string, context: RootVisibilityContext): PolicyError | undefined;
+    /**
+     * 调用方至目标动作 uses 依赖声明授权校验（Caller -> Callee Authorization & Uses Policy）。
+     *
+     * 判定规则：
+     * - 同包内部 Action 互调自然合法，豁免 uses 声明；
+     * - 跨包调用必须在调用方 Action 的 uses 声明列表中显式声明目标（完全限定名、通配符或包名），
+     *   或经由 PackageGraph.canCascadeCall 裁决通过；未声明直接拦截。
+     *
+     * @param caller 调用方 Action 标识与声明上下文
+     * @param target 目标 Action 标识
+     * @param graph 可选的包依赖拓扑图
+     * @returns 若鉴权未通过返回标准 RuntimeError，通过则返回 undefined
+     */
+    checkUsesAuthorization(caller: CallerActionInfo, target: TargetActionInfo, graph?: PackageGraph): PolicyError | undefined;
+    /**
+     * 调用嵌套最大深度限制校验（Max Call Depth Policy）。
+     *
+     * 超限时返回标准 ACTION_CALL_CYCLE 错误。
+     *
+     * @param callStack 当前已累积的调用栈切片
+     * @param targetActionId 欲调用的目标 Action 标识
+     * @param maxDepthOverride 临时执行覆盖的最大深度限制
+     * @returns 超限错误或 undefined
+     */
+    checkCallDepth(callStack: readonly string[], targetActionId: string, maxDepthOverride?: number): PolicyError | undefined;
+    /**
+     * 调用链环路死锁检测（Cycle Detection Policy）。
+     *
+     * 计算目标调用键并在历史调用栈中执行检测，杜绝 A -> B -> A 形成死锁。
+     * 命中环路时返回 ACTION_CALL_CYCLE 错误。
+     *
+     * @param callStack 当前已累积的调用栈切片
+     * @param targetActionId 欲调用的目标 Action 标识
+     * @param targetPackageId 目标 Action 所属包标识
+     * @param currentPackageId 当前执行发起方包标识
+     * @returns 包含规范化 callKey 与可选错误的结构体
+     */
+    checkCycle(callStack: readonly string[], targetActionId: string, targetPackageId?: string, currentPackageId?: string): CycleCheckResult;
+    /**
+     * 并发活跃子任务配额检查（Sub-Run Quota Policy）。
+     *
+     * 针对同源 rootRunId 限制派生的并发子任务上限，防止资源耗尽。
+     *
+     * @param rootRunId 根运行标识符
+     * @returns 超限错误或 undefined
+     */
+    checkSubRunQuota(rootRunId: string): PolicyError | undefined;
+    /**
+     * 申请子任务并发配额槽位。
+     *
+     * @param rootRunId 根运行标识符
+     * @returns 是否成功获取槽位（若已达上限返回 false）
+     */
+    acquireSubRun(rootRunId: string): boolean;
+    /**
+     * 释放已申请的子任务并发配额槽位。
+     *
+     * @param rootRunId 根运行标识符
+     */
+    releaseSubRun(rootRunId: string): void;
+    /**
+     * 获取指定根运行当前的活跃并发子任务计数。
+     */
+    getActiveSubRuns(rootRunId: string): number;
+}

package/dist/invocation/policy.js

@@ -0,0 +1,231 @@
+import { ACTION_CALL_CYCLE, ACTION_SUBRUN_LIMIT, UNDECLARED_ACTION_DEPENDENCY, ActionDockError, } from "../errors.js";
+import { isUsesDeclared } from "../catalog/graph.js";
+/**
+ * 全局统一调用治理策略服务（InvocationPolicy）。
+ *
+ * 铁律 5 单一事实源：统一负责 root visibility、caller -> callee authorization、
+ * uses 检查、max call depth、cycle detection、subrun quota 与 lineage policy。
+ * 彻底消除 Host、ExecutionService 与 ActionRunner 中分散重复的检查逻辑。
+ */
+export class InvocationPolicy {
+    maxCallDepth;
+    maxSubRuns;
+    activeSubRunsPerRoot = new Map();
+    visibilityContext;
+    constructor(options = {}) {
+        this.maxCallDepth = options.maxCallDepth ?? 16;
+        this.maxSubRuns = options.maxSubRuns ?? 64;
+    }
+    /**
+     * 设置路由可见性上下文。
+     */
+    setVisibilityContext(context) {
+        this.visibilityContext = context;
+    }
+    /**
+     * 严格断言根调用可见性（Root Visibility Assertion）。
+     * 若不可见则抛出 ActionDockError(UNDECLARED_ACTION_DEPENDENCY, ...)。
+     */
+    assertRootVisibility(resolved, context) {
+        const ctx = context ?? this.visibilityContext;
+        if (!ctx) {
+            return;
+        }
+        const error = this.checkRootVisibility(resolved.package.id, resolved.ref.actionId, ctx);
+        if (error) {
+            throw new ActionDockError(error.code, error.message, error.details);
+        }
+    }
+    /**
+     * 根调用可见性判定与鉴权（Root Visibility Policy）。
+     *
+     * 判定规则：
+     * - 宿主公开注册的包（直接依赖包或显式声明包）允许根调用；
+     * - 传递依赖包必须经由可见 Playbook 委托授权，否则拦截并返回 UNDECLARED_ACTION_DEPENDENCY。
+     *
+     * @param targetPackageId 目标包标识
+     * @param targetActionId 目标 Action 标识
+     * @param context 路由可见性上下文
+     * @returns 若拦截返回标准 RuntimeError，通过则返回 undefined
+     */
+    checkRootVisibility(targetPackageId, targetActionId, context) {
+        const isPublic = context.hostPublicPackageIds.has(targetPackageId);
+        if (isPublic) {
+            return undefined;
+        }
+        if (context.graph && !context.graph.canRootCall(targetPackageId, targetActionId)) {
+            return {
+                code: UNDECLARED_ACTION_DEPENDENCY,
+                message: `Root call to action '${targetPackageId}/${targetActionId}' is not allowed: package '${targetPackageId}' is not declared as a direct dependency in actiondock.json and is not delegated by a visible playbook`,
+                details: { target: `${targetPackageId}/${targetActionId}` },
+            };
+        }
+        return undefined;
+    }
+    /**
+     * 调用方至目标动作 uses 依赖声明授权校验（Caller -> Callee Authorization & Uses Policy）。
+     *
+     * 判定规则：
+     * - 同包内部 Action 互调自然合法，豁免 uses 声明；
+     * - 跨包调用必须在调用方 Action 的 uses 声明列表中显式声明目标（完全限定名、通配符或包名），
+     *   或经由 PackageGraph.canCascadeCall 裁决通过；未声明直接拦截。
+     *
+     * @param caller 调用方 Action 标识与声明上下文
+     * @param target 目标 Action 标识
+     * @param graph 可选的包依赖拓扑图
+     * @returns 若鉴权未通过返回标准 RuntimeError，通过则返回 undefined
+     */
+    checkUsesAuthorization(caller, target, graph) {
+        // 同包调用完全自由开放，不作限制
+        if (!caller.packageId || !target.packageId || caller.packageId === target.packageId) {
+            return undefined;
+        }
+        const targetRef = `${target.packageId}/${target.actionId}`;
+        const callerNode = graph?.getNode(caller.packageId);
+        const shortActionId = caller.actionId.includes("/")
+            ? caller.actionId.split("/").pop()
+            : caller.actionId;
+        const usesList = caller.declaredUses ||
+            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));
+        if (!isAllowed) {
+            return {
+                code: UNDECLARED_ACTION_DEPENDENCY,
+                message: `Undeclared cross-package dependency: Action '${caller.packageId}/${caller.actionId}' does not declare dependency on '${targetRef}' in 'uses'`,
+                details: {
+                    caller: `${caller.packageId}/${caller.actionId}`,
+                    target: targetRef,
+                    declaredUses: usesList,
+                },
+            };
+        }
+        return undefined;
+    }
+    /**
+     * 调用嵌套最大深度限制校验（Max Call Depth Policy）。
+     *
+     * 超限时返回标准 ACTION_CALL_CYCLE 错误。
+     *
+     * @param callStack 当前已累积的调用栈切片
+     * @param targetActionId 欲调用的目标 Action 标识
+     * @param maxDepthOverride 临时执行覆盖的最大深度限制
+     * @returns 超限错误或 undefined
+     */
+    checkCallDepth(callStack, targetActionId, maxDepthOverride) {
+        const limit = maxDepthOverride ?? this.maxCallDepth;
+        if (callStack.length >= limit) {
+            return {
+                code: ACTION_CALL_CYCLE,
+                message: `Maximum call depth of ${limit} exceeded: ${callStack.join(" -> ")} -> ${targetActionId}`,
+                details: {
+                    reason: "depth_exceeded",
+                    maxDepth: limit,
+                    callStack: [...callStack],
+                },
+            };
+        }
+        return undefined;
+    }
+    /**
+     * 调用链环路死锁检测（Cycle Detection Policy）。
+     *
+     * 计算目标调用键并在历史调用栈中执行检测，杜绝 A -> B -> A 形成死锁。
+     * 命中环路时返回 ACTION_CALL_CYCLE 错误。
+     *
+     * @param callStack 当前已累积的调用栈切片
+     * @param targetActionId 欲调用的目标 Action 标识
+     * @param targetPackageId 目标 Action 所属包标识
+     * @param currentPackageId 当前执行发起方包标识
+     * @returns 包含规范化 callKey 与可选错误的结构体
+     */
+    checkCycle(callStack, targetActionId, targetPackageId, currentPackageId) {
+        const isExternal = Boolean(targetPackageId && currentPackageId && targetPackageId !== currentPackageId);
+        const callKey = targetPackageId
+            ? `${targetPackageId}/${targetActionId}`
+            : targetActionId;
+        let hasCycle = false;
+        if (isExternal) {
+            hasCycle = callStack.includes(callKey);
+        }
+        else {
+            hasCycle =
+                callStack.includes(callKey) ||
+                    callStack.includes(targetActionId) ||
+                    (targetPackageId ? callStack.includes(`${targetPackageId}/${targetActionId}`) : false);
+        }
+        if (hasCycle) {
+            return {
+                callKey,
+                error: {
+                    code: ACTION_CALL_CYCLE,
+                    message: `Cycle detected in action invocation: ${callStack.join(" -> ")} -> ${callKey}`,
+                    details: {
+                        reason: "cycle_detected",
+                        callStack: [...callStack],
+                        target: callKey,
+                    },
+                },
+            };
+        }
+        return { callKey };
+    }
+    /**
+     * 并发活跃子任务配额检查（Sub-Run Quota Policy）。
+     *
+     * 针对同源 rootRunId 限制派生的并发子任务上限，防止资源耗尽。
+     *
+     * @param rootRunId 根运行标识符
+     * @returns 超限错误或 undefined
+     */
+    checkSubRunQuota(rootRunId) {
+        const current = this.activeSubRunsPerRoot.get(rootRunId) || 0;
+        if (current >= this.maxSubRuns) {
+            return {
+                code: ACTION_SUBRUN_LIMIT,
+                message: `Maximum concurrent sub-runs (${this.maxSubRuns}) reached for root run '${rootRunId}'`,
+                details: {
+                    limit: this.maxSubRuns,
+                },
+            };
+        }
+        return undefined;
+    }
+    /**
+     * 申请子任务并发配额槽位。
+     *
+     * @param rootRunId 根运行标识符
+     * @returns 是否成功获取槽位（若已达上限返回 false）
+     */
+    acquireSubRun(rootRunId) {
+        const current = this.activeSubRunsPerRoot.get(rootRunId) || 0;
+        if (current >= this.maxSubRuns) {
+            return false;
+        }
+        this.activeSubRunsPerRoot.set(rootRunId, current + 1);
+        return true;
+    }
+    /**
+     * 释放已申请的子任务并发配额槽位。
+     *
+     * @param rootRunId 根运行标识符
+     */
+    releaseSubRun(rootRunId) {
+        const current = this.activeSubRunsPerRoot.get(rootRunId) || 1;
+        if (current <= 1) {
+            this.activeSubRunsPerRoot.delete(rootRunId);
+        }
+        else {
+            this.activeSubRunsPerRoot.set(rootRunId, current - 1);
+        }
+    }
+    /**
+     * 获取指定根运行当前的活跃并发子任务计数。
+     */
+    getActiveSubRuns(rootRunId) {
+        return this.activeSubRunsPerRoot.get(rootRunId) || 0;
+    }
+}

package/dist/invocation/types.d.ts

@@ -0,0 +1,172 @@
+import type { ActionDefinition, ActionRef, Logger, ProcessAPI, ProgressReporter } from "@actiondock/sdk";
+import type { ProcessOwner } from "../process/index.js";
+import { createPackageIdentity, type PackageIdentity } from "../runtime/identity.js";
+export { createPackageIdentity };
+export type { PackageIdentity };
+export type { RunOptions } from "../service/types.js";
+/**
+ * 构造默认进程归属所有者（ProcessOwner）的单一事实源工厂。
+ *
+ * 兜底语义：租户与主体标识缺失时回退 "default"，包实例与代次标识缺失时回退
+ * 调用方提供的兜底值；全部五处默认 Owner 构造点（invocation、runner、runtime
+ * 上下文与进程执行器）必须统一经由本工厂，禁止散落字面量拷贝。
+ */
+export declare function createDefaultProcessOwner(options?: {
+    /** 租户标识，缺省回退 "default" */
+    tenantId?: string;
+    /** 主体标识，缺省回退 "default" */
+    principalId?: string;
+    /** 包物理实例标识兜底值，缺省回退 "default" */
+    packageInstanceId?: string;
+    /** 快照代次标识兜底值，缺省回退 "default" */
+    generationId?: string;
+}): ProcessOwner;
+/**
+ * 内部调用方身份凭证（InvocationCaller）。
+ */
+export interface InvocationCaller {
+    /** 调用方所在包标识 */
+    readonly packageId: string;
+    /** 调用方 Action 标识 */
+    readonly actionId: string;
+    /** 调用方运行 ID */
+    readonly runId?: string;
+    /** 调用方声明的 uses 列表 */
+    readonly declaredUses?: string[];
+}
+/**
+ * 内部调用上下文（InvocationContext）。
+ * 贯穿 Host -> Resolution -> PackageRuntime -> ExecutionService 的内部调用链路上下文。
+ */
+export interface InvocationContext {
+    /** 本次执行的全局唯一运行标识 */
+    readonly runId: string;
+    /** 根运行标识（调用链起点） */
+    readonly rootRunId: string;
+    /** 直接父运行标识（嵌套子调用时关联） */
+    readonly parentRunId?: string;
+    /** 调用方上下文（若为嵌套/跨包调用） */
+    readonly caller?: InvocationCaller;
+    /** 调用栈数组快照（用于环路检测与调用深度限制） */
+    readonly callStack: readonly string[];
+    /** 目标包物理与快照身份标识 */
+    readonly package: PackageIdentity;
+    /** 取消信号 */
+    readonly signal: AbortSignal;
+    /** 超时毫秒数 */
+    readonly timeoutMs?: number;
+    /** 配置覆盖项 */
+    readonly config?: Record<string, unknown>;
+    /** 幂等请求标识 */
+    readonly requestId?: string;
+    /** 租户标识 */
+    readonly tenantId?: string;
+    /** 主体标识 */
+    readonly principalId?: string;
+    /** 执行宿主会话标识 */
+    readonly hostSessionId?: string;
+    /** 最大调用深度覆盖 */
+    readonly maxCallDepth?: number;
+    /** 日志记录器 */
+    readonly logger?: Logger;
+    /** 进度报告器 */
+    readonly progress?: ProgressReporter;
+    /** 进程执行器 */
+    readonly process?: ProcessAPI;
+    /** 进程属主身份 */
+    readonly owner?: ProcessOwner;
+}
+/**
+ * 内部调用上下文选项契约。
+ * 强制要求提供确定的 PackageIdentity，禁止隐式兜底 mock 默认包。
+ */
+export interface CreateInvocationContextOptions extends Omit<Partial<InvocationContext>, "package"> {
+    /** 目标包物理与快照身份标识（必填单一事实源） */
+    package: PackageIdentity;
+}
+/**
+ * 构造合法的内部调用上下文（InvocationContext）。
+ * 供测试或内部直接调用执行服务时便捷装配上下文凭据。
+ */
+export declare function createInvocationContext(options: CreateInvocationContextOptions): InvocationContext;
+/**
+ * 构造受信任的根调用上下文选项。
+ */
+export interface CreateRootInvocationContextOptions {
+    /** 目标包物理与快照身份标识（必填单一事实源） */
+    targetPackage: PackageIdentity;
+    /** 可选的初始调用栈（根调用通常为 [rootKey]） */
+    callStack?: readonly string[];
+    /** 外部传入的 AbortSignal 取消信号 */
+    signal?: AbortSignal;
+    /** 最大超时时间（毫秒） */
+    timeoutMs?: number;
+    /** 执行级临时配置覆盖字典 */
+    config?: Record<string, unknown>;
+    /** 幂等请求标识 */
+    requestId?: string;
+    /** 执行宿主会话标识 */
+    hostSessionId?: string;
+    /** 最大调用嵌套深度限制 */
+    maxCallDepth?: number;
+    /** 外部进程执行器注入 */
+    process?: ProcessAPI;
+    /** 租户标识 */
+    tenantId?: string;
+    /** 主体标识 */
+    principalId?: string;
+    /** 日志记录器 */
+    logger?: Logger;
+    /** 进度报告器 */
+    progress?: ProgressReporter;
+    /** 显式执行归属所有者契约 */
+    owner?: ProcessOwner;
+}
+/**
+ * 构造合法的受信任根调用上下文（Root InvocationContext）。
+ * 在 Host 服务边界装配，严格保证无父级调用血缘（parentRunId 为 undefined），
+ * 根运行 ID 等同于自身运行 ID，且仅透传受信任参数。
+ *
+ * 实现委托 createInvocationContext 单一事实源：不传入 runId/rootRunId/parentRunId/caller，
+ * 由公共构造逻辑兜底生成 runId 并令 rootRunId 收敛为自身 runId；随后显式覆写
+ * parentRunId 与 caller 为 undefined，并按根调用契约挑选字段，保持无血缘血缘字段的键序不变。
+ */
+export declare function createRootInvocationContext(options: CreateRootInvocationContextOptions): InvocationContext;
+/**
+ * Action 执行上下文（ActionExecutionContext）。
+ * ActionRunner 启动单次 Action 执行时内部装配的完整上下文状态。
+ */
+export interface ActionExecutionContext {
+    /** 运行 ID */
+    readonly runId: string;
+    /** 根运行 ID */
+    readonly rootRunId: string;
+    /** 父运行 ID */
+    readonly parentRunId?: string;
+    /** 当前执行所属包标识 */
+    readonly packageIdentity: PackageIdentity;
+    /** 目标 Action 标识 */
+    readonly targetActionId: string;
+    /** 输入数据 */
+    readonly input: unknown;
+    /** 目标 Action 定义（若已解析就绪） */
+    readonly action?: ActionDefinition;
+    /** 调用栈数组快照 */
+    readonly callStack: readonly string[];
+    /** 取消中断控制器 */
+    readonly controller: AbortController;
+    /** 执行开始时间戳 */
+    readonly startedAt: string;
+    /** 生效的进程执行器 */
+    readonly effectiveProcess?: ProcessAPI;
+    /** 进程属主信息 */
+    readonly owner: ProcessOwner;
+    /** 日志记录器 */
+    readonly logger?: Logger;
+    /** 进度报告器 */
+    readonly progress?: ProgressReporter;
+    /** 配置覆盖项 */
+    readonly configOverrides?: Record<string, unknown>;
+    /** 嵌套子调用委托函数 */
+    readonly actionInvoker?: (childAction: ActionRef | string, childInput: unknown, callerRunId?: string) => Promise<unknown>;
+}

package/dist/invocation/types.js

@@ -0,0 +1,97 @@
+import { createPackageIdentity } from "../runtime/identity.js";
+export { createPackageIdentity };
+/**
+ * 构造默认进程归属所有者（ProcessOwner）的单一事实源工厂。
+ *
+ * 兜底语义：租户与主体标识缺失时回退 "default"，包实例与代次标识缺失时回退
+ * 调用方提供的兜底值；全部五处默认 Owner 构造点（invocation、runner、runtime
+ * 上下文与进程执行器）必须统一经由本工厂，禁止散落字面量拷贝。
+ */
+export function createDefaultProcessOwner(options) {
+    return {
+        tenantId: options?.tenantId || "default",
+        principalId: options?.principalId || "default",
+        packageInstanceId: options?.packageInstanceId || "default",
+        generationId: options?.generationId || "default",
+    };
+}
+/**
+ * 构造合法的内部调用上下文（InvocationContext）。
+ * 供测试或内部直接调用执行服务时便捷装配上下文凭据。
+ */
+export function createInvocationContext(options) {
+    const runId = options.runId ?? crypto.randomUUID();
+    const rootRunId = options.rootRunId ?? runId;
+    const pkg = options.package;
+    return {
+        runId,
+        rootRunId,
+        parentRunId: options.parentRunId,
+        caller: options.caller,
+        callStack: options.callStack ? [...options.callStack] : [],
+        package: pkg,
+        signal: options.signal ?? new AbortController().signal,
+        timeoutMs: options.timeoutMs,
+        config: options.config,
+        requestId: options.requestId,
+        tenantId: options.tenantId,
+        principalId: options.principalId,
+        hostSessionId: options.hostSessionId,
+        maxCallDepth: options.maxCallDepth,
+        logger: options.logger,
+        progress: options.progress,
+        process: options.process,
+        owner: options.owner ??
+            createDefaultProcessOwner({
+                tenantId: options.tenantId,
+                principalId: options.principalId,
+                packageInstanceId: pkg.instanceId,
+                generationId: pkg.generation,
+            }),
+    };
+}
+/**
+ * 构造合法的受信任根调用上下文（Root InvocationContext）。
+ * 在 Host 服务边界装配，严格保证无父级调用血缘（parentRunId 为 undefined），
+ * 根运行 ID 等同于自身运行 ID，且仅透传受信任参数。
+ *
+ * 实现委托 createInvocationContext 单一事实源：不传入 runId/rootRunId/parentRunId/caller，
+ * 由公共构造逻辑兜底生成 runId 并令 rootRunId 收敛为自身 runId；随后显式覆写
+ * parentRunId 与 caller 为 undefined，并按根调用契约挑选字段，保持无血缘血缘字段的键序不变。
+ */
+export function createRootInvocationContext(options) {
+    const base = createInvocationContext({
+        package: options.targetPackage,
+        callStack: options.callStack,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+        config: options.config,
+        requestId: options.requestId,
+        hostSessionId: options.hostSessionId,
+        maxCallDepth: options.maxCallDepth,
+        logger: options.logger,
+        progress: options.progress,
+        process: options.process,
+        owner: options.owner,
+        tenantId: options.tenantId,
+        principalId: options.principalId,
+    });
+    return {
+        runId: base.runId,
+        rootRunId: base.rootRunId,
+        parentRunId: undefined,
+        caller: undefined,
+        callStack: base.callStack,
+        package: base.package,
+        signal: base.signal,
+        timeoutMs: base.timeoutMs,
+        config: base.config,
+        requestId: base.requestId,
+        hostSessionId: base.hostSessionId,
+        maxCallDepth: base.maxCallDepth,
+        logger: base.logger,
+        progress: base.progress,
+        process: base.process,
+        owner: base.owner,
+    };
+}

package/dist/ipc/diagnostic.d.ts

@@ -35,14 +35,6 @@ export declare class DiagnosticForwarder {
     private truncated;
     private attachedStreams;
     constructor(options?: DiagnosticForwarderOptions);
-    /**
-     * 是否已达到上限并处于截断状态。
-     */
-    get isTruncated(): boolean;
-    /**
-     * 已成功转发的累计字节数。
-     */
-    get bytesEmitted(): number;
     /**
      * 绑定并监听可读流（如 childProcess.stdout 或 childProcess.stderr）。
      *
@@ -58,8 +50,4 @@ export declare class DiagnosticForwarder {
      * 解绑所有已连接的流。
      */
     detachAll(): void;
-    /**
-     * 重置计数器与截断标志。
-     */
-    reset(): void;
 }