@beeos-ai/device-agent 0.5.1 → 0.6.0

package/dist/app/jsonl-store.js

@@ -0,0 +1,402 @@
+/**
+ * Append-only JSONL persistence layer for `MessageStore`.
+ *
+ * Layout (one file per session, plus one metadata file):
+ *
+ *   ${BEEOS_HOME ?? ~/.beeos}/device-agent/sessions/
+ *     ├── <sid>.jsonl          # append-only record log
+ *     └── <sid>.meta.json      # { sessionId, title, createdAt, updatedAt }
+ *
+ * Each JSONL line is a serialised `PersistedRecord` (see message-store.ts):
+ *
+ *   {"v":1,"type":"user_message","id":"...","ts":...,"content":"...","turnId":"...","messageId":"..."}
+ *   {"v":1,"type":"assistant_turn","id":"...","ts":...,"messageId":"...","turnId":"...",
+ *    "startedAt":...,"completedAt":...,"text":"...","toolCalls":[...],"stopReason":"...","error":"..."}
+ *
+ * IO strategy:
+ *
+ *   - Appends use `fs.writeSync` against a long-lived FD opened in
+ *     append mode (`O_APPEND`). Sync IO sidesteps the buffer-flush
+ *     race that bites WriteStream-based rotation (`clearSession`
+ *     followed immediately by a new append). The blocking cost is
+ *     negligible at our message rate (1-2 records per ~5-10s task).
+ *   - `O_APPEND` guarantees every kernel write seeks to EOF
+ *     atomically, so concurrent appenders on the same file (rare —
+ *     would only happen if two device-agent siblings shared a
+ *     sessions dir) never interleave a single line.
+ *
+ * Crash semantics:
+ *
+ *   - Each write hits disk before the call returns; finalised turns
+ *     survive an unclean shutdown. The user-selected `memory_only`
+ *     in-flight policy means a turn that hadn't yet reached `task:end`
+ *     is lost — that's expected.
+ *   - Reads tolerate partial / corrupt tail lines (the writer might
+ *     have died mid-line on a previous run) by skipping any line that
+ *     fails to parse. Same convention as beeos-claw's
+ *     `LocalSessionHistory.readEntries`.
+ */
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import * as readline from "node:readline";
+import { MessageStore, } from "./message-store.js";
+/**
+ * Debounce window for `<sid>.meta.json` writes. Title / updatedAt change
+ * frequently (every appended turn touches updatedAt) — we coalesce
+ * within 500ms so a bursty stream of appends doesn't fsync metadata
+ * dozens of times per second.
+ */
+const META_DEBOUNCE_MS = 500;
+/**
+ * Persistent variant of `MessageStore` — every append is mirrored to a
+ * per-session JSONL log, every metadata change debounced into
+ * `<sid>.meta.json`.
+ *
+ * Construct via `JsonlMessageStore.open(...)` so the on-disk state can
+ * be loaded into memory before any reads happen.
+ */
+export class JsonlMessageStore extends MessageStore {
+    sessionsDir;
+    logger;
+    /** Lazily-opened append-mode FDs keyed by sessionId. */
+    fds = new Map();
+    metaTimers = new Map();
+    closed = false;
+    constructor(opts) {
+        super({
+            ...(opts.maxRecordsPerSession !== undefined ? { maxRecordsPerSession: opts.maxRecordsPerSession } : {}),
+            ...(opts.maxSessions !== undefined ? { maxSessions: opts.maxSessions } : {}),
+        });
+        this.sessionsDir = opts.sessionsDir;
+        if (opts.logger)
+            this.logger = opts.logger;
+    }
+    /** Construct and load on-disk state into memory. */
+    static async open(opts) {
+        const store = new JsonlMessageStore(opts);
+        await fsp.mkdir(opts.sessionsDir, { recursive: true });
+        const sids = opts.preloadSids
+            ? [...opts.preloadSids]
+            : await store.discoverSids();
+        for (const sid of sids) {
+            await store.preloadSession(sid);
+        }
+        return store;
+    }
+    /** Path of the JSONL transcript for a given sid. */
+    sessionFile(sid) {
+        return path.join(this.sessionsDir, `${safeFilename(sid)}.jsonl`);
+    }
+    /** Path of the metadata file for a given sid. */
+    metaFile(sid) {
+        return path.join(this.sessionsDir, `${safeFilename(sid)}.meta.json`);
+    }
+    /** Discover every sid present on disk by scanning `*.jsonl` files. */
+    async discoverSids() {
+        let entries;
+        try {
+            entries = await fsp.readdir(this.sessionsDir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+        return entries
+            .filter((name) => name.endsWith(".jsonl"))
+            .map((name) => name.slice(0, -".jsonl".length));
+    }
+    /**
+     * Read the JSONL for a sid into memory. Skips rows that fail to
+     * parse (truncated tail line on a previous crash, schema mismatch
+     * from a future version, etc.) so a single bad row doesn't sink the
+     * whole session.
+     */
+    async preloadSession(sid) {
+        const meta = await this.readMeta(sid);
+        if (meta) {
+            // Inject directly into the parent map so we don't bump updatedAt
+            // back to `now` on cold start.
+            this.sessions.set(sid, {
+                sessionId: meta.sessionId,
+                title: meta.title,
+                createdAt: meta.createdAt,
+                updatedAt: meta.updatedAt,
+            });
+        }
+        else {
+            // Will be populated by the first record we read, then synced to
+            // disk on the next mutation (or close).
+            this.sessions.set(sid, {
+                sessionId: sid,
+                title: "New chat",
+                createdAt: Date.now(),
+                updatedAt: 0,
+            });
+        }
+        const file = this.sessionFile(sid);
+        if (!fs.existsSync(file))
+            return;
+        const rl = readline.createInterface({
+            input: fs.createReadStream(file, { encoding: "utf8" }),
+            crlfDelay: Infinity,
+        });
+        let parsed = 0;
+        let skipped = 0;
+        for await (const rawLine of rl) {
+            const line = rawLine.trim();
+            if (!line)
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(line);
+            }
+            catch {
+                skipped++;
+                continue;
+            }
+            if (!isPersistedRecord(rec)) {
+                skipped++;
+                continue;
+            }
+            this.loadRecord(sid, rec);
+            parsed++;
+        }
+        if (skipped > 0) {
+            this.logger?.warn({ sid, parsed, skipped, file }, "jsonl-store: skipped malformed lines during preload");
+        }
+        // If preload populated records but we had no meta on disk,
+        // backfill createdAt from the earliest record so the index
+        // matches the transcript.
+        if (!meta) {
+            const records = this.records.get(sid);
+            if (records && records.length > 0) {
+                const first = records[0];
+                const last = records[records.length - 1];
+                const session = this.sessions.get(sid);
+                session.createdAt = first.ts;
+                session.updatedAt = Math.max(session.updatedAt, last.ts);
+            }
+        }
+    }
+    async readMeta(sid) {
+        try {
+            const raw = await fsp.readFile(this.metaFile(sid), "utf8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.sessionId === "string" &&
+                typeof parsed.title === "string" &&
+                typeof parsed.createdAt === "number" &&
+                typeof parsed.updatedAt === "number") {
+                return parsed;
+            }
+            return null;
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            this.logger?.warn({ sid, err: err.message }, "jsonl-store: failed to read meta.json — falling back to defaults");
+            return null;
+        }
+    }
+    getOrCreateFd(sid) {
+        let fd = this.fds.get(sid);
+        if (fd === undefined) {
+            // O_APPEND ("a") makes every kernel write seek to EOF atomically,
+            // safe against concurrent appenders on the same file.
+            fd = fs.openSync(this.sessionFile(sid), "a");
+            this.fds.set(sid, fd);
+        }
+        return fd;
+    }
+    // ── overrides — every mutation also persists ─────────────────────────────
+    appendUserMessage(sessionId, content, opts = {}) {
+        if (this.closed)
+            throw new Error("JsonlMessageStore: appendUserMessage on closed store");
+        const record = super.appendUserMessage(sessionId, content, opts);
+        this.writeJsonlLine(sessionId, record);
+        this.scheduleMetaWrite(sessionId);
+        return record;
+    }
+    appendAssistantTurn(sessionId, turn, opts = {}) {
+        if (this.closed)
+            throw new Error("JsonlMessageStore: appendAssistantTurn on closed store");
+        const record = super.appendAssistantTurn(sessionId, turn, opts);
+        this.writeJsonlLine(sessionId, record);
+        this.scheduleMetaWrite(sessionId);
+        return record;
+    }
+    upsertSession(sessionId, title) {
+        super.upsertSession(sessionId, title);
+        this.scheduleMetaWrite(sessionId);
+    }
+    renameSession(sessionId, title) {
+        super.renameSession(sessionId, title);
+        this.scheduleMetaWrite(sessionId);
+    }
+    clearSession(sessionId) {
+        super.clearSession(sessionId);
+        // Truncate the JSONL on disk — we just lost the in-memory log so
+        // the file should match. Stream needs to be rotated so subsequent
+        // appends start from offset 0.
+        this.rotateStream(sessionId);
+        this.scheduleMetaWrite(sessionId);
+    }
+    deleteSession(sessionId) {
+        super.deleteSession(sessionId);
+        // Close any open FD first to avoid Windows EBUSY on unlink.
+        this.closeFd(sessionId);
+        // Cancel any pending meta write — the file is about to be gone.
+        const debounced = this.metaTimers.get(sessionId);
+        if (debounced) {
+            clearTimeout(debounced.timer);
+            this.metaTimers.delete(sessionId);
+        }
+        // Sync unlinks — the public API is sync so callers (including
+        // tests) expect the files to be gone by the time we return.
+        unlinkSyncIfExists(this.sessionFile(sessionId), this.logger);
+        unlinkSyncIfExists(this.metaFile(sessionId), this.logger);
+    }
+    // ── shutdown ─────────────────────────────────────────────────────────────
+    /** Flush every pending meta write and close every open FD. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Flush any pending meta writes.
+        const metaWrites = [];
+        for (const [sid, debounced] of this.metaTimers) {
+            clearTimeout(debounced.timer);
+            metaWrites.push(this.writeMetaNow(sid, debounced.pending));
+        }
+        this.metaTimers.clear();
+        // JSONL writes are sync, so the FDs hold no pending data — just
+        // close them.
+        for (const sid of Array.from(this.fds.keys())) {
+            this.closeFd(sid);
+        }
+        await Promise.all(metaWrites);
+    }
+    // ── helpers ──────────────────────────────────────────────────────────────
+    writeJsonlLine(sid, record) {
+        const fd = this.getOrCreateFd(sid);
+        const line = JSON.stringify(record) + "\n";
+        fs.writeSync(fd, line);
+    }
+    closeFd(sid) {
+        const fd = this.fds.get(sid);
+        if (fd === undefined)
+            return;
+        this.fds.delete(sid);
+        try {
+            fs.closeSync(fd);
+        }
+        catch (err) {
+            this.logger?.warn({ sid, err: err.message }, "jsonl-store: failed to close JSONL fd");
+        }
+    }
+    rotateStream(sid) {
+        // Close the FD first so the truncate sees no in-flight writers.
+        // Sync IO means there are no buffered writes to discard — every
+        // appendUserMessage / appendAssistantTurn already hit disk before
+        // returning.
+        this.closeFd(sid);
+        try {
+            fs.writeFileSync(this.sessionFile(sid), "");
+        }
+        catch (err) {
+            this.logger?.warn({ sid, err: err.message }, "jsonl-store: failed to truncate JSONL during clearSession");
+        }
+    }
+    scheduleMetaWrite(sid) {
+        const meta = this.snapshotMeta(sid);
+        if (!meta)
+            return;
+        const existing = this.metaTimers.get(sid);
+        if (existing) {
+            existing.pending = meta;
+            return;
+        }
+        const timer = setTimeout(() => {
+            const cur = this.metaTimers.get(sid);
+            this.metaTimers.delete(sid);
+            if (!cur)
+                return;
+            void this.writeMetaNow(sid, cur.pending);
+        }, META_DEBOUNCE_MS);
+        // Don't keep the event loop alive solely for the meta debounce —
+        // a paused / idle agent should still be able to exit cleanly.
+        if (typeof timer.unref === "function")
+            timer.unref();
+        this.metaTimers.set(sid, { timer, pending: meta });
+    }
+    snapshotMeta(sid) {
+        const s = this.sessions.get(sid);
+        if (!s)
+            return null;
+        return {
+            sessionId: s.sessionId,
+            title: s.title,
+            createdAt: s.createdAt,
+            updatedAt: s.updatedAt,
+        };
+    }
+    async writeMetaNow(sid, meta) {
+        try {
+            // Atomic-enough: write to tmp + rename. Avoids a torn meta file
+            // if the process dies mid-write (rare, but cheap to defend).
+            const file = this.metaFile(sid);
+            const tmp = `${file}.tmp`;
+            await fsp.writeFile(tmp, JSON.stringify(meta) + "\n", "utf8");
+            await fsp.rename(tmp, file);
+        }
+        catch (err) {
+            this.logger?.warn({ sid, err: err.message }, "jsonl-store: failed to write meta.json");
+        }
+    }
+}
+/** Reject sids that would escape the sessions directory. */
+function safeFilename(sid) {
+    // Forbid path separators and the magic dotted entries; allow `:` for
+    // our `device:<deviceId>` convention by transliterating to `_`.
+    const cleaned = sid.replace(/[\\/]/g, "_").replace(/^\.+$/, "_");
+    return cleaned.replace(/:/g, "_");
+}
+function unlinkSyncIfExists(file, logger) {
+    try {
+        fs.unlinkSync(file);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return;
+        logger?.warn({ file, err: err.message }, "jsonl-store: failed to unlink file");
+    }
+}
+/**
+ * Best-effort schema check. Anything that doesn't look like a v1
+ * `user_message` or `assistant_turn` record is dropped.
+ */
+function isPersistedRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const r = value;
+    if (r.v !== 1)
+        return false;
+    if (typeof r.id !== "string" || typeof r.ts !== "number")
+        return false;
+    if (r.type === "user_message") {
+        return typeof r.content === "string";
+    }
+    if (r.type === "assistant_turn") {
+        return (typeof r.text === "string" &&
+            typeof r.messageId === "string" &&
+            typeof r.turnId === "string" &&
+            typeof r.startedAt === "number" &&
+            typeof r.completedAt === "number" &&
+            Array.isArray(r.toolCalls) &&
+            typeof r.stopReason === "string");
+    }
+    return false;
+}
+//# sourceMappingURL=jsonl-store.js.map

package/dist/app/jsonl-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl-store.js","sourceRoot":"","sources":["../../src/app/jsonl-store.ts"],"names":[],"mappings":"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"}

package/dist/app/message-store.d.ts

@@ -1,55 +1,106 @@
 /**
- * In-memory MessageStore.
+ * In-memory MessageStore — typed turn-grained transcript log.
  *
- * Mirrors the surface of the Python `MessageStore` (`add_message`,
- * `get_messages_as_dicts`, `list_sessions`, etc.) so the ACP handlers stay
- * byte-for-byte compatible. Persistence is left out of the MVP; `~/.beeos`
- * SQLite can be re-added later behind the same interface (pluggable adapter).
+ * Each session holds an ordered list of `PersistedRecord`s, one per
+ * logical turn:
+ *
+ *  - `user_message` — emitted on `session/prompt` entry.
+ *  - `assistant_turn` — emitted exactly once per `task:end` (replaces
+ *    the legacy "one row per chunk" model that produced fragmented
+ *    transcripts on reload). Carries the full `text`, every tool call
+ *    in invocation order, the stop reason, and an optional terminal
+ *    error string.
+ *
+ * This base class is pure in-memory; persistence is added by
+ * `JsonlMessageStore` which extends this and forwards every mutation
+ * to disk before returning.
+ *
+ * The shape is deliberately aligned with OpenClaw's per-agent JSONL
+ * (`~/.openclaw/agents/<id>/sessions/<sid>.jsonl`) so operational
+ * tooling that already knows that layout works here too.
  */
-export interface StoredMessage {
+import type { AssistantTurnRecord } from "./in-flight-turn.js";
+/** Schema version. Bumped only on incompatible disk format changes. */
+export declare const RECORD_SCHEMA_VERSION: 1;
+/** A user-authored message — written on `session/prompt` entry. */
+export interface UserMessageRecord {
+    v: typeof RECORD_SCHEMA_VERSION;
+    type: "user_message";
+    /** Stable row id. Unique within a sid. */
     id: string;
-    sessionId: string;
-    role: "user" | "assistant" | "system" | "tool";
+    /** Wall-clock timestamp at write time (epoch ms). */
+    ts: number;
+    /** Plain text of the prompt (resource-link normalisation already applied). */
     content: string;
-    messageType: "text" | "tool_call" | "tool_result" | "status";
-    metadata: Record<string, unknown>;
-    createdAt: number;
+    /** turnId of the corresponding assistant turn — populated when known. */
+    turnId?: string;
+    /** messageId of the corresponding assistant turn — populated when known. */
+    messageId?: string;
 }
+/** Persisted shape of an assistant turn — wraps `AssistantTurnRecord`. */
+export interface PersistedAssistantTurn extends AssistantTurnRecord {
+    v: typeof RECORD_SCHEMA_VERSION;
+    type: "assistant_turn";
+    /** Stable row id. Unique within a sid. */
+    id: string;
+    /** Wall-clock timestamp at write time (epoch ms) — equals `completedAt`. */
+    ts: number;
+}
+export type PersistedRecord = UserMessageRecord | PersistedAssistantTurn;
 export interface SessionRecord {
     sessionId: string;
     title: string;
     createdAt: number;
     updatedAt: number;
 }
-export interface MessageHistoryEntry {
-    role: string;
-    content: string;
-    type: string;
-    createdAt: number;
-    metadata?: Record<string, unknown>;
+export interface MessageStoreOptions {
+    /** Soft cap on records kept per session. LRU evicts the oldest. */
+    maxRecordsPerSession?: number;
+    /** Soft cap on session count — LRU evicts least-recently-updated. */
+    maxSessions?: number;
 }
+/** Mutable in-memory message store. */
 export declare class MessageStore {
-    private readonly maxPerSession;
-    private readonly maxSessions;
-    private readonly sessions;
-    private readonly messages;
-    constructor(opts?: {
-        maxMessagesPerSession?: number;
-        maxSessions?: number;
-    });
+    protected readonly maxRecordsPerSession: number;
+    protected readonly maxSessions: number;
+    protected readonly sessions: Map<string, SessionRecord>;
+    protected readonly records: Map<string, PersistedRecord[]>;
+    constructor(opts?: MessageStoreOptions);
     upsertSession(sessionId: string, title?: string): void;
     sessionExists(sessionId: string): boolean;
     renameSession(sessionId: string, title: string): void;
     deleteSession(sessionId: string): void;
+    /** Drop every record in a session but keep the session record itself. */
+    clearSession(sessionId: string): void;
     listSessions(limit?: number): Array<{
         sessionId: string;
         title: string;
         updatedAt: number;
     }>;
-    clearSession(sessionId: string): void;
-    addMessage(sessionId: string, role: StoredMessage["role"], content: string, messageType?: StoredMessage["messageType"], metadata?: Record<string, unknown>): string;
-    getMessages(sessionId: string, limit?: number): StoredMessage[];
-    getMessagesAsDicts(sessionId: string, limit?: number): MessageHistoryEntry[];
-    /** Drop the least-recently-updated sessions when we exceed maxSessions. */
-    private evictSessionLru;
+    /** Append a user prompt row. Returns the persisted record. */
+    appendUserMessage(sessionId: string, content: string, opts?: {
+        turnId?: string;
+        messageId?: string;
+        now?: number;
+    }): UserMessageRecord;
+    /** Append a finalized assistant turn. Returns the persisted record. */
+    appendAssistantTurn(sessionId: string, turn: AssistantTurnRecord, opts?: {
+        now?: number;
+    }): PersistedAssistantTurn;
+    /** Pre-loaded record (used by `JsonlMessageStore.open` to seed memory). */
+    loadRecord(sessionId: string, record: PersistedRecord): void;
+    /** All records for a session in chronological insertion order. */
+    getTurns(sessionId: string): PersistedRecord[];
+    /** True iff at least one record exists for this session. */
+    hasRecords(sessionId: string): boolean;
+    /**
+     * Append a record to memory and bump session.updatedAt.
+     * Subclasses (JsonlMessageStore) override to additionally persist.
+     *
+     * `touch=false` is used by `loadRecord` so a cold-start replay of a
+     * year-old transcript doesn't artificially bump updatedAt to "now".
+     */
+    protected persistRecord(sessionId: string, record: PersistedRecord, ts: number, touch?: boolean): void;
+    /** Drop the least-recently-updated sessions when exceeding maxSessions. */
+    protected evictSessionLru(): void;
 }