@phnx-labs/agents-cli 1.20.15 → 1.20.17

package/dist/lib/session/sync/agents.js

@@ -0,0 +1,94 @@
+/**
+ * Per-agent adapter for sync. Each supported agent declares where its
+ * transcripts live and how to derive a session id and storage-relative key
+ * from a file path. The merge (crdt.ts) and transport (r2.ts) are fully
+ * agent-agnostic — adding a new agent is just another entry in SYNC_AGENTS.
+ *
+ * Mirror layout: synced-in transcripts land under
+ *   ~/.agents/.history/backups/<agent>/<machine>/<subdir>/<relKey>
+ * which is already a scan root (getAgentSessionDirs scans backups/<agent>/<ts>),
+ * so the existing incremental scanner indexes them with no changes. Because the
+ * scanner dedups by session id with the live home scanned first, a session that
+ * also exists locally always wins — the mirror only ever fills in sessions
+ * originated on other machines.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getHistoryDir } from '../../state.js';
+import { getAgentSessionDirs } from '../discover.js';
+import { walkForFiles } from '../../fs-walk.js';
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+export const SYNC_AGENTS = [
+    {
+        id: 'claude',
+        subdir: 'projects',
+        // Claude transcripts are <projectDir>/<sessionId>.jsonl.
+        sessionIdFromRelKey: rel => path.basename(rel).replace(/\.jsonl$/, ''),
+    },
+    {
+        id: 'codex',
+        subdir: 'sessions',
+        // Codex transcripts are rollout-<ts>-<uuid>.jsonl under date dirs; the uuid
+        // is the session id (matches session_meta.payload.id).
+        sessionIdFromRelKey: rel => path.basename(rel).match(UUID_RE)?.[0] ?? rel,
+    },
+];
+let cachedMirrorRoot = null;
+function mirrorRootReal() {
+    if (cachedMirrorRoot)
+        return cachedMirrorRoot;
+    const root = path.join(getHistoryDir(), 'backups');
+    cachedMirrorRoot = safeReal(root);
+    return cachedMirrorRoot;
+}
+function safeReal(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * List this machine's own transcript files for an agent, EXCLUDING the sync
+ * mirror (we never re-upload another machine's files under our prefix). Dedups
+ * by session id so a session present in multiple version homes is uploaded once.
+ */
+export function listLocalTranscripts(spec) {
+    const mirror = mirrorRootReal();
+    const out = [];
+    const seen = new Set();
+    for (const dir of getAgentSessionDirs(spec.id, spec.subdir)) {
+        if (safeReal(dir).startsWith(mirror))
+            continue; // skip synced-in mirror dirs
+        for (const abs of walkForFiles(dir, '.jsonl', 100_000)) {
+            const relKey = path.relative(dir, abs);
+            if (!relKey || relKey.startsWith('..'))
+                continue;
+            const sessionId = spec.sessionIdFromRelKey(relKey);
+            if (seen.has(sessionId))
+                continue;
+            seen.add(sessionId);
+            out.push({ absPath: abs, sessionId, relKey });
+        }
+    }
+    return out;
+}
+/** Session ids this machine holds locally (live home), used to skip mirror writes. */
+export function localSessionIds(spec) {
+    return new Set(listLocalTranscripts(spec).map(t => t.sessionId));
+}
+/** Absolute mirror path for a remote machine's transcript — lands in a scan root. */
+export function mirrorPath(spec, machine, relKey) {
+    return path.join(getHistoryDir(), 'backups', spec.id, machine, spec.subdir, relKey);
+}
+/** R2 object key for a transcript: sessions/<machine>/<agent>/<sessionId>.jsonl */
+export function objectKey(machine, agentId, sessionId) {
+    return `sessions/${machine}/${agentId}/${sessionId}.jsonl`;
+}
+/** R2 object key for a machine's manifest. */
+export function manifestKey(machine) {
+    return `sessions/${machine}/manifest.json`;
+}
+/** Prefix under which all machine manifests live (for discovery). */
+export const SESSIONS_PREFIX = 'sessions/';

