@phnx-labs/agents-cli 1.20.66 → 1.20.68

package/dist/lib/share/capture.js

@@ -100,7 +100,17 @@ export async function captureCover(htmlPath, timeoutMs = 15_000) {
     if (!fs.existsSync(abs))
         return null;
     const fileUrl = `file://${abs.split('/').map(encodeURIComponent).join('/')}`;
-    for (const bin of candidateBrowsers()) {
+    const candidates = candidateBrowsers();
+    if (candidates.length === 0) {
+        // A silently-dropped cover reads as "the CLI decided this page needs none",
+        // when in fact no headless browser was found. Say so and point at the escape
+        // hatch instead of leaving the publish coverless with no explanation.
+        process.stderr.write('[agents share] no headless browser found for the OG cover — install Chrome/Chromium ' +
+            'or set AGENTS_SHARE_BROWSER=/path/to/chrome. Publishing without a preview image.\n');
+        return null;
+    }
+    let lastFailure = '';
+    for (const bin of candidates) {
         const outPng = path.join(os.tmpdir(), `agents-share-cover-${process.pid}-${Date.now()}.png`);
         const userDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-share-chrome-'));
         try {
@@ -126,15 +136,23 @@ export async function captureCover(htmlPath, timeoutMs = 15_000) {
                 // A valid PNG starts with the 8-byte signature; guard against 0-byte writes.
                 if (buf.length > 8 && buf[0] === 0x89 && buf[1] === 0x50)
                     return buf;
+                lastFailure = `${path.basename(bin)}: produced no valid PNG`;
+            }
+            else {
+                lastFailure = `${path.basename(bin)}: no screenshot written`;
             }
         }
-        catch {
-            // try the next candidate
+        catch (err) {
+            lastFailure = `${path.basename(bin)}: ${err.message}`;
         }
         finally {
             fs.rmSync(outPng, { force: true });
             fs.rmSync(userDir, { recursive: true, force: true });
         }
     }
+    // Every candidate ran but none yielded a cover — surface the last reason so a
+    // missing preview card is diagnosable (timeout, crash, bad binary) rather than silent.
+    process.stderr.write(`[agents share] OG cover capture failed (${lastFailure || 'unknown error'}) — ` +
+        'publishing without a preview image. Set AGENTS_SHARE_BROWSER to override.\n');
     return null;
 }

package/dist/lib/signin-badge.d.ts

@@ -0,0 +1,41 @@
+import type { AccountInfo } from './agents.js';
+import type { AgentId } from './types.js';
+/**
+ * The exact command that logs a given agent in — for warn banners and nudges.
+ * Driven off the registry `cliCommand` with the per-agent subcommand overrides
+ * (verified against the real CLIs): codex/grok use `<cli> login`, opencode uses
+ * `<cli> auth login`, claude logs in from inside its TUI via `/login`, and the
+ * remaining agents (kimi, gemini, …) start their device/oauth flow on launch.
+ */
+export declare function loginHint(agentId: AgentId): string;
+/**
+ * Whether `agents run` should probe login state before launching. True only for
+ * a launch that actually opens the interactive TUI — where discovering a logged-out
+ * account after the fact wastes time. Suppressed when there is no preamble surface
+ * (`--json`/`--quiet`), when the check is explicitly disabled
+ * (`--no-auth-check` / `AGENTS_NO_AUTH_CHECK=1`), or when a rotation already picked a
+ * signed-in account.
+ *
+ * `forceInteractive` is load-bearing: a resume of a non-native-resume agent
+ * (`agents run kimi --resume`, also grok/opencode/gemini) rewrites the prompt to
+ * `/continue <id>` — so `hasPrompt` is true even though the run still opens the TUI.
+ * Keying only off `hasPrompt` would silently skip the warning on exactly those
+ * agents (the ones the feature is for), so the resume's `forceInteractive` flag is
+ * consulted directly.
+ */
+export declare function shouldCheckLoginBeforeLaunch(o: {
+    interactive?: boolean;
+    forceInteractive?: boolean;
+    headless?: boolean;
+    hasPrompt: boolean;
+    json?: boolean;
+    quiet?: boolean;
+    authCheckDisabled?: boolean;
+    rotated?: boolean;
+}): boolean;
+/**
+ * Colored `✓ signed in <account>` / `✗ logged out` badge. When signed in and an
+ * account label is derivable (email, else an account id), it is appended in cyan;
+ * opaque-credential agents with no email still read as signed in.
+ */
+export declare function formatSignInBadge(info: Pick<AccountInfo, 'signedIn' | 'email' | 'accountId'> | null | undefined): string;

package/dist/lib/signin-badge.js

@@ -0,0 +1,64 @@
+/**
+ * Shared login-state LOOK. One place decides how "signed in / logged out"
+ * renders and what the login command is, so `agents doctor`, `agents view`, and
+ * the `agents run` preflight banner all read identically.
+ *
+ * The signal is `AccountInfo.signedIn` from `getAccountInfo` (file-based, cheap,
+ * no Keychain ACL prompt). It is advisory — opaque-credential agents (Kimi,
+ * Antigravity) and keychain-bound Claude can false-negative — so callers that act
+ * on it (the run preflight) WARN and continue; they never block.
+ */
+import chalk from 'chalk';
+import { AGENTS } from './agents.js';
+/**
+ * The exact command that logs a given agent in — for warn banners and nudges.
+ * Driven off the registry `cliCommand` with the per-agent subcommand overrides
+ * (verified against the real CLIs): codex/grok use `<cli> login`, opencode uses
+ * `<cli> auth login`, claude logs in from inside its TUI via `/login`, and the
+ * remaining agents (kimi, gemini, …) start their device/oauth flow on launch.
+ */
+export function loginHint(agentId) {
+    const cli = AGENTS[agentId]?.cliCommand ?? agentId;
+    switch (agentId) {
+        case 'claude':
+            return `${cli}, then /login`;
+        case 'codex':
+        case 'grok':
+            return `${cli} login`;
+        case 'opencode':
+            return `${cli} auth login`;
+        default:
+            return cli;
+    }
+}
+/**
+ * Whether `agents run` should probe login state before launching. True only for
+ * a launch that actually opens the interactive TUI — where discovering a logged-out
+ * account after the fact wastes time. Suppressed when there is no preamble surface
+ * (`--json`/`--quiet`), when the check is explicitly disabled
+ * (`--no-auth-check` / `AGENTS_NO_AUTH_CHECK=1`), or when a rotation already picked a
+ * signed-in account.
+ *
+ * `forceInteractive` is load-bearing: a resume of a non-native-resume agent
+ * (`agents run kimi --resume`, also grok/opencode/gemini) rewrites the prompt to
+ * `/continue <id>` — so `hasPrompt` is true even though the run still opens the TUI.
+ * Keying only off `hasPrompt` would silently skip the warning on exactly those
+ * agents (the ones the feature is for), so the resume's `forceInteractive` flag is
+ * consulted directly.
+ */
+export function shouldCheckLoginBeforeLaunch(o) {
+    if (o.json || o.quiet || o.authCheckDisabled || o.rotated)
+        return false;
+    return o.interactive === true || o.forceInteractive === true || (!o.hasPrompt && o.headless !== true);
+}
+/**
+ * Colored `✓ signed in <account>` / `✗ logged out` badge. When signed in and an
+ * account label is derivable (email, else an account id), it is appended in cyan;
+ * opaque-credential agents with no email still read as signed in.
+ */
+export function formatSignInBadge(info) {
+    if (!info?.signedIn)
+        return chalk.red('✗ logged out');
+    const who = info.email ?? (info.accountId ? `id:${info.accountId}` : '');
+    return who ? `${chalk.green('✓ signed in')} ${chalk.cyan(who)}` : chalk.green('✓ signed in');
+}

package/dist/lib/ssh-exec.d.ts

@@ -70,6 +70,11 @@ export interface SshExecResult {
  * it); callers that build it from user input must `shellQuote` the pieces.
  */
 export declare function sshExec(target: string, remoteCmd: string, opts?: SshExecOptions): SshExecResult;
+/**
+ * Async variant of {@link sshExec}. Same hardened argv composition, but uses
+ * child_process.spawn so fleet fan-outs can probe multiple hosts concurrently.
+ */
+export declare function sshExecAsync(target: string, remoteCmd: string, opts?: SshExecOptions): Promise<SshExecResult>;
 export interface SshExecRawResult {
     code: number | null;
     stdout: Buffer;

package/dist/lib/ssh-exec.js

@@ -7,7 +7,7 @@
  * target-injection guard live in exactly one place. Target validation is the
  * canonical definition; `commands/secrets.ts` re-exports it.
  */
-import { spawnSync } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
@@ -125,6 +125,60 @@ export function sshExec(target, remoteCmd, opts = {}) {
         timedOut,
     };
 }
+/**
+ * Async variant of {@link sshExec}. Same hardened argv composition, but uses
+ * child_process.spawn so fleet fan-outs can probe multiple hosts concurrently.
+ */
+export function sshExecAsync(target, remoteCmd, opts = {}) {
+    assertValidSshTarget(target);
+    const mux = opts.multiplex === false ? [] : controlOpts();
+    const args = [...sshConnectOpts(mux, opts.hostKeyOpts), ...(opts.extraSshArgs ?? []), target, remoteCmd];
+    return new Promise((resolve) => {
+        const child = spawn('ssh', args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let timedOut = false;
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+            }, opts.timeoutMs)
+            : null;
+        child.stdout.setEncoding('utf-8');
+        child.stderr.setEncoding('utf-8');
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        // Guard the stdin pipe: if the child closes stdin early (e.g. exits fast), the
+        // end()/write below emits EPIPE on the stream. With no listener Node escalates
+        // that to an uncaught exception that kills the whole CLI. Swallow it — the real
+        // outcome is still reported by the 'close'/'error' handlers below.
+        child.stdin.on('error', () => { });
+        if (opts.input !== undefined)
+            child.stdin.end(opts.input);
+        else
+            child.stdin.end();
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({ code: null, stdout, stderr: stderr + err.message, timedOut });
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({ code, stdout, stderr, timedOut });
+        });
+    });
+}
 /**
  * Like {@link sshExec} but returns raw stdout/stderr Buffers — no UTF-8 decode.
  *

package/dist/lib/types.d.ts

@@ -160,6 +160,16 @@ export interface AgentConfig {
          * `skip` errors with a clear message naming the supported modes.
          */
         modes: Mode[];
