@alisio/core 0.1.0-alpha.17 → 0.1.0-alpha.19

package/dist/runtime/diff.js

@@ -0,0 +1,154 @@
+/**
+ * Unified line diffs for the `diff` UiBlock that `write_file`/`edit_file` attach for rich
+ * clients (spec §8.6, RF-13). Myers O((N+M)·D) on lines after trimming the common prefix and
+ * suffix; when the edit distance exceeds `maxD` the middle becomes a full replacement. Pure and
+ * portable (no dependency). The web UI ships its own copy of the algorithm for third-party blocks
+ * that only carry `before`/`after` (packages cannot share code with the browser bundle).
+ */
+function myers(a, b, maxD) {
+    const n = a.length;
+    const m = b.length;
+    if (!n)
+        return b.map(() => 2);
+    if (!m)
+        return a.map(() => 1);
+    const max = n + m;
+    const offset = max + 1;
+    const v = new Int32Array(2 * max + 3);
+    const trace = [];
+    for (let d = 0; d <= Math.min(max, maxD); d++) {
+        trace.push(v.slice(offset - d - 1, offset + d + 2));
+        for (let k = -d; k <= d; k += 2) {
+            let x = k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1])
+                ? v[offset + k + 1]
+                : v[offset + k - 1] + 1;
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            v[offset + k] = x;
+            if (x >= n && y >= m)
+                return backtrack(trace, n, m);
+        }
+    }
+    return undefined;
+}
+function backtrack(trace, n, m) {
+    const ops = [];
+    let x = n;
+    let y = m;
+    for (let d = trace.length - 1; d > 0; d--) {
+        const snap = trace[d];
+        const at = (k) => snap[k + d + 1];
+        const k = x - y;
+        const prevK = k === -d || (k !== d && at(k - 1) < at(k + 1)) ? k + 1 : k - 1;
+        const prevX = at(prevK);
+        const prevY = prevX - prevK;
+        while (x > prevX && y > prevY) {
+            ops.push(0);
+            x--;
+            y--;
+        }
+        ops.push(x === prevX ? 2 : 1);
+        x = prevX;
+        y = prevY;
+    }
+    while (x > 0 && y > 0) {
+        ops.push(0);
+        x--;
+        y--;
+    }
+    return ops.reverse();
+}
+/** Line edit script (0 equal, 1 delete, 2 insert). */
+export function lineEdits(a, b, maxD = 2000) {
+    let start = 0;
+    while (start < a.length && start < b.length && a[start] === b[start])
+        start++;
+    let endA = a.length;
+    let endB = b.length;
+    while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+        endA--;
+        endB--;
+    }
+    const midA = a.slice(start, endA);
+    const midB = b.slice(start, endB);
+    const middle = myers(midA, midB, maxD) ?? [...midA.map(() => 1), ...midB.map(() => 2)];
+    return [...new Array(start).fill(0), ...middle, ...new Array(a.length - endA).fill(0)];
+}
+const NO_EOL = "\u0000no-eol";
+/** Lines of a text; a last line without `\n` carries a marker so a newline change is a change. */
+function linesOf(text) {
+    if (!text)
+        return [];
+    const lines = text.split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    else
+        lines[lines.length - 1] = `${lines.at(-1)}${NO_EOL}`;
+    return lines;
+}
+/**
+ * A unified patch (`--- a/path`, `+++ b/path`, hunks with `context` lines) from `before` to
+ * `after`; `undefined` means the file did not exist. Identical texts give `""`.
+ */
+export function unifiedPatch(path, before, after, options = {}) {
+    const context = options.context ?? 3;
+    const a = linesOf(before);
+    const b = linesOf(after);
+    const rows = [];
+    let i = 0;
+    let j = 0;
+    for (const op of lineEdits(a, b)) {
+        if (op === 0)
+            rows.push({ op, text: a[i], old: i++, new: j++ });
+        else if (op === 1)
+            rows.push({ op, text: a[i], old: i++, new: j });
+        else
+            rows.push({ op, text: b[j], old: i, new: j++ });
+    }
+    const hunks = [];
+    for (let k = 0; k < rows.length; k++) {
+        if (rows[k].op === 0)
+            continue;
+        const from = Math.max(0, k - context);
+        const last = hunks.at(-1);
+        if (last && from <= last[1] + 1)
+            last[1] = Math.min(rows.length - 1, k + context);
+        else
+            hunks.push([from, Math.min(rows.length - 1, k + context)]);
+    }
+    if (!hunks.length)
+        return "";
+    const out = [
+        `--- ${before === undefined ? "/dev/null" : `a/${path}`}`,
+        `+++ ${after === undefined ? "/dev/null" : `b/${path}`}`,
+    ];
+    const range = (start, count) => count === 1 ? `${start + 1}` : `${count === 0 ? start : start + 1},${count}`;
+    for (const [from, to] of hunks) {
+        const slice = rows.slice(from, to + 1);
+        const first = slice[0];
+        const oldCount = slice.filter((r) => r.op !== 2).length;
+        const newCount = slice.filter((r) => r.op !== 1).length;
+        out.push(`@@ -${range(first.old, oldCount)} +${range(first.new, newCount)} @@`);
+        for (const row of slice) {
+            const noEol = row.text.endsWith(NO_EOL);
+            const text = noEol ? row.text.slice(0, -NO_EOL.length) : row.text;
+            out.push(`${row.op === 0 ? " " : row.op === 1 ? "-" : "+"}${text}`);
+            if (noEol)
+                out.push("\");
+        }
+    }
+    return out.join("\n");
+}
+/** Cuts `text` at a line boundary so it fits in `maxBytes` (UTF-8). */
+export function clipLines(text, maxBytes) {
+    if (Buffer.byteLength(text) <= maxBytes)
+        return { text, clipped: false };
+    let cut = Buffer.from(text).subarray(0, maxBytes).toString("utf8");
+    // A split multi-byte character decodes to U+FFFD; drop the partial last line either way.
+    const newline = cut.lastIndexOf("\n");
+    cut = newline > 0 ? cut.slice(0, newline) : cut.replace(/�$/, "");
+    return { text: cut, clipped: true };
+}

package/dist/runtime/store.d.ts

@@ -1,5 +1,5 @@
 import { type Message, type SqlDatabase, type ToolCall, type ToolResult } from "@alisio/sdk";
-import type { Session, SessionStore } from "../core/contracts.ts";
+import type { BeginRunInput, EndRunInput, EventPage, MessagePage, PageOptions, RunRecord, Session, SessionStore, ToolCallMeta } from "../core/contracts.ts";
 export declare class SQLiteStore implements SessionStore {
     readonly db: SqlDatabase;
     constructor(path: string);
@@ -23,17 +23,89 @@ export declare class SQLiteStore implements SessionStore {
     interruptStale(): number;
     messages(id: string): Message[];
     append(id: string, message: Message): void;
+    private touch;
     setModel(id: string, model: string): void;
     compact(id: string, replaced: number, summary: Message): void;
     overwrite(id: string, messages: Message[]): void;
     acquire(id: string): void;
     release(id: string): void;
-    beginCall(id: string, call: ToolCall): void;
+    beginCall(id: string, call: ToolCall, meta?: ToolCallMeta): void;
     endCall(id: string, call: ToolCall, result: ToolResult): void;
+    /**
+     * Calls of a session with one effect (for example `write`), oldest first. Needs the v4
+     * `effect`/`run_id`/`started_at` columns; rows written by older versions have no effect.
+     */
+    effectCalls(session: string, effect: string): Array<{
+        callId: string;
+        name: string;
+        runId?: string;
+        startedAt?: number;
+    }>;
     /** Rich (ui/image) parts persist as part of the serialized result and replay verbatim. */
     callResult(id: string, callId: string): ToolResult | undefined;
     reconcile(id: string, acknowledge?: boolean): void;
-    event(id: string, runId: string, type: string, data: unknown): void;
+    /** Persists a durable event and returns its global `events.seq`. */
+    event(id: string, runId: string, type: string, data: unknown, meta?: {
+        correlationId?: string;
+    }): number;
+    private runRow;
+    private runById;
+    beginRun(input: BeginRunInput): {
+        run: RunRecord;
+        created: boolean;
+    };
+    endRun(id: string, input: EndRunInput): void;
+    runByRequest(session: string, requestId: string): RunRecord | undefined;
+    runs(session: string, options?: {
+        limit?: number;
+    }): RunRecord[];
+    interruptRuns(): number;
+    /**
+     * A page of messages by `seq`. With `after`, the first `limit` rows after it; otherwise the
+     * newest `limit` rows (before `before` when given). Items are always in ascending order.
+     */
+    messagesPage(session: string, options?: PageOptions & {
+        compacted?: boolean;
+    }): MessagePage;
+    /** Durable events of a session after `after` (a previous `eventId`), ascending. */
+    eventsPage(session: string, options?: PageOptions): EventPage;
+    /**
+     * Known workspaces for web clients: the workspaces of root sessions plus the ones recorded with
+     * `recordWorkspace` (v4 `workspaces` table), with their UI metadata (v5: `archivedAt`) and
+     * root-session count.
+     */
+    workspaces(): Array<{
+        path: string;
+        label?: string;
+        pinned: boolean;
+        lastOpenedAt?: number;
+        archivedAt?: number;
+        sessions: number;
+    }>;
+    /**
+     * Records (upserts) a workspace and patches its UI metadata (`label: null` clears the label;
+     * `archived` stamps or clears `archived_at` and never touches its sessions).
+     */
+    recordWorkspace(path: string, patch?: {
+        label?: string | null;
+        pinned?: boolean;
+        lastOpenedAt?: number;
+        archived?: boolean;
+    }): void;
+    /**
+     * Patches web-facing session metadata: title, pin, archive flag and `options` (shallow-merged
+     * into the stored options object). Does not touch the run-relevant columns.
+     */
+    updateSessionMeta(id: string, patch: {
+        title?: string | null;
+        pinned?: boolean;
+        archived?: boolean;
+        options?: Record<string, unknown>;
+    }): void;
+    /** `MAX(events.seq)` of a session (0 without events): the web snapshot cursor. */
+    lastEventId(session: string): number;
+    /** The pid of another live process holding the session lock, if any. */
+    lockedBy(id: string): number | undefined;
     getState(plugin: string, key: string): unknown;
     setState(plugin: string, key: string, value: unknown): void;
     close(): void;

package/dist/runtime/store.js

@@ -1,5 +1,16 @@
 import { textResult, } from "@alisio/sdk";
 import { openDatabase } from "./sqlite.js";
+/** Whether a process id belongs to a live process (EPERM still means alive). */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code !== "ESRCH";
+    }
+}
+const TERMINAL_RUN = "('completed','turns_exceeded','failed','cancelled','interrupted')";
 export class SQLiteStore {
     db;
     constructor(path) {
@@ -45,12 +56,69 @@ export class SQLiteStore {
                 this.db.exec("CREATE INDEX IF NOT EXISTS sessions_parent ON sessions(parent_id)");
                 this.db.exec("INSERT OR IGNORE INTO schema_migrations VALUES(3)");
             });
+        if (!has(4))
+            this.db.transaction(() => {
+                // v4 (additive): run journal, workspace UI metadata, blob index and nullable columns.
+                this.db.exec(`CREATE TABLE IF NOT EXISTS runs(
+            id TEXT PRIMARY KEY,
+            session TEXT NOT NULL REFERENCES sessions(id),
+            status TEXT NOT NULL,
+            request_id TEXT,
+            correlation_id TEXT,
+            owner_pid INTEGER,
+            model TEXT,
+            created_at INTEGER NOT NULL,
+            started_at INTEGER,
+            ended_at INTEGER,
+            error TEXT,
+            usage TEXT);
+          CREATE UNIQUE INDEX IF NOT EXISTS runs_request ON runs(session, request_id) WHERE request_id IS NOT NULL;
+          CREATE INDEX IF NOT EXISTS runs_session ON runs(session, created_at);
+          CREATE TABLE IF NOT EXISTS workspaces(
+            path TEXT PRIMARY KEY,
+            label TEXT,
+            pinned INTEGER NOT NULL DEFAULT 0,
+            last_opened_at INTEGER);
+          CREATE TABLE IF NOT EXISTS blobs(
+            hash TEXT PRIMARY KEY,
+            mime TEXT NOT NULL,
+            size INTEGER NOT NULL,
+            width INTEGER,
+            height INTEGER,
+            created_at INTEGER NOT NULL);`);
+                const add = (table, name, type) => {
+                    const columns = this.db.prepare(`PRAGMA table_info(${table})`).all();
+                    if (!columns.some((c) => c.name === name))
+                        this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${type}`);
+                };
+                add("sessions", "pinned", "INTEGER NOT NULL DEFAULT 0");
+                add("sessions", "archived_at", "INTEGER");
+                add("events", "created_at", "INTEGER");
+                add("events", "correlation_id", "TEXT");
+                add("tool_calls", "run_id", "TEXT");
+                add("tool_calls", "name", "TEXT");
+                add("tool_calls", "effect", "TEXT");
+                add("tool_calls", "started_at", "INTEGER");
+                add("tool_calls", "ended_at", "INTEGER");
+                this.db.exec(`CREATE INDEX IF NOT EXISTS events_session ON events(session, seq);
+          CREATE INDEX IF NOT EXISTS messages_session ON messages(session, seq);
+          INSERT OR IGNORE INTO schema_migrations VALUES(4);`);
+            });
+        if (!has(5))
+            this.db.transaction(() => {
+                // v5 (additive): archived workspaces (hidden from the default web list).
+                const columns = this.db.prepare("PRAGMA table_info(workspaces)").all();
+                if (!columns.some((c) => c.name === "archived_at"))
+                    this.db.exec("ALTER TABLE workspaces ADD COLUMN archived_at INTEGER");
+                this.db.exec("INSERT OR IGNORE INTO schema_migrations VALUES(5)");
+            });
     }
     create(workspace, provider, model) {
         const id = crypto.randomUUID();
+        const now = Date.now();
         this.db
-            .prepare("INSERT INTO sessions(id,workspace,provider,model) VALUES(?,?,?,?)")
-            .run(id, workspace, provider, model);
+            .prepare("INSERT INTO sessions(id,workspace,provider,model,created_at,updated_at) VALUES(?,?,?,?,?,?)")
+            .run(id, workspace, provider, model, now, now);
         return { id, workspace, provider, model };
     }
     row(r) {
@@ -68,6 +136,8 @@ export class SQLiteStore {
             ...(r.options ? { options: JSON.parse(String(r.options)) } : {}),
             ...(r.created_at ? { createdAt: Number(r.created_at) } : {}),
             ...(r.updated_at ? { updatedAt: Number(r.updated_at) } : {}),
+            ...(r.pinned ? { pinned: true } : {}),
+            ...(r.archived_at ? { archivedAt: Number(r.archived_at) } : {}),
         };
     }
     get(id) {
@@ -147,6 +217,10 @@ export class SQLiteStore {
         this.db
             .prepare("INSERT INTO messages(session,body) VALUES(?,?)")
             .run(id, JSON.stringify(message));
+        this.touch(id);
+    }
+    touch(id) {
+        this.db.prepare("UPDATE sessions SET updated_at=? WHERE id=?").run(Date.now(), id);
     }
     setModel(id, model) {
         if (!model.trim())
@@ -201,15 +275,30 @@ export class SQLiteStore {
             .prepare("UPDATE sessions SET locked_pid=NULL WHERE id=? AND locked_pid=?")
             .run(id, process.pid);
     }
-    beginCall(id, call) {
+    beginCall(id, call, meta = {}) {
         this.db
-            .prepare("INSERT INTO tool_calls(session,call_id,status) VALUES(?,?,'pending')")
-            .run(id, call.id);
+            .prepare("INSERT INTO tool_calls(session,call_id,status,run_id,name,effect,started_at) VALUES(?,?,'pending',?,?,?,?)")
+            .run(id, call.id, meta.runId ?? null, call.name, meta.effect ?? null, Date.now());
     }
     endCall(id, call, result) {
         this.db
-            .prepare("INSERT INTO tool_calls(session,call_id,status,result) VALUES(?,?,'completed',?) ON CONFLICT(session,call_id) DO UPDATE SET status='completed',result=excluded.result")
-            .run(id, call.id, JSON.stringify(result));
+            .prepare("INSERT INTO tool_calls(session,call_id,status,result,name,ended_at) VALUES(?,?,'completed',?,?,?) ON CONFLICT(session,call_id) DO UPDATE SET status='completed',result=excluded.result,ended_at=excluded.ended_at,name=COALESCE(tool_calls.name,excluded.name)")
+            .run(id, call.id, JSON.stringify(result), call.name, Date.now());
+    }
+    /**
+     * Calls of a session with one effect (for example `write`), oldest first. Needs the v4
+     * `effect`/`run_id`/`started_at` columns; rows written by older versions have no effect.
+     */
+    effectCalls(session, effect) {
+        const rows = this.db
+            .prepare("SELECT call_id,name,run_id,started_at FROM tool_calls WHERE session=? AND effect=? ORDER BY started_at, rowid")
+            .all(session, effect);
+        return rows.map((row) => ({
+            callId: row.call_id,
+            name: row.name ?? "",
+            ...(row.run_id ? { runId: row.run_id } : {}),
+            ...(row.started_at != null ? { startedAt: Number(row.started_at) } : {}),
+        }));
     }
     /** Rich (ui/image) parts persist as part of the serialized result and replay verbatim. */
     callResult(id, callId) {
@@ -244,10 +333,219 @@ export class SQLiteStore {
             }
         });
     }
-    event(id, runId, type, data) {
-        this.db
-            .prepare("INSERT INTO events(session,run_id,type,body) VALUES(?,?,?,?)")
-            .run(id, runId, type, JSON.stringify(data));
+    /** Persists a durable event and returns its global `events.seq`. */
+    event(id, runId, type, data, meta = {}) {
+        const { lastInsertRowid } = this.db
+            .prepare("INSERT INTO events(session,run_id,type,body,created_at,correlation_id) VALUES(?,?,?,?,?,?)")
+            .run(id, runId, type, JSON.stringify(data), Date.now(), meta.correlationId ?? null);
+        return Number(lastInsertRowid);
+    }
+    runRow(r) {
+        return {
+            id: String(r.id),
+            session: String(r.session),
+            status: r.status,
+            ...(r.request_id != null ? { requestId: String(r.request_id) } : {}),
+            ...(r.correlation_id != null ? { correlationId: String(r.correlation_id) } : {}),
+            ...(r.owner_pid != null ? { ownerPid: Number(r.owner_pid) } : {}),
+            ...(r.model != null ? { model: String(r.model) } : {}),
+            createdAt: Number(r.created_at),
+            ...(r.started_at != null ? { startedAt: Number(r.started_at) } : {}),
+            ...(r.ended_at != null ? { endedAt: Number(r.ended_at) } : {}),
+            ...(r.error != null ? { error: String(r.error) } : {}),
+            ...(r.usage != null ? { usage: JSON.parse(String(r.usage)) } : {}),
+        };
+    }
+    runById(id) {
+        const row = this.db.prepare("SELECT * FROM runs WHERE id=?").get(id);
+        return row ? this.runRow(row) : undefined;
+    }
+    beginRun(input) {
+        return this.db.transaction(() => {
+            const status = input.status ?? "running";
+            const now = Date.now();
+            const existing = this.runById(input.id);
+            if (existing) {
+                if (existing.status === "queued" && status === "running")
+                    this.db
+                        .prepare("UPDATE runs SET status='running', started_at=?, owner_pid=?, model=COALESCE(?,model) WHERE id=?")
+                        .run(now, process.pid, input.model ?? null, input.id);
+                return { run: this.runById(input.id), created: false };
+            }
+            if (input.requestId !== undefined) {
+                const retried = this.runByRequest(input.session, input.requestId);
+                if (retried)
+                    return { run: retried, created: false };
+            }
+            this.db
+                .prepare(`INSERT INTO runs(id,session,status,request_id,correlation_id,owner_pid,model,created_at,started_at)
+           VALUES(?,?,?,?,?,?,?,?,?)`)
+                .run(input.id, input.session, status, input.requestId ?? null, input.correlationId ?? null, process.pid, input.model ?? null, now, status === "running" ? now : null);
+            return { run: this.runById(input.id), created: true };
+        });
+    }
+    endRun(id, input) {
+        const now = Date.now();
+        this.db.transaction(() => {
+            this.db
+                .prepare(`UPDATE runs SET status=?, ended_at=?, error=?, usage=COALESCE(?,usage)
+           WHERE id=? AND status NOT IN ${TERMINAL_RUN}`)
+                .run(input.status, now, input.error ?? null, input.usage ? JSON.stringify(input.usage) : null, id);
+            const run = this.runById(id);
+            if (run)
+                this.touch(run.session);
+        });
+    }
+    runByRequest(session, requestId) {
+        const row = this.db
+            .prepare("SELECT * FROM runs WHERE session=? AND request_id=?")
+            .get(session, requestId);
+        return row ? this.runRow(row) : undefined;
+    }
+    runs(session, options = {}) {
+        return this.db
+            .prepare("SELECT * FROM runs WHERE session=? ORDER BY created_at DESC, rowid DESC LIMIT ?")
+            .all(session, options.limit ?? 100)
+            .map((r) => this.runRow(r));
+    }
+    interruptRuns() {
+        const rows = this.db
+            .prepare("SELECT id, owner_pid FROM runs WHERE status IN ('queued','running')")
+            .all();
+        let count = 0;
+        for (const row of rows) {
+            // Runs of this process (another Application in it) or of another live process stay.
+            if (row.owner_pid && (row.owner_pid === process.pid || alive(row.owner_pid)))
+                continue;
+            this.endRun(row.id, { status: "interrupted" });
+            count++;
+        }
+        return count;
+    }
+    /**
+     * A page of messages by `seq`. With `after`, the first `limit` rows after it; otherwise the
+     * newest `limit` rows (before `before` when given). Items are always in ascending order.
+     */
+    messagesPage(session, options = {}) {
+        const limit = Math.max(1, Math.min(options.limit ?? 100, 1000));
+        const active = options.compacted ? "" : " AND compacted=0";
+        const rows = (options.after !== undefined
+            ? this.db
+                .prepare(`SELECT seq,body,compacted FROM messages WHERE session=? AND seq>?${active} ORDER BY seq LIMIT ?`)
+                .all(session, options.after, limit + 1)
+            : this.db
+                .prepare(`SELECT seq,body,compacted FROM messages WHERE session=? AND seq<?${active} ORDER BY seq DESC LIMIT ?`)
+                .all(session, options.before ?? Number.MAX_SAFE_INTEGER, limit + 1));
+        const hasMore = rows.length > limit;
+        const page = rows.slice(0, limit);
+        if (options.after === undefined)
+            page.reverse();
+        return {
+            items: page.map((r) => ({
+                seq: Number(r.seq),
+                message: JSON.parse(r.body),
+                compacted: !!r.compacted,
+            })),
+            hasMore,
+        };
+    }
+    /** Durable events of a session after `after` (a previous `eventId`), ascending. */
+    eventsPage(session, options = {}) {
+        const limit = Math.max(1, Math.min(options.limit ?? 500, 5000));
+        const rows = this.db
+            .prepare("SELECT seq,run_id,type,body,created_at,correlation_id FROM events WHERE session=? AND seq>? AND seq<? ORDER BY seq LIMIT ?")
+            .all(session, options.after ?? 0, options.before ?? Number.MAX_SAFE_INTEGER, limit + 1);
+        return {
+            items: rows.slice(0, limit).map((r) => ({
+                eventId: String(r.seq),
+                runId: String(r.run_id),
+                type: String(r.type),
+                data: r.body == null ? undefined : JSON.parse(String(r.body)),
+                ...(r.created_at != null ? { createdAt: Number(r.created_at) } : {}),
+                ...(r.correlation_id != null ? { correlationId: String(r.correlation_id) } : {}),
+            })),
+            hasMore: rows.length > limit,
+        };
+    }
+    /**
+     * Known workspaces for web clients: the workspaces of root sessions plus the ones recorded with
+     * `recordWorkspace` (v4 `workspaces` table), with their UI metadata (v5: `archivedAt`) and
+     * root-session count.
+     */
+    workspaces() {
+        const rows = this.db
+            .prepare(`SELECT p.path, w.label, COALESCE(w.pinned, 0) AS pinned, w.last_opened_at, w.archived_at,
+           (SELECT count(*) FROM sessions s WHERE s.workspace=p.path AND s.parent_id IS NULL) AS sessions
+         FROM (SELECT workspace AS path FROM sessions WHERE parent_id IS NULL AND workspace IS NOT NULL
+               UNION SELECT path FROM workspaces) p
+         LEFT JOIN workspaces w ON w.path=p.path
+         ORDER BY p.path`)
+            .all();
+        return rows.map((r) => ({
+            path: String(r.path),
+            ...(r.label != null ? { label: String(r.label) } : {}),
+            pinned: !!r.pinned,
+            ...(r.last_opened_at != null ? { lastOpenedAt: Number(r.last_opened_at) } : {}),
+            ...(r.archived_at != null ? { archivedAt: Number(r.archived_at) } : {}),
+            sessions: Number(r.sessions ?? 0),
+        }));
+    }
+    /**
+     * Records (upserts) a workspace and patches its UI metadata (`label: null` clears the label;
+     * `archived` stamps or clears `archived_at` and never touches its sessions).
+     */
+    recordWorkspace(path, patch = {}) {
+        this.db.transaction(() => {
+            this.db.prepare("INSERT OR IGNORE INTO workspaces(path) VALUES(?)").run(path);
+            if (patch.label !== undefined)
+                this.db.prepare("UPDATE workspaces SET label=? WHERE path=?").run(patch.label, path);
+            if (patch.pinned !== undefined)
+                this.db
+                    .prepare("UPDATE workspaces SET pinned=? WHERE path=?")
+                    .run(patch.pinned ? 1 : 0, path);
+            if (patch.lastOpenedAt !== undefined)
+                this.db
+                    .prepare("UPDATE workspaces SET last_opened_at=? WHERE path=?")
+                    .run(patch.lastOpenedAt, path);
+            if (patch.archived !== undefined)
+                this.db
+                    .prepare("UPDATE workspaces SET archived_at=? WHERE path=?")
+                    .run(patch.archived ? Date.now() : null, path);
+        });
+    }
+    /**
+     * Patches web-facing session metadata: title, pin, archive flag and `options` (shallow-merged
+     * into the stored options object). Does not touch the run-relevant columns.
+     */
+    updateSessionMeta(id, patch) {
+        this.db.transaction(() => {
+            const current = this.get(id);
+            if (patch.title !== undefined)
+                this.db.prepare("UPDATE sessions SET title=? WHERE id=?").run(patch.title, id);
+            if (patch.pinned !== undefined)
+                this.db.prepare("UPDATE sessions SET pinned=? WHERE id=?").run(patch.pinned ? 1 : 0, id);
+            if (patch.archived !== undefined)
+                this.db
+                    .prepare("UPDATE sessions SET archived_at=? WHERE id=?")
+                    .run(patch.archived ? Date.now() : null, id);
+            if (patch.options)
+                this.db
+                    .prepare("UPDATE sessions SET options=? WHERE id=?")
+                    .run(JSON.stringify({ ...(current.options ?? {}), ...patch.options }), id);
+        });
+    }
+    /** `MAX(events.seq)` of a session (0 without events): the web snapshot cursor. */
+    lastEventId(session) {
+        const row = this.db
+            .prepare("SELECT MAX(seq) AS seq FROM events WHERE session=?")
+            .get(session);
+        return Number(row?.seq ?? 0);
+    }
+    /** The pid of another live process holding the session lock, if any. */
+    lockedBy(id) {
+        const row = this.db.prepare("SELECT locked_pid FROM sessions WHERE id=?").get(id);
+        const pid = row?.locked_pid;
+        return pid && pid !== process.pid && alive(pid) ? pid : undefined;
     }
     getState(plugin, key) {
         const row = this.db

package/dist/sessions/side-questions.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `/btw` side questions: a question about a session answered by one separate, tool-less model
+ * call that sees the session's active history, without becoming part of the conversation.
+ *
+ * Guarantees: nothing is written to `messages`, `tool_calls`, `runs`, the durable `events` or the
+ * session usage, and the session lock is never claimed, so a side question may run while a run
+ * is active (it has its own abort signal). The only thing persisted is this service's own
+ * history, in `plugin_state` under the reserved namespace `core:btw` (plugin ids cannot contain
+ * `:`, so no plugin can read or overwrite it), keyed by session id and capped to the newest
+ * `SIDE_QUESTION_HISTORY_LIMIT` entries.
+ */
+import type { Message, SideQuestionEntry } from "@alisio/sdk";
+import type { AgentRunner } from "../core/runner.ts";
+export type { SideQuestionEntry };
+/** `plugin_state.plugin` value of the side-question history (never a valid plugin id). */
+export declare const SIDE_QUESTIONS_NAMESPACE = "core:btw";
+export declare const SIDE_QUESTION_HISTORY_LIMIT = 20;
+export declare const SIDE_QUESTION_MAX_CHARS = 4000;
+/** The line every surface prints for `/btw` without a question and without any history. */
+export declare const SIDE_QUESTION_USAGE = "Usage: /btw <question>";
+export declare const SIDE_QUESTION_DESCRIPTION = "Ask a side question about the current session without adding to the conversation.";
+export declare const SIDE_QUESTION_INSTRUCTIONS: string;
+interface StateStore {
+    getState(plugin: string, key: string): unknown;
+    setState(plugin: string, key: string, value: unknown): void;
+}
+export interface SideQuestionsOptions {
+    runner: Pick<AgentRunner, "sideContext">;
+    /** Where the history lives (the SQLite store's `plugin_state`). */
+    state: StateStore;
+    now?: () => number;
+    id?: () => string;
+}
+/**
+ * The transcript lines for the side call, newest kept first: when the whole history does not fit
+ * `budget` characters, the oldest messages are dropped (and counted in a leading marker). The
+ * newest message alone is clipped from its start if it is still too large.
+ */
+export declare function sideTranscript(messages: Message[], budget: number): string;
+export declare class SideQuestions {
+    private readonly options;
+    private readonly now;
+    private readonly newId;
+    constructor(options: SideQuestionsOptions);
+    /** The session's side questions, oldest first (newest last). */
+    history(sessionId: string): SideQuestionEntry[];
+    /**
+     * Answers `question` about the session with one tool-less call of the session's model and
+     * records it in the history. Throws on an empty or oversized question, on cancellation (the
+     * signal's reason) and on provider failures (nothing is recorded then).
+     */
+    ask(sessionId: string, question: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<SideQuestionEntry>;
+}
+/** Plain Markdown for one entry (`position` is 1-based): readline, API callers and `/btw`. */
+export declare function formatSideQuestion(entry: SideQuestionEntry, position: number, total: number): string;