@botbotgo/agent-harness 0.0.284 → 0.0.285

package/README.md

@@ -859,8 +859,8 @@ spec:
     path: store.sqlite
   - kind: Checkpointer
     name: default
-    checkpointerKind: FileCheckpointer
-    path: checkpoints.json
+    checkpointerKind: SqliteSaver
+    path: runtime/checkpoints.sqlite
 ```
 
 ### `config/runtime/runtime-memory.yaml`

package/README.zh.md

@@ -818,8 +818,8 @@ spec:
     path: store.sqlite
   - kind: Checkpointer
     name: default
-    checkpointerKind: FileCheckpointer
-    path: checkpoints.json
+    checkpointerKind: SqliteSaver
+    path: runtime/checkpoints.sqlite
 ```
 
 ### `config/runtime/runtime-memory.yaml`

package/dist/config/agents/direct.yaml

@@ -33,8 +33,8 @@ spec:
   mcpServers: []
   # Runtime execution feature: checkpointer config passed into the selected backend adapter.
   # Even the lightweight direct path can benefit from resumable state during interactive use.
-  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`.
-  # The repository default uses the file-backed preset so durable checkpoint state does not require native sqlite bindings.
+  # Available `kind` options in this harness: `SqliteSaver`, `FileCheckpointer`, `MemorySaver`.
+  # The repository default uses the sqlite-backed preset so durable checkpoint state stays inside `runtime/checkpoints.sqlite`.
   checkpointer: default
   # Upstream execution feature: LangGraph store available to middleware and runtime context hooks.
   # The default direct host keeps this enabled so middleware can use the same durable store surface as other hosts.

package/dist/config/agents/orchestra.yaml

@@ -40,8 +40,8 @@ spec:
   mcpServers: []
   # Runtime execution feature: checkpointer config passed into the selected backend adapter.
   # This persists resumable graph state for this agent.
-  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`.
-  # The repository default uses the file-backed preset so durable checkpoint state does not require native sqlite bindings.
+  # Available `kind` options in this harness: `SqliteSaver`, `FileCheckpointer`, `MemorySaver`.
+  # The repository default uses the sqlite-backed preset so durable checkpoint state stays inside `runtime/checkpoints.sqlite`.
   checkpointer: default
   # Upstream execution feature: store config passed into the selected backend adapter.
   # In the default deepagent adapter this is the LangGraph store used by `StoreBackend` routes.

package/dist/config/catalogs/stores.yaml

@@ -13,6 +13,6 @@ spec:
   # agent-harness feature: reusable checkpointer preset for resumable execution state.
   - kind: Checkpointer
     name: default
-    description: Default file-backed checkpointer preset for durable local graph state without native sqlite bindings.
-    checkpointerKind: FileCheckpointer
-    path: runtime/checkpoints.json
+    description: Default sqlite-backed checkpointer preset for durable local graph state under the runtime data root.
+    checkpointerKind: SqliteSaver
+    path: runtime/checkpoints.sqlite

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.283";
+export declare const AGENT_HARNESS_VERSION = "0.0.284";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.283";
+export const AGENT_HARNESS_VERSION = "0.0.284";

package/dist/runtime/harness/run/resources.js

