@xgjktech/xg-openclaw-shared 0.2.2 → 0.2.4

package/dist/action-store.d.ts

@@ -0,0 +1,37 @@
+import type { ActionDispatchEvent } from "./action-types.js";
+export interface ActionStore {
+    get(eventId: string): ActionDispatchEvent | undefined;
+    set(event: ActionDispatchEvent): void;
+    delete(eventId: string): void;
+    list(): ActionDispatchEvent[];
+    listActionsByOrigin(origin: {
+        channel: string;
+        to: string;
+    }): ActionDispatchEvent[];
+}
+export declare class ActionStoreError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * SqliteActionStore：动作指令的唯一写者。读写走事务，异常一律转 ActionStoreError。
+ */
+export declare class SqliteActionStore implements ActionStore {
+    private readonly db;
+    constructor(dbPath: string);
+    close(): void;
+    get(eventId: string): ActionDispatchEvent | undefined;
+    set(event: ActionDispatchEvent): void;
+    delete(eventId: string): void;
+    list(): ActionDispatchEvent[];
+    listActionsByOrigin(origin: {
+        channel: string;
+        to: string;
+    }): ActionDispatchEvent[];
+}
+/**
+ * IM 侧只读入口：以 readOnly 模式打开同一 DB，杜绝误写。
+ */
+export declare function openActionStoreReadonly(dbPath: string): Pick<ActionStore, "get" | "list" | "listActionsByOrigin">;
+//# sourceMappingURL=action-store.d.ts.map

package/dist/action-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-store.d.ts","sourceRoot":"","sources":["../src/action-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;IACtD,GAAG,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACtC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,IAAI,mBAAmB,EAAE,CAAC;IAC9B,mBAAmB,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,mBAAmB,EAAE,CAAC;CACrF;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAsJD;;GAEG;AACH,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;gBAEtB,MAAM,EAAE,MAAM;IAI1B,KAAK,IAAI,IAAI;IAIb,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAIrD,GAAG,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;IAyCrC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ7B,IAAI,IAAI,mBAAmB,EAAE;IAI7B,mBAAmB,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,mBAAmB,EAAE;CAGpF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,GACb,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,MAAM,GAAG,qBAAqB,CAAC,CAkB3D"}

package/dist/action-store.js

