@actiondock/core 2.5.1 → 2.6.0

package/dist/host/routing.d.ts

@@ -0,0 +1,92 @@
+import type { ActionRef, RuntimeError } from "@actiondock/sdk";
+import type { ActionDockApp, ActionSpec, PackageInfo, PlaybookSpec, PlaybookSummary } from "../app/types.js";
+import type { ActionPackageResolver } from "../project/resolver.js";
+/**
+ * 判定异常是否为 not-found 语义（包内确实不存在该 Action）。
+ *
+ * 遍历匹配短标识符时仅跳过此类错误；存储损坏、模块加载失败等内部错误必须向调用方透传，
+ * 严禁被吞没后伪装成 ACTION_NOT_FOUND。
+ */
+export declare function isActionNotFoundLikeError(err: any): boolean;
+/**
+ * 宽松解析引用：优先结构化解析，失败时按对象或裸短标识符回退。
+ */
+export declare function parseRefLoose(ref: ActionRef | string): ActionRef;
+/**
+ * 根调用可见性判定：非公开包且存在依赖解析器时，交由解析器委托规则裁决。
+ */
+export declare function isRootCallVisible(packageId: string, actionId: string, hostPublicPackageIds: ReadonlySet<string>, resolver?: ActionPackageResolver): boolean;
+/**
+ * 跨包短标识符歧义消解结果：唯一匹配、歧义多匹配与零匹配三态。
+ */
+export type ShortRefResolution = {
+    kind: "unique";
+    app: ActionDockApp;
+} | {
+    kind: "ambiguous";
+    candidates: string[];
+} | {
+    kind: "not_found";
+};
+/**
+ * 在全部已注册包中按短标识符解析唯一提供方。
+ *
+ * 可见性过滤遵循根调用规则（公开包直接可见；传递依赖包仅可见 Playbook 委托项）；
+ * 仅 not-found 语义错误被跳过，其余异常向调用方透传。
+ */
+export declare function resolveShortRef(apps: readonly ActionDockApp[], actionId: string, visibility: {
+    hostPublicPackageIds: ReadonlySet<string>;
+    resolver?: ActionPackageResolver;
+}): Promise<ShortRefResolution>;
+/**
+ * 按包标识构造未找到错误信息：优先透传链接包加载失败的精准诊断。
+ */
+export declare function packageNotFoundMessage(packageId: string, failedLinkedPackages: ReadonlyMap<string, {
+    path: string;
+    error: string;
+}>): string;
+/**
+ * 静态查询并聚合可见包的 Playbook 规程摘要（带包前缀限定）。
+ */
+export declare function listVisiblePlaybooks(apps: readonly ActionDockApp[], visibility: {
+    hostPublicPackageIds: ReadonlySet<string>;
+    resolver?: ActionPackageResolver;
+}): Promise<PlaybookSummary[]>;
+/**
+ * 静态查询指定 Playbook 规范：支持「包/规程」限定引用与裸短标识符两级解析。
+ * 未声明依赖的传递包、不存在的规程与空匹配分别抛出对应语义错误。
+ */
+export declare function describeVisiblePlaybook(apps: readonly ActionDockApp[], id: string, visibility: {
+    hostPublicPackageIds: ReadonlySet<string>;
+    resolver?: ActionPackageResolver;
+}): Promise<PlaybookSpec>;
+/**
+ * 聚合全部已注册包的元数据信息。
+ */
+export declare function collectPackageInfos(apps: readonly ActionDockApp[]): Promise<PackageInfo[]>;
+/**
+ * 构造失配类错误响应载荷（ACTION_NOT_FOUND / AMBIGUOUS_ACTION_REF 等）。
+ */
+export declare function buildRuntimeError(code: string, message: string, details?: Record<string, unknown>): RuntimeError;
+/**
+ * 构造短标识符歧义错误消息（供静态查询与启动执行链路复用统一文案）。
+ */
+export declare function ambiguousActionMessage(actionId: string, candidates: readonly string[]): string;
+/**
+ * 静态查询指定 Action 规范：包限定引用直查，裸短标识符跨包消歧后返回。
+ */
+export declare function describeActionAcrossApps(ref: ActionRef | string, apps: readonly ActionDockApp[], visibility: {
+    hostPublicPackageIds: ReadonlySet<string>;
+    resolver?: ActionPackageResolver;
+}, failedLinkedPackages: ReadonlyMap<string, {
+    path: string;
+    error: string;
+}>): Promise<ActionSpec>;
+/** existsSync 的可注入探测依赖（纯函数模块保持可测试性） */
+export type ExistsProbe = (path: string) => boolean;
+/**
+ * 解析宿主自动加载工程根目录：显式指定优先，其次当前进程工作目录探测。
+ */
+export declare function resolveProjectRoot(options: {
+    projectRoot?: string;
+}, detect: () => string | null, exists?: ExistsProbe): string | null;

