pi-ext bugabingas pi extensions
owned by bugabinga
README Source History Refs Compare Notes Search feat(bak): add S3 session archive
6b73505f32257190da87d7d9f46f0260fcc05c9e
Oliver Jan Krylow <oliver@bugabinga.net > · 17 Sep 2026
SSH signature · not checked
Browse files Compare with HEAD
Changed files (12) 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 3 + Asynchronous Pi session backup and restore through S3-compatible object storage.
7 + Create a private bucket and credentials limited to object read/write access for that bucket.
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=...
20 + PI_BAK_S3_BUCKET=pi-bak
21 + PI_BAK_S3_REGION=auto
24 + Initialize each host once:
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.
40 + /bak restore <alias>/<session-id-prefix> [path]
41 + /bak restore all [path]
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" ;
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 ),
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 (),
33 + const etag
= `"${ ++ this.revision}"` ;
34 + this.objects.
set (key, { body, etag });
35 + return new Response (
null , { status:
200 , headers: { etag } });
37 + if (
! current)
return new Response (
"missing" , { status:
404 });
38 + return new Response (current.
body , {
40 + headers: { etag: current.etag },
45 + function info (path
: string , id
: string )
: SessionInfo {
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" ),
54 + firstMessage:
"hello" ,
55 + allMessagesText:
"hello world" ,
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 ;
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 (
72 + endpoint:
"https://example.invalid" ,
76 + secretAccessKey:
"secret" ,
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" ),
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 ({ 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);
98 + archive.
backup ([
info (sessionPath, sessionId)]),
99 + ).resolves.
toEqual ({
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" }],
110 + const destination
= join (directory,
"restore" );
112 + archive.
restore (catalog.indexes[
0 ]?.sessions
?? [], destination),
113 + ).resolves.
toEqual ({ restored:
1 , skipped:
0 , conflicts:
0 });
115 + archive.
restore (catalog.indexes[
0 ]?.sessions
?? [], destination),
116 + ).resolves.
toEqual ({ restored:
0 , skipped:
1 , conflicts:
0 });
117 + const restored
= join (
119 + `2026-01-02T03-04-05-000Z_${sessionId}.jsonl` ,
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);
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` ,
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 (
141 + endpoint:
"https://example.invalid" ,
145 + secretAccessKey:
"secret" ,
150 + identity:
join (directory,
"state" ,
"identity.json" ),
151 + cache:
join (directory,
"cache" ,
"catalog.json" ),
152 + pendingDir:
join (directory,
"state" ,
"pending" ),
160 + id:
"x/../../escaped" ,
161 + key:
"sessions/host/x/../../escaped.jsonl" ,
163 + created:
"2026-01-02T03:04:05.000Z" ,
166 + join (directory,
"restore" ),
168 + ).rejects.
toThrow (
"Invalid archived session record" );
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" ,
180 + secretAccessKey:
"secret" ,
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" ),
189 + await archive.
init (
"work-laptop" );
190 + const sessionId
= "12345678-1234-1234-1234-123456789abc" ;
191 + const sessionPath
= join (directory,
"blank-header.jsonl" );
194 + `\n${ JSON . stringify ({ 198 + timestamp: "2026-01-02T03:04:05.000Z", 199 + cwd: "/work/project", 204 + archive.
backup ([
info (sessionPath, sessionId)]),
205 + ).rejects.
toThrow (
"Invalid Pi session header" );
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 (
214 + endpoint:
"https://example.invalid" ,
218 + secretAccessKey:
"secret" ,
223 + identity:
join (directory,
"state" ,
"identity.json" ),
224 + cache:
join (directory,
"cache" ,
"catalog.json" ),
225 + pendingDir:
join (directory,
"state" ,
"pending" ),
228 + await archive.
init (
"work-laptop" );
230 + "12345678-1234-1234-1234-123456789abc" ,
231 + "abcdefab-1234-1234-1234-123456789abc" ,
233 + const paths
= await Promise .
all (
234 + ids.
map (
async (id, index)
=> {
235 + const path
= join (directory,
`${index}.jsonl` );
238 + `${ JSON . stringify ({ type: "session", version: 3, id, timestamp: `2026-01-02T03:04:0${index}.000Z`, cwd: "/work/project" })}\n` ,
244 + await Promise .
all ([
245 + archive.
backup ([
info (paths[
0 ]
?? "" , ids[
0 ]
?? "" )]),
246 + archive.
backup ([
info (paths[
1 ]
?? "" , ids[
1 ]
?? "" )]),
249 + const catalog
= await archive.
refresh ();
251 + catalog.indexes[
0 ]?.sessions.
map ((session)
=> session.
id ).
sort (),
252 + ).
toEqual ([
... ids].
sort ());
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 (
261 + endpoint:
"https://example.invalid" ,
265 + secretAccessKey:
"secret" ,
270 + identity:
join (directory,
"state" ,
"identity.json" ),
271 + cache:
join (directory,
"cache" ,
"catalog.json" ),
272 + pendingDir:
join (directory,
"state" ,
"pending" ),
275 + await archive.
init (
"work-laptop" );
276 + const ids
= Array .
from (
279 + `00000000-0000-0000-0000-${ String (index). padStart (12, "0")}` ,
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` );
287 + `${ JSON . stringify ({ type: "session", version: 3, id, timestamp: "2026-01-02T03:04:05.000Z", cwd: "/work/project" })}\n` ,
289 + return info (path, id);
293 + let failure
: unknown ;
295 + await archive.
backup (infos);
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 );
304 + indexed.
every ((record)
=> ! memory.failSessionIds.
has (record.
id )),
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 (
315 + endpoint:
"https://example.invalid" ,
319 + secretAccessKey:
"secret" ,
324 + identity:
join (directory,
"state" ,
"identity.json" ),
325 + cache:
join (directory,
"cache" ,
"catalog.json" ),
326 + pendingDir:
join (directory,
"state" ,
"pending" ),
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" );
337 + `${ JSON . stringify ({ type: "session", version: 3, id: sessionId, timestamp: "2026-01-02T03:04:05.000Z", cwd: "/work/project" })}\n` ,
340 + archive.
backup ([
info (sessionPath, sessionId)]),
341 + ).resolves.
toMatchObject ({ uploaded:
1 });
342 + expect ((
await archive.
refresh ()).catalog.hosts).
toEqual ([pendingIdentity]);
345 + it (
"rejects duplicate aliases through the shared catalog" ,
async ()
=> {
346 + directory
= await mkdtemp (
join (
tmpdir (),
"pi-bak-" ));
347 + const memory
= new MemoryS3 ();
349 + endpoint:
"https://example.invalid" ,
353 + secretAccessKey:
"secret" ,
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" ),
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" ),
365 + await first.
init (
"work-laptop" );
366 + await expect (second.
init (
"work-laptop" )).rejects.
toThrow (
367 + "Alias already exists: work-laptop" ,
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 ;
10 + session
= undefined ;
12 + vi.
unstubAllGlobals ();
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 ();
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" },
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" ;
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 ;
20 + describe (
"bak state" , ()
=> {
21 + it (
"keeps machine identity outside Pi configuration" , ()
=> {
24 + { XDG_STATE_HOME:
"/state" , XDG_CACHE_HOME:
"/cache" },
29 + identity:
"/state/pi/bak/identity.json" ,
30 + cache:
"/cache/pi/bak/catalog.json" ,
31 + pendingDir:
"/state/pi/bak/pending" ,
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" ),
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 );
48 + (
await readPending (pendingDir)).
map ((entry)
=> entry.
id ).
sort (),
49 + ).
toEqual ([second.
id , newer.
id ].
sort ());
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 ();
extensions/bak/archive.ts Added new file mode 100644 1 + import { randomUUID }
from "node:crypto" ;
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" ;
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 {
41 + export interface RestoreResult {
47 + interface SessionSnapshot {
48 + record
: SessionRecord ;
53 + export class PartialBackupError extends Error {
56 + readonly succeededPaths
: string [],
57 + options
?: ErrorOptions ,
59 + super(message, options);
60 + this.
name = "PartialBackupError" ;
64 + class AliasCollisionError extends Error {}
66 + async function forEachConcurrent <
T >(
68 + worker : (item
: T )
=> Promise <
void >,
69 + )
: Promise <{ failed
: false }
| { failed
: true ; error
: unknown }> {
72 + let failure
: unknown ;
73 + const run = async ()
=> {
74 + while (cursor
< items.
length ) {
75 + const item
= items[cursor
++ ];
76 + if (item
=== undefined )
continue ;
80 + if (
! failed) failure
= error;
86 + Array .
from ({ length:
Math .
min (TRANSFER_CONCURRENCY, items.
length ) }, run),
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 {
101 + return JSON .
parse (decoder.
decode (body))
as T ;
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 >;
119 + typeof identity.hostId
=== "string" && 120 + UUID.
test (identity.hostId)
&& 121 + typeof identity.alias
=== "string" && 122 + normalizeAlias (identity.alias)
=== identity.alias
126 + function validTimestamp (value
: unknown )
: value
is string {
127 + if (
typeof value
!== "string" )
return false ;
129 + return new Date (value).
toISOString ()
=== value;
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 >;
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)
148 + function parseCatalog (body
: Uint8Array )
: HostCatalog {
149 + const catalog
= parseJson <
HostCatalog >(body, HOST_CATALOG_KEY);
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));
159 + ids.
size !== catalog.hosts.
length || 160 + aliases.
size !== catalog.hosts.
length 162 + throw new Error (
`Duplicate host in ${HOST_CATALOG_KEY}` );
166 + function parseIndex (
169 + expected
: HostIdentity ,
171 + const index
= parseJson <
HostIndex >(body, key);
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}` );
181 + new Set (index.sessions.
map ((record)
=> record.
id )).
size !== 182 + index.sessions.
length 184 + throw new Error (
`Duplicate session in ${key}` );
188 + function stableIndex (index
: HostIndex )
: string {
189 + return JSON .
stringify ({
191 + sessions: [
... index.sessions].
sort ((a, b)
=> a.
id .
localeCompare (b.
id )),
195 + function validateSessionBody (
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 = {
206 + timestamp
?: unknown ;
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 ;
215 + entry
= JSON .
parse (line);
217 + throw new Error (
`Invalid Pi session JSONL at line ${index + 1}` );
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 ;
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" )
254 + created:
new Date (header.timestamp),
255 + modified:
new Date (),
258 + allMessagesText:
"" ,
262 + async function snapshot (
265 + )
: Promise <
SessionSnapshot > {
266 + const body
= new Uint8Array (
await readFile (info.path));
267 + const header
= validateSessionBody (body, info.
id );
270 + sourcePath: info.path,
273 + key:
sessionKey (hostId, header.
id ),
274 + ... (info.
name ? { name: info.
name }
: {}),
276 + created: header.timestamp,
281 + function sameBytes (left
: Uint8Array , right
: Uint8Array )
: boolean {
283 + left.byteLength
=== right.byteLength
&& 284 + left.
every ((value, index)
=> value
=== right[index])
288 + function startsWithBytes (value
: Uint8Array , prefix
: Uint8Array )
: boolean {
290 + value.byteLength
>= prefix.byteLength
&& 291 + prefix.
every ((byte, index)
=> value[index]
=== byte)
295 + async function sameFile (path
: string , body
: Uint8Array )
: Promise <
boolean > {
297 + const local
= await readFile (path);
298 + return local.byteLength
=== body.byteLength
&& local.
equals (body);
300 + if ((error
as NodeJS .
ErrnoException ).
code === "ENOENT" )
return false ;
305 + async function publishNoReplace (
308 + )
: Promise <
boolean > {
309 + await mkdir (
dirname (path), { recursive:
true , mode:
0o700 });
310 + const temporary
= join (
312 + `.${ basename (path)}.${ randomUUID ()}.tmp` ,
315 + await writeFile (temporary, body, { mode:
0o600 , flag:
"wx" });
317 + await link (temporary, path);
320 + if ((error
as NodeJS .
ErrnoException ).
code === "EEXIST" )
return false ;
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 ;
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 {
345 + return header.
type === "session" && typeof header.
id === "string" 351 + await handle?.
close ();
355 + async function destinationSessions (
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);
364 + const paths
= sessions.
get (id)
?? [];
366 + sessions.
set (id, paths);
371 + export class BakArchive {
372 + private initializedHostId
?: string ;
375 + private readonly store
: S3Store ,
376 + private readonly paths
: StatePaths ,
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" );
386 + async cachedCatalog ()
: Promise <
CatalogCache | undefined > {
387 + return readJson <
CatalogCache >(this.paths.cache);
390 + private async remoteCatalog (signal
?: AbortSignal )
: Promise <{
391 + catalog
: HostCatalog ;
395 + const object
= await this.store.
get (HOST_CATALOG_KEY, { signal });
396 + if (
! object)
return { catalog:
emptyCatalog (), exists:
false };
398 + throw new Error (
`Missing ETag for existing ${HOST_CATALOG_KEY}` );
400 + catalog:
parseCatalog (object.
body ),
406 + private async register (
407 + identity
: HostIdentity ,
408 + signal
?: AbortSignal ,
410 + for (
let attempt
= 0 ; attempt
< CAS_ATTEMPTS; attempt
++ ) {
411 + const remote
= await this.
remoteCatalog (signal);
412 + const collision
= remote.catalog.hosts.
find (
414 + host.alias
=== identity.alias
&& host.hostId
!== identity.hostId,
417 + throw new AliasCollisionError (
418 + `Alias already exists: ${identity.alias}` ,
420 + const registered
= remote.catalog.hosts.
find (
421 + (host)
=> host.hostId
=== identity.hostId,
423 + if (registered?.alias
=== identity.alias)
return ;
424 + const hosts
= remote.catalog.hosts.
filter (
425 + (host)
=> host.hostId
!== identity.hostId,
427 + hosts.
push (identity);
428 + hosts.
sort ((a, b)
=> a.alias.
localeCompare (b.alias));
430 + await this.store.
put (
432 + `${ JSON . stringify ({ version: CATALOG_VERSION, hosts })}\n` ,
434 + contentType:
"application/json" ,
436 + ? { ifMatch: remote.etag }
437 + : { ifNoneMatch:
"*" }),
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 ,
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) {
459 + await this.store.
put (key,
`${ stableIndex ( emptyIndex (identity))}\n` , {
460 + contentType:
"application/json" ,
465 + if (
! (error
instanceof S3Error )
|| error.
status !== 412 )
throw error;
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);
477 + "Alias must use 1-64 lowercase letters, digits, ., _, or -" ,
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 ;
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}` );
492 + await this.
ensureInitialized (identity, signal);
495 + if (created
&& error
instanceof AliasCollisionError )
496 + await unlink (this.paths.identity).
catch (()
=> undefined );
501 + async refresh (signal
?: AbortSignal )
: Promise <
CatalogCache > {
502 + const { catalog }
= await this.
remoteCatalog (signal);
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);
512 + ).
sort ((a, b)
=> a.alias.
localeCompare (b.alias));
514 + refreshedAt:
new Date ().
toISOString (),
518 + await atomicWriteJson (this.paths.cache, cache);
522 + private async putSession (
523 + snapshot
: SessionSnapshot ,
524 + signal
?: AbortSignal ,
526 + for (
let attempt
= 0 ; attempt
< CAS_ATTEMPTS; attempt
++ ) {
527 + const current
= await this.store.
get (snapshot.record.key, { signal });
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 }` );
535 + throw new Error (
`Missing ETag for existing ${snapshot.record.key}` );
538 + await this.store.
put (snapshot.record.key, snapshot.
body , {
539 + contentType:
"application/x-ndjson" ,
540 + ... (current
? { ifMatch: current.etag }
: { ifNoneMatch:
"*" }),
545 + if (
! (error
instanceof S3Error )
|| error.
status !== 412 )
throw error;
548 + throw new Error (
`Session changed repeatedly: ${snapshot.record. id }` );
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 []
= [];
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);
567 + onProgress ?.(done, infos.
length );
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]),
582 + for (
const item
of snapshots) {
583 + const previous
= records.
get (item.record.
id );
584 + records.
set (item.record.
id , {
586 + name: item.record.
name ?? previous?.
name ,
589 + const index
: HostIndex = {
590 + version: CATALOG_VERSION,
592 + sessions: [
... records.
values ()],
594 + if (
stableIndex (index)
=== stableIndex (current)) {
595 + indexed
= index.sessions.
length ;
599 + await this.store.
put (key,
`${ stableIndex (index)}\n` , {
600 + contentType:
"application/json" ,
602 + ? { ifMatch: currentObject.etag }
603 + : { ifNoneMatch:
"*" }),
606 + indexed
= index.sessions.
length ;
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) {
616 + transferError.error
instanceof Error 617 + ? transferError.error.message
618 + : String (transferError.error);
619 + throw new PartialBackupError (
621 + snapshots.
map ((item)
=> item.sourcePath),
622 + { cause: transferError.error },
625 + return { uploaded: done, indexed };
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);
645 + const transferError
= await forEachConcurrent (
646 + [
... groups.
values ()],
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 ) {
661 + existing.
map ((path)
=> sameFile (path, object.
body )),
666 + else result.conflicts
++ ;
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 )) {
673 + localSessions.
set (record.
id , [path]);
674 + }
else if (
await sameFile (path, object.
body )) {
676 + localSessions.
set (record.
id , [path]);
677 + }
else result.conflicts
++ ;
680 + onProgress ?.(done, records.
length );
684 + if (transferError.failed)
throw transferError.error;
extensions/bak/index.ts Added new file mode 100644 5 + }
from "@earendil-works/pi-coding-agent" ;
6 + import { SessionManager }
from "@earendil-works/pi-coding-agent" ;
10 + sessionInfoFromPath,
11 + }
from "./archive.js" ;
12 + import { S3Store, s3Config }
from "./s3.js" ;
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 ;
37 + name: ctx.sessionManager.
getSessionName (),
38 + parentSessionPath: header.parentSession,
39 + created:
new Date (header.timestamp),
40 + modified:
new Date (),
41 + messageCount: ctx.sessionManager
43 + .
filter ((entry)
=> entry.
type === "message" ).
length ,
45 + allMessagesText:
"" ,
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);
85 + ! ids.
some ((candidate)
=> candidate
!== id
&& candidate.
startsWith (prefix))
92 + async function localSessions (ctx
: ExtensionContext )
: Promise <
SessionInfo []> {
93 + const manager
= ctx.sessionManager
as typeof ctx.sessionManager
& {
94 + usesDefaultSessionDir ?: ()
=> boolean ;
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)
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 ;
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 >();
122 + ctx
: ExtensionContext ,
124 + level
: "info" | "warning" | "error" = "info" ,
126 + if (ctx.hasUI) ctx.ui.
notify (
`bak: ${message}` , level);
129 + const runSerial = <
T >(
operation : ()
=> Promise <
T >)
: Promise <
T >
=> {
130 + const result
= serial.
then (operation, operation);
131 + serial
= result.
then (
138 + const requireArchive = (ctx
: ExtensionContext )
: BakArchive | undefined => {
139 + if (archive)
return archive;
140 + notify (ctx,
`disabled; missing ${resolved.missing. join (", ")}` ,
"error" );
144 + const setProgress = (ctx
: ExtensionContext , text
?: string )
=> {
148 + text
? ctx.ui.theme.
fg (
"dim" ,
`${ICON} ${text}` )
: undefined ,
152 + const addPending = async (path
: string )
: Promise <
PendingEntry >
=> {
153 + const entry
= await markPending (paths.pendingDir, path);
154 + pending.
set (entry.
id , entry);
158 + const removePending = async (entries
: PendingEntry [])
=> {
160 + entries.
map (
async (entry)
=> {
161 + await clearPending (paths.pendingDir, entry.
id );
162 + pending.
delete (entry.
id );
167 + const ensureLoaded = (
168 + ctx
: ExtensionContext ,
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),
178 + let savedCache
: CatalogCache | undefined ;
180 + savedCache
= await archive.
cachedCatalog ();
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 ;
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);
207 + const backupBatch = async (
208 + infos
: SessionInfo [],
209 + onProgress ?: (done
: number , total
: number )
=> void ,
210 + replayEntries
?: PendingEntry [],
212 + if (
! archive
|| infos.
length === 0 )
return { uploaded:
0 , indexed:
0 };
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),
220 + if (
! identity)
throw new Error (
"Run /bak init <alias> first" );
222 + const result
= await archive.
backup (
225 + lifecycleController?.signal,
227 + await removePending (covered);
228 + lastBackupAt
= new Date ().
toISOString ();
229 + lastError
= undefined ;
232 + if (error
instanceof PartialBackupError ) {
233 + const succeeded
= new Set (error.succeededPaths);
234 + await removePending (
235 + covered.
filter ((entry)
=> succeeded.
has (entry.path)),
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 ;
250 + await archive.
ensureInitialized (
252 + lifecycleController?.signal,
255 + if (epoch
=== lifecycle)
258 + `background init failed: ${ errorText (error)}` ,
262 + void refresh (ctx, lifecycleController?.signal).
catch ((error)
=> {
263 + if (epoch
=== lifecycle
&& ! cache)
266 + `catalog refresh failed: ${ errorText (error)}` ,
270 + await retryPending (epoch);
272 + .
catch ((error)
=> {
273 + if (epoch
=== lifecycle)
276 + `background state failed: ${ errorText (error)}` ,
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,
"↑" );
292 + await backupBatch ([info]);
293 + if (warnedFailure
&& epoch
=== lifecycle) {
294 + notify (ctx,
"backup recovered" );
295 + warnedFailure
= false ;
298 + lastError
= errorText (error);
299 + if (
! warnedFailure
&& epoch
=== lifecycle) {
300 + notify (ctx,
`backup failed: ${lastError}; retry pending` ,
"warning" );
301 + warnedFailure
= true ;
304 + clearTimeout (statusTimer);
305 + if (epoch
=== lifecycle)
setProgress (ctx);
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))) {
316 + infos.
push (
await sessionInfoFromPath (path));
318 + lastError
= `pending ${path}: ${ errorText (error)}` ;
321 + if (infos.
length === 0 )
return ;
322 + await runSerial (()
=> backupBatch (infos,
undefined , replayEntries));
325 + pi.
on (
"session_start" , (_event, ctx)
=> {
327 + lifecycleController?.
abort ();
328 + lifecycleController
= new AbortController ();
329 + loadedLifecycle
= 0 ;
330 + backgroundLifecycle
= 0 ;
331 + readiness
= Promise .
resolve ();
332 + identity
= undefined ;
334 + pending
= new Map ();
335 + if (
! archive
&& ! warnedSetup) {
338 + `disabled; missing ${resolved.missing. join (", ")}` ,
341 + warnedSetup
= true ;
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);
355 + automaticBackup (ctx);
356 + await Promise .
race ([
358 + new Promise ((resolve)
=> setTimeout (resolve, SHUTDOWN_DRAIN_MS)),
360 + lifecycleController?.
abort ();
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);
371 + const query
= restore[
1 ]?.
toLowerCase ()
?? "" ;
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);
378 + value:
`restore ${index.alias}/${prefix}` ,
379 + label:
`${index.alias}/${prefix}` ,
380 + description: record.
name ?? record.cwd,
385 + { value:
"restore all" , label:
"all" , description:
"all sessions" },
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 ;
396 + async handler (args, ctx) {
397 + const trimmed
= args.
trim ();
398 + const [command
= "status" ,
... rest]
= trimmed.
split (
/\s + / );
399 + if (command
=== "status" ) {
401 + await ensureLoaded (ctx).
catch ((error)
=> {
402 + lastError
= errorText (error);
404 + const indexed
= cache?.indexes.
reduce (
405 + (total, index)
=> total
+ index.sessions.
length ,
408 + const state
= archive
411 + : "not initialized" 412 + : `disabled; missing ${resolved.missing. join (", ")}` ;
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 ,
426 + lastError
? "warning" : "info" ,
430 + const client
= requireArchive (ctx);
431 + if (
! client)
return ;
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),
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" );
447 + notify (ctx,
`initialized as ${identity.alias}` );
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),
457 + notify (ctx,
`refreshed ${next.indexes. length } host(s)` );
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}` ),
471 + `backed up ${result.uploaded}; ${result.indexed} indexed` ,
475 + if (command
=== "restore" ) {
476 + const parsed
= destinationArgs (rest.
join (
" " ));
477 + if (
! parsed.
target )
479 + "Usage: /bak restore <alias>/<id-prefix>|all [path]" ,
481 + setProgress (ctx,
"refreshing" );
482 + const current
= await runSerial (()
=> 483 + client.
refresh (lifecycleController?.signal),
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 (()
=> 494 + parsed.path
?? ctx.sessionManager.
getSessionDir (),
495 + (done, total)
=> setProgress (ctx,
`↓ ${done}/${total}` ),
496 + lifecycleController?.signal,
501 + `restored ${result.restored}, skipped ${result.skipped}, conflicts ${result.conflicts}` ,
502 + result.conflicts
> 0 ? "warning" : "info" ,
507 + "Usage: /bak init <alias> | backup | restore <alias>/<id-prefix>|all [path] | refresh | status" ,
510 + lastError
= errorText (error);
511 + notify (ctx, lastError,
"error" );
extensions/bak/mise.toml Added new file mode 100644 2 + description =
"Format bak extension" 3 + depends = [
"//:install" ]
5 + "biome check --write --config-path ../.. ." ,
6 + "rumdl fmt --config ../../.rumdl.toml ." ,
7 + "taplo format --config ../../.taplo.toml mise.toml" ,
11 + description =
"Lint bak extension" 12 + depends = [
"//:install" ]
14 + "biome ci --config-path ../.. ." ,
15 + "rumdl check --config ../../.rumdl.toml ." ,
16 + "taplo format --check --config ../../.taplo.toml mise.toml" ,
20 + description =
"Test bak extension" 21 + depends = [
"//:install" ]
23 + {
task =
"//:test" ,
args = [
"extensions/bak" ] },
27 + description =
"Check bak extension" 28 + depends = [
"//:install" ]
30 + {
task =
"//:build" ,
args = [
"bak" ] },
extensions/bak/package.json Added new file mode 100644 2 + "name" :
"@bugabinga/pi-ext-bak" ,
5 + "peerDependencies" : {
6 + "@earendil-works/pi-coding-agent" :
"*" 9 + "aws4fetch" :
"^1.0.20" 11 + "devDependencies" : {
12 + "@marcfargas/pi-test-harness" :
"^0.6.1" ,
16 + "description" :
"Asynchronous Pi session backup and restore for S3-compatible storage." ,
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 {
11 + accessKeyId
: string ;
12 + secretAccessKey
: string ;
15 + export interface StoredObject {
20 + export class S3Error extends Error {
22 + readonly status
: number ,
26 + this.
name = "S3Error" ;
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))
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 ();
47 + text.
slice (
0 , ERROR_TEXT_LIMIT)
|| response.
statusText || "request failed" 51 + export class S3Store {
52 + private readonly client
: SignedClient ;
55 + readonly config
: S3Config ,
56 + client
?: SignedClient ,
61 + accessKeyId: config.accessKeyId,
62 + secretAccessKey: config.secretAccessKey,
64 + region: config.region,
69 + private async request (
72 + signal
?: AbortSignal ,
73 + )
: Promise <
Response > {
74 + let lastError
: unknown ;
75 + for (
let attempt
= 0 ; attempt
< MAX_ATTEMPTS; attempt
++ ) {
76 + signal?.
throwIfAborted ();
78 + const timeout
= AbortSignal.
timeout (REQUEST_TIMEOUT_MS);
79 + const response
= await this.client.
fetch (
objectUrl (this.config, key), {
81 + signal: signal
? AbortSignal.
any ([signal, timeout])
: timeout,
83 + if (
! shouldRetry (response.
status )
|| attempt
=== MAX_ATTEMPTS
- 1 )
85 + await response.
body ?.
cancel ();
88 + signal?.
throwIfAborted ();
89 + if (attempt
=== MAX_ATTEMPTS
- 1 )
throw error;
91 + await new Promise ((resolve)
=> setTimeout (resolve,
250 * 2 ** attempt));
93 + throw lastError
instanceof Error 95 + : new Error (
"S3 request failed" );
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 ;
105 + throw new S3Error (response.
status ,
await boundedError (response));
107 + body:
new Uint8Array (
await response.
arrayBuffer ()),
108 + etag: response.
headers .
get (
"etag" )
?? undefined ,
114 + body
: string | Uint8Array ,
116 + contentType
?: string ;
118 + ifNoneMatch
?: string ;
119 + signal
?: AbortSignal ;
121 + )
: Promise <
string | undefined > {
122 + const headers
= new Headers ({
123 + "content-type" : options.contentType
?? "application/octet-stream" ,
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 (
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 )
: {
149 + "PI_BAK_S3_ENDPOINT" ,
150 + "PI_BAK_S3_ACCESS_KEY_ID" ,
151 + "PI_BAK_S3_SECRET_ACCESS_KEY" ,
153 + const missing
= required.
filter ((name)
=> ! env[name]?.
trim ());
154 + if (missing.
length > 0 )
return { missing };
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 ()
?? "" ,
extensions/bak/state.ts Added new file mode 100644 1 + import { randomUUID }
from "node:crypto" ;
9 + }
from "node:fs/promises" ;
10 + import { homedir }
from "node:os" ;
11 + import { dirname, join, posix, win32 }
from "node:path" ;
13 + export interface HostIdentity {
18 + export interface SessionRecord {
26 + export interface HostIndex extends HostIdentity {
28 + sessions
: SessionRecord [];
31 + export interface HostCatalog {
33 + hosts
: HostIdentity [];
36 + export interface CatalogCache {
37 + refreshedAt
: string ;
38 + catalog
: HostCatalog ;
39 + indexes
: HostIndex [];
42 + export interface StatePaths {
48 + function platformRoot (
49 + kind
: "state" | "cache" ,
50 + env
: NodeJS .
ProcessEnv ,
51 + platform
: NodeJS .
Platform ,
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" );
59 + env.LOCALAPPDATA
?? paths.
join (home,
"AppData" ,
"Local" ),
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" );
71 + kind
=== "state" ? "Application Support" : "Caches" ,
76 + const override
= kind
=== "state" ? env.XDG_STATE_HOME
: env.XDG_CACHE_HOME;
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 ,
89 + const paths
= platform
=== "win32" ? win32
: posix;
90 + const state
= platformRoot (
"state" , env, platform, home);
92 + identity: paths.
join (state,
"identity.json" ),
94 + platformRoot (
"cache" , env, platform, home),
97 + pendingDir: paths.
join (state,
"pending" ),
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)
108 + export function newIdentity (alias
: string )
: HostIdentity {
109 + return { hostId:
randomUUID (), alias };
112 + export async function readJson <
T >(path
: string )
: Promise <
T | undefined > {
114 + return JSON .
parse (
await readFile (path,
"utf8" ))
as T ;
116 + if ((error
as NodeJS .
ErrnoException ).
code === "ENOENT" )
return undefined ;
121 + export interface PendingEntry {
126 + function pendingMarker (directory
: string , id
: string )
: string {
127 + return join (directory,
`${id}.json` );
130 + export async function markPending (
133 + )
: Promise <
PendingEntry > {
134 + const entry
= { id:
randomUUID (), path };
135 + await atomicWriteJson (
pendingMarker (directory, entry.
id ), entry);
139 + export async function clearPending (
143 + await unlink (
pendingMarker (directory, id)).
catch ((error)
=> {
144 + if ((error
as NodeJS .
ErrnoException ).
code !== "ENOENT" )
throw error;
148 + export async function readPending (directory
: string )
: Promise <
PendingEntry []> {
149 + let names
: string [];
151 + names
= await readdir (directory);
153 + if ((error
as NodeJS .
ErrnoException ).
code === "ENOENT" )
return [];
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),
163 + typeof marker?.
id === "string" && 164 + `${marker. id }.json` === name
&& 165 + typeof marker.path
=== "string" 167 + entries.
push ({ id: marker.
id , path: marker.path });
172 + export async function writeJsonExclusive (
175 + )
: Promise <
boolean > {
176 + await mkdir (
dirname (path), { recursive:
true , mode:
0o700 });
178 + await writeFile (path,
`${ JSON . stringify (value)}\n` , {
184 + if ((error
as NodeJS .
ErrnoException ).
code === "EEXIST" )
return false ;
189 + export async function atomicWriteJson (
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 57 + "name" :
"@bugabinga/pi-ext-bak" ,
60 + "aws4fetch" :
"^1.0.20" 62 + "devDependencies" : {
63 + "@marcfargas/pi-test-harness" :
"^0.6.1" ,
66 + "peerDependencies" : {
67 + "@earendil-works/pi-coding-agent" :
"*" 56 70 "extensions/btw" : {
57 71 "name" :
"@bugabinga/pi-ext-btw" ,
1425 1439 "resolved" :
"extensions/ask" ,
1442 + "node_modules/@bugabinga/pi-ext-bak" : {
1443 + "resolved" :
"extensions/bak" ,
1428 1446 "node_modules/@bugabinga/pi-ext-btw" : {
1429 1447 "resolved" :
"extensions/btw" ,
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==" ,
5654 5678 "node_modules/bail" : {
5655 5679 "version" :
"2.0.2" ,
5656 5680 "resolved" :
"https://registry.npmjs.org/bail/-/bail-2.0.2.tgz" ,