@phnx-labs/agents-cli 1.20.64 → 1.20.66

package/dist/commands/sessions-browser.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 type { SessionMeta } from '../lib/session/types.js';
+/**
+ * The single canonical filter state. Every field has a flag equivalent, so the
+ * same view is reachable interactively (hotkeys) or from the command line (flags).
+ */
+export interface BrowserFilter {
+    /** running-only — the `R` key / `--active`. */
+    running: boolean;
+    /** include team-spawned sessions — the `C` key / `--teams`. */
+    teams: boolean;
+    /** filter to one agent, or all — the `A` key / `-a`. */
+    agent?: string;
+    /** filter to one machine, or all — the `D` key / `--device`. */
+    device?: string;
+    /** this-repo subtree vs every directory — the `P` key / `--all`. */
+    projectScope: 'repo' | 'all';
+    /** time window (undefined = all time) — the `W` key / `--since`. */
+    window?: string;
+}
+/** Return the next value in `[undefined, ...options]`, wrapping. */
+export declare function cycle(current: string | undefined, options: string[]): string | undefined;
+export declare function cycleWindow(current: string | undefined): string | undefined;
+/**
+ * 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 declare function sessionMatchesQuery(s: SessionMeta, query: string): boolean;
+/**
+ * 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 declare function browserFilterToArgv(f: BrowserFilter, query?: string): string[];
+/** 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 declare function normalizeDeviceSeed(host: string | undefined): string | undefined;
+/**
+ * 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 declare function activeBrowserSeed(opts: {
+    teams?: boolean;
+    agent?: string;
+    host?: string[];
+    since?: string;
+}): Partial<BrowserFilter>;
+/**
+ * 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 declare function bareBrowserSeed(opts: {
+    teams?: boolean;
+    agent?: string;
+    all?: boolean;
+    since?: string;
+}): Partial<BrowserFilter>;
+/**
+ * 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 declare function runSessionBrowser(initial?: Partial<BrowserFilter>, opts?: {
+    local?: boolean;
+    hosts?: string[];
+}): Promise<void>;

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-export.js

@@ -27,7 +27,8 @@ import { machineId } from '../lib/machine-id.js';
 import { getHistoryDir } from '../lib/state.js';
 import { loadR2Config } from '../lib/session/sync/config.js';
 import { resolveSyncEncKey, generateSyncEncKey } from '../lib/session/sync/transcript-crypto.js';
-import { buildRecord, makeHeader, mergeRecords, serializeBundle, specForAgent, } from '../lib/session/bundle.js';
+import { buildRecord, makeHeader, mergeRecords, serializeBundle, writeBundleFile, specForAgent, } from '../lib/session/bundle.js';
+import { knownSecretValuesFromEnv } from '../lib/redact.js';
 import { pullBundlesFromHosts } from '../lib/session/remote-bundle.js';
 import { setHelpSections } from '../lib/help.js';
 /** Default cap when exporting a scope (not explicit ids) and the user gave no -n. */
@@ -119,11 +120,15 @@ async function runExport(selectors, command) {
     // 4. Resolve encryption key (opt-in) + redaction (default on via parent --no-redact).
     const encryptKey = g.encrypt ? resolveExportKey() : null;
     const redact = g.redact !== false;
+    // Value-aware redaction: mask live credential values already in the
+    // environment (e.g. an injected secrets bundle) verbatim, whatever their
+    // format. Only meaningful when redacting.
+    const knownSecrets = redact ? knownSecretValuesFromEnv() : undefined;
     // 5. Build records + header.
     const records = [];
     for (const f of files) {
         try {
-            records.push(buildRecord(f, { redact, encryptKey }));
+            records.push(buildRecord(f, { redact, encryptKey, knownSecrets }));
         }
         catch (err) {
             process.stderr.write(chalk.yellow(`Skipped ${f.agent}/${f.sessionId} (${f.relKey}): ${err.message}\n`));
@@ -193,7 +198,7 @@ function emitBundle(header, records, g) {
         return;
     }
     const outPath = g.output || defaultBundlePath();
-    fs.writeFileSync(outPath, wire, 'utf-8');
+    writeBundleFile(outPath, wire);
     process.stderr.write(chalk.green(`Exported ${header.sessions} session${header.sessions === 1 ? '' : 's'} ` +
         `(${header.count} file${header.count === 1 ? '' : 's'}${header.encrypted ? ', encrypted' : ''}${header.redacted ? ', redacted' : ''}) ` +
         `→ ${outPath}\n`));

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
@@ -201,6 +202,22 @@ export declare function pickSessionInteractive(sessions: SessionMeta[], message?
  * binary is missing (ENOENT).
  */
 export declare function resumeSessionInPlace(session: SessionMeta): Promise<void>;
+/**
+ * Map a resume argv to the spawn(command, args, {shell}) triple.
+ *
+ * On Windows the agent launcher is a `.cmd`/PATHEXT shim and needs shell:true.
+ * With shell:true, Node concatenates args into the cmd.exe line unescaped
+ * (DEP0190 + injection). A session.id derived from a filename can carry
+ * metacharacters (`&|<>`); compose a fully-quoted line and pass an EMPTY args
+ * array so cmd.exe cannot reparse them (RUSH-1753). See composeWin32CommandLine.
+ *
+ * `platform` is injectable so the win32 shell path is unit-testable on any host.
+ */
+export declare function resumeSpawnInvocation(cmd: string[], platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+    shell: boolean;
+};
 /**
  * Build the shell command that resumes a picked session.
  *