@@ -0,0 +1,202 @@
+import { DatabaseSync } from "node:sqlite";
+export class ActionStoreError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ActionStoreError";
+    }
+}
+const BUSY_TIMEOUT_MS = 5000;
+const MAX_RETAIN_RECORDS = 1000;
+const RETENTION_MS = 7 * 24 * 60 * 60 * 1000; // 7 天
+const CREATE_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS actions (
+  event_id        TEXT PRIMARY KEY,
+  action          TEXT NOT NULL,
+  target          TEXT NOT NULL,
+  version         INTEGER NOT NULL,
+  origin_channel  TEXT,
+  origin_to       TEXT,
+  created_at      TEXT NOT NULL,
+  doc             TEXT NOT NULL
+) STRICT;
+`;
+const CREATE_INDEX_CREATED_AT_SQL = `
+CREATE INDEX IF NOT EXISTS idx_actions_created_at ON actions(created_at);
+`;
+const CREATE_INDEX_ORIGIN_SQL = `
+CREATE INDEX IF NOT EXISTS idx_actions_origin ON actions(origin_channel, origin_to);
+`;
+function listColumnNames(db) {
+    const rows = db.prepare("PRAGMA table_info(actions);").all();
+    return new Set(rows.map((row) => row.name));
+}
+function parseActionDoc(row) {
+    try {
+        return JSON.parse(row.doc);
+    }
+    catch (cause) {
+        throw new ActionStoreError(`action ${row.event_id} 的 doc 列不是合法 JSON`, { cause });
+    }
+}
+function ensureSchema(db) {
+    db.exec(CREATE_TABLE_SQL);
+    db.exec(CREATE_INDEX_CREATED_AT_SQL);
+    db.exec(CREATE_INDEX_ORIGIN_SQL);
+}
+function openDatabase(dbPath, options) {
+    try {
+        const db = new DatabaseSync(dbPath, { readOnly: options.readOnly });
+        db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS};`);
+        if (!options.readOnly) {
+            db.exec("PRAGMA journal_mode = WAL;");
+            ensureSchema(db);
+        }
+        return db;
+    }
+    catch (cause) {
+        throw new ActionStoreError(`打开 ActionStore 数据库失败: ${dbPath}`, { cause });
+    }
+}
+function readActionRow(db, eventId) {
+    return db
+        .prepare("SELECT event_id, action, target, version, origin_channel, origin_to, created_at, doc FROM actions WHERE event_id = ?")
+        .get(eventId);
+}
+function readAllActionRows(db) {
+    return db
+        .prepare("SELECT event_id, action, target, version, origin_channel, origin_to, created_at, doc FROM actions ORDER BY created_at DESC")
+        .all();
+}
+function readActionRowsByOrigin(db, origin) {
+    return db
+        .prepare(`SELECT event_id, action, target, version, origin_channel, origin_to, created_at, doc FROM actions
+       WHERE origin_channel = ? AND origin_to = ?
+       ORDER BY created_at DESC`)
+        .all(origin.channel, origin.to);
+}
+function getAction(db, eventId, errorPrefix) {
+    try {
+        const row = readActionRow(db, eventId);
+        return row === undefined ? undefined : parseActionDoc(row);
+    }
+    catch (cause) {
+        if (cause instanceof ActionStoreError)
+            throw cause;
+        throw new ActionStoreError(`${errorPrefix} action ${eventId} 失败`, { cause });
+    }
+}
+function listActions(db, errorPrefix) {
+    try {
+        return readAllActionRows(db).map((row) => parseActionDoc(row));
+    }
+    catch (cause) {
+        if (cause instanceof ActionStoreError)
+            throw cause;
+        throw new ActionStoreError(`${errorPrefix} action 列表失败`, { cause });
+    }
+}
+function listActionsByOrigin(db, origin, errorPrefix) {
+    try {
+        return readActionRowsByOrigin(db, origin).map((row) => parseActionDoc(row));
+    }
+    catch (cause) {
+        if (cause instanceof ActionStoreError)
+            throw cause;
+        throw new ActionStoreError(`${errorPrefix} action 按 origin 列表失败`, { cause });
+    }
+}
+function runTtlCleanup(db, nowMs) {
+    const cutoffIso = new Date(nowMs - RETENTION_MS).toISOString();
+    db.prepare("DELETE FROM actions WHERE created_at < ?").run(cutoffIso);
+    db.prepare(`DELETE FROM actions WHERE event_id NOT IN (
+      SELECT event_id FROM actions ORDER BY created_at DESC LIMIT ${MAX_RETAIN_RECORDS}
+    )`).run();
+}
+/**
+ * SqliteActionStore：动作指令的唯一写者。读写走事务，异常一律转 ActionStoreError。
+ */
+export class SqliteActionStore {
+    db;
+    constructor(dbPath) {
+        this.db = openDatabase(dbPath, { readOnly: false });
+    }
+    close() {
+        this.db.close();
+    }
+    get(eventId) {
+        return getAction(this.db, eventId, "读取");
+    }
+    set(event) {
+        try {
+            this.db.exec("BEGIN IMMEDIATE");
+            try {
+                const createdAt = event.timestamp ?? new Date().toISOString();
+                this.db
+                    .prepare(`INSERT INTO actions (event_id, action, target, version, origin_channel, origin_to, created_at, doc)
+             VALUES (@eventId, @action, @target, @version, @originChannel, @originTo, @createdAt, @doc)
+             ON CONFLICT(event_id) DO UPDATE SET
+               action = excluded.action,
+               target = excluded.target,
+               version = excluded.version,
+               origin_channel = excluded.origin_channel,
+               origin_to = excluded.origin_to,
+               created_at = excluded.created_at,
+               doc = excluded.doc`)
+                    .run({
+                    eventId: event.eventId,
+                    action: event.action,
+                    target: event.target,
+                    version: event.version,
+                    originChannel: event.origin?.channel ?? null,
+                    originTo: event.origin?.to ?? null,
+                    createdAt: createdAt,
+                    doc: JSON.stringify(event),
+                });
+                runTtlCleanup(this.db, Date.now());
+                this.db.exec("COMMIT");
+            }
+            catch (cause) {
+                this.db.exec("ROLLBACK");
+                throw cause;
+            }
+        }
+        catch (cause) {
+            throw new ActionStoreError(`写入 action ${event.eventId} 失败`, { cause });
+        }
+    }
+    delete(eventId) {
+        try {
+            this.db.prepare("DELETE FROM actions WHERE event_id = ?").run(eventId);
+        }
+        catch (cause) {
+            throw new ActionStoreError(`删除 action ${eventId} 失败`, { cause });
+        }
+    }
+    list() {
+        return listActions(this.db, "列出");
+    }
+    listActionsByOrigin(origin) {
+        return listActionsByOrigin(this.db, origin, "列出");
+    }
+}
+/**
+ * IM 侧只读入口：以 readOnly 模式打开同一 DB，杜绝误写。
+ */
+export function openActionStoreReadonly(dbPath) {
+    const db = openDatabase(dbPath, { readOnly: true });
+    return {
+        get(eventId) {
+            return getAction(db, eventId, "只读读取");
+        },
+        list() {
+            return listActions(db, "只读列出");
+        },
+        listActionsByOrigin(origin) {
+            const columns = listColumnNames(db);
+            if (!columns.has("origin_channel") || !columns.has("origin_to")) {
+                return [];
+            }
+            return listActionsByOrigin(db, origin, "只读列出");
+        },
+    };
+}

