@actiondock/core 2.0.12 → 2.2.1

package/dist/storage/types.d.ts

@@ -1,5 +1,9 @@
 import type { RuntimeError, RunRecord } from "@actiondock/sdk";
-import type { Clock } from "../runtime/clock";
+import type { Clock } from "../runtime/clock.js";
+/**
+ * 固定的存储 Schema 目标版本常量。
+ */
+export declare const STORAGE_SCHEMA_VERSION = 2;
 /**
  * SQLite 基础参数值类型。
  */
@@ -20,7 +24,13 @@ export interface SqliteStatement {
     all<T>(...params: any[]): T[];
 }
 /**
- * 统一 SQLite 驱动层接口。
+ * 统一 SQLite 驱动层接口（严格同步契约）。
+ *
+ * 本契约为同步驱动：exec、prepare 与 transaction 全部以同步语义返回结果，
+ * 不接受任何 Promise 或异步实现。SqliteRuntimeStorage 的公共同步方法
+ * （getConfig、listConfig、getRun、listRuns、checkAndRecordIdempotency 等）
+ * 直接依赖这一同步保证。异步驱动（如 runtime-node 的 WorkerSqliteDriver）
+ * 不应注入本契约，需通过 RuntimeStorage 的异步外观层另行适配。
  */
 export interface SqliteDriver {
     exec(sql: string): void;
@@ -68,15 +78,48 @@ export interface StorageOptions {
     dbPath?: string;
     /** 所绑定的 Package ID */
     packageId: string;
-    /** 显式注入的 SQLite 底层驱动 */
+    /** 显式注入的 SQLite 底层驱动（必须满足同步 SqliteDriver 契约） */
     driver?: SqliteDriver;
     /** 可选注入的时间提供器，便于与模拟时钟联动 */
     clock?: Clock;
 }
+/**
+ * 数据库中存储的幂等请求去重记录实体。
+ */
+export interface IdempotencyRecord {
+    /** 鉴权主体标识 */
+    ownerId: string;
+    /** 完全限定动作标识 */
+    actionRef: string;
+    /** 客户端幂等请求标识 */
+    requestId: string;
+    /** 输入参数与选项的 SHA-256 规范化摘要 */
+    inputDigest: string;
+    /** 关联的运行记录标识 */
+    runId: string;
+    /** 创建时间戳（ISO 8601 格式） */
+    createdAt?: string;
+}
+/**
+ * 幂等检查与登记结果。
+ */
+export type IdempotencyCheckResult = {
+    outcome: "new";
+} | {
+    outcome: "duplicate";
+    runId: string;
+} | {
+    outcome: "conflict";
+    existingDigest: string;
+};
 /**
  * Action 执行终态枚举。
  */
 export type TerminalRunStatus = "success" | "failed" | "cancelled" | "timed_out" | "interrupted";
+/**
+ * 判断指定运行状态是否为终态（收敛 success, failed, cancelled, timed_out, interrupted）。
+ */
+export declare function isTerminalRunStatus(status: string): status is TerminalRunStatus;
 /**
  * 统一运行时存储抽象接口。
  */
@@ -87,8 +130,8 @@ export interface RuntimeStorage {
     readonly closed?: boolean;
     getConfig<T = unknown>(key: string): T | undefined;
     listConfig(): Record<string, unknown>;
-    setConfig(key: string, value: unknown): void;
-    deleteConfig(key: string): boolean;
+    setConfig(key: string, value: unknown): void | Promise<void>;
+    deleteConfig(key: string): boolean | Promise<boolean>;
     getState<T = unknown>(namespace: string, key: string): Promise<T | undefined>;
     findState<T = unknown>(targetKey: string, namespace?: string): Promise<StateEntry | undefined>;
     setState<T = unknown>(namespace: string, key: string, value: T, ttl?: number): Promise<void>;
@@ -116,6 +159,14 @@ export interface RuntimeStorage {
         actionId?: string;
         status?: string;
     }): number;
+    /** 故障重启恢复：将遗留非终态运行收敛为 interrupted */
+    recoverRunningRuns?(currentHostSessionId?: string): number | Promise<number>;
+    /** 收敛死亡会话遗留的非终态运行任务 */
+    recoverDeadSessionRuns?(currentHostSessionId?: string): number | Promise<number>;
+    /** 确保底层存储与 Schema 初始化完成 */
+    ensureInitialized?(): Promise<void>;
+    checkAndRecordIdempotency?(record: IdempotencyRecord): IdempotencyCheckResult;
+    getIdempotencyRecord?(ownerId: string, actionRef: string, requestId: string): IdempotencyRecord | undefined;
     /** 关闭底层 SQLite 数据库连接并释放句柄 */
-    close(): void;
+    close(): void | Promise<void>;
 }

