@actiondock/core 2.9.1 → 2.11.0

package/dist/package/runtime.js

@@ -5,17 +5,73 @@ 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 { createLazyStorage } from "../storage/index.js";
 import { isSecretConfigKey, sanitizeConfigDefinitions } from "../storage/mask.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, } from "../errors.js";
+import { ACTION_NOT_FOUND, ActionDockError, CAPABILITY_UNAVAILABLE, INVALID_ARGUMENT, INVOCATION_UNSUPPORTED, NOT_FOUND, SERVICE_CLOSED, } from "../errors.js";
+import { createAbortError } from "../ipc/service.js";
 import { createRootInvocationContext } from "../invocation/types.js";
 import { buildStaticActionMap, buildStaticPlaybookMap } from "./static-index.js";
 import { applyActionSummaryFilters } from "./types.js";
+function normalizeStateReadArgs(arg1, arg2, arg3) {
+    if (typeof arg2 === "string") {
+        if (arg3?.actionId !== undefined && arg3.actionId !== arg1) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Conflicting actionId specified: positional '${arg1}' vs options.actionId '${arg3.actionId}'`);
+        }
+        return {
+            key: arg2,
+            options: { ...arg3, actionId: arg1 },
+        };
+    }
+    return {
+        key: arg1,
+        options: arg2,
+    };
+}
+function normalizeStateWriteArgs(arg1, arg2, arg3, arg4, argsCount) {
+    const isFourArgs = argsCount !== undefined ? argsCount >= 4 : arg4 !== undefined;
+    if (isFourArgs) {
+        if (arg4?.actionId !== undefined && arg4.actionId !== arg1) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Conflicting actionId specified: positional '${arg1}' vs options.actionId '${arg4.actionId}'`);
+        }
+        return {
+            key: String(arg2),
+            value: arg3,
+            options: { ...arg4, actionId: arg1 },
+        };
+    }
+    if (arg3 !== undefined &&
+        (typeof arg3 !== "object" || arg3 === null || Array.isArray(arg3))) {
+        throw new ActionDockError(INVALID_ARGUMENT, "Invalid options provided to setState. Use setActionState(actionId, key, value, options) or 4-argument setState for action state.");
+    }
+    return {
+        key: arg1,
+        value: arg2,
+        options: arg3,
+    };
+}
+function normalizeStateScopeArgs(actionIdOrOptions, options) {
+    if (typeof actionIdOrOptions === "string") {
+        if (options?.actionId !== undefined && options.actionId !== actionIdOrOptions) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Conflicting actionId specified: positional '${actionIdOrOptions}' vs options.actionId '${options.actionId}'`);
+        }
+        return { ...options, actionId: actionIdOrOptions };
+    }
+    if (actionIdOrOptions === undefined) {
+        return options;
+    }
+    return actionIdOrOptions;
+}
 /**
  * ActionDock 统一包运行时默认实现。
  * 封装并管理单个 Action Package 的执行引擎、静态元数据索引、配置与状态存储生命周期。
+ *
+ * 资源按需装配契约：
+ * - 构造函数只完成身份、清单与内存注入动作的归一化，不打开数据库、
+ *   不创建进程接口、不注册模块加载钩子、不实例化执行服务；
+ * - 包存储、执行服务、全局存储与配置解析器拆分为内部资源槽位，
+ *   首次实际调用时准备并缓存复用；
+ * - info / list / describe / 规程发现等静态查询全程零资源创建。
  */
 export class DefaultPackageRuntime {
     identity;
@@ -24,21 +80,28 @@ export class DefaultPackageRuntime {
     generationId;
     packageRoot;
     projectConfig;
+    inMemory;
     platform;
-    storage;
-    globalStorage;
-    executionService;
     actionsMap;
     options;
-    runtimeConfig;
     isClosed = false;
-    injectedGlobalStorage = false;
+    // - 资源槽位（构造阶段全部为空，按需准备）
+    storageSlot = {};
+    executionSlot = {};
+    /** 全局存储：显式注入或首次准备后固定，配合 ownership 判定关闭归属 */
+    globalStorageRes;
+    runtimeConfig;
+    /** 执行委托暂存：执行服务尚未创建时只保存，不触发资源初始化 */
+    pendingInvoker;
+    /** Host 会话级恢复标记：存储准备阶段收敛执行一次，避免重复执行恢复链 */
+    recoveredForHostSession = false;
     /** 静态清单索引缓存：包静态事实（根目录、配置、内存注入集合）在实例生命周期内不变，解析结果同实例内复用 */
     staticActionIndex;
     staticPlaybookIndex;
     constructor(options = {}) {
         this.options = options;
-        // 1. 确定项目根路径与配置对象
+        this.inMemory = Boolean(options.inMemory);
+        // - 确定项目根路径与配置对象
         let packageRoot = options.packageRoot;
         let projectConfig = options.projectConfig;
         if (!packageRoot && !projectConfig) {
@@ -64,6 +127,7 @@ export class DefaultPackageRuntime {
         }
         this.packageRoot = packageRoot;
         this.projectConfig = projectConfig;
+        // 兼容未在公开选项契约中显式声明的包实例标识与代系标识内部参数透传
         this.identity = options.identity || createPackageIdentity({
             id: projectConfig.id,
             instanceId: options?.packageInstanceId || projectConfig.packageInstanceId,
@@ -72,89 +136,16 @@ export class DefaultPackageRuntime {
         this.packageId = this.identity.id;
         this.packageInstanceId = this.identity.instanceId;
         this.generationId = this.identity.generation;
-        // 2. 转换 Action 集合：委托归一化单一入口
+        // - 转换 Action 集合：委托归一化单一入口
         this.actionsMap = normalizeActionCollection(options.actions).actionsMap;
-        // 3. 确定平台适配层
+        // - 确定平台适配层：默认平台对象自身不打开数据库、不注册加载钩子、不创建进程接口
         this.platform = options.platform ?? createNodePlatform();
-        // 4. 确定并初始化存储实例
         if (options.storage) {
-            this.storage = options.storage;
-        }
-        else {
-            const storageOpts = {
-                projectRoot: this.packageRoot,
-                dataDir: options.dataDir,
-                customHome: options.customHome,
-                inMemory: options.inMemory,
-                // 默认持有者语义：App 主路径打开时收割死亡会话遗留非终态运行记录；
-                // CLI 查询旁观视图显式置 recoverOrphans: false 跳过收割
-                recoverOrphans: options.recoverOrphans !== false,
-            };
-            const initStorage = () => {
-                return this.platform.storage.createStorage(this.packageId, storageOpts);
-            };
-            if (options.inMemory) {
-                this.storage = initStorage();
-            }
-            else {
-                this.storage = createLazyStorage(initStorage);
-            }
+            this.storageSlot.instance = options.storage;
         }
-        // 5. 确定全局存储实例
         if (options.globalStorage) {
-            this.globalStorage = options.globalStorage;
-            this.injectedGlobalStorage = true;
-        }
-        else if (options.inMemory) {
-            this.globalStorage = new SqliteRuntimeStorage({
-                dbPath: ":memory:",
-                packageId: "__global__",
-            });
-            this.injectedGlobalStorage = false;
-        }
-        else {
-            const globalOpts = {
-                customHome: options.customHome,
-                dataDir: options.dataDir,
-                inMemory: options.inMemory,
-                // 与主存储保持同侧收割语义（全局库 runs 表为空集，收割无实际副作用）
-                recoverOrphans: options.recoverOrphans !== false,
-            };
-            const initGlobalStorage = () => {
-                return this.platform.storage.createGlobalStorage(globalOpts);
-            };
-            this.globalStorage = createLazyStorage(initGlobalStorage);
-            this.injectedGlobalStorage = false;
-        }
-        // 6. 初始化唯一执行协调服务
-        this.executionService = new DefaultExecutionService({
-            identity: this.identity,
-            hostSessionId: options.hostSessionId,
-            storage: this.storage,
-            globalStorage: this.globalStorage,
-            projectRoot: this.packageRoot,
-            projectConfig: this.projectConfig,
-            configOverrides: options.configOverrides,
-            actions: this.actionsMap,
-            process: options.process ?? this.platform.process,
-            clock: options.clock ?? this.platform.clock,
-            logger: options.logger,
-            eventSink: options.eventSink ?? this.platform?.eventSink,
-            maxActiveRuns: options.maxActiveRuns,
-            ownerId: options.ownerId,
-            actionResolver: options.actionResolver,
-            customHome: options.customHome,
-            moduleLoader: this.platform.modules,
-            actionInvoker: options.actionInvoker,
-        });
-        if (!options.actionInvoker) {
-            const unsupportedInvoker = async () => {
-                throw new ActionDockError(INVOCATION_UNSUPPORTED, "Cascaded action invocation (ctx.actions.invoke) is not supported in standalone PackageRuntime. Actions must be executed within an ActionDock Host.");
-            };
-            this.executionService.setActionInvoker?.(unsupportedInvoker);
+            this.globalStorageRes = { kind: "external", storage: options.globalStorage };
         }
-        // 7. 初始化配置解析器
-        this.runtimeConfig = new RuntimeConfig(this.storage, options.configOverrides, this.projectConfig, this.globalStorage);
     }
     /**
      * 静态读取并聚合当前包的 Action 规范索引。
@@ -186,7 +177,260 @@ export class DefaultPackageRuntime {
         }
         return this.staticPlaybookIndex;
     }
+    assertOpen() {
+        if (this.isClosed) {
+            throw new ActionDockError(SERVICE_CLOSED, `PackageRuntime for package '${this.packageId}' is closed`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // - 内部资源准备路径（存储 / 全局存储 / 执行服务 / 配置解析器）
+    // -------------------------------------------------------------------------
+    /**
+     * 准备包存储：打开（或复用注入的）包数据库，等待可选的 ensureInitialized，
+     * 并在持有者模式下完成运行记录恢复（允许返回 Promise 的恢复接口必须被等待）。
+     * 并发首次调用共享同一在途 Promise；失败时释放新建资源、清空失败 Promise、透传原始错误。
+     */
+    ensureStorage() {
+        if (this.storageSlot.instance) {
+            return Promise.resolve(this.storageSlot.instance);
+        }
+        if (!this.storageSlot.initPromise) {
+            const init = this.openStorageAsync();
+            this.storageSlot.initPromise = init;
+            init.catch(() => {
+                // 失败后清空在途 Promise 供后续显式调用重试；同时防止未处理拒绝告警
+                if (this.storageSlot.initPromise === init) {
+                    this.storageSlot.initPromise = undefined;
+                }
+            });
+        }
+        return this.storageSlot.initPromise;
+    }
+    async openStorageAsync() {
+        let storage;
+        try {
+            storage = this.platform.storage.createStorage(this.packageId, this.buildStorageOptions());
+            if (typeof storage.ensureInitialized === "function") {
+                await storage.ensureInitialized();
+            }
+            // 存储打开阶段无会话参数的恢复（初始化链语义）已完成：
+            // 这里补充 Host 会话粒度的恢复（同一宿主会话内只收敛执行一次，返回 Promise 时被等待）
+            await this.recoverForHostSessionOnce(storage);
+            this.storageSlot.instance = storage;
+            return storage;
+        }
+        catch (err) {
+            // 初始化失败：释放本次新建且由本层拥有的资源，透传原始错误
+            if (storage) {
+                try {
+                    await storage.close();
+                }
+                catch {
+                    // 忽略清理阶段的副异常，确保原始错误优先透传
+                }
+            }
+            throw err;
+        }
+    }
+    /** 构造包存储工厂选项（单一事实源，异步与同步打开路径共用） */
+    buildStorageOptions() {
+        return {
+            projectRoot: this.packageRoot,
+            dataDir: this.options.dataDir,
+            customHome: this.options.customHome,
+            inMemory: this.options.inMemory,
+            // 默认持有者语义：App 主路径打开时收割死亡会话遗留非终态运行记录；
+            // CLI 查询旁观视图显式置 recoverOrphans: false 跳过收割
+            recoverOrphans: this.options.recoverOrphans !== false,
+        };
+    }
+    /**
+     * Host 会话级运行记录恢复：同实例生命周期内最多执行一次。
+     * 允许返回 Promise 的恢复接口被等待：恢复完成（或失败透传）前存储不发布；
+     * 恢复失败沿用既有可观测处理（告警透传），不因异步化静默丢失。
+     */
+    async recoverForHostSessionOnce(storage) {
+        if (this.recoveredForHostSession) {
+            return;
+        }
+        this.recoveredForHostSession = true;
+        if (this.options.recoverOrphans === false) {
+            return;
+        }
+        if (typeof storage.recoverDeadSessionRuns !== "function") {
+            return;
+        }
+        try {
+            await storage.recoverDeadSessionRuns(this.options.hostSessionId);
+        }
+        catch (err) {
+            // 单包恢复失败不阻断整体接管流程，但必须可观测：告警后透传，不静默丢失
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[actiondock] recoverDeadSessionRuns failed for package '${this.packageId}': ${message}`);
+            throw err;
+        }
+    }
+    /**
+     * 准备全局存储：显式注入优先，其次 Host 共享提供函数，最后独立使用平台存储工厂。
+     * 同步契约：RuntimeConfig 与 ctx.config.get() 的读取是同步的，故全局库必须同步可得。
+     */
+    ensureGlobalStorageSync() {
+        if (this.globalStorageRes) {
+            return this.globalStorageRes.storage;
+        }
+        const provider = this.options.globalStorageProvider;
+        if (provider) {
+            // Host 提供函数复用 Host 级缓存，同一 Host 不为每个包重复打开全局库
+            // （优先级高于独立内存自建路径，保证 Host 与包共享同一全局库实例）
+            const storage = provider();
+            this.globalStorageRes = { kind: "external", storage };
+            return storage;
+        }
+        if (this.options.inMemory) {
+            // 独立内存包的全局库：包自建自关（同步创建，无 IO）
+            const storage = new SqliteRuntimeStorage({
+                dbPath: ":memory:",
+                packageId: "__global__",
+            });
+            this.globalStorageRes = { kind: "own", storage };
+            return storage;
+        }
+        const globalOpts = {
+            customHome: this.options.customHome,
+            dataDir: this.options.dataDir,
+            inMemory: this.options.inMemory,
+            // 与主存储保持同侧收割语义（全局库 runs 表为空集，收割无实际副作用）
+            recoverOrphans: this.options.recoverOrphans !== false,
+        };
+        const storage = this.platform.storage.createGlobalStorage(globalOpts);
+        this.globalStorageRes = { kind: "own", storage };
+        return storage;
+    }
+    /**
+     * 异步准备全局存储：供执行服务装配前调用，保证可选的异步初始化完成。
+     * 同步路径（RuntimeConfig 读取）仍走 ensureGlobalStorageSync 复用同一实例。
+     */
+    async ensureGlobalStorage() {
+        const storage = this.ensureGlobalStorageSync();
+        if (typeof storage.ensureInitialized === "function") {
+            await storage.ensureInitialized();
+        }
+        return storage;
+    }
+    /**
+     * 准备配置解析器：依赖包存储与全局存储（五层优先级链既有实现不变）。
+     * 同步契约：RuntimeConfig 与 ctx.config.get() 的读取是同步的，故同步打开包库；
+     * 若异步准备已在途，同步路径仅在实例已发布后复用，避免双打开竞态。
+     */
+    ensureRuntimeConfig() {
+        if (!this.runtimeConfig) {
+            this.runtimeConfig = new RuntimeConfig(this.getStorageAlreadyPrepared(), this.options.configOverrides, this.projectConfig, this.ensureGlobalStorageSync());
+        }
+        return this.runtimeConfig;
+    }
+    /**
+     * 获取已就绪的包存储（同步契约专用）：
+     * - 已发布实例直接复用；
+     * - 异步准备在途时等待其结算后复用同一实例；
+     * - 未准备时同步打开并登记在途 Promise 已完成状态。
+     * 单一事实源：同步打开也走 buildStorageOptions，并补齐会话恢复等待语义的同步近似。
+     */
+    getStorageAlreadyPrepared() {
+        if (this.storageSlot.instance) {
+            return this.storageSlot.instance;
+        }
+        if (this.storageSlot.initPromise) {
+            // 异步准备在途：无法同步等待，抛出明确错误供调用方改用异步入口
+            throw new ActionDockError(SERVICE_CLOSED, `Package storage for '${this.packageId}' is still initializing; retry after initialization settles`);
+        }
+        return this.openStorageSync();
+    }
+    /** 同步打开包存储（仅当异步准备从未发起时使用） */
+    openStorageSync() {
+        this.assertOpen();
+        const storage = this.platform.storage.createStorage(this.packageId, this.buildStorageOptions());
+        this.storageSlot.instance = storage;
+        this.storageSlot.initPromise = Promise.resolve(storage);
+        return storage;
+    }
+    /**
+     * 准备执行服务：等待存储与全局存储就绪后创建唯一 DefaultExecutionService。
+     * 失败时只回收执行初始化独自新建的资源，不关闭仍被状态查询使用的包存储。
+     */
+    ensureExecutionService() {
+        if (this.executionSlot.instance) {
+            return Promise.resolve(this.executionSlot.instance);
+        }
+        if (!this.executionSlot.initPromise) {
+            const init = this.buildExecutionService();
+            this.executionSlot.initPromise = init;
+            init.catch(() => {
+                // 失败后清空在途 Promise 供后续显式调用重试；同时防止未处理拒绝告警
+                if (this.executionSlot.initPromise === init) {
+                    this.executionSlot.initPromise = undefined;
+                }
+            });
+        }
+        return this.executionSlot.initPromise;
+    }
+    async buildExecutionService() {
+        try {
+            const storage = await this.prepareStorageAsync();
+            const globalStorage = await this.ensureGlobalStorage();
+            const service = new DefaultExecutionService({
+                identity: this.identity,
+                hostSessionId: this.options.hostSessionId,
+                storage,
+                globalStorage,
+                projectRoot: this.packageRoot,
+                projectConfig: this.projectConfig,
+                configOverrides: this.options.configOverrides,
+                actions: this.actionsMap,
+                process: this.options.process ?? this.platform.process,
+                clock: this.options.clock ?? this.platform.clock,
+                logger: this.options.logger,
+                eventSink: this.options.eventSink ?? this.platform.eventSink,
+                maxActiveRuns: this.options.maxActiveRuns,
+                ownerId: this.options.ownerId,
+                actionResolver: this.options.actionResolver,
+                customHome: this.options.customHome,
+                moduleLoader: this.platform.modules,
+                // 委托优先级：最后一次绑定的 pendingInvoker 优先，否则透传显式注入的构造选项委托
+                actionInvoker: this.pendingInvoker ?? this.options.actionInvoker,
+            });
+            // 服务创建后使用最后一次绑定的委托；单包独立使用保留 INVOCATION_UNSUPPORTED 限制
+            if (!this.pendingInvoker && !this.options.actionInvoker) {
+                const unsupportedInvoker = async () => {
+                    throw new ActionDockError(INVOCATION_UNSUPPORTED, "Cascaded action invocation (ctx.actions.invoke) is not supported in standalone PackageRuntime. Actions must be executed within an ActionDock Host.");
+                };
+                service.setActionInvoker?.(unsupportedInvoker);
+            }
+            else {
+                service.setActionInvoker?.(this.pendingInvoker ?? this.options.actionInvoker);
+            }
+            this.executionSlot.instance = service;
+            return service;
+        }
+        catch (err) {
+            // 执行准备失败：只回收执行初始化独自新建的资源，不关闭仍被状态查询使用的包存储；
+            // 在途 Promise 由 ensureExecutionService 的失败回调清空（不缓存永久失败，不后台轮询）
+            throw err;
+        }
+    }
+    /** 异步等待存储准备完成（供执行准备与异步入口复用；单一赋值入口） */
+    async prepareStorageAsync() {
+        this.assertOpen();
+        if (this.storageSlot.instance) {
+            return this.storageSlot.instance;
+        }
+        return this.ensureStorage();
+    }
+    /** 获取已创建的执行服务（若存在），不触发创建 */
+    peekExecutionService() {
+        return this.executionSlot.instance;
+    }
     async info(options) {
+        this.assertOpen();
         const actionsMap = this.getStaticActionMap();
         const playbooksMap = this.getStaticPlaybookMap();
         const actions = Array.from(actionsMap.keys());
@@ -208,6 +452,7 @@ export class DefaultPackageRuntime {
         };
     }
     async listActions(options) {
+        this.assertOpen();
         const map = this.getStaticActionMap();
         const summaries = Array.from(map.values()).map((spec) => ({
             id: spec.id,
@@ -223,6 +468,7 @@ export class DefaultPackageRuntime {
         return applyActionSummaryFilters(summaries, options);
     }
     async describeAction(id) {
+        this.assertOpen();
         const map = this.getStaticActionMap();
         let spec = map.get(id);
         if (!spec && id.startsWith(`${this.packageId}/`)) {
@@ -236,30 +482,18 @@ export class DefaultPackageRuntime {
                 }
             }
         }
-        let liveAction = this.actionsMap.get(id) || (spec ? this.actionsMap.get(spec.id) : undefined);
-        if (!liveAction && this.executionService.getAction) {
-            liveAction =
-                this.executionService.getAction(id) ||
-                    (spec ? this.executionService.getAction(spec.id) : undefined);
-        }
-        if (!liveAction && this.executionService.resolveAction) {
-            try {
-                // 仅在本包范围内解析动态动作：限定 packageId 前缀，避免全局兜底搜索把
-                // 其他包的动作误计为本包提供者（host 层据此统计候选导致 AMBIGUOUS_ACTION_REF 误报）。
-                const qualifiedId = id.includes("/") ? id : `${this.packageId}/${id}`;
-                const resolution = await this.executionService.resolveAction(qualifiedId);
-                if (resolution) {
-                    liveAction = resolution;
-                }
-            }
-            catch {
-                // 忽略动态解析异常
-            }
-        }
+        // 仅读取内存注入动作与已存在（不触发创建）的执行服务缓存，不调用动态解析器
+        const cachedService = this.peekExecutionService();
+        const liveAction = this.actionsMap.get(id) ||
+            (spec ? this.actionsMap.get(spec.id) : undefined) ||
+            (cachedService?.getAction
+                ? cachedService.getAction(id) || (spec ? cachedService.getAction(spec.id) : undefined)
+                : undefined);
         if (liveAction) {
+            // 第三方 Action 实例或内存注册 Action 可能存在规范外的运行时元数据扩展字段
             const actObj = liveAction;
             return {
-                id: actObj.id || id,
+                id: actObj.id || spec?.id || id,
                 packageId: this.packageId,
                 description: actObj.description ?? spec?.description,
                 inputSchema: actObj.inputSchema ?? spec?.inputSchema,
@@ -280,6 +514,7 @@ export class DefaultPackageRuntime {
         };
     }
     async listPlaybooks() {
+        this.assertOpen();
         const map = this.getStaticPlaybookMap();
         return Array.from(map.values()).map((spec) => ({
             id: spec.id,
@@ -290,6 +525,7 @@ export class DefaultPackageRuntime {
         }));
     }
     async describePlaybook(id) {
+        this.assertOpen();
         const map = this.getStaticPlaybookMap();
         const cleanId = id.replace(/\.md$/, "");
         const spec = map.get(cleanId) || map.get(id);
@@ -317,6 +553,7 @@ export class DefaultPackageRuntime {
         });
     }
     async runAction(id, input, options) {
+        const service = await this.prepareExecution();
         let actionId = id;
         if (actionId.includes("/")) {
             if (actionId.startsWith(`${this.packageId}/`)) {
@@ -327,9 +564,10 @@ export class DefaultPackageRuntime {
             }
         }
         const context = this.buildRootInvocationContext(actionId, options);
-        return this.executionService.execute(actionId, input, context);
+        return service.execute(actionId, input, context);
     }
     async startAction(id, input, options) {
+        const service = await this.prepareExecution();
         let actionId = id;
         if (actionId.includes("/")) {
             if (actionId.startsWith(`${this.packageId}/`)) {
@@ -340,37 +578,103 @@ export class DefaultPackageRuntime {
             }
         }
         const context = this.buildRootInvocationContext(actionId, options);
-        return this.executionService.start(actionId, input, context);
+        return service.start(actionId, input, context);
     }
     async startInvocation(actionId, input, context) {
+        const service = await this.prepareExecution();
         let targetId = actionId;
         if (targetId.startsWith(`${this.packageId}/`)) {
             targetId = targetId.slice(this.packageId.length + 1);
         }
-        return this.executionService.start(targetId, input, context);
+        return service.start(targetId, input, context);
+    }
+    /** 执行前统一准备：关闭检查与执行服务就绪 */
+    async prepareExecution() {
+        this.assertOpen();
+        return this.ensureExecutionService();
     }
     async getRun(runId) {
-        return this.executionService.get(runId);
+        this.assertOpen();
+        // 历史读取复用存储能力，不创建执行服务；详情路径补齐 requestId 关联
+        const storage = await this.prepareStorageAsync();
+        if (typeof storage.getRunWithRequestId === "function") {
+            return storage.getRunWithRequestId(runId) ?? undefined;
+        }
+        return storage.getRun(runId) ?? undefined;
     }
     async cancelRun(runId, reason) {
-        return this.executionService.cancel(runId, reason);
+        this.assertOpen();
+        // 包已有执行服务时交由该服务处理活动任务与取消信号；
+        // 没有服务时只读取历史记录，不为了取消不存在的本地活动任务创建执行服务
+        const service = this.peekExecutionService();
+        if (service) {
+            return service.cancel(runId, reason);
+        }
+        const record = (await this.prepareStorageAsync()).getRun(runId);
+        if (record) {
+            return { outcome: "already_terminal", runId, status: record.status };
+        }
+        return { outcome: "not_found", runId };
     }
     events(runId, options) {
-        return this.executionService.events(runId, options);
+        this.assertOpen();
+        // 已有执行服务时沿用其事件源；没有服务时复用注入/平台事件源，不新建执行服务
+        const service = this.peekExecutionService();
+        if (service) {
+            return service.events(runId, options);
+        }
+        const sink = this.options.eventSink ?? this.platform.eventSink;
+        if (sink) {
+            return sink.subscribe(runId, options);
+        }
+        // 无任何事件源时返回空流（不新建执行服务）
+        return (async function* () { })();
     }
     setActionInvoker(invoker) {
-        if (this.executionService && typeof this.executionService.setActionInvoker === "function") {
-            this.executionService.setActionInvoker(invoker);
+        // 执行服务尚未创建时只保存委托，不触发资源初始化；服务创建后使用最后一次绑定的委托
+        this.pendingInvoker = invoker;
+        const service = this.peekExecutionService();
+        if (service) {
+            service.setActionInvoker?.(invoker);
         }
     }
+    /**
+     * Host 持有者路径预热入口：完成包存储准备（含运行记录恢复），不创建执行服务。
+     * 延迟装配下旁观路径零资源创建，持有者工厂在返回前调用本方法保持既有初始化时机。
+     */
+    async prepareResources() {
+        this.assertOpen();
+        const storage = await this.prepareStorageAsync();
+        // 注入存储路径也应执行会话级恢复：持有者预热返回前恢复必须完成（含返回 Promise 的实现）
+        await this.recoverForHostSessionOnce(storage);
+    }
+    /**
+     * 显式触发运行记录恢复（Host 持有者路径兼容入口）。
+     * 延迟装配下恢复已收敛到存储准备路径，本方法确保存储已就绪后按需补一次会话恢复。
+     */
     recoverDeadSessionRuns(sessionId) {
-        if (typeof this.storage.recoverDeadSessionRuns === "function") {
-            this.storage.recoverDeadSessionRuns(sessionId);
+        if (this.isClosed) {
+            throw new ActionDockError(SERVICE_CLOSED, `PackageRuntime for package '${this.packageId}' is closed`);
+        }
+        const storage = this.storageSlot.instance ?? this.openStorageSync();
+        if (typeof storage.recoverDeadSessionRuns === "function") {
+            try {
+                const result = storage.recoverDeadSessionRuns(sessionId ?? this.options.hostSessionId);
+                if (result instanceof Promise) {
+                    void result.catch((err) => {
+                        console.warn(`[actiondock] recoverDeadSessionRuns failed for package '${this.packageId}': ${err instanceof Error ? err.message : String(err)}`);
+                    });
+                }
+            }
+            catch (err) {
+                console.warn(`[actiondock] recoverDeadSessionRuns failed for package '${this.packageId}': ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
     async listConfig() {
+        this.assertOpen();
         const declared = this.projectConfig.config || {};
-        const stored = this.storage.listConfig();
+        const stored = (await this.prepareStorageAsync()).listConfig();
         const allKeys = Array.from(new Set([...Object.keys(declared), ...Object.keys(stored)]));
         const views = [];
         for (const key of allKeys) {
@@ -382,10 +686,11 @@ export class DefaultPackageRuntime {
         return views;
     }
     async getConfig(key) {
+        this.assertOpen();
         const itemDef = this.projectConfig.config?.[key];
         const isSecret = isSecretConfigKey(key, itemDef);
         // 委托 RuntimeConfig 五层优先级链单一事实源，避免重复实现解析链
-        const resolved = this.runtimeConfig.describe(key);
+        const resolved = this.ensureRuntimeConfig().describe(key);
         // overrides 来源对外统一星现为包级覆盖视角
         const source = resolved.source === "overrides" ? "package" : resolved.source;
         const configured = resolved.source !== "default";
@@ -398,187 +703,220 @@ export class DefaultPackageRuntime {
         };
     }
     async setConfig(key, value) {
-        await this.storage.setConfig(key, value);
+        this.assertOpen();
+        await (await this.prepareStorageAsync()).setConfig(key, value);
     }
     async deleteConfig(key) {
-        return await this.storage.deleteConfig(key);
-    }
-    /**
-     * 状态作用域统一解析辅助函数（单一事实源）。
-     *
-     * 完成重载消歧后委托 mergeStateScope 计算最终生效的命名空间：
-     * - (actionId, key, options) 形态：位置 actionId 参与冲突校验；
-     * - (key, options) 扁平形态：首参是状态键，options.actionId 属合法显式指定。
-     */
-    resolveStateScope(actionIdOrKey, keyOrOptions, options) {
-        // 消歧规则（与原始重载语义严格一致）：仅当第二参为字符串时认定为
-        // (actionId, key, options) 形态；否则（undefined 或选项对象）认定为
-        // (key, options) 扁平调用形态，首参是状态键而非 actionId
-        if (typeof keyOrOptions === "string") {
-            return { ns: this.mergeStateScope(actionIdOrKey, options), opts: options };
-        }
-        return { ns: this.mergeStateScope(undefined, keyOrOptions), opts: keyOrOptions };
+        this.assertOpen();
+        return await (await this.prepareStorageAsync()).deleteConfig(key);
     }
     /**
-     * 合并位置 actionId 与 options.actionId 并计算最终命名空间（单一事实源）。
-     *
-     * - positionalActionId 非 undefined：调用形态携带位置 actionId，
-     *   options.actionId 与其冲突时抛出异常（空串同样参与冲突校验）；
-     * - positionalActionId 为 undefined：无位置 actionId 的扁平调用形态，
-     *   options.actionId 属合法显式指定，直接采纳。
+     * 将可能携带命名空间前缀的状态键解码为 (namespace, key)。
+     * 解码失败时按无命名空间处理。
      */
-    mergeStateScope(positionalActionId, opts) {
-        let actionId;
-        if (positionalActionId !== undefined) {
-            actionId = positionalActionId;
-            if (opts?.actionId && opts.actionId !== actionId) {
-                throw new ActionDockError(INVALID_ARGUMENT, `Conflicting actionId specified: positional '${actionId}' vs options.actionId '${opts.actionId}'`);
-            }
+    decodeStateKeyParts(key) {
+        try {
+            const decoded = decodeStateKey(key);
+            return { namespace: decoded.namespace, key: decoded.key };
         }
-        else {
-            actionId = opts?.actionId ?? "";
+        catch {
+            return { namespace: "", key };
         }
+    }
+    hasExplicitStateScope(options) {
+        return options?.actionId !== undefined || options?.namespace !== undefined;
+    }
+    computeStateNamespace(options) {
+        const actionId = options?.actionId ?? "";
         return actionId
-            ? (opts?.namespace ? `${actionId}:${opts.namespace}` : actionId)
-            : (opts?.namespace ?? "");
-    }
-    async getState(actionIdOrKey, keyOrOptions, options) {
-        const { ns, opts } = this.resolveStateScope(actionIdOrKey, keyOrOptions, options);
-        const key = typeof keyOrOptions === "string" ? keyOrOptions : actionIdOrKey;
-        if (opts?.detail) {
-            const entry = await this.storage.findState(key, ns || undefined);
+            ? (options?.namespace ? `${actionId}:${options.namespace}` : actionId)
+            : (options?.namespace ?? "");
+    }
+    async getStateInternal(key, options) {
+        const storage = await this.prepareStorageAsync();
+        const explicitScope = this.hasExplicitStateScope(options);
+        const ns = this.computeStateNamespace(options);
+        if (options?.detail) {
+            const entry = await storage.findState(key, explicitScope ? ns : undefined);
             return entry;
         }
-        if (ns) {
-            return await this.storage.getState(ns, key);
+        if (explicitScope || ns) {
+            return await storage.getState(ns, key);
         }
-        const entry = await this.storage.findState(key);
+        const entry = await storage.findState(key);
         return entry?.value;
     }
-    async setState(actionIdOrKey, keyOrValue, valueOrOptions, options) {
-        let key;
-        let value;
-        let opts;
-        // 携带位置 actionId 的调用形态标记：undefined 表示扁平 (key, value[, options]) 形态
-        let positionalActionId;
-        // 消歧规则（与原始重载语义严格一致）：按实参个数区分三形态
-        if (arguments.length >= 4) {
-            positionalActionId = actionIdOrKey;
-            key = keyOrValue;
-            value = valueOrOptions;
-            opts = options;
-        }
-        else if (arguments.length === 2) {
-            key = actionIdOrKey;
-            value = keyOrValue;
-            opts = undefined;
-        }
-        else {
-            if (valueOrOptions !== undefined &&
-                (typeof valueOrOptions !== "object" || valueOrOptions === null || Array.isArray(valueOrOptions))) {
-                throw new ActionDockError(INVALID_ARGUMENT, "Invalid options provided to setState. Use setActionState(actionId, key, value, options) or 4-argument setState for action state.");
-            }
-            key = actionIdOrKey;
-            value = keyOrValue;
-            opts = valueOrOptions;
-        }
-        // 作用域解析与命名空间计算统一委托 mergeStateScope 单一事实源
-        const ns = this.mergeStateScope(positionalActionId, opts);
-        if (ns) {
-            await this.storage.setState(ns, key, value, opts?.ttl);
+    async setStateInternal(key, value, options) {
+        const storage = await this.prepareStorageAsync();
+        const explicitScope = this.hasExplicitStateScope(options);
+        const ns = this.computeStateNamespace(options);
+        if (explicitScope || ns) {
+            await storage.setState(ns, key, value, options?.ttl);
             return;
         }
-        let targetKey = key;
-        let targetNs = "";
-        try {
-            const decoded = decodeStateKey(key);
-            targetNs = decoded.namespace;
-            targetKey = decoded.key;
-        }
-        catch {
-            targetNs = "";
-        }
-        await this.storage.setState(targetNs, targetKey, value, opts?.ttl);
+        const target = this.decodeStateKeyParts(key);
+        await storage.setState(target.namespace, target.key, value, options?.ttl);
+    }
+    async deleteStateInternal(key, options) {
+        const storage = await this.prepareStorageAsync();
+        const explicitScope = this.hasExplicitStateScope(options);
+        const ns = this.computeStateNamespace(options);
+        if (explicitScope || ns) {
+            return await storage.deleteState(ns, key);
+        }
+        const target = this.decodeStateKeyParts(key);
+        return await storage.deleteState(target.namespace, target.key);
+    }
+    async listStateKeysInternal(options) {
+        const storage = await this.prepareStorageAsync();
+        if (options?.namespace === null) {
+            return storage.listStateKeys(null, options?.prefix);
+        }
+        const explicitScope = this.hasExplicitStateScope(options);
+        const ns = this.computeStateNamespace(options);
+        const targetNs = explicitScope ? ns : (ns ? ns : null);
+        return storage.listStateKeys(targetNs, options?.prefix);
+    }
+    async clearStateInternal(options) {
+        const storage = await this.prepareStorageAsync();
+        const explicitScope = this.hasExplicitStateScope(options);
+        const ns = this.computeStateNamespace(options);
+        const targetNs = options?.all ? undefined : (explicitScope ? ns : (ns ? ns : undefined));
+        return storage.clearState({
+            namespace: targetNs,
+            prefix: options?.prefix,
+            all: options?.all,
+        });
     }
-    async deleteState(actionIdOrKey, keyOrOptions, options) {
-        const { ns } = this.resolveStateScope(actionIdOrKey, keyOrOptions, options);
-        const key = typeof keyOrOptions === "string" ? keyOrOptions : actionIdOrKey;
-        if (ns) {
-            return await this.storage.deleteState(ns, key);
-        }
-        let targetKey = key;
-        let targetNs = "";
-        try {
-            const decoded = decodeStateKey(key);
-            targetNs = decoded.namespace;
-            targetKey = decoded.key;
-        }
-        catch {
-            targetNs = "";
-        }
-        return await this.storage.deleteState(targetNs, targetKey);
+    async getState(arg1, arg2, arg3) {
+        this.assertOpen();
+        const { key, options } = normalizeStateReadArgs(arg1, arg2, arg3);
+        return this.getStateInternal(key, options);
+    }
+    async setState(arg1, arg2, arg3, arg4) {
+        this.assertOpen();
+        const { key, value, options } = normalizeStateWriteArgs(arg1, arg2, arg3, arg4, arguments.length);
+        return this.setStateInternal(key, value, options);
+    }
+    async deleteState(arg1, arg2, arg3) {
+        this.assertOpen();
+        const { key, options } = normalizeStateReadArgs(arg1, arg2, arg3);
+        return this.deleteStateInternal(key, options);
     }
     async getActionState(actionId, key, options) {
-        const { ns, opts } = this.resolveStateScope(actionId, key, options);
-        if (opts?.detail) {
-            const entry = await this.storage.findState(key, ns || undefined);
-            return entry;
+        if (options?.actionId !== undefined && options.actionId !== actionId) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Conflicting actionId specified: positional '${actionId}' vs options.actionId '${options.actionId}'`);
         }
-        return await this.storage.getState(ns, key);
+        return this.getStateInternal(key, { ...options, actionId });
     }
     async setActionState(actionId, key, value, options) {
-        const { ns, opts } = this.resolveStateScope(actionId, key, options);
-        await this.storage.setState(ns, key, value, opts?.ttl);
+        if (options?.actionId !== undefined && options.actionId !== actionId) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Conflicting actionId specified: positional '${actionId}' vs options.actionId '${options.actionId}'`);
+        }
+        return this.setStateInternal(key, value, { ...options, actionId });
     }
     async deleteActionState(actionId, key, options) {
-        const { ns } = this.resolveStateScope(actionId, key, options);
-        return await this.storage.deleteState(ns, key);
+        if (options?.actionId !== undefined && options.actionId !== actionId) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Conflicting actionId specified: positional '${actionId}' vs options.actionId '${options.actionId}'`);
+        }
+        return this.deleteStateInternal(key, { ...options, actionId });
     }
     async listStateKeys(actionIdOrOptions, options) {
-        // 重载消歧：首参为字符串时是 (actionId, options) 调用（完成冲突校验后取其域）；
-        // 否则首参本身就是选项对象（或未传），取 options.actionId 或 namespace 扁平域
-        let ns;
-        if (typeof actionIdOrOptions === "string") {
-            ns = this.resolveStateScope(actionIdOrOptions, "", options).ns;
-        }
-        else {
-            const opts = actionIdOrOptions;
-            ns = opts?.actionId
-                ? (opts.namespace ? `${opts.actionId}:${opts.namespace}` : opts.actionId)
-                : (opts?.namespace ?? "");
-        }
-        const opts = typeof actionIdOrOptions === "string" ? options : actionIdOrOptions;
-        return this.storage.listStateKeys(ns ? ns : null, opts?.prefix);
+        this.assertOpen();
+        const normalizedOptions = normalizeStateScopeArgs(actionIdOrOptions, options);
+        return this.listStateKeysInternal(normalizedOptions);
     }
     async clearState(actionIdOrOptions, options) {
-        // 首参为字符串时是 (actionId, options) 调用：以伪 key 消费冲突校验后取其 actionId 域；
-        // 否则首参本身就是选项对象（或未传），直接走扁平分支
-        if (typeof actionIdOrOptions === "string") {
-            const { ns } = this.resolveStateScope(actionIdOrOptions, "", options);
-            const finalNs = ns || (options?.namespace ?? "");
-            return this.storage.clearState({
-                namespace: finalNs ? finalNs : undefined,
-                prefix: options?.prefix,
-                all: options?.all,
-            });
-        }
-        const opts = actionIdOrOptions;
-        const ns = opts?.namespace;
-        return this.storage.clearState({
-            namespace: ns ? ns : undefined,
-            prefix: opts?.prefix,
-            all: opts?.all,
-        });
+        this.assertOpen();
+        const normalizedOptions = normalizeStateScopeArgs(actionIdOrOptions, options);
+        return this.clearStateInternal(normalizedOptions);
     }
     async listRuns(options) {
-        return this.storage.listRuns({
+        this.assertOpen();
+        if (options?.signal?.aborted) {
+            throw createAbortError(options.signal.reason);
+        }
+        const storage = await this.prepareStorageAsync();
+        if (options?.signal?.aborted) {
+            throw createAbortError(options.signal.reason);
+        }
+        // requestId 反查路径：经 idempotency_keys 反查关联运行记录（存储可选能力）
+        if (options?.requestIds && options.requestIds.length > 0) {
+            if (typeof storage.listRunsByRequestIds !== "function") {
+                return [];
+            }
+            let records = storage.listRunsByRequestIds(options.requestIds);
+            if (options.actionId) {
+                records = records.filter((r) => r.actionId === options.actionId);
+            }
+            if (options.status) {
+                records = records.filter((r) => r.status === options.status);
+            }
+            records.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+            if (typeof options.offset === "number" && options.offset > 0) {
+                records = records.slice(options.offset);
+            }
+            if (options.limit !== undefined && records.length > options.limit) {
+                records.length = options.limit;
+            }
+            return records;
+        }
+        const records = storage.listRuns({
             actionId: options?.actionId,
             status: options?.status,
             limit: options?.limit,
+            offset: options?.offset,
+        });
+        // 常规路径补齐 requestId 关联（可选能力缺失时保持无关联，不阻断查询）
+        if (typeof storage.getRunRequestIds === "function" && records.length > 0) {
+            const requestIdByRunId = storage.getRunRequestIds(records.map((r) => r.id));
+            for (const record of records) {
+                const requestId = requestIdByRunId[record.id];
+                if (requestId)
+                    record.requestId = requestId;
+            }
+        }
+        return records;
+    }
+    async countRuns(options) {
+        this.assertOpen();
+        if (options?.signal?.aborted) {
+            throw createAbortError(options.signal.reason);
+        }
+        const storage = await this.prepareStorageAsync();
+        if (options?.signal?.aborted) {
+            throw createAbortError(options.signal.reason);
+        }
+        if (typeof storage.countRuns === "function") {
+            return storage.countRuns({
+                actionId: options?.actionId,
+                status: options?.status,
+                requestIds: options?.requestIds,
+            });
+        }
+        if (options?.requestIds && options.requestIds.length > 0) {
+            if (typeof storage.listRunsByRequestIds === "function") {
+                let records = storage.listRunsByRequestIds(options.requestIds);
+                if (options.actionId) {
+                    records = records.filter((r) => r.actionId === options.actionId);
+                }
+                if (options.status) {
+                    records = records.filter((r) => r.status === options.status);
+                }
+                return records.length;
+            }
+            return 0;
+        }
+        const records = storage.listRuns({
+            actionId: options?.actionId,
+            status: options?.status,
+            limit: 100_000,
         });
+        return records.length;
     }
     async clearRuns(options) {
-        return this.storage.clearRuns({
+        this.assertOpen();
+        return (await this.prepareStorageAsync()).clearRuns({
             actionId: options?.actionId,
             status: options?.status,
             olderThanMs: options?.olderThanMs,
@@ -586,14 +924,15 @@ export class DefaultPackageRuntime {
         });
     }
     async cleanExpiredRuns(policy) {
-        if (typeof this.storage.cleanExpiredRuns === "function") {
-            return this.storage.cleanExpiredRuns(policy);
-        }
-        return 0;
+        this.assertOpen();
+        const storage = await this.prepareStorageAsync();
+        return storage.cleanExpiredRuns?.(policy) ?? 0;
     }
     async listStateEntries(options) {
-        if (typeof this.storage.listStateEntries === "function") {
-            return this.storage.listStateEntries(options);
+        this.assertOpen();
+        const storage = await this.prepareStorageAsync();
+        if (typeof storage.listStateEntries === "function") {
+            return storage.listStateEntries(options);
         }
         throw new ActionDockError(CAPABILITY_UNAVAILABLE, `CAPABILITY_UNAVAILABLE: listStateEntries is not supported by package '${this.packageId}' storage`);
     }
@@ -601,20 +940,35 @@ export class DefaultPackageRuntime {
         if (this.isClosed)
             return;
         this.isClosed = true;
+        // 等待已经开始的资源准备结算；初始化完成后不把实例发布给已关闭对象
+        const pendingStorage = this.storageSlot.initPromise?.catch(() => undefined);
+        const pendingExecution = this.executionSlot.initPromise?.catch(() => undefined);
+        await Promise.allSettled([pendingStorage, pendingExecution]);
+        const service = this.executionSlot.instance;
+        this.executionSlot.instance = undefined;
+        this.executionSlot.initPromise = undefined;
         try {
-            await this.executionService.close(options);
+            if (service) {
+                await service.close(options);
+            }
         }
         finally {
+            const storage = this.storageSlot.instance;
+            this.storageSlot.instance = undefined;
+            this.storageSlot.initPromise = undefined;
             try {
-                this.storage.close();
+                storage?.close();
             }
             catch {
                 // 忽略存储重复关闭异常
             }
             finally {
-                if (!this.injectedGlobalStorage) {
+                // 共享全局库由 Host 关闭；独立包自建的全局库由包关闭；外部注入存储不在此关闭
+                const globalRes = this.globalStorageRes;
+                this.globalStorageRes = undefined;
+                if (globalRes?.kind === "own") {
                     try {
-                        this.globalStorage?.close();
+                        globalRes.storage.close();
                     }
                     catch {
                         // 忽略全局存储关闭异常