package/dist/action-types.d.ts

@@ -0,0 +1,28 @@
+import type { PlanOrigin } from "./plan-types.js";
+export type ActionStatus = "completed" | "running" | "pending" | "failed";
+export interface ActionScopeControl {
+    activeSessionOnly?: boolean;
+}
+export interface ActionDispatchPayload {
+    data: Record<string, unknown>;
+}
+export interface ActionDispatchEvent {
+    eventId: string;
+    event: "action_dispatch";
+    action: string;
+    topic?: string;
+    target: string;
+    version: number;
+    status: ActionStatus;
+    scopeControl?: ActionScopeControl;
+    payload: ActionDispatchPayload;
+    timestamp: string;
+    origin?: PlanOrigin;
+}
+export declare class ActionInvariantError extends Error {
+    constructor(message: string);
+}
+export declare function isActionStatus(value: unknown): value is ActionStatus;
+export declare function isActionDispatchEvent(value: unknown): value is ActionDispatchEvent;
+export declare function assertActionDispatchEventInvariants(event: ActionDispatchEvent): void;
+//# sourceMappingURL=action-types.d.ts.map

package/dist/action-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-types.d.ts","sourceRoot":"","sources":["../src/action-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAI1E,MAAM,WAAW,kBAAkB;IACjC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CA+BlF;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAkCpF"}

package/dist/action-types.js

