repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(bak): add S3 session archive

6b73505f32257190da87d7d9f46f0260fcc05c9e

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (12)

CHANGELOG.md

Modified
2 2 # Changelog
4 4 ## Unreleased
6 +- Add Bak for asynchronous S3-compatible session backup and conflict-safe restore, with host initialization, manual backup, refresh, and status commands, durable retries, safe partial-failure handling, and no filesystem or network work during Pi startup
6 7 - Make Ultra workflow `report` values available to agents as well as human-facing output, while preserving full-output references for oversized reports
7 8 - Refine Ultra model-tier selection around residual judgement: default to `small`, use `tiny` only for deterministic work, decompose when context or risk benefits exceed handoff cost, and block rather than compensate for missing facts or authority
8 9 - Add `ctrl+enter` to park editor text as a note, and `ctrl+alt+enter` to open a notes picker and send the selected note

extensions/bak/README.md

Added
new file mode 100644
1 +# bak
3 +Asynchronous Pi session backup and restore through S3-compatible object storage.
5 +## Setup
7 +Create a private bucket and credentials limited to object read/write access for that bucket.
9 +Set:
11 +```text
12 +PI_BAK_S3_ENDPOINT=https://<account>.eu.r2.cloudflarestorage.com
13 +PI_BAK_S3_ACCESS_KEY_ID=...
14 +PI_BAK_S3_SECRET_ACCESS_KEY=...
15 +```
17 +Optional settings:
19 +```text
20 +PI_BAK_S3_BUCKET=pi-bak
21 +PI_BAK_S3_REGION=auto
22 +```
24 +Initialize each host once:
26 +```text
27 +/bak init <alias>
28 +```
30 +Host identity lives in platform-local state outside Pi configuration.
31 +Catalog autocomplete uses a platform-local stale-while-refresh cache.
32 +Bak performs no filesystem or network work during Pi session startup; initialization starts lazily on first command or backup-triggering event.
34 +## Commands
36 +```text
37 +/bak
38 +/bak init <alias>
39 +/bak backup
40 +/bak restore <alias>/<session-id-prefix> [path]
41 +/bak restore all [path]
42 +/bak refresh
43 +/bak status
44 +```
46 +`/bak backup` uploads all locally discoverable sessions.
47 +Completed agent runs back up their current session asynchronously.
48 +Restore defaults to the current configured session directory and never silently overwrites differing files.

extensions/bak/__tests__/archive.test.ts

Added
new file mode 100644
1 +import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
2 +import { tmpdir } from "node:os";
3 +import { join } from "node:path";
4 +import type { SessionInfo } from "@earendil-works/pi-coding-agent";
5 +import { afterEach, describe, expect, it } from "vitest";
6 +import { BakArchive, PartialBackupError } from "../archive.js";
7 +import { S3Store } from "../s3.js";
9 +class MemoryS3 {
10 + readonly objects = new Map<string, { body: Uint8Array; etag: string }>();
11 + failCatalogPuts = 0;
12 + readonly failSessionIds = new Set<string>();
13 + private revision = 0;
15 + fetch = async (url: string, init?: RequestInit): Promise<Response> => {
16 + const key = decodeURIComponent(
17 + new URL(url).pathname.slice("/pi-bak/".length),
18 + );
19 + const current = this.objects.get(key);
20 + if (init?.method === "PUT") {
21 + if ([...this.failSessionIds].some((id) => key.endsWith(`/${id}.jsonl`)))
22 + return new Response("rejected", { status: 400 });
23 + if (key === "catalog/hosts.json" && this.failCatalogPuts-- > 0)
24 + throw new Error("network down");
25 + const headers = new Headers(init.headers);
26 + if (headers.get("if-none-match") === "*" && current)
27 + return new Response("precondition", { status: 412 });
28 + if (headers.has("if-match") && headers.get("if-match") !== current?.etag)
29 + return new Response("precondition", { status: 412 });
30 + const body = new Uint8Array(
31 + await new Response(init.body as BodyInit | null).arrayBuffer(),
32 + );
33 + const etag = `"${++this.revision}"`;
34 + this.objects.set(key, { body, etag });
35 + return new Response(null, { status: 200, headers: { etag } });
36 + }
37 + if (!current) return new Response("missing", { status: 404 });
38 + return new Response(current.body, {
39 + status: 200,
40 + headers: { etag: current.etag },
41 + });
42 + };
45 +function info(path: string, id: string): SessionInfo {
46 + return {
47 + path,
48 + id,
49 + cwd: "/work/project",
50 + name: "Archive test",
51 + created: new Date("2026-01-02T03:04:05.000Z"),
52 + modified: new Date("2026-01-02T03:05:05.000Z"),
53 + messageCount: 2,
54 + firstMessage: "hello",
55 + allMessagesText: "hello world",
56 + };
59 +describe("bak archive", () => {
60 + let directory: string | undefined;
62 + afterEach(async () => {
63 + if (directory) await rm(directory, { recursive: true, force: true });
64 + directory = undefined;
65 + });
67 + it("initializes, backs up, refreshes, and restores without listing", async () => {
68 + directory = await mkdtemp(join(tmpdir(), "pi-bak-"));
69 + const memory = new MemoryS3();
70 + const store = new S3Store(
71 + {
72 + endpoint: "https://example.invalid",
73 + bucket: "pi-bak",
74 + region: "auto",
75 + accessKeyId: "id",
76 + secretAccessKey: "secret",
77 + },
78 + memory as never,
79 + );
80 + const archive = new BakArchive(store, {
81 + identity: join(directory, "state", "identity.json"),
82 + cache: join(directory, "cache", "catalog.json"),
83 + pendingDir: join(directory, "state", "pending"),
84 + });
85 + const identity = await archive.init("work-laptop");
86 + const sessionPath = join(directory, "session.jsonl");
87 + const sessionId = "12345678-1234-1234-1234-123456789abc";
88 + const body = `${JSON.stringify({
89 + type: "session",
90 + version: 3,
91 + id: sessionId,
92 + timestamp: "2026-01-02T03:04:05.000Z",
93 + cwd: "/work/project",
94 + })}\n${JSON.stringify({ type: "message", id: "a", parentId: null, timestamp: "2026-01-02T03:04:06.000Z", message: { role: "user", content: "hello" } })}\n`;
95 + await writeFile(sessionPath, body);
97 + await expect(
98 + archive.backup([info(sessionPath, sessionId)]),
99 + ).resolves.toEqual({
100 + uploaded: 1,
101 + indexed: 1,
102 + });
103 + const catalog = await archive.refresh();
104 + expect(catalog.indexes[0]).toMatchObject({
105 + hostId: identity.hostId,
106 + alias: "work-laptop",
107 + sessions: [{ id: sessionId, name: "Archive test" }],
108 + });
110 + const destination = join(directory, "restore");
111 + await expect(
112 + archive.restore(catalog.indexes[0]?.sessions ?? [], destination),
113 + ).resolves.toEqual({ restored: 1, skipped: 0, conflicts: 0 });
114 + await expect(
115 + archive.restore(catalog.indexes[0]?.sessions ?? [], destination),
116 + ).resolves.toEqual({ restored: 0, skipped: 1, conflicts: 0 });
117 + const restored = join(
118 + destination,
119 + `2026-01-02T03-04-05-000Z_${sessionId}.jsonl`,
120 + );
121 + expect(await readFile(restored, "utf8")).toBe(body);
122 + const divergent = `${body}${JSON.stringify({ type: "message", id: "b", parentId: "a", timestamp: "2026-01-02T03:04:07.000Z", message: { role: "assistant", content: [] } })}\n`;
123 + await writeFile(restored, divergent);
124 + await expect(
125 + archive.restore(catalog.indexes[0]?.sessions ?? [], destination),
126 + ).resolves.toEqual({ restored: 0, skipped: 0, conflicts: 1 });
127 + expect(await readFile(restored, "utf8")).toBe(divergent);
128 + expect([...memory.objects.keys()].sort()).toEqual([
129 + "catalog/hosts.json",
130 + `hosts/${identity.hostId}.json`,
131 + `sessions/${identity.hostId}/${sessionId}.jsonl`,
132 + ]);
133 + });
135 + it("rejects unsafe remote session records", async () => {
136 + directory = await mkdtemp(join(tmpdir(), "pi-bak-"));
137 + const memory = new MemoryS3();
138 + const archive = new BakArchive(
139 + new S3Store(
141 + endpoint: "https://example.invalid",
142 + bucket: "pi-bak",
143 + region: "auto",
144 + accessKeyId: "id",
145 + secretAccessKey: "secret",
146 + },
147 + memory as never,
148 + ),
150 + identity: join(directory, "state", "identity.json"),
151 + cache: join(directory, "cache", "catalog.json"),
152 + pendingDir: join(directory, "state", "pending"),
153 + },
154 + );
156 + await expect(
157 + archive.restore(
160 + id: "x/../../escaped",
161 + key: "sessions/host/x/../../escaped.jsonl",
162 + cwd: "/work",
163 + created: "2026-01-02T03:04:05.000Z",
164 + },
165 + ],
166 + join(directory, "restore"),
167 + ),
168 + ).rejects.toThrow("Invalid archived session record");
169 + });
171 + it("rejects a session whose first line is blank", async () => {
172 + directory = await mkdtemp(join(tmpdir(), "pi-bak-"));
173 + const memory = new MemoryS3();
174 + const store = new S3Store(
176 + endpoint: "https://example.invalid",
177 + bucket: "pi-bak",
178 + region: "auto",
179 + accessKeyId: "id",
180 + secretAccessKey: "secret",
181 + },
182 + memory as never,
183 + );
184 + const archive = new BakArchive(store, {
185 + identity: join(directory, "state", "identity.json"),
186 + cache: join(directory, "cache", "catalog.json"),
187 + pendingDir: join(directory, "state", "pending"),
188 + });
189 + await archive.init("work-laptop");
190 + const sessionId = "12345678-1234-1234-1234-123456789abc";
191 + const sessionPath = join(directory, "blank-header.jsonl");
192 + await writeFile(
193 + sessionPath,
194 + `\n${JSON.stringify({
195 + type: "session",
196 + version: 3,
197 + id: sessionId,
198 + timestamp: "2026-01-02T03:04:05.000Z",
199 + cwd: "/work/project",
200 + })}\n`,
201 + );
203 + await expect(
204 + archive.backup([info(sessionPath, sessionId)]),
205 + ).rejects.toThrow("Invalid Pi session header");
206 + });
208 + it("merges concurrent host-index updates", async () => {
209 + directory = await mkdtemp(join(tmpdir(), "pi-bak-"));
210 + const memory = new MemoryS3();
211 + const archive = new BakArchive(
212 + new S3Store(
214 + endpoint: "https://example.invalid",
215 + bucket: "pi-bak",
216 + region: "auto",
217 + accessKeyId: "id",
218 + secretAccessKey: "secret",
219 + },
220 + memory as never,
221 + ),
223 + identity: join(directory, "state", "identity.json"),
224 + cache: join(directory, "cache", "catalog.json"),
225 + pendingDir: join(directory, "state", "pending"),
226 + },
227 + );
228 + await archive.init("work-laptop");
229 + const ids = [
230 + "12345678-1234-1234-1234-123456789abc",
231 + "abcdefab-1234-1234-1234-123456789abc",
232 + ];
233 + const paths = await Promise.all(
234 + ids.map(async (id, index) => {
235 + const path = join(directory, `${index}.jsonl`);
236 + await writeFile(
237 + path,
238 + `${JSON.stringify({ type: "session", version: 3, id, timestamp: `2026-01-02T03:04:0${index}.000Z`, cwd: "/work/project" })}\n`,
239 + );
240 + return path;
241 + }),
242 + );
244 + await Promise.all([
245 + archive.backup([info(paths[0] ?? "", ids[0] ?? "")]),
246 + archive.backup([info(paths[1] ?? "", ids[1] ?? "")]),
247 + ]);
249 + const catalog = await archive.refresh();
250 + expect(
251 + catalog.indexes[0]?.sessions.map((session) => session.id).sort(),
252 + ).toEqual([...ids].sort());
253 + });
255 + it("drains failed batches and indexes successful transfers", async () => {
256 + directory = await mkdtemp(join(tmpdir(), "pi-bak-"));
257 + const memory = new MemoryS3();
258 + const archive = new BakArchive(
259 + new S3Store(
261 + endpoint: "https://example.invalid",
262 + bucket: "pi-bak",
263 + region: "auto",
264 + accessKeyId: "id",
265 + secretAccessKey: "secret",
266 + },
267 + memory as never,
268 + ),
270 + identity: join(directory, "state", "identity.json"),
271 + cache: join(directory, "cache", "catalog.json"),
272 + pendingDir: join(directory, "state", "pending"),
273 + },
274 + );
275 + await archive.init("work-laptop");
276 + const ids = Array.from(
277 + { length: 12 },
278 + (_, index) =>
279 + `00000000-0000-0000-0000-${String(index).padStart(12, "0")}`,
280 + );
281 + for (const id of ids.slice(0, 6)) memory.failSessionIds.add(id);
282 + const infos = await Promise.all(
283 + ids.map(async (id, index) => {
284 + const path = join(directory, `batch-${index}.jsonl`);
285 + await writeFile(
286 + path,
287 + `${JSON.stringify({ type: "session", version: 3, id, timestamp: "2026-01-02T03:04:05.000Z", cwd: "/work/project" })}\n`,
288 + );
289 + return info(path, id);
290 + }),
291 + );
293 + let failure: unknown;
294 + try {
295 + await archive.backup(infos);
296 + } catch (error) {
297 + failure = error;
299 + expect(failure).toBeInstanceOf(PartialBackupError);
300 + expect((failure as PartialBackupError).succeededPaths).toHaveLength(6);
301 + const indexed = (await archive.refresh()).indexes[0]?.sessions ?? [];
302 + expect(indexed).toHaveLength(6);
303 + expect(
304 + indexed.every((record) => !memory.failSessionIds.has(record.id)),
305 + ).toBe(true);
306 + });
308 + it("reuses durable identity after interrupted initialization", async () => {
309 + directory = await mkdtemp(join(tmpdir(), "pi-bak-"));
310 + const memory = new MemoryS3();
311 + memory.failCatalogPuts = 3;
312 + const archive = new BakArchive(
313 + new S3Store(
315 + endpoint: "https://example.invalid",
316 + bucket: "pi-bak",
317 + region: "auto",
318 + accessKeyId: "id",
319 + secretAccessKey: "secret",
320 + },
321 + memory as never,
322 + ),
324 + identity: join(directory, "state", "identity.json"),
325 + cache: join(directory, "cache", "catalog.json"),
326 + pendingDir: join(directory, "state", "pending"),
327 + },
328 + );
330 + await expect(archive.init("work-laptop")).rejects.toThrow("network down");
331 + const pendingIdentity = await archive.identity();
332 + expect(pendingIdentity).toBeDefined();
333 + const sessionId = "12345678-1234-1234-1234-123456789abc";
334 + const sessionPath = join(directory, "recovered.jsonl");
335 + await writeFile(
336 + sessionPath,
337 + `${JSON.stringify({ type: "session", version: 3, id: sessionId, timestamp: "2026-01-02T03:04:05.000Z", cwd: "/work/project" })}\n`,
338 + );
339 + await expect(
340 + archive.backup([info(sessionPath, sessionId)]),
341 + ).resolves.toMatchObject({ uploaded: 1 });
342 + expect((await archive.refresh()).catalog.hosts).toEqual([pendingIdentity]);
343 + });
345 + it("rejects duplicate aliases through the shared catalog", async () => {
346 + directory = await mkdtemp(join(tmpdir(), "pi-bak-"));
347 + const memory = new MemoryS3();
348 + const config = {
349 + endpoint: "https://example.invalid",
350 + bucket: "pi-bak",
351 + region: "auto",
352 + accessKeyId: "id",
353 + secretAccessKey: "secret",
354 + };
355 + const first = new BakArchive(new S3Store(config, memory as never), {
356 + identity: join(directory, "one", "identity.json"),
357 + cache: join(directory, "one", "catalog.json"),
358 + pendingDir: join(directory, "one", "pending"),
359 + });
360 + const second = new BakArchive(new S3Store(config, memory as never), {
361 + identity: join(directory, "two", "identity.json"),
362 + cache: join(directory, "two", "catalog.json"),
363 + pendingDir: join(directory, "two", "pending"),
364 + });
365 + await first.init("work-laptop");
366 + await expect(second.init("work-laptop")).rejects.toThrow(
367 + "Alias already exists: work-laptop",
368 + );
369 + });
370 +});