@@ -43,13 +43,13 @@ export async function resolveVectorStore(workspace, vectorStores, vectorStoreRef
     return resolved;
 }
 export function resolveCheckpointer(checkpointers, binding) {
-    const key = `${binding.harnessRuntime.runRoot}:${JSON.stringify(binding.harnessRuntime.checkpointer ?? { kind: "FileCheckpointer", path: resolveRuntimeCheckpointerPath(binding.harnessRuntime.runRoot, "checkpoints.json") })}`;
+    const key = `${binding.harnessRuntime.runRoot}:${JSON.stringify(binding.harnessRuntime.checkpointer ?? { kind: "SqliteSaver", path: resolveRuntimeCheckpointerPath(binding.harnessRuntime.runRoot, "checkpoints.sqlite") })}`;
     const existing = checkpointers.get(key);
     if (existing) {
         return existing;
     }
     const resolvedConfig = binding.harnessRuntime.checkpointer ??
-        { kind: "FileCheckpointer", path: resolveRuntimeCheckpointerPath(binding.harnessRuntime.runRoot, "checkpoints.json") };
+        { kind: "SqliteSaver", path: resolveRuntimeCheckpointerPath(binding.harnessRuntime.runRoot, "checkpoints.sqlite") };
     if (typeof resolvedConfig === "boolean") {
         checkpointers.set(key, resolvedConfig);
         return resolvedConfig;

package/dist/runtime/maintenance/checkpoint-maintenance.js

@@ -1,4 +1,6 @@
 import path from "node:path";
+import { stat } from "node:fs/promises";
+import { createClient } from "@libsql/client";
 import { fileExists } from "../../utils/fs.js";
 import { resolveRuntimeCheckpointerPath } from "../support/runtime-layout.js";
 import { getRuntimeDefaults } from "../../workspace/support/workspace-ref-utils.js";
@@ -73,13 +75,49 @@ export function discoverCheckpointMaintenanceTargets(workspace) {
 export function maintainSqliteCheckpoints(dbPath, config, nowMs = Date.now()) {
     return maintainSqliteCheckpointsInternal(dbPath, config, nowMs);
 }
-async function maintainSqliteCheckpointsInternal(dbPath, config, _nowMs) {
+async function maintainSqliteCheckpointsInternal(dbPath, config, nowMs) {
     if (!(await fileExists(dbPath))) {
         return { deletedCount: 0 };
     }
-    void config;
+    const client = createClient({ url: `file:${dbPath}` });
+    await client.execute("PRAGMA journal_mode=WAL");
+    await client.execute("PRAGMA foreign_keys=ON");
+    await client.execute("PRAGMA busy_timeout=5000");
+    await client.execute(`
+    CREATE TABLE IF NOT EXISTS checkpoint_state (
+      state_key TEXT PRIMARY KEY,
+      state_json TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    )
+  `);
+    const result = await client.execute("SELECT state_key, updated_at FROM checkpoint_state");
+    if (result.rows.length === 0) {
+        return { deletedCount: 0 };
+    }
+    const stats = await stat(dbPath).catch(() => null);
+    const maxAgeMs = config.policies.maxAgeSeconds ? config.policies.maxAgeSeconds * 1000 : null;
+    const maxBytes = config.policies.maxBytes ?? null;
+    const sweepBatchSize = Math.max(1, config.sqlite.sweepBatchSize);
+    let deletedCount = 0;
+    for (const row of result.rows.slice(0, sweepBatchSize)) {
+        const stateKey = typeof row.state_key === "string" ? row.state_key : "";
+        const updatedAtMs = typeof row.updated_at === "string" ? Date.parse(row.updated_at) : NaN;
+        const exceededAge = maxAgeMs !== null && Number.isFinite(updatedAtMs) && nowMs - updatedAtMs > maxAgeMs;
+        const exceededBytes = maxBytes !== null && stats !== null && stats.size > maxBytes;
+        if (!exceededAge && !exceededBytes) {
+            continue;
+        }
+        await client.execute({
+            sql: "DELETE FROM checkpoint_state WHERE state_key = ?",
+            args: [stateKey],
+        });
+        deletedCount += 1;
+    }
+    if (deletedCount > 0 && config.sqlite.vacuum) {
+        await client.execute("VACUUM");
+    }
     void path.dirname(dbPath);
-    throw new Error("Checkpoint maintenance for SqliteSaver is not supported in this runtime right now");
+    return { deletedCount };
 }
 export class CheckpointMaintenanceLoop {
     targets;

package/dist/runtime/maintenance/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./checkpoint-maintenance.js";
 export * from "./file-checkpoint-saver.js";
+export * from "./sqlite-checkpoint-saver.js";
 export * from "./runtime-record-maintenance.js";

package/dist/runtime/maintenance/index.js

@@ -1,3 +1,4 @@
 export * from "./checkpoint-maintenance.js";
 export * from "./file-checkpoint-saver.js";
+export * from "./sqlite-checkpoint-saver.js";
 export * from "./runtime-record-maintenance.js";

package/dist/runtime/maintenance/sqlite-checkpoint-saver.d.ts

@@ -0,0 +1,28 @@
+import { MemorySaver } from "@langchain/langgraph";
+type MemorySaverConfig = Parameters<MemorySaver["getTuple"]>[0];
+type MemorySaverListOptions = Parameters<MemorySaver["list"]>[1];
+type MemorySaverPutCheckpoint = Parameters<MemorySaver["put"]>[1];
+type MemorySaverPutMetadata = Parameters<MemorySaver["put"]>[2];
+type MemorySaverPutWrites = Parameters<MemorySaver["putWrites"]>[1];
+type MemorySaverPutResult = ReturnType<MemorySaver["put"]>;
+export declare class SqliteCheckpointSaver extends MemorySaver {
+    readonly filePath: string;
+    private client;
+    private loaded;
+    private initialized;
+    private initialization;
+    private operationChain;
+    constructor(filePath: string);
+    private runSerialized;
+    private getClient;
+    private ensureInitialized;
+    private loadStateRow;
+    private ensureLoaded;
+    private persist;
+    getTuple(config: MemorySaverConfig): Promise<import("@langchain/langgraph").CheckpointTuple | undefined>;
+    list(config: MemorySaverConfig, options?: MemorySaverListOptions): AsyncGenerator<import("@langchain/langgraph").CheckpointTuple, void, unknown>;
+    put(config: MemorySaverConfig, checkpoint: MemorySaverPutCheckpoint, metadata: MemorySaverPutMetadata): MemorySaverPutResult;
+    putWrites(config: MemorySaverConfig, writes: MemorySaverPutWrites, taskId: string): Promise<void>;
+    deleteThread(threadId: string): Promise<void>;
+}
+export { SqliteCheckpointSaver as SqliteSaver };

package/dist/runtime/maintenance/sqlite-checkpoint-saver.js

@@ -0,0 +1,177 @@
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { MemorySaver } from "@langchain/langgraph";
+import { createClient } from "@libsql/client";
+const CHECKPOINT_TABLE = "checkpoint_state";
+const DEFAULT_STATE_KEY = "default";
+function encodeBinary(value) {
+    if (value instanceof Uint8Array) {
+        return {
+            __type: "Uint8Array",
+            data: Array.from(value),
+        };
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => encodeBinary(item));
+    }
+    if (typeof value === "object" && value) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, encodeBinary(entry)]));
+    }
+    return value;
+}
+function decodeBinary(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => decodeBinary(item));
+    }
+    if (typeof value === "object" && value) {
+        const typed = value;
+        if (typed.__type === "Uint8Array" && Array.isArray(typed.data)) {
+            return new Uint8Array(typed.data.map((item) => Number(item)));
+        }
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, decodeBinary(entry)]));
+    }
+    return value;
+}
+function pruneThreadEntries(record, threadId) {
+    for (const key of Object.keys(record)) {
+        if (key.includes(threadId)) {
+            delete record[key];
+            continue;
+        }
+        const value = record[key];
+        if (typeof value === "object" && value && !Array.isArray(value)) {
+            pruneThreadEntries(value, threadId);
+            if (Object.keys(value).length === 0) {
+                delete record[key];
+            }
+        }
+    }
+}
+export class SqliteCheckpointSaver extends MemorySaver {
+    filePath;
+    client = null;
+    loaded = false;
+    initialized = false;
+    initialization = null;
+    operationChain = Promise.resolve();
+    constructor(filePath) {
+        super();
+        this.filePath = filePath;
+        mkdirSync(path.dirname(filePath), { recursive: true });
+    }
+    async runSerialized(operation) {
+        const pending = this.operationChain.then(operation, operation);
+        this.operationChain = pending.then(() => undefined, () => undefined);
+        return pending;
+    }
+    async getClient() {
+        if (!this.client) {
+            this.client = createClient({ url: `file:${this.filePath}` });
+        }
+        return this.client;
+    }
+    async ensureInitialized() {
+        if (this.initialized) {
+            return;
+        }
+        if (this.initialization) {
+            await this.initialization;
+            return;
+        }
+        this.initialization = (async () => {
+            const client = await this.getClient();
+            await client.execute("PRAGMA journal_mode=WAL");
+            await client.execute("PRAGMA foreign_keys=ON");
+            await client.execute("PRAGMA busy_timeout=5000");
+            await client.execute(`
+        CREATE TABLE IF NOT EXISTS ${CHECKPOINT_TABLE} (
+          state_key TEXT PRIMARY KEY,
+          state_json TEXT NOT NULL,
+          updated_at TEXT NOT NULL
+        )
+      `);
+            this.initialized = true;
+            this.initialization = null;
+        })();
+        await this.initialization;
+    }
+    async loadStateRow() {
+        await this.ensureInitialized();
+        const client = await this.getClient();
+        const result = await client.execute({
+            sql: `SELECT state_json, updated_at FROM ${CHECKPOINT_TABLE} WHERE state_key = ?`,
+            args: [DEFAULT_STATE_KEY],
+        });
+        return result.rows[0] ?? null;
+    }
+    async ensureLoaded() {
+        if (this.loaded) {
+            return;
+        }
+        const row = await this.loadStateRow();
+        if (row) {
+            const parsed = JSON.parse(row.state_json);
+            this.storage = decodeBinary(parsed.storage ?? {});
+            this.writes = decodeBinary(parsed.writes ?? {});
+        }
+        else {
+            this.storage = {};
+            this.writes = {};
+        }
+        this.loaded = true;
+    }
+    async persist() {
+        await this.ensureInitialized();
+        const client = await this.getClient();
+        const now = new Date().toISOString();
+        const payload = JSON.stringify({
+            storage: this.storage,
+            writes: this.writes,
+        }, (_key, value) => encodeBinary(value));
+        await client.execute({
+            sql: `INSERT INTO ${CHECKPOINT_TABLE} (state_key, state_json, updated_at)
+         VALUES (?, ?, ?)
+         ON CONFLICT(state_key) DO UPDATE SET
+           state_json = excluded.state_json,
+           updated_at = excluded.updated_at`,
+            args: [DEFAULT_STATE_KEY, payload, now],
+        });
+    }
+    async getTuple(config) {
+        return this.runSerialized(async () => {
+            await this.ensureLoaded();
+            return super.getTuple(config);
+        });
+    }
+    async *list(config, options) {
+        await this.ensureLoaded();
+        for await (const item of super.list(config, options)) {
+            yield item;
+        }
+    }
+    async put(config, checkpoint, metadata) {
+        return this.runSerialized(async () => {
+            await this.ensureLoaded();
+            const result = await super.put(config, checkpoint, metadata);
+            await this.persist();
+            return result;
+        });
+    }
+    async putWrites(config, writes, taskId) {
+        return this.runSerialized(async () => {
+            await this.ensureLoaded();
+            const result = await super.putWrites(config, writes, taskId);
+            await this.persist();
+            return result;
+        });
+    }
+    async deleteThread(threadId) {
+        return this.runSerialized(async () => {
+            await this.ensureLoaded();
+            pruneThreadEntries(this.storage, threadId);
+            pruneThreadEntries(this.writes, threadId);
+            await this.persist();
+        });
+    }
+}
+export { SqliteCheckpointSaver as SqliteSaver };

