@phnx-labs/agents-cli 1.20.65 → 1.20.67

package/dist/commands/sessions-browser.js

@@ -0,0 +1,320 @@
+/**
+ * Interactive fleet-wide session browser — the human front-end of `agents sessions`.
+ *
+ * One canonical filter state (device / agent / project / window / running / teams),
+ * driven by single-key hotkeys, re-pulling live over the same fleet fan-out the flag
+ * surface uses. The identical state is expressible as flags (the agent front-end);
+ * `y` / `--print-cmd` round-trips a hand-built view into a copy-pasteable command.
+ *
+ * Built on {@link dynamicPicker}; every data source (discover, fleet, live index,
+ * preview, resume dispatch) is reused from the existing sessions plumbing.
+ */
+import { spawnSync } from 'child_process';
+import { dynamicPicker } from '../lib/picker.js';
+import { getActiveSessions } from '../lib/session/active.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { gatherRemoteList } from '../lib/session/remote-list.js';
+import { machineId, normalizeHost } from '../lib/session/sync/config.js';
+import { buildPreview } from './sessions-picker.js';
+import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, indexActiveBySessionId, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, } from './sessions.js';
+/** Ordered window cycle for the `W` key. `undefined` = all time. */
+const WINDOW_CYCLE = [undefined, '1d', '7d', '30d'];
+/** Return the next value in `[undefined, ...options]`, wrapping. */
+export function cycle(current, options) {
+    const ring = [undefined, ...options];
+    const idx = ring.findIndex((v) => v === current);
+    return ring[(idx + 1) % ring.length];
+}
+export function cycleWindow(current) {
+    const idx = WINDOW_CYCLE.findIndex((v) => v === current);
+    return WINDOW_CYCLE[(idx + 1) % WINDOW_CYCLE.length];
+}
+function distinct(values) {
+    return [...new Set(values.filter((v) => !!v))].sort();
+}
+/**
+ * Cheap client-side match for the `S` search — a plain substring test over a
+ * row's visible fields. Deliberately NOT the FTS `filterSessionsByQuery`: that
+ * runs a content-index scan per call, which is fine once over a pool but a
+ * CPU sink when a picker calls it per-row on every keystroke.
+ */
+export function sessionMatchesQuery(s, query) {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (terms.length === 0)
+        return true;
+    const hay = [
+        s.shortId,
+        s.agent,
+        s.project,
+        s.cwd,
+        s.topic,
+        s.label,
+        ticketLabel(s),
+        s.machine,
+    ]
+        .filter(Boolean)
+        .join(' ')
+        .toLowerCase();
+    return terms.every((t) => hay.includes(t));
+}
+/**
+ * The canonical `ag sessions …` command for a filter state (+ optional search) —
+ * the agent-facing twin of the interactive view. Shared by the `y` hotkey and
+ * `--print-cmd`.
+ */
+export function browserFilterToArgv(f, query = '') {
+    const a = ['sessions'];
+    if (f.running)
+        a.push('--active');
+    if (f.teams)
+        a.push('--teams');
+    if (f.agent)
+        a.push('-a', f.agent);
+    if (f.device)
+        a.push('--device', f.device);
+    if (f.projectScope === 'all')
+        a.push('--all');
+    if (f.window)
+        a.push('--since', f.window);
+    const q = query.trim();
+    if (q)
+        a.push(JSON.stringify(q));
+    return a;
+}
+/** Normalize a `--host`/`--device` token (`alias`, `user@host`, `host.domain`) to
+ * the canonical machine id the rows carry in `.machine`, so a flag seed matches
+ * (the `d` hotkey already cycles canonical ids). Mirrors sessions.ts `hostToken`. */
+export function normalizeDeviceSeed(host) {
+    if (!host)
+        return undefined;
+    return normalizeHost(host.split('@').pop() || host);
+}
+/**
+ * The initial filter for the `--active` browser: fleet-wide (matches the static
+ * `renderActiveSessions`, which has no project scoping — the `p` hotkey narrows to
+ * this repo), running-only, with the device seed normalized and `--since` seeding
+ * the window. Pure, so the routing call site is unit-testable.
+ */
+export function activeBrowserSeed(opts) {
+    return {
+        running: true,
+        teams: !!opts.teams,
+        agent: opts.agent,
+        projectScope: 'all',
+        device: normalizeDeviceSeed(opts.host?.[0]),
+        window: opts.since ?? '30d',
+    };
+}
+/**
+ * The initial filter for the bare interactive listing: current-repo subtree by
+ * default (matches the static overview's cwd scoping), `--all` widens to every
+ * directory, `--since` seeds the window.
+ */
+export function bareBrowserSeed(opts) {
+    return {
+        teams: !!opts.teams,
+        agent: opts.agent,
+        projectScope: opts.all ? 'all' : 'repo',
+        window: opts.since ?? '30d',
+    };
+}
+/** Copy text to the OS clipboard (best-effort; silently no-ops if unavailable). */
+function copyToClipboard(text) {
+    const candidates = process.platform === 'darwin'
+        ? [['pbcopy', []]]
+        : [
+            ['wl-copy', []],
+            ['xclip', ['-selection', 'clipboard']],
+            ['xsel', ['--clipboard', '--input']],
+        ];
+    for (const [cmd, args] of candidates) {
+        try {
+            const res = spawnSync(cmd, args, { input: text });
+            if (res.status === 0)
+                return true;
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return false;
+}
+/** The transcript pool: the local index + (unless --local) a live fleet fan-out.
+ * The live index is fetched separately/lazily — it's the slow part and only the
+ * running filter needs it, so a bare browse stays instant.
+ *
+ * `hosts` is the explicit `--host`/`--device` scope (if any): it restricts which
+ * peers are dialed and whether local is included, honoring the flag's "scope,
+ * not add" contract instead of always sweeping the whole fleet. */
+async function fetchRawPool(f, self, local, hosts) {
+    const since = f.window;
+    // Local pool: wide (every directory) — device/agent/project are applied in
+    // memory so a hotkey toggle is instant and doesn't re-hit the disk. Skipped
+    // when an explicit host scope excludes this machine.
+    let rows = shouldIncludeLocal(hosts, self)
+        ? await discoverSessions({
+            all: true,
+            cwd: process.cwd(),
+            since,
+            excludeTeamOrigin: !f.teams,
+            limit: 500,
+            sortBy: 'timestamp',
+        })
+        : [];
+    // Fleet: fold in peers' own indexes over SSH (no sync), same as the flag path.
+    // Skipped under --local. An explicit --host/--device scopes exactly which peers
+    // are dialed (undefined = sweep every online device). Best-effort — a fan-out
+    // failure leaves the local list intact.
+    if (!local) {
+        try {
+            const forwarded = ['sessions', '--all', '--json', '--limit', '500'];
+            if (since)
+                forwarded.push('--since', since);
+            if (f.teams)
+                forwarded.push('--teams');
+            const { sessions: remote } = await gatherRemoteList(forwarded, remoteHostsToDial(hosts, self));
+            if (remote.length > 0)
+                rows = mergeLocalFirst([...rows, ...remote], self);
+        }
+        catch {
+            // enrichment, never a hard dependency
+        }
+    }
+    return { key: `${since ?? 'all'}|${f.teams}`, rows };
+}
+/** Apply the cheap in-memory filters (agent / device / project / running). */
+function applyFilters(rows, live, f, self) {
+    let out = rows;
+    if (f.agent)
+        out = out.filter((r) => r.agent === f.agent);
+    if (f.device)
+        out = out.filter((r) => (r.machine ?? self) === f.device);
+    if (f.projectScope === 'repo') {
+        const cwd = process.cwd();
+        out = out.filter((r) => !!r.cwd && (r.cwd === cwd || r.cwd.startsWith(cwd + '/')));
+    }
+    if (f.running)
+        out = out.filter((r) => live.has(r.id));
+    return out;
+}
+function headerFor(f) {
+    const bits = [
+        `device:${f.device ?? 'all'}`,
+        `agent:${f.agent ?? 'all'}`,
+        f.projectScope === 'repo' ? 'this repo' : 'all dirs',
+        `window:${f.window ?? 'all'}`,
+    ];
+    if (f.running)
+        bits.push('running');
+    if (f.teams)
+        bits.push('teams');
+    return bits.join(' · ');
+}
+function helpFor(_f, mode) {
+    if (mode === 'search') {
+        return 'type to filter · ↑↓ navigate · esc exit search · ⏎ resume';
+    }
+    return 's search · r running · c teams · a agent · d device · p project · w window · y copy-cmd · ⏎ resume · esc quit';
+}
+/**
+ * Launch the interactive session browser. `initial` seeds the filter (e.g.
+ * `{ running: true }` for `--active`). Resolves after the user resumes a session
+ * or cancels — the picked row is dispatched through the shared resume/focus path.
+ */
+export async function runSessionBrowser(initial = {}, opts = {}) {
+    const self = machineId();
+    const local = opts.local ?? false;
+    const hosts = opts.hosts && opts.hosts.length > 0 ? opts.hosts : undefined;
+    // Updated after each load so the A/D cycles range over what's actually present.
+    let agentsInPool = [];
+    let devicesInPool = [];
+    let cols = {};
+    // Cache the transcript fetch, keyed by (window, teams); agent/device/project/
+    // running are applied in memory so their hotkeys don't re-fan-out the fleet.
+    let rawCache = null;
+    // The live index is slow (a full ps/tmux scan) and only the running filter
+    // needs it — fetch it once, lazily, the first time running is toggled on.
+    let liveCache = null;
+    // Generation guard: two quick keypresses can start overlapping loads whose
+    // SSH fan-outs settle out of order. dynamicPicker's own gen ref guards which
+    // rows become `items`, but the shared closure state below (cols / cycle pools /
+    // caches) is a side channel it can't see — so a stale load must never commit
+    // it. We compute into locals and only write the shared state as the latest load.
+    let loadGen = 0;
+    const initialFilter = {
+        running: initial.running ?? false,
+        teams: initial.teams ?? false,
+        agent: initial.agent,
+        device: initial.device,
+        projectScope: initial.projectScope ?? 'repo',
+        window: 'window' in initial ? initial.window : '30d',
+    };
+    const load = async (f) => {
+        const myGen = ++loadGen;
+        const key = `${f.window ?? 'all'}|${f.teams}`;
+        let pool = rawCache && rawCache.key === key ? rawCache : null;
+        if (!pool) {
+            const fetched = await fetchRawPool(f, self, local, hosts);
+            if (myGen !== loadGen)
+                return []; // superseded — don't touch shared state
+            pool = fetched;
+        }
+        // Only pay for the live scan when the running filter needs it.
+        let live = liveCache;
+        if (f.running && !live) {
+            try {
+                live = indexActiveBySessionId(await getActiveSessions());
+            }
+            catch {
+                live = new Map();
+            }
+            if (myGen !== loadGen)
+                return [];
+        }
+        // Latest load — commit shared state atomically (no await past this point, so
+        // no newer load can interleave between these writes).
+        rawCache = pool;
+        if (live)
+            liveCache = live;
+        agentsInPool = distinct(pool.rows.map((r) => r.agent));
+        devicesInPool = distinct(pool.rows.map((r) => r.machine ?? self));
+        const filtered = applyFilters(pool.rows, live ?? new Map(), f, self);
+        cols = pickerColumnsFor(filtered);
+        return filtered;
+    };
+    const picked = await dynamicPicker({
+        message: 'Sessions',
+        initialFilter,
+        load,
+        keyFor: (s) => s.id,
+        labelFor: (s, q) => formatPickerLabel(s, q, cols),
+        matches: sessionMatchesQuery,
+        buildPreview,
+        headerFor,
+        helpFor,
+        enterHint: 'resume',
+        emptyMessage: 'No sessions match this filter.',
+        loadingMessage: local ? 'Loading…' : 'Loading (reaching other machines)…',
+        keyBindings: {
+            r: (f) => ({ ...f, running: !f.running }),
+            c: (f) => ({ ...f, teams: !f.teams }),
+            a: (f) => ({ ...f, agent: cycle(f.agent, agentsInPool) }),
+            d: (f) => ({ ...f, device: cycle(f.device, devicesInPool) }),
+            p: (f) => ({ ...f, projectScope: f.projectScope === 'repo' ? 'all' : 'repo' }),
+            w: (f) => ({ ...f, window: cycleWindow(f.window) }),
+        },
+        onKey: (name, f, _active, query) => {
+            if (name === 'y') {
+                // Thread the live search query so the copied command reproduces the
+                // exact view — the human→agent bridge must include the search term.
+                const cmd = 'ag ' + browserFilterToArgv(f, query).join(' ');
+                const ok = copyToClipboard(cmd);
+                return ok ? `copied: ${cmd}` : cmd;
+            }
+            return undefined;
+        },
+    });
+    if (!picked)
+        return;
+    await handlePickedSession({ session: picked.item, action: 'resume' });
+}

package/dist/commands/sessions.d.ts

@@ -193,6 +193,7 @@ export declare function formatPickerLabel(s: SessionMeta, query: string, cols?:
  */
 export declare function formatPickerTip(sessions: SessionMeta[]): string;
 export declare function pickSessionInteractive(sessions: SessionMeta[], message?: string, initialSearch?: string, hiddenCount?: number, enterHint?: string): Promise<PickedSession | null>;
+export declare function handlePickedSession(picked: PickedSession): Promise<void>;
 /**
  * Resume a session in the current terminal — a foreground takeover of this
  * process. Used by the single-select picker and by `sessions resume` when the

package/dist/commands/sessions.js

@@ -37,7 +37,7 @@ import { colorAgent, resolveAgentName } from '../lib/agents.js';
 import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { resolveVersionAliasLoose } from '../lib/versions.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
-import { sessionPicker } from './sessions-picker.js';
+import { sessionPicker, buildPreview } from './sessions-picker.js';
 import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
 import { registerSessionsSyncCommand } from './sessions-sync.js';
@@ -790,6 +790,57 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
 function printCrossMachineTip() {
     console.log(chalk.gray("\nTip: include sessions from your other machines — register them with 'ag devices sync', then rerun. Use --local to skip."));
 }
+/**
+ * True when the interactive session browser should open instead of a printed
+ * listing: a real TTY, no `--json`, and `--no-interactive` not set. The bare
+ * listing and `--active` both default to it; scripts/pipes/agents fall through
+ * to the existing printed/JSON paths.
+ */
+function useInteractiveBrowser(options) {
+    return options.interactive !== false && !options.json && isInteractiveTerminal();
+}
+/** The canonical `ag sessions …` command for a set of flags — the twin of the
+ * browser's `y` hotkey (see --print-cmd). Normalizes to the stable flag form. */
+function canonicalSessionsCommand(query, options) {
+    const a = ['sessions'];
+    if (options.active)
+        a.push('--active');
+    if (options.teams)
+        a.push('--teams');
+    if (options.agent)
+        a.push('-a', options.agent);
+    for (const h of options.host ?? [])
+        a.push('--device', h);
+    if (options.project)
+        a.push('--project', options.project);
+    if (options.all)
+        a.push('--all');
+    if (options.since)
+        a.push('--since', options.since);
+    if (options.until)
+        a.push('--until', options.until);
+    if (options.local)
+        a.push('--local');
+    if (options.waiting)
+        a.push('--waiting');
+    const q = (query ?? '').trim();
+    if (q)
+        a.push(JSON.stringify(q));
+    return 'ag ' + a.join(' ');
+}
+/** Resolve a session by id/query globally and print its compact preview (no pager).
+ * Backs `--preview` — the fast path for the "peek before resume" hot loop. */
+async function renderSessionPreview(query, scope) {
+    const discovered = await discoverSessions({ all: true, cwd: process.cwd(), limit: 5000 });
+    const pool = applyScopeFilters(discovered, scope);
+    const matches = resolveSessionById(pool, query);
+    const session = (matches.length > 0 ? matches : filterSessionsByQuery(pool, query))[0];
+    if (!session) {
+        console.log(chalk.gray(`No session matches "${query}".`));
+        return;
+    }
+    console.log(buildPreview(session));
+}
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
     // Explicit --query is interchangeable with the positional; it's how you search
@@ -802,6 +853,13 @@ async function sessionsAction(query, options) {
     if (options.device && options.device.length > 0) {
         options.host = [...(options.host ?? []), ...options.device];
     }
+    // --print-cmd: echo the canonical `ag sessions …` for the given flags and exit.
+    // The non-interactive twin of the browser's `y` hotkey — lets an agent compose
+    // (or a human copy) the exact command a view maps to.
+    if (options.printCmd) {
+        process.stdout.write(canonicalSessionsCommand(query, options) + '\n');
+        return;
+    }
     // --roots: emit the local session-scan directories, per agent, as JSON. A pure
     // machine-readable query (no listing/render) — external watchers (the Factory
     // extension's fs.watch) read it to track the same dirs the CLI scans, instead
@@ -830,7 +888,39 @@ async function sessionsAction(query, options) {
         }
         return;
     }
+    // --preview <id/query>: resolve one session and print its compact preview, then
+    // exit — checked before --active so `--active --preview <id>` peeks the id
+    // rather than being swallowed by the active listing.
+    if (options.preview) {
+        if (!query) {
+            console.error(chalk.red('--preview requires a session id or query.'));
+            process.exit(1);
+        }
+        await renderSessionPreview(query, { agent: options.agent, project: options.project });
+        return;
+    }
     if (options.active) {
+        // On a TTY (and not a scripting path), open the interactive browser seeded to
+        // running-only. --json / --waiting / --no-interactive / a peer fan-out keep the
+        // static dump untouched, so scripts and agents are unaffected. An explicit
+        // --since seeds the window; --until / --project (no browser field) or a
+        // multi-host scope fall through to the static dump that already honors them.
+        if (useInteractiveBrowser(options) &&
+            !options.waiting &&
+            !options.until &&
+            !options.project &&
+            !options.sort &&
+            (options.host?.length ?? 0) <= 1 &&
+            process.env.AGENTS_SESSIONS_LOCAL !== '1') {
+            const { runSessionBrowser, activeBrowserSeed } = await import('./sessions-browser.js');
+            await runSessionBrowser(activeBrowserSeed({
+                teams: options.teams,
+                agent: options.agent,
+                host: options.host,
+                since: options.since,
+            }), { local: options.local === true, hosts: options.host });
+            return;
+        }
         // AGENTS_SESSIONS_LOCAL is set by a parent fan-out invocation (see
         // remote-active.ts) so a peer answers for itself without recursing.
         const forceLocal = options.local === true || process.env.AGENTS_SESSIONS_LOCAL === '1';
@@ -844,6 +934,30 @@ async function sessionsAction(query, options) {
         await runCloudSessions(query, options);
         return;
     }
+    // Bare interactive listing → the interactive fleet browser (humans). A query,
+    // a render/filter flag, --flat/--tree, --json, --until, --project (a named-project
+    // filter the browser can't represent), or --no-interactive keep the existing
+    // printed/render paths (agents and scripts unaffected). An explicit --since seeds
+    // the browser's window so the flag is honored, not swallowed.
+    if (useInteractiveBrowser(options) &&
+        !query &&
+        !options.flat &&
+        !options.tree &&
+        !options.markdown &&
+        !options.until &&
+        !options.project &&
+        !options.sort &&
+        !options.artifacts &&
+        options.artifact === undefined) {
+        const { runSessionBrowser, bareBrowserSeed } = await import('./sessions-browser.js');
+        await runSessionBrowser(bareBrowserSeed({
+            teams: options.teams,
+            agent: options.agent,
+            all: options.all,
+            since: options.since,
+        }), { local: options.local === true, hosts: options.host });
+        return;
+    }
     let filterOpts;
     try {
         filterOpts = buildFilterOptions(options);
@@ -1559,7 +1673,7 @@ function warnNoPeerTarget(machine, session) {
     console.log(chalk.yellow(`Session ${session.shortId} lives on ${machine}, which isn't a reachable device right now.`));
     console.log(chalk.gray(`Register/wake it (ag devices), or run there: agents ssh ${machine}`));
 }
-async function handlePickedSession(picked) {
+export async function handlePickedSession(picked) {
     // A session on another machine is read/resumed ON that machine over SSH — its
     // transcript and agent binary live there. Both actions execute on the peer
     // (not a local `--host` hop, which would discover locally and dead-end for a
@@ -2075,7 +2189,7 @@ export function registerSessionsCommands(program) {
         .option('--opencode', 'Shorthand for --agent opencode')
         .option('--all', 'Include sessions from every directory (not just current project)')
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
-        .option('--project <name>', 'Filter by project name (searches across all directories)')
+        .option('-p, --project <name>', 'Filter by project name (searches across all directories)')
         .option('--since <time>', 'Only sessions newer than this (e.g., 2h, 7d, 4w, or ISO date)')
         .option('--until <time>', 'Only sessions older than this (ISO timestamp)')
         .option('-n, --limit <n>', 'Maximum number of sessions to return', '50')
@@ -2099,7 +2213,10 @@ export function registerSessionsCommands(program) {
         .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
         .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)')
         .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable)')
-        .option('--browser', 'List browser-profile captures (screenshots, PDFs, recordings, downloads) instead of agent transcripts — alias of `agents browser sessions`');
+        .option('--browser', 'List browser-profile captures (screenshots, PDFs, recordings, downloads) instead of agent transcripts — alias of `agents browser sessions`')
+        .option('--no-interactive', 'Print the listing instead of opening the interactive browser (default on a TTY for the bare listing and --active)')
+        .option('--print-cmd', 'Print the canonical `ag sessions …` command for the given flags and exit (the twin of the browser’s `y` hotkey)')
+        .option('--preview', 'With a session id/query: print a compact preview and exit (no pager)');
     setHelpSections(sessionsCmd, {
         examples: `
       # Search prior sessions in this project by topic, file path, or command

package/dist/commands/share.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerShareCommands(program: Command): void;

package/dist/commands/share.js

@@ -0,0 +1,150 @@
+// `agents share` — publish an HTML file to your own Cloudflare R2 behind a tiny
+// Worker, and get a shareable link (~$0). See apps/cli/docs/share.md.
+import { existsSync } from 'node:fs';
+import chalk from 'chalk';
+import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_WORKER_NAME, generateWriteToken, readCloudflareCreds, readShareConfig, storeWriteToken, writeShareConfig, } from '../lib/share/config.js';
+import { addCustomDomain, createBucket, deployWorker, enableWorkersDev, findZoneId, } from '../lib/share/provision.js';
+import { publishFile } from '../lib/share/publish.js';
+import { renderWorkerScript } from '../lib/share/worker-template.js';
+export function registerShareCommands(program) {
+    const shareCmd = program
+        .command('share')
+        .description('Publish an HTML file to your own Cloudflare R2 and get a shareable link (~$0).')
+        .argument('[file]', 'file to publish (HTML or any static asset)')
+        .option('--slug <slug>', 'custom URL slug (default: <project>-<feature>-<hash>)')
+        .option('--expire <spec>', 'auto-expire, e.g. 30d, 12h, or 2026-08-01')
+        .option('--no-cover', 'skip the OG preview image (HTML pages get one by default)')
+        .action(async (file, opts) => {
+        if (!file) {
+            shareCmd.help();
+            return;
+        }
+        if (!existsSync(file)) {
+            console.error(chalk.red(`No such file: ${file}`));
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const { url, expiresAt, coverUrl } = await publishFile(file, {
+                slug: opts.slug,
+                expire: opts.expire,
+                cover: opts.cover,
+            });
+            console.log(chalk.green(url));
+            if (coverUrl)
+                console.log(chalk.dim(`  cover ${coverUrl}`));
+            if (expiresAt)
+                console.log(chalk.dim(`  expires ${new Date(expiresAt).toLocaleString()}`));
+        }
+        catch (e) {
+            console.error(chalk.red(e.message));
+            process.exitCode = 1;
+        }
+    });
+    shareCmd
+        .command('setup')
+        .description('One-time: provision an R2 bucket + Worker on your Cloudflare and save the config.')
+        .option('--bundle <name>', 'secrets bundle holding the Cloudflare API token', DEFAULT_CF_BUNDLE)
+        .option('--worker <name>', 'Worker name', DEFAULT_WORKER_NAME)
+        .option('--bucket <name>', 'R2 bucket name', DEFAULT_BUCKET_NAME)
+        .option('--account <id>', 'Cloudflare account id (else read from the bundle / prompt)')
+        .option('--token <t>', 'Cloudflare API token (else read from the --bundle)')
+        .option('--domain <host>', 'also map a custom domain (e.g. share.agents-cli.sh) if the token owns the zone')
+        .action(async (opts) => {
+        try {
+            await runSetup(opts);
+        }
+        catch (e) {
+            console.error(chalk.red(e.message));
+            process.exitCode = 1;
+        }
+    });
+    shareCmd
+        .command('join')
+        .description('Use an existing share endpoint (no provisioning) — pass the base URL and paste the write token.')
+        .argument('<baseUrl>', 'base URL of the endpoint, e.g. https://share.agents-cli.sh')
+        .action(async (baseUrl) => {
+        try {
+            await runJoin(baseUrl);
+        }
+        catch (e) {
+            console.error(chalk.red(e.message));
+            process.exitCode = 1;
+        }
+    });
+    shareCmd
+        .command('status')
+        .description('Show the configured share endpoint.')
+        .action(() => {
+        const cfg = readShareConfig();
+        if (!cfg) {
+            console.log(chalk.dim("Not configured. Run 'agents share setup' or 'agents share join'."));
+            return;
+        }
+        console.log(`${chalk.bold('endpoint')}  ${chalk.green(cfg.baseUrl)}`);
+        console.log(chalk.dim(`worker ${cfg.workerName} · bucket ${cfg.bucketName} · account ${cfg.accountId}`));
+    });
+}
+async function runSetup(opts) {
+    const { default: ora } = await import('ora');
+    const { input } = await import('@inquirer/prompts');
+    const { apiToken, accountId: acctFromBundle } = readCloudflareCreds(opts.bundle, {
+        apiToken: opts.token,
+        accountId: opts.account,
+    });
+    const accountId = opts.account || acctFromBundle || (await input({ message: 'Cloudflare account id' }));
+    if (!accountId)
+        throw new Error('A Cloudflare account id is required.');
+    const workerName = opts.worker;
+    const bucketName = opts.bucket;
+    const token = generateWriteToken();
+    const spin = ora('Provisioning on Cloudflare…').start();
+    try {
+        await createBucket(apiToken, accountId, bucketName);
+        spin.text = `R2 bucket '${bucketName}' ready`;
+        await deployWorker(apiToken, accountId, workerName, renderWorkerScript(), bucketName, token);
+        spin.text = `Worker '${workerName}' deployed`;
+        const subdomain = await enableWorkersDev(apiToken, accountId, workerName);
+        let baseUrl = `https://${workerName}.${subdomain}.workers.dev`;
+        let domain;
+        if (opts.domain) {
+            spin.text = `Mapping ${opts.domain}…`;
+            const zoneId = await findZoneId(apiToken, opts.domain);
+            if (zoneId) {
+                await addCustomDomain(apiToken, accountId, workerName, zoneId, opts.domain);
+                baseUrl = `https://${opts.domain}`;
+                domain = opts.domain;
+            }
+            else {
+                spin.warn(`Zone for ${opts.domain} not visible to this token — staying on workers.dev`);
+            }
+        }
+        spin.succeed('Provisioned');
+        const cfg = { baseUrl, accountId, workerName, bucketName, domain };
+        writeShareConfig(cfg);
+        storeWriteToken(token);
+        console.log(chalk.green(`\nShare endpoint ready → ${chalk.bold(baseUrl)}`));
+        console.log(chalk.dim('Publish with:  ') + chalk.cyan('agents share <file>'));
+        console.log(chalk.dim(`Fleet: push the token with 'agents secrets export share --host <box>' and pull config with 'agents repo pull'.`));
+    }
+    catch (e) {
+        spin.fail('Provisioning failed');
+        throw e;
+    }
+}
+async function runJoin(baseUrl) {
+    const { password, input } = await import('@inquirer/prompts');
+    const clean = baseUrl.replace(/\/+$/, '');
+    const workerName = await input({ message: 'Worker name', default: DEFAULT_WORKER_NAME });
+    const bucketName = await input({ message: 'Bucket name', default: DEFAULT_BUCKET_NAME });
+    const accountId = await input({ message: 'Cloudflare account id' });
+    const token = await password({ message: 'Write token (from the endpoint owner)', mask: true });
+    if (!token)
+        throw new Error('A write token is required to join.');
+    const domain = clean.startsWith('https://') && !clean.includes('.workers.dev')
+        ? clean.replace(/^https:\/\//, '')
+        : undefined;
+    writeShareConfig({ baseUrl: clean, accountId, workerName, bucketName, domain });
+    storeWriteToken(token);
+    console.log(chalk.green(`Joined ${chalk.bold(clean)} — publish with `) + chalk.cyan('agents share <file>'));
+}