@loggie-ai/openclaw-plugin 0.1.0 → 0.1.1

package/README.md

@@ -15,7 +15,8 @@ OpenClaw inbound channel turn for the configured agent.
 3. The monitor opens a WebSocket to `baseUrl + socketPath`, authenticating with
    either `Authorization: Bearer <token>` or `x-api-key: <token>`.
 4. Before opening the socket, the plugin loads the durable cursor from OpenClaw
-   runtime state and appends it to the URL as `?cursor=<lastCursor>`.
+   trusted runtime state when available, otherwise from the file-backed cursor
+   store, and appends it to the URL as `?cursor=<lastCursor>`.
 5. Loggie sends event envelopes. The plugin validates the envelope, skips
    duplicates or cursor regressions, and processes `meeting.transcript.ready`.
 6. If the event includes `payload.detailPath`, the plugin fetches that detail
@@ -144,9 +145,13 @@ Session identity is deterministic:
 - Embedded run session id:
   `loggie-<accountId>-<meetingScheduleId|meetingId|eventId>`
 
-The cursor store is required to be durable. Runtime startup fails if OpenClaw
-does not provide a keyed runtime state store. This prevents silent in-memory
-cursor loss and duplicate transcript dispatch after restart.
+The cursor store is always durable. Trusted OpenClaw installs use
+`runtime.state.openKeyedStore({ namespace: "loggie-cursors" })`. Plain external
+npm installs that do not receive the trusted runtime state API fall back to a
+file-backed store at `runtime.state.resolveStateDir()/loggie-cursors.json` when
+OpenClaw exposes a state directory, or `~/.openclaw/state/loggie-cursors.json`
+otherwise. Startup does not fail solely because trusted state is unavailable,
+and the fallback still persists replay cursors across gateway restarts.
 
 The plugin keeps a bounded set of recently seen event ids and skips:
 

package/dist/setup-entry.d.ts