+        /**
+         * Whether `plan` mode works in a HEADLESS run (`--prompt`/`-p`). Some CLIs
+         * list a `plan` mode that only works interactively — kimi refuses `--prompt`
+         * combined with `--plan`, and grok's `--permission-mode plan` silently stalls
+         * a headless run at its ExitPlanMode gate. Absent (undefined) means true:
+         * headless plan is assumed to work unless a agent opts out with `false`, in
+         * which case a headless `--mode plan` request auto-downgrades to `auto`
+         * (see resolveHeadlessMode). Interactive plan is unaffected.
+         */
+        headlessPlan?: boolean;
         /**
          * Whether the agent natively resolves `@path/to/file` imports inside its
          * rules file at session start. If false, agents-cli must pre-compile the

package/dist/lib/usage.d.ts

@@ -66,8 +66,18 @@ export declare function buildCanonicalUsageContext(inputs: UsageIdentityInput[])
     canonicalByUsageKey: Map<string, AccountInfo>;
     usageFetchInputs: Map<string, UsageFetchInput>;
 };
+/**
+ * Whether an agent exposes usage/limit data we can render — Claude/Kimi/Droid via
+ * a live API, Codex via local session logs. Everything else has no usage concept,
+ * so callers use this to decide whether a missing snapshot is worth flagging as
+ * "usage unavailable" (a signed-in Claude account with no data) versus simply not
+ * applicable (Antigravity, Grok, OpenCode).
+ */
+export declare function agentReportsUsage(agentId: AgentId): boolean;
 /** Fetch usage info for all unique accounts in parallel, keyed by usage key. */
