@botbotgo/agent-harness 0.0.283 → 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

@@ -10,9 +10,6 @@ metadata:
   description: Manual low-latency host for direct answers and lightweight inventory lookup. Do not use it as the default executor for tool-heavy or delegation-heavy tasks.
 spec:
   runtime:
-    # agent-harness feature: host-level run data placement override.
-    # This matches the workspace default and keeps the default config shape explicit.
-    runRoot: ./.agent
     # agent-harness feature: workspace-level durable long-term memory defaults for this host profile.
     runtimeMemory: default
   # =====================
@@ -36,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

@@ -10,9 +10,6 @@ metadata:
   description: Default execution host. Answer directly when possible, use local tools and skills first, and delegate only when a subagent is a better fit. Not a reflex delegation-only orchestrator.
 spec:
   runtime:
-    # agent-harness feature: host-level run data placement override.
-    # This matches the workspace default and keeps the default config shape explicit.
-    runRoot: ./.agent
     # agent-harness feature: workspace-level durable long-term memory defaults for this host profile.
     runtimeMemory: default
   # =====================
@@ -43,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: 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/config/catalogs/vector-stores.yaml

@@ -13,7 +13,7 @@ spec:
     storeKind: LibSQLVectorStore
     # LangChain aligned feature: libSQL connection URL.
     # Local SQLite files use the `file:` prefix.
-    url: file:.agent/knowledge/vectors.sqlite
+    url: file:knowledge/vectors.sqlite
     # LangChain aligned feature: target table and embedding column.
     table: rag_chunks
     column: embedding

package/dist/config/runtime/workspace.yaml

@@ -12,15 +12,22 @@ spec:
   # ======================
   # agent-harness Features
   # ======================
-  # agent-harness feature: filesystem root where the harness stores local run artifacts by default.
-  # This affects file-backed persistence such as:
-  # - session / thread / run indexes
-  # - approval and delegation records
-  # - default file-backed store paths
-  # - default file-backed checkpointer paths
-  # Agents inherit this value unless they override `spec.runRoot` locally.
-  # Value options: relative workspace path like `./.agent`, or an absolute filesystem path.
-  runRoot: ./.agent
+  # agent-harness feature: read-only application folder that contains the shared workspace assembly.
+  # This is where the runtime loads config catalogs and packaged resources such as:
+  # - config/
+  # - resources/
+  # Downstream applications can point multiple runtime profiles at the same application folder.
+  applicationRoot: .
+
+  # agent-harness feature: writable data folder for one runtime profile.
+  # Runtime-owned persistence stays under this root, split by function:
+  # - runtime/ for requests, approvals, checkpoints, and artifacts
+  # - knowledge/ for durable knowledge and vector indexes
+  # Different runtime profiles can use different data folders while sharing the same application folder.
+  dataRoot: ./.agent
+
+  # agent-harness feature: stable runtime profile identifier for this data folder.
+  profile: default
 
   # agent-harness feature: runtime-level task queue and maximum number of concurrent runs.
   # Additional runs wait in the harness queue until a slot becomes available.

package/dist/contracts/workspace.d.ts

