@adecore/agents 0.0.1 → 0.17.0-beta.2

package/src/async.ts

@@ -0,0 +1,40 @@
+/* The two waits the host does: a pause it can be woken from, and a deadline on somebody else's promise. */
+
+/*
+ * Resolves after `ms`, or at once when the signal is raised. An abort ends the wait rather than
+ * failing it: every caller here is a loop that checks the signal itself on the next turn, and a
+ * rejection would only be caught and thrown away.
+ */
+export function wait(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener(
+            'abort',
+            () => {
+                clearTimeout(timer);
+                resolve();
+            },
+            { once: true }
+        );
+    });
+}
+
+/*
+ * The promise, or `message` when it takes longer than `ms`. The timer is cleared either way, so a
+ * call that answers at once does not hold the process for the rest of its deadline.
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(message)), ms);
+        promise.then(
+            (value) => {
+                clearTimeout(timer);
+                resolve(value);
+            },
+            (e: unknown) => {
+                clearTimeout(timer);
+                reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        );
+    });
+}

package/src/chat/attachment-store.ts

@@ -0,0 +1,108 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { attachmentImageMime, type ChatAttachment, type ChatAttachmentUpload } from '@adecore/agent-contracts';
+
+// The extension the file gets on disk when its name does not carry a usable one.
+const EXTENSIONS: Record<string, string> = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/svg+xml': 'svg',
+    'application/pdf': 'pdf',
+    'application/json': 'json',
+    'text/csv': 'csv',
+    'text/markdown': 'md',
+    'text/plain': 'txt'
+};
+
+const SAFE_EXTENSION = /^[A-Za-z0-9]{1,8}$/;
+
+/* What the file is called on disk: the id, plus an extension the agent's tools can recognize. */
+export function extensionFor(name: string, mime: string): string {
+    const own = extname(name).slice(1).toLowerCase();
+    if (SAFE_EXTENSION.test(own)) {
+        return own;
+    }
+    const known = EXTENSIONS[mime.toLowerCase()];
+    if (known) {
+        return known;
+    }
+    const subtype = mime.split('/')[1]?.replace(/\+.*$/, '') ?? '';
+    return SAFE_EXTENSION.test(subtype) ? subtype.toLowerCase() : 'bin';
+}
+
+/*
+ * The files people attach to a message, under `<home>/attachments/<chatId>`. The thread keeps
+ * only what a row needs (name, mime, size, path); the bytes stay on disk, so a thread with a video
+ * in it is still a small JSON file.
+ */
+export class AttachmentStore {
+    readonly dir: string;
+
+    constructor(home: string) {
+        this.dir = join(home, 'attachments');
+    }
+
+    /* Writes one upload and answers the metadata the thread stores. */
+    async save(chatId: string, upload: ChatAttachmentUpload): Promise<ChatAttachment> {
+        const bytes = Buffer.from(upload.data, 'base64');
+        const mime = attachmentImageMime(upload) ?? upload.mime;
+        const id = randomBytes(8).toString('hex');
+        const folder = this.folder(chatId);
+        await mkdir(folder, { recursive: true, mode: 0o700 });
+        const path = join(folder, `${id}.${extensionFor(upload.name, mime)}`);
+        await writeFile(path, bytes, { mode: 0o600 });
+        return { id, name: upload.name, mime, size: bytes.byteLength, path };
+    }
+
+    /* Everything a chat attached; used when the chat itself is deleted. */
+    async removeAll(chatId: string): Promise<void> {
+        await rm(this.folder(chatId), { recursive: true, force: true });
+    }
+
+    private folder(chatId: string): string {
+        return join(this.dir, encodeURIComponent(chatId));
+    }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// What an attachment looked like before the files moved out of the thread: the bytes inline.
+function isInline(value: unknown): value is { name: string; mediaType: string; data: string } {
+    return isRecord(value) && typeof value.name === 'string' && typeof value.mediaType === 'string' && typeof value.data === 'string';
+}
+
+/*
+ * Writes out the images a thread still carries inline and answers the record with metadata in their
+ * place, or null when there was nothing to do. Old records are migrated on the read that opens the
+ * chat, before the schema sees them, because the schema no longer knows the inline shape.
+ */
+export async function migrateInlineAttachments(chatId: string, record: unknown, store: AttachmentStore): Promise<unknown | null> {
+    const items = isRecord(record) && Array.isArray(record.items) ? record.items : null;
+    if (!items) {
+        return null;
+    }
+    let migrated = false;
+    const next = await Promise.all(
+        items.map(async (item) => {
+            if (!isRecord(item) || !Array.isArray(item.attachments) || !item.attachments.some(isInline)) {
+                return item;
+            }
+            const attachments = await Promise.all(
+                item.attachments.map(async (attachment) => {
+                    if (!isInline(attachment)) {
+                        return attachment;
+                    }
+                    migrated = true;
+                    return await store.save(chatId, { name: attachment.name, mime: attachment.mediaType, data: attachment.data });
+                })
+            );
+            return { ...item, attachments };
+        })
+    );
+    return migrated ? { ...(record as Record<string, unknown>), items: next } : null;
+}

package/src/chat/backend.ts

@@ -0,0 +1,199 @@
+import type {
+    ChatAttachment,
+    ChatFileChange,
+    ChatQuestion,
+    ChatSkill,
+    ChatSubagentUsage,
+    ChatTurnLimit,
+    ChatWorkflow,
+    ModelSelection,
+    RuntimeMode
+} from '@adecore/agent-contracts';
+import type { LimitsUpdate } from '../usage/limits/normalize.ts';
+import type { SpawnChatProcess } from './chat-process.ts';
+
+/*
+ * The seam between one chat and one CLI. A backend owns a process and the protocol it speaks; it
+ * reports what happened as `BackendEvent`s and never touches the thread, its item ids or its turns.
+ * Everything a provider does differently lives behind this interface.
+ */
+
+export interface BackendLaunch {
+    // A test points this at a fake CLI.
+    command: string[];
+    cwd: string;
+    env: Record<string, string>;
+    selection: ModelSelection;
+    // The selected model as a person reads it, for the errors a backend puts in the thread.
+    modelName: string;
+    runtimeMode: RuntimeMode;
+    // The CLI's own session or thread id to continue, if the chat has one.
+    resume: string | null;
+    // How often this chat started a CLI; a protocol that numbers its own requests from zero
+    // needs it to keep the ids of one process apart from those of the one before.
+    generation: number;
+    // What the agent is told once, at the start of a process: a system prompt, or a new thread's developer instructions.
+    instructions: string | null;
+    // The part of it a resumed thread has to hear again in front of its next prompt, for a CLI that ignores new
+    // instructions on a resume; null when there is nothing to repeat.
+    resumeNote: string | null;
+    // Folders outside `cwd` the agent may reach without asking. Claude Code takes them as `--add-dir`; Codex's
+    // sandbox reads the whole disk already and keeps writes to the workspace, so it needs nothing.
+    folders?: readonly string[];
+    // How the CLI is started; a test runs a fake in the same process, everything else spawns it.
+    spawn?: SpawnChatProcess;
+}
+
+export interface TurnInput {
+    promptId?: string;
+    text: string;
+    // What the session wants in front of the text (a context change); the backend places it after its own prefix.
+    preamble: string | null;
+    attachments: ChatAttachment[];
+    // The paths the person picked with `@`; they also sit in the text, for a CLI that expands them itself.
+    mentions: string[];
+    // The skills the person picked with `$`; they also sit in the text, for a CLI that expands them itself.
+    skills: string[];
+}
+
+export type ApprovalDecision = 'allow' | 'allow-always' | 'deny';
+
+/*
+ * What a CLI told us, in one vocabulary. `ref` is the backend's own key for an item (a tool use id,
+ * a message id plus block ordinal, a native item id); the projector turns it into a thread item id.
+ */
+export type BackendEvent =
+    | { type: 'turn.accepted'; promptId: string }
+    // `title` is the name the CLI already has for the thread, as a resumed Codex thread carries it.
+    | {
+          type: 'session';
+          agentSessionId: string | null;
+          model: string | null;
+          slashCommands?: string[];
+          skills?: string[];
+          title?: string | null;
+          effectiveRuntimeMode?: RuntimeMode;
+          permissionMode?: string;
+      }
+    // The CLI renamed its thread, for a protocol that says so.
+    | { type: 'title'; title: string }
+    | { type: 'permissions'; permissionMode: string; effectiveRuntimeMode?: RuntimeMode }
+    | { type: 'text.delta'; ref: string; text: string }
+    // `parentRef` is set for text a subagent wrote; it belongs to that agent's row, not to the thread.
+    | { type: 'text.done'; ref: string; text: string; parentRef?: string | null }
+    // What the model thought before it answered; consecutive blocks become one thinking item.
+    | { type: 'thinking.delta'; ref: string; text: string }
+    | { type: 'thinking.done'; ref: string; text: string }
+    | { type: 'tool.started'; ref: string; name: string; input: unknown; parentRef: string | null; changes?: ChatFileChange[] }
+    | { type: 'tool.progress'; ref: string; startedAt: number | null; description: string | null }
+    | { type: 'tool.output'; ref: string; text: string }
+    | { type: 'tool.done'; ref: string; output: string | null; state: 'done' | 'error'; changes?: ChatFileChange[] }
+    | {
+          type: 'approval.requested';
+          requestId: string;
+          // The tool call the request is about, when the CLI names one.
+          ref: string | null;
+          toolName: string;
+          input: unknown;
+          description: string | null;
+          canAllowAlways: boolean;
+          // A child request may arrive after the main turn ended, without starting another one.
+          background?: boolean;
+          allowAlways?: { label: string; description: string };
+      }
+    // `async` marks a question the CLI goes on past, which is the only kind the person may dismiss.
+    | { type: 'question.requested'; requestId: string; questions: ChatQuestion[]; async?: boolean; background?: boolean }
+    // The CLI took an approval or a question back; the person no longer has to answer it.
+    | { type: 'request.withdrawn'; requestId: string }
+    // An agent the agent delegated to, keyed by the call that spawned it. `background` says whether
+    // it runs beside the turn; a foreground one settles with the call's own result instead.
+    | {
+          type: 'task.started';
+          ref: string;
+          description: string | null;
+          subagentType: string | null;
+          prompt: string | null;
+          background: boolean;
+          // The CLI's own id for the agent, which stays the same when a message wakes it again under another call.
+          taskId?: string | null;
+          // The thread a CLI that keeps one per agent opened for it, which is where its whole conversation is read.
+          threadId?: string | null;
+          // How many agents deep it runs: 1 for one the chat's own agent opened, 2 for one a subagent opened.
+          depth?: number;
+          resumed?: boolean;
+      }
+    | { type: 'task.progress'; ref: string; taskId?: string | null; summary: string | null; lastTool: string | null; usage: ChatSubagentUsage | null }
+    // The model a subagent's own answers came from, which its call may not have named.
+    | { type: 'task.model'; ref: string; model: string }
+    // A task the CLI runs beside the turn (a background subagent, a backgrounded command) settled.
+    // Its summary is what the CLI says came of it, and what a turn the CLI opens on its own is about.
+    | {
+          type: 'task.done';
+          ref: string | null;
+          taskId?: string | null;
+          summary: string | null;
+          ok: boolean;
+          usage?: ChatSubagentUsage | null;
+          outputFile?: string | null;
+      }
+    // What the workflow a Workflow call launched runs now, whole; a null name leaves the one said before.
+    | { type: 'workflow.progress'; ref: string; workflow: ChatWorkflow }
+    // A command or a monitor the CLI keeps running beside its turns. `ref` is the call that started it, when a
+    // call did; `monitor` is set when the CLI's own frame already says it is one.
+    | { type: 'background.started'; taskId: string; ref: string | null; monitor: boolean; description: string | null }
+    | { type: 'background.ended'; taskId: string }
+    | { type: 'usage'; contextTokens?: number; contextWindow?: number; costUsd?: number }
+    // What the CLI said in passing about the plan it runs on; it belongs to the machine, not the chat.
+    | { type: 'limits'; update: LimitsUpdate }
+    | { type: 'compaction'; preTokens: number | null }
+    | { type: 'model'; model: string }
+    | { type: 'note'; level: 'info' | 'warning' | 'error'; text: string }
+    // `native` is the CLI's own name for where the turn ended, which a fork of the chat is cut at.
+    | {
+          type: 'turn.done';
+          promptId?: string;
+          state: 'done' | 'aborted' | 'error';
+          costUsd: number;
+          error?: string;
+          native?: { turnId?: string; lastUuid?: string };
+          limit?: ChatTurnLimit;
+      }
+    // The CLI could not be reached or refused the request; the turn ends and the chat needs a new one.
+    | { type: 'failed'; message: string; processAlive?: boolean }
+    // `stderr` is the last of what the CLI wrote there, for an exit with an error code.
+    | { type: 'exit'; exitCode: number | null; stderr?: string };
+
+export interface BackendHost {
+    onEvent(event: BackendEvent): void;
+}
+
+export interface ChatBackend {
+    readonly acknowledgesTurns?: boolean;
+    readonly running: boolean;
+    // The CLI's process while it runs, so the process panel can put its tree under the node.
+    readonly pid: number | null;
+    // Starts the process if it has not started; resolves once the CLI can take a turn.
+    start(): Promise<void>;
+    sendTurn(input: TurnInput): void;
+    compact(): void;
+    interrupt(): void;
+    // False when nothing waits under that id, so the caller can answer the client with an error.
+    respondApproval(requestId: string, decision: ApprovalDecision, message?: string): boolean;
+    respondQuestion(requestId: string, answers: Record<string, string>): boolean;
+    // Ends one command or monitor the CLI runs beside its turns, for a protocol that can name one.
+    stopTask?(taskId: string): void;
+    // Turns down a request the CLI still holds after a person stopped the turn, for a protocol that leaves one open past it.
+    declineRequest?(requestId: string, message: string): boolean;
+    // Drops an asynchronous question without telling the CLI, for a protocol that keeps one waiting.
+    dismissRequest?(requestId: string): boolean;
+    // Gives the CLI's own thread the name the chat got, for a protocol whose thread list and resume carry one.
+    setTitle?(title: string): void;
+    // What this CLI would run right now, for a protocol that answers the question itself.
+    listSkills?(): Promise<ChatSkill[]>;
+    // One page of a thread the CLI keeps, asked of this running process rather than of a new one.
+    listThreadItems?(params: { threadId: string; cursor?: string; limit: number; sortDirection: 'asc' | 'desc' }): Promise<unknown>;
+    // Closes the input and lets the CLI leave on its own; `dispose` ends it.
+    stop(): void;
+    // Ends the CLI and everything it started; settles once it exited or was sent the SIGKILL.
+    dispose(): Promise<void>;
+}

package/src/chat/background-work.ts

@@ -0,0 +1,42 @@
+import type { AgentKind, ChatBackgroundTask, ChatItem, ChatSubagentItem, ChatToolItem } from '@adecore/agent-contracts';
+
+export type BackgroundWork = ChatSubagentItem | ChatToolItem;
+
+/*
+ * Work a chat's CLI goes on with after the turn that started it ended: a subagent it runs in the
+ * background (Claude's `run_in_background`, every agent Codex spawns) and a Claude workflow, whose call
+ * answers at launch. A command or a monitor sent to the background is not work of this kind but a
+ * `ChatBackgroundTask` in the chat's info, held to `BACKGROUND_COMMAND_LIMIT_MS`; a row the host drew for
+ * work it delegated itself (origin `ruimte` on the wire) is that work's own.
+ */
+export function isBackgroundWork(item: ChatItem): item is BackgroundWork {
+    return (item.kind === 'subagent' && item.background && item.origin !== 'ruimte') || (item.kind === 'tool' && item.name === 'Workflow');
+}
+
+export function runsInBackground(item: BackgroundWork): boolean {
+    return item.kind === 'subagent' ? item.status === 'running' : item.state === 'running';
+}
+
+export function runningInBackground(items: readonly ChatItem[]): BackgroundWork[] {
+    return items.filter((item): item is BackgroundWork => isBackgroundWork(item) && runsInBackground(item));
+}
+
+/*
+ * How long a command or a monitor still running in the background holds a child's task once nothing
+ * else does, since a dev server never ends. Subagents and workflows have no such limit.
+ */
+export const BACKGROUND_COMMAND_LIMIT_MS = 30 * 60_000;
+
+export function commandLabel(task: ChatBackgroundTask): string {
+    return task.command ?? (task.description === '' ? task.id : task.description);
+}
+
+/*
+ * Whether the CLI opens a turn of its own once its background work ended, to tell what came of it.
+ * Claude Code 2.1.282 does after every task notification, a command's included; a command a subagent
+ * started first takes that subagent up again, which then notifies the main agent. Codex 0.156.1
+ * reports a spawned agent completed and opens nothing.
+ */
+export function reportsOnBackgroundWork(provider: AgentKind): boolean {
+    return provider === 'claude';
+}

package/src/chat/bookmark-store.ts

@@ -0,0 +1,166 @@
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CHAT_BOOKMARK_LIMITS, ChatBookmarksSchema, clipText, type ChatBookmark } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import { isNotFound, writeAtomic } from '../fs.ts';
+import { KeyedSerializer } from '../serializer.ts';
+import { ChatError } from './errors.ts';
+
+const SUFFIX = '.bookmarks.json';
+
+const BookmarkFileSchema = z.object({ version: z.literal(1), bookmarks: ChatBookmarksSchema });
+
+export function bookmarkFileName(chatId: string): string {
+    return `${encodeURIComponent(chatId)}${SUFFIX}`;
+}
+
+/* Whether a name in the chats folder is a bookmarks file, which the chat records beside it must not count as a chat. */
+export function isBookmarkFileName(name: string): boolean {
+    return name.endsWith(SUFFIX);
+}
+
+export type BookmarkListener = (chatId: string, bookmarks: ChatBookmark[]) => void;
+
+/* A name as it is kept: trimmed, and none at all when nothing is left. */
+function cleanName(name: string | undefined): string | undefined {
+    const trimmed = name === undefined ? undefined : clipText(name.trim(), CHAT_BOOKMARK_LIMITS.name);
+    return trimmed === undefined || trimmed === '' ? undefined : trimmed;
+}
+
+function named(bookmark: ChatBookmark, name: string | undefined): ChatBookmark {
+    const { name: _previous, ...rest } = bookmark;
+    return name === undefined ? rest : { ...rest, name };
+}
+
+/*
+ * The bookmarks of every chat, one file per chat beside its record under `<home>/chats`, apart
+ * from the record, which is rewritten on every turn. One chain per chat puts two clients' clicks
+ * after each other, and every change is told to the listeners from inside that chain, so the lists
+ * go out in the order they were written.
+ */
+export class BookmarkStore {
+    readonly dir: string;
+    private readonly writes = new KeyedSerializer();
+    private readonly listeners = new Set<BookmarkListener>();
+
+    constructor(home: string) {
+        this.dir = join(home, 'chats');
+    }
+
+    listen(listener: BookmarkListener): () => void {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+
+    /* The bookmarks of one chat in the order they were made, after any write still on its way. */
+    read(chatId: string): Promise<ChatBookmark[]> {
+        return this.writes.run(chatId, () => this.readFile(chatId));
+    }
+
+    /* Marks a message; one that already has a bookmark keeps it, and takes the name when one is given. */
+    add(chatId: string, input: { itemId: string; excerpt: string; name?: string }, now: number): Promise<ChatBookmark[]> {
+        return this.change(chatId, (bookmarks) => {
+            const name = cleanName(input.name);
+            const existing = bookmarks.find((bookmark) => bookmark.itemId === input.itemId);
+            if (existing) {
+                return name === undefined ? null : bookmarks.map((bookmark) => (bookmark === existing ? named(bookmark, name) : bookmark));
+            }
+            if (bookmarks.length >= CHAT_BOOKMARK_LIMITS.perChat) {
+                throw new ChatError('too-many-bookmarks', `This chat already keeps ${CHAT_BOOKMARK_LIMITS.perChat} bookmarks; remove one first`);
+            }
+            const excerpt = clipText(input.excerpt, CHAT_BOOKMARK_LIMITS.excerpt);
+            return [...bookmarks, named({ itemId: input.itemId, excerpt, createdAt: now }, name)];
+        });
+    }
+
+    rename(chatId: string, itemId: string, name: string): Promise<ChatBookmark[]> {
+        return this.change(chatId, (bookmarks) => {
+            if (!bookmarks.some((bookmark) => bookmark.itemId === itemId)) {
+                throw new ChatError('bookmark-not-found', `This chat has no bookmark on ${itemId}`);
+            }
+            return bookmarks.map((bookmark) => (bookmark.itemId === itemId ? named(bookmark, cleanName(name)) : bookmark));
+        });
+    }
+
+    remove(chatId: string, itemId: string): Promise<ChatBookmark[]> {
+        return this.change(chatId, (bookmarks) =>
+            bookmarks.some((bookmark) => bookmark.itemId === itemId) ? bookmarks.filter((bookmark) => bookmark.itemId !== itemId) : null
+        );
+    }
+
+    /* The bookmarks go with the chat or with a clear of it. A file that no longer parses goes too, since nothing could show it again. */
+    removeChat(chatId: string): Promise<void> {
+        return this.writes.run(chatId, async () => {
+            const had = await this.readFile(chatId).then(
+                (bookmarks) => bookmarks.length > 0,
+                () => true
+            );
+            await rm(join(this.dir, bookmarkFileName(chatId)), { force: true });
+            if (had) {
+                this.tell(chatId, []);
+            }
+        });
+    }
+
+    /* A fork keeps the bookmarks on the messages it copied, which are the ones up to where it was cut. */
+    async copyChat(fromChatId: string, toChatId: string, keep: (itemId: string) => boolean): Promise<void> {
+        const kept = (await this.read(fromChatId)).filter((bookmark) => keep(bookmark.itemId));
+        if (kept.length === 0) {
+            return;
+        }
+        await this.writes.run(toChatId, async () => {
+            await this.writeFile(toChatId, kept);
+            this.tell(toChatId, kept);
+        });
+    }
+
+    /* One read, one decision and one write in the chat's chain; a change that returns null changes nothing and tells nobody. */
+    private change(chatId: string, decide: (bookmarks: ChatBookmark[]) => ChatBookmark[] | null): Promise<ChatBookmark[]> {
+        return this.writes.run(chatId, async () => {
+            const bookmarks = await this.readFile(chatId);
+            const next = decide(bookmarks);
+            if (next === null) {
+                return bookmarks;
+            }
+            await this.writeFile(chatId, next);
+            this.tell(chatId, next);
+            return next;
+        });
+    }
+
+    private tell(chatId: string, bookmarks: ChatBookmark[]): void {
+        for (const listener of this.listeners) {
+            listener(chatId, bookmarks);
+        }
+    }
+
+    private async readFile(chatId: string): Promise<ChatBookmark[]> {
+        let raw: string;
+        try {
+            raw = await readFile(join(this.dir, bookmarkFileName(chatId)), 'utf8');
+        } catch (e) {
+            if (isNotFound(e)) {
+                return [];
+            }
+            throw e;
+        }
+        // A file that does not parse is refused rather than read as empty, which the next write would make true.
+        const parsed = BookmarkFileSchema.safeParse(JSON.parse(raw));
+        if (!parsed.success) {
+            throw new Error(`The bookmarks file of chat ${chatId} is not valid: ${parsed.error.issues[0]?.message ?? 'unknown problem'}`);
+        }
+        return parsed.data.bookmarks;
+    }
+
+    private async writeFile(chatId: string, bookmarks: readonly ChatBookmark[]): Promise<void> {
+        const path = join(this.dir, bookmarkFileName(chatId));
+        if (bookmarks.length === 0) {
+            await rm(path, { force: true });
+            return;
+        }
+        await mkdir(this.dir, { recursive: true, mode: 0o700 });
+        await writeAtomic(path, JSON.stringify({ version: 1, bookmarks }));
+    }
+}