package/dist/runtime/support/runtime-factories.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { MemorySaver } from "@langchain/langgraph";
 import { FileCheckpointSaver } from "../maintenance/file-checkpoint-saver.js";
+import { SqliteCheckpointSaver } from "../maintenance/sqlite-checkpoint-saver.js";
 import { createInMemoryStore, FileBackedStore, SqliteBackedStore } from "../harness/system/store.js";
 import { resolveKnowledgeFileStorePath, resolveKnowledgeStorePath, resolveRuntimeCheckpointerPath, } from "./runtime-layout.js";
 export function createStoreForConfig(storeConfig, runRoot) {
@@ -28,12 +29,16 @@ export function createCheckpointerForConfig(checkpointerConfig, runRoot) {
     if (typeof checkpointerConfig === "boolean") {
         return checkpointerConfig;
     }
-    const kind = typeof checkpointerConfig.kind === "string" ? checkpointerConfig.kind : "FileCheckpointer";
+    const kind = typeof checkpointerConfig.kind === "string" ? checkpointerConfig.kind : "SqliteSaver";
     switch (kind) {
         case "MemorySaver":
             return new MemorySaver();
-        case "SqliteSaver":
-            throw new Error("Checkpointer kind SqliteSaver is not supported in this runtime right now");
+        case "SqliteSaver": {
+            const configuredPath = typeof checkpointerConfig.path === "string"
+                ? String(checkpointerConfig.path)
+                : resolveRuntimeCheckpointerPath(runRoot, "checkpoints.sqlite");
+            return new SqliteCheckpointSaver(path.isAbsolute(configuredPath) ? configuredPath : path.join(runRoot, configuredPath));
+        }
         case "FileCheckpointer": {
             const configuredPath = typeof checkpointerConfig.path === "string"
                 ? String(checkpointerConfig.path)

package/dist/workspace/validate.js

@@ -10,7 +10,7 @@ function validateCheckpointerConfig(agent) {
         return;
     }
     const typedCheckpointer = checkpointer;
-    const kind = typeof typedCheckpointer.kind === "string" ? typedCheckpointer.kind : "FileCheckpointer";
+    const kind = typeof typedCheckpointer.kind === "string" ? typedCheckpointer.kind : "SqliteSaver";
     const hasPath = typeof typedCheckpointer.path === "string" && typedCheckpointer.path.trim().length > 0;
     if (kind === "MemorySaver" && hasPath) {
         throw new Error(`Agent ${agent.id} checkpointer.path is not supported for kind MemorySaver`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.284",
+  "version": "0.0.285",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",