@phnx-labs/agents-cli 1.20.92 → 1.21.0

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

@@ -1,49 +0,0 @@
-/**
- * Provisioning for cross-machine session sync: write the `r2.backups` secrets
- * bundle and probe R2 connectivity. Pure logic — no prompts, no Commander — so
- * it is unit-testable against the in-memory keychain seam. The interactive flow
- * that collects the values lives in the command layer
- * (`commands/sync-provision.ts`).
- */
-/** Values a caller has already collected for the sync bundle. */
-export interface ProvisionInput {
-    accountId: string;
-    bucketName: string;
-    accessKeyId: string;
-    secretAccessKey: string;
-    /** Optional S3 endpoint override (MinIO / non-R2). Default derived from accountId. */
-    endpoint?: string;
-    /**
-     * Shared transcript-encryption key for a machine JOINING an existing fabric —
-     * paste the key the first machine generated. Omit on the first machine to mint
-     * a fresh one. Ignored if the bundle already carries a key (never overwritten).
-     */
-    encKey?: string;
-}
-export type EncKeyAction = 'generated' | 'reused' | 'provided';
-/**
- * Create or update the `r2.backups` bundle from already-collected values.
- *
- * The four R2 credentials are always (over)written. The encryption key is
- * handled carefully: an existing key is REUSED, never overwritten (overwriting
- * would orphan every transcript peers already encrypted under it); otherwise a
- * caller-supplied `encKey` is stored, or a fresh one minted on the first machine.
- */
-export declare function writeSyncBundle(input: ProvisionInput): {
-    encKeyAction: EncKeyAction;
-};
-/** The shared encryption key currently stored (for display when handing it to peers). */
-export declare function readStoredEncKey(): string | null;
-/**
- * Prove the configured bundle can read AND write its bucket: put a throwaway
- * object, read it back, delete it. Returns a structured result instead of
- * throwing so the caller (setup) never crashes on a bad credential. The probe
- * key lives OUTSIDE the `sessions/` prefix so it can never be mistaken for a
- * machine manifest by the pull path.
- */
-export declare function probeR2Connectivity(): Promise<{
-    ok: true;
-} | {
-    ok: false;
-    error: string;
-}>;

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