@@ -7,6 +7,9 @@ export type ParsedAgentObject = {
     description: string;
     modelRef: string;
     runRoot?: string;
+    applicationRoot?: string;
+    dataRoot?: string;
+    runtimeProfile?: string;
     toolRefs: string[];
     toolBindings?: ParsedAgentToolBinding[];
     inlineTools?: ParsedToolObject[];
@@ -260,6 +263,9 @@ export type CompiledAgentBinding = {
      */
     deepAgentParams?: LegacyDeepAgentParams;
     harnessRuntime: {
+        applicationRoot?: string;
+        dataRoot?: string;
+        runtimeProfile?: string;
         runRoot: string;
         workspaceRoot?: string;
         capabilities?: RuntimeCapabilities;

package/dist/init-project.js

@@ -93,7 +93,9 @@ kind: Runtime
 metadata:
   name: default
 spec:
-  runRoot: ./.agent
+  applicationRoot: .
+  dataRoot: ./.agent
+  profile: default
 `;
 }
 function renderAgentContext(options) {

package/dist/package-version.d.ts

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

package/dist/package-version.js

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

package/dist/persistence/sqlite-store.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { mkdir, rm } from "node:fs/promises";
 import { createClient } from "@libsql/client";
 import { fileExists, readJson, writeJson } from "../utils/fs.js";
+import { resolveRuntimeRoot, resolveRuntimeSqlitePath } from "../runtime/support/runtime-layout.js";
 import { SqliteRunContextStore } from "./sqlite-run-context-store.js";
 import { SqliteRunQueueStore } from "./sqlite-run-queue-store.js";
 const RUNTIME_SQLITE_SCHEMA_VERSION = 6;
@@ -97,7 +98,9 @@ export class SqlitePersistence {
     initialization = null;
     constructor(runRoot, dbFile = "runtime.sqlite") {
         this.runRoot = runRoot;
-        this.dbPath = path.join(runRoot, dbFile);
+        this.dbPath = dbFile === "runtime.sqlite"
+            ? resolveRuntimeSqlitePath(runRoot)
+            : path.join(resolveRuntimeRoot(runRoot), dbFile);
         this.runContextStore = new SqliteRunContextStore({
             execute: (sql, args) => this.execute(sql, args),
             selectOne: (sql, args) => this.selectOne(sql, args),
@@ -148,7 +151,7 @@ export class SqlitePersistence {
             return;
         }
         this.initialization = (async () => {
-            await mkdir(this.runRoot, { recursive: true });
+            await mkdir(resolveRuntimeRoot(this.runRoot), { recursive: true });
             await this.getClient();
             await this.rawExecute("PRAGMA journal_mode=WAL");
             await this.rawExecute("PRAGMA foreign_keys=ON");

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/harness/system/mem0-ingestion-sync.js

@@ -62,7 +62,7 @@ export function readMem0RuntimeConfig(runtimeMemory, workspaceRoot) {
         projectId: asNonEmptyString(mem0.projectId),
         appId: asNonEmptyString(mem0.appId) ?? workspaceBaseName,
         userIdPrefix: asNonEmptyString(mem0.userIdPrefix),
-        stateStorePath: asNonEmptyString(mem0.stateStorePath) ?? "mem0-sync-state.json",
+        stateStorePath: asNonEmptyString(mem0.stateStorePath) ?? "knowledge/mem0-sync-state.json",
         maxMessagesPerRun: asPositiveInteger(mem0.maxMessagesPerRun) ?? 200,
         writeOnApprovalResolution: asBoolean(mem0.writeOnApprovalResolution) ?? asBoolean(ingestion?.writeOnApprovalResolution) ?? true,
         writeOnRunCompletion: asBoolean(mem0.writeOnRunCompletion) ?? asBoolean(ingestion?.writeOnRunCompletion) ?? true,

package/dist/runtime/harness/system/runtime-memory-manager.js

@@ -57,7 +57,7 @@ export function readRuntimeMemoryFormationConfig(runtimeMemory, workspaceRoot) {
             enabled: asBoolean(background?.enabled) ?? true,
             maxMessagesPerRun: asPositiveInteger(background?.maxMessagesPerRun) ?? asPositiveInteger(ingestion?.maxMessagesPerRun) ?? 40,
             scopes: normalizeScopeList(asMemoryScopes(background?.scopes) ?? ["thread"]),
-            stateStorePath: asNonEmptyString(background?.stateStorePath) ?? `${workspaceBaseName}-memory-formation-state.json`,
+            stateStorePath: asNonEmptyString(background?.stateStorePath) ?? `knowledge/${workspaceBaseName}-memory-formation-state.json`,
             writeOnApprovalResolution: asBoolean(background?.writeOnApprovalResolution) ?? asBoolean(ingestion?.writeOnApprovalResolution) ?? true,
             writeOnRunCompletion: asBoolean(background?.writeOnRunCompletion) ?? asBoolean(ingestion?.writeOnRunCompletion) ?? true,
         },

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/llamaindex.d.ts

@@ -21,4 +21,4 @@ export type VectorStoreRuntimeLike = {
     }) => Promise<void>;
 };
 export declare function createLlamaIndexEmbeddingModel(embeddingModel: CompiledEmbeddingModel): EmbeddingRuntimeLike;
-export declare function createLlamaIndexVectorStore(workspaceRoot: string, vectorStore: CompiledVectorStore, embeddings: EmbeddingRuntimeLike): Promise<VectorStoreRuntimeLike>;
+export declare function createLlamaIndexVectorStore(dataRoot: string, vectorStore: CompiledVectorStore, embeddings: EmbeddingRuntimeLike): Promise<VectorStoreRuntimeLike>;

package/dist/runtime/support/llamaindex.js

@@ -41,8 +41,8 @@ export function createLlamaIndexEmbeddingModel(embeddingModel) {
         },
     };
 }
-export async function createLlamaIndexVectorStore(workspaceRoot, vectorStore, embeddings) {
-    const persistPath = resolveFilePath(vectorStore.url ?? ".agent/knowledge/vectors.json", workspaceRoot);
+export async function createLlamaIndexVectorStore(dataRoot, vectorStore, embeddings) {
+    const persistPath = resolveFilePath(vectorStore.url ?? "knowledge/vectors.json", dataRoot);
     await mkdir(path.dirname(persistPath), { recursive: true });
     const emptyStore = () => SimpleVectorStore.fromDict({
         embeddingDict: {},

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/runtime/support/runtime-layout.d.ts

@@ -1,6 +1,7 @@
-export declare function resolveRuntimeArtifactsRoot(runRoot: string): string;
-export declare function resolveRuntimeSqlitePath(runRoot: string): string;
-export declare function resolveRuntimeCheckpointerPath(runRoot: string, fileName?: string): string;
-export declare function resolveKnowledgeRoot(runRoot: string): string;
-export declare function resolveKnowledgeStorePath(runRoot: string, fileName?: string): string;
-export declare function resolveKnowledgeFileStorePath(runRoot: string, fileName?: string): string;
+export declare function resolveRuntimeRoot(dataRoot: string): string;
+export declare function resolveRuntimeArtifactsRoot(dataRoot: string): string;
+export declare function resolveRuntimeSqlitePath(dataRoot: string): string;
+export declare function resolveRuntimeCheckpointerPath(dataRoot: string, fileName?: string): string;
+export declare function resolveKnowledgeRoot(dataRoot: string): string;
+export declare function resolveKnowledgeStorePath(dataRoot: string, fileName?: string): string;
+export declare function resolveKnowledgeFileStorePath(dataRoot: string, fileName?: string): string;

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

@@ -1,19 +1,22 @@
 import path from "node:path";
-export function resolveRuntimeArtifactsRoot(runRoot) {
-    return path.join(runRoot, "artifacts");
+export function resolveRuntimeRoot(dataRoot) {
+    return path.join(dataRoot, "runtime");
 }
-export function resolveRuntimeSqlitePath(runRoot) {
-    return path.join(runRoot, "runtime.sqlite");
+export function resolveRuntimeArtifactsRoot(dataRoot) {
+    return path.join(resolveRuntimeRoot(dataRoot), "artifacts");
 }
-export function resolveRuntimeCheckpointerPath(runRoot, fileName = "checkpoints.json") {
-    return path.join(runRoot, fileName);
+export function resolveRuntimeSqlitePath(dataRoot) {
+    return path.join(resolveRuntimeRoot(dataRoot), "runtime.sqlite");
 }
-export function resolveKnowledgeRoot(runRoot) {
-    return path.join(runRoot, "knowledge");
+export function resolveRuntimeCheckpointerPath(dataRoot, fileName = "checkpoints.json") {
+    return path.join(resolveRuntimeRoot(dataRoot), fileName);
 }
-export function resolveKnowledgeStorePath(runRoot, fileName = "records.sqlite") {
-    return path.join(resolveKnowledgeRoot(runRoot), fileName);
+export function resolveKnowledgeRoot(dataRoot) {
+    return path.join(dataRoot, "knowledge");
 }
-export function resolveKnowledgeFileStorePath(runRoot, fileName = "records.json") {
-    return path.join(resolveKnowledgeRoot(runRoot), fileName);
+export function resolveKnowledgeStorePath(dataRoot, fileName = "records.sqlite") {
+    return path.join(resolveKnowledgeRoot(dataRoot), fileName);
+}
+export function resolveKnowledgeFileStorePath(dataRoot, fileName = "records.json") {
+    return path.join(resolveKnowledgeRoot(dataRoot), fileName);
 }

package/dist/runtime/support/vector-stores.js

@@ -5,7 +5,7 @@ import { createClient } from "@libsql/client";
 import { LibSQLVectorStore } from "@langchain/community/vectorstores/libsql";
 import { QdrantClient } from "@qdrant/js-client-rest";
 import { compileVectorStore } from "../../workspace/resource-compilers.js";
-import { resolveRefId } from "../../workspace/support/workspace-ref-utils.js";
+import { getRuntimeStorageRoots, resolveRefId } from "../../workspace/support/workspace-ref-utils.js";
 import { resolveCompiledEmbeddingModel, resolveCompiledEmbeddingModelRef } from "./embedding-models.js";
 import { createLlamaIndexVectorStore } from "./llamaindex.js";
 function resolveFileUrl(rawUrl, workspaceRoot) {
@@ -92,10 +92,11 @@ export async function resolveCompiledVectorStore(workspace, vectorStore, options
     if (options.vectorStoreResolver) {
         return options.vectorStoreResolver(vectorStore.id);
     }
+    const { dataRoot } = getRuntimeStorageRoots(workspace.refs, workspace.workspaceRoot);
     if (vectorStore.kind === "LlamaIndexSimpleVectorStore") {
         const embeddingModel = resolveCompiledEmbeddingModelRef(workspace, vectorStore.embeddingModelRef);
         const embeddings = await resolveCompiledEmbeddingModel(embeddingModel, options.embeddingModelResolver);
-        return createLlamaIndexVectorStore(workspace.workspaceRoot, vectorStore, embeddings);
+        return createLlamaIndexVectorStore(dataRoot, vectorStore, embeddings);
     }
     if (vectorStore.kind === "QdrantVectorStore") {
         const embeddingModel = resolveCompiledEmbeddingModelRef(workspace, vectorStore.embeddingModelRef);
@@ -178,7 +179,7 @@ export async function resolveCompiledVectorStore(workspace, vectorStore, options
     const embeddingModel = resolveCompiledEmbeddingModelRef(workspace, vectorStore.embeddingModelRef);
     const embeddings = await resolveCompiledEmbeddingModel(embeddingModel, options.embeddingModelResolver);
     const db = createClient({
-        url: await ensureFileUrlDirectory(vectorStore.url ?? "", workspace.workspaceRoot),
+        url: await ensureFileUrlDirectory(vectorStore.url ?? "", dataRoot),
         ...(vectorStore.authToken ? { authToken: vectorStore.authToken } : {}),
     });
     const table = vectorStore.table ?? "vectors";

package/dist/workspace/agent-binding-compiler.js

@@ -5,7 +5,7 @@ import { compileModel, compileTool } from "./resource-compilers.js";
 import { inferAgentCapabilities } from "./support/agent-capabilities.js";
 import { getAgentExecutionConfigValue, getAgentExecutionObject, getAgentExecutionString } from "./support/agent-execution-config.js";
 import { discoverSkillPaths } from "./support/discovery.js";
-import { compileAgentMemories, getResilienceConfig, getRuntimeDefaults, getRuntimeMemoryDefaults, getWorkspaceObject, resolvePromptValue, resolveRefId } from "./support/workspace-ref-utils.js";
+import { compileAgentMemories, getResilienceConfig, getRuntimeDefaults, getRuntimeMemoryDefaults, getRuntimeStorageRoots, getWorkspaceObject, resolvePromptValue, resolveRefId, } from "./support/workspace-ref-utils.js";
 const WORKSPACE_BOUNDARY_GUIDANCE = "Keep repository and file exploration bounded to the current workspace root unless the user explicitly asks for broader host or filesystem access. " +
     "Do not inspect absolute paths outside the workspace, system directories, or unrelated repos by default. " +
     "Prefer workspace-local tools, relative paths, and the current repository checkout when analyzing code.";
@@ -339,6 +339,7 @@ function resolveRuntimeMemoryConfig(agent, refs) {
 export function compileBinding(workspaceRoot, agent, agents, referencedSubagentIds, refs, models, tools) {
     const internalSubagent = referencedSubagentIds.has(agent.id);
     const runtimeDefaults = getRuntimeDefaults(refs);
+    const runtimeStorage = getRuntimeStorageRoots(refs, workspaceRoot);
     const resilience = getResilienceConfig(refs);
     const compiledAgentSkills = compileAgentSkills(workspaceRoot, agent);
     const compiledAgentMemory = compileAgentMemories(workspaceRoot, agent.memorySources);
@@ -361,15 +362,16 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
         ? mergeConfigObjects(runtimeFilesystemDefaults, getAgentExecutionObject(agent, "filesystem", { executionMode: "langchain-v1" }))
         : undefined;
     const runRoot = typeof agent.runRoot === "string" && agent.runRoot.trim().length > 0
-        ? path.resolve(workspaceRoot, agent.runRoot)
-        : typeof runtimeDefaults?.runRoot === "string" && runtimeDefaults.runRoot.trim().length > 0
-            ? path.resolve(workspaceRoot, runtimeDefaults.runRoot)
-            : path.join(workspaceRoot, "run-data");
+        ? (path.isAbsolute(agent.runRoot) ? agent.runRoot : path.resolve(runtimeStorage.dataRoot, agent.runRoot))
+        : runtimeStorage.dataRoot;
     const base = {
         agent,
         harnessRuntime: {
+            applicationRoot: runtimeStorage.applicationRoot,
+            dataRoot: runtimeStorage.dataRoot,
+            runtimeProfile: runtimeStorage.runtimeProfile,
             runRoot,
-            workspaceRoot,
+            workspaceRoot: runtimeStorage.applicationRoot,
             capabilities: inferAgentCapabilities(agent),
             resilience,
             ...(runtimeGovernanceDefaults ? { governance: runtimeGovernanceDefaults } : {}),

package/dist/workspace/compile.js

@@ -10,7 +10,7 @@ import { validateAgent, validateTopology } from "./validate.js";
 import { compileBinding } from "./agent-binding-compiler.js";
 import { discoverSubagents, ensureDiscoverySources } from "./support/discovery.js";
 import { collectAgentDiscoverySourceRefs, collectToolSourceRefs } from "./support/source-collectors.js";
-import { getRoutingDefaultAgentId, getRuntimeResources, getToolModuleDiscoveryConfig, getRoutingRules, resolveRefId, } from "./support/workspace-ref-utils.js";
+import { getRoutingDefaultAgentId, getRuntimeResources, getRuntimeStorageRoots, getToolModuleDiscoveryConfig, getRoutingRules, resolveRefId, } from "./support/workspace-ref-utils.js";
 import { hydrateAgentMcpTools, hydrateResourceAndExternalTools } from "./tool-hydration.js";
 import { traceStartupStage } from "../runtime/startup-tracing.js";
 import { shouldSkipScanDirectory } from "../utils/fs.js";
@@ -209,6 +209,11 @@ export async function loadWorkspace(workspaceRoot, options = {}) {
     const loaded = await traceStartupStage("workspace.load.objects", () => loadWorkspaceObjects(workspaceRoot, options), {
         workspaceRoot,
     });
+    const runtimeStorage = getRuntimeStorageRoots(loaded.refs, workspaceRoot);
+    if (path.resolve(runtimeStorage.applicationRoot) !== path.resolve(workspaceRoot)) {
+        throw new Error(`Runtime applicationRoot ${runtimeStorage.applicationRoot} must resolve to the loaded workspace root ${workspaceRoot}. ` +
+            "Load the shared application folder as the workspace root and use Runtime.dataRoot for writable profile data.");
+    }
     loaded.agents = await traceStartupStage("workspace.discover.subagents", () => discoverSubagents(loaded.agents, workspaceRoot), {
         workspaceRoot,
     });

package/dist/workspace/object-loader.js

@@ -516,6 +516,9 @@ export function parseAgentItem(item, sourcePath) {
         description: String(normalizedItem.description ?? ""),
         modelRef: readExecutionValue(normalizedItem, "modelRef", readSingleRef) ?? "",
         runRoot: typeof runtime?.runRoot === "string" ? runtime.runRoot : undefined,
+        applicationRoot: typeof runtime?.applicationRoot === "string" ? runtime.applicationRoot : undefined,
+        dataRoot: typeof runtime?.dataRoot === "string" ? runtime.dataRoot : undefined,
+        runtimeProfile: typeof runtime?.profile === "string" ? runtime.profile : undefined,
         toolRefs: toolBindings.map((binding) => binding.ref),
         toolBindings,
         inlineTools: undefined,

package/dist/workspace/support/workspace-ref-utils.d.ts

@@ -37,6 +37,12 @@ export type ToolModuleDiscoveryConfig = {
 };
 export declare function getWorkspaceObject(refs: Map<string, WorkspaceObject | ParsedAgentObject>, ref: string | undefined): WorkspaceObject | undefined;
 export declare function getRuntimeDefaults(refs: Map<string, WorkspaceObject | ParsedAgentObject>): Record<string, unknown> | undefined;
+export type RuntimeStorageRoots = {
+    applicationRoot: string;
+    dataRoot: string;
+    runtimeProfile: string;
+};
+export declare function getRuntimeStorageRoots(refs: Map<string, WorkspaceObject | ParsedAgentObject>, workspaceRoot: string): RuntimeStorageRoots;
 export declare function getRuntimeResources(refs: Map<string, WorkspaceObject | ParsedAgentObject>): string[];
 export declare function getToolModuleDiscoveryConfig(refs: Map<string, WorkspaceObject | ParsedAgentObject>): ToolModuleDiscoveryConfig;
 export declare function getRuntimeMemoryDefaults(refs: Map<string, WorkspaceObject | ParsedAgentObject>): Record<string, unknown> | undefined;

package/dist/workspace/support/workspace-ref-utils.js

@@ -26,6 +26,31 @@ export function getRuntimeDefaults(refs) {
     }
     return runtimes[0].value;
 }
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+export function getRuntimeStorageRoots(refs, workspaceRoot) {
+    const runtimeDefaults = getRuntimeDefaults(refs);
+    const configuredApplicationRoot = asNonEmptyString(runtimeDefaults?.applicationRoot);
+    const configuredDataRoot = asNonEmptyString(runtimeDefaults?.dataRoot);
+    const configuredProfile = asNonEmptyString(runtimeDefaults?.profile);
+    const applicationRoot = configuredApplicationRoot
+        ? (path.isAbsolute(configuredApplicationRoot)
+            ? configuredApplicationRoot
+            : path.resolve(workspaceRoot, configuredApplicationRoot))
+        : workspaceRoot;
+    const dataRoot = configuredDataRoot
+        ? (path.isAbsolute(configuredDataRoot)
+            ? configuredDataRoot
+            : path.resolve(applicationRoot, configuredDataRoot))
+        : path.join(applicationRoot, ".agent");
+    const runtimeProfile = configuredProfile ?? "default";
+    return {
+        applicationRoot,
+        dataRoot,
+        runtimeProfile,
+    };
+}
 export function getRuntimeResources(refs) {
     const runtimeDefaults = getRuntimeDefaults(refs);
     if (!Array.isArray(runtimeDefaults?.resources)) {

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.283",
+  "version": "0.0.285",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",