extensions/bak/__tests__/harness.test.ts

Added
new file mode 100644
1 +import path from "node:path";
2 +import { afterEach, describe, expect, it, vi } from "vitest";
3 +import { createTestSession, type TestSession } from "../../../test/harness.js";
5 +describe("bak pi-test-harness", () => {
6 + let session: TestSession | undefined;
8 + afterEach(() => {
9 + session?.dispose();
10 + session = undefined;
11 + vi.unstubAllEnvs();
12 + vi.unstubAllGlobals();
13 + });
15 + it("performs no remote work during session startup", async () => {
16 + vi.stubEnv("PI_BAK_S3_ENDPOINT", "https://example.invalid");
17 + vi.stubEnv("PI_BAK_S3_ACCESS_KEY_ID", "id");
18 + vi.stubEnv("PI_BAK_S3_SECRET_ACCESS_KEY", "secret");
19 + const fetch = vi.fn();
20 + vi.stubGlobal("fetch", fetch);
21 + const extensionPath = path.resolve(import.meta.dirname, "../index.ts");
23 + session = await createTestSession({ extensions: [extensionPath] });
24 + await new Promise((resolve) => setTimeout(resolve, 20));
26 + expect(fetch).not.toHaveBeenCalled();
27 + });
29 + it("loads through Pi and registers the bak command", async () => {
30 + const extensionPath = path.resolve(import.meta.dirname, "../index.ts");
31 + session = await createTestSession({ extensions: [extensionPath] });
32 + const extension = session.session.extensionRunner.extensions[0];
33 + const command = extension?.commands.get("bak");
35 + expect(session.session.extensionRunner.extensions).toHaveLength(1);
36 + expect(command).toBeDefined();
37 + expect(command?.getArgumentCompletions?.("res")).toEqual([
38 + { value: "restore", label: "restore" },
39 + ]);
40 + });
41 +});

extensions/bak/__tests__/state.test.ts

