@actiondock/core 2.0.11 → 2.0.12

package/dist/schema/validator.d.ts

@@ -0,0 +1,28 @@
+import type { JsonSchema } from "@actiondock/sdk";
+/**
+ * JSON Schema 校验结果对象。
+ */
+export interface ValidationResult {
+    /** 数据是否完全符合 Schema 规范 */
+    valid: boolean;
+    /** 校验失败时的具体错误详情列表 */
+    errors?: string[];
+}
+/**
+ * 递归检查数据中是否包含危险的原型污染属性键名（__proto__、constructor、prototype）。
+ */
+export declare function hasDangerousKeys(data: unknown): boolean;
+/**
+ * 校验指定数据是否符合给定的 JSON Schema 契约。
+ *
+ * 行为与策略约定：
+ * 1. 严格契约校验：当 Schema 中定义 additionalProperties: false 时，包含未声明属性的输入将被直接拒绝（返回 valid: false），系统不会静默过滤或篡改用户输入。
+ * 2. 危险原型键硬拦截：输入数据或其任意嵌套对象中若出现 __proto__、constructor 或 prototype 键名，即使 Schema 允许亦立即拒绝，彻底杜绝原型污染。
+ * 3. 布尔 Schema：false 显式拒绝所有输入；true 或未定义时允许所有合法非污染数据。
+ * 4. 无原型对象支持：完全支持 Object.create(null) 创建的无原型对象校验。
+ *
+ * @param schema 期望匹配的 JSON Schema 对象（未提供或为空对象/true 时默认通过；为 false 时拒绝所有数据）
+ * @param data 待校验的原始数据
+ * @returns 包含 valid 状态与错误信息列表的 ValidationResult
+ */
+export declare function validateSchema(schema: JsonSchema | undefined, data: unknown): ValidationResult;

package/dist/server/body.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 默认单次 HTTP 请求体最大字节上限（1 MiB）。
+ */
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+/**
+ * 请求体超出最大允许体积时抛出的异常（对应 HTTP 413 Payload Too Large）。
+ */
+export declare class RequestTooLargeError extends Error {
+    code: string;
+    constructor(message?: string);
+}
+/**
+ * 请求体非合法 JSON 格式时抛出的异常（对应 HTTP 400 Bad Request）。
+ */
+export declare class InvalidJsonError extends Error {
+    code: string;
+    constructor(message?: string);
+}
+/**
+ * 请求体安全读取选项。
+ */
+export interface ReadJsonBodyOptions {
+    /** 最大允许的字节数（默认 1 MiB） */
+    maxBytes?: number;
+}
+/**
+ * 流式安全地读取 HTTP 请求体并解析为 JSON 对象。
+ *
+ * 防护机制：
+ * 1. 快速拒绝（Fast-path）：若请求头中存在 `Content-Length` 且超过 `maxBytes`，立即抛出 RequestTooLargeError，不进行内存分配。
+ * 2. 流式计数器（Chunk Streaming）：在读取 ReadableStream 过程中实时累计字节数，中途超出上限即刻截断并释放流锁，防止大文件 DoS 与内存耗尽（OOM）。
+ * 3. 安全解码：处理空请求体与 UTF-8 字符集解码。
+ *
+ * @param req 传入的 Request 对象
+ * @param options 读取配置选项
+ * @returns 解析后的 JSON 对象
+ * @throws {RequestTooLargeError} 若请求体体积超限
+ * @throws {InvalidJsonError} 若请求体非合法 JSON
+ */
+export declare function readJsonBody<T = any>(req: Request, options?: ReadJsonBodyOptions): Promise<T>;

package/{src/server/index.ts → dist/server/index.d.ts}

@@ -4,4 +4,3 @@ export * from "./body";
 export * from "./runtime-registry";
 export * from "./routes";
 export * from "./server";
-

package/dist/server/routes/actions.d.ts

@@ -0,0 +1,5 @@
+import { type RouteContext } from "./common";
+/**
+ * 处理 Action 列表、详情查询及同步/异步运行接口。
+ */
+export declare function handleActionsRoutes(ctx: RouteContext): Promise<Response | null>;

