@phnx-labs/agents-cli 1.20.15 → 1.20.16

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 '';
+    }
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Cross-machine session sync orchestration.
+ *
+ *  PUSH  this machine's transcripts (changed since last tick) to its own R2
+ *        prefix, then publish a manifest. Single-writer prefixes mean no two
+ *        machines ever write the same object — zero remote contention.
+ *
+ *  PULL  every other machine's manifest, fetch changed transcripts, CRDT-union
+ *        copies of the same session, and write the result into the local mirror
+ *        (a scan root). The existing scanner indexes it; sessions present in the
+ *        live home always win, so the mirror only fills in remote-origin sessions.
+ *
+ * Invariants:
+ *  - Live home transcripts are only ever READ + uploaded, never rewritten.
+ *  - Union is idempotent, so once sets match nothing is transferred (quiescence).
+ */
+import { type SyncAgentSpec } from './agents.js';
+import { type ManifestEntry, type PullState } from './manifest.js';
+export interface SyncResult {
+    machine: string;
+    pushed: number;
+    pushSkipped: number;
+    pulled: number;
+    merged: number;
+    pullSkipped: number;
+    errors: string[];
+}
+export interface SyncOptions {
+    verbose?: boolean;
+    log?: (msg: string) => void;
+    /** Upload this machine's transcripts (default true). */
+    push?: boolean;
+    /** Download + merge other machines' transcripts (default true). A machine
+     *  with read-only R2 credentials can still pull. */
+    pull?: boolean;
+}
+export interface RemoteCopy {
+    machine: string;
+    entry: ManifestEntry;
+}
+export interface PendingSession {
+    agentId: string;
+    sessionId: string;
+    copies: RemoteCopy[];
+    /** Signature of source hashes — stored in pull state once applied. */
+    sig: string;
+}
+/**
+ * Decide which remote sessions need fetching this tick. Pure: no I/O.
+ * Skips sessions we hold locally (home wins) and sessions whose source set is
+ * unchanged since we last materialized them (pull-state hit → quiescence).
+ */
+export declare function selectSessionsToFetch(copies: Map<string, Map<string, RemoteCopy[]>>, localIdsByAgent: Map<string, Set<string>>, pullState: PullState): PendingSession[];
+/**
+ * Resolve the mirror destination + merged content for one session. Pure.
+ * The canonical path comes from the lexicographically-smallest machine so every
+ * puller derives an identical location; the content is the CRDT union of copies.
+ */
+export declare function resolveMirrorWrite(spec: SyncAgentSpec, copies: RemoteCopy[], contents: string[]): {
+    dest: string;
+    content: string;
+    merged: boolean;
+};
+/**
+ * Decide how to reconcile one session's fetched copies. Pure: no I/O.
+ *
+ * `fetched` is positionally aligned to `copies` — a `null` slot means that
+ * copy's object wasn't retrievable this tick (R2 404 / LIST→GET consistency
+ * lag / a transient get error). If ANY listed copy is missing, returns `null`:
+ * the caller must then skip the mirror write AND skip stamping pull-state, so
+ * the session is retried next tick. Writing a partial set instead would
+ * materialize a non-converged union and — because pull-state would record the
+ * full source signature — abandon the missing branch forever (the bug this
+ * guards: a signature match in selectSessionsToFetch never re-fetches it).
+ */
+export declare function reconcileCopies(spec: SyncAgentSpec, copies: RemoteCopy[], fetched: Array<string | null>): {
+    dest: string;
+    content: string;
+    merged: boolean;
+} | null;
+/** Run one full sync cycle: push this machine's changes, pull everyone else's. */
+export declare function syncSessions(opts?: SyncOptions): Promise<SyncResult>;