@phnx-labs/agents-cli 1.20.15 → 1.20.17

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>;

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

@@ -0,0 +1,251 @@
+/**
+ * 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 * as fs from 'fs';
+import * as path from 'path';
+import { R2Client } from './r2.js';
+import { loadR2Config, machineId } from './config.js';
+import { SYNC_AGENTS, listLocalTranscripts, localSessionIds, mirrorPath, objectKey, manifestKey, SESSIONS_PREFIX, } from './agents.js';
+import { mergeTranscripts, transcriptStats } from './crdt.js';
+import { emptyManifest, parseManifest, hashContent, loadLedger, saveLedger, ledgerUnchanged, ledgerRecord, loadLocalManifest, saveLocalManifest, loadPullState, savePullState, sourceSignature, } from './manifest.js';
+const nowIso = () => new Date().toISOString();
+function specById(id) {
+    return SYNC_AGENTS.find(s => s.id === id);
+}
+/** Upload this machine's changed transcripts and publish its manifest. */
+async function pushOwn(r2, me, opts, result) {
+    const ledger = loadLedger();
+    const prev = loadLocalManifest();
+    const manifest = emptyManifest(me, nowIso());
+    for (const spec of SYNC_AGENTS) {
+        const agentManifest = {};
+        for (const t of listLocalTranscripts(spec)) {
+            let stat;
+            try {
+                stat = fs.statSync(t.absPath);
+            }
+            catch {
+                continue;
+            }
+            const prevEntry = prev?.agents?.[spec.id]?.[t.sessionId];
+            if (prevEntry && ledgerUnchanged(ledger, t.absPath, stat.size, stat.mtimeMs)) {
+                agentManifest[t.sessionId] = prevEntry; // unchanged: reuse, no read, no upload
+                result.pushSkipped++;
+                continue;
+            }
+            let content;
+            try {
+                content = fs.readFileSync(t.absPath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const hash = hashContent(content);
+            const { lastTs } = transcriptStats(content);
+            const entry = { relKey: t.relKey, size: stat.size, hash, lastTs };
+            try {
+                await r2.put(objectKey(me, spec.id, t.sessionId), content, 'application/x-ndjson');
+                ledgerRecord(ledger, t.absPath, stat.size, stat.mtimeMs, hash);
+                agentManifest[t.sessionId] = entry;
+                result.pushed++;
+                if (opts.verbose)
+                    opts.log?.(`  push ${spec.id}/${t.sessionId.slice(0, 8)} (${stat.size}B)`);
+            }
+            catch (err) {
+                result.errors.push(`push ${spec.id}/${t.sessionId}: ${err.message}`);
+            }
+        }
+        if (Object.keys(agentManifest).length > 0)
+            manifest.agents[spec.id] = agentManifest;
+    }
+    try {
+        await r2.put(manifestKey(me), JSON.stringify(manifest), 'application/json');
+        saveLocalManifest(manifest);
+        saveLedger(ledger);
+    }
+    catch (err) {
+        result.errors.push(`manifest publish: ${err.message}`);
+    }
+}
+/**
+ * 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 function selectSessionsToFetch(copies, localIdsByAgent, pullState) {
+    const pending = [];
+    for (const [agentId, byAgent] of copies) {
+        const localIds = localIdsByAgent.get(agentId) ?? new Set();
+        for (const [sessionId, list] of byAgent) {
+            if (localIds.has(sessionId))
+                continue;
+            const sig = sourceSignature(list.map(c => c.entry.hash));
+            if (pullState[`${agentId}/${sessionId}`] === sig)
+                continue;
+            pending.push({ agentId, sessionId, copies: list, sig });
+        }
+    }
+    return pending;
+}
+/**
+ * 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 function resolveMirrorWrite(spec, copies, contents) {
+    const canonical = [...copies].sort((a, b) => (a.machine < b.machine ? -1 : a.machine > b.machine ? 1 : 0))[0];
+    const content = contents.length === 1 ? contents[0] : mergeTranscripts(contents);
+    return {
+        dest: mirrorPath(spec, canonical.machine, canonical.entry.relKey),
+        content,
+        merged: contents.length > 1,
+    };
+}
+/**
+ * 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 function reconcileCopies(spec, copies, fetched) {
+    const contents = [];
+    for (const text of fetched) {
+        if (text === null)
+            return null; // incomplete fetch — retry next tick
+        contents.push(text);
+    }
+    if (contents.length === 0)
+        return null;
+    return resolveMirrorWrite(spec, copies, contents);
+}
+/** Fetch other machines' manifests, union changed sessions into the mirror. */
+async function pullAndReconcile(r2, me, opts, result) {
+    const prefixes = await r2.listPrefixes(SESSIONS_PREFIX); // sessions/<machine>/
+    const machines = prefixes
+        .map(p => p.slice(SESSIONS_PREFIX.length).replace(/\/$/, ''))
+        .filter(m => m && m !== me);
+    // agentId -> sessionId -> copies across machines
+    const copies = new Map();
+    for (const m of machines) {
+        let manifest = null;
+        try {
+            const text = await r2.get(manifestKey(m));
+            manifest = text ? parseManifest(text) : null;
+        }
+        catch (err) {
+            result.errors.push(`fetch manifest ${m}: ${err.message}`);
+        }
+        if (!manifest)
+            continue;
+        for (const [agentId, sessions] of Object.entries(manifest.agents)) {
+            if (!specById(agentId))
+                continue;
+            let byAgent = copies.get(agentId);
+            if (!byAgent)
+                copies.set(agentId, (byAgent = new Map()));
+            for (const [sessionId, entry] of Object.entries(sessions)) {
+                const list = byAgent.get(sessionId) ?? [];
+                list.push({ machine: m, entry });
+                byAgent.set(sessionId, list);
+            }
+        }
+    }
+    const pullState = loadPullState();
+    const localIdsByAgent = new Map();
+    for (const agentId of copies.keys()) {
+        const spec = specById(agentId);
+        if (spec)
+            localIdsByAgent.set(agentId, localSessionIds(spec));
+    }
+    const pending = selectSessionsToFetch(copies, localIdsByAgent, pullState);
+    let candidates = 0;
+    for (const byAgent of copies.values())
+        candidates += byAgent.size;
+    result.pullSkipped += candidates - pending.length; // local-owned or unchanged
+    for (const { agentId, sessionId, copies: list, sig } of pending) {
+        const spec = specById(agentId);
+        // Download each copy (could be a fork across >1 machine), keeping the
+        // result positionally aligned to `list` — null marks a copy we couldn't
+        // fetch this tick (404 / consistency lag / error).
+        const fetched = [];
+        for (const c of list) {
+            try {
+                fetched.push(await r2.get(objectKey(c.machine, agentId, sessionId)));
+            }
+            catch (err) {
+                result.errors.push(`get ${c.machine}/${sessionId}: ${err.message}`);
+                fetched.push(null);
+            }
+        }
+        // null ⇒ an incomplete fetch: skip the write AND the pull-state stamp so we
+        // retry next tick instead of persisting a partial union / abandoning a branch.
+        const resolved = reconcileCopies(spec, list, fetched);
+        if (!resolved)
+            continue;
+        const { dest, content, merged } = resolved;
+        try {
+            let existing = null;
+            try {
+                existing = fs.readFileSync(dest, 'utf-8');
+            }
+            catch { /* not present yet */ }
+            if (existing !== content) {
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.writeFileSync(dest, content, 'utf-8');
+                if (merged)
+                    result.merged++;
+                result.pulled++;
+                if (opts.verbose) {
+                    opts.log?.(`  pull ${agentId}/${sessionId.slice(0, 8)} <- ${list.map(c => c.machine).join('+')}`);
+                }
+            }
+            else {
+                result.pullSkipped++;
+            }
+            pullState[`${agentId}/${sessionId}`] = sig;
+        }
+        catch (err) {
+            result.errors.push(`write mirror ${sessionId}: ${err.message}`);
+        }
+    }
+    savePullState(pullState);
+}
+/** Run one full sync cycle: push this machine's changes, pull everyone else's. */
+export async function syncSessions(opts = {}) {
+    const cfg = loadR2Config();
+    const me = machineId();
+    const r2 = new R2Client(cfg);
+    const result = {
+        machine: me,
+        pushed: 0,
+        pushSkipped: 0,
+        pulled: 0,
+        merged: 0,
+        pullSkipped: 0,
+        errors: [],
+    };
+    if (opts.push !== false)
+        await pushOwn(r2, me, opts, result);
+    if (opts.pull !== false)
+        await pullAndReconcile(r2, me, opts, result);
+    return result;
+}

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 18;
+export declare const SHIM_SCHEMA_VERSION = 19;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -202,7 +202,7 @@ async function promptConflictStrategy(conflictInfos) {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export const SHIM_SCHEMA_VERSION = 18;
+export const SHIM_SCHEMA_VERSION = 19;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -414,6 +414,22 @@ elif [ "$AGENT" = "kimi" ]; then
     # Last resort: whatever is on PATH
     BINARY=$(command -v kimi 2>/dev/null || echo "")
   fi
+# Droid (Factory AI) special case: the official installer drops a standalone
+# native binary at ~/.local/bin/droid — there is no npm package and nothing
+# lands in node_modules/.bin. Resolve the fixed install path directly. The
+# PATH fallback explicitly refuses anything under our own shims dir: that path
+# IS this dispatcher, so exec'ing it would re-enter and spin in an infinite
+# re-exec loop (the bug this branch fixes).
+elif [ "$AGENT" = "droid" ]; then
+  DROID_BINARY="$HOME/.local/bin/droid"
+  if [ -x "$DROID_BINARY" ]; then
+    BINARY="$DROID_BINARY"
+  else
+    BINARY=$(command -v droid 2>/dev/null || echo "")
+    case "$BINARY" in
+      "$AGENTS_USER_DIR/.cache/shims/"*) BINARY="" ;;
+    esac
+  fi
 else
   BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 fi

package/dist/lib/sync-umbrella.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Umbrella `agents sync` orchestration — "make this machine current".
+ *
+ * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
+ * then reconciles it into every installed agent's version home. Each stage is
+ * an existing exported library function; this module only sequences them and
+ * decides — from the flags — which stages run (`planUmbrellaStages`). The
+ * planner is pure so the flag matrix is unit-tested without any I/O.
+ *
+ * Stage backends:
+ *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
+ *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
+ *               cleanly when none is available — tokenized non-interactive auth
+ *               arrives with `agents login`, #366/#367)
+ *   sessions -> syncSessions(), gated by isSyncConfigured() exactly like the daemon
+ *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
+ */
+/** The five umbrella flags off `agents sync`. */
+export interface UmbrellaFlags {
+    repos?: boolean;
+    secrets?: boolean;
+    sessions?: boolean;
+    cloud?: boolean;
+    local?: boolean;
+}
+/** Which stages a given flag combination runs. */
+export interface UmbrellaPlan {
+    fetchRepos: boolean;
+    fetchSecrets: boolean;
+    fetchSessions: boolean;
+    reconcile: boolean;
+}
+/**
+ * Decide which stages run. Pure — no I/O. Semantics:
+ *   bare (no flags)        fetch all three, then reconcile
+ *   --local                reconcile only, no fetch
+ *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --repos/--secrets/...  fetch only the selected types, then reconcile
+ * `--local` wins over everything; `--cloud` suppresses reconcile.
+ */
+export declare function planUmbrellaStages(f: UmbrellaFlags): UmbrellaPlan;
+export interface UmbrellaResult {
+    plan: UmbrellaPlan;
+    repos?: {
+        pulled: number;
+        errors: string[];
+    };
+    secrets?: {
+        pulled: number;
+        skipped: boolean;
+        reason?: string;
+        errors: string[];
+    };
+    sessions?: {
+        ran: boolean;
+        pushed: number;
+        pulled: number;
+        merged: number;
+    };
+    reconciled: boolean;
+}
+export interface RunUmbrellaArgs {
+    flags: UmbrellaFlags;
+    /** Progress sink (already quiet-aware in the caller). */
+    log: (msg: string) => void;
+    /** Pass `skipPrompts` through to reconcile / non-interactive behavior. */
+    yes: boolean;
+    /** Secrets passphrase, if available (env var or prompt). Undefined => skip secrets. */
+    passphrase?: string;
+}
+/**
+ * Execute the planned stages in order: repos -> secrets -> sessions -> reconcile.
+ * A failure in one fetch stage is recorded and does not abort the others or the
+ * reconcile — `agents sync` should make as much current as it can in one pass.
+ */
+export declare function runUmbrellaSync(args: RunUmbrellaArgs): Promise<UmbrellaResult>;

package/dist/lib/sync-umbrella.js

@@ -0,0 +1,125 @@
+/**
+ * Umbrella `agents sync` orchestration — "make this machine current".
+ *
+ * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
+ * then reconciles it into every installed agent's version home. Each stage is
+ * an existing exported library function; this module only sequences them and
+ * decides — from the flags — which stages run (`planUmbrellaStages`). The
+ * planner is pure so the flag matrix is unit-tested without any I/O.
+ *
+ * Stage backends:
+ *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
+ *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
+ *               cleanly when none is available — tokenized non-interactive auth
+ *               arrives with `agents login`, #366/#367)
+ *   sessions -> syncSessions(), gated by isSyncConfigured() exactly like the daemon
+ *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
+ */
+import { pullRepo } from './git.js';
+import { getUserAgentsDir, getEnabledExtraRepos } from './state.js';
+import { listRemoteBundles, pullBundle } from './secrets/sync.js';
+/**
+ * Decide which stages run. Pure — no I/O. Semantics:
+ *   bare (no flags)        fetch all three, then reconcile
+ *   --local                reconcile only, no fetch
+ *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --repos/--secrets/...  fetch only the selected types, then reconcile
+ * `--local` wins over everything; `--cloud` suppresses reconcile.
+ */
+export function planUmbrellaStages(f) {
+    if (f.local) {
+        return { fetchRepos: false, fetchSecrets: false, fetchSessions: false, reconcile: true };
+    }
+    const anySelector = !!(f.repos || f.secrets || f.sessions);
+    if (anySelector) {
+        return {
+            fetchRepos: !!f.repos,
+            fetchSecrets: !!f.secrets,
+            fetchSessions: !!f.sessions,
+            reconcile: !f.cloud,
+        };
+    }
+    // No per-type selector: bare = all + reconcile; --cloud = all, no reconcile.
+    return { fetchRepos: true, fetchSecrets: true, fetchSessions: true, reconcile: !f.cloud };
+}
+/**
+ * Execute the planned stages in order: repos -> secrets -> sessions -> reconcile.
+ * A failure in one fetch stage is recorded and does not abort the others or the
+ * reconcile — `agents sync` should make as much current as it can in one pass.
+ */
+export async function runUmbrellaSync(args) {
+    const { flags, log, yes, passphrase } = args;
+    const plan = planUmbrellaStages(flags);
+    const result = { plan, reconciled: false };
+    if (plan.fetchRepos) {
+        const dirs = [
+            { alias: 'user', dir: getUserAgentsDir() },
+            ...getEnabledExtraRepos().map((e) => ({ alias: e.alias, dir: e.dir })),
+        ];
+        let pulled = 0;
+        const errors = [];
+        for (const { alias, dir } of dirs) {
+            const r = await pullRepo(dir);
+            if (r.success) {
+                pulled++;
+                log(`repos: ${alias} → ${r.commit}`);
+            }
+            else {
+                errors.push(`${alias}: ${r.error ?? 'unknown error'}`);
+            }
+        }
+        result.repos = { pulled, errors };
+    }
+    if (plan.fetchSecrets) {
+        if (!passphrase) {
+            result.secrets = {
+                pulled: 0,
+                skipped: true,
+                reason: 'no passphrase — set AGENTS_SECRETS_PASSPHRASE or run `agents login` (#366)',
+                errors: [],
+            };
+            log('secrets: skipped (no passphrase available)');
+        }
+        else {
+            let pulled = 0;
+            const errors = [];
+            try {
+                const remote = await listRemoteBundles();
+                for (const b of remote) {
+                    try {
+                        await pullBundle(b.name, { passphrase, force: true });
+                        pulled++;
+                        log(`secrets: ${b.name}`);
+                    }
+                    catch (err) {
+                        errors.push(`${b.name}: ${err.message}`);
+                    }
+                }
+            }
+            catch (err) {
+                errors.push(err.message);
+            }
+            result.secrets = { pulled, skipped: false, errors };
+        }
+    }
+    if (plan.fetchSessions) {
+        // Gate exactly like the daemon: a missing r2.backups bundle is a clean no-op,
+        // not an error that fails the whole sync.
+        const { isSyncConfigured } = await import('./session/sync/config.js');
+        if (isSyncConfigured()) {
+            const { syncSessions } = await import('./session/sync/sync.js');
+            const r = await syncSessions();
+            result.sessions = { ran: true, pushed: r.pushed, pulled: r.pulled, merged: r.merged };
+            log(`sessions: pushed ${r.pushed}, pulled ${r.pulled}, merged ${r.merged}`);
+        }
+        else {
+            result.sessions = { ran: false, pushed: 0, pulled: 0, merged: 0 };
+        }
+    }
+    if (plan.reconcile) {
+        const { refresh } = await import('./refresh.js');
+        await refresh({ skipPrompts: yes });
+        result.reconciled = true;
+    }
+    return result;
+}