package/dist/server/routes/common.d.ts

@@ -0,0 +1,36 @@
+import type { RuntimeStorage } from "../../storage/types";
+import type { RunRecord } from "@actiondock/sdk";
+import type { ServerRuntimeRegistry } from "../runtime-registry";
+import type { ServerOptions } from "../types";
+/**
+ * 路由处理统一上下文对象。
+ */
+export interface RouteContext {
+    req: Request;
+    url: URL;
+    pathname: string;
+    corsHeaders: Record<string, string>;
+    projectRoot: string | null;
+    customHome?: string;
+    runtimeRegistry: ServerRuntimeRegistry;
+    options: ServerOptions;
+}
+/**
+ * 辅助函数：构造带 CORS 头的标准 JSON HTTP 响应。
+ */
+export declare function jsonResponse(data: unknown, status?: number, corsHeaders?: Record<string, string>): Response;
+/**
+ * 依据 package 参数或项目上下文解析目标 Storage 实例与根目录。
+ */
+export declare function resolveStorageForPackage(packageIdOrPath: string | undefined, runtimeRegistry: ServerRuntimeRegistry, projectRoot?: string | null, customHome?: string): {
+    packageId: string;
+    storage: RuntimeStorage;
+    projectRoot?: string;
+};
+/**
+ * 跨活跃连接与所有已知持久化存储全局检索指定 runId 的运行记录。
+ */
+export declare function findRunAcrossStorages(runId: string, runtimeRegistry: ServerRuntimeRegistry, projectRoot?: string | null, customHome?: string): {
+    storage: RuntimeStorage;
+    run: RunRecord;
+} | null;

package/dist/server/routes/config.d.ts

@@ -0,0 +1,5 @@
+import { type RouteContext } from "./common";
+/**
+ * 处理配置元数据与当前值读取、更新及删除接口。
+ */
+export declare function handleConfigRoutes(ctx: RouteContext): Promise<Response | null>;

package/dist/server/routes/doctor.d.ts

@@ -0,0 +1,5 @@
+import { type RouteContext } from "./common";
+/**
+ * 处理环境与依赖诊断接口（GET /api/v1/doctor）。
+ */
+export declare function handleDoctorRoute(ctx: RouteContext): Promise<Response | null>;

package/dist/server/routes/health.d.ts

@@ -0,0 +1,5 @@
+import { type RouteContext } from "./common";
+/**
+ * 处理健康检查与就绪状态接口（支持 /api/v1/health 与 /health）。
+ */
+export declare function handleHealthRoute(ctx: RouteContext): Promise<Response | null>;

package/dist/server/routes/info.d.ts

@@ -0,0 +1,5 @@
+import { type RouteContext } from "./common";
+/**
+ * 处理系统探索与自省接口（GET /api/v1/info）。
+ */
+export declare function handleInfoRoute(ctx: RouteContext): Promise<Response | null>;

package/dist/server/routes/playbooks.d.ts

@@ -0,0 +1,5 @@
+import { type RouteContext } from "./common";
+/**
+ * 处理 Playbook 列表与 SOP 详情接口。
+ */
+export declare function handlePlaybooksRoutes(ctx: RouteContext): Promise<Response | null>;

package/dist/server/routes/runs.d.ts

@@ -0,0 +1,5 @@
+import { type RouteContext } from "./common";
+/**
+ * 处理历史运行记录检索、清理、详情及 SSE 流式日志接口。
+ */
+export declare function handleRunsRoutes(ctx: RouteContext): Promise<Response | null>;

package/dist/server/routes/state.d.ts

@@ -0,0 +1,5 @@
+import { type RouteContext } from "./common";
+/**
+ * 处理状态键名列表、读取、写入、删除及清空接口。
+ */
+export declare function handleStateRoutes(ctx: RouteContext): Promise<Response | null>;

package/dist/server/runtime-registry.d.ts