Added
new file mode 100644
1 +import { mkdtemp, rm } from "node:fs/promises";
2 +import { tmpdir } from "node:os";
3 +import { join } from "node:path";
4 +import { afterEach, describe, expect, it } from "vitest";
5 +import {
6 + clearPending,
7 + markPending,
8 + normalizeAlias,
9 + readPending,
10 + statePaths,
11 +} from "../state.js";
13 +let directory: string | undefined;
15 +afterEach(async () => {
16 + if (directory) await rm(directory, { recursive: true, force: true });
17 + directory = undefined;
18 +});
20 +describe("bak state", () => {
21 + it("keeps machine identity outside Pi configuration", () => {
22 + expect(
23 + statePaths(
24 + { XDG_STATE_HOME: "/state", XDG_CACHE_HOME: "/cache" },
25 + "linux",
26 + "/home/me",
27 + ),
28 + ).toEqual({
29 + identity: "/state/pi/bak/identity.json",
30 + cache: "/cache/pi/bak/catalog.json",
31 + pendingDir: "/state/pi/bak/pending",
32 + });
33 + });
35 + it("keeps concurrent pending markers independent", async () => {
36 + directory = await mkdtemp(join(tmpdir(), "pi-bak-state-"));
37 + const pendingDir = join(directory, "pending");
38 + const [first, second, newer] = await Promise.all([
39 + markPending(pendingDir, "/sessions/a.jsonl"),
40 + markPending(pendingDir, "/sessions/b.jsonl"),
41 + markPending(pendingDir, "/sessions/a.jsonl"),
42 + ]);
43 + expect(
44 + (await readPending(pendingDir)).map((entry) => entry.path).sort(),
45 + ).toEqual(["/sessions/a.jsonl", "/sessions/a.jsonl", "/sessions/b.jsonl"]);
46 + await clearPending(pendingDir, first.id);
47 + expect(
48 + (await readPending(pendingDir)).map((entry) => entry.id).sort(),
49 + ).toEqual([second.id, newer.id].sort());
50 + });
52 + it("normalizes safe human aliases", () => {
53 + expect(normalizeAlias(" Work-Laptop ")).toBe("work-laptop");
54 + expect(normalizeAlias("bad alias")).toBeUndefined();
55 + expect(normalizeAlias("-bad")).toBeUndefined();
56 + });
57 +});

extensions/bak/archive.ts