@@ -1,91 +0,0 @@
-/**
- * Provisioning for cross-machine session sync: write the `r2.backups` secrets
- * bundle and probe R2 connectivity. Pure logic — no prompts, no Commander — so
- * it is unit-testable against the in-memory keychain seam. The interactive flow
- * that collects the values lives in the command layer
- * (`commands/sync-provision.ts`).
- */
-import { bundleExists, readBundle, writeBundle, bundleItemStore, keychainRef, } from '../../secrets/bundles.js';
-import { secretsKeychainItem } from '../../secrets/index.js';
-import { SYNC_BUNDLE, loadR2Config, clearR2ConfigCache } from './config.js';
-import { R2Client } from './r2.js';
-import { generateSyncEncKey, resolveSyncEncKey } from './transcript-crypto.js';
-import { machineId } from '../../machine-id.js';
-/**
- * Create or update the `r2.backups` bundle from already-collected values.
- *
- * The four R2 credentials are always (over)written. The encryption key is
- * handled carefully: an existing key is REUSED, never overwritten (overwriting
- * would orphan every transcript peers already encrypted under it); otherwise a
- * caller-supplied `encKey` is stored, or a fresh one minted on the first machine.
- */
-export function writeSyncBundle(input) {
-    // Validate a joining machine's pasted key up front so a bad paste fails here,
-    // not silently at the next sync.
-    if (input.encKey)
-        resolveSyncEncKey({ syncEncKey: input.encKey });
-    const bundle = bundleExists(SYNC_BUNDLE)
-        ? readBundle(SYNC_BUNDLE)
-        : { name: SYNC_BUNDLE, description: 'Cross-machine session-sync R2 credentials', vars: {} };
-    const store = bundleItemStore(bundle.backend);
-    const setKey = (key, value) => {
-        store.set(secretsKeychainItem(SYNC_BUNDLE, key), value);
-        bundle.vars[key] = keychainRef(key);
-    };
-    setKey('R2_ACCOUNT_ID', input.accountId);
-    setKey('R2_BUCKET_NAME', input.bucketName);
-    setKey('R2_ACCESS_KEY_ID', input.accessKeyId);
-    setKey('R2_SECRET_ACCESS_KEY', input.secretAccessKey);
-    if (input.endpoint)
-        setKey('R2_ENDPOINT', input.endpoint);
-    let encKeyAction;
-    if (bundle.vars['R2_SYNC_ENC_KEY']) {
-        encKeyAction = 'reused';
-    }
-    else if (input.encKey) {
-        setKey('R2_SYNC_ENC_KEY', input.encKey);
-        encKeyAction = 'provided';
-    }
-    else {
-        setKey('R2_SYNC_ENC_KEY', generateSyncEncKey());
-        encKeyAction = 'generated';
-    }
-    writeBundle(bundle);
-    clearR2ConfigCache(); // so the next loadR2Config() sees the just-written values
-    return { encKeyAction };
-}
-/** The shared encryption key currently stored (for display when handing it to peers). */
-export function readStoredEncKey() {
-    clearR2ConfigCache();
-    try {
-        return loadR2Config().syncEncKey ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Prove the configured bundle can read AND write its bucket: put a throwaway
- * object, read it back, delete it. Returns a structured result instead of
- * throwing so the caller (setup) never crashes on a bad credential. The probe
- * key lives OUTSIDE the `sessions/` prefix so it can never be mistaken for a
- * machine manifest by the pull path.
- */
-export async function probeR2Connectivity() {
-    try {
-        clearR2ConfigCache();
-        const cfg = loadR2Config();
-        const r2 = new R2Client(cfg);
-        const key = `.agents-provision-probe/${machineId()}.txt`;
-        const token = `agents-sync-probe-${machineId()}`;
-        await r2.put(key, token, 'text/plain');
-        const got = await r2.get(key);
-        await r2.delete(key);
-        if (got !== token)
-            return { ok: false, error: 'wrote a probe object but read back different bytes' };
-        return { ok: true };
-    }
-    catch (err) {
-        return { ok: false, error: err.message };
-    }
-}

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

@@ -1,32 +0,0 @@
-/**
- * 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

@@ -1,121 +0,0 @@
-/**
- * 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

@@ -1,106 +0,0 @@
-/**
- * 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[];
-    /** Non-fatal advisories (e.g. transcripts uploaded unencrypted). Unlike
-     *  `errors` these do not set a failing exit code. */
-    warnings: 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 + reconciled content for ONE file across its
- * copies (every copy here is the same file — same relKey — held by a different
- * machine). Pure.
- *
- * The canonical path comes from the lexicographically-smallest machine so every
- * puller derives an identical location. The content depends on the file's kind
- * (see `isMergeableFile`):
- *  - append-only logs (a transcript `.jsonl`) take the CRDT G-Set union — every
- *    machine converges to byte-identical output regardless of order.
- *  - mutable blobs (Kimi `state.json`) can't be line-unioned without corruption,
- *    so they resolve **last-writer-wins**: the copy with the latest event
- *    timestamp, tie-broken by content hash so the pick is deterministic fleet-wide.
- */
-/**
- * The `lastTs` a manifest entry carries for one file. Append-only logs (a
- * conversation `.jsonl`) embed per-line event timestamps, so their recency is
- * the latest line timestamp (`transcriptStats`). Mutable blobs (Kimi
- * `state.json`, the per-tool `tasks/*.json` sidecars) carry no event timestamp —
- * their own `updatedAt`/`createdAt` fields are agent-specific and unreliable — so
- * their "last written" signal is the file mtime. Without this, `transcriptStats`
- * returns `''` for every blob and the last-writer-wins branch in
- * `resolveMirrorWrite` silently degrades to "highest-hash-wins", which can pick a
- * stale copy over the genuinely newer one.
- */
-export declare function deriveLastTs(spec: SyncAgentSpec, relKey: string, content: string, mtimeMs: number): string;
-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>;