@@ -0,0 +1,78 @@
+import type { ActionDefinition } from "@actiondock/sdk";
+import { DefaultExecutionService } from "../execution/service";
+import type { ProjectConfig } from "../project/types";
+import { ExecutionManager } from "../runtime/execution-manager";
+import type { RuntimeStorage } from "../storage/types";
+/**
+ * 服务端运行时注册表（ServerRuntimeRegistry）。
+ *
+ * 职责：
+ * 1. 在长期运行的 HTTP 服务端（`ad serve` / `ad mcp serve`）中，跨请求缓存并池化管理 SQLite 数据库存储连接。
+ * 2. 集中维护活跃的在途任务执行句柄（ExecutionManager）。
+ * 3. 服务端停止或优雅关机（Graceful Shutdown）时，统一中断在途任务并安全关闭所有数据库连接。
+ */
+export declare class ServerRuntimeRegistry {
+    private customHome?;
+    private storages;
+    private globalStorage?;
+    private listeners;
+    private executionServices;
+    executionManager: ExecutionManager;
+    constructor(customHome?: string);
+    /**
+     * 订阅指定 runId 的事件（用于 SSE 流式推送）。
+     */
+    subscribe(runId: string, listener: (event: {
+        type: string;
+        data: any;
+    }) => void): () => void;
+    /**
+     * 向指定 runId 的订阅者广播事件。
+     */
+    emit(runId: string, event: {
+        type: string;
+        data: any;
+    }): void;
+    /**
+     * 获取或懒加载指定 Package 和 projectRoot 的缓存 RuntimeStorage 实例。
+     *
+     * @param packageId 所属 Package ID
+     * @param projectRoot 项目根目录（可选）
+     * @returns 缓存或新创建的 RuntimeStorage 实例
+     */
+    getStorage(packageId: string, projectRoot?: string): RuntimeStorage;
+    /**
+     * 获取或懒加载统一 ExecutionService 实例。
+     */
+    getExecutionService(packageId: string, projectRoot?: string, projectConfig?: ProjectConfig, options?: {
+        storage?: RuntimeStorage;
+        actions?: Map<string, ActionDefinition>;
+        configOverrides?: Record<string, unknown>;
+    }): DefaultExecutionService;
+    /**
+     * 获取或懒加载全局共享持久化存储实例（~/.actiondock/global.db）。
+     * 实现全局数据库单例池化，避免重复创建连接泄漏。
+     *
+     * @param customHome 自定义家目录路径（可选）
+     */
+    getGlobalStorage(customHome?: string): RuntimeStorage;
+    /**
+     * 获取当前缓存的所有活跃 RuntimeStorage 实例列表。
+     */
+    getAllStorages(): RuntimeStorage[];
+    /**
+     * 跨所有已建立的存储连接全局查找指定 runId 的运行记录。
+     *
+     * @param runId 目标运行 ID
+     */
+    findRun(runId: string): {
+        storage: RuntimeStorage;
+        run: import("@actiondock/sdk").RunRecord;
+    } | undefined;
+    /**
+     * 优雅关机：中断所有在途异步任务并安全关闭所有 SQLite 存储连接。
+     */
+    close(options?: {
+        graceMs?: number;
+    }): Promise<void>;
+}

package/dist/server/security.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 恒定时间字符串比较（Constant-time comparison）。
+ * 使用底层的 `crypto.timingSafeEqual` 防范时序攻击（Timing Attack）。
+ *
+ * @param a 字符串 A
+ * @param b 字符串 B
+ * @returns 两个字符串内容是否完全一致
+ */
+export declare function safeEqual(a: string, b: string): boolean;
+/**
+ * 检查指定的主机地址是否为本地回环接口（Loopback Host）。
+ * 支持 127.0.0.1, localhost, ::1 等形式。
+ *
+ * @param host 主机名或 IP 字符串
+ */
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * 校验 HTTP 请求中的鉴权令牌是否有效。
+ *
+ * 支持两种凭证携带模式（均通过恒定时间对比）：
+ * 1. HTTP 请求头: `Authorization: Bearer <token>`
+ * 2. URL 查询参数: `?token=<token>`（便于浏览器/Web 调试）
+ *
+ * @param req 传入的 HTTP Request 对象
+ * @param expectedToken 服务端预期的正确 Token（若未配置 Token 则默认放行）
+ * @returns 是否鉴权成功
+ */
+export declare function verifyBearerToken(req: Request, expectedToken?: string): boolean;
+/**
+ * 根据配置的 CORS 白名单解析并返回跨域响应头。
+ * 默认情况下若未配置 corsOrigins，返回空对象（即默认关闭跨域访问，防范 CSRF）。
+ *
+ * @param origin 请求头中的 Origin 字段
+ * @param allowedOrigins 允许跨域的白名单来源数组
+ * @returns 包含 Access-Control-* 的响应头对象
+ */
+export declare function resolveCorsHeaders(origin: string | null, allowedOrigins?: string[]): Record<string, string>;