@@ -0,0 +1,83 @@
+const ACTION_STATUSES = ["completed", "running", "pending", "failed"];
+export class ActionInvariantError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ActionInvariantError";
+    }
+}
+export function isActionStatus(value) {
+    return typeof value === "string" && ACTION_STATUSES.includes(value);
+}
+export function isActionDispatchEvent(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const evt = value;
+    if (typeof evt["eventId"] !== "string" || evt["eventId"].trim() === "")
+        return false;
+    if (evt["event"] !== "action_dispatch")
+        return false;
+    if (typeof evt["action"] !== "string" || evt["action"].trim() === "")
+        return false;
+    if (evt["topic"] !== undefined && typeof evt["topic"] !== "string")
+        return false;
+    if (typeof evt["target"] !== "string" || evt["target"].trim() === "")
+        return false;
+    if (typeof evt["version"] !== "number" || !Number.isFinite(evt["version"]) || evt["version"] <= 0) {
+        return false;
+    }
+    if (!isActionStatus(evt["status"]))
+        return false;
+    if (evt["scopeControl"] !== undefined) {
+        if (typeof evt["scopeControl"] !== "object" || evt["scopeControl"] === null)
+            return false;
+        const scopeCtrl = evt["scopeControl"];
+        if (scopeCtrl["activeSessionOnly"] !== undefined &&
+            typeof scopeCtrl["activeSessionOnly"] !== "boolean") {
+            return false;
+        }
+    }
+    if (typeof evt["payload"] !== "object" || evt["payload"] === null)
+        return false;
+    const payload = evt["payload"];
+    if (typeof payload["data"] !== "object" || payload["data"] === null)
+        return false;
+    if (typeof evt["timestamp"] !== "string" || evt["timestamp"].trim() === "")
+        return false;
+    return true;
+}
+export function assertActionDispatchEventInvariants(event) {
+    if (typeof event.eventId !== "string" || event.eventId.trim() === "") {
+        throw new ActionInvariantError("eventId 不能为空");
+    }
+    if (event.event !== "action_dispatch") {
+        throw new ActionInvariantError(`event 必须为 'action_dispatch'，实际为: ${event.event}`);
+    }
+    if (typeof event.action !== "string" || event.action.trim() === "") {
+        throw new ActionInvariantError("action 不能为空");
+    }
+    if (event.topic !== undefined && typeof event.topic !== "string") {
+        throw new ActionInvariantError("topic 类型必须为 string");
+    }
+    if (typeof event.target !== "string" || event.target.trim() === "") {
+        throw new ActionInvariantError("target 不能为空");
+    }
+    if (event.target.length > 128) {
+        throw new ActionInvariantError("target 长度不能超过 128");
+    }
+    if (typeof event.version !== "number" || !Number.isFinite(event.version) || event.version <= 0) {
+        throw new ActionInvariantError(`version 取值非法: ${event.version}`);
+    }
+    if (!isActionStatus(event.status)) {
+        throw new ActionInvariantError(`status 取值非法: ${event.status}`);
+    }
+    if (typeof event.payload !== "object" || event.payload === null) {
+        throw new ActionInvariantError("payload 必须是非空对象");
+    }
+    if (typeof event.payload.data !== "object" || event.payload.data === null) {
+        throw new ActionInvariantError("payload.data 必须是非空对象");
+    }
+    if (typeof event.timestamp !== "string" || event.timestamp.trim() === "") {
+        throw new ActionInvariantError("timestamp 不能为空");
+    }
+}

package/dist/index.d.ts

@@ -4,4 +4,8 @@ export type { PlanStore, PlanSummary } from "./plan-store.js";
 export { SqlitePlanStore, openPlanStoreReadonly, resolvePlanDbPath, PlanStoreError } from "./plan-store.js";
 export type { PlanEventPayload, PlanEventSummary } from "./plan-events.js";
 export { planEventStream, isPlanEventPayload } from "./plan-events.js";
+export type { ActionStatus, ActionScopeControl, ActionDispatchPayload, ActionDispatchEvent, } from "./action-types.js";
+export { ActionInvariantError, isActionStatus, isActionDispatchEvent, assertActionDispatchEventInvariants, } from "./action-types.js";
+export type { ActionStore } from "./action-store.js";
+export { SqliteActionStore, openActionStoreReadonly, ActionStoreError } from "./action-store.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE5F,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5G,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE5F,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5G,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEvE,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,mCAAmC,GACpC,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -2,3 +2,5 @@
 export { assertPlanInvariants, isPlanCancelled, PlanInvariantError } from "./plan-types.js";
 export { SqlitePlanStore, openPlanStoreReadonly, resolvePlanDbPath, PlanStoreError } from "./plan-store.js";
 export { planEventStream, isPlanEventPayload } from "./plan-events.js";
+export { ActionInvariantError, isActionStatus, isActionDispatchEvent, assertActionDispatchEventInvariants, } from "./action-types.js";
+export { SqliteActionStore, openActionStoreReadonly, ActionStoreError } from "./action-store.js";

package/dist/plan-events.d.ts

@@ -11,7 +11,7 @@ export interface PlanEventSummary {
     inProgress: number;
 }
 /**
- * plan_execute 推进后发出的事件 payload（缝隙 A 定义，两插件共用）。
+ * 计划推进后发出的事件 payload（缝隙 A 定义，两插件共用；当前事件链路休眠，仅编译兼容保留）。
  * 路由定位字段（deliveryContext/agentAccountId/messageChannel/sessionKey）均可选：
  * 能从工具工厂 ctx 取到就带，取不到就省略——事件是尽力而为，不因缺字段而阻断。
  */

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@xgjktech/xg-openclaw-shared",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "xgjktech OpenClaw 插件共享层：Plan 数据模型/不变量、SQLite PlanStore、计划事件契约",
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=22.22.3 <23 || >=24.15.0 <25 || >=25.9.0"
   },
   "exports": {
     ".": {
@@ -22,6 +22,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prebuild": "npm run clean",
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "pretest": "npm run build",