package/dist/host/routing.js

@@ -0,0 +1,238 @@
+import { existsSync } from "node:fs";
+import { ActionResolver } from "../catalog/action-resolver.js";
+/**
+ * 判定异常是否为 not-found 语义（包内确实不存在该 Action）。
+ *
+ * 遍历匹配短标识符时仅跳过此类错误；存储损坏、模块加载失败等内部错误必须向调用方透传，
+ * 严禁被吞没后伪装成 ACTION_NOT_FOUND。
+ */
+export function isActionNotFoundLikeError(err) {
+    if (!err) {
+        return false;
+    }
+    if (err.code === "ACTION_NOT_FOUND" || err.code === "NOT_FOUND") {
+        return true;
+    }
+    const message = typeof err.message === "string" ? err.message : String(err);
+    return (message.startsWith("ACTION_NOT_FOUND:") ||
+        /Action '[^']*' not found in package/.test(message));
+}
+/**
+ * 宽松解析引用：优先结构化解析，失败时按对象或裸短标识符回退。
+ */
+export function parseRefLoose(ref) {
+    try {
+        return ActionResolver.parseRef(ref);
+    }
+    catch {
+        return typeof ref === "object" ? ref : { actionId: ref };
+    }
+}
+/**
+ * 根调用可见性判定：非公开包且存在依赖解析器时，交由解析器委托规则裁决。
+ */
+export function isRootCallVisible(packageId, actionId, hostPublicPackageIds, resolver) {
+    const isPublic = hostPublicPackageIds.has(packageId);
+    if (isPublic) {
+        return true;
+    }
+    if (resolver && !resolver.canRootCall(packageId, actionId)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * 在全部已注册包中按短标识符解析唯一提供方。
+ *
+ * 可见性过滤遵循根调用规则（公开包直接可见；传递依赖包仅可见 Playbook 委托项）；
+ * 仅 not-found 语义错误被跳过，其余异常向调用方透传。
+ */
+export async function resolveShortRef(apps, actionId, visibility) {
+    const matches = [];
+    for (const app of apps) {
+        try {
+            if (!isRootCallVisible(app.packageId, actionId, visibility.hostPublicPackageIds, visibility.resolver)) {
+                continue;
+            }
+            await app.describeAction(actionId);
+            matches.push(app);
+        }
+        catch (err) {
+            // 仅将 not-found 语义视为「包内无此 Action」；其余异常必须透传，避免内部错误伪装成 ACTION_NOT_FOUND
+            if (!isActionNotFoundLikeError(err)) {
+                throw err;
+            }
+        }
+    }
+    if (matches.length === 1) {
+        return { kind: "unique", app: matches[0] };
+    }
+    if (matches.length > 1) {
+        return { kind: "ambiguous", candidates: matches.map((m) => m.packageId) };
+    }
+    return { kind: "not_found" };
+}
+/**
+ * 按包标识构造未找到错误信息：优先透传链接包加载失败的精准诊断。
+ */
+export function packageNotFoundMessage(packageId, failedLinkedPackages) {
+    const failed = failedLinkedPackages.get(packageId);
+    if (failed) {
+        return `Package '${packageId}' not found in host (failed to load from '${failed.path}': ${failed.error})`;
+    }
+    return `Package '${packageId}' not found in host`;
+}
+/**
+ * 静态查询并聚合可见包的 Playbook 规程摘要（带包前缀限定）。
+ */
+export async function listVisiblePlaybooks(apps, visibility) {
+    const results = [];
+    for (const app of apps) {
+        const isPublic = visibility.hostPublicPackageIds.has(app.packageId);
+        if (!isPublic && visibility.resolver) {
+            const graph = visibility.resolver.resolveSync();
+            if (!graph.directDependencyIds.has(app.packageId)) {
+                continue;
+            }
+        }
+        const appPlaybooks = await app.listPlaybooks();
+        for (const item of appPlaybooks) {
+            const qualifiedId = apps.length > 1 && !item.id.includes("/")
+                ? `${app.packageId}/${item.id}`
+                : item.id;
+            results.push({
+                ...item,
+                id: qualifiedId,
+                packageId: app.packageId,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * 静态查询指定 Playbook 规范：支持「包/规程」限定引用与裸短标识符两级解析。
+ * 未声明依赖的传递包、不存在的规程与空匹配分别抛出对应语义错误。
+ */
+export async function describeVisiblePlaybook(apps, id, visibility) {
+    if (id.includes("/")) {
+        const lastSlashIndex = id.lastIndexOf("/");
+        const packageId = id.slice(0, lastSlashIndex);
+        const playbookId = id.slice(lastSlashIndex + 1);
+        const isPublic = visibility.hostPublicPackageIds.has(packageId);
+        if (!isPublic && visibility.resolver) {
+            const graph = visibility.resolver.resolveSync();
+            if (!graph.directDependencyIds.has(packageId)) {
+                throw new Error(`UNDECLARED_ACTION_DEPENDENCY: Playbook '${id}' belongs to undeclared transitive package '${packageId}'`);
+            }
+        }
+        const app = apps.find((a) => a.packageId === packageId);
+        if (!app) {
+            throw new Error(`Package '${packageId}' not found in host`);
+        }
+        return app.describePlaybook(playbookId);
+    }
+    for (const app of apps) {
+        try {
+            const isPublic = visibility.hostPublicPackageIds.has(app.packageId);
+            if (!isPublic && visibility.resolver) {
+                const graph = visibility.resolver.resolveSync();
+                if (!graph.directDependencyIds.has(app.packageId)) {
+                    continue;
+                }
+            }
+            return await app.describePlaybook(id);
+        }
+        catch {
+            // 忽略未匹配的包
+        }
+    }
+    throw new Error(`Playbook '${id}' not found in any registered package`);
+}
+/**
+ * 聚合全部已注册包的元数据信息。
+ */
+export async function collectPackageInfos(apps) {
+    return Promise.all(apps.map((app) => app.info()));
+}
+/**
+ * 构造失配类错误响应载荷（ACTION_NOT_FOUND / AMBIGUOUS_ACTION_REF 等）。
+ */
+export function buildRuntimeError(code, message, details) {
+    const error = { code, message };
+    if (details !== undefined) {
+        error.details = details;
+    }
+    return error;
+}
+/**
+ * 构造短标识符歧义错误消息（供静态查询与启动执行链路复用统一文案）。
+ */
+export function ambiguousActionMessage(actionId, candidates) {
+    const joined = candidates.map((c) => `${c}/${actionId}`).join(", ");
+    return `Action '${actionId}' is ambiguous and provided by multiple packages: ${joined}. Please specify '<package-id>/${actionId}'.`;
+}
+/**
+ * 静态查询指定 Action 规范：包限定引用直查，裸短标识符跨包消歧后返回。
+ */
+export async function describeActionAcrossApps(ref, apps, visibility, failedLinkedPackages) {
+    const parsed = parseRefLoose(ref);
+    if (parsed.packageId) {
+        if (!isRootCallVisible(parsed.packageId, parsed.actionId, visibility.hostPublicPackageIds, visibility.resolver)) {
+            throw new Error(`UNDECLARED_ACTION_DEPENDENCY: Action '${parsed.packageId}/${parsed.actionId}' is not declared as a direct dependency in actiondock.json and is not delegated by a visible playbook`);
+        }
+        const app = apps.find((a) => a.packageId === parsed.packageId);
+        if (!app) {
+            throw new Error(packageNotFoundMessage(parsed.packageId, failedLinkedPackages));
+        }
+        const spec = await app.describeAction(parsed.actionId);
+        return {
+            ...spec,
+            packageId: app.packageId,
+        };
+    }
+    const matches = [];
+    for (const app of apps) {
+        try {
+            if (!isRootCallVisible(app.packageId, parsed.actionId, visibility.hostPublicPackageIds, visibility.resolver)) {
+                continue;
+            }
+            const spec = await app.describeAction(parsed.actionId);
+            matches.push({ app, spec: { ...spec, packageId: app.packageId } });
+        }
+        catch (err) {
+            // 仅将 not-found 语义视为「包内无此 Action」；其余异常必须透传，避免内部错误伪装成 ACTION_NOT_FOUND
+            if (!isActionNotFoundLikeError(err)) {
+                throw err;
+            }
+        }
+    }
+    if (matches.length === 1) {
+        return {
+            ...matches[0].spec,
+            packageId: matches[0].app.packageId,
+        };
+    }
+    if (matches.length > 1) {
+        const err = new Error(`INVALID_ACTION_REF: ${ambiguousActionMessage(parsed.actionId, matches.map((m) => m.app.packageId))} (AMBIGUOUS_ACTION_REF)`);
+        err.code = "INVALID_ACTION_REF";
+        err.details = { alias: "AMBIGUOUS_ACTION_REF", candidates: matches.map((m) => m.app.packageId) };
+        throw err;
+    }
+    throw new Error(`ACTION_NOT_FOUND: Action '${parsed.actionId}' not found in any registered package`);
+}
+/**
+ * 解析宿主自动加载工程根目录：显式指定优先，其次当前进程工作目录探测。
+ */
+export function resolveProjectRoot(options, detect, exists = existsSync) {
+    let root = options.projectRoot;
+    if (!root) {
+        const detected = detect();
+        if (detected) {
+            root = detected;
+        }
+    }
+    if (!root || !exists(root)) {
+        return null;
+    }
+    return root;
+}

package/dist/host/types.d.ts

@@ -16,6 +16,12 @@ export interface ActionDockHostOptions {
     autoLoadCurrentProject?: boolean;
     /** 是否扫描已软链接的外部包（通过 listLinkedPackages，默认为 false） */
     scanLinkedPackages?: boolean;
+    /**
+     * 是否以数据目录持有者身份打开包存储：true 时内部创建的 App 存储在打开阶段
+     * 收割遗留非终态运行记录。默认 true（Host 本身即持有者）；
+     * CLI 查询命令创建旁观 Host 时显式置 false，避免误收割并发 serve 进程的在途运行。
+     */
+    recoverOrphans?: boolean;
     /** 显式注入的运行时平台适配 */
     platform?: RuntimePlatform;
     /** 全局最大并发活跃运行数 */
@@ -44,6 +50,8 @@ export interface ActionDockHostOptions {
  * 作为多包环境下的全局协调中枢，负责多包生命周期、完全限定引用路由、依赖校验与配额管理。
  */
 export interface ActionDockHost {
+    /** 宿主容器初始化配置项（只读） */
+    readonly options?: ActionDockHostOptions;
     /** 获取所有已注册包的元数据信息列表 */
     info(): Promise<PackageInfo[]>;
     /** 静态列出所有已注册包中可用的 Action 摘要 */

package/dist/ipc/host.js

@@ -1,4 +1,36 @@
+import { TARGET_CAPABILITY_UNAVAILABLE } from "../target/types.js";
 import { hasIpcSignalMarker, IPC_SIGNAL_MARKER } from "./target.js";
+/**
+ * IPC 通道允许反射调用的目标方法白名单。
+ *
+ * 严格对齐 ActionDockTarget 公共接口方法名集合：白名单之外的方法一律拒绝，
+ * 防止 IPC 消息通道触达任意内部属性或危险方法（如 close 之外的私有能力）。
+ */
+const IPC_ALLOWED_METHODS = new Set([
+    "info",
+    "listPackages",
+    "listActions",
+    "describeAction",
+    "listPlaybooks",
+    "describePlaybook",
+    "runAction",
+    "startAction",
+    "listRuns",
+    "getRun",
+    "cancelRun",
+    "clearRuns",
+    "events",
+    "getConfig",
+    "setConfig",
+    "deleteConfig",
+    "listConfig",
+    "getState",
+    "setState",
+    "deleteState",
+    "listStateKeys",
+    "clearState",
+    "listStateEntries",
+]);
 /**
  * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockTarget 门面能力。
  *
@@ -65,6 +97,12 @@ export async function serveParentIpc(target) {
             const callMsg = msg;
             const { id, method, args } = callMsg;
             try {
+                // 白名单校验：仅允许 ActionDockTarget 公共接口方法，阻止任意方法反射调用
+                if (typeof method !== "string" || !IPC_ALLOWED_METHODS.has(method)) {
+                    const err = new Error(`Target method '${method}' is not allowed over IPC (not in ActionDockTarget public interface)`);
+                    err.code = TARGET_CAPABILITY_UNAVAILABLE;
+                    throw err;
+                }
                 const fn = target[method];
                 if (typeof fn !== "function") {
                     throw new Error(`Target method '${method}' not found`);

package/dist/platform/types.d.ts

@@ -53,6 +53,11 @@ export interface StorageFactoryOptions {
     dataDir?: string;
     inMemory?: boolean;
     customHome?: string;
+    /**
+     * 是否以数据目录持有者身份打开：true 时构造阶段收割死亡会话遗留的非终态运行记录。
+     * 默认 false（旁观查询打开，不触碰在途记录），供 CLI 查询命令与执行宿主并发共存。
+     */
+    recoverOrphans?: boolean;
 }
 /**
  * 跨运行时全局存储工厂配置选项。
@@ -61,6 +66,8 @@ export interface GlobalStorageFactoryOptions {
     dataDir?: string;
     inMemory?: boolean;
     customHome?: string;
+    /** 是否以持有者身份打开并收割遗留非终态运行记录（默认 false，旁观语义） */
+    recoverOrphans?: boolean;
 }
 /**
  * 跨运行时持久化存储工厂契约。

package/dist/process/control-arbiter.d.ts

@@ -0,0 +1,107 @@
+import type { ControlGrant } from "@actiondock/sdk";
+import type { ManagedProcessRecord, ProcessOwner } from "./managed-record.js";
+import type { StoredProcessRecord } from "./metadata-store.js";
+/**
+ * 控制权仲裁器宿主协作回调集合。
+ *
+ * 持有者始终为 ProcessManager：仲裁器仅经回调透传副作用，不反向依赖管理器。
+ */
+export interface ControlArbiterHost {
+    /** 控制权状态落盘（异步尽力而为） */
+    persistState(processId: string, patch: Partial<StoredProcessRecord>): unknown;
+    /** 排队路径授予成功时的凭据落盘（异步尽力而为） */
+    persistGrantReceipt(grant: ControlGrant, wait: {
+        requestId: string;
+        waitMs: number;
+        ttlMs: number;
+    }, proc: ManagedProcessRecord): unknown;
+    /** 控制权事件后的空闲定时器刷新（授予、续租与成功输入均触发） */
+    refreshIdleTimer(proc: ManagedProcessRecord): void;
+    /** 到期复核通过后的隔离处置（隔离而非释放） */
+    quarantineProcess(owner: ProcessOwner, processId: string, token?: string, reason?: string): unknown;
+    /** 宿主级等待者配额统计（含全部进程的排队等待者） */
+    countHostAcquireWaiters(): number;
+    /** 宿主等待者配额上限 */
+    readonly maxWaitersPerProcess: number;
+    /** 单进程等待者配额上限 */
+    readonly maxWaitersPerHost: number;
+}
+/**
+ * 控制权仲裁器。
+ *
+ * 单一职责：独占控制权状态机的全部推进路径——
+ * - 直接授予与 FIFO 等待队列（唯一唤醒）
+ * - TTL 定时器生命周期（设置、续租换新、清理）
+ * - 到期复核（复合控制态与凭据双重校验，转隔离而非释放）
+ * - 操作授权校验（write/control 提交前与调度复核共用）
+ * - 终态等待者单一拒绝入口
+ */
+export declare class ControlArbiter {
+    private readonly host;
+    constructor(host: ControlArbiterHost);
+    /**
+     * 尝试立即授予控制权：控制权空闲且无等待者时直接授予，
+     * 否则按 FIFO 进入等待队列并返回等待 Promise。
+     *
+     * 调用方（原 acquire 请求）在排队路径 resolve 后负责预约结算；
+     * 唤醒方负责凭据落盘，保持两阶段时序不变。
+     */
+    tryAcquire(proc: ManagedProcessRecord, input: {
+        requestId: string;
+        waitMs: number;
+        ttlMs: number;
+    }, call?: {
+        signal?: AbortSignal;
+    }, runId?: string): {
+        granted: boolean;
+        waiter?: Promise<ControlGrant>;
+    };
+    /**
+     * FIFO 入队单个等待者：注册超时定时器、中止监听与自清理钩子。
+     */
+    private enqueueWaiter;
+    /**
+     * 授予指定受管进程控制令牌：递增控制纪元、登记凭据并设置 TTL 定时器。
+     */
+    grantControl(proc: ManagedProcessRecord, requestId: string, ttlMs: number, runId?: string): ControlGrant;
+    /**
+     * 续租当前有效控制令牌：先清理旧 TTL 定时器再设置新定时器，
+     * 刷新到期时刻并联动空闲定时器。
+     */
+    renewGrant(proc: ManagedProcessRecord, ttlMs: number): ControlGrant;
+    /**
+     * 显式释放控制令牌：清理 TTL 定时器、凭据置空并唤醒下一个等待者。
+     */
+    releaseGrant(proc: ManagedProcessRecord): void;
+    /**
+     * 唤醒排队等待控制权的下一个调用者（唯一唤醒入口）：
+     * 授予令牌、由唤醒方落盘排队凭据并 resolve 原等待 Promise。
+     */
+    private wakeNextAcquireWaiter;
+    /**
+     * 控制权到期未释放时的复核：仍处于 held 且凭据有效时转隔离（隔离而非释放）。
+     */
+    handleGrantTtlExpired(proc: ManagedProcessRecord): void;
+    /**
+     * 操作提交前校验持有者令牌与授权（write/control 入队前与调度链路共用）。
+     */
+    validateOperation(proc: ManagedProcessRecord, token: string): void;
+    /**
+     * 校验当前持有凭据有效性（token 匹配且未过期），供 renew/release 提交前判定。
+     */
+    validateHeldGrant(proc: ManagedProcessRecord, token: string): void;
+    /**
+     * 终态等待者单一拒绝入口：按 FIFO 拒绝全部排队等待者。
+     *
+     * 终态转移（exit/error/stop/quarantine）必须经由此方法清空等待队列，
+     * 禁止直接操作 acquireWaiters 数组。
+     */
+    revokeAllWaiters(proc: ManagedProcessRecord, reason: {
+        code: string;
+        message: string;
+    }): void;
+    /**
+     * 清理进程全部控制权相关定时器与等待队列（stop/退出/故障路径统一入口）。
+     */
+    disposeProcess(proc: ManagedProcessRecord): void;
+}