@botbotgo/agent-harness 0.0.18 → 0.0.19

package/dist/resource/sources.js

@@ -1,9 +1,9 @@
 import { execFile } from "node:child_process";
 import { existsSync, statSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, createPublicKey, verify } from "node:crypto";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 const sourceCache = new Map();
@@ -38,14 +38,22 @@ export function parseExternalSourceLocator(locator) {
     const separator = locator.indexOf("::");
     const rawBase = separator >= 0 ? locator.slice(0, separator) : locator;
     const subpath = separator >= 0 ? locator.slice(separator + 2) : undefined;
-    if (rawBase.startsWith("npm:")) {
-        return { kind: "npm", spec: rawBase.slice(4), subpath };
-    }
-    if (rawBase.startsWith("tgz:")) {
-        return { kind: "tgz", spec: rawBase.slice(4), subpath };
-    }
-    if (rawBase.startsWith("file:")) {
-        return { kind: "file", spec: rawBase.slice(5), subpath };
+    const [baseWithoutQuery, rawQuery = ""] = rawBase.split("?", 2);
+    const query = new URLSearchParams(rawQuery);
+    const shared = {
+        subpath,
+        integrity: query.get("integrity") ?? undefined,
+        signature: query.get("signature") ?? undefined,
+        publicKey: query.get("publicKey") ?? query.get("key") ?? undefined,
+    };
+    if (baseWithoutQuery.startsWith("npm:")) {
+        return { kind: "npm", spec: baseWithoutQuery.slice(4), ...shared };
+    }
+    if (baseWithoutQuery.startsWith("tgz:")) {
+        return { kind: "tgz", spec: baseWithoutQuery.slice(4), ...shared };
+    }
+    if (baseWithoutQuery.startsWith("file:")) {
+        return { kind: "file", spec: baseWithoutQuery.slice(5), ...shared };
     }
     throw new Error(`Unsupported external source locator ${locator}. Use npm:, tgz:, or file:.`);
 }
@@ -59,8 +67,13 @@ async function packAndExtract(packageSpec, cacheKey) {
     const root = sourceCacheDir(cacheKey);
     const extractRoot = path.join(root, "extract");
     const packageRoot = path.join(extractRoot, "package");
+    const tarballMarker = path.join(root, ".tarball-path");
     if (existsSync(path.join(packageRoot, "package.json"))) {
-        return packageRoot;
+        const tarballPath = existsSync(tarballMarker) ? (await readFile(tarballMarker, "utf8")).trim() : undefined;
+        return {
+            basePath: packageRoot,
+            tarballPath: tarballPath || undefined,
+        };
     }
     await mkdir(root, { recursive: true });
     await mkdir(extractRoot, { recursive: true });
@@ -72,41 +85,108 @@ async function packAndExtract(packageSpec, cacheKey) {
     if (!tarballName) {
         throw new Error(`Failed to pack external source ${cacheKey}`);
     }
+    const tarballPath = path.join(root, tarballName);
     await execFileAsync("tar", ["-xzf", tarballName, "-C", extractRoot], {
         cwd: root,
         maxBuffer: 1024 * 1024 * 10,
     });
-    return packageRoot;
+    await writeFile(tarballMarker, tarballPath, "utf8");
+    return {
+        basePath: packageRoot,
+        tarballPath,
+    };
+}
+function decodeIntegrity(integrity) {
+    const trimmed = integrity.trim();
+    if (!trimmed) {
+        throw new Error("External source integrity must not be empty.");
+    }
+    const [algorithm, encoded] = trimmed.includes("-")
+        ? trimmed.split("-", 2)
+        : trimmed.includes(":")
+            ? trimmed.split(":", 2)
+            : [trimmed, ""];
+    if (!encoded) {
+        throw new Error(`External source integrity ${integrity} must use <algorithm>-<digest> or <algorithm>:<digest>.`);
+    }
+    const normalizedAlgorithm = algorithm.toLowerCase();
+    const encoding = /^[a-f0-9]+$/i.test(encoded) ? "hex" : "base64";
+    return {
+        algorithm: normalizedAlgorithm,
+        expected: Buffer.from(encoded, encoding),
+    };
+}
+async function readVerificationPublicKey(publicKey, workspaceRoot) {
+    const trimmed = publicKey.trim();
+    if (trimmed.startsWith("-----BEGIN")) {
+        return trimmed;
+    }
+    const resolved = trimmed.startsWith("file:")
+        ? resolveFileSpec(trimmed.slice("file:".length), workspaceRoot)
+        : resolveFileSpec(trimmed, workspaceRoot);
+    return readFile(resolved);
+}
+async function verifyExternalSource(locator, parsed, cached, workspaceRoot) {
+    if (!parsed.integrity && !parsed.signature) {
+        return;
+    }
+    if (!cached.tarballPath) {
+        throw new Error(`External source ${locator} does not provide a tarball to verify.`);
+    }
+    const tarball = await readFile(cached.tarballPath);
+    if (parsed.integrity) {
+        const { algorithm, expected } = decodeIntegrity(parsed.integrity);
+        const actual = createHash(algorithm).update(tarball).digest();
+        if (!actual.equals(expected)) {
+            throw new Error(`External source ${locator} failed integrity verification.`);
+        }
+    }
+    if (parsed.signature) {
+        if (!parsed.publicKey) {
+            throw new Error(`External source ${locator} signature verification requires publicKey=.`);
+        }
+        const key = createPublicKey(await readVerificationPublicKey(parsed.publicKey, workspaceRoot));
+        const signature = Buffer.from(parsed.signature, "base64");
+        const verified = verify(null, tarball, key, signature) ||
+            verify("sha256", tarball, key, signature);
+        if (!verified) {
+            throw new Error(`External source ${locator} failed signature verification.`);
+        }
+    }
 }
 export async function ensureExternalSource(locator, workspaceRoot) {
     const parsed = parseExternalSourceLocator(locator);
     const cacheKey = `${parsed.kind}:${parsed.spec}`;
     const cached = sourceCache.get(cacheKey);
     if (cached) {
-        return parsed.subpath ? path.join(cached, parsed.subpath) : cached;
+        await verifyExternalSource(locator, parsed, cached, workspaceRoot);
+        return parsed.subpath ? path.join(cached.basePath, parsed.subpath) : cached.basePath;
     }
-    let basePath;
+    let resolved;
     if (parsed.kind === "npm") {
-        basePath = await packAndExtract(parsed.spec, cacheKey);
+        resolved = await packAndExtract(parsed.spec, cacheKey);
     }
     else if (parsed.kind === "tgz") {
-        const resolved = resolveFileSpec(parsed.spec, workspaceRoot);
-        basePath = await packAndExtract(resolved, cacheKey);
+        const tgzPath = resolveFileSpec(parsed.spec, workspaceRoot);
+        resolved = await packAndExtract(tgzPath, cacheKey);
+        resolved.tarballPath ??= tgzPath;
     }
     else {
-        const resolved = resolveFileSpec(parsed.spec, workspaceRoot);
-        if (!existsSync(resolved)) {
+        const filePath = resolveFileSpec(parsed.spec, workspaceRoot);
+        if (!existsSync(filePath)) {
             throw new Error(`External file source ${locator} does not exist`);
         }
-        if (resolved.endsWith(".tgz") || resolved.endsWith(".tar.gz")) {
-            basePath = await packAndExtract(resolved, cacheKey);
+        if (filePath.endsWith(".tgz") || filePath.endsWith(".tar.gz")) {
+            resolved = await packAndExtract(filePath, cacheKey);
+            resolved.tarballPath ??= filePath;
         }
         else {
-            basePath = resolved;
+            resolved = { basePath: filePath };
         }
     }
-    sourceCache.set(cacheKey, basePath);
-    return parsed.subpath ? path.join(basePath, parsed.subpath) : basePath;
+    sourceCache.set(cacheKey, resolved);
+    await verifyExternalSource(locator, parsed, resolved, workspaceRoot);
+    return parsed.subpath ? path.join(resolved.basePath, parsed.subpath) : resolved.basePath;
 }
 export async function ensureExternalResourceSource(locator, workspaceRoot) {
     const parsed = parseExternalSourceLocator(locator);
@@ -134,7 +214,7 @@ export function resolveExternalSourcePath(locator, workspaceRoot) {
     const cacheKey = `${parsed.kind}:${parsed.spec}`;
     const cached = sourceCache.get(cacheKey);
     if (cached) {
-        return parsed.subpath ? path.join(cached, parsed.subpath) : cached;
+        return parsed.subpath ? path.join(cached.basePath, parsed.subpath) : cached.basePath;
     }
     if (parsed.kind === "file") {
         const resolved = resolveFileSpec(parsed.spec, workspaceRoot);

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

@@ -0,0 +1,36 @@
+import type { WorkspaceBundle } from "../contracts/types.js";
+type CheckpointMaintenanceConfig = {
+    enabled: boolean;
+    schedule: {
+        intervalSeconds: number;
+        runOnStartup: boolean;
+    };
+    policies: {
+        maxAgeSeconds?: number;
+        maxBytes?: number;
+    };
+    sqlite: {
+        sweepBatchSize: number;
+        vacuum: boolean;
+    };
+};
+type CheckpointMaintenanceTarget = {
+    agentId: string;
+    dbPath: string;
+};
+export declare function readCheckpointMaintenanceConfig(workspace: WorkspaceBundle): CheckpointMaintenanceConfig | null;
+export declare function discoverCheckpointMaintenanceTargets(workspace: WorkspaceBundle): CheckpointMaintenanceTarget[];
+export declare function maintainSqliteCheckpoints(dbPath: string, config: CheckpointMaintenanceConfig, nowMs?: number): {
+    deletedCount: number;
+};
+export declare class CheckpointMaintenanceLoop {
+    private readonly targets;
+    private readonly config;
+    private timer;
+    private running;
+    constructor(targets: CheckpointMaintenanceTarget[], config: CheckpointMaintenanceConfig);
+    runOnce(nowMs?: number): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export {};

package/dist/runtime/checkpoint-maintenance.js

@@ -0,0 +1,223 @@
+import path from "node:path";
+import { SqliteSaver } from "@langchain/langgraph-checkpoint-sqlite";
+import { getRuntimeDefaults } from "../workspace/support/workspace-ref-utils.js";
+import { ManagedSqliteSaver } from "./sqlite-maintained-checkpoint-saver.js";
+function asObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function readPositiveNumber(value, label, allowUndefined = true) {
+    if (value === undefined && allowUndefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new Error(`${label} must be a positive number`);
+    }
+    return value;
+}
+export function readCheckpointMaintenanceConfig(workspace) {
+    const runtimeDefaults = getRuntimeDefaults(workspace.refs);
+    const maintenance = asObject(runtimeDefaults?.maintenance);
+    const checkpoints = asObject(maintenance?.checkpoints);
+    if (!checkpoints || checkpoints.enabled !== true) {
+        return null;
+    }
+    const schedule = asObject(checkpoints.schedule);
+    const policies = asObject(checkpoints.policies);
+    const sqlite = asObject(checkpoints.sqlite);
+    const config = {
+        enabled: true,
+        schedule: {
+            intervalSeconds: readPositiveNumber(schedule?.intervalSeconds, "runtime.maintenance.checkpoints.schedule.intervalSeconds") ?? 3600,
+            runOnStartup: schedule?.runOnStartup !== false,
+        },
+        policies: {
+            maxAgeSeconds: readPositiveNumber(policies?.maxAgeSeconds, "runtime.maintenance.checkpoints.policies.maxAgeSeconds"),
+            maxBytes: readPositiveNumber(policies?.maxBytes, "runtime.maintenance.checkpoints.policies.maxBytes"),
+        },
+        sqlite: {
+            sweepBatchSize: readPositiveNumber(sqlite?.sweepBatchSize, "runtime.maintenance.checkpoints.sqlite.sweepBatchSize") ?? 200,
+            vacuum: sqlite?.vacuum === true,
+        },
+    };
+    if (config.policies.maxAgeSeconds === undefined && config.policies.maxBytes === undefined) {
+        throw new Error("runtime.maintenance.checkpoints.enabled requires at least one cleanup policy");
+    }
+    return config;
+}
+function resolveSqliteCheckpointPath(binding) {
+    const config = binding.harnessRuntime.checkpointer;
+    if (!config) {
+        return null;
+    }
+    const kind = typeof config.kind === "string" ? config.kind : "FileCheckpointer";
+    if (kind !== "SqliteSaver") {
+        return null;
+    }
+    const configuredPath = typeof config.path === "string" ? String(config.path) : "checkpoints.sqlite";
+    return path.isAbsolute(configuredPath) ? configuredPath : path.join(binding.harnessRuntime.runRoot, configuredPath);
+}
+export function discoverCheckpointMaintenanceTargets(workspace) {
+    const deduped = new Map();
+    for (const binding of workspace.bindings.values()) {
+        const dbPath = resolveSqliteCheckpointPath(binding);
+        if (!dbPath) {
+            continue;
+        }
+        deduped.set(dbPath, {
+            agentId: binding.agent.id,
+            dbPath,
+        });
+    }
+    return Array.from(deduped.values());
+}
+function backfillCheckpointMetadata(db, nowMs = Date.now()) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS checkpoint_maintenance_meta (
+  thread_id TEXT NOT NULL,
+  checkpoint_ns TEXT NOT NULL DEFAULT '',
+  checkpoint_id TEXT NOT NULL,
+  created_at_ms INTEGER NOT NULL,
+  PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+);`);
+    db.prepare(`INSERT OR IGNORE INTO checkpoint_maintenance_meta
+     (thread_id, checkpoint_ns, checkpoint_id, created_at_ms)
+     SELECT thread_id, checkpoint_ns, checkpoint_id, ?
+     FROM checkpoints`).run(nowMs);
+}
+function deleteCheckpointRows(db, rows) {
+    if (rows.length === 0) {
+        return 0;
+    }
+    const deleteCheckpoint = db.prepare(`DELETE FROM checkpoints
+     WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?`);
+    const deleteWrites = db.prepare(`DELETE FROM writes
+     WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?`);
+    const deleteMeta = db.prepare(`DELETE FROM checkpoint_maintenance_meta
+     WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?`);
+    db.transaction((items) => {
+        for (const row of items) {
+            deleteCheckpoint.run(row.thread_id, row.checkpoint_ns, row.checkpoint_id);
+            deleteWrites.run(row.thread_id, row.checkpoint_ns, row.checkpoint_id);
+            deleteMeta.run(row.thread_id, row.checkpoint_ns, row.checkpoint_id);
+        }
+    })(rows);
+    return rows.length;
+}
+function selectOldestRows(db, limit) {
+    return db
+        .prepare(`SELECT
+         meta.thread_id,
+         meta.checkpoint_ns,
+         meta.checkpoint_id,
+         meta.created_at_ms,
+         COALESCE(LENGTH(cp.checkpoint), 0) + COALESCE(LENGTH(cp.metadata), 0) + COALESCE(SUM(LENGTH(w.value)), 0) AS size_bytes
+       FROM checkpoint_maintenance_meta AS meta
+       JOIN checkpoints AS cp
+         ON cp.thread_id = meta.thread_id
+        AND cp.checkpoint_ns = meta.checkpoint_ns
+        AND cp.checkpoint_id = meta.checkpoint_id
+       LEFT JOIN writes AS w
+         ON w.thread_id = meta.thread_id
+        AND w.checkpoint_ns = meta.checkpoint_ns
+        AND w.checkpoint_id = meta.checkpoint_id
+       GROUP BY meta.thread_id, meta.checkpoint_ns, meta.checkpoint_id, meta.created_at_ms, cp.checkpoint, cp.metadata
+       ORDER BY meta.created_at_ms ASC, meta.checkpoint_id ASC
+       LIMIT ?`)
+        .all(limit);
+}
+function totalCheckpointBytes(db) {
+    const checkpointsBytes = db
+        .prepare(`SELECT COALESCE(SUM(LENGTH(checkpoint) + LENGTH(metadata)), 0) AS total FROM checkpoints`)
+        .get();
+    const writesBytes = db
+        .prepare(`SELECT COALESCE(SUM(LENGTH(value)), 0) AS total FROM writes`)
+        .get();
+    return Number(checkpointsBytes.total ?? 0) + Number(writesBytes.total ?? 0);
+}
+export function maintainSqliteCheckpoints(dbPath, config, nowMs = Date.now()) {
+    const saver = new ManagedSqliteSaver(SqliteSaver.fromConnString(dbPath).db);
+    const db = saver.db;
+    try {
+        saver.prepareMaintenance();
+        backfillCheckpointMetadata(db, nowMs);
+        let deletedCount = 0;
+        if (config.policies.maxAgeSeconds !== undefined) {
+            const cutoffMs = nowMs - config.policies.maxAgeSeconds * 1000;
+            const expired = db
+                .prepare(`SELECT
+             meta.thread_id,
+             meta.checkpoint_ns,
+             meta.checkpoint_id,
+             meta.created_at_ms,
+             0 AS size_bytes
+           FROM checkpoint_maintenance_meta AS meta
+           WHERE meta.created_at_ms <= ?
+           ORDER BY meta.created_at_ms ASC, meta.checkpoint_id ASC
+           LIMIT ?`)
+                .all(cutoffMs, config.sqlite.sweepBatchSize);
+            deletedCount += deleteCheckpointRows(db, expired);
+        }
+        if (config.policies.maxBytes !== undefined) {
+            let currentBytes = totalCheckpointBytes(db);
+            while (currentBytes > config.policies.maxBytes) {
+                const oldest = selectOldestRows(db, config.sqlite.sweepBatchSize);
+                if (oldest.length === 0) {
+                    break;
+                }
+                let reclaimed = 0;
+                const toDelete = [];
+                for (const row of oldest) {
+                    toDelete.push(row);
+                    reclaimed += Number(row.size_bytes ?? 0);
+                    if (currentBytes - reclaimed <= config.policies.maxBytes) {
+                        break;
+                    }
+                }
+                deletedCount += deleteCheckpointRows(db, toDelete);
+                currentBytes = totalCheckpointBytes(db);
+            }
+        }
+        if (deletedCount > 0 && config.sqlite.vacuum) {
+            db.exec("VACUUM");
+        }
+        return { deletedCount };
+    }
+    finally {
+        db.close();
+    }
+}
+export class CheckpointMaintenanceLoop {
+    targets;
+    config;
+    timer = null;
+    running = false;
+    constructor(targets, config) {
+        this.targets = targets;
+        this.config = config;
+    }
+    async runOnce(nowMs = Date.now()) {
+        for (const target of this.targets) {
+            maintainSqliteCheckpoints(target.dbPath, this.config, nowMs);
+        }
+    }
+    async start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        if (this.config.schedule.runOnStartup) {
+            await this.runOnce();
+        }
+        this.timer = setInterval(() => {
+            void this.runOnce();
+        }, this.config.schedule.intervalSeconds * 1000);
+        this.timer.unref?.();
+    }
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.running = false;
+    }
+}

package/dist/runtime/harness.d.ts

@@ -1,4 +1,4 @@
-import type { ApprovalRecord, HarnessEvent, HarnessStreamItem, RunStartOptions, RestartConversationOptions, RuntimeAdapterOptions, ResumeOptions, RunOptions, RunResult, ThreadSummary, ThreadRecord, WorkspaceBundle } from "../contracts/types.js";
+import type { ApprovalRecord, CompiledTool, HarnessEvent, HarnessStreamItem, RunStartOptions, RestartConversationOptions, RuntimeAdapterOptions, ResumeOptions, RunOptions, RunResult, ThreadSummary, ThreadRecord, WorkspaceBundle } from "../contracts/types.js";
 export declare class AgentHarness {
     private readonly workspace;
     private readonly runtimeAdapterOptions;
@@ -14,6 +14,8 @@ export declare class AgentHarness {
     private readonly routingSystemPrompt?;
     private readonly threadMemorySync;
     private readonly unsubscribeThreadMemorySync;
+    private readonly resolvedRuntimeAdapterOptions;
+    private readonly checkpointMaintenance;
     private listHostBindings;
     private defaultRunRoot;
     private heuristicRoute;
@@ -25,6 +27,13 @@ export declare class AgentHarness {
     constructor(workspace: WorkspaceBundle, runtimeAdapterOptions?: RuntimeAdapterOptions);
     initialize(): Promise<void>;
     subscribe(listener: (event: HarnessEvent) => void): () => void;
+    getWorkspace(): WorkspaceBundle;
+    getBinding(agentId: string): WorkspaceBundle["bindings"] extends Map<any, infer T> ? T | undefined : never;
+    listAgentTools(agentId: string): CompiledTool[];
+    resolveAgentTools(agentId: string): Array<{
+        compiledTool: CompiledTool;
+        resolvedTool: unknown;
+    }>;
     listSessions(filter?: {
         agentId?: string;
     }): Promise<ThreadSummary[]>;

package/dist/runtime/harness.js

@@ -12,6 +12,7 @@ import { resolveCompiledEmbeddingModel, resolveCompiledEmbeddingModelRef } from
 import { resolveCompiledVectorStore, resolveCompiledVectorStoreRef } from "./support/vector-stores.js";
 import { ThreadMemorySync } from "./thread-memory-sync.js";
 import { FileBackedStore } from "./store.js";
+import { CheckpointMaintenanceLoop, discoverCheckpointMaintenanceTargets, readCheckpointMaintenanceConfig, } from "./checkpoint-maintenance.js";
 export class AgentHarness {
     workspace;
     runtimeAdapterOptions;
@@ -27,6 +28,8 @@ export class AgentHarness {
     routingSystemPrompt;
     threadMemorySync;
     unsubscribeThreadMemorySync;
+    resolvedRuntimeAdapterOptions;
+    checkpointMaintenance;
     listHostBindings() {
         return inferRoutingBindings(this.workspace).hostBindings;
     }
@@ -112,7 +115,7 @@ export class AgentHarness {
         this.persistence = new FilePersistence(runRoot);
         const defaultStoreConfig = this.listHostBindings()[0]?.harnessRuntime.store;
         this.defaultStore = defaultStoreConfig ? createStoreForConfig(defaultStoreConfig, runRoot) : new FileBackedStore(`${runRoot}/store.json`);
-        this.runtimeAdapter = new AgentRuntimeAdapter({
+        this.resolvedRuntimeAdapterOptions = {
             ...runtimeAdapterOptions,
             toolResolver: runtimeAdapterOptions.toolResolver ??
                 createResourceToolResolver(workspace, {
@@ -136,19 +139,51 @@ export class AgentHarness {
                 ((binding) => this.resolveStore(binding)),
             backendResolver: runtimeAdapterOptions.backendResolver ??
                 ((binding) => createResourceBackendResolver(workspace)(binding)),
-        });
+        };
+        this.runtimeAdapter = new AgentRuntimeAdapter(this.resolvedRuntimeAdapterOptions);
         this.routingSystemPrompt = getRoutingSystemPrompt(workspace.refs);
         this.threadMemorySync = new ThreadMemorySync(this.persistence, this.defaultStore);
         this.unsubscribeThreadMemorySync = this.eventBus.subscribe((event) => {
             void this.threadMemorySync.handleEvent(event);
         });
+        const checkpointMaintenanceConfig = readCheckpointMaintenanceConfig(workspace);
+        this.checkpointMaintenance = checkpointMaintenanceConfig
+            ? new CheckpointMaintenanceLoop(discoverCheckpointMaintenanceTargets(workspace), checkpointMaintenanceConfig)
+            : null;
     }
     async initialize() {
         await this.persistence.initialize();
+        await this.checkpointMaintenance?.start();
     }
     subscribe(listener) {
         return this.eventBus.subscribe(listener);
     }
+    getWorkspace() {
+        return this.workspace;
+    }
+    getBinding(agentId) {
+        return this.workspace.bindings.get(agentId);
+    }
+    listAgentTools(agentId) {
+        const binding = this.getBinding(agentId);
+        if (!binding) {
+            throw new Error(`Unknown agent ${agentId}`);
+        }
+        return binding.langchainAgentParams?.tools ?? binding.deepAgentParams?.tools ?? [];
+    }
+    resolveAgentTools(agentId) {
+        const binding = this.getBinding(agentId);
+        if (!binding) {
+            throw new Error(`Unknown agent ${agentId}`);
+        }
+        const compiledTools = this.listAgentTools(agentId);
+        const resolver = this.resolvedRuntimeAdapterOptions.toolResolver;
+        const resolvedTools = resolver ? resolver(compiledTools.map((tool) => tool.id), binding) : [];
+        return compiledTools.map((compiledTool, index) => ({
+            compiledTool,
+            resolvedTool: resolvedTools[index],
+        }));
+    }
     async listSessions(filter) {
         const threadSummaries = await this.persistence.listSessions();
         if (!filter?.agentId) {
@@ -750,6 +785,7 @@ export class AgentHarness {
         };
     }
     async close() {
+        await this.checkpointMaintenance?.stop();
         this.unsubscribeThreadMemorySync();
         await this.threadMemorySync.close();
     }

package/dist/runtime/index.d.ts

@@ -1,6 +1,8 @@
 export { AgentRuntimeAdapter, AGENT_INTERRUPT_SENTINEL_PREFIX } from "./agent-runtime-adapter.js";
 export { EventBus } from "./event-bus.js";
 export { FileCheckpointSaver } from "./file-checkpoint-saver.js";
+export { CheckpointMaintenanceLoop, discoverCheckpointMaintenanceTargets, maintainSqliteCheckpoints, readCheckpointMaintenanceConfig, } from "./checkpoint-maintenance.js";
+export { ManagedSqliteSaver } from "./sqlite-maintained-checkpoint-saver.js";
 export { AgentHarness } from "./harness.js";
 export { describeWorkspaceInventory, findAgentBinding, listAgentSkills, listAgentTools, listAvailableAgents, listSpecialists, } from "./inventory.js";
 export * from "./parsing/index.js";

package/dist/runtime/index.js

@@ -1,6 +1,8 @@
 export { AgentRuntimeAdapter, AGENT_INTERRUPT_SENTINEL_PREFIX } from "./agent-runtime-adapter.js";
 export { EventBus } from "./event-bus.js";
 export { FileCheckpointSaver } from "./file-checkpoint-saver.js";
+export { CheckpointMaintenanceLoop, discoverCheckpointMaintenanceTargets, maintainSqliteCheckpoints, readCheckpointMaintenanceConfig, } from "./checkpoint-maintenance.js";
+export { ManagedSqliteSaver } from "./sqlite-maintained-checkpoint-saver.js";
 export { AgentHarness } from "./harness.js";
 export { describeWorkspaceInventory, findAgentBinding, listAgentSkills, listAgentTools, listAvailableAgents, listSpecialists, } from "./inventory.js";
 export * from "./parsing/index.js";

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

@@ -0,0 +1,9 @@
+import { SqliteSaver } from "@langchain/langgraph-checkpoint-sqlite";
+import type { RunnableConfig } from "@langchain/core/runnables";
+export declare class ManagedSqliteSaver extends SqliteSaver {
+    constructor(db: ConstructorParameters<typeof SqliteSaver>[0]);
+    prepareMaintenance(): void;
+    setup(): void;
+    put(config: RunnableConfig, checkpoint: Parameters<SqliteSaver["put"]>[1], metadata: Parameters<SqliteSaver["put"]>[2]): Promise<RunnableConfig<Record<string, any>>>;
+    deleteThread(threadId: string): Promise<void>;
+}

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

@@ -0,0 +1,39 @@
+import { SqliteSaver } from "@langchain/langgraph-checkpoint-sqlite";
+export class ManagedSqliteSaver extends SqliteSaver {
+    constructor(db) {
+        super(db);
+    }
+    prepareMaintenance() {
+        this.setup();
+    }
+    setup() {
+        super.setup();
+        this.db.exec(`
+CREATE TABLE IF NOT EXISTS checkpoint_maintenance_meta (
+  thread_id TEXT NOT NULL,
+  checkpoint_ns TEXT NOT NULL DEFAULT '',
+  checkpoint_id TEXT NOT NULL,
+  created_at_ms INTEGER NOT NULL,
+  PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+);`);
+    }
+    async put(config, checkpoint, metadata) {
+        const result = await super.put(config, checkpoint, metadata);
+        const threadId = result.configurable?.thread_id;
+        const checkpointNs = result.configurable?.checkpoint_ns ?? "";
+        const checkpointId = result.configurable?.checkpoint_id;
+        if (!threadId || !checkpointId) {
+            throw new Error("Missing checkpoint identity after SqliteSaver.put");
+        }
+        this.db
+            .prepare(`INSERT OR IGNORE INTO checkpoint_maintenance_meta
+         (thread_id, checkpoint_ns, checkpoint_id, created_at_ms)
+         VALUES (?, ?, ?, ?)`)
+            .run(threadId, checkpointNs, checkpointId, Date.now());
+        return result;
+    }
+    async deleteThread(threadId) {
+        await super.deleteThread(threadId);
+        this.db.prepare(`DELETE FROM checkpoint_maintenance_meta WHERE thread_id = ?`).run(threadId);
+    }
+}

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

@@ -2,6 +2,7 @@ import path from "node:path";
 import { MemorySaver } from "@langchain/langgraph";
 import { SqliteSaver } from "@langchain/langgraph-checkpoint-sqlite";
 import { FileCheckpointSaver } from "../file-checkpoint-saver.js";
+import { ManagedSqliteSaver } from "../sqlite-maintained-checkpoint-saver.js";
 import { createInMemoryStore, FileBackedStore } from "../store.js";
 export function createStoreForConfig(storeConfig, runRoot) {
     const kind = typeof storeConfig.kind === "string" ? storeConfig.kind : "FileStore";
@@ -27,7 +28,8 @@ export function createCheckpointerForConfig(checkpointerConfig, runRoot) {
             return new MemorySaver();
         case "SqliteSaver": {
             const configuredPath = typeof checkpointerConfig.path === "string" ? String(checkpointerConfig.path) : "checkpoints.sqlite";
-            return SqliteSaver.fromConnString(path.isAbsolute(configuredPath) ? configuredPath : path.join(runRoot, configuredPath));
+            const resolvedPath = path.isAbsolute(configuredPath) ? configuredPath : path.join(runRoot, configuredPath);
+            return new ManagedSqliteSaver(SqliteSaver.fromConnString(resolvedPath).db);
         }
         case "FileCheckpointer": {
             const configuredPath = typeof checkpointerConfig.path === "string" ? String(checkpointerConfig.path) : "checkpoints.json";

package/dist/tool-modules.d.ts

@@ -0,0 +1,17 @@
+type ImportedToolModule = Record<string, unknown>;
+type SchemaLike = {
+    parse: (input: unknown) => unknown;
+    description?: string;
+    shape?: Record<string, unknown>;
+};
+export type LoadedToolModule = {
+    implementationName: string;
+    invoke: (input: unknown, context?: Record<string, unknown>) => Promise<unknown> | unknown;
+    schema: SchemaLike;
+    description: string;
+};
+export declare function isSupportedToolModulePath(filePath: string): boolean;
+export declare function discoverAnnotatedFunctionNames(sourceText: string): string[];
+export declare function discoverToolModuleDefinitions(sourceText: string, imported: ImportedToolModule): LoadedToolModule[];
+export declare function loadToolModuleDefinition(imported: ImportedToolModule, implementationName: string): LoadedToolModule;
+export {};