-export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[]): Promise<{
+export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[], opts?: {
+    forceRefresh?: boolean;
+}): Promise<{
     canonicalByUsageKey: Map<string, AccountInfo>;
     usageByKey: Map<string, UsageInfo>;
 }>;
@@ -83,9 +93,13 @@ export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[]): Pr
  * cache; every run after that returns instantly while the cache silently
  * refreshes in the background.
  */
-export declare function getUsageInfoForIdentity(input: UsageIdentityInput): Promise<UsageInfo>;
+export declare function getUsageInfoForIdentity(input: UsageIdentityInput, opts?: {
+    forceRefresh?: boolean;
+}): Promise<UsageInfo>;
 /** Format a one-line usage summary with compact bars for inline display. */
-export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number): string;
+export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number, opts?: {
+    unavailable?: boolean;
+}): string;
 /**
  * Derive an account's real throttle state from its live usage windows — the
  * single signal both the `agents view` badge and run-rotation eligibility share

package/dist/lib/usage.js

@@ -87,8 +87,18 @@ export function buildCanonicalUsageContext(inputs) {
     }
     return { canonicalByUsageKey, usageFetchInputs };
 }
+/**
+ * Whether an agent exposes usage/limit data we can render — Claude/Kimi/Droid via
+ * a live API, Codex via local session logs. Everything else has no usage concept,
+ * so callers use this to decide whether a missing snapshot is worth flagging as
+ * "usage unavailable" (a signed-in Claude account with no data) versus simply not
+ * applicable (Antigravity, Grok, OpenCode).
+ */
+export function agentReportsUsage(agentId) {
+    return agentId === 'claude' || agentId === 'codex' || agentId === 'kimi' || agentId === 'droid';
+}
 /** Fetch usage info for all unique accounts in parallel, keyed by usage key. */
