@phnx-labs/agents-cli 1.20.27 → 1.20.29

package/dist/lib/secrets/remote.js

@@ -0,0 +1,133 @@
+/**
+ * Remote secrets — read and use `agents secrets` bundles that live on another
+ * host, over the same hardened SSH path that `agents secrets export --host`
+ * (the write inverse) already uses.
+ *
+ * This is the READ / USE direction:
+ *   - browse:  drive the remote `agents secrets list|view` and stream its
+ *              stdout back verbatim (lossless, no parsing).
+ *   - use:     resolve a remote bundle to an env map (JSON over ssh stdout) and
+ *              inject it ephemerally — never written to this machine's keychain.
+ *
+ * Trust model: relies on the operator's existing SSH access to the host (same
+ * boundary as `export --host` / `run --host`). Bundle names are shell-quoted
+ * into the remote command; resolved VALUES return over ssh stdout; a forwarded
+ * file-backend passphrase travels over ssh stdin (first line) so it never lands
+ * in argv / `ps` / remote shell history. Nothing is persisted locally.
+ */
+import { sshExec, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { resolveHost } from '../hosts/registry.js';
+import { sshTargetFor } from '../hosts/types.js';
+const REMOTE_TIMEOUT_MS = 30_000;
+/**
+ * Resolve a `--host` value to an ssh target string. Tries the `agents hosts`
+ * registry first (enrolled name → ssh-config alias / `user@host`); on a miss,
+ * treats the value as a raw ssh target and validates it against injection.
+ */
+export async function resolveSshTarget(nameOrAlias) {
+    const host = await resolveHost(nameOrAlias);
+    if (host)
+        return sshTargetFor(host);
+    assertValidSshTarget(nameOrAlias);
+    return nameOrAlias;
+}
+/**
+ * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
+ * list. Both flags compose; either alone works. Empty when neither is set.
+ */
+export function parseHostsOption(opts) {
+    const out = [];
+    const seen = new Set();
+    const push = (h) => {
+        const t = h.trim();
+        if (t && !seen.has(t)) {
+            seen.add(t);
+            out.push(t);
+        }
+    };
+    if (opts.host)
+        push(opts.host);
+    if (opts.hosts)
+        for (const h of opts.hosts.split(','))
+            push(h);
+    return out;
+}
+/**
+ * Split a `bundle@host` reference. No `@` → a local bundle (host undefined).
+ * Bundle names can't contain `@` (BUNDLE_NAME_PATTERN), so the FIRST `@`
+ * separates the bundle from the ssh target — and the target itself may be a
+ * `user@host` (e.g. `r2.backups@muqsit@box` → bundle `r2.backups`, host
+ * `muqsit@box`).
+ */
+export function splitBundleRef(ref) {
+    const at = ref.indexOf('@');
+    if (at === -1)
+        return { bundle: ref };
+    const bundle = ref.slice(0, at);
+    const host = ref.slice(at + 1);
+    if (!bundle || !host) {
+        throw new Error(`Invalid remote bundle reference ${JSON.stringify(ref)}. Expected 'bundle@host'.`);
+    }
+    return { bundle, host };
+}
+/**
+ * Run `agents secrets <args>` on a remote host over ssh and return the raw
+ * result. Used by the browse commands — the remote's human-readable stdout is
+ * streamed back unchanged. `tty` forces an interactive ssh session (`-tt`) so a
+ * remote Touch-ID / passphrase prompt can surface (e.g. `view --reveal`).
+ */
+export function remoteSecretsRaw(target, args, opts = {}) {
+    const inner = ['agents', 'secrets', ...args].map(shellQuote).join(' ');
+    const remoteCmd = `bash -lc ${shellQuote(inner)}`;
+    return sshExec(target, remoteCmd, {
+        timeoutMs: REMOTE_TIMEOUT_MS,
+        input: opts.input,
+        extraSshArgs: opts.tty ? ['-tt'] : undefined,
+    });
+}
+/**
+ * Resolve a remote bundle to a plaintext env map by driving the remote's
+ * `agents secrets export <bundle> --plaintext --format json`. Values cross over
+ * ssh stdout (encrypted in transit), parsed in memory, never persisted.
+ *
+ * The remote unlocks the bundle with ITS OWN credentials — the owner host's
+ * keychain/secrets-agent, or its own `AGENTS_SECRETS_PASSPHRASE` (in the login
+ * env) for a file-backed bundle. We deliberately do NOT forward this machine's
+ * passphrase: the remote bundle is encrypted with the remote's passphrase, so
+ * overriding it would break the read. (A macOS remote under non-interactive
+ * SSH will block on Touch-ID — use `view`/`exec` with a remote `file` bundle,
+ * an already-unlocked remote secrets-agent, or an interactive `-tt` session.)
+ */
+export async function remoteResolveEnv(target, bundle) {
+    assertValidSshTarget(target);
+    const exportCmd = `agents secrets export ${shellQuote(bundle)} --plaintext --format json`;
+    const res = sshExec(target, `bash -lc ${shellQuote(exportCmd)}`, {
+        timeoutMs: REMOTE_TIMEOUT_MS,
+    });
+    if (res.code !== 0) {
+        const msg = (res.stderr || res.stdout || '').trim();
+        const why = res.timedOut ? 'timed out' : res.code === null ? 'ssh failed' : `exit ${res.code}`;
+        throw new Error(`Failed to resolve '${bundle}' on ${target} (${why})${msg ? `: ${msg}` : ''}`);
+    }
+    // Tolerate login-shell banner noise on stdout: take the outer { … } object.
+    const raw = res.stdout;
+    const start = raw.indexOf('{');
+    const end = raw.lastIndexOf('}');
+    const jsonText = start >= 0 && end >= start ? raw.slice(start, end + 1) : raw.trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch {
+        throw new Error(`Could not parse secrets JSON from '${bundle}' on ${target}. ` +
+            `Is the remote agents-cli new enough for 'secrets export --format json'?`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Unexpected payload resolving '${bundle}' on ${target}.`);
+    }
+    const env = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        env[k] = typeof v === 'string' ? v : String(v);
+    }
+    return env;
+}

package/dist/lib/self-update.js

@@ -16,6 +16,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
 import { compareVersions } from './versions.js';
+import { needsWindowsShell } from './platform/index.js';
 export const NPM_PACKAGE_NAME = '@phnx-labs/agents-cli';
 /**
  * The directory bun installs global packages into:
@@ -145,7 +146,10 @@ export async function installPackageIntoPrefix(spec, prefix) {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');
     const execFileAsync = promisify(execFile);
-    await execFileAsync('npm', ['install', '-g', '--prefix', prefix, spec, '--ignore-scripts']);
+    // On Windows `npm` is `npm.cmd`; execFile cannot run it without a shell (ENOENT).
+    await execFileAsync('npm', ['install', '-g', '--prefix', prefix, spec, '--ignore-scripts'], {
+        shell: needsWindowsShell('npm'),
+    });
 }
 /**
  * Install `spec` into bun's global store with `bun add -g`. bun writes to
@@ -159,7 +163,8 @@ export async function installPackageWithBun(spec) {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');
     const execFileAsync = promisify(execFile);
-    await execFileAsync('bun', ['add', '-g', spec]);
+    // On Windows `bun` resolves to `bun.exe`/`bun.cmd`; force shell for the .cmd case.
+    await execFileAsync('bun', ['add', '-g', spec], { shell: needsWindowsShell('bun') });
 }
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
 export function readInstalledVersion(packageRoot) {

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

@@ -35,6 +35,7 @@ export interface SessionRow {
 export interface ScanStamp {
     fileMtimeMs: number;
     fileSize: number;
+    scannedAt?: number;
 }
 /** Filter and pagination options for querying the sessions table. */
 export interface QueryOptions {
@@ -45,6 +46,10 @@ export interface QueryOptions {
     /** Match any session whose cwd equals this or is a descendant of it. */
     cwdPrefix?: string;
     project?: string;
+    /** Match the full session id or short id, case-insensitively (exact). */
+    idExact?: string;
+    /** Match sessions whose id or short id begins with this (case-insensitive prefix). */
+    idPrefix?: string;
     sinceMs?: number;
     untilMs?: number;
     limit?: number;
@@ -118,6 +123,16 @@ export declare function upsertSessionsBatch(entries: Array<{
  * Leaves FTS5 content/topic/project untouched — cheap to call every run.
  */
 export declare function syncLabels(labelMap: Map<string, string | null>): number;
+/**
+ * Sync topics (session titles) for a set of sessions, keyed by id. For agents
+ * whose human-readable title lives in a side index that updates independently
+ * of the transcript (Codex `session_index.jsonl`), the per-file scan can't see
+ * a title that lands later. This applies those titles by id, updating both
+ * `sessions.topic` and the FTS5 topic column. Only ever sets a non-empty title
+ * and only when it differs from the stored value — cheap to call every run.
+ * Returns the number of rows updated.
+ */
+export declare function syncTopics(topicMap: Map<string, string>): number;
 /** Query sessions from the database, applying filters and ordering by timestamp descending. */
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
 /** Count sessions matching the given filter options. */
@@ -160,6 +175,15 @@ export declare function getAllFilePaths(): Set<string>;
 export declare function getSessionsByFilePaths(paths: string[]): Map<string, SessionMeta>;
 /** Look up a single session by its unique ID. */
 export declare function getSessionById(id: string): SessionMeta | null;
+/**
+ * Resolve a full-or-partial session id against the index, exact-first then
+ * prefix — the DB-backed equivalent of resolveSessionById() that runs over the
+ * SQLite table instead of a pre-loaded array. Matches both the full id and the
+ * short id. An exact hit short-circuits so a complete id never also drags in its
+ * prefix siblings. `scope` narrows by agent / version / project (cwd) so an
+ * ambiguous prefix disambiguates against the caller's context.
+ */
+export declare function findSessionsById(idQuery: string, scope?: Pick<QueryOptions, 'agent' | 'version' | 'cwd' | 'project'>): SessionMeta[];
 /** A single full-text search result with ranking score. */
 export interface FtsHit {
     sessionId: string;

package/dist/lib/session/db.js

@@ -65,6 +65,7 @@ CREATE INDEX IF NOT EXISTS idx_sessions_timestamp ON sessions(timestamp DESC);
 CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd);
 CREATE INDEX IF NOT EXISTS idx_sessions_agent ON sessions(agent);
 CREATE INDEX IF NOT EXISTS idx_sessions_file_path ON sessions(file_path);
+CREATE INDEX IF NOT EXISTS idx_sessions_short_id ON sessions(short_id);
 
 CREATE VIRTUAL TABLE IF NOT EXISTS session_text USING fts5(
   session_id UNINDEXED,
@@ -289,9 +290,9 @@ export function getDBPath() {
 export function getScanStampByPath(filePath) {
     const db = getDB();
     const row = db
-        .prepare(`SELECT file_mtime_ms, file_size FROM scan_ledger WHERE file_path = ? LIMIT 1`)
+        .prepare(`SELECT file_mtime_ms, file_size, scanned_at FROM scan_ledger WHERE file_path = ? LIMIT 1`)
         .get(canonicalLedgerKey(filePath));
-    return row ? { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size } : null;
+    return row ? { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size, scannedAt: row.scanned_at } : null;
 }
 /**
  * Bulk-load the stamp ledger for a set of file paths in a single SQL query.
@@ -323,13 +324,13 @@ export function getScanStampsForPaths(filePaths) {
         const placeholders = chunk.map(() => '?').join(',');
         const rows = db
             .prepare(`
-        SELECT file_path, file_mtime_ms, file_size
+        SELECT file_path, file_mtime_ms, file_size, scanned_at
         FROM scan_ledger
         WHERE file_path IN (${placeholders})
       `)
             .all(...chunk);
         for (const row of rows) {
-            const stamp = { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size };
+            const stamp = { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size, scannedAt: row.scanned_at };
             for (const original of canonicalToOriginals.get(row.file_path) || []) {
                 result.set(original, stamp);
             }
@@ -558,6 +559,48 @@ export function syncLabels(labelMap) {
     txn(updates);
     return updates.length;
 }
+/**
+ * Sync topics (session titles) for a set of sessions, keyed by id. For agents
+ * whose human-readable title lives in a side index that updates independently
+ * of the transcript (Codex `session_index.jsonl`), the per-file scan can't see
+ * a title that lands later. This applies those titles by id, updating both
+ * `sessions.topic` and the FTS5 topic column. Only ever sets a non-empty title
+ * and only when it differs from the stored value — cheap to call every run.
+ * Returns the number of rows updated.
+ */
+export function syncTopics(topicMap) {
+    if (topicMap.size === 0)
+        return 0;
+    const db = getDB();
+    const ids = [...topicMap.keys()];
+    const CHUNK = 500;
+    const updates = [];
+    for (let i = 0; i < ids.length; i += CHUNK) {
+        const chunk = ids.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => '?').join(',');
+        const rows = db
+            .prepare(`SELECT id, topic FROM sessions WHERE id IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows) {
+            const live = topicMap.get(row.id) ?? '';
+            if (live && live !== (row.topic ?? '')) {
+                updates.push({ id: row.id, topic: live });
+            }
+        }
+    }
+    if (updates.length === 0)
+        return 0;
+    const updSessions = db.prepare(`UPDATE sessions SET topic = ? WHERE id = ?`);
+    const updFts = db.prepare(`UPDATE session_text SET topic = ? WHERE session_id = ?`);
+    const txn = db.transaction((items) => {
+        for (const { id, topic } of items) {
+            updSessions.run(topic, id);
+            updFts.run(topic, id);
+        }
+    });
+    txn(updates);
+    return updates.length;
+}
 /** Convert a raw database row into a SessionMeta object. */
 function rowToMeta(row) {
     return {
@@ -601,13 +644,28 @@ function buildSessionWhere(options) {
         params.push(options.cwd);
     }
     if (options.cwdPrefix) {
+        // Stored cwd uses the host path separator (normalizeCwd → path.resolve), so
+        // the subdir wildcard must too — a hardcoded '/' never matches a Windows
+        // `C:\a\b` subpath and the listing comes back empty.
         where.push('(cwd = ? OR cwd LIKE ?)');
-        params.push(options.cwdPrefix, options.cwdPrefix + '/%');
+        params.push(options.cwdPrefix, options.cwdPrefix + path.sep + '%');
     }
     if (options.project) {
         where.push('LOWER(IFNULL(project, \'\')) LIKE ?');
         params.push(`%${options.project.toLowerCase()}%`);
     }
+    // id lookup. SQLite's LIKE is case-insensitive for ASCII, so a lowercased
+    // pattern matches mixed-case ids; the `=` exact compare adds COLLATE NOCASE
+    // for the same reason. short_id carries its own index (idx_sessions_short_id);
+    // id is the PRIMARY KEY.
+    if (options.idExact) {
+        where.push('(id = ? COLLATE NOCASE OR short_id = ? COLLATE NOCASE)');
+        params.push(options.idExact, options.idExact);
+    }
+    if (options.idPrefix) {
+        where.push('(id LIKE ? OR short_id LIKE ?)');
+        params.push(`${options.idPrefix}%`, `${options.idPrefix}%`);
+    }
     if (typeof options.sinceMs === 'number') {
         // Compare as strings; ISO 8601 timestamps sort lexicographically.
         where.push('timestamp >= ?');
@@ -739,6 +797,23 @@ export function getSessionById(id) {
     const row = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id);
     return row ? rowToMeta(row) : null;
 }
+/**
+ * Resolve a full-or-partial session id against the index, exact-first then
+ * prefix — the DB-backed equivalent of resolveSessionById() that runs over the
+ * SQLite table instead of a pre-loaded array. Matches both the full id and the
+ * short id. An exact hit short-circuits so a complete id never also drags in its
+ * prefix siblings. `scope` narrows by agent / version / project (cwd) so an
+ * ambiguous prefix disambiguates against the caller's context.
+ */
+export function findSessionsById(idQuery, scope = {}) {
+    const q = idQuery.trim();
+    if (!q)
+        return [];
+    const exact = querySessions({ ...scope, idExact: q });
+    if (exact.length > 0)
+        return exact;
+    return querySessions({ ...scope, idPrefix: q });
+}
 /**
  * Escape a raw user query into a safe FTS5 MATCH expression.
  * Splits on non-word characters, keeps tokens >= 2 chars, and OR-joins

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

@@ -7,6 +7,7 @@
  * subsequent queries are served entirely from the cache.
  */
 import type { SessionAgentId, SessionMeta } from './types.js';
+import { type ScanStamp } from './db.js';
 /** Options controlling which sessions to discover and how to report progress. */
 export interface DiscoverOptions {
     agent?: SessionAgentId;
@@ -36,6 +37,27 @@ export interface ScanProgress {
     parsed: number;
     total: number;
 }
+/** Lightweight metadata extracted from a Claude JSONL file during incremental scan. */
+interface ClaudeSessionScan {
+    timestamp?: string;
+    cwd?: string;
+    gitBranch?: string;
+    version?: string;
+    topic?: string;
+    messageCount: number;
+    tokenCount?: number;
+    /** Total USD cost accumulated from per-(model, direction) token usage. */
+    costUsd?: number;
+    /** Wall-clock duration in ms between the first and last timestamped event. */
+    durationMs?: number;
+    /**
+     * Value of the JSONL `entrypoint` field on the first event that carries it.
+     * 'cli' for real interactive sessions, 'sdk-cli' for team-spawned ones.
+     */
+    entrypoint?: string;
+    /** Concatenated user message text, ready to hand to FTS5. */
+    contentText?: string;
+}
 /**
  * Discover sessions. Scans only files whose (mtime, size) have changed since
  * the last run; everything else is served from the SQLite cache.
@@ -64,6 +86,7 @@ export declare function resolveSessionById(sessions: SessionMeta[], idQuery: str
  * preserving the existing SessionMeta[] contract so sessions.ts is unchanged.
  */
 export declare function searchContentIndex(sessions: SessionMeta[], query: string): Map<string, SessionMeta>;
+export declare function shouldDeferRecentAppend(prev: ScanStamp, current: ScanStamp, nowMs: number, debounceMs?: number): boolean;
 /**
  * Collect all directories to scan for an agent's sessions. Deduplicates by
  * realpath to avoid double-counting symlinked version homes.
@@ -77,7 +100,12 @@ export declare function getAgentSessionDirs(agent: string, subdir: string): stri
  * recent startedAt.
  */
 export declare function buildClaudeLabelMap(): Map<string, string | null>;
+/** Parse the lines of a Codex `session_index.jsonl` into a session id -> title map. */
+export declare function parseCodexThreadNameIndex(raw: string): Map<string, string>;
+/** Stream a Claude JSONL file and extract scan-level metadata (timestamp, cwd, topic, tokens). */
+export declare function scanClaudeSession(filePath: string): Promise<ClaudeSessionScan>;
 /** Read up to maxLines non-empty lines from the beginning of a file. */
 export declare function readFirstLines(filePath: string, maxLines: number): Promise<string[]>;
 /** Parse a time filter string (relative like '7d' or ISO timestamp) into epoch milliseconds. */
 export declare function parseTimeFilter(input: string): number;
+export {};