@abot-ai/runtime 1.0.0 → 1.2.0

package/dist/src/plugin-sdk/tool-availability-overview.js

@@ -0,0 +1,62 @@
+/** Complete informational candidates; callers own admission and context budget. */
+export function buildToolAvailabilityOverview(entries, groups, level) {
+    if (level === "detailed")
+        return describeAvailableTools(entries);
+    const orderedGroups = [...groups].sort((left, right) => compareAscii(left.groupId, right.groupId));
+    if (level === "titles")
+        return describeGroupTools(entries, orderedGroups);
+    return orderedGroups.map(describeGroupMetadata).join("\n");
+}
+function describeAvailableTools(entries) {
+    const tools = new Map();
+    for (const entry of entries) {
+        const tool = tools.get(entry.toolName) ?? {
+            operationIds: new Set(),
+            catalogGroups: new Set(),
+        };
+        tool.operationIds.add(entry.operationId);
+        for (const groupId of entry.catalogGroups)
+            tool.catalogGroups.add(groupId);
+        tools.set(entry.toolName, tool);
+    }
+    return [...tools.entries()]
+        .sort(([left], [right]) => compareAscii(left, right))
+        .map(([toolName, tool]) => `- ${formatOverviewIdentifier(toolName)} — ${sortedValues(tool.operationIds)} [${sortedValues(tool.catalogGroups)}]`)
+        .join("\n");
+}
+function describeGroupTools(entries, groups) {
+    return groups
+        .map((group) => {
+        const toolNames = new Set(entries
+            .filter((entry) => entry.catalogGroups.includes(group.groupId))
+            .map((entry) => entry.toolName));
+        return `- ${group.groupId}: ${sortedValues(toolNames)}`;
+    })
+        .join("\n");
+}
+function describeGroupMetadata(group) {
+    return `- ${group.groupId} (memberCount=${group.memberCount}; effects=${sortedValues(group.effects)})`;
+}
+function sortedValues(values) {
+    return [...values]
+        .sort(compareAscii)
+        .map(formatOverviewIdentifier)
+        .join(", ");
+}
+function formatOverviewIdentifier(value) {
+    if (isPlainOverviewIdentifier(value))
+        return value;
+    return JSON.stringify(value)
+        .replace(/\u2028/gu, "\\u2028")
+        .replace(/\u2029/gu, "\\u2029");
+}
+function isPlainOverviewIdentifier(value) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(value);
+}
+function compareAscii(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}

package/dist/src/runtime/adapters/index.d.ts

@@ -2,6 +2,10 @@ export * from "./configured-skill-provider.js";
 export * from "./compiled-workspace-provider.js";
 export * from "./file-session-store.js";
 export * from "./in-memory-session-store.js";
+export * from "./long-term-memory/file-repository.js";
+export * from "./long-term-memory/in-memory-repository.js";
+export * from "./long-term-memory/onboarding-config-repository.js";
+export * from "./long-term-memory/onboarding-service.js";
 export * from "./multi-workspace-provider.js";
 export * from "./registered-tool-normal-invocations.js";
 export * from "./registered-tool-worker-capabilities.js";

package/dist/src/runtime/adapters/index.js

@@ -2,6 +2,10 @@ export * from "./configured-skill-provider.js";
 export * from "./compiled-workspace-provider.js";
 export * from "./file-session-store.js";
 export * from "./in-memory-session-store.js";
+export * from "./long-term-memory/file-repository.js";
+export * from "./long-term-memory/in-memory-repository.js";
+export * from "./long-term-memory/onboarding-config-repository.js";
+export * from "./long-term-memory/onboarding-service.js";
 export * from "./multi-workspace-provider.js";
 export * from "./registered-tool-normal-invocations.js";
 export * from "./registered-tool-worker-capabilities.js";

package/dist/src/runtime/adapters/long-term-memory/file-lock/acquisition.d.ts

@@ -0,0 +1,2 @@
+import { type FileLockOptions } from "./contracts.js";
+export declare function acquireFileLock(lockPath: string, options: FileLockOptions): Promise<() => Promise<void>>;

package/dist/src/runtime/adapters/long-term-memory/file-lock/acquisition.js

