antechamber 1.0.40 → 2.0.1

package/dist/session-store.js

@@ -6,7 +6,7 @@
  * so the adapter never needs its own transcript store — only:
  *
  *   1. a scan of that directory to rebuild the sidebar after a restart, and
- *   2. a small registry JSON for adapter-owned metadata that pi does not
+ *   2. a SQLite registry for adapter-owned metadata that pi does not
  *      keep (titles, conversation cursors and child-task metadata).
  *
  * OpenChamber session ids for restored sessions are derived deterministically
@@ -14,8 +14,9 @@
  * the same OpenChamber id, even if the registry file is lost.
  */
 import { createHash } from "node:crypto";
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, } from "node:fs";
 import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
 import { piAgentDir } from "./agent-dir.js";
 import { isPromptPart } from "./prompt-parts.js";
 import { defaultStateDir, envSetting } from "./config.js";
@@ -42,9 +43,6 @@ const TITLE_MAX_LINES = 200;
 const TITLE_MAX_CHARS = 60;
 const REGISTRY_DIRECTORY_MODE = 0o700;
 const REGISTRY_FILE_MODE = 0o600;
-const REGISTRY_LOCK_RETRY_MS = 10;
-const REGISTRY_LOCK_STALE_MS = 5_000;
-const registryLockWaiter = new Int32Array(new SharedArrayBuffer(4));
 function readHead(path, bytes = SNIFF_BYTES) {
     const fd = openSync(path, "r");
     try {
@@ -359,7 +357,7 @@ export function scanPiSessions(directory) {
 }
 /**
  * Persistent oc-session-id → metadata registry (title overrides, known pi
- * paths). Atomic writes, lazy load, corrupt file degrades to an empty map.
+ * paths). Legacy JSON records are validated at migration; SQLite writes are atomic.
  */
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -387,12 +385,31 @@ function sessionTreeState(value) {
     if (value.promptMetadata !== undefined &&
         (!record(value.promptMetadata) || !Object.values(value.promptMetadata).every((metadata) => record(metadata))))
         return false;
+    if (value.promptDescriptions !== undefined && !stringRecord(value.promptDescriptions))
+        return false;
+    if (value.compactionReasons !== undefined &&
+        (!stringRecord(value.compactionReasons) ||
+            !Object.values(value.compactionReasons).every((reason) => reason === "manual" || reason === "auto")))
+        return false;
     if (value.messageParts !== undefined &&
         (!record(value.messageParts) ||
             !Object.values(value.messageParts).every((parts) => Array.isArray(parts) && parts.every((part) => typeof part === "string"))))
         return false;
     if (value.shellDispatch !== undefined && !booleanRecord(value.shellDispatch))
         return false;
+    const finite = (item) => typeof item === "number" && Number.isFinite(item);
+    if (value.lastIdle !== undefined && !finite(value.lastIdle))
+        return false;
+    if (value.compactionAdmissions !== undefined &&
+        (!record(value.compactionAdmissions) || !Object.values(value.compactionAdmissions).every(finite)))
+        return false;
+    if (value.idleBoundaries !== undefined &&
+        (!record(value.idleBoundaries) ||
+            !Object.values(value.idleBoundaries).every((boundary) => record(boundary) &&
+                finite(boundary.at) &&
+                ["succeeded", "failed", "interrupted"].includes(boundary.outcome) &&
+                (boundary.error === undefined || record(boundary.error)))))
+        return false;
     if (value.leafId !== undefined && value.leafId !== null && typeof value.leafId !== "string")
         return false;
     if (value.fileSize !== undefined && (typeof value.fileSize !== "number" || !Number.isFinite(value.fileSize)))
@@ -448,6 +465,13 @@ function registryEntry(value) {
         return false;
     if (value.metadata !== undefined && !record(value.metadata))
         return false;
+    if (value.instructions !== undefined &&
+        (!record(value.instructions) ||
+            !Object.entries(value.instructions).every(([key, entry]) => /^[a-z0-9][a-z0-9._-]*$/.test(key) &&
+                record(entry) &&
+                "value" in entry &&
+                (entry.removed === undefined || entry.removed === true))))
+        return false;
     if (value.task !== undefined && !childTask(value.task))
         return false;
     if (value.title !== undefined && typeof value.title !== "string")
@@ -456,6 +480,8 @@ function registryEntry(value) {
         return false;
     if (value.archived !== undefined && (typeof value.archived !== "number" || !Number.isFinite(value.archived)))
         return false;
+    if (value.viewed !== undefined && (typeof value.viewed !== "number" || !Number.isFinite(value.viewed)))
+        return false;
     if (value.model !== undefined &&
         (!record(value.model) || typeof value.model.providerID !== "string" || typeof value.model.modelID !== "string"))
         return false;
@@ -484,140 +510,231 @@ function errorCode(error) {
 export class SessionStore {
     stateDir;
     file;
-    entries;
-    /** The registry bytes `entries` was parsed from or last written as; equal bytes on disk mean the cache is current. */
-    raw;
+    db;
+    version;
+    entries = new Map();
     batchState;
     constructor(stateDir) {
         const dir = stateDir ?? envSetting("STATE_DIR") ?? defaultStateDir();
         this.stateDir = dir;
-        this.file = join(dir, "sessions.json");
-    }
-    load() {
-        if (this.batchState !== undefined) {
-            // Shallow: changes replace whole entries, and get() clones an entry before handing it out.
-            this.batchState.entries ??= new Map(this.committed());
-            return this.batchState.entries;
-        }
-        return this.committed();
-    }
-    committed() {
-        if (this.entries !== undefined)
-            return this.entries;
-        this.raw = this.readRaw();
-        this.entries = this.parseEntries(this.raw);
-        return this.entries;
+        this.file = join(dir, "sessions.sqlite");
     }
-    readRaw() {
-        try {
-            return readFileSync(this.file);
-        }
-        catch {
+    database(write = false) {
+        if (this.db !== undefined)
+            return this.db;
+        const legacy = join(this.stateDir, "sessions.json");
+        if (!write && !existsSync(this.file) && !existsSync(legacy))
             return undefined;
-        }
-    }
-    parseEntries(raw) {
-        const entries = new Map();
-        if (raw === undefined)
-            return entries;
+        let db;
         try {
-            const parsed = JSON.parse(raw.toString("utf8"));
-            if (!record(parsed))
-                return entries;
-            for (const [id, value] of Object.entries(parsed))
-                if (registryEntry(value))
-                    entries.set(id, value);
+            mkdirSync(this.stateDir, { recursive: true, mode: REGISTRY_DIRECTORY_MODE });
+            chmodSync(this.stateDir, REGISTRY_DIRECTORY_MODE);
+            // SQLite inherits the database mode for WAL/SHM; set it before enabling WAL.
+            closeSync(openSync(this.file, "a", REGISTRY_FILE_MODE));
+            chmodSync(this.file, REGISTRY_FILE_MODE);
+            db = new DatabaseSync(this.file);
+            db.exec("PRAGMA busy_timeout = 5000; PRAGMA journal_mode = WAL;");
+            db.exec(`CREATE TABLE IF NOT EXISTS sessions (
+        id TEXT PRIMARY KEY, payload TEXT NOT NULL, pi_session_id TEXT NOT NULL,
+        directory TEXT NOT NULL, parent_id TEXT, has_task INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS sessions_pi ON sessions(pi_session_id);
+      CREATE INDEX IF NOT EXISTS sessions_directory ON sessions(directory);
+      CREATE INDEX IF NOT EXISTS sessions_children ON sessions(parent_id) WHERE has_task = 1;
+      CREATE TABLE IF NOT EXISTS registry_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);`);
+            this.migrate(db, legacy);
+            for (const suffix of ["-wal", "-shm"]) {
+                const path = this.file + suffix;
+                if (existsSync(path))
+                    chmodSync(path, REGISTRY_FILE_MODE);
+            }
+            this.db = db;
+            return db;
         }
-        catch {
-            /* corrupt — start empty */
+        catch (error) {
+            db?.close();
+            throw new SessionPersistenceError(this.file, error);
         }
-        return entries;
     }
-    withRegistryLock(action) {
-        const lock = `${this.file}.lock`;
-        let fd;
+    migrate(db, legacy) {
+        const meta = (key) => db.prepare("SELECT value FROM registry_meta WHERE key = ?").get(key)?.value;
+        const setMeta = (key, value) => db
+            .prepare("INSERT INTO registry_meta VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+            .run(key, value);
+        db.prepare("INSERT OR IGNORE INTO registry_meta VALUES ('created_at', ?)").run(String(Date.now()));
+        if (!existsSync(legacy))
+            return;
+        db.exec("BEGIN IMMEDIATE");
+        let backup;
+        let merged = 0;
         try {
-            mkdirSync(this.stateDir, { recursive: true, mode: REGISTRY_DIRECTORY_MODE });
-            chmodSync(this.stateDir, REGISTRY_DIRECTORY_MODE);
-            for (;;) {
+            const imported = meta("legacy_backup");
+            const parse = () => {
                 try {
-                    fd = openSync(lock, "wx", REGISTRY_FILE_MODE);
-                    break;
+                    const parsed = JSON.parse(readFileSync(legacy, "utf8"));
+                    return record(parsed) ? parsed : undefined;
                 }
                 catch (error) {
-                    if (errorCode(error) !== "EEXIST")
+                    if (!(error instanceof SyntaxError))
                         throw error;
-                    try {
-                        if (Date.now() - statSync(lock).mtimeMs >= REGISTRY_LOCK_STALE_MS) {
-                            unlinkSync(lock);
+                    // Preserve malformed JSON untouched; a later repair can still be imported.
+                    return undefined;
+                }
+            };
+            if (typeof imported === "string" && !existsSync(imported))
+                backup = imported;
+            else if (imported === undefined && db.prepare("SELECT 1 FROM sessions LIMIT 1").get() === undefined) {
+                const parsed = parse();
+                if (parsed !== undefined) {
+                    const upsert = this.upsert(db);
+                    for (const [id, entry] of Object.entries(parsed))
+                        if (registryEntry(entry))
+                            this.writeRow(upsert, id, entry);
+                    backup = `${legacy}.migrated-${Date.now()}-${process.pid}`;
+                    setMeta("legacy_backup", backup);
+                    setMeta("reconciled_at", String(Date.now()));
+                }
+            }
+            else {
+                // A sessions.json next to a populated registry was written by an older antechamber after the migration (a
+                // rollback). Sessions it changed since then are newer than the rows here; older entries, including ones
+                // deleted since, stay as the registry has them.
+                const since = Number(meta("reconciled_at") ?? /\.migrated-(\d+)-/.exec(String(imported))?.[1] ?? meta("created_at") ?? Infinity);
+                const parsed = parse();
+                if (parsed !== undefined) {
+                    const upsert = this.upsert(db);
+                    for (const [id, entry] of Object.entries(parsed)) {
+                        if (!registryEntry(entry) || !(entry.updated > since))
+                            continue;
+                        const current = this.read(db, id);
+                        if (current !== undefined && current.updated >= entry.updated)
                             continue;
-                        }
+                        this.writeRow(upsert, id, entry);
+                        merged += 1;
                     }
-                    catch (staleLockError) {
-                        if (errorCode(staleLockError) !== "ENOENT")
-                            throw staleLockError;
-                        continue;
+                    if (merged > 0) {
+                        backup = `${legacy}.merged-${Date.now()}-${process.pid}`;
+                        setMeta("reconciled_at", String(Date.now()));
                     }
-                    Atomics.wait(registryLockWaiter, 0, 0, REGISTRY_LOCK_RETRY_MS);
                 }
             }
-            return action();
+            db.exec("COMMIT");
         }
         catch (error) {
-            throw new SessionPersistenceError(this.file, error);
+            db.exec("ROLLBACK");
+            throw error;
         }
-        finally {
-            if (fd !== undefined) {
-                closeSync(fd);
-                unlinkSync(lock);
+        if (merged > 0)
+            this.entries.clear();
+        if (merged > 0)
+            console.warn(`[session-store] merged ${merged} sessions an older antechamber wrote to ${legacy}`);
+        // The durable marker handles a crash after COMMIT but before rename, including an empty import.
+        // Never overwrite an existing backup or import the same legacy file after sessions are deleted.
+        if (backup !== undefined && !existsSync(backup)) {
+            try {
+                chmodSync(legacy, REGISTRY_FILE_MODE);
+                renameSync(legacy, backup);
+            }
+            catch (error) {
+                if (errorCode(error) !== "ENOENT")
+                    throw error;
             }
         }
     }
-    persist(entries) {
-        const obj = Object.fromEntries([...entries].map(([id, entry]) => [id, persistedEntry(entry)]));
-        const tmp = `${this.file}.${process.pid}.tmp`;
-        const data = Buffer.from(JSON.stringify(obj));
-        writeFileSync(tmp, data, { mode: REGISTRY_FILE_MODE });
-        chmodSync(tmp, REGISTRY_FILE_MODE);
-        renameSync(tmp, this.file);
-        return data;
-    }
-    mutate(change) {
-        if (this.batchState !== undefined) {
-            this.batchState.changes.push(change);
-            change(this.load());
-            return;
+    upsert(db) {
+        return db.prepare(`INSERT INTO sessions (id, payload, pi_session_id, directory, parent_id, has_task)
+      VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET
+      payload=excluded.payload, pi_session_id=excluded.pi_session_id, directory=excluded.directory,
+      parent_id=excluded.parent_id, has_task=excluded.has_task`);
+    }
+    writeRow(statement, id, entry) {
+        statement.run(id, JSON.stringify(persistedEntry(entry)), entry.piSessionId, entry.directory, entry.parentID ?? null, entry.task === undefined ? 0 : 1);
+    }
+    refresh(db) {
+        const version = db.prepare("PRAGMA data_version").get()?.data_version;
+        if (typeof version !== "number" && typeof version !== "bigint")
+            throw new Error("Invalid SQLite data_version");
+        if (this.version !== version) {
+            this.entries.clear();
+            this.version = version;
+        }
+    }
+    read(db, id) {
+        const cached = this.entries.get(id);
+        if (cached !== undefined)
+            return cached;
+        const payload = db.prepare("SELECT payload FROM sessions WHERE id = ?").get(id)?.payload;
+        if (typeof payload !== "string")
+            return undefined;
+        const entry = JSON.parse(payload);
+        if (!registryEntry(entry))
+            return undefined;
+        this.entries.set(id, entry);
+        return entry;
+    }
+    persist(changes) {
+        try {
+            mkdirSync(this.stateDir, { recursive: true, mode: REGISTRY_DIRECTORY_MODE });
+            chmodSync(this.stateDir, REGISTRY_DIRECTORY_MODE);
+            const db = this.database(true);
+            db.exec("BEGIN IMMEDIATE");
+            const changed = new Map();
+            try {
+                this.refresh(db);
+                for (const { id, apply } of changes) {
+                    const previous = changed.has(id) ? changed.get(id) : this.read(db, id);
+                    const next = apply(previous);
+                    if (next !== undefined || previous !== undefined)
+                        changed.set(id, next);
+                }
+                const upsert = this.upsert(db);
+                const remove = db.prepare("DELETE FROM sessions WHERE id = ?");
+                for (const [id, entry] of changed) {
+                    if (entry === undefined)
+                        remove.run(id);
+                    else
+                        this.writeRow(upsert, id, entry);
+                }
+                db.exec("COMMIT");
+            }
+            catch (error) {
+                db.exec("ROLLBACK");
+                throw error;
+            }
+            for (const [id, entry] of changed) {
+                if (entry === undefined)
+                    this.entries.delete(id);
+                else
+                    this.entries.set(id, entry);
+            }
+        }
+        catch (error) {
+            if (error instanceof SessionPersistenceError)
+                throw error;
+            throw new SessionPersistenceError(this.file, error);
         }
-        this.withRegistryLock(() => {
-            // Another process may have written since; only parse again when the bytes differ.
-            const raw = this.readRaw();
-            const entries = this.entries !== undefined && raw !== undefined && this.raw !== undefined && raw.equals(this.raw)
-                ? new Map(this.entries)
-                : this.parseEntries(raw);
-            const written = change(entries) ? this.persist(entries) : raw;
-            this.entries = entries;
-            this.raw = written;
-        });
     }
-    /** Synchronous restoration reads its own changes, then merges them under one short-lived write lock. */
+    mutate(id, apply) {
+        const batch = this.batchState;
+        if (batch === undefined)
+            this.persist([{ id, apply }]);
+        else {
+            const previous = this.get(id);
+            batch.changes.push({ id, apply });
+            batch.entries.set(id, apply(previous));
+        }
+    }
+    /** Stage only touched rows; replay partial updates against the latest rows under SQLite's write lock. */
     batch(action) {
         if (this.batchState !== undefined)
             return action();
-        const changes = [];
-        const batch = { entries: undefined, isolated: new WeakSet(), changes };
+        const batch = { entries: new Map(), changes: [] };
         this.batchState = batch;
         try {
             const result = action();
             this.batchState = undefined;
-            if (batch.changes.length !== 0) {
-                this.mutate((entries) => {
-                    let changed = false;
-                    for (const change of batch.changes)
-                        if (change(entries))
-                            changed = true;
-                    return changed;
-                });
-            }
+            if (batch.changes.length !== 0)
+                this.persist(batch.changes);
             return result;
         }
         finally {
@@ -625,49 +742,70 @@ export class SessionStore {
         }
     }
     get(ocSessionId) {
-        const entries = this.load();
-        const entry = entries.get(ocSessionId);
-        if (this.batchState === undefined || entry === undefined || this.batchState.isolated.has(entry))
+        const batch = this.batchState;
+        if (batch?.entries.has(ocSessionId))
+            return batch.entries.get(ocSessionId);
+        const db = this.database();
+        if (db === undefined)
+            return undefined;
+        this.refresh(db);
+        const entry = this.read(db, ocSessionId);
+        if (batch === undefined)
             return entry;
-        const staged = structuredClone(entry);
-        entries.set(ocSessionId, staged);
-        this.batchState.isolated.add(staged);
+        const staged = entry === undefined ? undefined : structuredClone(entry);
+        batch.entries.set(ocSessionId, staged);
         return staged;
     }
     idFor(piSessionId) {
-        return [...this.load()].find(([, entry]) => entry.piSessionId === piSessionId)?.[0];
+        return this.matching("SELECT id FROM sessions WHERE pi_session_id = ? ORDER BY rowid", [piSessionId], (entry) => entry.piSessionId === piSessionId)[0];
     }
     childIds() {
-        return [...this.load()]
-            .filter(([, entry]) => entry.task !== undefined && entry.parentID !== undefined)
-            .map(([id]) => id);
+        return this.matching("SELECT id FROM sessions WHERE has_task = 1 AND parent_id IS NOT NULL ORDER BY rowid", [], (entry) => entry.task !== undefined && entry.parentID !== undefined);
+    }
+    matching(query, parameters, matches) {
+        const db = this.database();
+        if (db !== undefined)
+            this.refresh(db);
+        const ids = new Set();
+        for (const row of db?.prepare(query).all(...parameters) ?? [])
+            if (typeof row.id === "string")
+                ids.add(row.id);
+        if (this.batchState === undefined)
+            return [...ids];
+        for (const id of this.batchState?.entries.keys() ?? [])
+            ids.add(id);
+        return [...ids].filter((id) => {
+            const entry = this.get(id);
+            return entry !== undefined && matches(entry);
+        });
     }
     set(ocSessionId, entry) {
         const saved = this.batchState === undefined ? entry : structuredClone(entry);
-        this.mutate((entries) => {
-            entries.set(ocSessionId, this.batchState === undefined ? saved : structuredClone(saved));
-            return true;
-        });
+        this.mutate(ocSessionId, () => (this.batchState === undefined ? saved : structuredClone(saved)));
     }
     /** Merge a partial update (e.g. title override, updated timestamp). */
     update(ocSessionId, patch) {
         const saved = this.batchState === undefined ? patch : structuredClone(patch);
-        this.mutate((entries) => {
-            const previous = entries.get(ocSessionId);
-            if (previous === undefined)
-                return false;
-            entries.set(ocSessionId, {
+        this.mutate(ocSessionId, (previous) => previous === undefined
+            ? undefined
+            : {
                 ...previous,
                 ...(this.batchState === undefined ? saved : structuredClone(saved)),
             });
-            return true;
-        });
     }
     remove(ocSessionId) {
-        this.mutate((entries) => entries.delete(ocSessionId));
+        this.mutate(ocSessionId, () => undefined);
     }
     /** Every directory the registry knows about — used to resolve bare session ids. */
     directories() {
-        return [...new Set([...this.load().values()].map((e) => e.directory))];
+        const db = this.database();
+        const directories = new Set();
+        for (const row of db?.prepare("SELECT DISTINCT directory FROM sessions").all() ?? [])
+            if (typeof row.directory === "string")
+                directories.add(row.directory);
+        if (this.batchState === undefined)
+            return [...directories];
+        const ids = this.matching("SELECT id FROM sessions", [], () => true);
+        return [...new Set(ids.map((id) => this.get(id).directory))];
     }
 }

package/dist/session-tree.d.ts

@@ -1,6 +1,6 @@
 import { type PiRpcClient } from "./pi-rpc.js";
 import type { ManagedSession } from "./sessions.js";
-import type { OCMessageWithParts } from "./types.js";
+import type { OCAssistantMessage, OCMessageWithParts, OCSession } from "./types.js";
 import type { OCPromptPart } from "./types.js";
 export interface SessionTreeState {
     messageEntries: Record<string, string>;
@@ -10,6 +10,10 @@ export interface SessionTreeState {
     promptParts?: Record<string, OCPromptPart[]>;
     /** Client prompt metadata; native RPC does not store it. */
     promptMetadata?: Record<string, Record<string, unknown>>;
+    /** Client-provided synthetic notice labels; native RPC stores only the context text. */
+    promptDescriptions?: Record<string, string>;
+    /** Native compaction reasons by the durable compaction entry ID. */
+    compactionReasons?: Record<string, "manual" | "auto">;
     /** Actual transport dispatch, not inferred from a card's terminal state. */
     shellDispatch?: Record<string, boolean>;
     /** Identity-only dispatched admissions; never rendered without a native entry. */
@@ -25,6 +29,16 @@ export interface SessionTreeState {
         previousLeafId: string | null;
         targetId: string | null;
     };
+    /** Execution boundaries observed over RPC, retained with the durable message identities. */
+    idleBoundaries?: Record<string, {
+        at: number;
+        outcome: NonNullable<OCSession["outcome"]>;
+        error?: NonNullable<OCAssistantMessage["error"]>;
+    }>;
+    /** The last idle time, restored as time.idle so /view accepts a watermark seen before a restart. */
+    lastIdle?: number;
+    /** When each compaction was admitted, keyed by its admitted message ID. */
+    compactionAdmissions?: Record<string, number>;
 }
 export interface TreeEntry {
     type: string;

package/dist/session-tree.js

@@ -332,8 +332,8 @@ function entryForMessage(s, tree, messageID) {
 }
 /**
  * The last entry of an assistant reply: the reply, or the latest result of its own tool calls.
- * OpenChamber 2.x /btw names a final reply (no tool calls); 1.24's /btw can name any completed
- * step, whose tool results belong to the same OpenChamber message.
+ * A final reply has no tool calls. When an API caller selects a tool-bearing
+ * reply, its completed tool results belong to the same message.
  */
 function replyEnd(tree, reply, leafId) {
     const content = reply.message?.content;