package/dist/server/server.d.ts

@@ -0,0 +1,15 @@
+import type { ActionDockServerInstance, CoreHttpServerFactory, CoreHttpServerInstance, ServerOptions } from "./types";
+/**
+ * 注册自定义 HTTP 服务端工厂（用于 Node.js / Bun 运行时环境适配）。
+ */
+export declare function setHttpServerFactory(factory: CoreHttpServerFactory): void;
+/**
+ * 根据当前运行时环境启动标准 Web Request/Response 兼容的 HTTP 服务。
+ */
+export declare function launchHttpServer(port: number, host: string, fetchHandler: (req: Request) => Promise<Response>): Promise<CoreHttpServerInstance>;
+/**
+ * 启动 ActionDock 2.0 原生轻量级 HTTP 服务装配中枢。
+ *
+ * 仅负责中间件流转、认证拦截、路由分发与服务生命周期管理。
+ */
+export declare function startActionDockServer(options?: ServerOptions): Promise<ActionDockServerInstance>;

package/dist/server/types.d.ts

@@ -0,0 +1,59 @@
+import type { ServerRuntimeRegistry } from "./runtime-registry";
+export interface CoreHttpServerInstance {
+    port: number;
+    stop: (closeActiveConnections?: boolean) => void | Promise<void>;
+    ready?: Promise<void>;
+}
+export type CoreHttpServerFactory = (options: {
+    port: number;
+    host: string;
+    fetch: (req: Request) => Promise<Response>;
+}) => CoreHttpServerInstance | Promise<CoreHttpServerInstance>;
+/**
+ * 启动 ActionDock HTTP Runner 服务端的配置选项。
+ */
+export interface ServerOptions {
+    /** 监听端口号（默认 5177） */
+    port?: number;
+    /** 绑定监听的主机地址（默认 "127.0.0.1"） */
+    host?: string;
+    /** 用于 HTTP Bearer Token 鉴权的密钥令牌 */
+    token?: string;
+    /** 服务的项目根目录（可选，若未指定则自动向上查找或进入全局 Registry 模式） */
+    projectRoot?: string;
+    /** 自定义 ActionDock 用户家目录 */
+    customHome?: string;
+    /** 是否允许非回环地址（如 0.0.0.0）在未配置 Token 的情况下启动（不安全） */
+    allowInsecureNoAuth?: boolean;
+    /** 允许跨域请求的 CORS Origin 白名单列表 */
+    corsOrigins?: string[];
+    /** 允许访问执行的 Package ID 白名单列表（为空允许全部） */
+    packageAllowlist?: string[];
+    /** 最大允许的请求体字节限制（默认 1MB，防 DoS） */
+    maxBodyBytes?: number;
+    /** 是否在 health 和 info 接口中透传本地 projectRoot 等调试路径 */
+    exposeDebugInfo?: boolean;
+    /** 是否启用一体化 MCP 协议支持（默认开启） */
+    enableMcp?: boolean;
+    /** 自定义 MCP 请求处理器钩子（若挂载则 /mcp 路由交由其处理） */
+    mcpHandler?: (req: Request) => Promise<Response | null | undefined> | Response | null | undefined;
+}
+/**
+ * 已启动的 ActionDock HTTP Runner 实例句柄。
+ */
+export interface ActionDockServerInstance {
+    /** 实际监听的端口号 */
+    port: number;
+    /** 实际绑定的主机地址 */
+    host: string;
+    /** 服务端可访问的基础 URL（如 "http://127.0.0.1:5177"） */
+    url: string;
+    /** 关联的 ServerRuntimeRegistry 运行时注册表 */
+    runtimeRegistry?: ServerRuntimeRegistry;
+    /** 服务就绪 Promise（可等待端口解析与监听建立） */
+    ready?: Promise<void>;
+    /** 优雅关闭服务端并释放所有存储连接 */
+    stop: (options?: {
+        graceMs?: number;
+    }) => Promise<void> | void;
+}

