@actiondock/core 2.5.0 → 2.6.0

package/dist/runtime/runner.js

@@ -2,10 +2,13 @@ import { existsSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { ActionResolver } from "../catalog/action-resolver.js";
 import { loadActions, loadProjectConfig } from "../project/loader.js";
-import { resolveActionProject, resolvePackageRoot } from "../registry/registry.js";
-import { ACTION_CALL_CYCLE, ACTION_CYCLE_DETECTED, ACTION_FAILED, ACTION_MAX_DEPTH_EXCEEDED, ACTION_NOT_FOUND, ACTION_SUBRUN_LIMIT, ACTION_TIMEOUT, describeActionLoadFailure, INPUT_NOT_JSON, MAX_SUBRUNS_REACHED, OUTPUT_NOT_JSON, RUN_PERSISTENCE_FAILED, RUN_REPOSITORY_UNAVAILABLE, UNDECLARED_ACTION_DEPENDENCY, PACKAGE_NOT_FOUND, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, ACTION_CANCELLED, } from "../errors.js";
+import { resolveActionProject } from "../registry/registry.js";
+import { ACTION_CALL_CYCLE, ACTION_CYCLE_DETECTED, ACTION_FAILED, ACTION_MAX_DEPTH_EXCEEDED, ACTION_NOT_FOUND, ACTION_SUBRUN_LIMIT, ACTION_TIMEOUT, describeActionLoadFailure, INPUT_NOT_JSON, MAX_SUBRUNS_REACHED, OUTPUT_NOT_JSON, ACTION_CANCELLED, PACKAGE_NOT_FOUND, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, UNDECLARED_ACTION_DEPENDENCY, } from "../errors.js";
 import { validateSchema } from "../schema/validator.js";
 import { createActionContext, StderrLogger } from "./context.js";
+import { ActionRegistry, findLocalAction, isActionDefinitionObject, parseActionRef, resolveAnonymousActionId, } from "./action-registry.js";
+import { buildInitialRunRecord, createRunFinalizer, createRunOrThrow, tryCreateRun, } from "./run-persistence.js";
+import { PackageRunnerFactory } from "./package-runner-factory.js";
 // 错误码常量已收敛至 src/errors.ts 单一事实源，此处保留 re-export 以维持既有导入路径兼容。
 export { RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, MAX_SUBRUNS_REACHED, ACTION_CALL_CYCLE, ACTION_CYCLE_DETECTED, ACTION_MAX_DEPTH_EXCEEDED, } from "../errors.js";
 /**
@@ -57,17 +60,18 @@ export function validateJsonValue(val, stack = new WeakSet()) {
     }
     return { valid: true };
 }
-const anonymousRunnerActionIds = new WeakMap();
-let anonymousRunnerActionCounter = 0;
 /**
  * ActionDock 核心执行引擎（ActionRunner）。
  *
- * 职责：
- * - 负责 Action 执行的全生命周期管理（校验、隔离、跟踪、落库）。
- * - 入参 (inputSchema) 与出参 (outputSchema) 的 JSON Schema 严格校验。
- * - 嵌套 Action 相互调用的环路检测（Cycle Detection）。
- * - 超时 (Timeout) 与中断信号 (AbortSignal) 竞态控制。
- * - 自动记录并持久化 RunRecord 运行记录至 SQLite 存储。
+ * 本类为执行编排壳：负责 Action 执行的全生命周期编排（校验、深度与环路检测、
+ * 超时与取消竞态、子调用 uses 授权与错误分类），并将单一职责域委托至独立模块：
+ * - Action 注册与检索委托 `ActionRegistry`（action-registry.ts）
+ * - RunRecord 构造与落库委托 run-persistence.ts
+ * - 跨包 Runner 构建与缓存委托 `PackageRunnerFactory`（package-runner-factory.ts）
+ *
+ * 入参 (inputSchema) 与出参 (outputSchema) 的 JSON Schema 严格校验、嵌套 Action
+ * 相互调用的环路检测（Cycle Detection）、超时 (Timeout) 与中断信号 (AbortSignal)
+ * 竞态控制与运行记录持久化编排仍由本类承担。
  */
 export class ActionRunner {
     packageId;
@@ -78,19 +82,16 @@ export class ActionRunner {
     projectRoot;
     projectConfig;
     configOverrides;
-    actions;
+    registry;
     clock;
     process;
     platform;
     maxCallDepth;
     maxSubRuns;
     activeSubRuns = 0;
-    packageRunners = new Map();
-    /** 跨包 Runner 构建中的 in-flight Promise：并发调用 await 同一构建任务，消除 check-then-act 竞态 */
-    pendingPackageRunners = new Map();
+    packageFactory;
     actionResolver;
     getStorageForPackage;
-    packageContextResolver;
     customHome;
     hostSessionId;
     constructor(options) {
@@ -101,7 +102,7 @@ export class ActionRunner {
         this.projectRoot = options.projectRoot;
         this.projectConfig = options.projectConfig;
         this.configOverrides = options.configOverrides || {};
-        this.actions = options.actions || new Map();
+        this.registry = new ActionRegistry(options.actions);
         this.customHome = options.customHome;
         this.platform = options.platform;
         if (options.platform) {
@@ -110,6 +111,8 @@ export class ActionRunner {
             this.storage = options.storage ?? options.platform.storage.createStorage(this.packageId, {
                 projectRoot: this.projectRoot,
                 customHome: this.customHome,
+                // Runner 作为执行宿主组件属于持有者路径，打开时收割遗留孤儿运行
+                recoverOrphans: true,
             });
             this.globalStorage = options.globalStorage ?? options.platform.storage.createGlobalStorage({
                 customHome: this.customHome,
@@ -128,34 +131,38 @@ export class ActionRunner {
         this.maxSubRuns = options.maxSubRuns ?? 64;
         this.actionResolver = options.actionResolver;
         this.getStorageForPackage = options.getStorageForPackage;
-        this.packageContextResolver = options.packageContextResolver;
+        this.packageFactory = new PackageRunnerFactory({
+            globalStorage: this.globalStorage,
+            projectRoot: this.projectRoot,
+            process: this.process,
+            clock: this.clock,
+            platform: this.platform,
+            maxCallDepth: this.maxCallDepth,
+            maxSubRuns: this.maxSubRuns,
+            actionResolver: this.actionResolver,
+            getStorageForPackage: this.getStorageForPackage,
+            packageContextResolver: options.packageContextResolver,
+            customHome: this.customHome,
+        }, (opts) => new ActionRunner(opts));
+    }
+    /** 本地 Action 注册表底层映射（仅内部与跨包工厂委托使用） */
+    get actions() {
+        return this.registry.map;
     }
     getStorage() {
         return this.storage;
     }
     getPackageRunners() {
-        return this.packageRunners;
+        return this.packageFactory.runners;
     }
     registerAction(idOrAction, actionDef) {
-        if (typeof idOrAction === "string") {
-            if (actionDef) {
-                this.actions.set(idOrAction, actionDef);
-            }
-        }
-        else {
-            const actObj = idOrAction;
-            const id = actObj.id || "anonymous-action";
-            const act = actObj.action || (actObj.run ? actObj : undefined);
-            if (act) {
-                this.actions.set(id, act);
-            }
-        }
+        this.registry.registerAction(idOrAction, actionDef);
     }
     /**
      * 根据 ID 检索注册的 Action。
      */
     getAction(id) {
-        return this.actions.get(id);
+        return this.registry.getAction(id);
     }
     /**
      * 动态解析 Action（支持本地注册表、自定义解析器委托与已链接包目录索引检索）。
@@ -164,15 +171,13 @@ export class ActionRunner {
      * @returns 解析判别联合结果（found | not_found | load_failed）
      */
     async resolveAction(actionOrRef) {
-        if (typeof actionOrRef === "object" &&
-            "run" in actionOrRef &&
-            typeof actionOrRef.run === "function") {
+        if (isActionDefinitionObject(actionOrRef)) {
             return { status: "found", action: actionOrRef };
         }
         const ref = actionOrRef;
         let parsed;
         try {
-            parsed = ActionResolver.parseRef(ref);
+            parsed = parseActionRef(ref);
         }
         catch (err) {
             return { status: "not_found", reason: err.message };
@@ -180,18 +185,9 @@ export class ActionRunner {
         const targetActionId = parsed.actionId;
         const targetPackageId = parsed.packageId;
         // 本地 actions 映射表优先检索
-        if (targetPackageId && targetPackageId !== this.packageId) {
-            if (this.actions.has(`${targetPackageId}/${targetActionId}`)) {
-                return { status: "found", action: this.actions.get(`${targetPackageId}/${targetActionId}`) };
-            }
-        }
-        else {
-            if (this.actions.has(targetActionId)) {
-                return { status: "found", action: this.actions.get(targetActionId) };
-            }
-            if (this.packageId && this.actions.has(`${this.packageId}/${targetActionId}`)) {
-                return { status: "found", action: this.actions.get(`${this.packageId}/${targetActionId}`) };
-            }
+        const localMatched = findLocalAction(this.actions, parsed, this.packageId);
+        if (localMatched) {
+            return { status: "found", action: localMatched };
         }
         // 外部注入的自定义 actionResolver 调度
         if (this.actionResolver) {
@@ -246,7 +242,6 @@ export class ActionRunner {
         let actionsMap;
         try {
             actionsMap = await loadActions(resolved.projectRoot, config.actionsDir, {
-                autoInstall: false,
                 loader: this.platform?.modules,
             });
         }
@@ -276,13 +271,13 @@ export class ActionRunner {
      * 获取当前 Runner 已注册的所有 Action 列表。
      */
     listActions() {
-        return Array.from(this.actions.values());
+        return this.registry.listActions();
     }
     /**
      * 注入或更新跨包运行上下文解析委托。
      */
     setPackageContextResolver(resolver) {
-        this.packageContextResolver = resolver;
+        this.packageFactory.setPackageContextResolver(resolver);
     }
     /**
      * 跨包运行时解析与获取（确保跨包执行具备独立的配置、存储、状态与 Action 注册表）。
@@ -292,95 +287,7 @@ export class ActionRunner {
      * 并发方 await 同一构建任务，构建失败时移除该 Promise 以便后续重试。
      */
     async resolveTargetPackageRunner(targetPackageId) {
-        const cached = this.packageRunners.get(targetPackageId);
-        if (cached) {
-            return cached;
-        }
-        const inFlight = this.pendingPackageRunners.get(targetPackageId);
-        if (inFlight) {
-            return inFlight;
-        }
-        const building = this.buildTargetPackageRunner(targetPackageId).finally(() => {
-            // 无论成败均移除 in-flight 记录：成功者已写入正式缓存，失败者允许重试
-            this.pendingPackageRunners.delete(targetPackageId);
-        });
-        this.pendingPackageRunners.set(targetPackageId, building);
-        return building;
-    }
-    /**
-     * 实际构建跨包 Runner（仅由 resolveTargetPackageRunner 串行调度）。
-     */
-    async buildTargetPackageRunner(targetPackageId) {
-        if (this.packageContextResolver) {
-            const resolved = await this.packageContextResolver(targetPackageId);
-            if (resolved) {
-                const runner = new ActionRunner({
-                    packageId: targetPackageId,
-                    packageInstanceId: resolved.packageInstanceId || resolved.projectConfig?.packageInstanceId || targetPackageId,
-                    generationId: resolved.generationId || resolved.projectConfig?.generationId || "1",
-                    storage: resolved.storage,
-                    globalStorage: this.globalStorage,
-                    projectRoot: resolved.projectRoot,
-                    projectConfig: resolved.projectConfig,
-                    actions: resolved.actions,
-                    process: this.process,
-                    clock: this.clock,
-                    platform: this.platform,
-                    maxCallDepth: this.maxCallDepth,
-                    maxSubRuns: this.maxSubRuns,
-                    actionResolver: this.actionResolver,
-                    getStorageForPackage: this.getStorageForPackage,
-                    packageContextResolver: this.packageContextResolver,
-                });
-                this.packageRunners.set(targetPackageId, runner);
-                return runner;
-            }
-        }
-        const root = resolvePackageRoot(targetPackageId, this.projectRoot, this.customHome);
-        if (root && existsSync(root)) {
-            const config = loadProjectConfig(root);
-            let storage;
-            if (this.getStorageForPackage) {
-                storage = this.getStorageForPackage(targetPackageId, root);
-            }
-            else if (this.platform) {
-                storage = this.platform.storage.createStorage(targetPackageId, {
-                    projectRoot: root,
-                    customHome: this.customHome,
-                });
-            }
-            else {
-                // 回退分支与主路径共用 createStorage 单一事实源，确保 run 记录落在统一解析的库文件
-                const { createStorage } = await import("../storage/index.js");
-                storage = createStorage(targetPackageId, { projectRoot: root, customHome: this.customHome });
-            }
-            const actionsMap = await loadActions(root, config.actionsDir, {
-                autoInstall: false,
-                loader: this.platform?.modules,
-            });
-            const runner = new ActionRunner({
-                packageId: targetPackageId,
-                packageInstanceId: config.packageInstanceId || targetPackageId,
-                generationId: config.generationId || "1",
-                storage,
-                globalStorage: this.globalStorage,
-                projectRoot: root,
-                projectConfig: config,
-                actions: actionsMap,
-                process: this.process,
-                clock: this.clock,
-                platform: this.platform,
-                maxCallDepth: this.maxCallDepth,
-                maxSubRuns: this.maxSubRuns,
-                actionResolver: this.actionResolver,
-                getStorageForPackage: this.getStorageForPackage,
-                packageContextResolver: this.packageContextResolver,
-                customHome: this.customHome,
-            });
-            this.packageRunners.set(targetPackageId, runner);
-            return runner;
-        }
-        return undefined;
+        return this.packageFactory.resolveTargetPackageRunner(targetPackageId);
     }
     /**
      * 异步启动 Action 的执行并立即返回 ExecutionHandle 句柄。
@@ -401,7 +308,7 @@ export class ActionRunner {
                 message: `Input validation failed for action '${targetActionId}': ${inputCheck.reason}`,
             };
             // 安全记录 failed 状态（不可序列化的非法 input 严禁直接写入持久化存储）
-            this.tryPersistInitialRun(runCtx, "failed", error);
+            tryCreateRun(this.storage, buildInitialRunRecord(this.buildRunPersistenceInput(runCtx), "failed", error));
             return {
                 runId,
                 result: Promise.resolve({ ok: false, runId, error }),
@@ -409,8 +316,8 @@ export class ActionRunner {
             };
         }
         // 始终优先将执行尝试持久化到存储中（确保任意异常与终态都可追溯）
-        this.persistInitialRun(runCtx, "running");
-        const finalizer = this.createRunFinalizer(runCtx);
+        createRunOrThrow(this.storage, buildInitialRunRecord(this.buildRunPersistenceInput(runCtx), "running"));
+        const finalizer = createRunFinalizer(this.storage, runCtx.runId);
         // 调用嵌套深度限制检测 (Max Call Depth Check)
         const depthError = this.checkCallDepth(runCtx.callStack, targetActionId, runCtx.options);
         if (depthError) {
@@ -512,33 +419,24 @@ export class ActionRunner {
         let action;
         let targetActionId;
         let targetPackageId = this.packageId;
-        if (typeof actionOrId === "object" &&
-            "run" in actionOrId &&
-            typeof actionOrId.run === "function") {
+        if (isActionDefinitionObject(actionOrId)) {
             action = actionOrId;
             const actObj = action;
             if (actObj.id) {
                 targetActionId = actObj.id;
             }
             else {
-                targetActionId = this.resolveAnonymousActionId(action);
+                targetActionId = resolveAnonymousActionId(this.actions, action);
             }
             this.actions.set(targetActionId, action);
         }
         else {
-            const parsed = ActionResolver.parseRef(actionOrId);
+            const parsed = parseActionRef(actionOrId);
             targetActionId = parsed.actionId;
             if (parsed.packageId) {
                 targetPackageId = parsed.packageId;
             }
-            if (parsed.packageId && parsed.packageId !== this.packageId) {
-                action = this.actions.get(`${parsed.packageId}/${targetActionId}`);
-            }
-            else {
-                action =
-                    this.actions.get(targetActionId) ||
-                        (this.packageId ? this.actions.get(`${this.packageId}/${targetActionId}`) : undefined);
-            }
+            action = findLocalAction(this.actions, parsed, this.packageId);
         }
         return {
             runId,
@@ -554,128 +452,27 @@ export class ActionRunner {
         };
     }
     /**
-     * 为匿名传入的 Action 定义对象解析或分配稳定标识。
+     * 依据运行期上下文装配落库模块入参（RunRecord 构造领域契约）。
      */
-    resolveAnonymousActionId(action) {
-        const actObj = action;
-        let foundId;
-        for (const [id, a] of this.actions) {
-            if (a === action) {
-                foundId = id;
-                break;
-            }
-        }
-        if (foundId) {
-            return foundId;
-        }
-        let anonId = anonymousRunnerActionIds.get(action);
-        if (!anonId) {
-            anonymousRunnerActionCounter++;
-            anonId = `anonymous-action-${anonymousRunnerActionCounter}`;
-            anonymousRunnerActionIds.set(action, anonId);
-        }
-        try {
-            actObj.id = anonId;
-        }
-        catch { }
-        return anonId;
-    }
-    /**
-     * 尝试将 failed 终态初始记录写入存储（非法输入场景，存储异常静默忽略）。
-     */
-    tryPersistInitialRun(runCtx, status, error) {
-        const initialRun = this.buildInitialRunRecord(runCtx, status, error);
-        try {
-            this.storage.createRun(initialRun);
-        }
-        catch { }
-    }
-    /**
-     * 构建 running 初始记录并强制写入存储（存储不可用时抛出 RUN_REPOSITORY_UNAVAILABLE）。
-     */
-    persistInitialRun(runCtx, status) {
-        const initialRun = this.buildInitialRunRecord(runCtx, status);
-        try {
-            this.storage.createRun(initialRun);
-        }
-        catch (err) {
-            const error = new Error(`RUN_REPOSITORY_UNAVAILABLE: Failed to initialize run record in repository: ${err?.message || String(err)}`);
-            error.code = RUN_REPOSITORY_UNAVAILABLE;
-            error.details = { originalError: err?.message };
-            throw error;
-        }
-    }
-    /**
-     * 依据运行期上下文构造 RunRecord 初始记录。
-     */
-    buildInitialRunRecord(runCtx, status, error) {
-        const { runId, options, targetPackageId, targetActionId, startedAt } = runCtx;
-        const record = {
-            id: runId,
+    buildRunPersistenceInput(runCtx) {
+        const { options, targetPackageId, targetActionId, startedAt, input } = runCtx;
+        return {
+            runId: runCtx.runId,
             rootRunId: this.computeRootRunId(runCtx),
             parentRunId: options.parentRunId,
-            packageId: targetPackageId,
-            packageInstanceId: options.packageInstanceId || (this.packageId === targetPackageId ? this.packageInstanceId : targetPackageId),
-            actionId: targetActionId,
-            generationId: options.generationId || (this.packageId === targetPackageId ? this.generationId : "1"),
-            ownerId: options.ownerId || "local",
-            hostSessionId: options.hostSessionId || this.hostSessionId,
-            status,
-            error,
+            ownerId: options.ownerId,
+            hostSessionId: options.hostSessionId,
+            packageInstanceId: options.packageInstanceId,
+            generationId: options.generationId,
+            targetPackageId,
+            targetActionId,
             startedAt,
+            input,
+            runnerPackageId: this.packageId,
+            runnerPackageInstanceId: this.packageInstanceId,
+            runnerGenerationId: this.generationId,
+            runnerHostSessionId: this.hostSessionId,
         };
-        if (status === "running") {
-            record.input = runCtx.input;
-        }
-        else {
-            record.finishedAt = startedAt;
-        }
-        return record;
-    }
-    /**
-     * 创建运行终态收敛器：封装终态去重、超时定时器清理与落库异常捕获。
-     */
-    createRunFinalizer(runCtx) {
-        const finalizer = {
-            finalized: false,
-            isTimeout: false,
-            persistError: undefined,
-            timeoutTimer: undefined,
-            controller: undefined,
-            signal: undefined,
-            onAbort: undefined,
-            startTimeout: (controller, timeoutMs) => {
-                finalizer.controller = controller;
-                finalizer.timeoutTimer = setTimeout(() => {
-                    finalizer.isTimeout = true;
-                    finalizer.controller?.abort(new Error(`Action exceeded timeout of ${timeoutMs}ms`));
-                }, timeoutMs);
-            },
-            finalize: (status, output, error) => {
-                if (finalizer.timeoutTimer) {
-                    clearTimeout(finalizer.timeoutTimer);
-                    finalizer.timeoutTimer = undefined;
-                }
-                if (finalizer.signal && finalizer.onAbort) {
-                    finalizer.signal.removeEventListener("abort", finalizer.onAbort);
-                    finalizer.onAbort = undefined;
-                }
-                if (finalizer.finalized)
-                    return;
-                finalizer.finalized = true;
-                try {
-                    this.storage.updateRun(runCtx.runId, status, output, error);
-                }
-                catch (persistErr) {
-                    finalizer.persistError = {
-                        code: RUN_PERSISTENCE_FAILED,
-                        message: `RUN_PERSISTENCE_FAILED: Failed to persist run state: ${persistErr?.message || String(persistErr)}`,
-                        details: { originalError: persistErr?.message },
-                    };
-                }
-            },
-        };
-        return finalizer;
     }
     /**
      * 调用嵌套深度限制检测（超限时返回 ACTION_CALL_CYCLE 错误）。
@@ -892,11 +689,16 @@ export class ActionRunner {
         const { runCtx, actionOrId, input, options, controller, finalizer, ctx } = args;
         const { runId, targetActionId } = runCtx;
         const abortPromise = new Promise((_, reject) => {
+            const rejectWithReason = () => reject(controller.signal.reason || new Error("Action execution was cancelled"));
             if (controller.signal.aborted) {
-                reject(controller.signal.reason || new Error("Action execution was cancelled"));
+                rejectWithReason();
             }
             else {
-                controller.signal.addEventListener("abort", () => reject(controller.signal.reason || new Error("Action execution was cancelled")), { once: true });
+                controller.signal.addEventListener("abort", rejectWithReason, { once: true });
+                // 成功与失败路径统一注销：finalize 时回收监听句柄，避免信号对象残留引用
+                finalizer.raceListenerRemovers.push(() => {
+                    controller.signal.removeEventListener("abort", rejectWithReason);
+                });
             }
         });
         return (async () => {
@@ -936,17 +738,11 @@ export class ActionRunner {
                         finalizer.finalize("failed", undefined, error);
                         return { ok: false, runId, error };
                     }
-                    if (currentAction.inputSchema) {
-                        const val = validateSchema(currentAction.inputSchema, input);
-                        if (!val.valid) {
-                            const error = {
-                                code: INPUT_VALIDATION_FAILED,
-                                message: `Input schema validation failed for action '${targetActionId}'`,
-                                details: val.errors,
-                            };
-                            finalizer.finalize("failed", undefined, error);
-                            return { ok: false, runId, error };
-                        }
+                    // 复用统一校验入口：优先 action 声明 schema，缺失时回退 projectConfig 清单声明
+                    const schemaError = this.checkActionInputSchema(currentAction, targetActionId, input);
+                    if (schemaError) {
+                        finalizer.finalize("failed", undefined, schemaError);
+                        return { ok: false, runId, error: schemaError };
                     }
                 }
                 const rawOutput = await Promise.race([
@@ -1052,6 +848,16 @@ export class ActionRunner {
             error: finalizer.persistError || error,
         };
     }
+    /**
+     * 释放 Runner 持有的跨包资源：遍历关闭全部子包 Runner 及其独立创建的存储连接。
+     *
+     * 幂等且并发安全：重复调用直接复用首次 Promise；子包存储异常不阻断其余释放；
+     * 仅关闭由本 Runner 构建子包 Runner 时独立创建的存储，外部注入的存储（如经
+     * packageContextResolver 传入的目标包自身存储）生命周期归所有者管理，不在此误关。
+     */
+    async dispose() {
+        return this.packageFactory.dispose();
+    }
     /**
      * 同步等待方式执行指定 Action，直接返回 ExecutionResult 信封结果。
      *

package/dist/runtime/standalone.d.ts

@@ -1,4 +1,4 @@
-import type { ActionDefinition } from "@actiondock/sdk";
+import { type ActionDefinition } from "@actiondock/sdk";
 import type { ActionSpec } from "../app/types.js";
 import type { ConfigItemDefinition } from "../project/types.js";
 import type { ActionDockTarget } from "../target/types.js";
@@ -71,6 +71,16 @@ export declare class StandaloneDispatcher {
     private handleRun;
     private handleConfig;
     private handleState;
+    /**
+     * 判定配置读取异常是否为目标层能力缺失（键未配置语义）而非内部故障。
+     */
+    private isTargetCapabilityError;
+    /**
+     * 解析携带命名空间前缀的状态键参数：委托 sdk 单一事实源 decodeStateKey。
+     *
+     * 解析失败（如存在多个未转义冒号的歧义键）时按纯键处理，交由存储层兜底。
+     */
+    private decodeStateKeyArg;
     private printHelp;
 }
 /**