Added
new file mode 100644
1 +import { randomUUID } from "node:crypto";
2 +import {
3 + link,
4 + mkdir,
5 + open,
6 + readdir,
7 + readFile,
8 + unlink,
9 + writeFile,
10 +} from "node:fs/promises";
11 +import { basename, dirname, join, resolve } from "node:path";
12 +import type { SessionInfo } from "@earendil-works/pi-coding-agent";
13 +import { S3Error, type S3Store } from "./s3.js";
14 +import {
15 + atomicWriteJson,
16 + type CatalogCache,
17 + type HostCatalog,
18 + type HostIdentity,
19 + type HostIndex,
20 + newIdentity,
21 + normalizeAlias,
22 + readJson,
23 + type SessionRecord,
24 + type StatePaths,
25 + writeJsonExclusive,
26 +} from "./state.js";
28 +const HOST_CATALOG_KEY = "catalog/hosts.json";
29 +const CATALOG_VERSION = 1;
30 +const CAS_ATTEMPTS = 5;
31 +const SESSION_HEADER_LIMIT = 64 * 1024;
32 +const TRANSFER_CONCURRENCY = 6;
33 +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
34 +const decoder = new TextDecoder();
36 +export interface BackupResult {
37 + uploaded: number;
38 + indexed: number;
41 +export interface RestoreResult {
42 + restored: number;
43 + skipped: number;
44 + conflicts: number;
47 +interface SessionSnapshot {
48 + record: SessionRecord;
49 + body: Uint8Array;
50 + sourcePath: string;
53 +export class PartialBackupError extends Error {
54 + constructor(
55 + message: string,
56 + readonly succeededPaths: string[],
57 + options?: ErrorOptions,
58 + ) {
59 + super(message, options);
60 + this.name = "PartialBackupError";
61 + }
64 +class AliasCollisionError extends Error {}
66 +async function forEachConcurrent<T>(
67 + items: T[],
68 + worker: (item: T) => Promise<void>,
69 +): Promise<{ failed: false } | { failed: true; error: unknown }> {
70 + let cursor = 0;
71 + let failed = false;
72 + let failure: unknown;
73 + const run = async () => {
74 + while (cursor < items.length) {
75 + const item = items[cursor++];
76 + if (item === undefined) continue;
77 + try {
78 + await worker(item);
79 + } catch (error) {
80 + if (!failed) failure = error;
81 + failed = true;
82 + }
83 + }
84 + };
85 + await Promise.all(
86 + Array.from({ length: Math.min(TRANSFER_CONCURRENCY, items.length) }, run),
87 + );
88 + return failed ? { failed: true, error: failure } : { failed: false };
91 +function hostIndexKey(hostId: string): string {
92 + return `hosts/${hostId}.json`;
95 +function sessionKey(hostId: string, sessionId: string): string {
96 + return `sessions/${hostId}/${sessionId}.jsonl`;
99 +function parseJson<T>(body: Uint8Array, key: string): T {
100 + try {
101 + return JSON.parse(decoder.decode(body)) as T;
102 + } catch {
103 + throw new Error(`Invalid JSON in ${key}`);
107 +function emptyCatalog(): HostCatalog {
108 + return { version: CATALOG_VERSION, hosts: [] };
111 +function emptyIndex(identity: HostIdentity): HostIndex {
112 + return { version: CATALOG_VERSION, ...identity, sessions: [] };
115 +function validIdentity(value: unknown): value is HostIdentity {
116 + if (!value || typeof value !== "object") return false;
117 + const identity = value as Partial<HostIdentity>;
118 + return (
119 + typeof identity.hostId === "string" &&
120 + UUID.test(identity.hostId) &&
121 + typeof identity.alias === "string" &&
122 + normalizeAlias(identity.alias) === identity.alias
123 + );
126 +function validTimestamp(value: unknown): value is string {
127 + if (typeof value !== "string") return false;
128 + try {
129 + return new Date(value).toISOString() === value;
130 + } catch {
131 + return false;
135 +function validRecord(value: unknown, hostId: string): value is SessionRecord {
136 + if (!value || typeof value !== "object") return false;
137 + const record = value as Partial<SessionRecord>;
138 + return (
139 + typeof record.id === "string" &&
140 + UUID.test(record.id) &&
141 + record.key === sessionKey(hostId, record.id) &&
142 + (record.name === undefined || typeof record.name === "string") &&
143 + typeof record.cwd === "string" &&
144 + validTimestamp(record.created)
145 + );
148 +function parseCatalog(body: Uint8Array): HostCatalog {
149 + const catalog = parseJson<HostCatalog>(body, HOST_CATALOG_KEY);
150 + if (
151 + catalog.version !== CATALOG_VERSION ||
152 + !Array.isArray(catalog.hosts) ||
153 + !catalog.hosts.every(validIdentity)
155 + throw new Error(`Unsupported ${HOST_CATALOG_KEY}`);
156 + const ids = new Set(catalog.hosts.map((host) => host.hostId));
157 + const aliases = new Set(catalog.hosts.map((host) => host.alias));
158 + if (
159 + ids.size !== catalog.hosts.length ||
160 + aliases.size !== catalog.hosts.length
162 + throw new Error(`Duplicate host in ${HOST_CATALOG_KEY}`);
163 + return catalog;
166 +function parseIndex(
167 + body: Uint8Array,
168 + key: string,
169 + expected: HostIdentity,
170 +): HostIndex {
171 + const index = parseJson<HostIndex>(body, key);
172 + if (
173 + index.version !== CATALOG_VERSION ||
174 + index.hostId !== expected.hostId ||
175 + index.alias !== expected.alias ||
176 + !Array.isArray(index.sessions) ||
177 + !index.sessions.every((record) => validRecord(record, expected.hostId))
179 + throw new Error(`Unsupported ${key}`);
180 + if (
181 + new Set(index.sessions.map((record) => record.id)).size !==
182 + index.sessions.length
184 + throw new Error(`Duplicate session in ${key}`);
185 + return index;
188 +function stableIndex(index: HostIndex): string {
189 + return JSON.stringify({
190 + ...index,
191 + sessions: [...index.sessions].sort((a, b) => a.id.localeCompare(b.id)),
192 + });
195 +function validateSessionBody(
196 + body: Uint8Array,
197 + expectedId?: string,
198 +): { id: string; timestamp: string; cwd: string } {
199 + const text = decoder.decode(body);
200 + const lines = text.split("\n");
201 + if (lines.at(-1) === "") lines.pop();
202 + if (lines.length === 0) throw new Error("Empty Pi session");
203 + type SessionHeaderCandidate = {
204 + type?: unknown;
205 + id?: unknown;
206 + timestamp?: unknown;
207 + cwd?: unknown;
208 + };
209 + let header: SessionHeaderCandidate | undefined;
210 + for (let index = 0; index < lines.length; index++) {
211 + const line = lines[index];
212 + if (!line?.trim()) continue;
213 + let entry: unknown;
214 + try {
215 + entry = JSON.parse(line);
216 + } catch {
217 + throw new Error(`Invalid Pi session JSONL at line ${index + 1}`);
219 + if (
220 + !entry ||
221 + typeof entry !== "object" ||
222 + typeof (entry as { type?: unknown }).type !== "string"
224 + throw new Error(`Invalid Pi session JSONL at line ${index + 1}`);
225 + if (index === 0) header = entry as SessionHeaderCandidate;
227 + if (
228 + header?.type !== "session" ||
229 + typeof header.id !== "string" ||
230 + !UUID.test(header.id) ||
231 + (expectedId !== undefined && header.id !== expectedId) ||
232 + !validTimestamp(header.timestamp) ||
233 + typeof header.cwd !== "string"
235 + throw new Error("Invalid Pi session header");
236 + return { id: header.id, timestamp: header.timestamp, cwd: header.cwd };
239 +export async function sessionInfoFromPath(path: string): Promise<SessionInfo> {
240 + const body = new Uint8Array(await readFile(path));
241 + const header = validateSessionBody(body);
242 + let name: string | undefined;
243 + for (const line of decoder.decode(body).split("\n")) {
244 + if (!line.trim()) continue;
245 + const entry = JSON.parse(line) as { type?: unknown; name?: unknown };
246 + if (entry.type === "session_info" && typeof entry.name === "string")
247 + name = entry.name;
249 + return {
250 + name,
251 + path,
252 + id: header.id,
253 + cwd: header.cwd,
254 + created: new Date(header.timestamp),
255 + modified: new Date(),
256 + messageCount: 0,
257 + firstMessage: "",
258 + allMessagesText: "",
259 + };
262 +async function snapshot(
263 + info: SessionInfo,
264 + hostId: string,
265 +): Promise<SessionSnapshot> {
266 + const body = new Uint8Array(await readFile(info.path));
267 + const header = validateSessionBody(body, info.id);
268 + return {
269 + body,
270 + sourcePath: info.path,
271 + record: {
272 + id: header.id,
273 + key: sessionKey(hostId, header.id),
274 + ...(info.name ? { name: info.name } : {}),
275 + cwd: header.cwd,
276 + created: header.timestamp,
277 + },
278 + };
281 +function sameBytes(left: Uint8Array, right: Uint8Array): boolean {
282 + return (
283 + left.byteLength === right.byteLength &&
284 + left.every((value, index) => value === right[index])
285 + );
288 +function startsWithBytes(value: Uint8Array, prefix: Uint8Array): boolean {
289 + return (
290 + value.byteLength >= prefix.byteLength &&
291 + prefix.every((byte, index) => value[index] === byte)
292 + );
295 +async function sameFile(path: string, body: Uint8Array): Promise<boolean> {
296 + try {
297 + const local = await readFile(path);
298 + return local.byteLength === body.byteLength && local.equals(body);
299 + } catch (error) {
300 + if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
301 + throw error;
305 +async function publishNoReplace(
306 + path: string,
307 + body: Uint8Array,
308 +): Promise<boolean> {
309 + await mkdir(dirname(path), { recursive: true, mode: 0o700 });
310 + const temporary = join(
311 + dirname(path),
312 + `.${basename(path)}.${randomUUID()}.tmp`,
313 + );
314 + try {
315 + await writeFile(temporary, body, { mode: 0o600, flag: "wx" });
316 + try {
317 + await link(temporary, path);
318 + return true;
319 + } catch (error) {
320 + if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
321 + throw error;
323 + } finally {
324 + await unlink(temporary).catch(() => undefined);
328 +function restoredFilename(record: SessionRecord): string {
329 + const timestamp = record.created.replace(/[:.]/g, "-");
330 + return `${timestamp}_${record.id}.jsonl`;
333 +async function sessionIdFromFile(path: string): Promise<string | undefined> {
334 + let handle: Awaited<ReturnType<typeof open>> | undefined;
335 + try {
336 + handle = await open(path, "r");
337 + const buffer = Buffer.allocUnsafe(SESSION_HEADER_LIMIT);
338 + const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
339 + const newline = buffer.subarray(0, bytesRead).indexOf(10);
340 + if (newline < 0) return undefined;
341 + const header = JSON.parse(buffer.subarray(0, newline).toString("utf8")) as {
342 + type?: unknown;
343 + id?: unknown;
344 + };
345 + return header.type === "session" && typeof header.id === "string"
346 + ? header.id
347 + : undefined;
348 + } catch {
349 + return undefined;
350 + } finally {
351 + await handle?.close();
355 +async function destinationSessions(
356 + directory: string,
357 +): Promise<Map<string, string[]>> {
358 + const sessions = new Map<string, string[]>();
359 + for (const name of await readdir(directory)) {
360 + if (!name.endsWith(".jsonl")) continue;
361 + const path = join(directory, name);
362 + const id = await sessionIdFromFile(path);
363 + if (!id) continue;
364 + const paths = sessions.get(id) ?? [];
365 + paths.push(path);
366 + sessions.set(id, paths);
368 + return sessions;
371 +export class BakArchive {
372 + private initializedHostId?: string;
374 + constructor(
375 + private readonly store: S3Store,
376 + private readonly paths: StatePaths,
377 + ) {}
379 + async identity(): Promise<HostIdentity | undefined> {
380 + const value = await readJson<unknown>(this.paths.identity);
381 + if (value === undefined) return undefined;
382 + if (!validIdentity(value)) throw new Error("Invalid bak identity file");
383 + return value;
386 + async cachedCatalog(): Promise<CatalogCache | undefined> {
387 + return readJson<CatalogCache>(this.paths.cache);
390 + private async remoteCatalog(signal?: AbortSignal): Promise<{
391 + catalog: HostCatalog;
392 + etag?: string;
393 + exists: boolean;
394 + }> {
395 + const object = await this.store.get(HOST_CATALOG_KEY, { signal });
396 + if (!object) return { catalog: emptyCatalog(), exists: false };
397 + if (!object.etag)
398 + throw new Error(`Missing ETag for existing ${HOST_CATALOG_KEY}`);
399 + return {
400 + catalog: parseCatalog(object.body),
401 + etag: object.etag,
402 + exists: true,
403 + };
406 + private async register(
407 + identity: HostIdentity,
408 + signal?: AbortSignal,
409 + ): Promise<void> {
410 + for (let attempt = 0; attempt < CAS_ATTEMPTS; attempt++) {
411 + const remote = await this.remoteCatalog(signal);
412 + const collision = remote.catalog.hosts.find(
413 + (host) =>
414 + host.alias === identity.alias && host.hostId !== identity.hostId,
415 + );
416 + if (collision)
417 + throw new AliasCollisionError(
418 + `Alias already exists: ${identity.alias}`,
419 + );
420 + const registered = remote.catalog.hosts.find(
421 + (host) => host.hostId === identity.hostId,
422 + );
423 + if (registered?.alias === identity.alias) return;
424 + const hosts = remote.catalog.hosts.filter(
425 + (host) => host.hostId !== identity.hostId,
426 + );
427 + hosts.push(identity);
428 + hosts.sort((a, b) => a.alias.localeCompare(b.alias));
429 + try {
430 + await this.store.put(
431 + HOST_CATALOG_KEY,
432 + `${JSON.stringify({ version: CATALOG_VERSION, hosts })}\n`,
434 + contentType: "application/json",
435 + ...(remote.exists
436 + ? { ifMatch: remote.etag }
437 + : { ifNoneMatch: "*" }),
438 + signal,
439 + },
440 + );
441 + return;
442 + } catch (error) {
443 + if (!(error instanceof S3Error) || error.status !== 412) throw error;
446 + throw new Error("Host catalog changed repeatedly; retry /bak init");
449 + async ensureInitialized(
450 + identity: HostIdentity,
451 + signal?: AbortSignal,
452 + ): Promise<void> {
453 + if (this.initializedHostId === identity.hostId) return;
454 + await this.register(identity, signal);
455 + const key = hostIndexKey(identity.hostId);
456 + const indexObject = await this.store.get(key, { signal });
457 + if (!indexObject) {
458 + try {
459 + await this.store.put(key, `${stableIndex(emptyIndex(identity))}\n`, {
460 + contentType: "application/json",
461 + ifNoneMatch: "*",
462 + signal,
463 + });
464 + } catch (error) {
465 + if (!(error instanceof S3Error) || error.status !== 412) throw error;
467 + } else {
468 + parseIndex(indexObject.body, key, identity);
470 + this.initializedHostId = identity.hostId;
473 + async init(aliasInput: string, signal?: AbortSignal): Promise<HostIdentity> {
474 + const alias = normalizeAlias(aliasInput);
475 + if (!alias)
476 + throw new Error(
477 + "Alias must use 1-64 lowercase letters, digits, ., _, or -",
478 + );
479 + let identity = await this.identity();
480 + if (identity && identity.alias !== alias)
481 + throw new Error(`Already initialized as ${identity.alias}`);
482 + let created = false;
483 + if (!identity) {
484 + const candidate = newIdentity(alias);
485 + created = await writeJsonExclusive(this.paths.identity, candidate);
486 + identity = created ? candidate : await this.identity();
487 + if (!identity) throw new Error("Could not create bak identity");
488 + if (identity.alias !== alias)
489 + throw new Error(`Already initialized as ${identity.alias}`);
491 + try {
492 + await this.ensureInitialized(identity, signal);
493 + return identity;
494 + } catch (error) {
495 + if (created && error instanceof AliasCollisionError)
496 + await unlink(this.paths.identity).catch(() => undefined);
497 + throw error;
501 + async refresh(signal?: AbortSignal): Promise<CatalogCache> {
502 + const { catalog } = await this.remoteCatalog(signal);
503 + const indexes = (
504 + await Promise.all(
505 + catalog.hosts.map(async (host) => {
506 + const key = hostIndexKey(host.hostId);
507 + const object = await this.store.get(key, { signal });
508 + if (!object) return emptyIndex(host);
509 + return parseIndex(object.body, key, host);
510 + }),
512 + ).sort((a, b) => a.alias.localeCompare(b.alias));
513 + const cache = {
514 + refreshedAt: new Date().toISOString(),
515 + catalog,
516 + indexes,
517 + };
518 + await atomicWriteJson(this.paths.cache, cache);
519 + return cache;
522 + private async putSession(
523 + snapshot: SessionSnapshot,
524 + signal?: AbortSignal,
525 + ): Promise<void> {
526 + for (let attempt = 0; attempt < CAS_ATTEMPTS; attempt++) {
527 + const current = await this.store.get(snapshot.record.key, { signal });
528 + if (current) {
529 + validateSessionBody(current.body, snapshot.record.id);
530 + if (sameBytes(current.body, snapshot.body)) return;
531 + if (startsWithBytes(current.body, snapshot.body)) return;
532 + if (!startsWithBytes(snapshot.body, current.body))
533 + throw new Error(`Archived session diverged: ${snapshot.record.id}`);
534 + if (!current.etag)
535 + throw new Error(`Missing ETag for existing ${snapshot.record.key}`);
537 + try {
538 + await this.store.put(snapshot.record.key, snapshot.body, {
539 + contentType: "application/x-ndjson",
540 + ...(current ? { ifMatch: current.etag } : { ifNoneMatch: "*" }),
541 + signal,
542 + });
543 + return;
544 + } catch (error) {
545 + if (!(error instanceof S3Error) || error.status !== 412) throw error;
548 + throw new Error(`Session changed repeatedly: ${snapshot.record.id}`);
551 + async backup(
552 + infos: SessionInfo[],
553 + onProgress?: (done: number, total: number) => void,
554 + signal?: AbortSignal,
555 + ): Promise<BackupResult> {
556 + const identity = await this.identity();
557 + if (!identity) throw new Error("Run /bak init <alias> first");
558 + await this.ensureInitialized(identity, signal);
559 + const snapshots: SessionSnapshot[] = [];
560 + let done = 0;
561 + const transferError = await forEachConcurrent(infos, async (info) => {
562 + signal?.throwIfAborted();
563 + const next = await snapshot(info, identity.hostId);
564 + await this.putSession(next, signal);
565 + snapshots.push(next);
566 + done++;
567 + onProgress?.(done, infos.length);
568 + });
569 + const key = hostIndexKey(identity.hostId);
570 + let indexed: number | undefined;
571 + for (let attempt = 0; attempt < CAS_ATTEMPTS; attempt++) {
572 + signal?.throwIfAborted();
573 + const currentObject = await this.store.get(key, { signal });
574 + if (currentObject && !currentObject.etag)
575 + throw new Error(`Missing ETag for existing ${key}`);
576 + const current = currentObject
577 + ? parseIndex(currentObject.body, key, identity)
578 + : emptyIndex(identity);
579 + const records = new Map(
580 + current.sessions.map((record) => [record.id, record]),
581 + );
582 + for (const item of snapshots) {
583 + const previous = records.get(item.record.id);
584 + records.set(item.record.id, {
585 + ...item.record,
586 + name: item.record.name ?? previous?.name,
587 + });
589 + const index: HostIndex = {
590 + version: CATALOG_VERSION,
591 + ...identity,
592 + sessions: [...records.values()],
593 + };
594 + if (stableIndex(index) === stableIndex(current)) {
595 + indexed = index.sessions.length;
596 + break;
598 + try {
599 + await this.store.put(key, `${stableIndex(index)}\n`, {
600 + contentType: "application/json",
601 + ...(currentObject
602 + ? { ifMatch: currentObject.etag }
603 + : { ifNoneMatch: "*" }),
604 + signal,
605 + });
606 + indexed = index.sessions.length;
607 + break;
608 + } catch (error) {
609 + if (!(error instanceof S3Error) || error.status !== 412) throw error;
612 + if (indexed === undefined)
613 + throw new Error("Host index changed repeatedly; retry backup");
614 + if (transferError.failed) {
615 + const message =
616 + transferError.error instanceof Error
617 + ? transferError.error.message
618 + : String(transferError.error);
619 + throw new PartialBackupError(
620 + message,
621 + snapshots.map((item) => item.sourcePath),
622 + { cause: transferError.error },
623 + );
625 + return { uploaded: done, indexed };
628 + async restore(
629 + records: SessionRecord[],
630 + destination: string,
631 + onProgress?: (done: number, total: number) => void,
632 + signal?: AbortSignal,
633 + ): Promise<RestoreResult> {
634 + const targetDirectory = resolve(destination);
635 + await mkdir(targetDirectory, { recursive: true, mode: 0o700 });
636 + const localSessions = await destinationSessions(targetDirectory);
637 + const result = { restored: 0, skipped: 0, conflicts: 0 };
638 + const groups = new Map<string, SessionRecord[]>();
639 + for (const record of records) {
640 + const group = groups.get(record.id) ?? [];
641 + group.push(record);
642 + groups.set(record.id, group);
644 + let done = 0;
645 + const transferError = await forEachConcurrent(
646 + [...groups.values()],
647 + async (group) => {
648 + for (const record of group) {
649 + signal?.throwIfAborted();
650 + const hostId = record.key.split("/")[1];
651 + if (!hostId || !validRecord(record, hostId))
652 + throw new Error(`Invalid archived session record: ${record.id}`);
653 + const object = await this.store.get(record.key, { signal });
654 + if (!object) throw new Error(`Missing archive object: ${record.key}`);
655 + validateSessionBody(object.body, record.id);
656 + const existing = localSessions.get(record.id) ?? [];
657 + if (existing.length > 0) {
658 + if (
660 + await Promise.all(
661 + existing.map((path) => sameFile(path, object.body)),
663 + ).some(Boolean)
665 + result.skipped++;
666 + else result.conflicts++;
667 + } else {
668 + const path = resolve(targetDirectory, restoredFilename(record));
669 + if (dirname(path) !== targetDirectory)
670 + throw new Error(`Unsafe restore path for ${record.id}`);
671 + if (await publishNoReplace(path, object.body)) {
672 + result.restored++;
673 + localSessions.set(record.id, [path]);
674 + } else if (await sameFile(path, object.body)) {
675 + result.skipped++;
676 + localSessions.set(record.id, [path]);
677 + } else result.conflicts++;
679 + done++;
680 + onProgress?.(done, records.length);
682 + },
683 + );
684 + if (transferError.failed) throw transferError.error;
685 + return result;

extensions/bak/index.ts

Added
new file mode 100644
1 +import type {
2 + ExtensionAPI,
3 + ExtensionContext,
4 + SessionInfo,
5 +} from "@earendil-works/pi-coding-agent";
6 +import { SessionManager } from "@earendil-works/pi-coding-agent";
7 +import {
8 + BakArchive,
9 + PartialBackupError,
10 + sessionInfoFromPath,
11 +} from "./archive.js";
12 +import { S3Store, s3Config } from "./s3.js";
13 +import {
14 + type CatalogCache,
15 + clearPending,
16 + type HostIdentity,
17 + markPending,
18 + type PendingEntry,
19 + readPending,
20 + type SessionRecord,
21 + statePaths,
22 +} from "./state.js";
24 +const ICON = "󰁯";
25 +const STATUS_KEY = "bak";
26 +const SHUTDOWN_DRAIN_MS = 2_000;
27 +const SUBCOMMANDS = ["init", "backup", "restore", "refresh", "status"];
29 +function currentSession(ctx: ExtensionContext): SessionInfo | undefined {
30 + const path = ctx.sessionManager.getSessionFile();
31 + const header = ctx.sessionManager.getHeader();
32 + if (!path || !header) return undefined;
33 + return {
34 + path,
35 + id: header.id,
36 + cwd: header.cwd,
37 + name: ctx.sessionManager.getSessionName(),
38 + parentSessionPath: header.parentSession,
39 + created: new Date(header.timestamp),
40 + modified: new Date(),
41 + messageCount: ctx.sessionManager
42 + .getEntries()
43 + .filter((entry) => entry.type === "message").length,
44 + firstMessage: "",
45 + allMessagesText: "",
46 + };
49 +function errorText(error: unknown): string {
50 + const text = error instanceof Error ? error.message : String(error);
51 + return text.replace(/\s+/g, " ").trim().slice(0, 240);
54 +function formatAge(timestamp: string | undefined): string {
55 + if (!timestamp) return "never";
56 + const age = Date.now() - new Date(timestamp).getTime();
57 + if (!Number.isFinite(age) || age < 0) return "unknown";
58 + if (age < 60_000) return "now";
59 + if (age < 3_600_000) return `${Math.floor(age / 60_000)}m ago`;
60 + if (age < 86_400_000) return `${Math.floor(age / 3_600_000)}h ago`;
61 + return `${Math.floor(age / 86_400_000)}d ago`;
64 +function destinationArgs(args: string): { target: string; path?: string } {
65 + const match = /^(\S+)(?:\s+(.+))?$/.exec(args.trim());
66 + return { target: match?.[1] ?? "", path: match?.[2]?.trim() || undefined };
69 +function selectRecords(cache: CatalogCache, target: string): SessionRecord[] {
70 + if (target === "all") return cache.indexes.flatMap((index) => index.sessions);
71 + const slash = target.indexOf("/");
72 + const alias = slash >= 0 ? target.slice(0, slash) : undefined;
73 + const prefix = slash >= 0 ? target.slice(slash + 1) : target;
74 + if (!prefix) return [];
75 + return cache.indexes
76 + .filter((index) => !alias || index.alias === alias)
77 + .flatMap((index) => index.sessions)
78 + .filter((record) => record.id.startsWith(prefix));
81 +function uniquePrefix(id: string, ids: string[]): string {
82 + for (let length = Math.min(8, id.length); length < id.length; length++) {
83 + const prefix = id.slice(0, length);
84 + if (
85 + !ids.some((candidate) => candidate !== id && candidate.startsWith(prefix))
86 + )
87 + return prefix;
88 + }
89 + return id;
92 +async function localSessions(ctx: ExtensionContext): Promise<SessionInfo[]> {
93 + const manager = ctx.sessionManager as typeof ctx.sessionManager & {
94 + usesDefaultSessionDir?: () => boolean;
95 + };
96 + return manager.usesDefaultSessionDir?.()
97 + ? SessionManager.listAll()
98 + : SessionManager.listAll(ctx.sessionManager.getSessionDir());
101 +export default function bakExtension(pi: ExtensionAPI) {
102 + const resolved = s3Config();
103 + const paths = statePaths();
104 + const archive = resolved.config
105 + ? new BakArchive(new S3Store(resolved.config), paths)
106 + : undefined;
107 + let identity: HostIdentity | undefined;
108 + let cache: CatalogCache | undefined;
109 + let lastBackupAt: string | undefined;
110 + let lastError: string | undefined;
111 + let warnedFailure = false;
112 + let warnedSetup = false;
113 + let lifecycle = 0;
114 + let loadedLifecycle = 0;
115 + let backgroundLifecycle = 0;
116 + let serial: Promise<void> = Promise.resolve();
117 + let readiness: Promise<void> = Promise.resolve();
118 + let lifecycleController: AbortController | undefined;
119 + let pending = new Map<string, PendingEntry>();
121 + const notify = (
122 + ctx: ExtensionContext,
123 + message: string,
124 + level: "info" | "warning" | "error" = "info",
125 + ) => {
126 + if (ctx.hasUI) ctx.ui.notify(`bak: ${message}`, level);
127 + };
129 + const runSerial = <T>(operation: () => Promise<T>): Promise<T> => {
130 + const result = serial.then(operation, operation);
131 + serial = result.then(
132 + () => undefined,
133 + () => undefined,
134 + );
135 + return result;
136 + };
138 + const requireArchive = (ctx: ExtensionContext): BakArchive | undefined => {
139 + if (archive) return archive;
140 + notify(ctx, `disabled; missing ${resolved.missing.join(", ")}`, "error");
141 + return undefined;
142 + };
144 + const setProgress = (ctx: ExtensionContext, text?: string) => {
145 + if (ctx.hasUI)
146 + ctx.ui.setStatus(
147 + STATUS_KEY,
148 + text ? ctx.ui.theme.fg("dim", `${ICON} ${text}`) : undefined,
149 + );
150 + };
152 + const addPending = async (path: string): Promise<PendingEntry> => {
153 + const entry = await markPending(paths.pendingDir, path);
154 + pending.set(entry.id, entry);
155 + return entry;
156 + };
158 + const removePending = async (entries: PendingEntry[]) => {
159 + await Promise.all(
160 + entries.map(async (entry) => {
161 + await clearPending(paths.pendingDir, entry.id);
162 + pending.delete(entry.id);
163 + }),
164 + );
165 + };
167 + const ensureLoaded = (
168 + ctx: ExtensionContext,
169 + epoch = lifecycle,
170 + ): Promise<void> => {
171 + if (!archive || loadedLifecycle === epoch) return readiness;
172 + loadedLifecycle = epoch;
173 + readiness = (async () => {
174 + const [savedIdentity, savedPending] = await Promise.all([
175 + archive.identity(),
176 + readPending(paths.pendingDir),
177 + ]);
178 + let savedCache: CatalogCache | undefined;
179 + try {
180 + savedCache = await archive.cachedCatalog();
181 + } catch {
182 + savedCache = undefined;
184 + if (epoch !== lifecycle) return;
185 + identity = savedIdentity;
186 + cache = savedCache;
187 + pending = new Map(savedPending.map((entry) => [entry.id, entry]));
188 + if (!identity && !warnedSetup) {
189 + notify(ctx, "run /bak init <alias>", "warning");
190 + warnedSetup = true;
192 + })();
193 + return readiness;
194 + };
196 + const refresh = async (
197 + ctx: ExtensionContext,
198 + signal?: AbortSignal,
199 + ): Promise<CatalogCache | undefined> => {
200 + const client = requireArchive(ctx);
201 + if (!client) return undefined;
202 + const next = await client.refresh(signal);
203 + cache = next;
204 + return next;
205 + };
207 + const backupBatch = async (
208 + infos: SessionInfo[],
209 + onProgress?: (done: number, total: number) => void,
210 + replayEntries?: PendingEntry[],
211 + ) => {
212 + if (!archive || infos.length === 0) return { uploaded: 0, indexed: 0 };
213 + await readiness;
214 + if (!replayEntries)
215 + await Promise.all(infos.map((info) => addPending(info.path)));
216 + const paths = new Set(infos.map((info) => info.path));
217 + const covered = (replayEntries ?? [...pending.values()]).filter((entry) =>
218 + paths.has(entry.path),
219 + );
220 + if (!identity) throw new Error("Run /bak init <alias> first");
221 + try {
222 + const result = await archive.backup(
223 + infos,
224 + onProgress,
225 + lifecycleController?.signal,
226 + );
227 + await removePending(covered);
228 + lastBackupAt = new Date().toISOString();
229 + lastError = undefined;
230 + return result;
231 + } catch (error) {
232 + if (error instanceof PartialBackupError) {
233 + const succeeded = new Set(error.succeededPaths);
234 + await removePending(
235 + covered.filter((entry) => succeeded.has(entry.path)),
236 + );
238 + throw error;
240 + };
242 + const startBackground = (ctx: ExtensionContext) => {
243 + const epoch = lifecycle;
244 + if (!archive || backgroundLifecycle === epoch) return;
245 + backgroundLifecycle = epoch;
246 + void ensureLoaded(ctx, epoch)
247 + .then(async () => {
248 + if (!identity || epoch !== lifecycle) return;
249 + try {
250 + await archive.ensureInitialized(
251 + identity,
252 + lifecycleController?.signal,
253 + );
254 + } catch (error) {
255 + if (epoch === lifecycle)
256 + notify(
257 + ctx,
258 + `background init failed: ${errorText(error)}`,
259 + "warning",
260 + );
262 + void refresh(ctx, lifecycleController?.signal).catch((error) => {
263 + if (epoch === lifecycle && !cache)
264 + notify(
265 + ctx,
266 + `catalog refresh failed: ${errorText(error)}`,
267 + "warning",
268 + );
269 + });
270 + await retryPending(epoch);
271 + })
272 + .catch((error) => {
273 + if (epoch === lifecycle)
274 + notify(
275 + ctx,
276 + `background state failed: ${errorText(error)}`,
277 + "warning",
278 + );
279 + });
280 + };
282 + const automaticBackup = (ctx: ExtensionContext) => {
283 + startBackground(ctx);
284 + const info = currentSession(ctx);
285 + if (!archive || !info) return;
286 + const epoch = lifecycle;
287 + void runSerial(async () => {
288 + const statusTimer = setTimeout(() => {
289 + if (epoch === lifecycle) setProgress(ctx, "↑");
290 + }, 300);
291 + try {
292 + await backupBatch([info]);
293 + if (warnedFailure && epoch === lifecycle) {
294 + notify(ctx, "backup recovered");
295 + warnedFailure = false;
297 + } catch (error) {
298 + lastError = errorText(error);
299 + if (!warnedFailure && epoch === lifecycle) {
300 + notify(ctx, `backup failed: ${lastError}; retry pending`, "warning");
301 + warnedFailure = true;
303 + } finally {
304 + clearTimeout(statusTimer);
305 + if (epoch === lifecycle) setProgress(ctx);
307 + });
308 + };
310 + const retryPending = async (epoch: number) => {
311 + if (!archive || pending.size === 0 || epoch !== lifecycle) return;
312 + const replayEntries = [...pending.values()];
313 + const infos: SessionInfo[] = [];
314 + for (const path of new Set(replayEntries.map((entry) => entry.path))) {
315 + try {
316 + infos.push(await sessionInfoFromPath(path));
317 + } catch (error) {
318 + lastError = `pending ${path}: ${errorText(error)}`;
321 + if (infos.length === 0) return;
322 + await runSerial(() => backupBatch(infos, undefined, replayEntries));
323 + };
325 + pi.on("session_start", (_event, ctx) => {
326 + lifecycle++;
327 + lifecycleController?.abort();
328 + lifecycleController = new AbortController();
329 + loadedLifecycle = 0;
330 + backgroundLifecycle = 0;
331 + readiness = Promise.resolve();
332 + identity = undefined;
333 + cache = undefined;
334 + pending = new Map();
335 + if (!archive && !warnedSetup) {
336 + notify(
337 + ctx,
338 + `disabled; missing ${resolved.missing.join(", ")}`,
339 + "warning",
340 + );
341 + warnedSetup = true;
343 + });
345 + pi.on("agent_settled", async (_event, ctx) => automaticBackup(ctx));
346 + pi.on("session_info_changed", async (_event, ctx) => automaticBackup(ctx));
348 + pi.on("session_shutdown", async (_event, ctx) => {
349 + const info = currentSession(ctx);
350 + if (archive && info) {
351 + await addPending(info.path).catch((error) => {
352 + lastError = errorText(error);
353 + });
355 + automaticBackup(ctx);
356 + await Promise.race([
357 + serial,
358 + new Promise((resolve) => setTimeout(resolve, SHUTDOWN_DRAIN_MS)),
359 + ]);
360 + lifecycleController?.abort();
361 + lifecycle++;
362 + setProgress(ctx);
363 + });
365 + pi.registerCommand("bak", {
366 + description: "Back up and restore Pi sessions",
367 + getArgumentCompletions(prefix) {
368 + const normalized = prefix.trimStart();
369 + const restore = /^restore\s+(\S*)$/i.exec(normalized);
370 + if (restore) {
371 + const query = restore[1]?.toLowerCase() ?? "";
372 + const records =
373 + cache?.indexes.flatMap((index) => {
374 + const ids = index.sessions.map((record) => record.id);
375 + return index.sessions.map((record) => {
376 + const prefix = uniquePrefix(record.id, ids);
377 + return {
378 + value: `restore ${index.alias}/${prefix}`,
379 + label: `${index.alias}/${prefix}`,
380 + description: record.name ?? record.cwd,
381 + };
382 + });
383 + }) ?? [];
384 + const items = [
385 + { value: "restore all", label: "all", description: "all sessions" },
386 + ...records,
387 + ].filter((item) => item.label.toLowerCase().startsWith(query));
388 + return items.length > 0 ? items.slice(0, 100) : null;
390 + if (normalized.includes(" ")) return null;
391 + const items = SUBCOMMANDS.filter((command) =>
392 + command.startsWith(normalized.toLowerCase()),
393 + ).map((command) => ({ value: command, label: command }));
394 + return items.length > 0 ? items : null;
395 + },
396 + async handler(args, ctx) {
397 + const trimmed = args.trim();
398 + const [command = "status", ...rest] = trimmed.split(/\s+/);
399 + if (command === "status") {
400 + if (archive)
401 + await ensureLoaded(ctx).catch((error) => {
402 + lastError = errorText(error);
403 + });
404 + const indexed = cache?.indexes.reduce(
405 + (total, index) => total + index.sessions.length,
406 + 0,
407 + );
408 + const state = archive
409 + ? identity
410 + ? "ready"
411 + : "not initialized"
412 + : `disabled; missing ${resolved.missing.join(", ")}`;
413 + notify(
414 + ctx,
416 + identity?.alias,
417 + state,
418 + indexed === undefined ? undefined : `${indexed} indexed`,
419 + `${new Set([...pending.values()].map((entry) => entry.path)).size} pending`,
420 + `last backup ${formatAge(lastBackupAt)}`,
421 + `catalog ${formatAge(cache?.refreshedAt)}`,
422 + lastError ? `error ${lastError}` : undefined,
424 + .filter(Boolean)
425 + .join(" · "),
426 + lastError ? "warning" : "info",
427 + );
428 + return;
430 + const client = requireArchive(ctx);
431 + if (!client) return;
433 + try {
434 + await ensureLoaded(ctx);
435 + if (command === "init") {
436 + if (rest.length !== 1) throw new Error("Usage: /bak init <alias>");
437 + setProgress(ctx, "initializing");
438 + identity = await runSerial(() =>
439 + client.init(rest[0] ?? "", lifecycleController?.signal),
440 + );
441 + cache = await refresh(ctx, lifecycleController?.signal);
442 + warnedSetup = false;
443 + void retryPending(lifecycle).catch((error) => {
444 + lastError = errorText(error);
445 + notify(ctx, `pending retry failed: ${lastError}`, "warning");
446 + });
447 + notify(ctx, `initialized as ${identity.alias}`);
448 + return;
450 + if (command === "refresh") {
451 + if (rest.length > 0) throw new Error("Usage: /bak refresh");
452 + setProgress(ctx, "refreshing");
453 + const next = await runSerial(() =>
454 + client.refresh(lifecycleController?.signal),
455 + );
456 + cache = next;
457 + notify(ctx, `refreshed ${next.indexes.length} host(s)`);
458 + return;
460 + if (command === "backup") {
461 + if (rest.length > 0) throw new Error("Usage: /bak backup");
462 + setProgress(ctx, "scanning");
463 + const infos = await localSessions(ctx);
464 + const result = await runSerial(() =>
465 + backupBatch(infos, (done, total) =>
466 + setProgress(ctx, `↑ ${done}/${total}`),
467 + ),
468 + );
469 + notify(
470 + ctx,
471 + `backed up ${result.uploaded}; ${result.indexed} indexed`,
472 + );
473 + return;
475 + if (command === "restore") {
476 + const parsed = destinationArgs(rest.join(" "));
477 + if (!parsed.target)
478 + throw new Error(
479 + "Usage: /bak restore <alias>/<id-prefix>|all [path]",
480 + );
481 + setProgress(ctx, "refreshing");
482 + const current = await runSerial(() =>
483 + client.refresh(lifecycleController?.signal),
484 + );
485 + cache = current;
486 + const records = selectRecords(current, parsed.target);
487 + if (records.length === 0)
488 + throw new Error(`No session matches ${parsed.target}`);
489 + if (parsed.target !== "all" && records.length !== 1)
490 + throw new Error(`Ambiguous session: ${parsed.target}`);
491 + const result = await runSerial(() =>
492 + client.restore(
493 + records,
494 + parsed.path ?? ctx.sessionManager.getSessionDir(),
495 + (done, total) => setProgress(ctx, `↓ ${done}/${total}`),
496 + lifecycleController?.signal,
497 + ),
498 + );
499 + notify(
500 + ctx,
501 + `restored ${result.restored}, skipped ${result.skipped}, conflicts ${result.conflicts}`,
502 + result.conflicts > 0 ? "warning" : "info",
503 + );
504 + return;
506 + throw new Error(
507 + "Usage: /bak init <alias> | backup | restore <alias>/<id-prefix>|all [path] | refresh | status",
508 + );
509 + } catch (error) {
510 + lastError = errorText(error);
511 + notify(ctx, lastError, "error");
512 + } finally {
513 + setProgress(ctx);
515 + },
516 + });

extensions/bak/mise.toml

Added
new file mode 100644
1 +[tasks.fmt]
2 +description = "Format bak extension"
3 +depends = ["//:install"]
4 +run = [
5 + "biome check --write --config-path ../.. .",
6 + "rumdl fmt --config ../../.rumdl.toml .",
7 + "taplo format --config ../../.taplo.toml mise.toml",
8 +]
10 +[tasks.lint]
11 +description = "Lint bak extension"
12 +depends = ["//:install"]
13 +run = [
14 + "biome ci --config-path ../.. .",
15 + "rumdl check --config ../../.rumdl.toml .",
16 + "taplo format --check --config ../../.taplo.toml mise.toml",
19 +[tasks.test]
20 +description = "Test bak extension"
21 +depends = ["//:install"]
22 +run = [
23 + { task = "//:test", args = ["extensions/bak"] },
26 +[tasks.check]
27 +description = "Check bak extension"
28 +depends = ["//:install"]
29 +run = [
30 + { task = "//:build", args = ["bak"] },

extensions/bak/package.json

Added
new file mode 100644
1 +{
2 + "name": "@bugabinga/pi-ext-bak",
3 + "type": "module",
4 + "main": "index.ts",
5 + "peerDependencies": {
6 + "@earendil-works/pi-coding-agent": "*"
7 + },
8 + "dependencies": {
9 + "aws4fetch": "^1.0.20"
10 + },
11 + "devDependencies": {
12 + "@marcfargas/pi-test-harness": "^0.6.1",
13 + "vitest": "^4.1.9"
14 + },
15 + "license": "MIT",
16 + "description": "Asynchronous Pi session backup and restore for S3-compatible storage.",
17 + "keywords": [
18 + "pi",
19 + "pi-extension",
20 + "backup",
21 + "s3"
22 + ],
23 + "private": true

extensions/bak/s3.ts

Added
new file mode 100644
1 +import { AwsClient } from "aws4fetch";
3 +const ERROR_TEXT_LIMIT = 500;
4 +const MAX_ATTEMPTS = 3;
5 +const REQUEST_TIMEOUT_MS = 30_000;
7 +export interface S3Config {
8 + endpoint: string;
9 + bucket: string;
10 + region: string;
11 + accessKeyId: string;
12 + secretAccessKey: string;
15 +export interface StoredObject {
16 + body: Uint8Array;
17 + etag?: string;
20 +export class S3Error extends Error {
21 + constructor(
22 + readonly status: number,
23 + message: string,
24 + ) {
25 + super(message);
26 + this.name = "S3Error";
27 + }
30 +type SignedClient = Pick<AwsClient, "fetch">;
32 +function objectUrl(config: S3Config, key: string): string {
33 + const endpoint = config.endpoint.replace(/\/+$/, "");
34 + const path = [config.bucket, ...key.split("/")]
35 + .map((part) => encodeURIComponent(part))
36 + .join("/");
37 + return `${endpoint}/${path}`;
40 +function shouldRetry(status: number): boolean {
41 + return status === 408 || status === 429 || status >= 500;
44 +async function boundedError(response: Response): Promise<string> {
45 + const text = (await response.text()).replace(/\s+/g, " ").trim();
46 + return (
47 + text.slice(0, ERROR_TEXT_LIMIT) || response.statusText || "request failed"
48 + );
51 +export class S3Store {
52 + private readonly client: SignedClient;
54 + constructor(
55 + readonly config: S3Config,
56 + client?: SignedClient,
57 + ) {
58 + this.client =
59 + client ??
60 + new AwsClient({
61 + accessKeyId: config.accessKeyId,
62 + secretAccessKey: config.secretAccessKey,
63 + service: "s3",
64 + region: config.region,
65 + retries: 0,
66 + });
67 + }
69 + private async request(
70 + key: string,
71 + init: RequestInit,
72 + signal?: AbortSignal,
73 + ): Promise<Response> {
74 + let lastError: unknown;
75 + for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
76 + signal?.throwIfAborted();
77 + try {
78 + const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
79 + const response = await this.client.fetch(objectUrl(this.config, key), {
80 + ...init,
81 + signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
82 + });
83 + if (!shouldRetry(response.status) || attempt === MAX_ATTEMPTS - 1)
84 + return response;
85 + await response.body?.cancel();
86 + } catch (error) {
87 + lastError = error;
88 + signal?.throwIfAborted();
89 + if (attempt === MAX_ATTEMPTS - 1) throw error;
90 + }
91 + await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
92 + }
93 + throw lastError instanceof Error
94 + ? lastError
95 + : new Error("S3 request failed");
96 + }
98 + async get(
99 + key: string,
100 + options: { signal?: AbortSignal } = {},
101 + ): Promise<StoredObject | undefined> {
102 + const response = await this.request(key, { method: "GET" }, options.signal);
103 + if (response.status === 404) return undefined;
104 + if (!response.ok)
105 + throw new S3Error(response.status, await boundedError(response));
106 + return {
107 + body: new Uint8Array(await response.arrayBuffer()),
108 + etag: response.headers.get("etag") ?? undefined,
109 + };
112 + async put(
113 + key: string,
114 + body: string | Uint8Array,
115 + options: {
116 + contentType?: string;
117 + ifMatch?: string;
118 + ifNoneMatch?: string;
119 + signal?: AbortSignal;
120 + } = {},
121 + ): Promise<string | undefined> {
122 + const headers = new Headers({
123 + "content-type": options.contentType ?? "application/octet-stream",
124 + });
125 + if (options.ifMatch) headers.set("if-match", options.ifMatch);
126 + if (options.ifNoneMatch) headers.set("if-none-match", options.ifNoneMatch);
127 + const requestBody =
128 + typeof body === "string" ? body : Uint8Array.from(body).buffer;
129 + const response = await this.request(
130 + key,
132 + method: "PUT",
133 + headers,
134 + body: requestBody,
135 + },
136 + options.signal,
137 + );
138 + if (!response.ok)
139 + throw new S3Error(response.status, await boundedError(response));
140 + return response.headers.get("etag") ?? undefined;
144 +export function s3Config(env: NodeJS.ProcessEnv = process.env): {
145 + config?: S3Config;
146 + missing: string[];
147 +} {
148 + const required = [
149 + "PI_BAK_S3_ENDPOINT",
150 + "PI_BAK_S3_ACCESS_KEY_ID",
151 + "PI_BAK_S3_SECRET_ACCESS_KEY",
152 + ] as const;
153 + const missing = required.filter((name) => !env[name]?.trim());
154 + if (missing.length > 0) return { missing };
155 + return {
156 + missing: [],
157 + config: {
158 + endpoint: env.PI_BAK_S3_ENDPOINT?.trim() ?? "",
159 + bucket: env.PI_BAK_S3_BUCKET?.trim() || "pi-bak",
160 + region: env.PI_BAK_S3_REGION?.trim() || "auto",
161 + accessKeyId: env.PI_BAK_S3_ACCESS_KEY_ID?.trim() ?? "",
162 + secretAccessKey: env.PI_BAK_S3_SECRET_ACCESS_KEY?.trim() ?? "",
163 + },
164 + };

extensions/bak/state.ts

Added
new file mode 100644
1 +import { randomUUID } from "node:crypto";
2 +import {
3 + mkdir,
4 + readdir,
5 + readFile,
6 + rename,
7 + unlink,
8 + writeFile,
9 +} from "node:fs/promises";
10 +import { homedir } from "node:os";
11 +import { dirname, join, posix, win32 } from "node:path";
13 +export interface HostIdentity {
14 + hostId: string;
15 + alias: string;
18 +export interface SessionRecord {
19 + id: string;
20 + key: string;
21 + name?: string;
22 + cwd: string;
23 + created: string;
26 +export interface HostIndex extends HostIdentity {
27 + version: 1;
28 + sessions: SessionRecord[];
31 +export interface HostCatalog {
32 + version: 1;
33 + hosts: HostIdentity[];
36 +export interface CatalogCache {
37 + refreshedAt: string;
38 + catalog: HostCatalog;
39 + indexes: HostIndex[];
42 +export interface StatePaths {
43 + identity: string;
44 + cache: string;
45 + pendingDir: string;
48 +function platformRoot(
49 + kind: "state" | "cache",
50 + env: NodeJS.ProcessEnv,
51 + platform: NodeJS.Platform,
52 + home: string,
53 +): string {
54 + if (platform === "win32") {
55 + const paths = win32;
56 + const override = kind === "state" ? env.XDG_STATE_HOME : env.XDG_CACHE_HOME;
57 + if (override?.trim()) return paths.join(override, "pi", "bak");
58 + return paths.join(
59 + env.LOCALAPPDATA ?? paths.join(home, "AppData", "Local"),
60 + "pi",
61 + "bak",
62 + kind,
63 + );
64 + }
65 + if (platform === "darwin") {
66 + const override = kind === "state" ? env.XDG_STATE_HOME : env.XDG_CACHE_HOME;
67 + if (override?.trim()) return posix.join(override, "pi", "bak");
68 + return posix.join(
69 + home,
70 + "Library",
71 + kind === "state" ? "Application Support" : "Caches",
72 + "pi",
73 + "bak",
74 + );
75 + }
76 + const override = kind === "state" ? env.XDG_STATE_HOME : env.XDG_CACHE_HOME;
77 + const fallback =
78 + kind === "state"
79 + ? posix.join(home, ".local", "state")
80 + : posix.join(home, ".cache");
81 + return posix.join(override?.trim() || fallback, "pi", "bak");
84 +export function statePaths(
85 + env: NodeJS.ProcessEnv = process.env,
86 + platform: NodeJS.Platform = process.platform,
87 + home = homedir(),
88 +): StatePaths {
89 + const paths = platform === "win32" ? win32 : posix;
90 + const state = platformRoot("state", env, platform, home);
91 + return {
92 + identity: paths.join(state, "identity.json"),
93 + cache: paths.join(
94 + platformRoot("cache", env, platform, home),
95 + "catalog.json",
96 + ),
97 + pendingDir: paths.join(state, "pending"),
98 + };
101 +export function normalizeAlias(value: string): string | undefined {
102 + const alias = value.trim().toLowerCase();
103 + return /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/.test(alias)
104 + ? alias
105 + : undefined;
108 +export function newIdentity(alias: string): HostIdentity {
109 + return { hostId: randomUUID(), alias };
112 +export async function readJson<T>(path: string): Promise<T | undefined> {
113 + try {
114 + return JSON.parse(await readFile(path, "utf8")) as T;
115 + } catch (error) {
116 + if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
117 + throw error;
121 +export interface PendingEntry {
122 + id: string;
123 + path: string;
126 +function pendingMarker(directory: string, id: string): string {
127 + return join(directory, `${id}.json`);
130 +export async function markPending(
131 + directory: string,
132 + path: string,
133 +): Promise<PendingEntry> {
134 + const entry = { id: randomUUID(), path };
135 + await atomicWriteJson(pendingMarker(directory, entry.id), entry);
136 + return entry;
139 +export async function clearPending(
140 + directory: string,
141 + id: string,
142 +): Promise<void> {
143 + await unlink(pendingMarker(directory, id)).catch((error) => {
144 + if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
145 + });
148 +export async function readPending(directory: string): Promise<PendingEntry[]> {
149 + let names: string[];
150 + try {
151 + names = await readdir(directory);
152 + } catch (error) {
153 + if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
154 + throw error;
156 + const entries: PendingEntry[] = [];
157 + for (const name of names) {
158 + if (!name.endsWith(".json")) continue;
159 + const marker = await readJson<{ id?: unknown; path?: unknown }>(
160 + join(directory, name),
161 + );
162 + if (
163 + typeof marker?.id === "string" &&
164 + `${marker.id}.json` === name &&
165 + typeof marker.path === "string"
167 + entries.push({ id: marker.id, path: marker.path });
169 + return entries;
172 +export async function writeJsonExclusive(
173 + path: string,
174 + value: unknown,
175 +): Promise<boolean> {
176 + await mkdir(dirname(path), { recursive: true, mode: 0o700 });
177 + try {
178 + await writeFile(path, `${JSON.stringify(value)}\n`, {
179 + mode: 0o600,
180 + flag: "wx",
181 + });
182 + return true;
183 + } catch (error) {
184 + if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
185 + throw error;
189 +export async function atomicWriteJson(
190 + path: string,
191 + value: unknown,
192 +): Promise<void> {
193 + await mkdir(dirname(path), { recursive: true, mode: 0o700 });
194 + const temporary = join(dirname(path), `.${process.pid}-${randomUUID()}.tmp`);
195 + await writeFile(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600 });
196 + await rename(temporary, path);

package-lock.json

Modified
53 53 "typebox": "*"
56 + "extensions/bak": {
57 + "name": "@bugabinga/pi-ext-bak",
58 + "license": "MIT",
59 + "dependencies": {
60 + "aws4fetch": "^1.0.20"
61 + },
62 + "devDependencies": {
63 + "@marcfargas/pi-test-harness": "^0.6.1",
64 + "vitest": "^4.1.9"
65 + },
66 + "peerDependencies": {
67 + "@earendil-works/pi-coding-agent": "*"
68 + }
69 + },
56 70 "extensions/btw": {
57 71 "name": "@bugabinga/pi-ext-btw",
58 72 "license": "MIT",
1425 1439 "resolved": "extensions/ask",
1426 1440 "link": true
1442 + "node_modules/@bugabinga/pi-ext-bak": {
1443 + "resolved": "extensions/bak",
1444 + "link": true
1445 + },
1428 1446 "node_modules/@bugabinga/pi-ext-btw": {
1429 1447 "resolved": "extensions/btw",
1430 1448 "link": true
5651 5669 "node": ">=12"
5672 + "node_modules/aws4fetch": {
5673 + "version": "1.0.20",
5674 + "resolved": "https://registry.npmjs.org/aws4fetch/-/aws4fetch-1.0.20.tgz",
5675 + "integrity": "sha512-/djoAN709iY65ETD6LKCtyyEI04XIBP5xVvfmNxsEP0uJB5tyaGBztSryRr4HqMStr9R06PisQE7m9zDTXKu6g==",
5676 + "license": "MIT"
5677 + },
5654 5678 "node_modules/bail": {
5655 5679 "version": "2.0.2",
5656 5680 "resolved": "https://registry.npmjs.org/bail/-/bail-2.0.2.tgz",