package/dist/storage/driver.d.ts

@@ -0,0 +1,15 @@
+import type { SqliteDriver } from "./types";
+export type SqliteDriverFactory = (dbPath: string) => SqliteDriver;
+/**
+ * 获取当前注册的全局默认 SQLite 驱动工厂。
+ */
+export declare function getSqliteDriverFactory(): SqliteDriverFactory | undefined;
+/**
+ * 注册全局默认 SQLite 驱动工厂。
+ */
+export declare function setSqliteDriverFactory(factory: SqliteDriverFactory): void;
+/**
+ * 创建默认 SQLite 驱动实例。
+ * 优先使用外部注册的工厂，其次根据当前运行时环境自动适配。
+ */
+export declare function createDefaultSqliteDriver(dbPath: string): SqliteDriver;

package/dist/storage/index.d.ts

@@ -0,0 +1,44 @@
+import type { RuntimeStorage } from "./types";
+export * from "./driver";
+export * from "./mask";
+export * from "./sqlite";
+export * from "./types";
+/**
+ * 解析并计算目标 SQLite 数据库文件的绝对路径。
+ *
+ * 优先级规则：
+ * 1. inMemory: true -> 返回 ":memory:"
+ * 2. 显式指定 dataDir -> 返回 `<dataDir>/<packageId>/runtime.db`
+ * 3. 显式指定 projectRoot（开发态项目） -> 返回 `<projectRoot>/.actiondock/runtime.db`
+ * 4. 默认独立二进制存储路径 -> 返回 `~/.actiondock/data/<packageId>/runtime.db`
+ *
+ * @param packageId 所属 Package ID
+ * @param options 路径解析选项
+ */
+export declare function resolveDatabasePath(packageId: string, options?: {
+    projectRoot?: string;
+    dataDir?: string;
+    inMemory?: boolean;
+}): string;
+/**
+ * 工厂函数：为指定 Package 创建或连接 RuntimeStorage 实例。
+ *
+ * @param packageId 目标 Package ID
+ * @param options 存储配置参数（支持 projectRoot, dataDir, inMemory）
+ */
+export declare function createStorage(packageId: string, options?: {
+    projectRoot?: string;
+    dataDir?: string;
+    inMemory?: boolean;
+}): RuntimeStorage;
+/**
+ * 工厂函数：创建或连接 ActionDock 全局共享数据库（~/.actiondock/global.db）。
+ * 用于跨 Package 共享的全局配置项存储。
+ *
+ * @param customHomeOrOptions 自定义家目录路径或配置对象（可选）
+ * @param dataDirArg 自定义数据存储目录（可选）
+ */
+export declare function createGlobalStorage(customHomeOrOptions?: string | {
+    customHome?: string;
+    dataDir?: string;
+}, dataDirArg?: string): RuntimeStorage;

package/{src/storage/mask.ts → dist/storage/mask.d.ts}

@@ -1,34 +1,19 @@
 import type { ConfigItemDefinition } from "../project/types";
-
 /**
  * 检查指定配置项是否为敏感数据（密码、私钥、Token、密钥等）。
- * 
+ *
  * 判定逻辑：
  * 1. 若 actiondock.json 中显式声明了 `secret: true`，直接判定为敏感。
  * 2. 若未显式声明，使用正则探测包含 PASSWORD/SECRET/TOKEN/KEY/PASS/AUTH/CREDENTIAL/PRIVATE_KEY 的通用敏感命名特征。
- * 
+ *
  * @param key 配置键名
  * @param declaredItem 项目中声明的配置元数据（可选）
  */