package/dist/storage/types.js

@@ -0,0 +1,14 @@
+/**
+ * 固定的存储 Schema 目标版本常量。
+ */
+export const STORAGE_SCHEMA_VERSION = 2;
+/**
+ * 判断指定运行状态是否为终态（收敛 success, failed, cancelled, timed_out, interrupted）。
+ */
+export function isTerminalRunStatus(status) {
+    return (status === "success" ||
+        status === "failed" ||
+        status === "cancelled" ||
+        status === "timed_out" ||
+        status === "interrupted");
+}

package/dist/target/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./local.js";
+export * from "./remote.js";
+export * from "./target.js";

package/dist/target/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./local.js";
+export * from "./remote.js";
+export * from "./target.js";

package/dist/target/local.d.ts

@@ -0,0 +1,52 @@
+import type { ActionRef, ExecutionEvent, ExecutionResult, JsonValue, RunRecord } from "@actiondock/sdk";
+import type { ActionDockApp, ActionSpec, ActionSummary, ListActionsOptions, PackageInfo, PlaybookSpec, PlaybookSummary } from "../app/types.js";
+import type { CancelResult, ExecuteOptions, ExecutionTicket } from "../execution/types.js";
+import type { ActionDockHost } from "../host/types.js";
+import type { StateEntry } from "../storage/types.js";
+import { type ActionDockTarget, type ConfigValueView, type ListRunsOptions, type StateScopeOptions, type TargetInfo } from "./types.js";
+/**
+ * 本地 ActionDockTarget 门面实现。
+ * 内部包装 ActionDockHost 或 ActionDockApp，将统一调用直接转交给 Host 或 App。
+ */
+export declare class LocalActionDockTarget implements ActionDockTarget {
+    readonly target: ActionDockHost | ActionDockApp;
+    constructor(target: ActionDockHost | ActionDockApp);
+    unwrap(): ActionDockHost | ActionDockApp;
+    info(): Promise<TargetInfo>;
+    listPackages(): Promise<PackageInfo[]>;
+    listActions(options?: ListActionsOptions): Promise<ActionSummary[]>;
+    describeAction(ref: ActionRef | string): Promise<ActionSpec>;
+    listPlaybooks(): Promise<PlaybookSummary[]>;
+    describePlaybook(id: string): Promise<PlaybookSpec>;
+    runAction(ref: ActionRef | string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionResult>;
+    startAction(ref: ActionRef | string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionTicket>;
+    listRuns(options?: ListRunsOptions): Promise<RunRecord[]>;
+    clearRuns(options?: {
+        packageId?: string;
+        actionId?: string;
+        status?: string;
+    }): Promise<number>;
+    getRun(runId: string): Promise<RunRecord | undefined>;
+    cancelRun(runId: string, reason?: string): Promise<CancelResult>;
+    events(runId: string, options?: {
+        after?: number | string;
+        signal?: AbortSignal;
+        maxQueueSize?: number;
+    }): AsyncIterable<ExecutionEvent>;
+    private resolveApp;
+    private getGlobalStorage;
+    private findDeclaredConfigItem;
+    getConfig(packageId: string, key: string): Promise<ConfigValueView>;
+    setConfig(packageId: string, key: string, value: JsonValue): Promise<void>;
+    deleteConfig(packageId: string, key: string): Promise<boolean>;
+    listConfig(packageId: string): Promise<ConfigValueView[]>;
+    getState<T extends JsonValue = JsonValue>(packageId: string, actionId: string, key: string, options?: StateScopeOptions): Promise<T | undefined>;
+    setState<T extends JsonValue = JsonValue>(packageId: string, actionId: string, key: string, value: T, options?: StateScopeOptions): Promise<void>;
+    deleteState(packageId: string, actionId: string, key: string, options?: StateScopeOptions): Promise<boolean>;
+    listStateKeys(packageId: string, actionId: string, options?: StateScopeOptions): Promise<string[]>;
+    clearState(packageId: string, actionId: string, options?: StateScopeOptions): Promise<number>;
+    listStateEntries(packageId: string, options?: any): Promise<StateEntry[]>;
+    close(options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+}

package/dist/target/local.js

@@ -0,0 +1,343 @@
+import { createGlobalStorage, isSecretConfigKey } from "../storage/index.js";
+import { ACTIONDOCK_PROTOCOL_VERSION, TargetError, CloseTimeoutError, TARGET_CAPABILITY_UNAVAILABLE, } from "./types.js";
+/**
+ * 本地 ActionDockTarget 门面实现。
+ * 内部包装 ActionDockHost 或 ActionDockApp，将统一调用直接转交给 Host 或 App。
+ */
+export class LocalActionDockTarget {
+    target;
+    constructor(target) {
+        this.target = target;
+    }
+    unwrap() {
+        return this.target;
+    }
+    async info() {
+        const packages = await this.listPackages();
+        let id = "local-host";
+        let name = "Local Host";
+        if ("listApps" in this.target) {
+            id = this.target.id || "local-host";
+            name = this.target.name || "Local Host";
+        }
+        else {
+            id = this.target.packageId;
+            name = packages[0]?.name || this.target.packageId;
+        }
+        return {
+            id,
+            name,
+            protocolVersion: ACTIONDOCK_PROTOCOL_VERSION,
+            packages,
+            capabilities: [
+                "actions",
+                "playbooks",
+                "runs",
+                "events",
+                "management.config",
+                "management.state",
+            ],
+            idempotencyPolicy: {
+                retentionMs: 86400000,
+                header: "x-request-id",
+            },
+        };
+    }
+    async listPackages() {
+        if ("listApps" in this.target) {
+            const apps = this.target.listApps();
+            return Promise.all(apps.map((app) => app.info()));
+        }
+        else {
+            return [await this.target.info()];
+        }
+    }
+    async listActions(options) {
+        return this.target.listActions(options);
+    }
+    async describeAction(ref) {
+        if ("getApp" in this.target) {
+            return this.target.describeAction(ref);
+        }
+        else {
+            const actionId = typeof ref === "string" ? ref : ref.actionId;
+            return this.target.describeAction(actionId);
+        }
+    }
+    async listPlaybooks() {
+        return this.target.listPlaybooks();
+    }
+    async describePlaybook(id) {
+        return this.target.describePlaybook(id);
+    }
+    async runAction(ref, input, options) {
+        if ("listApps" in this.target) {
+            return this.target.runAction(ref, input, options);
+        }
+        const actionId = typeof ref === "string" ? (ref.includes(":") ? ref.split(":").pop() : ref) : ref.actionId;
+        return this.target.runAction(actionId, input, options);
+    }
+    async startAction(ref, input, options) {
+        if ("listApps" in this.target) {
+            return this.target.startAction(ref, input, options);
+        }
+        const actionId = typeof ref === "string" ? (ref.includes(":") ? ref.split(":").pop() : ref) : ref.actionId;
+        return this.target.startAction(actionId, input, options);
+    }
+    async listRuns(options) {
+        if ("listApps" in this.target) {
+            const apps = options?.packageId
+                ? [this.target.getApp(options.packageId)].filter(Boolean)
+                : this.target.listApps();
+            let records = [];
+            for (const app of apps) {
+                const recs = app.storage.listRuns({
+                    actionId: options?.actionId,
+                    limit: options?.limit,
+                });
+                for (const r of recs) {
+                    records.push({
+                        ...r,
+                        packageId: r.packageId || app.packageId,
+                    });
+                }
+            }
+            records.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+            if (options?.status) {
+                records = records.filter((r) => r.status === options.status);
+            }
+            if (options?.limit && records.length > options.limit) {
+                records = records.slice(0, options.limit);
+            }
+            return records;
+        }
+        else {
+            if (options?.packageId && options.packageId !== this.target.packageId) {
+                return [];
+            }
+            let records = this.target.storage.listRuns({
+                actionId: options?.actionId,
+                limit: options?.limit,
+            });
+            if (options?.status) {
+                records = records.filter((r) => r.status === options.status);
+            }
+            if (options?.limit && records.length > options.limit) {
+                records = records.slice(0, options.limit);
+            }
+            return records;
+        }
+    }
+    async clearRuns(options) {
+        if ("listApps" in this.target) {
+            const apps = options?.packageId
+                ? [this.target.getApp(options.packageId)].filter(Boolean)
+                : this.target.listApps();
+            let total = 0;
+            for (const app of apps) {
+                total += app.storage.clearRuns({
+                    actionId: options?.actionId,
+                    status: options?.status,
+                });
+            }
+            return total;
+        }
+        else {
+            if (options?.packageId && options.packageId !== this.target.packageId) {
+                return 0;
+            }
+            return this.target.storage.clearRuns({
+                actionId: options?.actionId,
+                status: options?.status,
+            });
+        }
+    }
+    async getRun(runId) {
+        return this.target.getRun(runId);
+    }
+    async cancelRun(runId, reason) {
+        return this.target.cancelRun(runId, reason);
+    }
+    events(runId, options) {
+        return this.target.events(runId, options);
+    }
+    resolveApp(packageId) {
+        if ("listApps" in this.target) {
+            if (packageId) {
+                return this.target.getApp(packageId);
+            }
+            const apps = this.target.listApps();
+            return apps.length === 1 ? apps[0] : undefined;
+        }
+        else {
+            if (!packageId || packageId === this.target.packageId) {
+                return this.target;
+            }
+            return undefined;
+        }
+    }
+    getGlobalStorage() {
+        if ("globalStorage" in this.target && this.target.globalStorage) {
+            return this.target.globalStorage;
+        }
+        const apps = "listApps" in this.target ? this.target.listApps() : [];
+        for (const app of apps) {
+            if (app.globalStorage)
+                return app.globalStorage;
+        }
+        return createGlobalStorage({
+            dataDir: this.target.options?.dataDir,
+            customHome: this.target.options?.customHome,
+        });
+    }
+    findDeclaredConfigItem(key) {
+        if ("listApps" in this.target) {
+            let foundItem;
+            for (const app of this.target.listApps()) {
+                const item = app.projectConfig?.config?.[key];
+                if (item) {
+                    if (item.secret)
+                        return item;
+                    foundItem = item;
+                }
+            }
+            return foundItem;
+        }
+        else if ("projectConfig" in this.target) {
+            return this.target.projectConfig?.config?.[key];
+        }
+        return undefined;
+    }
+    async getConfig(packageId, key) {
+        if (packageId === "global") {
+            const globalStorage = this.getGlobalStorage();
+            const val = globalStorage.getConfig(key);
+            const configured = val !== undefined;
+            const declaredItem = this.findDeclaredConfigItem(key);
+            const isSecret = isSecretConfigKey(key, declaredItem);
+            return {
+                key,
+                configured,
+                secret: isSecret,
+                source: configured ? "global" : "default",
+                value: !isSecret && configured ? val : undefined,
+            };
+        }
+        const app = this.resolveApp(packageId);
+        if (!app) {
+            throw new Error(`Package '${packageId}' not found in target`);
+        }
+        return app.getConfig(key);
+    }
+    async setConfig(packageId, key, value) {
+        if (packageId === "global") {
+            await this.getGlobalStorage().setConfig(key, value);
+            return;
+        }
+        const app = this.resolveApp(packageId);
+        if (!app) {
+            throw new Error(`Package '${packageId}' not found in target`);
+        }
+        await app.setConfig(key, value);
+    }
+    async deleteConfig(packageId, key) {
+        if (packageId === "global") {
+            return await this.getGlobalStorage().deleteConfig(key);
+        }
+        const app = this.resolveApp(packageId);
+        if (!app) {
+            throw new Error(`Package '${packageId}' not found in target`);
+        }
+        return await app.deleteConfig(key);
+    }
+    async listConfig(packageId) {
+        if (packageId === "global") {
+            const globalStorage = this.getGlobalStorage();
+            const all = globalStorage.listConfig();
+            return Object.entries(all).map(([key, val]) => {
+                const declaredItem = this.findDeclaredConfigItem(key);
+                const isSecret = isSecretConfigKey(key, declaredItem);
+                return {
+                    key,
+                    configured: true,
+                    secret: isSecret,
+                    source: "global",
+                    value: isSecret ? undefined : val,
+                };
+            });
+        }
+        const app = this.resolveApp(packageId);
+        if (!app) {
+            throw new Error(`Package '${packageId}' not found in target`);
+        }
+        return app.listConfig();
+    }
+    async getState(packageId, actionId, key, options) {
+        const app = this.resolveApp(packageId);
+        if (!app) {
+            throw new Error(`Package '${packageId}' not found in target`);
+        }
+        return app.getState(actionId, key, options);
+    }
+    async setState(packageId, actionId, key, value, options) {
+        const app = this.resolveApp(packageId);
+        if (!app) {
+            throw new Error(`Package '${packageId}' not found in target`);
+        }
+        if (actionId) {
+            await app.setActionState(actionId, key, value, options);
+        }
+        else {
+            await app.setState(key, value, options);
+        }
+    }
+    async deleteState(packageId, actionId, key, options) {
+        const app = this.resolveApp(packageId);
+        if (!app) {
+            throw new Error(`Package '${packageId}' not found in target`);
+        }
+        return app.deleteState(actionId, key, options);
+    }
+    async listStateKeys(packageId, actionId, options) {
+        const app = this.resolveApp(packageId);
+        if (!app) {
+            throw new Error(`Package '${packageId}' not found in target`);
+        }
+        return app.listStateKeys(actionId, options);
+    }
+    async clearState(packageId, actionId, options) {
+        const app = this.resolveApp(packageId);
+        if (!app) {
+            throw new Error(`Package '${packageId}' not found in target`);
+        }
+        return app.clearState(actionId, options);
+    }
+    async listStateEntries(packageId, options) {
+        const app = this.resolveApp(packageId);
+        if (!app) {
+            throw new TargetError(TARGET_CAPABILITY_UNAVAILABLE, `TARGET_CAPABILITY_UNAVAILABLE: Package '${packageId}' not found in target`);
+        }
+        if (!app.storage || typeof app.storage.listStateEntries !== "function") {
+            throw new TargetError(TARGET_CAPABILITY_UNAVAILABLE, `TARGET_CAPABILITY_UNAVAILABLE: listStateEntries is not supported by package '${packageId}' storage`);
+        }
+        return app.storage.listStateEntries(options);
+    }
+    async close(options) {
+        if (options?.timeoutMs && options.timeoutMs > 0) {
+            let timer;
+            const timeoutPromise = new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    reject(new CloseTimeoutError(`Target close operation timed out after ${options.timeoutMs}ms`));
+                }, options.timeoutMs);
+            });
+            try {
+                await Promise.race([this.target.close(), timeoutPromise]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            return;
+        }
+        return this.target.close();
+    }
+}

package/dist/target/remote.d.ts

@@ -0,0 +1,76 @@
+import type { ActionRef, ExecutionEvent, ExecutionResult, JsonValue, RunRecord } from "@actiondock/sdk";
+import type { ActionSpec, ActionSummary, ListActionsOptions, PackageInfo, PlaybookSpec, PlaybookSummary } from "../app/types.js";
+import type { CancelResult, ExecuteOptions, ExecutionTicket } from "../execution/types.js";
+import { type StateEntry } from "../storage/types.js";
+import { type ActionDockTarget, type ConfigValueView, type ListRunsOptions, type RemoteTargetOptions, type StateScopeOptions, type TargetInfo } from "./types.js";
+/**
+ * 读取并解析远端 SSE 事件流。
+ */
+export declare function streamRemoteEvents(serverUrl: string, runId: string, token?: string, options?: {
+    after?: number | string;
+    signal?: AbortSignal;
+    maxQueueSize?: number;
+    allowInsecureHttp?: boolean;
+}): AsyncIterable<ExecutionEvent>;
+/**
+ * 远程 ActionDockTarget 门面实现。
+ * 内部封装基于 HTTP/SSE 协议与远端 ActionDock 服务端的通信管道。
+ */
+export declare class RemoteActionDockTarget implements ActionDockTarget {
+    readonly serverUrl: string;
+    readonly token?: string;
+    readonly timeoutMs?: number;
+    readonly baseTimeoutMs: number;
+    readonly allowInsecureHttp?: boolean;
+    constructor(options: RemoteTargetOptions);
+    info(): Promise<TargetInfo>;
+    listPackages(): Promise<PackageInfo[]>;
+    listActions(options?: ListActionsOptions): Promise<ActionSummary[]>;
+    describeAction(ref: ActionRef | string): Promise<ActionSpec>;
+    listPlaybooks(options?: {
+        intent?: string;
+        package?: string;
+    }): Promise<PlaybookSummary[]>;
+    describePlaybook(id: string): Promise<PlaybookSpec>;
+    runAction(ref: ActionRef | string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionResult>;
+    startAction(ref: ActionRef | string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionTicket>;
+    /**
+     * 等待远端运行抵达终态：优先监听 SSE 事件流，失败后按指数退避轮询运行详情。
+     *
+     * @param runId 运行标识
+     * @param signal 外部取消信号
+     * @param timeoutMs 运行自身声明的超时（等待上限取该值与默认上限中的较大者）
+     */
+    private waitForRunCompletion;
+    /**
+     * 指数退避轮询远端运行详情直至终态、取消或超时上限。
+     */
+    private pollRunCompletion;
+    private formatTerminalRunResult;
+    listRuns(options?: ListRunsOptions): Promise<RunRecord[]>;
+    clearRuns(options?: {
+        packageId?: string;
+        actionId?: string;
+        status?: string;
+    }): Promise<number>;
+    getRun(runId: string): Promise<RunRecord | undefined>;
+    cancelRun(runId: string, reason?: string): Promise<CancelResult>;
+    events(runId: string, options?: {
+        after?: number | string;
+        signal?: AbortSignal;
+        maxQueueSize?: number;
+    }): AsyncIterable<ExecutionEvent>;
+    getConfig(packageId: string, key: string): Promise<ConfigValueView>;
+    setConfig(packageId: string, key: string, value: JsonValue): Promise<void>;
+    deleteConfig(packageId: string, key: string): Promise<boolean>;
+    listConfig(packageId: string): Promise<ConfigValueView[]>;
+    getState<T extends JsonValue = JsonValue>(packageId: string, actionId: string, key: string, options?: StateScopeOptions): Promise<T | undefined>;
+    setState<T extends JsonValue = JsonValue>(packageId: string, actionId: string, key: string, value: T, options?: StateScopeOptions): Promise<void>;
+    deleteState(packageId: string, actionId: string, key: string, options?: StateScopeOptions): Promise<boolean>;
+    listStateKeys(packageId: string, actionId: string, options?: StateScopeOptions): Promise<string[]>;
+    clearState(packageId: string, actionId: string, options?: StateScopeOptions): Promise<number>;
+    listStateEntries(packageId: string, options?: any): Promise<StateEntry[]>;
+    close(_options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+}