@@ -0,0 +1,77 @@
+import { randomUUID } from "node:crypto";
+import { removeEmptyLockTree, removeObservedOwner } from "./cleanup.js";
+import { fileSystemErrorCode, INCOMPLETE_LOCK_GRACE_MS, LOCK_ACQUIRE_TIMEOUT_MS, LOCK_RETRY_DELAY_MS, ownerFileName, } from "./contracts.js";
+import { installLockDirectory } from "./install.js";
+import { readLockSnapshot } from "./snapshot.js";
+export async function acquireFileLock(lockPath, options) {
+    const waitMs = options.waitMs ?? LOCK_ACQUIRE_TIMEOUT_MS;
+    const retryDelayMs = options.retryDelayMs ?? LOCK_RETRY_DELAY_MS;
+    const processIsAlive = options.processIsAlive ?? defaultProcessIsAlive;
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        const token = randomUUID();
+        try {
+            await installLockDirectory(lockPath, token);
+            return createRelease(lockPath, token);
+        }
+        catch (error) {
+            if (!isLockContention(error))
+                throw error;
+            const removed = await removeAbandonedLock(lockPath, processIsAlive);
+            if (removed)
+                continue;
+            if (Date.now() >= deadline) {
+                throw new Error("long_term_memory_store_lock_timeout");
+            }
+            await delay(Math.min(retryDelayMs, Math.max(deadline - Date.now(), 0)));
+        }
+    }
+}
+function createRelease(lockPath, token) {
+    let released = false;
+    return async () => {
+        if (released)
+            return;
+        await removeObservedOwner(lockPath, ownerFileName(token));
+        released = true;
+    };
+}
+async function removeAbandonedLock(lockPath, processIsAlive) {
+    const snapshot = await readLockSnapshot(lockPath);
+    if (!snapshot)
+        return true;
+    if (snapshot.kind === "legacy_file" || !snapshot.reclaimable)
+        return false;
+    if (snapshot.ownerPid !== undefined && processIsAlive(snapshot.ownerPid)) {
+        return false;
+    }
+    if (snapshot.record && snapshot.ownerFileName) {
+        return removeObservedOwner(lockPath, snapshot.ownerFileName);
+    }
+    const withinIncompleteLockGrace = Date.now() - snapshot.modifiedAtMs < INCOMPLETE_LOCK_GRACE_MS;
+    if (withinIncompleteLockGrace)
+        return false;
+    if (snapshot.ownerFileName) {
+        return removeObservedOwner(lockPath, snapshot.ownerFileName);
+    }
+    return removeEmptyLockTree(lockPath, snapshot.hasLeaseDirectory);
+}
+function defaultProcessIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return fileSystemErrorCode(error) !== "ESRCH";
+    }
+}
+function isLockContention(error) {
+    const code = fileSystemErrorCode(error);
+    return (code === "EEXIST" ||
+        code === "ENOTEMPTY" ||
+        code === "ENOTDIR" ||
+        code === "EISDIR");
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock/cleanup.d.ts

@@ -0,0 +1,4 @@
+export declare function removeObservedOwner(lockPath: string, observedOwnerFileName: string): Promise<boolean>;
+export declare function removeEmptyLockTree(lockPath: string, hasLeaseDirectory: boolean): Promise<boolean>;
+export declare function removeDirectoryIfEmpty(path: string): Promise<boolean>;
+export declare function removeStagingLock(stagingPath: string, stagingOwnerPath: string): Promise<void>;

package/dist/src/runtime/adapters/long-term-memory/file-lock/cleanup.js

@@ -0,0 +1,52 @@
+import { rmdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { fileSystemErrorCode, LEASE_DIRECTORY_NAME } from "./contracts.js";
+export async function removeObservedOwner(lockPath, observedOwnerFileName) {
+    try {
+        await unlink(join(lockPath, LEASE_DIRECTORY_NAME, observedOwnerFileName));
+    }
+    catch (error) {
+        if (fileSystemErrorCode(error) === "ENOENT")
+            return false;
+        throw error;
+    }
+    return removeEmptyLockTree(lockPath, true);
+}
+export async function removeEmptyLockTree(lockPath, hasLeaseDirectory) {
+    if (hasLeaseDirectory &&
+        !(await removeDirectoryIfEmpty(join(lockPath, LEASE_DIRECTORY_NAME)))) {
+        return false;
+    }
+    return removeDirectoryIfEmpty(lockPath);
+}
+export async function removeDirectoryIfEmpty(path) {
+    try {
+        await rmdir(path);
+        return true;
+    }
+    catch (error) {
+        const code = fileSystemErrorCode(error);
+        if (code === "ENOENT")
+            return true;
+        if (code === "EEXIST" || code === "ENOTEMPTY" || code === "ENOTDIR") {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function removeStagingLock(stagingPath, stagingOwnerPath) {
+    try {
+        await unlink(stagingOwnerPath);
+    }
+    catch (error) {
+        if (fileSystemErrorCode(error) !== "ENOENT")
+            throw error;
+    }
+    try {
+        await rmdir(stagingPath);
+    }
+    catch (error) {
+        if (fileSystemErrorCode(error) !== "ENOENT")
+            throw error;
+    }
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock/contracts.d.ts

@@ -0,0 +1,31 @@
+export declare const LOCK_RETRY_DELAY_MS = 10;
+export declare const LOCK_ACQUIRE_TIMEOUT_MS = 2000;
+export declare const INCOMPLETE_LOCK_GRACE_MS = 30000;
+export declare const MAX_LOCK_RECORD_BYTES = 1024;
+export declare const LEASE_DIRECTORY_NAME = "lease";
+export declare const OWNER_FILE_PATTERN: RegExp;
+export type FileLockOptions = Readonly<{
+    waitMs?: number;
+    retryDelayMs?: number;
+    processIsAlive?: (pid: number) => boolean;
+}>;
+export type LockRecord = Readonly<{
+    pid: number;
+    token: string;
+    createdAt: string;
+}>;
+export type DirectoryLockSnapshot = Readonly<{
+    kind: "directory";
+    modifiedAtMs: number;
+    hasLeaseDirectory: boolean;
+    ownerFileName?: string;
+    ownerPid?: number;
+    record?: LockRecord;
+    reclaimable: boolean;
+}>;
+export type LockSnapshot = DirectoryLockSnapshot | Readonly<{
+    kind: "legacy_file";
+}>;
+export declare function ownerFileName(token: string): string;
+export declare function directorySnapshot(snapshot: Omit<DirectoryLockSnapshot, "kind">): DirectoryLockSnapshot;
+export declare function fileSystemErrorCode(error: unknown): string | undefined;

package/dist/src/runtime/adapters/long-term-memory/file-lock/contracts.js

@@ -0,0 +1,17 @@
+export const LOCK_RETRY_DELAY_MS = 10;
+export const LOCK_ACQUIRE_TIMEOUT_MS = 2_000;
+export const INCOMPLETE_LOCK_GRACE_MS = 30_000;
+export const MAX_LOCK_RECORD_BYTES = 1_024;
+export const LEASE_DIRECTORY_NAME = "lease";
+export const OWNER_FILE_PATTERN = /^owner-([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})\.json$/iu;
+export function ownerFileName(token) {
+    return `owner-${token}.json`;
+}
+export function directorySnapshot(snapshot) {
+    return Object.freeze({ kind: "directory", ...snapshot });
+}
+export function fileSystemErrorCode(error) {
+    return error !== null && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : undefined;
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock/install.d.ts

@@ -0,0 +1 @@
+export declare function installLockDirectory(lockPath: string, token: string): Promise<void>;

package/dist/src/runtime/adapters/long-term-memory/file-lock/install.js

@@ -0,0 +1,36 @@
+import { mkdir, open, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { removeDirectoryIfEmpty, removeStagingLock } from "./cleanup.js";
+import { LEASE_DIRECTORY_NAME, ownerFileName } from "./contracts.js";
+export async function installLockDirectory(lockPath, token) {
+    const stagingPath = `${lockPath}.${process.pid}.${token}.pending`;
+    const stagingOwnerPath = join(stagingPath, ownerFileName(token));
+    let handle;
+    let claimedLockPath = false;
+    let installed = false;
+    try {
+        await mkdir(stagingPath, { mode: 0o700 });
+        handle = await open(stagingOwnerPath, "wx", 0o600);
+        await handle.writeFile(JSON.stringify({
+            pid: process.pid,
+            token,
+            createdAt: new Date().toISOString(),
+        }), "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await mkdir(lockPath, { mode: 0o700 });
+        claimedLockPath = true;
+        await rename(stagingPath, join(lockPath, LEASE_DIRECTORY_NAME));
+        installed = true;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        if (!installed) {
+            await removeStagingLock(stagingPath, stagingOwnerPath);
+            if (claimedLockPath) {
+                await removeDirectoryIfEmpty(lockPath);
+            }
+        }
+    }
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock/owner-record.d.ts

@@ -0,0 +1,2 @@
+import { type DirectoryLockSnapshot } from "./contracts.js";
+export declare function readOwnerRecord(lockPath: string, entryName: string, expectedToken: string, directoryModifiedAtMs: number): Promise<DirectoryLockSnapshot>;

package/dist/src/runtime/adapters/long-term-memory/file-lock/owner-record.js

@@ -0,0 +1,114 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { join } from "node:path";
+import { directorySnapshot, fileSystemErrorCode, LEASE_DIRECTORY_NAME, MAX_LOCK_RECORD_BYTES, } from "./contracts.js";
+export async function readOwnerRecord(lockPath, entryName, expectedToken, directoryModifiedAtMs) {
+    let handle;
+    try {
+        handle = await open(join(lockPath, LEASE_DIRECTORY_NAME, entryName), constants.O_RDONLY | constants.O_NOFOLLOW);
+        const before = await handle.stat({ bigint: true });
+        const modifiedAtMs = Math.max(directoryModifiedAtMs, Number(before.mtimeMs));
+        const hasReadableRecord = before.isFile() &&
+            before.size > 0n &&
+            before.size <= BigInt(MAX_LOCK_RECORD_BYTES);
+        if (!hasReadableRecord) {
+            return directorySnapshot({
+                modifiedAtMs,
+                hasLeaseDirectory: true,
+                ownerFileName: entryName,
+                reclaimable: true,
+            });
+        }
+        const raw = await readStableRecord(handle, before);
+        if (raw === undefined) {
+            return directorySnapshot({
+                modifiedAtMs,
+                hasLeaseDirectory: true,
+                ownerFileName: entryName,
+                reclaimable: false,
+            });
+        }
+        const parsed = parseLockRecord(raw, expectedToken);
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            ownerFileName: entryName,
+            reclaimable: true,
+            ...parsed,
+        });
+    }
+    catch (error) {
+        return snapshotReadFailure(error, directoryModifiedAtMs, entryName);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function readStableRecord(handle, before) {
+    const bytes = Buffer.alloc(Number(before.size));
+    let offset = 0;
+    while (offset < bytes.length) {
+        const result = await handle.read(bytes, offset, bytes.length - offset, offset);
+        if (result.bytesRead <= 0)
+            return undefined;
+        offset += result.bytesRead;
+    }
+    const after = await handle.stat({ bigint: true });
+    const recordChangedWhileReading = !after.isFile() ||
+        after.dev !== before.dev ||
+        after.ino !== before.ino ||
+        after.size !== before.size ||
+        after.mtimeNs !== before.mtimeNs ||
+        after.ctimeNs !== before.ctimeNs;
+    return recordChangedWhileReading ? undefined : bytes.toString("utf8");
+}
+function snapshotReadFailure(error, modifiedAtMs, entryName) {
+    const code = fileSystemErrorCode(error);
+    if (code === "ENOENT") {
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            reclaimable: false,
+        });
+    }
+    if (code === "ELOOP") {
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            ownerFileName: entryName,
+            reclaimable: true,
+        });
+    }
+    throw error;
+}
+function parseLockRecord(raw, expectedToken) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return Object.freeze({});
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return Object.freeze({});
+    }
+    const candidate = value;
+    const ownerPid = Number.isSafeInteger(candidate.pid) && Number(candidate.pid) > 0
+        ? Number(candidate.pid)
+        : undefined;
+    const hasValidRecord = ownerPid !== undefined &&
+        candidate.token === expectedToken &&
+        typeof candidate.createdAt === "string" &&
+        Number.isFinite(Date.parse(candidate.createdAt));
+    if (!hasValidRecord) {
+        return Object.freeze({ ...(ownerPid === undefined ? {} : { ownerPid }) });
+    }
+    return Object.freeze({
+        ownerPid,
+        record: Object.freeze({
+            pid: ownerPid,
+            token: expectedToken,
+            createdAt: candidate.createdAt,
+        }),
+    });
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock/snapshot.d.ts

@@ -0,0 +1,2 @@
+import { type LockSnapshot } from "./contracts.js";
+export declare function readLockSnapshot(lockPath: string): Promise<LockSnapshot | undefined>;

package/dist/src/runtime/adapters/long-term-memory/file-lock/snapshot.js

@@ -0,0 +1,103 @@
+import { lstat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { directorySnapshot, fileSystemErrorCode, LEASE_DIRECTORY_NAME, OWNER_FILE_PATTERN, } from "./contracts.js";
+import { readOwnerRecord } from "./owner-record.js";
+export async function readLockSnapshot(lockPath) {
+    const lockInfo = await readLockInfo(lockPath);
+    if (!lockInfo)
+        return undefined;
+    if (!lockInfo.isDirectory()) {
+        return Object.freeze({ kind: "legacy_file" });
+    }
+    let lockEntries;
+    try {
+        lockEntries = await readdir(lockPath, { withFileTypes: true });
+    }
+    catch (error) {
+        const code = fileSystemErrorCode(error);
+        if (code === "ENOENT")
+            return undefined;
+        if (code === "ENOTDIR") {
+            return Object.freeze({ kind: "legacy_file" });
+        }
+        throw error;
+    }
+    if (lockEntries.length === 0) {
+        return directorySnapshot({
+            modifiedAtMs: lockInfo.mtimeMs,
+            hasLeaseDirectory: false,
+            reclaimable: true,
+        });
+    }
+    const hasExpectedLeaseDirectory = lockEntries.length === 1 &&
+        lockEntries[0]?.name === LEASE_DIRECTORY_NAME &&
+        lockEntries[0].isDirectory();
+    if (!hasExpectedLeaseDirectory) {
+        return directorySnapshot({
+            modifiedAtMs: lockInfo.mtimeMs,
+            hasLeaseDirectory: false,
+            reclaimable: false,
+        });
+    }
+    return readLeaseSnapshot(lockPath, lockInfo.mtimeMs);
+}
+async function readLockInfo(lockPath) {
+    try {
+        return await lstat(lockPath);
+    }
+    catch (error) {
+        if (fileSystemErrorCode(error) === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function readLeaseSnapshot(lockPath, lockModifiedAtMs) {
+    const leasePath = join(lockPath, LEASE_DIRECTORY_NAME);
+    let leaseInfo;
+    let leaseEntries;
+    try {
+        leaseInfo = await lstat(leasePath);
+        if (!leaseInfo.isDirectory()) {
+            return invalidLeaseSnapshot(lockModifiedAtMs);
+        }
+        leaseEntries = await readdir(leasePath, { withFileTypes: true });
+    }
+    catch (error) {
+        if (fileSystemErrorCode(error) === "ENOENT") {
+            return invalidLeaseSnapshot(lockModifiedAtMs);
+        }
+        throw error;
+    }
+    const modifiedAtMs = Math.max(lockModifiedAtMs, leaseInfo.mtimeMs);
+    if (leaseEntries.length === 0) {
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            reclaimable: true,
+        });
+    }
+    if (leaseEntries.length !== 1 || !leaseEntries[0]?.isFile()) {
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            reclaimable: false,
+        });
+    }
+    const entryName = leaseEntries[0].name;
+    const token = OWNER_FILE_PATTERN.exec(entryName)?.[1];
+    if (!token) {
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            reclaimable: false,
+        });
+    }
+    return readOwnerRecord(lockPath, entryName, token, modifiedAtMs);
+}
+function invalidLeaseSnapshot(modifiedAtMs) {
+    return directorySnapshot({
+        modifiedAtMs,
+        hasLeaseDirectory: false,
+        reclaimable: false,
+    });
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock.d.ts

@@ -0,0 +1,2 @@
+import type { FileLockOptions } from "./file-lock/contracts.js";
+export declare function withFileLock<T>(lockPath: string, operation: () => Promise<T>, options?: FileLockOptions): Promise<T>;

package/dist/src/runtime/adapters/long-term-memory/file-lock.js

@@ -0,0 +1,10 @@
+import { acquireFileLock } from "./file-lock/acquisition.js";
+export async function withFileLock(lockPath, operation, options = {}) {
+    const release = await acquireFileLock(lockPath, options);
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}

package/dist/src/runtime/adapters/long-term-memory/file-repository.d.ts

@@ -0,0 +1,2 @@
+import type { LongTermMemoryRepository } from "../../long-term-memory/contracts.js";
+export declare function createFileLongTermMemoryRepository(directory: string): LongTermMemoryRepository;

package/dist/src/runtime/adapters/long-term-memory/file-repository.js

@@ -0,0 +1,57 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { advanceMemorySnapshot, createEmptyMemorySnapshot, parseMemorySnapshot, } from "../../long-term-memory/repository-state.js";
+import { withFileLock } from "./file-lock.js";
+const STORE_FILE_NAME = "memory.json";
+const LOCK_FILE_NAME = "memory.lock";
+const PRIVATE_STORE_FILE_MODE = 0o600;
+export function createFileLongTermMemoryRepository(directory) {
+    const storePath = join(directory, STORE_FILE_NAME);
+    const lockPath = join(directory, LOCK_FILE_NAME);
+    return Object.freeze({
+        read: () => readSnapshot(storePath),
+        update: async (mutate) => {
+            await mkdir(directory, { recursive: true });
+            return withFileLock(lockPath, async () => {
+                const current = await readSnapshot(storePath);
+                const next = advanceMemorySnapshot(current, mutate(current));
+                await writeSnapshot(storePath, next);
+                return next;
+            });
+        },
+    });
+}
+async function readSnapshot(storePath) {
+    try {
+        return parseMemorySnapshot(JSON.parse(await readFile(storePath, "utf8")));
+    }
+    catch (error) {
+        if (isMissingFile(error)) {
+            return createEmptyMemorySnapshot();
+        }
+        throw error;
+    }
+}
+async function writeSnapshot(storePath, snapshot) {
+    await mkdir(dirname(storePath), { recursive: true });
+    const temporaryPath = `${storePath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporaryPath, JSON.stringify(snapshot, null, 2), {
+            encoding: "utf8",
+            flag: "wx",
+            mode: PRIVATE_STORE_FILE_MODE,
+        });
+        await rename(temporaryPath, storePath);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+function isMissingFile(error) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/src/runtime/adapters/long-term-memory/in-memory-repository.d.ts

@@ -0,0 +1,2 @@
+import type { LongTermMemoryRepository, LongTermMemoryRepositorySnapshot } from "../../long-term-memory/contracts.js";
+export declare function createInMemoryLongTermMemoryRepository(initial?: LongTermMemoryRepositorySnapshot): LongTermMemoryRepository;

package/dist/src/runtime/adapters/long-term-memory/in-memory-repository.js

@@ -0,0 +1,21 @@
+import { advanceMemorySnapshot, createEmptyMemorySnapshot, } from "../../long-term-memory/repository-state.js";
+export function createInMemoryLongTermMemoryRepository(initial = createEmptyMemorySnapshot()) {
+    let snapshot = initial;
+    let writeTail = Promise.resolve();
+    return Object.freeze({
+        async read() {
+            await writeTail;
+            return snapshot;
+        },
+        async update(mutate) {
+            let updated = snapshot;
+            const write = writeTail.then(() => {
+                updated = advanceMemorySnapshot(snapshot, mutate(snapshot));
+                snapshot = updated;
+            });
+            writeTail = write.catch(() => undefined);
+            await write;
+            return updated;
+        },
+    });
+}

package/dist/src/runtime/adapters/long-term-memory/onboarding-config-repository.d.ts

@@ -0,0 +1,5 @@
+import type { LongTermMemoryOnboardingConfigRepository } from "../../long-term-memory/onboarding/contracts.js";
+export declare function createFileLongTermMemoryOnboardingConfigRepository(params: {
+    rootDir: string;
+    configPath?: string;
+}): LongTermMemoryOnboardingConfigRepository;