@xandreed/plugin-session-sqlite 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xand Reed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @xandreed/plugin-session-sqlite
+
+Efferent composable agent framework, 0.3.0. Bun on Linux.
+
+Documentation: https://github.com/xandreeddev/efferent

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { Layer } from "effect";
+import { HarnessError, SessionStore } from "@xandreed/core";
+export declare const SessionStoreLive: (path: string) => Layer.Layer<SessionStore, HarnessError, never>;
+export declare const sessionSqlitePlugin: import("@xandreed/core").Plugin;
+export default sessionSqlitePlugin;
+export { SqliteConversationStoreLive } from "./store/sqliteStore.js";

package/dist/index.js

@@ -0,0 +1,60 @@
+import { Database } from "bun:sqlite";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { Effect, Layer, Schema } from "effect";
+import { ConversationId, definePlugin, HarnessError, SessionEvent, SessionRecord, SessionStore } from "@xandreed/core";
+const Config = Schema.Struct({ path: Schema.String }), decodeRecord = Schema.decodeUnknownSync(Schema.parseJson(SessionRecord)), decodeEvent = Schema.decodeUnknownSync(Schema.parseJson(SessionEvent));
+export const SessionStoreLive = (path) => Layer.scoped(SessionStore, Effect.gen(function* () {
+  yield* Effect.tryPromise({ try: () => mkdir(dirname(path), { recursive: !0 }), catch: (error) => new HarnessError({ code: "store.open", message: String(error) }) });
+  const db = yield* Effect.acquireRelease(Effect.try({ try: () => new Database(path, { create: !0, strict: !0 }), catch: (error) => new HarnessError({ code: "store.open", message: String(error) }) }), (database) => Effect.sync(() => database.close())), operation = (work) => Effect.try({ try: work, catch: (error) => new HarnessError({ code: "store.io", message: String(error) }) });
+  yield* operation(() => db.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA busy_timeout = 5000;
+    PRAGMA foreign_keys = ON;
+    CREATE TABLE IF NOT EXISTS harness_sessions (id TEXT PRIMARY KEY, workspace TEXT NOT NULL, body TEXT NOT NULL);
+    CREATE TABLE IF NOT EXISTS harness_events (session_id TEXT NOT NULL REFERENCES harness_sessions(id), seq INTEGER NOT NULL, body TEXT NOT NULL, PRIMARY KEY(session_id, seq));
+  `));
+  const insert = (record) => {
+    db.query("INSERT INTO harness_sessions VALUES (?, ?, ?)").run(record.id, record.workspace, JSON.stringify(record));
+    return record;
+  }, get = (id) => operation(() => db.query("SELECT body FROM harness_sessions WHERE id = ?").get(id)).pipe(Effect.flatMap((row) => row === null ? Effect.fail(new HarnessError({ code: "session.missing", message: `Session ${id} does not exist` })) : operation(() => decodeRecord(row.body)))), read = (id, after) => get(id).pipe(Effect.zipRight(operation(() => db.query("SELECT body FROM harness_events WHERE session_id = ? AND seq > ? ORDER BY seq").all(id, after).map((row) => decodeEvent(row.body)))));
+  return SessionStore.of({
+    create: (workspace, profile) => operation(() => insert({ id: ConversationId.make(crypto.randomUUID()), workspace, profile, createdAt: Date.now() })),
+    get,
+    list: (workspace) => operation(() => db.query("SELECT body FROM harness_sessions WHERE workspace = ? ORDER BY rowid DESC").all(workspace).map((row) => decodeRecord(row.body))),
+    read,
+    append: (id, body) => get(id).pipe(Effect.zipRight(operation(() => db.transaction(() => {
+      const row = db.query("SELECT COALESCE(MAX(seq), -1) + 1 AS seq FROM harness_events WHERE session_id = ?").get(id), event = { ...body, version: 1, id: crypto.randomUUID(), sessionId: id, seq: row?.seq ?? 0, at: Date.now() };
+      db.query("INSERT INTO harness_events VALUES (?, ?, ?)").run(id, event.seq, JSON.stringify(event));
+      return event;
+    })()))),
+    fork: (id, through) => Effect.gen(function* () {
+      const parent = yield* get(id), trail = (yield* read(id, -1)).filter((event) => event.seq <= through);
+      if (trail.reduce((runs, event) => {
+        if (event.runId === void 0)
+          return runs;
+        if (event.name === "run.started")
+          return [...runs, event.runId];
+        if (["run.completed", "run.failed", "run.cancelled"].includes(event.name))
+          return runs.filter((run) => run !== event.runId);
+        return runs;
+      }, []).length > 0)
+        return yield* Effect.fail(new HarnessError({ code: "session.fork-boundary", message: "Fork at a settled turn boundary" }));
+      return yield* operation(() => db.transaction(() => {
+        const record = insert({ ...parent, id: ConversationId.make(crypto.randomUUID()), parent: id, createdAt: Date.now() });
+        trail.forEach((event, seq) => db.query("INSERT INTO harness_events VALUES (?, ?, ?)").run(record.id, seq, JSON.stringify({ ...event, sessionId: record.id, id: crypto.randomUUID(), seq })));
+        return record;
+      })());
+    })
+  });
+})), sessionSqlitePlugin = definePlugin({
+  id: "@xandreed/plugin-session-sqlite",
+  version: "0.3.0",
+  scope: "runtime",
+  config: Config,
+  defaults: { path: ".efferent/runtime/sessions.db" },
+  provides: [SessionStore],
+  layer: ({ path }) => SessionStoreLive(path)
+});
+export default sessionSqlitePlugin;
+export { SqliteConversationStoreLive } from "./store/sqliteStore.js";

package/dist/store/sqliteStore.d.ts

@@ -0,0 +1,3 @@
+import { Layer } from "effect";
+import { ConversationStore, StoreError } from "@xandreed/core";
+export declare const SqliteConversationStoreLive: (dbPath: string) => Layer.Layer<ConversationStore, StoreError, never>;

package/dist/store/sqliteStore.js

@@ -0,0 +1,175 @@
+import { Database } from "bun:sqlite";
+import { chmodSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { Effect, Either, Layer, Option, Schema } from "effect";
+import { AgentMessage, Checkpoint, ConversationId, ConversationStore, ConversationSummary, RunOutcomeRecord, StoredMessage, StoreError } from "@xandreed/core";
+const MIGRATIONS = [
+  `
+  CREATE TABLE IF NOT EXISTS conversations (
+    id TEXT PRIMARY KEY,
+    workspace_dir TEXT,
+    title TEXT,
+    created_at INTEGER NOT NULL
+  );
+  CREATE TABLE IF NOT EXISTS messages (
+    conversation_id TEXT NOT NULL,
+    position INTEGER NOT NULL,
+    content TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    PRIMARY KEY (conversation_id, position)
+  );
+  CREATE TABLE IF NOT EXISTS checkpoints (
+    conversation_id TEXT NOT NULL,
+    message_position INTEGER NOT NULL,
+    summary TEXT NOT NULL,
+    created_at INTEGER NOT NULL
+  );
+  `,
+  `
+  CREATE INDEX IF NOT EXISTS checkpoints_by_conversation
+    ON checkpoints (conversation_id, message_position);
+  CREATE INDEX IF NOT EXISTS conversations_by_workspace
+    ON conversations (workspace_dir);
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS run_outcomes (
+    conversation_id TEXT NOT NULL,
+    at INTEGER NOT NULL,
+    outcome TEXT NOT NULL,
+    reason TEXT NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS run_outcomes_by_conversation
+    ON run_outcomes (conversation_id, at);
+  `
+], migrate = (db) => {
+  const version = db.query("PRAGMA user_version").get().user_version;
+  MIGRATIONS.slice(version).forEach((step) => db.transaction(() => db.exec(step))());
+  db.exec(`PRAGMA user_version = ${MIGRATIONS.length}`);
+}, decodeMessage = Schema.decodeUnknownEither(Schema.parseJson(AgentMessage)), tryDb = (run) => Effect.try({
+  try: run,
+  catch: (e) => new StoreError({ message: String(e) })
+}), salvageRows = (rows, where) => Effect.forEach(rows, (row) => Either.match(decodeMessage(row.content), {
+  onLeft: (issue) => Effect.logWarning(`${where}: skipping undecodable message row: ${String(issue)}`).pipe(Effect.as(Option.none())),
+  onRight: (message) => Effect.succeed(Option.some(message))
+})).pipe(Effect.map((decoded) => decoded.filter(Option.isSome).map((some) => some.value))), salvagePositioned = (rows, where) => Effect.forEach(rows, (row) => Either.match(decodeMessage(row.content), {
+  onLeft: (issue) => Effect.logWarning(`${where}: skipping undecodable message row at ${row.position}: ${String(issue)}`).pipe(Effect.as(Option.none())),
+  onRight: (message) => Effect.succeed(Option.some(new StoredMessage({ position: row.position, message })))
+})).pipe(Effect.map((decoded) => decoded.filter(Option.isSome).map((some) => some.value)));
+export const SqliteConversationStoreLive = (dbPath) => Layer.scoped(ConversationStore, Effect.gen(function* () {
+  const db = yield* tryDb(() => {
+    mkdirSync(dirname(dbPath), { recursive: !0 });
+    const database = new Database(dbPath, { create: !0 });
+    chmodSync(dbPath, 384);
+    database.exec("PRAGMA busy_timeout = 5000;");
+    database.exec("PRAGMA journal_mode = WAL;");
+    migrate(database);
+    return database;
+  });
+  yield* Effect.addFinalizer(() => tryDb(() => db.close()).pipe(Effect.catchAll((error) => Effect.logWarning(`conversation database cleanup failed: ${error.message}`))));
+  const latestCheckpointRow = (id) => Option.fromNullable(db.query(`SELECT message_position, summary, created_at FROM checkpoints
+               WHERE conversation_id = ? ORDER BY message_position DESC LIMIT 1`).get(id));
+  return {
+    create: (workspaceDir) => tryDb(() => {
+      const id = ConversationId.make(crypto.randomUUID());
+      db.query("INSERT INTO conversations (id, workspace_dir, title, created_at) VALUES (?, ?, NULL, ?)").run(id, workspaceDir ?? null, Date.now());
+      return id;
+    }),
+    append: (id, message) => tryDb(() => db.query(`INSERT INTO messages (conversation_id, position, content, created_at)
+                     SELECT ?1, COALESCE(MAX(position) + 1, 0), ?2, ?3
+                     FROM messages WHERE conversation_id = ?1
+                     RETURNING position`).get(id, JSON.stringify(message), Date.now()).position),
+    appendAll: (id, messages) => tryDb(() => db.transaction(() => messages.map((message) => db.query(`INSERT INTO messages (conversation_id, position, content, created_at)
+                         SELECT ?1, COALESCE(MAX(position) + 1, 0), ?2, ?3
+                         FROM messages WHERE conversation_id = ?1
+                         RETURNING position`).get(id, JSON.stringify(message), Date.now()).position))()),
+    list: (id) => tryDb(() => db.query("SELECT content FROM messages WHERE conversation_id = ? ORDER BY position ASC").all(id)).pipe(Effect.flatMap((rows) => salvageRows(rows, `list ${id}`))),
+    listActive: (id) => tryDb(() => {
+      const fold = latestCheckpointRow(id), after = Option.match(fold, {
+        onNone: () => -1,
+        onSome: (c) => c.message_position
+      });
+      return db.query(`SELECT position, content FROM messages
+                 WHERE conversation_id = ? AND position > ? ORDER BY position ASC`).all(id, after);
+    }).pipe(Effect.flatMap((rows) => salvagePositioned(rows, `listActive ${id}`))),
+    checkpoint: (id, summary) => tryDb(() => {
+      db.query(`INSERT INTO checkpoints (conversation_id, message_position, summary, created_at)
+               SELECT ?1, COALESCE(MAX(position), -1), ?2, ?3
+               FROM messages WHERE conversation_id = ?1`).run(id, summary, Date.now());
+    }),
+    checkpointAt: (id, summary, messagePosition) => tryDb(() => {
+      db.query(`INSERT INTO checkpoints (conversation_id, message_position, summary, created_at)
+               VALUES (?1, ?2, ?3, ?4)`).run(id, messagePosition, summary, Date.now());
+    }),
+    latestCheckpoint: (id) => tryDb(() => Option.map(latestCheckpointRow(id), (row) => new Checkpoint({
+      conversationId: id,
+      messagePosition: row.message_position,
+      summary: row.summary,
+      createdAt: row.created_at
+    }))),
+    setTitle: (id, title) => tryDb(() => {
+      db.query("UPDATE conversations SET title = ? WHERE id = ?").run(title, id);
+    }),
+    recordOutcome: (id, outcome, reason) => tryDb(() => {
+      db.query("INSERT INTO run_outcomes (conversation_id, at, outcome, reason) VALUES (?, ?, ?, ?)").run(id, Date.now(), outcome, reason);
+    }),
+    latestOutcome: (id) => tryDb(() => Option.fromNullable(db.query(`SELECT at, outcome, reason FROM run_outcomes
+                   WHERE conversation_id = ? ORDER BY at DESC, rowid DESC LIMIT 1`).get(id))).pipe(Effect.flatMap((row) => Option.match(row, {
+      onNone: () => Effect.succeed(Option.none()),
+      onSome: (r) => Schema.decodeUnknown(RunOutcomeRecord)({ conversationId: id, ...r }).pipe(Effect.map(Option.some), Effect.mapError((issue) => new StoreError({ message: String(issue) })))
+    }))),
+    prune: (beforeEpochMs) => tryDb(() => {
+      const removed = db.transaction(() => {
+        const ids = db.query("SELECT id FROM conversations WHERE created_at < ?").all(beforeEpochMs).map((row) => row.id);
+        ids.forEach((id) => {
+          db.query("DELETE FROM messages WHERE conversation_id = ?").run(id);
+          db.query("DELETE FROM checkpoints WHERE conversation_id = ?").run(id);
+          db.query("DELETE FROM conversations WHERE id = ?").run(id);
+        });
+        return ids.length;
+      })();
+      db.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+      return removed;
+    }),
+    fork: (id, upToPosition) => tryDb(() => Option.fromNullable(db.query("SELECT workspace_dir, title FROM conversations WHERE id = ?").get(id))).pipe(Effect.flatMap(Option.match({
+      onNone: () => Effect.fail(new StoreError({ message: `conversation ${id} not found` })),
+      onSome: (source) => tryDb(() => {
+        const forkId = ConversationId.make(crypto.randomUUID()), cap = upToPosition ?? Number.MAX_SAFE_INTEGER;
+        db.transaction(() => {
+          db.query("INSERT INTO conversations (id, workspace_dir, title, created_at) VALUES (?, ?, ?, ?)").run(forkId, source.workspace_dir, source.title === null ? null : `fork: ${source.title}`, Date.now());
+          db.query(`INSERT INTO messages (conversation_id, position, content, created_at)
+                         SELECT ?2, position, content, created_at FROM messages
+                         WHERE conversation_id = ?1 AND position <= ?3`).run(id, forkId, cap);
+          db.query(`INSERT INTO checkpoints (conversation_id, message_position, summary, created_at)
+                         SELECT ?2, message_position, summary, created_at FROM checkpoints
+                         WHERE conversation_id = ?1 AND message_position <= ?3
+                         ORDER BY message_position DESC LIMIT 1`).run(id, forkId, cap);
+        })();
+        return forkId;
+      })
+    }))),
+    listByWorkspace: (workspaceDir) => tryDb(() => db.query(`SELECT c.id, c.created_at, c.title,
+                          (SELECT m.content FROM messages m
+                           WHERE m.conversation_id = c.id ORDER BY m.position ASC LIMIT 1)
+                            AS first_content,
+                          (SELECT o.outcome FROM run_outcomes o
+                           WHERE o.conversation_id = c.id ORDER BY o.at DESC, o.rowid DESC LIMIT 1)
+                            AS last_outcome,
+                          (SELECT o.reason FROM run_outcomes o
+                           WHERE o.conversation_id = c.id ORDER BY o.at DESC, o.rowid DESC LIMIT 1)
+                            AS last_reason
+                   FROM conversations c WHERE c.workspace_dir = ?
+                   ORDER BY c.created_at DESC`).all(workspaceDir).map((row) => {
+      const first = Option.fromNullable(row.first_content).pipe(Option.flatMap((content) => Either.getRight(decodeMessage(content))), Option.flatMap((parsed) => parsed.role === "user" ? Option.some(parsed.content.slice(0, 120)) : Option.none())), lastOutcome = Option.flatMap(Option.all([Option.fromNullable(row.last_outcome), Option.fromNullable(row.last_reason)]), ([outcome, reason]) => Either.getRight(Schema.decodeUnknownEither(Schema.Struct({
+        outcome: Schema.Literal("ok", "partial"),
+        reason: Schema.Literal("completed", "step-cap", "degenerate-loop")
+      }))({ outcome, reason })));
+      return new ConversationSummary({
+        id: ConversationId.make(row.id),
+        createdAt: row.created_at,
+        firstPrompt: first,
+        title: Option.fromNullable(row.title),
+        lastOutcome
+      });
+    }))
+  };
+}));

package/dist/store/sqliteStore.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@xandreed/plugin-session-sqlite",
+  "version": "0.3.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@xandreed/core": "0.3.0",
+    "effect": "3.21.4",
+    "ws": "^8.21.0"
+  },
+  "private": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills",
+    "profiles",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "license": "MIT"
+}