-export async function getUsageInfoByIdentity(inputs) {
+export async function getUsageInfoByIdentity(inputs, opts) {
     const { canonicalByUsageKey, usageFetchInputs } = buildCanonicalUsageContext(inputs);
     const usageResults = await Promise.all([...usageFetchInputs.entries()].map(async ([key, input]) => ({
         key,
@@ -97,7 +107,7 @@ export async function getUsageInfoByIdentity(inputs) {
             home: input.home,
             cliVersion: input.cliVersion,
             info: canonicalByUsageKey.get(key),
-        }),
+        }, opts),
     })));
     return {
         canonicalByUsageKey,
@@ -120,8 +130,9 @@ const inFlightRefreshes = new Map();
  * cache; every run after that returns instantly while the cache silently
  * refreshes in the background.
  */
-export async function getUsageInfoForIdentity(input) {
+export async function getUsageInfoForIdentity(input, opts) {
     const usageKey = getUsageLookupKey(input.info);
+    const forceRefresh = opts?.forceRefresh === true;
     // Agents whose usage comes from a live network call (Claude, Kimi, Droid) go
     // through the stale-while-revalidate cache below so `agents run`/`agents view`
     // stay off the network on the hot path. Everything else (Codex reads local
@@ -139,15 +150,20 @@ export async function getUsageInfoForIdentity(input) {
     }
     const cached = readClaudeUsageCache(usageKey);
     const ageMs = cached?.capturedAt ? Date.now() - cached.capturedAt.getTime() : Infinity;
-    // Fresh: cache is recent enough, skip network entirely.
-    if (cached && ageMs < USAGE_CACHE_FRESH_MS) {
-        return { snapshot: cached, error: null };
-    }
-    // Stale-while-revalidate: cache exists and isn't ancient, return it now and
-    // refresh in the background so the next invocation has fresh data.
-    if (cached && ageMs < USAGE_CACHE_SWR_MS) {
-        triggerBackgroundUsageRefresh(input, usageKey);
-        return { snapshot: cached, error: null };
+    // `--refresh` (forceRefresh) skips both cache short-circuits and blocks on a
+    // live fetch below, so `agents view --refresh` repopulates every account we can
+    // actually reach a token for.
+    if (!forceRefresh) {
+        // Fresh: cache is recent enough, skip network entirely.
+        if (cached && ageMs < USAGE_CACHE_FRESH_MS) {
+            return { snapshot: cached, error: null };
+        }
+        // Stale-while-revalidate: cache exists and isn't ancient, return it now and
+        // refresh in the background so the next invocation has fresh data.
+        if (cached && ageMs < USAGE_CACHE_SWR_MS) {
+            triggerBackgroundUsageRefresh(input, usageKey);
+            return { snapshot: cached, error: null };
+        }
     }
     // Cold cache or > 24h old: block on live fetch.
     const usage = await getUsageInfo(input.agentId, {
@@ -201,7 +217,7 @@ function triggerBackgroundUsageRefresh(input, usageKey) {
     inFlightRefreshes.set(usageKey, promise);
 }
 /** Format a one-line usage summary with compact bars for inline display. */
-export function formatUsageSummary(plan, snapshot, planWidth = 3) {
+export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
     const parts = [];
     if (plan) {
         parts.push(chalk.gray(plan.padEnd(planWidth)));
@@ -212,14 +228,26 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3) {
         // account throttled by its month window (Droid meters on 5h/week/month)
         // shows the bar that explains why. Claude's Sonnet week is a per-model
         // sub-limit, not a blocking window; it renders only in the full
-        // per-version usage section.
+        // per-version usage section. Each window reads "S: ███░░ 58% (3d)" — the
+        // gauge, the exact percentage, and a compact hint of when it resets.
         const windows = snapshot.windows
             .filter((window) => window.key !== 'sonnet_week')
-            .map((window) => `${chalk.gray(`${window.shortLabel}:`)} ${renderCompactUsageBar(window.usedPercent)}`);
+            .map((window) => {
+            const bar = renderCompactUsageBar(window.usedPercent);
+            const pct = colorUsage(`${Math.round(window.usedPercent)}%`, window.usedPercent);
+            const reset = window.resetsAt ? chalk.dim(` (${formatResetHint(window.resetsAt)})`) : '';
+            return `${chalk.gray(`${window.shortLabel}:`)} ${bar} ${pct}${reset}`;
+        });
         if (windows.length > 0) {
-            parts.push(windows.join(' '));
+            parts.push(windows.join('  '));
         }
     }
+    else if (opts?.unavailable) {
+        // Signed-in account we could NOT fetch usage for (no live token in a reachable
+        // home / org mismatch / fetch error). Say so explicitly instead of drawing a
+        // blank gauge that reads like "0% used".
+        parts.push(chalk.dim('usage unavailable'));
+    }
     return parts.join('  ');
 }
 /**
@@ -1096,6 +1124,25 @@ function formatPercent(value) {
     const rounded = Math.round(value * 10) / 10;
     return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
 }
+/**
+ * Compact "time until reset" hint for the inline usage bars: "5m", "2h", "3d",
+ * or "now" once elapsed. Deliberately coarse (single unit, whole numbers) so it
+ * fits after a bar without wrapping the row — the detailed section
+ * (`formatResetAt`) carries the precise clock time.
+ */
+function formatResetHint(date) {
+    const diffMs = date.getTime() - Date.now();
+    if (diffMs <= 0)
+        return 'now';
+    const mins = Math.round(diffMs / 60000);
+    if (mins < 60)
+        return `${Math.max(1, mins)}m`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    const days = Math.round(hours / 24);
+    return `${days}d`;
+}
 /** Format a reset timestamp as a human-readable relative or absolute time. */
 function formatResetAt(date) {
     const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.66",
+  "version": "1.20.68",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",