-export function isSecretConfigKey(
-  key: string,
-  declaredItem?: ConfigItemDefinition
-): boolean {
-  if (declaredItem?.secret === true) {
-    return true;
-  }
-  // 匹配常见敏感词命名特征
-  return /^(.*_)?(PASSWORD|SECRET|TOKEN|KEY|PASS|AUTH|CREDENTIAL|PRIVATE_KEY)(_.*)?$/i.test(key);
-}
-
+export declare function isSecretConfigKey(key: string, declaredItem?: ConfigItemDefinition): boolean;
 /**
  * 对敏感数据的值进行掩码脱敏处理（返回 "********"）。
- * 
+ *
  * @param value 原始数据值
  * @returns 掩码脱敏后的安全展示字符串
  */
-export function maskSecretValue(value: unknown): string {
-  if (value === undefined) return "undefined";
-  if (value === null) return "null";
-  return "********";
-}
+export declare function maskSecretValue(value: unknown): string;

package/dist/storage/sqlite.d.ts

@@ -0,0 +1,66 @@
+import { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, type RuntimeError, type RunRecord } from "@actiondock/sdk";
+import type { RuntimeStorage, StateEntry, StorageOptions, TerminalRunStatus } from "./types";
+export { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, };
+/**
+ * 统一 SQLite 运行时存储实现。
+ * 通过 SqliteDriver 抽象驱动，解耦底层具体运行时引擎（Node.js / Bun）。
+ */
+export declare class SqliteRuntimeStorage implements RuntimeStorage {
+    private driver;
+    private packageId;
+    private clock;
+    private isClosed;
+    private statementCache;
+    get isOpen(): boolean;
+    get closed(): boolean;
+    constructor(options: StorageOptions);
+    /**
+     * 初始化数据库结构并执行无损版本升级。
+     */
+    private init;
+    /**
+     * 重启恢复：将未正常结算的 running 状态自动收敛为 interrupted
+     */
+    recoverRunningRuns(): number;
+    /**
+     * 获取或复用预编译 SQL 语句缓存。
+     */
+    private getStatement;
+    getConfig<T = unknown>(key: string): T | undefined;
+    listConfig(): Record<string, unknown>;
+    setConfig(key: string, value: unknown): void;
+    deleteConfig(key: string): boolean;
+    getState<T = unknown>(namespace: string, key: string): Promise<T | undefined>;
+    private findMatchingStateRows;
+    findState<T = unknown>(targetKey: string, namespace?: string): Promise<StateEntry | undefined>;
+    setState<T = unknown>(namespace: string, key: string, value: T, ttl?: number): Promise<void>;
+    deleteState(namespace: string, key: string): Promise<boolean>;
+    deleteStateSmart(targetKey: string, namespace?: string): Promise<boolean>;
+    /**
+     * 清理已过期的状态记录
+     */
+    cleanExpiredState(): Promise<number>;
+    clearState(options?: {
+        namespace?: string;
+        all?: boolean;
+        prefix?: string;
+    }): Promise<number>;
+    listStateKeys(namespace?: string | null, prefix?: string): Promise<string[]>;
+    listStateEntries(options?: {
+        namespace?: string;
+        prefix?: string;
+    }): Promise<StateEntry[]>;
+    createRun(record: RunRecord | any): void;
+    updateRun(id: string, status: TerminalRunStatus, output?: unknown, error?: RuntimeError, finishedAt?: string): void;
+    getRun(id: string): RunRecord | null;
+    listRuns(options?: {
+        actionId?: string;
+        limit?: number;
+    }): RunRecord[];
+    clearRuns(options?: {
+        actionId?: string;
+        status?: string;
+    }): number;
+    private mapRunRecord;
+    close(): void;
+}

package/dist/storage/types.d.ts