@@ -21,6 +21,12 @@ declare const _default: {
                 connected: {};
                 authenticated: {};
                 caughtUp: {};
+                cursorStoreMode: {} | null;
+                cursorPersistenceFailed: {};
+                lastCursorPersistenceAt: {} | null;
+                lastCursorPersistenceError: {} | null;
+                lastCursorPersistenceEventId: {} | null;
+                lastCursorPersistenceCursor: {} | null;
                 lastEventId: {} | null;
                 lastCursor: {} | null;
                 lastSequence: {} | null;

package/dist/src/channel.d.ts

@@ -22,6 +22,12 @@ export declare const loggiePlugin: {
             connected: {};
             authenticated: {};
             caughtUp: {};
+            cursorStoreMode: {} | null;
+            cursorPersistenceFailed: {};
+            lastCursorPersistenceAt: {} | null;
+            lastCursorPersistenceError: {} | null;
+            lastCursorPersistenceEventId: {} | null;
+            lastCursorPersistenceCursor: {} | null;
             lastEventId: {} | null;
             lastCursor: {} | null;
             lastSequence: {} | null;

package/dist/src/cursor-store.d.ts

@@ -37,9 +37,14 @@ export type LoggieCursorDecision = {
     reason: "duplicate_event" | "cursor_regression";
 };
 export type LoggieCursorStore = {
+    readonly mode?: LoggieCursorStoreMode;
     load(accountId: string, agentProfileId: string): Promise<LoggieCursorRecord | undefined>;
     save(record: LoggieCursorRecord): Promise<void>;
 };
+export type LoggieCursorStoreMode = "trusted" | "file";
+export type RuntimeCursorStoreOptions = {
+    warn?: (message: string) => void;
+};
 export declare function createEmptyCursorRecord(params: {
     accountId: string;
     agentProfileId: string;
@@ -73,8 +78,10 @@ export declare function deadLetterEvent(params: {
     now?: Date;
 }): LoggieCursorRecord;
 export declare function createMemoryCursorStore(initial?: LoggieCursorRecord[]): LoggieCursorStore;
+export declare function createFileCursorStore(filePath?: string): LoggieCursorStore;
 export declare function createRuntimeCursorStore(runtime: {
     state?: {
+        resolveStateDir?: () => string;
         openKeyedStore?: <T>(opts: {
             namespace: string;
             maxEntries: number;
@@ -83,4 +90,4 @@ export declare function createRuntimeCursorStore(runtime: {
             register(key: string, value: T): Promise<void>;
         };
     };
-}): LoggieCursorStore;
+}, options?: RuntimeCursorStoreOptions): LoggieCursorStore;

package/dist/src/cursor-store.js

@@ -1,6 +1,10 @@
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
 const MAX_SEEN_EVENT_IDS = 500;
 const MAX_FAILED_EVENTS = 50;
 const MAX_DEAD_LETTERED_EVENTS = 100;
+const warnedFileCursorStorePaths = new Set();
 export function createEmptyCursorRecord(params) {
     return {
         accountId: params.accountId,
@@ -111,19 +115,86 @@ export function createMemoryCursorStore(initial) {
         },
     };
 }
-export function createRuntimeCursorStore(runtime) {
+export function createFileCursorStore(filePath = defaultCursorStorePath()) {
+    let pending = Promise.resolve();
+    async function withFileLock(operation) {
+        const result = pending.then(operation, operation);
+        pending = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    return {
+        mode: "file",
+        load(accountId, agentProfileId) {
+            return withFileLock(async () => {
+                const records = await readCursorFile(filePath);
+                return records[cursorKey(accountId, agentProfileId)];
+            });
+        },
+        save(record) {
+            return withFileLock(async () => {
+                const records = await readCursorFile(filePath);
+                records[cursorKey(record.accountId, record.agentProfileId)] = record;
+                await writeCursorFile(filePath, records);
+            });
+        },
+    };
+}
+export function createRuntimeCursorStore(runtime, options = {}) {
     const store = runtime.state?.openKeyedStore?.({
         namespace: "loggie-cursors",
         maxEntries: 1000,
     });
     if (!store) {
-        throw new Error("Loggie durable cursor store is unavailable");
+        const stateDir = runtime.state?.resolveStateDir?.();
+        const filePath = stateDir ? join(stateDir, "loggie-cursors.json") : defaultCursorStorePath();
+        warnFileCursorStoreFallbackOnce(filePath, options.warn);
+        return createFileCursorStore(filePath);
     }
     return {
+        mode: "trusted",
         load: (accountId, agentProfileId) => store.lookup(cursorKey(accountId, agentProfileId)),
         save: (record) => store.register(cursorKey(record.accountId, record.agentProfileId), record),
     };
 }
+function defaultCursorStorePath() {
+    return join(homedir(), ".openclaw", "state", "loggie-cursors.json");
+}
+function warnFileCursorStoreFallbackOnce(filePath, warn) {
+    if (!warn || warnedFileCursorStorePaths.has(filePath)) {
+        return;
+    }
+    warnedFileCursorStorePaths.add(filePath);
+    warn(`Loggie trusted runtime cursor store is unavailable; using file-backed cursor store at ${filePath}. Cursor durability now depends on filesystem access to that path.`);
+}
+async function readCursorFile(filePath) {
+    try {
+        const contents = await fs.readFile(filePath, "utf8");
+        const parsed = JSON.parse(contents);
+        if (isCursorFile(parsed)) {
+            return parsed;
+        }
+        throw new Error(`Loggie cursor store file has invalid JSON shape: ${filePath}`);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+}
+async function writeCursorFile(filePath, records) {
+    const directory = dirname(filePath);
+    await fs.mkdir(directory, { recursive: true });
+    const tempPath = join(directory, `.loggie-cursors.${process.pid}.${Date.now()}.tmp`);
+    await fs.writeFile(tempPath, `${JSON.stringify(records, null, 2)}\n`, "utf8");
+    await fs.rename(tempPath, filePath);
+}
+function isCursorFile(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
 function cursorKey(accountId, agentProfileId) {
     return `${accountId}:${agentProfileId}`;
 }

package/dist/src/monitor/connection.js

@@ -1,7 +1,7 @@
 import { createRuntimeCursorStore } from "../cursor-store.js";
 import { buildLoggieAuthHeaders, buildLoggiePingMessage, buildLoggieResumeMessage, buildLoggieWebSocketUrl, decodeLoggieSocketMessage, defaultLoggieSocketFactory, } from "../loggie-client.js";
 import { createOpenClawTranscriptDispatcher } from "./transcript-dispatch.js";
-import { handleLoggieEvent } from "./event-handler.js";
+import { handleLoggieEvent, isLoggieCursorPersistenceError } from "./event-handler.js";
 export async function monitorLoggieAccount(params) {
     if (!params.account.enabled) {
         params.log?.info?.(`[${params.account.accountId}] Loggie account disabled`);
@@ -13,7 +13,7 @@ export async function monitorLoggieAccount(params) {
     if (!params.channelRuntime && !params.dispatcher) {
         throw new Error("Loggie channelRuntime is required for transcript dispatch");
     }
-    const cursorStore = params.cursorStore ?? createRuntimeCursorStore(params.runtime);
+    const cursorStore = params.cursorStore ?? createRuntimeCursorStore(params.runtime, { warn: params.log?.warn });
     const dispatcher = params.dispatcher ??
         createOpenClawTranscriptDispatcher({
             account: params.account,
@@ -38,6 +38,24 @@ export async function monitorLoggieAccount(params) {
             if (params.abortSignal?.aborted) {
                 return;
             }
+            if (isLoggieCursorPersistenceError(error)) {
+                const failedAt = Date.now();
+                params.setStatus?.({
+                    ...(params.getStatus?.() ?? { accountId: params.account.accountId }),
+                    running: false,
+                    connected: false,
+                    authenticated: false,
+                    ...cursorStoreStatus(cursorStore.mode),
+                    cursorPersistenceFailed: true,
+                    lastCursorPersistenceAt: failedAt,
+                    lastCursorPersistenceError: error.message,
+                    lastCursorPersistenceEventId: error.eventId,
+                    lastCursorPersistenceCursor: error.cursor ?? null,
+                    lastError: error.message,
+                });
+                params.log?.warn?.(`[${params.account.accountId}] Loggie cursor persistence failed; stopping monitor to avoid duplicate transcript dispatch: ${error.message}`);
+                throw error;
+            }
             attempts += 1;
             const delayMs = Math.min(params.account.reconnect.maxMs, params.account.reconnect.minMs * 2 ** Math.max(0, attempts - 1));
             params.setStatus?.({
@@ -46,6 +64,8 @@ export async function monitorLoggieAccount(params) {
                 connected: false,
                 authenticated: false,
                 reconnectAttempts: attempts,
+                ...cursorStoreStatus(cursorStore.mode),
+                ...cursorPersistenceOkStatus(),
                 lastError: error instanceof Error ? error.message : String(error),
             });
             params.log?.warn?.(`[${params.account.accountId}] Loggie socket failed; reconnecting in ${delayMs}ms`);
@@ -64,6 +84,8 @@ export async function runLoggieSocketOnce(params) {
         running: true,
         connected: false,
         authenticated: false,
+        ...cursorStoreStatus(params.cursorStore.mode),
+        ...cursorPersistenceOkStatus(),
         lastStartAt: Date.now(),
     });
     await new Promise((resolve, reject) => {
@@ -145,6 +167,8 @@ export async function runLoggieSocketOnce(params) {
                     connected: true,
                     authenticated: true,
                     reconnectAttempts: 0,
+                    ...cursorStoreStatus(params.cursorStore.mode),
+                    ...cursorPersistenceOkStatus(),
                     lastConnectedAt: connectedAt,
                     lastError: null,
                 });
@@ -211,6 +235,8 @@ export async function runLoggieSocketOnce(params) {
                     connected: true,
                     authenticated: true,
                     caughtUp: true,
+                    ...cursorStoreStatus(params.cursorStore.mode),
+                    ...cursorPersistenceOkStatus(),
                     lastEventAt: eventAt,
                     ...(result.status === "dispatched" ? { lastDispatchAt: eventAt } : {}),
                     ...(deadLettered && result.event
@@ -253,6 +279,18 @@ export async function runLoggieSocketOnce(params) {
         });
     });
 }
+function cursorStoreStatus(mode) {
+    return mode ? { cursorStoreMode: mode } : {};
+}
+function cursorPersistenceOkStatus() {
+    return {
+        cursorPersistenceFailed: false,
+        lastCursorPersistenceAt: null,
+        lastCursorPersistenceError: null,
+        lastCursorPersistenceEventId: null,
+        lastCursorPersistenceCursor: null,
+    };
+}
 function parseControlMessage(value) {
     if (value === null || typeof value !== "object" || !("type" in value)) {
         return { type: "none" };

package/dist/src/monitor/event-handler.d.ts

@@ -18,6 +18,20 @@ export type LoggieEventHandleResult = {
     reason: string;
     retryable: boolean;
 };
+export declare class LoggieCursorPersistenceError extends Error {
+    readonly eventId: string;
+    readonly cursor?: string;
+    readonly accountId: string;
+    readonly agentProfileId: string;
+    readonly phase: "post_dispatch";
+    constructor(params: {
+        event: LoggieEventEnvelope;
+        account: ResolvedLoggieAccount;
+        phase: "post_dispatch";
+        cause: unknown;
+    });
+}
+export declare function isLoggieCursorPersistenceError(error: unknown): error is LoggieCursorPersistenceError;
 export declare function handleLoggieEvent(params: {
     raw: unknown;
     account: ResolvedLoggieAccount;

package/dist/src/monitor/event-handler.js

@@ -1,6 +1,28 @@
 import { advanceCursor, deadLetterEvent, decideCursor, recordEventFailure, } from "../cursor-store.js";
 import { isTranscriptReadyEvent, parseLoggieEventEnvelope, } from "../event-types.js";
 const MAX_EVENT_DISPATCH_ATTEMPTS = 3;
+export class LoggieCursorPersistenceError extends Error {
+    eventId;
+    cursor;
+    accountId;
+    agentProfileId;
+    phase;
+    constructor(params) {
+        const causeMessage = params.cause instanceof Error ? params.cause.message : String(params.cause);
+        super(`Loggie cursor persistence failed after dispatching event ${params.event.eventId}: ${causeMessage}`, {
+            cause: params.cause,
+        });
+        this.name = "LoggieCursorPersistenceError";
+        this.eventId = params.event.eventId;
+        this.cursor = params.event.cursor;
+        this.accountId = params.account.accountId;
+        this.agentProfileId = params.account.agentProfileId;
+        this.phase = params.phase;
+    }
+}
+export function isLoggieCursorPersistenceError(error) {
+    return error instanceof LoggieCursorPersistenceError;
+}
 export async function handleLoggieEvent(params) {
     const parsed = parseLoggieEventEnvelope(params.raw);
     if (!parsed.ok) {
@@ -79,12 +101,23 @@ export async function handleLoggieEvent(params) {
             },
         };
     }
-    await params.cursorStore.save(advanceCursor({
+    const advanced = advanceCursor({
         record: cursor,
         event,
         accountId: params.account.accountId,
         agentProfileId: params.account.agentProfileId,
         now: params.now,
-    }));
+    });
+    try {
+        await params.cursorStore.save(advanced);
+    }
+    catch (error) {
+        throw new LoggieCursorPersistenceError({
+            event,
+            account: params.account,
+            phase: "post_dispatch",
+            cause: error,
+        });
+    }
     return { status: "dispatched", event };
 }

package/dist/src/monitor/transcript-dispatch.js

@@ -2,7 +2,14 @@ import { fetchLoggieTranscriptDetail } from "../loggie-client.js";
 import { buildLoggieRouteSessionKey, buildLoggieSessionId, meetingConversationId } from "../routing.js";
 import { formatTranscriptReadyPrompt } from "./transcript-format.js";
 export function createOpenClawTranscriptDispatcher(params) {
-    const agentRuntime = params.runtime.agent;
+    let agentRuntimePromise;
+    const getAgentRuntime = () => {
+        agentRuntimePromise ??= resolveAgentRuntime(params.runtime).catch((error) => {
+            agentRuntimePromise = undefined;
+            throw error;
+        });
+        return agentRuntimePromise;
+    };
     return {
         async dispatchTranscriptReady(event) {
             const routeSessionKey = buildLoggieRouteSessionKey({ account: params.account, event });
@@ -86,6 +93,7 @@ export function createOpenClawTranscriptDispatcher(params) {
                     },
                 },
                 runDispatch: async () => {
+                    const agentRuntime = await getAgentRuntime();
                     const workspaceDir = agentRuntime.resolveAgentWorkspaceDir(params.cfg, params.account.agentId);
                     await agentRuntime.ensureAgentWorkspace?.({ dir: workspaceDir });
                     return agentRuntime.runEmbeddedAgent({
@@ -122,3 +130,44 @@ export function createOpenClawTranscriptDispatcher(params) {
         },
     };
 }
+async function resolveAgentRuntime(runtime) {
+    const runtimeAgent = runtime.agent;
+    if (hasRequiredAgentHelpers(runtimeAgent)) {
+        return runtimeAgent;
+    }
+    const extensionApi = (await import("openclaw/extension-api"));
+    return {
+        runEmbeddedAgent: readRunEmbeddedAgent(runtimeAgent, extensionApi),
+        resolveAgentWorkspaceDir: readHelper(runtimeAgent, extensionApi, "resolveAgentWorkspaceDir"),
+        resolveAgentDir: readHelper(runtimeAgent, extensionApi, "resolveAgentDir"),
+        resolveAgentTimeoutMs: readHelper(runtimeAgent, extensionApi, "resolveAgentTimeoutMs"),
+        ensureAgentWorkspace: readOptionalHelper(runtimeAgent, extensionApi, "ensureAgentWorkspace"),
+    };
+}
+function hasRequiredAgentHelpers(value) {
+    return (typeof value?.runEmbeddedAgent === "function" &&
+        typeof value.resolveAgentWorkspaceDir === "function" &&
+        typeof value.resolveAgentDir === "function" &&
+        typeof value.resolveAgentTimeoutMs === "function");
+}
+function readRunEmbeddedAgent(runtimeAgent, extensionApi) {
+    const helper = runtimeAgent?.runEmbeddedAgent ?? extensionApi.runEmbeddedAgent ?? extensionApi.runEmbeddedPiAgent;
+    if (typeof helper !== "function") {
+        throw new Error("Loggie transcript dispatch requires OpenClaw agent helper: runEmbeddedAgent");
+    }
+    return helper;
+}
+function readHelper(runtimeAgent, extensionApi, key) {
+    const helper = runtimeAgent?.[key] ?? extensionApi[key];
+    if (typeof helper !== "function") {
+        throw new Error(`Loggie transcript dispatch requires OpenClaw agent helper: ${key}`);
+    }
+    return helper;
+}
+function readOptionalHelper(runtimeAgent, extensionApi, key) {
+    const helper = runtimeAgent?.[key] ?? extensionApi[key];
+    if (helper !== undefined && typeof helper !== "function") {
+        throw new Error(`Loggie transcript dispatch requires OpenClaw agent helper: ${key}`);
+    }
+    return helper;
+}

package/dist/src/status.d.ts

@@ -3,6 +3,12 @@ export type LoggieRuntimeExtra = {
     connected?: boolean;
     authenticated?: boolean;
     caughtUp?: boolean;
+    cursorStoreMode?: "trusted" | "file" | null;
+    cursorPersistenceFailed?: boolean;
+    lastCursorPersistenceAt?: number | null;
+    lastCursorPersistenceError?: string | null;
+    lastCursorPersistenceEventId?: string | null;
+    lastCursorPersistenceCursor?: string | null;
     lastEventId?: string | null;
     lastCursor?: string | null;
     lastSequence?: number | null;
@@ -33,6 +39,12 @@ export declare function buildLoggieAccountStatusSnapshot(params: {
     connected: {};
     authenticated: {};
     caughtUp: {};
+    cursorStoreMode: {} | null;
+    cursorPersistenceFailed: {};
+    lastCursorPersistenceAt: {} | null;
+    lastCursorPersistenceError: {} | null;
+    lastCursorPersistenceEventId: {} | null;
+    lastCursorPersistenceCursor: {} | null;
     lastEventId: {} | null;
     lastCursor: {} | null;
     lastSequence: {} | null;

package/dist/src/status.js

@@ -3,6 +3,12 @@ export const defaultLoggieRuntimeState = createDefaultChannelRuntimeState("defau
     connected: false,
     authenticated: false,
     caughtUp: false,
+    cursorStoreMode: null,
+    cursorPersistenceFailed: false,
+    lastCursorPersistenceAt: null,
+    lastCursorPersistenceError: null,
+    lastCursorPersistenceEventId: null,
+    lastCursorPersistenceCursor: null,
     lastEventId: null,
     lastCursor: null,
     lastSequence: null,
@@ -32,6 +38,12 @@ export function buildLoggieAccountStatusSnapshot(params) {
         connected: params.runtime?.connected ?? false,
         authenticated: params.runtime?.authenticated ?? false,
         caughtUp: params.runtime?.caughtUp ?? false,
+        cursorStoreMode: params.runtime?.cursorStoreMode ?? null,
+        cursorPersistenceFailed: params.runtime?.cursorPersistenceFailed ?? false,
+        lastCursorPersistenceAt: params.runtime?.lastCursorPersistenceAt ?? null,
+        lastCursorPersistenceError: params.runtime?.lastCursorPersistenceError ?? null,
+        lastCursorPersistenceEventId: params.runtime?.lastCursorPersistenceEventId ?? null,
+        lastCursorPersistenceCursor: params.runtime?.lastCursorPersistenceCursor ?? null,
         lastEventId: params.runtime?.lastEventId ?? null,
         lastCursor: params.runtime?.lastCursor ?? null,
         lastSequence: params.runtime?.lastSequence ?? null,

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "loggie",
   "kind": "channel",
   "name": "Loggie",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "OpenClaw channel plugin for durable Loggie meeting transcript events over WebSocket.",
   "activation": {
     "onStartup": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loggie-ai/openclaw-plugin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "OpenClaw channel plugin for Loggie meeting transcript events.",
   "type": "module",
   "main": "./dist/index.js",

package/src/cursor-store.ts

@@ -1,3 +1,6 @@
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
 import type { LoggieEventEnvelope } from "./event-types.js";
 
 export type LoggieCursorRecord = {
@@ -39,13 +42,21 @@ export type LoggieCursorDecision =
   | { action: "skip"; reason: "duplicate_event" | "cursor_regression" };
 
 export type LoggieCursorStore = {
+  readonly mode?: LoggieCursorStoreMode;
   load(accountId: string, agentProfileId: string): Promise<LoggieCursorRecord | undefined>;
   save(record: LoggieCursorRecord): Promise<void>;
 };
 
+export type LoggieCursorStoreMode = "trusted" | "file";
+
+export type RuntimeCursorStoreOptions = {
+  warn?: (message: string) => void;
+};
+
 const MAX_SEEN_EVENT_IDS = 500;
 const MAX_FAILED_EVENTS = 50;
 const MAX_DEAD_LETTERED_EVENTS = 100;
+const warnedFileCursorStorePaths = new Set<string>();
 
 export function createEmptyCursorRecord(params: {
   accountId: string;
@@ -193,27 +204,111 @@ export function createMemoryCursorStore(initial?: LoggieCursorRecord[]): LoggieC
   };
 }
 
-export function createRuntimeCursorStore(runtime: {
-  state?: {
-    openKeyedStore?: <T>(opts: { namespace: string; maxEntries: number }) => {
-      lookup(key: string): Promise<T | undefined>;
-      register(key: string, value: T): Promise<void>;
-    };
+export function createFileCursorStore(filePath = defaultCursorStorePath()): LoggieCursorStore {
+  let pending: Promise<void> = Promise.resolve();
+
+  async function withFileLock<T>(operation: () => Promise<T>): Promise<T> {
+    const result = pending.then(operation, operation);
+    pending = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+
+  return {
+    mode: "file",
+    load(accountId, agentProfileId) {
+      return withFileLock(async () => {
+        const records = await readCursorFile(filePath);
+        return records[cursorKey(accountId, agentProfileId)];
+      });
+    },
+    save(record) {
+      return withFileLock(async () => {
+        const records = await readCursorFile(filePath);
+        records[cursorKey(record.accountId, record.agentProfileId)] = record;
+        await writeCursorFile(filePath, records);
+      });
+    },
   };
-}): LoggieCursorStore {
+}
+
+export function createRuntimeCursorStore(
+  runtime: {
+    state?: {
+      resolveStateDir?: () => string;
+      openKeyedStore?: <T>(opts: { namespace: string; maxEntries: number }) => {
+        lookup(key: string): Promise<T | undefined>;
+        register(key: string, value: T): Promise<void>;
+      };
+    };
+  },
+  options: RuntimeCursorStoreOptions = {},
+): LoggieCursorStore {
   const store = runtime.state?.openKeyedStore?.<LoggieCursorRecord>({
     namespace: "loggie-cursors",
     maxEntries: 1000,
   });
   if (!store) {
-    throw new Error("Loggie durable cursor store is unavailable");
+    const stateDir = runtime.state?.resolveStateDir?.();
+    const filePath = stateDir ? join(stateDir, "loggie-cursors.json") : defaultCursorStorePath();
+    warnFileCursorStoreFallbackOnce(filePath, options.warn);
+    return createFileCursorStore(filePath);
   }
   return {
+    mode: "trusted",
     load: (accountId, agentProfileId) => store.lookup(cursorKey(accountId, agentProfileId)),
     save: (record) => store.register(cursorKey(record.accountId, record.agentProfileId), record),
   };
 }
 
+function defaultCursorStorePath(): string {
+  return join(homedir(), ".openclaw", "state", "loggie-cursors.json");
+}
+
+function warnFileCursorStoreFallbackOnce(filePath: string, warn: RuntimeCursorStoreOptions["warn"]): void {
+  if (!warn || warnedFileCursorStorePaths.has(filePath)) {
+    return;
+  }
+  warnedFileCursorStorePaths.add(filePath);
+  warn(
+    `Loggie trusted runtime cursor store is unavailable; using file-backed cursor store at ${filePath}. Cursor durability now depends on filesystem access to that path.`,
+  );
+}
+
+async function readCursorFile(filePath: string): Promise<Record<string, LoggieCursorRecord>> {
+  try {
+    const contents = await fs.readFile(filePath, "utf8");
+    const parsed = JSON.parse(contents) as unknown;
+    if (isCursorFile(parsed)) {
+      return parsed;
+    }
+    throw new Error(`Loggie cursor store file has invalid JSON shape: ${filePath}`);
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return {};
+    }
+    throw error;
+  }
+}
+
+async function writeCursorFile(filePath: string, records: Record<string, LoggieCursorRecord>): Promise<void> {
+  const directory = dirname(filePath);
+  await fs.mkdir(directory, { recursive: true });
+  const tempPath = join(directory, `.loggie-cursors.${process.pid}.${Date.now()}.tmp`);
+  await fs.writeFile(tempPath, `${JSON.stringify(records, null, 2)}\n`, "utf8");
+  await fs.rename(tempPath, filePath);
+}
+
+function isCursorFile(value: unknown): value is Record<string, LoggieCursorRecord> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}
+
 function cursorKey(accountId: string, agentProfileId: string): string {
   return `${accountId}:${agentProfileId}`;
 }

package/src/monitor/connection.ts

@@ -1,6 +1,6 @@
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/channel-core";
 import type { ResolvedLoggieAccount } from "../account.js";
-import { createRuntimeCursorStore, type LoggieCursorStore } from "../cursor-store.js";
+import { createRuntimeCursorStore, type LoggieCursorStore, type LoggieCursorStoreMode } from "../cursor-store.js";
 import {
   buildLoggieAuthHeaders,
   buildLoggiePingMessage,
@@ -11,7 +11,7 @@ import {
   type LoggieSocketFactory,
 } from "../loggie-client.js";
 import { createOpenClawTranscriptDispatcher, type TranscriptDispatcher } from "./transcript-dispatch.js";
-import { handleLoggieEvent } from "./event-handler.js";
+import { handleLoggieEvent, isLoggieCursorPersistenceError } from "./event-handler.js";
 
 type ChannelRuntime = PluginRuntime["channel"];
 
@@ -45,7 +45,7 @@ export async function monitorLoggieAccount(params: MonitorLoggieAccountParams):
     throw new Error("Loggie channelRuntime is required for transcript dispatch");
   }
 
-  const cursorStore = params.cursorStore ?? createRuntimeCursorStore(params.runtime);
+  const cursorStore = params.cursorStore ?? createRuntimeCursorStore(params.runtime, { warn: params.log?.warn });
   const dispatcher =
     params.dispatcher ??
     createOpenClawTranscriptDispatcher({
@@ -71,6 +71,26 @@ export async function monitorLoggieAccount(params: MonitorLoggieAccountParams):
       if (params.abortSignal?.aborted) {
         return;
       }
+      if (isLoggieCursorPersistenceError(error)) {
+        const failedAt = Date.now();
+        params.setStatus?.({
+          ...(params.getStatus?.() ?? { accountId: params.account.accountId }),
+          running: false,
+          connected: false,
+          authenticated: false,
+          ...cursorStoreStatus(cursorStore.mode),
+          cursorPersistenceFailed: true,
+          lastCursorPersistenceAt: failedAt,
+          lastCursorPersistenceError: error.message,
+          lastCursorPersistenceEventId: error.eventId,
+          lastCursorPersistenceCursor: error.cursor ?? null,
+          lastError: error.message,
+        });
+        params.log?.warn?.(
+          `[${params.account.accountId}] Loggie cursor persistence failed; stopping monitor to avoid duplicate transcript dispatch: ${error.message}`,
+        );
+        throw error;
+      }
       attempts += 1;
       const delayMs = Math.min(
         params.account.reconnect.maxMs,
@@ -82,6 +102,8 @@ export async function monitorLoggieAccount(params: MonitorLoggieAccountParams):
         connected: false,
         authenticated: false,
         reconnectAttempts: attempts,
+        ...cursorStoreStatus(cursorStore.mode),
+        ...cursorPersistenceOkStatus(),
         lastError: error instanceof Error ? error.message : String(error),
       });
       params.log?.warn?.(
@@ -107,6 +129,8 @@ export async function runLoggieSocketOnce(params: MonitorLoggieAccountParams & {
     running: true,
     connected: false,
     authenticated: false,
+    ...cursorStoreStatus(params.cursorStore.mode),
+    ...cursorPersistenceOkStatus(),
     lastStartAt: Date.now(),
   });
 
@@ -187,6 +211,8 @@ export async function runLoggieSocketOnce(params: MonitorLoggieAccountParams & {
           connected: true,
           authenticated: true,
           reconnectAttempts: 0,
+          ...cursorStoreStatus(params.cursorStore.mode),
+          ...cursorPersistenceOkStatus(),
           lastConnectedAt: connectedAt,
           lastError: null,
         });
@@ -253,6 +279,8 @@ export async function runLoggieSocketOnce(params: MonitorLoggieAccountParams & {
           connected: true,
           authenticated: true,
           caughtUp: true,
+          ...cursorStoreStatus(params.cursorStore.mode),
+          ...cursorPersistenceOkStatus(),
           lastEventAt: eventAt,
           ...(result.status === "dispatched" ? { lastDispatchAt: eventAt } : {}),
           ...(deadLettered && result.event
@@ -302,6 +330,20 @@ export async function runLoggieSocketOnce(params: MonitorLoggieAccountParams & {
   });
 }
 
+function cursorStoreStatus(mode: LoggieCursorStoreMode | undefined): { cursorStoreMode?: LoggieCursorStoreMode } {
+  return mode ? { cursorStoreMode: mode } : {};
+}
+
+function cursorPersistenceOkStatus() {
+  return {
+    cursorPersistenceFailed: false,
+    lastCursorPersistenceAt: null,
+    lastCursorPersistenceError: null,
+    lastCursorPersistenceEventId: null,
+    lastCursorPersistenceCursor: null,
+  };
+}
+
 type ControlMessageDecision =
   | { type: "none" }
   | { type: "ignore" }

package/src/monitor/event-handler.ts

@@ -28,6 +28,36 @@ export type LoggieEventHandleResult =
 
 const MAX_EVENT_DISPATCH_ATTEMPTS = 3;
 
+export class LoggieCursorPersistenceError extends Error {
+  readonly eventId: string;
+  readonly cursor?: string;
+  readonly accountId: string;
+  readonly agentProfileId: string;
+  readonly phase: "post_dispatch";
+
+  constructor(params: {
+    event: LoggieEventEnvelope;
+    account: ResolvedLoggieAccount;
+    phase: "post_dispatch";
+    cause: unknown;
+  }) {
+    const causeMessage = params.cause instanceof Error ? params.cause.message : String(params.cause);
+    super(`Loggie cursor persistence failed after dispatching event ${params.event.eventId}: ${causeMessage}`, {
+      cause: params.cause,
+    });
+    this.name = "LoggieCursorPersistenceError";
+    this.eventId = params.event.eventId;
+    this.cursor = params.event.cursor;
+    this.accountId = params.account.accountId;
+    this.agentProfileId = params.account.agentProfileId;
+    this.phase = params.phase;
+  }
+}
+
+export function isLoggieCursorPersistenceError(error: unknown): error is LoggieCursorPersistenceError {
+  return error instanceof LoggieCursorPersistenceError;
+}
+
 export async function handleLoggieEvent(params: {
   raw: unknown;
   account: ResolvedLoggieAccount;
@@ -120,14 +150,22 @@ export async function handleLoggieEvent(params: {
       },
     };
   }
-  await params.cursorStore.save(
-    advanceCursor({
-      record: cursor,
+  const advanced = advanceCursor({
+    record: cursor,
+    event,
+    accountId: params.account.accountId,
+    agentProfileId: params.account.agentProfileId,
+    now: params.now,
+  });
+  try {
+    await params.cursorStore.save(advanced);
+  } catch (error) {
+    throw new LoggieCursorPersistenceError({
       event,
-      accountId: params.account.accountId,
-      agentProfileId: params.account.agentProfileId,
-      now: params.now,
-    }),
-  );
+      account: params.account,
+      phase: "post_dispatch",
+      cause: error,
+    });
+  }
   return { status: "dispatched", event };
 }

package/src/monitor/transcript-dispatch.ts

@@ -10,6 +10,26 @@ export type TranscriptDispatcher = {
 };
 
 type ChannelRuntime = PluginRuntime["channel"];
+type AgentRuntimeHelpers = {
+  runEmbeddedAgent(input: Record<string, unknown>): Promise<unknown>;
+  resolveAgentWorkspaceDir(
+    cfg: OpenClawConfig,
+    agentId: string,
+    env?: NodeJS.ProcessEnv,
+  ): string;
+  resolveAgentDir(cfg: OpenClawConfig, agentId: string, env?: NodeJS.ProcessEnv): string;
+  resolveAgentTimeoutMs(opts: {
+    cfg?: OpenClawConfig;
+    overrideMs?: number | null;
+    overrideSeconds?: number | null;
+    minMs?: number;
+  }): number;
+  ensureAgentWorkspace?: (params: { dir: string }) => Promise<void> | void;
+};
+type ExtensionApi = Partial<AgentRuntimeHelpers>;
+type ExtensionApiWithAliases = ExtensionApi & {
+  runEmbeddedPiAgent?: AgentRuntimeHelpers["runEmbeddedAgent"];
+};
 
 export function createOpenClawTranscriptDispatcher(params: {
   account: ResolvedLoggieAccount;
@@ -19,7 +39,15 @@ export function createOpenClawTranscriptDispatcher(params: {
   abortSignal?: AbortSignal;
   fetchImpl?: typeof fetch;
 }): TranscriptDispatcher {
-  const agentRuntime = params.runtime.agent;
+  let agentRuntimePromise: Promise<AgentRuntimeHelpers> | undefined;
+  const getAgentRuntime = () => {
+    agentRuntimePromise ??= resolveAgentRuntime(params.runtime).catch((error: unknown) => {
+      agentRuntimePromise = undefined;
+      throw error;
+    });
+    return agentRuntimePromise;
+  };
+
   return {
     async dispatchTranscriptReady(event) {
       const routeSessionKey = buildLoggieRouteSessionKey({ account: params.account, event });
@@ -104,6 +132,7 @@ export function createOpenClawTranscriptDispatcher(params: {
           },
         },
         runDispatch: async () => {
+          const agentRuntime = await getAgentRuntime();
           const workspaceDir = agentRuntime.resolveAgentWorkspaceDir(
             params.cfg,
             params.account.agentId,
@@ -143,3 +172,63 @@ export function createOpenClawTranscriptDispatcher(params: {
     },
   };
 }
+
+async function resolveAgentRuntime(runtime: PluginRuntime): Promise<AgentRuntimeHelpers> {
+  const runtimeAgent = (runtime as { agent?: Partial<AgentRuntimeHelpers> }).agent;
+  if (hasRequiredAgentHelpers(runtimeAgent)) {
+    return runtimeAgent;
+  }
+
+  const extensionApi = (await import("openclaw/extension-api")) as ExtensionApiWithAliases;
+  return {
+    runEmbeddedAgent: readRunEmbeddedAgent(runtimeAgent, extensionApi),
+    resolveAgentWorkspaceDir: readHelper(runtimeAgent, extensionApi, "resolveAgentWorkspaceDir"),
+    resolveAgentDir: readHelper(runtimeAgent, extensionApi, "resolveAgentDir"),
+    resolveAgentTimeoutMs: readHelper(runtimeAgent, extensionApi, "resolveAgentTimeoutMs"),
+    ensureAgentWorkspace: readOptionalHelper(runtimeAgent, extensionApi, "ensureAgentWorkspace"),
+  };
+}
+
+function hasRequiredAgentHelpers(value: Partial<AgentRuntimeHelpers> | undefined): value is AgentRuntimeHelpers {
+  return (
+    typeof value?.runEmbeddedAgent === "function" &&
+    typeof value.resolveAgentWorkspaceDir === "function" &&
+    typeof value.resolveAgentDir === "function" &&
+    typeof value.resolveAgentTimeoutMs === "function"
+  );
+}
+
+function readRunEmbeddedAgent(
+  runtimeAgent: Partial<AgentRuntimeHelpers> | undefined,
+  extensionApi: ExtensionApiWithAliases,
+): AgentRuntimeHelpers["runEmbeddedAgent"] {
+  const helper = runtimeAgent?.runEmbeddedAgent ?? extensionApi.runEmbeddedAgent ?? extensionApi.runEmbeddedPiAgent;
+  if (typeof helper !== "function") {
+    throw new Error("Loggie transcript dispatch requires OpenClaw agent helper: runEmbeddedAgent");
+  }
+  return helper;
+}
+
+function readHelper<K extends keyof AgentRuntimeHelpers>(
+  runtimeAgent: Partial<AgentRuntimeHelpers> | undefined,
+  extensionApi: ExtensionApi,
+  key: K,
+): AgentRuntimeHelpers[K] {
+  const helper = runtimeAgent?.[key] ?? extensionApi[key];
+  if (typeof helper !== "function") {
+    throw new Error(`Loggie transcript dispatch requires OpenClaw agent helper: ${key}`);
+  }
+  return helper as AgentRuntimeHelpers[K];
+}
+
+function readOptionalHelper<K extends keyof AgentRuntimeHelpers>(
+  runtimeAgent: Partial<AgentRuntimeHelpers> | undefined,
+  extensionApi: ExtensionApi,
+  key: K,
+): AgentRuntimeHelpers[K] | undefined {
+  const helper = runtimeAgent?.[key] ?? extensionApi[key];
+  if (helper !== undefined && typeof helper !== "function") {
+    throw new Error(`Loggie transcript dispatch requires OpenClaw agent helper: ${key}`);
+  }
+  return helper as AgentRuntimeHelpers[K] | undefined;
+}

package/src/status.ts

@@ -5,6 +5,12 @@ export type LoggieRuntimeExtra = {
   connected?: boolean;
   authenticated?: boolean;
   caughtUp?: boolean;
+  cursorStoreMode?: "trusted" | "file" | null;
+  cursorPersistenceFailed?: boolean;
+  lastCursorPersistenceAt?: number | null;
+  lastCursorPersistenceError?: string | null;
+  lastCursorPersistenceEventId?: string | null;
+  lastCursorPersistenceCursor?: string | null;
   lastEventId?: string | null;
   lastCursor?: string | null;
   lastSequence?: number | null;
@@ -22,6 +28,12 @@ export const defaultLoggieRuntimeState = createDefaultChannelRuntimeState<Loggie
     connected: false,
     authenticated: false,
     caughtUp: false,
+    cursorStoreMode: null,
+    cursorPersistenceFailed: false,
+    lastCursorPersistenceAt: null,
+    lastCursorPersistenceError: null,
+    lastCursorPersistenceEventId: null,
+    lastCursorPersistenceCursor: null,
     lastEventId: null,
     lastCursor: null,
     lastSequence: null,
@@ -58,6 +70,12 @@ export function buildLoggieAccountStatusSnapshot(params: {
       connected: params.runtime?.connected ?? false,
       authenticated: params.runtime?.authenticated ?? false,
       caughtUp: params.runtime?.caughtUp ?? false,
+      cursorStoreMode: params.runtime?.cursorStoreMode ?? null,
+      cursorPersistenceFailed: params.runtime?.cursorPersistenceFailed ?? false,
+      lastCursorPersistenceAt: params.runtime?.lastCursorPersistenceAt ?? null,
+      lastCursorPersistenceError: params.runtime?.lastCursorPersistenceError ?? null,
+      lastCursorPersistenceEventId: params.runtime?.lastCursorPersistenceEventId ?? null,
+      lastCursorPersistenceCursor: params.runtime?.lastCursorPersistenceCursor ?? null,
       lastEventId: params.runtime?.lastEventId ?? null,
       lastCursor: params.runtime?.lastCursor ?? null,
       lastSequence: params.runtime?.lastSequence ?? null,