package/dist/lib/session/sync/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Configuration for cross-machine session sync: R2 credentials and this
+ * machine's stable identity. Credentials come from the `r2.backups` secrets
+ * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
+ */
+/** Secrets bundle holding the R2 credentials. */
+export declare const SYNC_BUNDLE = "r2.backups";
+export interface R2Config {
+    accountId: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** S3-compatible endpoint for the account (no bucket, no trailing slash). */
+    endpoint: string;
+}
+/**
+ * Resolve R2 credentials from the `r2.backups` bundle. Throws a clear,
+ * actionable error if the bundle or any key is missing — sync cannot proceed
+ * without real credentials (no silent fallback).
+ */
+export declare function loadR2Config(): R2Config;
+/** True when the sync bundle exists and looks resolvable, without throwing. */
+export declare function isSyncConfigured(): boolean;
+/**
+ * This machine's stable, human-readable id, used as its R2 prefix and mirror
+ * directory name. Tailnet hostnames (zion, yosemite-s0, mac-mini) are already
+ * unique and readable; we lowercase and strip any domain suffix. Overridable
+ * via AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
+ */
+export declare function machineId(): string;

package/dist/lib/session/sync/config.js

@@ -0,0 +1,58 @@
+/**
+ * Configuration for cross-machine session sync: R2 credentials and this
+ * machine's stable identity. Credentials come from the `r2.backups` secrets
+ * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
+ */
+import * as os from 'os';
+import { readAndResolveBundleEnv } from '../../secrets/bundles.js';
+/** Secrets bundle holding the R2 credentials. */
+export const SYNC_BUNDLE = 'r2.backups';
+/**
+ * Resolve R2 credentials from the `r2.backups` bundle. Throws a clear,
+ * actionable error if the bundle or any key is missing — sync cannot proceed
+ * without real credentials (no silent fallback).
+ */
+export function loadR2Config() {
+    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'sessions-sync' });
+    const accountId = env.R2_ACCOUNT_ID?.trim();
+    const bucket = env.R2_BUCKET_NAME?.trim();
+    const accessKeyId = env.R2_ACCESS_KEY_ID?.trim();
+    const secretAccessKey = env.R2_SECRET_ACCESS_KEY?.trim();
+    const missing = [
+        !accountId && 'R2_ACCOUNT_ID',
+        !bucket && 'R2_BUCKET_NAME',
+        !accessKeyId && 'R2_ACCESS_KEY_ID',
+        !secretAccessKey && 'R2_SECRET_ACCESS_KEY',
+    ].filter(Boolean);
+    if (missing.length > 0) {
+        throw new Error(`Sessions sync: bundle '${SYNC_BUNDLE}' is missing ${missing.join(', ')}. ` +
+            `Add them with: agents secrets add ${SYNC_BUNDLE} <KEY>`);
+    }
+    return {
+        accountId: accountId,
+        bucket: bucket,
+        accessKeyId: accessKeyId,
+        secretAccessKey: secretAccessKey,
+        endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
+    };
+}
+/** True when the sync bundle exists and looks resolvable, without throwing. */
+export function isSyncConfigured() {
+    try {
+        loadR2Config();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * This machine's stable, human-readable id, used as its R2 prefix and mirror
+ * directory name. Tailnet hostnames (zion, yosemite-s0, mac-mini) are already
+ * unique and readable; we lowercase and strip any domain suffix. Overridable
+ * via AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
+ */
+export function machineId() {
+    const raw = process.env.AGENTS_SYNC_MACHINE_ID || os.hostname();
+    return raw.split('.')[0].trim().toLowerCase().replace(/[^a-z0-9_-]/g, '-') || 'unknown';
+}

package/dist/lib/session/sync/crdt.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CRDT merge for agent transcripts.
+ *
+ * A transcript (Claude JSONL, Codex JSONL, …) is an append-only log of
+ * immutable events: each line is written once and never rewritten, and Claude
+ * already tolerates branches within one file (parentUuid fan-out). That makes a
+ * transcript a grow-only set (G-Set) of events, and merging two copies of the
+ * same session is a set union — associative, commutative, idempotent. Two
+ * machines that each appended to the same session therefore converge to the
+ * exact same merged file regardless of sync order or timing, with zero conflict
+ * resolution and zero data loss.
+ *
+ * Events are identified by the SHA-256 of their raw line bytes. We deliberately
+ * do NOT key on a per-event `uuid`: Codex lines carry no id, and because an
+ * event is written exactly once and then copied verbatim across machines, the
+ * raw bytes are a stable, agent-agnostic identity. Multiplicity is preserved
+ * (some transcripts contain legitimately identical lines, e.g. paired
+ * `queue-operation` entries) by taking the per-hash max count across sources.
+ */
+export interface ParsedEvent {
+    /** Original line bytes, exactly as stored (no trailing newline). */
+    raw: string;
+    /** SHA-256 of `raw` — the event's identity. */
+    hash: string;
+    /** Top-level ISO `timestamp`, or '' when absent/unparseable. */
+    ts: string;
+}
+/** Parse a transcript's raw text into events, skipping blank lines. */
+export declare function parseTranscript(content: string): ParsedEvent[];
+/**
+ * Merge copies of the same session into one transcript via G-Set union.
+ *
+ * Returns a source VERBATIM (no reordering, byte-identical) for the common
+ * cases — one source, all sources identical, or one source a superset of the
+ * rest — so the steady state never rewrites unchanged files. Only a true fork
+ * (each side holds events the other lacks) produces a reordered union, sorted
+ * by (timestamp, hash) so every machine derives identical bytes.
+ */
+export declare function mergeTranscripts(contents: string[]): string;
+/** Count distinct + total events across copies (for logging / manifest stats). */
+export declare function transcriptStats(content: string): {
+    events: number;
+    lastTs: string;
+};

package/dist/lib/session/sync/crdt.js

@@ -0,0 +1,119 @@
+/**
+ * CRDT merge for agent transcripts.
+ *
+ * A transcript (Claude JSONL, Codex JSONL, …) is an append-only log of
+ * immutable events: each line is written once and never rewritten, and Claude
+ * already tolerates branches within one file (parentUuid fan-out). That makes a
+ * transcript a grow-only set (G-Set) of events, and merging two copies of the
+ * same session is a set union — associative, commutative, idempotent. Two
+ * machines that each appended to the same session therefore converge to the
+ * exact same merged file regardless of sync order or timing, with zero conflict
+ * resolution and zero data loss.
+ *
+ * Events are identified by the SHA-256 of their raw line bytes. We deliberately
+ * do NOT key on a per-event `uuid`: Codex lines carry no id, and because an
+ * event is written exactly once and then copied verbatim across machines, the
+ * raw bytes are a stable, agent-agnostic identity. Multiplicity is preserved
+ * (some transcripts contain legitimately identical lines, e.g. paired
+ * `queue-operation` entries) by taking the per-hash max count across sources.
+ */
+import * as crypto from 'crypto';
+/** Extract the top-level `timestamp` field both Claude and Codex stamp per line. */
+function lineTimestamp(raw) {
+    try {
+        const obj = JSON.parse(raw);
+        const ts = obj?.timestamp;
+        return typeof ts === 'string' ? ts : '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Parse a transcript's raw text into events, skipping blank lines. */
+export function parseTranscript(content) {
+    const out = [];
+    for (const line of content.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        out.push({
+            raw: line,
+            hash: crypto.createHash('sha256').update(line).digest('hex'),
+            ts: lineTimestamp(line),
+        });
+    }
+    return out;
+}
+/** Order events deterministically across machines: by timestamp, then hash. */
+function compareEvents(a, b) {
+    if (a.ts !== b.ts)
+        return a.ts < b.ts ? -1 : 1;
+    if (a.hash !== b.hash)
+        return a.hash < b.hash ? -1 : 1;
+    return 0;
+}
+/**
+ * Merge copies of the same session into one transcript via G-Set union.
+ *
+ * Returns a source VERBATIM (no reordering, byte-identical) for the common
+ * cases — one source, all sources identical, or one source a superset of the
+ * rest — so the steady state never rewrites unchanged files. Only a true fork
+ * (each side holds events the other lacks) produces a reordered union, sorted
+ * by (timestamp, hash) so every machine derives identical bytes.
+ */
+export function mergeTranscripts(contents) {
+    const sources = contents.filter(c => c.length > 0);
+    if (sources.length === 0)
+        return '';
+    if (sources.length === 1)
+        return sources[0];
+    const parsed = sources.map(parseTranscript);
+    // Per-source multiset of event hashes.
+    const counts = parsed.map(events => {
+        const m = new Map();
+        for (const e of events)
+            m.set(e.hash, (m.get(e.hash) ?? 0) + 1);
+        return m;
+    });
+    // Global max count per hash + a representative event for raw bytes / ts.
+    const maxCount = new Map();
+    const rep = new Map();
+    for (let i = 0; i < parsed.length; i++) {
+        for (const e of parsed[i])
+            if (!rep.has(e.hash))
+                rep.set(e.hash, e);
+        for (const [h, c] of counts[i])
+            maxCount.set(h, Math.max(maxCount.get(h) ?? 0, c));
+    }
+    // Superset fast path: a source whose multiset already equals the global max
+    // is the union — return it byte-for-byte (covers identical/subset/prefix).
+    for (let i = 0; i < sources.length; i++) {
+        let isSuperset = true;
+        for (const [h, c] of maxCount) {
+            if ((counts[i].get(h) ?? 0) !== c) {
+                isSuperset = false;
+                break;
+            }
+        }
+        if (isSuperset)
+            return sources[i];
+    }
+    // True fork: emit each distinct event maxCount times, deterministically ordered.
+    const distinct = [...rep.values()].sort(compareEvents);
+    const lines = [];
+    for (const e of distinct) {
+        const n = maxCount.get(e.hash) ?? 1;
+        for (let k = 0; k < n; k++)
+            lines.push(e.raw);
+    }
+    const trailing = sources.some(s => s.endsWith('\n')) ? '\n' : '';
+    return lines.join('\n') + trailing;
+}
+/** Count distinct + total events across copies (for logging / manifest stats). */
+export function transcriptStats(content) {
+    const parsed = parseTranscript(content);
+    let lastTs = '';
+    for (const e of parsed)
+        if (e.ts > lastTs)
+            lastTs = e.ts;
+    return { events: parsed.length, lastTs };
+}

package/dist/lib/session/sync/manifest.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Manifests and the local upload ledger.
+ *
+ * Each machine publishes one manifest object (sessions/<machine>/manifest.json)
+ * listing every session it holds, keyed by session id, with content hash + size
+ * + last event timestamp. Pulling machines diff manifests to fetch only changed
+ * objects — no per-tick LIST of thousands of keys.
+ *
+ * The local upload ledger (cache, per machine) records (size, mtime, hash) of
+ * files already pushed, so a tick re-uploads only files that actually grew.
+ */
+export interface ManifestEntry {
+    /** Storage-relative key, preserved into the mirror layout on the puller. */
+    relKey: string;
+    size: number;
+    /** SHA-256 of the full transcript file. */
+    hash: string;
+    /** Latest event timestamp in the transcript. */
+    lastTs: string;
+}
+/** sessionId -> entry */
+export type AgentManifest = Record<string, ManifestEntry>;
+export interface Manifest {
+    machine: string;
+    updatedAt: string;
+    /** agentId -> (sessionId -> entry) */
+    agents: Record<string, AgentManifest>;
+}
+export declare function emptyManifest(machine: string, updatedAt: string): Manifest;
+export declare function parseManifest(text: string): Manifest | null;
+export declare function hashContent(content: string | Uint8Array): string;
+export declare function loadLocalManifest(): Manifest | null;
+export declare function saveLocalManifest(m: Manifest): void;
+/** key `${agent}/${sessionId}` -> signature of applied source hashes */
+export type PullState = Record<string, string>;
+export declare function loadPullState(): PullState;
+export declare function savePullState(s: PullState): void;
+/** Order-independent signature of the source hashes feeding one mirrored session. */
+export declare function sourceSignature(hashes: string[]): string;
+interface LedgerRow {
+    size: number;
+    mtimeMs: number;
+    hash: string;
+}
+type Ledger = Record<string, LedgerRow>;
+export declare function loadLedger(): Ledger;
+export declare function saveLedger(ledger: Ledger): void;
+/** True if the file at absPath is unchanged since we last uploaded it. */
+export declare function ledgerUnchanged(ledger: Ledger, absPath: string, size: number, mtimeMs: number): boolean;
+export declare function ledgerRecord(ledger: Ledger, absPath: string, size: number, mtimeMs: number, hash: string): void;
+export {};

package/dist/lib/session/sync/manifest.js

@@ -0,0 +1,96 @@
+/**
+ * Manifests and the local upload ledger.
+ *
+ * Each machine publishes one manifest object (sessions/<machine>/manifest.json)
+ * listing every session it holds, keyed by session id, with content hash + size
+ * + last event timestamp. Pulling machines diff manifests to fetch only changed
+ * objects — no per-tick LIST of thousands of keys.
+ *
+ * The local upload ledger (cache, per machine) records (size, mtime, hash) of
+ * files already pushed, so a tick re-uploads only files that actually grew.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { getCacheDir } from '../../state.js';
+export function emptyManifest(machine, updatedAt) {
+    return { machine, updatedAt, agents: {} };
+}
+export function parseManifest(text) {
+    try {
+        const m = JSON.parse(text);
+        if (m && typeof m.machine === 'string' && m.agents && typeof m.agents === 'object')
+            return m;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function hashContent(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+function stateDir() {
+    return path.join(getCacheDir(), 'state', 'sessions-sync');
+}
+// --- local cached copy of our published manifest ---------------------------
+function localManifestPath() {
+    return path.join(stateDir(), 'manifest.json');
+}
+export function loadLocalManifest() {
+    try {
+        return parseManifest(fs.readFileSync(localManifestPath(), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveLocalManifest(m) {
+    const p = localManifestPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(m), 'utf-8');
+}
+function pullStatePath() {
+    return path.join(stateDir(), 'pull-state.json');
+}
+export function loadPullState() {
+    try {
+        return JSON.parse(fs.readFileSync(pullStatePath(), 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function savePullState(s) {
+    const p = pullStatePath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(s), 'utf-8');
+}
+/** Order-independent signature of the source hashes feeding one mirrored session. */
+export function sourceSignature(hashes) {
+    return [...hashes].sort().join(',');
+}
+function ledgerPath() {
+    return path.join(getCacheDir(), 'state', 'sessions-sync', 'upload-ledger.json');
+}
+export function loadLedger() {
+    try {
+        return JSON.parse(fs.readFileSync(ledgerPath(), 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function saveLedger(ledger) {
+    const p = ledgerPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(ledger), 'utf-8');
+}
+/** True if the file at absPath is unchanged since we last uploaded it. */
+export function ledgerUnchanged(ledger, absPath, size, mtimeMs) {
+    const row = ledger[absPath];
+    return !!row && row.size === size && row.mtimeMs === Math.floor(mtimeMs);
+}
+export function ledgerRecord(ledger, absPath, size, mtimeMs, hash) {
+    ledger[absPath] = { size, mtimeMs: Math.floor(mtimeMs), hash };
+}

package/dist/lib/session/sync/r2.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Minimal S3-compatible client for Cloudflare R2, built on aws4fetch (SigV4
+ * over the platform `fetch` + WebCrypto — works identically under Bun and
+ * Node >= 22). Only the verbs sync needs: put / get / head / list / delete.
+ *
+ * No mounting, no FUSE: this is a plain object-store client driven by a polling
+ * loop, which is the only approach that is seamless on both macOS and Linux
+ * (Mountpoint for S3 is Linux-only; rclone-mount needs macFUSE).
+ */
+import type { R2Config } from './config.js';
+export interface HeadResult {
+    size: number;
+    etag: string;
+}
+export declare class R2Client {
+    private aws;
+    private base;
+    constructor(cfg: R2Config);
+    private url;
+    /** Upload an object. Overwrites unconditionally. */
+    put(key: string, body: string | Uint8Array, contentType?: string): Promise<void>;
+    /** Fetch an object as text, or null if it does not exist (404). */
+    get(key: string): Promise<string | null>;
+    /** HEAD an object for size + etag, or null if it does not exist. */
+    head(key: string): Promise<HeadResult | null>;
+    /** Delete an object (no error if it is already absent). */
+    delete(key: string): Promise<void>;
+    /** List immediate sub-prefixes under a prefix (delimiter '/'), e.g. machine dirs. */
+    listPrefixes(prefix: string): Promise<string[]>;
+    /** List all object keys under a prefix (handles pagination). */
+    list(prefix: string): Promise<string[]>;
+}

package/dist/lib/session/sync/r2.js

@@ -0,0 +1,121 @@
+/**
+ * Minimal S3-compatible client for Cloudflare R2, built on aws4fetch (SigV4
+ * over the platform `fetch` + WebCrypto — works identically under Bun and
+ * Node >= 22). Only the verbs sync needs: put / get / head / list / delete.
+ *
+ * No mounting, no FUSE: this is a plain object-store client driven by a polling
+ * loop, which is the only approach that is seamless on both macOS and Linux
+ * (Mountpoint for S3 is Linux-only; rclone-mount needs macFUSE).
+ */
+import { AwsClient } from 'aws4fetch';
+export class R2Client {
+    aws;
+    base;
+    constructor(cfg) {
+        this.aws = new AwsClient({
+            accessKeyId: cfg.accessKeyId,
+            secretAccessKey: cfg.secretAccessKey,
+            service: 's3',
+            region: 'auto',
+        });
+        this.base = `${cfg.endpoint}/${encodeURIComponent(cfg.bucket)}`;
+    }
+    url(key) {
+        const encoded = key.split('/').map(encodeURIComponent).join('/');
+        return `${this.base}/${encoded}`;
+    }
+    /** Upload an object. Overwrites unconditionally. */
+    async put(key, body, contentType = 'application/octet-stream') {
+        const res = await this.aws.fetch(this.url(key), {
+            method: 'PUT',
+            body,
+            headers: { 'content-type': contentType },
+        });
+        if (!res.ok)
+            throw new Error(`R2 PUT ${key} failed: ${res.status} ${await safeText(res)}`);
+    }
+    /** Fetch an object as text, or null if it does not exist (404). */
+    async get(key) {
+        const res = await this.aws.fetch(this.url(key), { method: 'GET' });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`R2 GET ${key} failed: ${res.status} ${await safeText(res)}`);
+        return await res.text();
+    }
+    /** HEAD an object for size + etag, or null if it does not exist. */
+    async head(key) {
+        const res = await this.aws.fetch(this.url(key), { method: 'HEAD' });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`R2 HEAD ${key} failed: ${res.status}`);
+        return {
+            size: Number(res.headers.get('content-length') ?? '0'),
+            etag: (res.headers.get('etag') ?? '').replace(/"/g, ''),
+        };
+    }
+    /** Delete an object (no error if it is already absent). */
+    async delete(key) {
+        const res = await this.aws.fetch(this.url(key), { method: 'DELETE' });
+        if (!res.ok && res.status !== 404) {
+            throw new Error(`R2 DELETE ${key} failed: ${res.status}`);
+        }
+    }
+    /** List immediate sub-prefixes under a prefix (delimiter '/'), e.g. machine dirs. */
+    async listPrefixes(prefix) {
+        const prefixes = [];
+        let token;
+        do {
+            const params = new URLSearchParams({ 'list-type': '2', prefix, delimiter: '/' });
+            if (token)
+                params.set('continuation-token', token);
+            const res = await this.aws.fetch(`${this.base}?${params.toString()}`, { method: 'GET' });
+            if (!res.ok)
+                throw new Error(`R2 LIST(prefixes) ${prefix} failed: ${res.status} ${await safeText(res)}`);
+            const xml = await res.text();
+            for (const m of xml.matchAll(/<CommonPrefixes><Prefix>([^<]+)<\/Prefix><\/CommonPrefixes>/g)) {
+                prefixes.push(decodeXml(m[1]));
+            }
+            const truncated = /<IsTruncated>true<\/IsTruncated>/.test(xml);
+            token = truncated ? xml.match(/<NextContinuationToken>([^<]+)<\/NextContinuationToken>/)?.[1] : undefined;
+        } while (token);
+        return prefixes;
+    }
+    /** List all object keys under a prefix (handles pagination). */
+    async list(prefix) {
+        const keys = [];
+        let token;
+        do {
+            const params = new URLSearchParams({ 'list-type': '2', prefix });
+            if (token)
+                params.set('continuation-token', token);
+            const res = await this.aws.fetch(`${this.base}?${params.toString()}`, { method: 'GET' });
+            if (!res.ok)
+                throw new Error(`R2 LIST ${prefix} failed: ${res.status} ${await safeText(res)}`);
+            const xml = await res.text();
+            for (const m of xml.matchAll(/<Key>([^<]+)<\/Key>/g)) {
+                keys.push(decodeXml(m[1]));
+            }
+            const truncated = /<IsTruncated>true<\/IsTruncated>/.test(xml);
+            token = truncated ? xml.match(/<NextContinuationToken>([^<]+)<\/NextContinuationToken>/)?.[1] : undefined;
+        } while (token);
+        return keys;
+    }
+}
+function decodeXml(s) {
+    return s
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'");
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 200);
+    }
+    catch {
+        return '';
+    }
+}