@@ -0,0 +1,121 @@
+import type { RuntimeError, RunRecord } from "@actiondock/sdk";
+import type { Clock } from "../runtime/clock";
+/**
+ * SQLite 基础参数值类型。
+ */
+export type SqlValue = null | number | string | Uint8Array;
+/**
+ * SQLite 位置参数数组。
+ */
+export type SqlParams = readonly SqlValue[];
+/**
+ * 编译后的 SQLite 参数化语句接口。
+ */
+export interface SqliteStatement {
+    run(...params: any[]): {
+        changes: number;
+        lastInsertRowid?: number | bigint;
+    };
+    get<T>(...params: any[]): T | undefined;
+    all<T>(...params: any[]): T[];
+}
+/**
+ * 统一 SQLite 驱动层接口。
+ */
+export interface SqliteDriver {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement;
+    transaction<T>(fn: () => T extends PromiseLike<unknown> ? never : T): T;
+    close(): void;
+}
+/**
+ * 数据库中存储的配置条目实体。
+ */
+export interface ConfigEntry {
+    /** 所属 Package ID */
+    packageId: string;
+    /** 配置键名 */
+    key: string;
+    /** 配置值（JSON 序列化存储） */
+    value: unknown;
+    /** 最近更新时间（ISO 8601 格式） */
+    updatedAt: string;
+}
+/**
+ * 数据库中存储的状态条目实体。
+ */
+export interface StateEntry {
+    /** 所属 Package ID */
+    packageId: string;
+    /** 状态隔离命名空间 */
+    namespace: string;
+    /** 状态键名 */
+    key: string;
+    /** 复合完整键名 */
+    fullKey: string;
+    /** 状态值（JSON 序列化存储） */
+    value: unknown;
+    /** 最近更新时间（ISO 8601 格式） */
+    updatedAt: string;
+    /** 自动过期时间戳（ISO 8601 格式，null/undefined 表示不过期） */
+    expiresAt?: string;
+}
+/**
+ * 初始化存储引擎所需的选项。
+ */
+export interface StorageOptions {
+    /** SQLite 数据库文件绝对路径，或 ":memory:" 表示内存数据库 */
+    dbPath?: string;
+    /** 所绑定的 Package ID */
+    packageId: string;
+    /** 显式注入的 SQLite 底层驱动 */
+    driver?: SqliteDriver;
+    /** 可选注入的时间提供器，便于与模拟时钟联动 */
+    clock?: Clock;
+}
+/**
+ * Action 执行终态枚举。
+ */
+export type TerminalRunStatus = "success" | "failed" | "cancelled" | "timed_out" | "interrupted";
+/**
+ * 统一运行时存储抽象接口。
+ */
+export interface RuntimeStorage {
+    /** 数据库是否处于打开状态 */
+    readonly isOpen?: boolean;
+    /** 数据库是否已关闭 */
+    readonly closed?: boolean;
+    getConfig<T = unknown>(key: string): T | undefined;
+    listConfig(): Record<string, unknown>;
+    setConfig(key: string, value: unknown): void;
+    deleteConfig(key: string): 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>;
+    deleteState(namespace: string, key: string): Promise<boolean>;
+    deleteStateSmart(targetKey: string, namespace?: string): Promise<boolean>;
+    clearState(options?: {
+        namespace?: string;
+        all?: boolean;
+        prefix?: string;
+    }): Promise<number>;
+    cleanExpiredState?(): Promise<number>;
+    listStateKeys(namespace?: string | null, prefix?: string): Promise<string[]>;
+    listStateEntries(options?: {
+        namespace?: string;
+        prefix?: string;
+    }): Promise<StateEntry[]>;
+    createRun(record: RunRecord): void;
+    updateRun(id: string, status: TerminalRunStatus, output?: unknown, error?: RuntimeError, finishedAt?: string): void;
+    getRun(id: string): RunRecord | null;
+    listRuns(options?: {
+        actionId?: string;
+        limit?: number;
+    }): RunRecord[];
+    clearRuns(options?: {
+        actionId?: string;
+        status?: string;
+    }): number;
+    /** 关闭底层 SQLite 数据库连接并释放句柄 */
+    close(): void;
+}