@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/browser/types.d.ts

@@ -77,6 +77,20 @@ export interface Task {
     tabs: Record<string, string>;
     currentTabId?: string;
     createdAt: number;
+    /**
+     * When this task last did anything. Stamped at creation (equal to
+     * `createdAt`) and refreshed by every task-scoped action, because every one
+     * of them resolves the task through `BrowserService.findTask`.
+     *
+     * Read by the idle half of the abandoned-task reaper (`hygiene.ts`): a task
+     * nobody has driven for `idleMs` is stopped so its tabs stop piling up in the
+     * profile window (RUSH-2622).
+     *
+     * Persisted in tasks.json. Tasks written before RUSH-2622 carry none;
+     * `loadTaskState` normalizes those to `createdAt` on read, so every task in
+     * memory has one and the reaper never has to guess.
+     */
+    lastActionAt: number;
     pid: number;
     /**
      * Resolved actor id (`resolveActor().id`) stamped at task start — WHO launched
@@ -93,6 +107,13 @@ export interface Task {
      * from the caller over IPC. Optional: tasks from before this shipped carry none.
      */
     launchId?: string;
+    /**
+     * The agent session that started this task (`$AGENT_SESSION_ID`), forwarded
+     * from the caller at `start`. The durable copy lives in the `browser_sessions`
+     * table, which survives `stop`; this in-memory/tasks.json copy is the live one
+     * (RUSH-2549).
+     */
+    sessionId?: string;
     /**
      * Per-tab snapshot of the last ref listing captured for that tab
      * (shortId -> {descriptors, opts}). Persisted to tasks.json so a later
@@ -144,7 +165,24 @@ export interface HistoricalTask {
     /** Actor id who launched the task (RUSH-2020); absent for pre-RUSH-2020 history. */
     owner?: string;
 }
-export type IPCAction = 'start' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'pdf' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
+/**
+ * Why the reaper stopped a task. `session-dead` — the agent session (or run)
+ * that started it is provably gone; `idle` — nothing has driven it for the
+ * idle window. See `hygiene.ts`.
+ */
+export type ReapReason = 'session-dead' | 'idle';
+/** One task the reaper stopped (or, under `dryRun`, would have stopped). */
+export interface ReapedTask {
+    task: string;
+    profile: string;
+    reason: ReapReason;
+}
+export interface ReapResult {
+    closed: ReapedTask[];
+    /** Tasks left alone this pass: still live, still inside the idle window, or recording. */
+    skipped: number;
+}
+export type IPCAction = 'start' | 'gc' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'pdf' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
@@ -194,8 +232,30 @@ export interface IPCRequest {
     until?: string;
     appLevel?: string;
     skipDomainSkill?: boolean;
+    /**
+     * Browser start: always open a new tab. Without it, `start --url` reclaims a
+     * tab that an ABANDONED task is still holding on this exact URL rather than
+     * opening a duplicate (RUSH-2622). A tab held by a live task, or one nobody's
+     * task owns (the user's own), is never taken either way — set this when the
+     * caller wants its own tab regardless.
+     */
+    fresh?: boolean;
+    idleMinutes?: number;
+    dryRun?: boolean;
     actor?: string;
     launchId?: string;
+    /**
+     * The calling agent session (`$AGENT_SESSION_ID` / `$AGENTS_SESSION_ID`) —
+     * the id that answers "which agent drove this task" and the one persisted to
+     * `browser_sessions` (RUSH-2549).
+     *
+     * This is the primary identity, not a spare: `launchId` alone was the join
+     * key, and a fleet measurement found it present on only 2 of 5 live agent
+     * processes while a session id was on 5 of 5 — every agent reaching the
+     * browser carries one. It is the same env `stampProvenance()` already reads
+     * for `computer.action` events, so both tool surfaces key on one signal.
+     */
+    sessionId?: string;
 }
 /** Subset of IPCResponse describing a recording start result. */
 export interface RecordStartFields {
@@ -217,6 +277,8 @@ export interface IPCResponse {
     tabs?: TabInfo[];
     profiles?: ProfileStatus[];
     history?: HistoricalTask[];
+    /** `gc`: what the abandoned-task reaper closed (or would close under dryRun). */
+    reaped?: ReapResult;
     result?: unknown;
     path?: string;
     bytes?: number;

package/dist/lib/byok-usage.d.ts

@@ -20,6 +20,8 @@ export interface ByokUsageResult {
     error: string | null;
 }
 export declare function setByokFetchForTest(fn: typeof globalThis.fetch): void;
+export declare const BYOK_REFRESH_INTERVAL_MS: number;
+export declare function setByokCachePathForTest(value: string | null): string | null;
 export declare function resetByokCacheForTest(): void;
 export declare function hasByokProvider(provider: string): boolean;
 export declare function renderByokBar(result: ByokUsageResult): string;
@@ -30,9 +32,14 @@ export declare function renderByokBar(result: ByokUsageResult): string;
  * Returns a `ByokUsageResult` with `budget: null` when the token is absent
  * from the keychain (so the caller can skip rendering a bar without error).
  *
- * Results are SWR-cached per `keychainItem` so harnesses sharing one API key
- * deduplicate to a single network request.
+ * Ordinary reads are cache-only. Explicit refreshes are serialized per provider
+ * credential across every agents-cli process on the device.
  */
 export declare function getByokUsageForHarness(profile: Profile, opts?: {
     forceRefresh?: boolean;
 }): Promise<ByokUsageResult | null>;
+/** Refresh each configured BYOK credential when its daemon-owned snapshot is due. */
+export declare function refreshDueByokUsage(profiles: Profile[], now?: number): Promise<{
+    refreshed: number;
+    skipped: number;
+}>;

package/dist/lib/byok-usage.js

@@ -8,31 +8,81 @@
  * API rather than the CLI's own usage tracking.
  */
 import { hasKeychainToken, getKeychainToken } from './secrets/profiles.js';
-import { renderBar, getUsageColor, USAGE_CACHE_FRESH_MS, USAGE_CACHE_SWR_MS } from './usage.js';
+import { renderBar, getUsageColor } from './usage.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+import { getCacheDir } from './state.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
+import { withRefreshLease } from './refresh-coordinator.js';
+import { findAccount, resolveCredentialAccount } from './account-registry.js';
+import { getAccountProvider } from './account-provider-registry.js';
 // ─── Injectable fetch seam (tests only) ──────────────────────────────────────
 let _fetch = globalThis.fetch;
 export function setByokFetchForTest(fn) {
     _fetch = fn;
 }
-const _cache = new Map();
-export function resetByokCacheForTest() {
-    _cache.clear();
+let cachePathOverride = null;
+function cachePath() {
+    return cachePathOverride ?? path.join(getCacheDir(), 'byok-usage.json');
 }
-async function fetchOpenRouter(keychainItem) {
+function readCache() {
     try {
-        if (!hasKeychainToken(keychainItem))
-            return { budget: null, error: null };
+        const parsed = JSON.parse(fs.readFileSync(cachePath(), 'utf-8'));
+        return parsed?.version === 1 && parsed.entries ? parsed.entries : {};
     }
     catch {
-        return { budget: null, error: null };
+        return {};
+    }
+}
+function writeCacheEntry(key, entry) {
+    const target = cachePath();
+    ensureLockTarget(target, JSON.stringify({ version: 1, entries: {} }));
+    withFileLock(target, () => {
+        atomicWriteFileSync(target, JSON.stringify({ version: 1, entries: { ...readCache(), [key]: entry } }));
+    });
+}
+function byokCacheKey(profile) {
+    return createHash('sha256').update(`${profile.provider}\0${profile.account ?? profile.auth?.keychainItem ?? ''}`).digest('hex');
+}
+export const BYOK_REFRESH_INTERVAL_MS = 5 * 60_000;
+export function setByokCachePathForTest(value) {
+    const previous = cachePathOverride;
+    cachePathOverride = value;
+    return previous;
+}
+export function resetByokCacheForTest() {
+    try {
+        fs.unlinkSync(cachePath());
+    }
+    catch { /* absent */ }
+}
+function resolveByokToken(profile) {
+    if (profile.account) {
+        try {
+            const account = findAccount(profile.account);
+            if (!account)
+                return null;
+            const resolved = resolveCredentialAccount(profile.account, profile.host.agent, profile.provider);
+            return resolved.env[getAccountProvider(account.provider).envFor(profile.host.agent, account.auth)] ?? null;
+        }
+        catch {
+            return null;
+        }
     }
-    let token;
+    const keychainItem = profile.auth?.keychainItem;
+    if (!keychainItem)
+        return null;
     try {
-        token = getKeychainToken(keychainItem);
+        if (!hasKeychainToken(keychainItem))
+            return null;
+        return getKeychainToken(keychainItem);
     }
     catch {
-        return { budget: null, error: null };
+        return null;
     }
+}
+async function fetchOpenRouter(token) {
     try {
         const res = await _fetch('https://openrouter.ai/api/v1/key', {
             headers: { Authorization: `Bearer ${token}` },
@@ -59,8 +109,37 @@ async function fetchOpenRouter(keychainItem) {
         return { budget: null, error: String(err) };
     }
 }
+async function fetchDeepInfra(token) {
+    try {
+        const res = await _fetch('https://api.deepinfra.com/payment/checklist', {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok)
+            return { budget: null, error: `HTTP ${res.status}` };
+        const json = (await res.json());
+        const limitUsd = json.limit !== null && json.limit >= 0 ? json.limit : null;
+        const usedUsd = json.recent;
+        const remainingUsd = limitUsd !== null
+            ? Math.max(0, limitUsd - usedUsd)
+            : json.stripe_balance < 0 ? -json.stripe_balance : null;
+        return {
+            budget: {
+                limitUsd,
+                remainingUsd,
+                usedUsd,
+                usedPercent: limitUsd !== null && limitUsd > 0 ? (usedUsd / limitUsd) * 100 : null,
+                fetchedAt: new Date(),
+            },
+            error: null,
+        };
+    }
+    catch (err) {
+        return { budget: null, error: String(err) };
+    }
+}
 const BYOK_REGISTRY = {
     openrouter: { fetch: fetchOpenRouter },
+    deepinfra: { fetch: fetchDeepInfra },
 };
 export function hasByokProvider(provider) {
     return Object.prototype.hasOwnProperty.call(BYOK_REGISTRY, provider);
@@ -72,7 +151,8 @@ export function renderByokBar(result) {
     const { budget } = result;
     if (budget.limitUsd === null) {
         const bar = renderBar(0, 10, 0);
-        return `$: ${bar} $${budget.usedUsd.toFixed(2)} used (unlimited)`;
+        const credit = budget.remainingUsd !== null ? `$${budget.remainingUsd.toFixed(2)} credit, ` : '';
+        return `$: ${bar} ${credit}$${budget.usedUsd.toFixed(2)} used (no spending limit)`;
     }
     const pct = budget.usedPercent ?? 0;
     const bar = renderBar(pct, 10, pct > 0 ? 1 : 0);
@@ -89,29 +169,51 @@ export function renderByokBar(result) {
  * Returns a `ByokUsageResult` with `budget: null` when the token is absent
  * from the keychain (so the caller can skip rendering a bar without error).
  *
- * Results are SWR-cached per `keychainItem` so harnesses sharing one API key
- * deduplicate to a single network request.
+ * Ordinary reads are cache-only. Explicit refreshes are serialized per provider
+ * credential across every agents-cli process on the device.
  */
 export async function getByokUsageForHarness(profile, opts) {
-    if (!profile.provider || !hasByokProvider(profile.provider) || !profile.auth)
+    if (!profile.provider || !hasByokProvider(profile.provider) || (!profile.auth && !profile.account))
         return null;
-    const keychainItem = profile.auth.keychainItem;
     const provider = BYOK_REGISTRY[profile.provider];
-    const now = Date.now();
-    const cached = _cache.get(keychainItem);
-    if (!opts?.forceRefresh && cached) {
-        const age = now - cached.fetchedAt;
-        if (age < USAGE_CACHE_FRESH_MS) {
-            return cached.result;
-        }
-        if (age < USAGE_CACHE_SWR_MS) {
-            void provider.fetch(keychainItem).then((result) => {
-                _cache.set(keychainItem, { result, fetchedAt: Date.now() });
-            });
-            return cached.result;
+    const cacheKey = byokCacheKey(profile);
+    const cached = readCache()[cacheKey];
+    if (!opts?.forceRefresh)
+        return cached?.result ?? { budget: null, error: 'stale' };
+    const previousFetchedAt = cached?.fetchedAt ?? 0;
+    return withRefreshLease({
+        scope: 'byok-usage',
+        key: cacheKey,
+        readCompleted: () => readCache()[cacheKey] ?? null,
+        isCompleted: (entry) => entry.fetchedAt > previousFetchedAt,
+        refresh: async () => {
+            const token = resolveByokToken(profile);
+            const result = token ? await provider.fetch(token) : { budget: null, error: null };
+            const entry = { result, fetchedAt: Math.max(Date.now(), previousFetchedAt + 1) };
+            writeCacheEntry(cacheKey, entry);
+            return entry;
+        },
+    }).then((entry) => entry.result);
+}
+/** Refresh each configured BYOK credential when its daemon-owned snapshot is due. */
+export async function refreshDueByokUsage(profiles, now = Date.now()) {
+    const due = new Map();
+    for (const profile of profiles) {
+        if (!profile.provider || (!profile.auth && !profile.account) || !hasByokProvider(profile.provider))
+            continue;
+        due.set(byokCacheKey(profile), profile);
+    }
+    let refreshed = 0;
+    let skipped = 0;
+    const cache = readCache();
+    for (const [key, profile] of due) {
+        const entry = cache[key];
+        if (entry && now - entry.fetchedAt < BYOK_REFRESH_INTERVAL_MS) {
+            skipped += 1;
+            continue;
         }
+        await getByokUsageForHarness(profile, { forceRefresh: true });
+        refreshed += 1;
     }
-    const result = await provider.fetch(keychainItem);
-    _cache.set(keychainItem, { result, fetchedAt: now });
-    return result;
+    return { refreshed, skipped };
 }

package/dist/lib/cli-entry.d.ts

@@ -1,5 +1,16 @@
 export declare const BUN_VIRTUAL_ROOT: RegExp;
 export declare function getAgentsBinPath(argv1?: string | undefined, execPath?: string): string;
+/**
+ * Directory that contains the `agents` launcher usable for PATH resolution.
+ *
+ * When the running entry IS the launcher (a compiled binary or an extension-less
+ * shim named `agents`), this is just `dirname(getAgentsBinPath())`. When the
+ * running entry is a script inside `dist/` reached via a symlink/shim elsewhere
+ * (the npm global-install shape), we look for a launcher whose realpath points at
+ * the same entry and return that launcher's directory. Falls back to the entry's
+ * own directory when no launcher is found.
+ */
+export declare function getAgentsBinDir(): string;
 /**
  * A CLI entry must be launched through the Node runtime when it is a Node
  * script — a `.js`/`.cjs`/`.mjs` file, OR a symlink/extension-less shim whose

package/dist/lib/cli-entry.js

@@ -19,6 +19,7 @@
  */
 import { execFileSync } from 'child_process';
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 export const BUN_VIRTUAL_ROOT = /[/\\]\$bunfs[/\\]root[/\\]/;
 function resolveBunStandaloneEntry(entry, execPath) {
@@ -61,6 +62,51 @@ export function getAgentsBinPath(argv1 = process.argv[1], execPath = process.exe
         return 'agents';
     }
 }
+/**
+ * Directory that contains the `agents` launcher usable for PATH resolution.
+ *
+ * When the running entry IS the launcher (a compiled binary or an extension-less
+ * shim named `agents`), this is just `dirname(getAgentsBinPath())`. When the
+ * running entry is a script inside `dist/` reached via a symlink/shim elsewhere
+ * (the npm global-install shape), we look for a launcher whose realpath points at
+ * the same entry and return that launcher's directory. Falls back to the entry's
+ * own directory when no launcher is found.
+ */
+export function getAgentsBinDir() {
+    const bin = getAgentsBinPath();
+    const base = path.basename(bin);
+    if (base === 'agents' || base === 'agents.exe' || base === 'agents.cmd') {
+        return path.dirname(bin);
+    }
+    const realBin = (() => {
+        try {
+            return fs.realpathSync(bin);
+        }
+        catch {
+            return bin;
+        }
+    })();
+    const home = os.homedir();
+    const candidates = [
+        path.join(home, '.local', 'bin'),
+        '/usr/local/bin',
+        '/opt/homebrew/bin',
+        path.join(home, '.npm-global', 'bin'),
+        path.join(home, '.bun', 'bin'),
+        path.dirname(process.execPath),
+    ];
+    for (const dir of candidates) {
+        for (const name of ['agents', 'agents.exe', 'agents.cmd']) {
+            const launcher = path.join(dir, name);
+            try {
+                if (fs.realpathSync(launcher) === realBin)
+                    return dir;
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return path.dirname(bin);
+}
 /**
  * A CLI entry must be launched through the Node runtime when it is a Node
  * script — a `.js`/`.cjs`/`.mjs` file, OR a symlink/extension-less shim whose

package/dist/lib/cloud/host.d.ts

@@ -4,7 +4,7 @@
  * A thin adapter over the hosts subsystem (lib/hosts/*): `agents cloud run
  * --provider host --host <name>` dispatches through the SAME detached-SSH
  * launch as `agents run --host`, and the resulting task shows up in BOTH
- * `agents cloud ps` and `agents hosts ps` — one store (the host-task sidecars
+ * `agents cloud ps` and `agents devices ps` — one store (the host-task sidecars
  * under ~/.agents/.cache/hosts/), two views. No new transport, no relay: SSH
  * is the only wire, exactly like the rest of the hosts design (docs/hosts.md).
  *

package/dist/lib/cloud/host.js

@@ -4,7 +4,7 @@
  * A thin adapter over the hosts subsystem (lib/hosts/*): `agents cloud run
  * --provider host --host <name>` dispatches through the SAME detached-SSH
  * launch as `agents run --host`, and the resulting task shows up in BOTH
- * `agents cloud ps` and `agents hosts ps` — one store (the host-task sidecars
+ * `agents cloud ps` and `agents devices ps` — one store (the host-task sidecars
  * under ~/.agents/.cache/hosts/), two views. No new transport, no relay: SSH
  * is the only wire, exactly like the rest of the hosts design (docs/hosts.md).
  *
@@ -77,7 +77,7 @@ export class HostCloudProvider {
     async dispatch(options) {
         const hostName = options.providerOptions?.host;
         if (!hostName) {
-            throw new MissingTargetError('host', 'No host given. Pass --host <name> (a registered host, a device, a capability tag, or user@host).', 'List your machines: agents hosts list  ·  register more: agents devices sync / agents hosts add');
+            throw new MissingTargetError('host', 'No host given. Pass --host <name> (a registered host, a device, a capability tag, or user@host).', 'List your machines: agents devices list  ·  register more: agents devices sync');
         }
         if (resolveDispatchRepos(options).length > 0) {
             throw new Error('--repo has no meaning for --provider host — the run executes in a directory on the machine, not a cloned repo. ' +

package/dist/lib/cloud/registry.js

@@ -46,7 +46,7 @@ function initProviders() {
     providers.set('factory', new FactoryCloudProvider(config.providers?.factory));
     providers.set('antigravity', new AntigravityCloudProvider(config.providers?.antigravity));
     providers.set('cursor', new CursorCloudProvider(config.providers?.cursor));
-    // Your own machines (agents hosts / agents devices) over SSH. No agent
+    // Your own machines (agents devices) over SSH. No agent
     // auto-routes here — it's always an explicit --provider host / --host choice.
     providers.set('host', new HostCloudProvider());
 }

package/dist/lib/cloud/types.d.ts

@@ -15,7 +15,7 @@ import type { JobTrigger } from '../routines.js';
  *   - `factory`     — Factory Droid Computers (`droid computer ssh` + remote `droid exec`)
  *   - `antigravity` — Google Gemini Managed Agents (Interactions API)
  *   - `cursor`      — Cursor Cloud Agents REST API
- *   - `host`        — a machine you own (`agents hosts` / `agents devices`), over SSH
+ *   - `host`        — a machine you own (`agents devices`), over SSH
  *
  * Agents route to their native cloud automatically (see `cloudProvider` in the
  * agent registry); `--provider` overrides. Nothing auto-routes to `host` — it

package/dist/lib/commands.d.ts

@@ -19,6 +19,8 @@ export interface CommandMetadata {
     since?: string;
     /** Exclusive upper bound on agent CLI version for this command. */
     until?: string;
+    /** Alternate names this command also resolves under (frontmatter `aliases:`). */
+    aliases?: string[];
 }
 export type CommandApplyFailReason = 'unsupported' | 'agent_excluded' | 'too_old' | 'too_new';
 export type CommandApplyResult = {

package/dist/lib/commands.js

@@ -12,6 +12,7 @@ import * as yaml from 'yaml';
 import { AGENTS, ensureCommandsDir, agentConfigDirName, resolveAgentName } from './agents.js';
 import { capableAgents, isCapable, supports } from './capabilities.js';
 import { isDirectoryDoc } from './resources.js';
+import { normalizeAliases } from './resource-aliases.js';
 import { markdownToToml } from './convert.js';
 import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir, getTrashCommandsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
@@ -102,6 +103,7 @@ export function parseCommandMetadata(filePath) {
                     agents: parseAgentsField(parsed.agents),
                     since: typeof parsed.since === 'string' ? parsed.since : undefined,
                     until: typeof parsed.until === 'string' ? parsed.until : undefined,
+                    aliases: normalizeAliases(parsed.aliases),
                 };
             }
         }

package/dist/lib/computer/sessions-list.d.ts

@@ -0,0 +1,150 @@
+import type { SessionMeta } from '../session/types.js';
+/** Max chars of a `run --task` description persisted to the ledger — see the
+ *  module docblock's retention/privacy note. */
+export declare const TASK_PREVIEW_MAX_CHARS = 200;
+/** One `computer.action` ledger entry, narrowed to the fields this module
+ *  renders or groups by. */
+export interface ComputerAction {
+    /** CLI verb: `click`, `type`, `screenshot`, … or `run` for the task marker
+     *  `registerRunCommand` emits before entering the model loop. */
+    verb: string;
+    ts: string;
+    tsMs: number;
+    /** The emitting CLI process's own pid — the run/task grouping key. */
+    pid: number;
+    /** Unique for the emitting CLI process; absent only on legacy ledger rows. */
+    invocationId?: string;
+    /** The driven app's pid, when resolved. */
+    targetPid?: number;
+    bundle?: string;
+    /** `--host <device>` target when this action drove a remote daemon. */
+    host?: string;
+    /** Truncated `--task` text; only ever present on a `verb: 'run'` marker. */
+    task?: string;
+    sessionId?: string;
+    launchId?: string;
+    agent?: string;
+    machineId?: string;
+    hostname?: string;
+}
+/** Read `computer.action` events straight from the durable event ledger,
+ *  newest first, bounded by `limit`. Malformed/legacy records (missing
+ *  `command` or `pid`, or an unparseable `ts`) are skipped, never thrown —
+ *  the ledger is a plain rotated JSONL file another process can be mid-write
+ *  or mid-rotate against. */
+export declare function listComputerActions(opts?: {
+    limit?: number;
+}): ComputerAction[];
+/** Why a row carries no session digest: `linked` resolved one, `unresolved`
+ *  has a sessionId/launchId but no matching indexed session, `unlinked` has
+ *  neither (a bare terminal invocation with no agent session env at all). */
+export type ComputerRunLinkStatus = 'linked' | 'unresolved' | 'unlinked';
+/** One task-first row: every `computer.action` emitted by one CLI process
+ *  (see the module docblock's "Grouping key" note), plus the agent session
+ *  it links to when resolvable. */
+export interface ComputerRunRow {
+    /** Invoking CLI process's pid. Absent on a run recovered from the DB after
+     *  the ledger pruned — that process is long gone and its pid unknowable. */
+    pid?: number;
+    invocationId?: string;
+    /**
+     * Total actions for a run recovered from the DB after the event ledger
+     * pruned its individual actions. Set ONLY on such rows: when it is present,
+     * `actions`/`counts` are empty because the per-verb detail is genuinely gone,
+     * and this total is all that survived. Live ledger rows leave it undefined
+     * and report real per-verb `counts` instead.
+     */
+    recoveredActionCount?: number;
+    /** Truncated task description — present only for a `computer run --task`
+     *  invocation; a bare verb call has none. */
+    task?: string;
+    /** Invoking machine's hostname — the CLI's own machine, not necessarily
+     *  the driven one (see `remoteHost`). */
+    machine: string;
+    machineId?: string;
+    /** `--host <device>` target when the run drove a remote (Windows) daemon. */
+    remoteHost?: string;
+    /** Best-known target app bundle across the run's actions. */
+    bundle?: string;
+    agent?: string;
+    sessionId?: string;
+    launchId?: string;
+    linkStatus: ComputerRunLinkStatus;
+    linkedSession?: SessionMeta;
+    /** Newest first; excludes the `run` task marker itself. */
+    actions: ComputerAction[];
+    /** Per-verb counts over `actions` (never includes the `run` marker). */
+    counts: Record<string, number>;
+    /** Oldest action's mtime — the row's start. */
+    startMs: number;
+    /** Newest action's mtime — the row's sort/age key. */
+    endMs: number;
+}
+/**
+ * Group flat ledger actions into task-first rows, newest first. Pure:
+ * session resolvers are passed in, so this has no filesystem/session-index
+ * dependency and is unit-testable with synthetic data (see
+ * {@link buildComputerSessionRows} for the impure disk/index-reading caller).
+ */
+export declare function groupIntoComputerRuns(actions: ComputerAction[], resolveSession?: (sessionId: string) => SessionMeta | null, resolveLaunch?: (launchId: string) => SessionMeta | null): ComputerRunRow[];
+/** Build task-first rows from the real ledger, resolving each row's owning
+ *  session against the live indexes. The interactive picker's (and the
+ *  flat/`--json` printer's) data source. `machine` narrows to rows whose
+ *  invoking hostname, machineId, or `--host` target contains the substring. */
+export declare function buildComputerSessionRows(opts?: {
+    limit?: number;
+    machine?: string;
+}): ComputerRunRow[];
+/**
+ * Search predicate for the interactive picker: task text, machine/remote
+ * host, target bundle, the linked session's agent/topic/label, or any
+ * driven verb in the row.
+ */
+export declare function matchesComputerSessionRow(row: ComputerRunRow, queryText: string): boolean;
+/** Human one-line summary of a row's per-verb action counts, most frequent
+ *  first — shared by the flat table and the interactive picker's label. */
+/**
+ * One row's action summary — the single renderer every surface should use.
+ *
+ * A run recovered from the DB after the ledger pruned has no per-verb detail,
+ * only a total. Rendering it through the per-verb formatter printed
+ * "(no actions)", which is indistinguishable from a run that did nothing — so a
+ * 40-action run read as empty. Report the surviving total, and say plainly that
+ * the breakdown is gone rather than implying we still have it.
+ */
+export declare function formatRowActions(row: ComputerRunRow): string;
+export declare function formatActionCounts(counts: Record<string, number>): string;
+/** Human table for the CLI. Returns lines (no trailing newline). */
+export declare function renderComputerSessionRows(rows: ComputerRunRow[]): string;
+/** Default row cap for the flat/non-interactive table. A computer row is
+ *  much finer-grained than a browser task — real usage is mostly one
+ *  standalone verb per CLI invocation, not a `run --task` loop, so an
+ *  unbounded flat dump against real history reads as hundreds of one-action
+ *  rows (confirmed against a real machine's history while building this).
+ *  The interactive picker has no such cap (it's searchable); only the
+ *  static table needs one. `--limit` overrides. */
+export declare const DEFAULT_ROW_DISPLAY_LIMIT = 50;
+/** Slice `rows` to at most `limit` (newest first, rows are already sorted),
+ *  and report how many were dropped — pure, so the cap arithmetic and the
+ *  trailer condition are unit-testable without a console spy. */
+export declare function applyRowDisplayLimit(rows: ComputerRunRow[], limit?: number): {
+    shown: ComputerRunRow[];
+    more: number;
+};
+/**
+ * Shared CLI action for `agents computer sessions` and `agents sessions
+ * --computer`. Non-interactive by design (the interactive routing decision
+ * lives in `commands/computer-sessions-picker.ts`, mirroring
+ * `runBrowserSessions`/`runBrowserSessionsCommand`'s split).
+ */
+export declare function runComputerSessions(opts: {
+    machine?: string;
+    json?: boolean;
+    limit?: number;
+}): void;
+/** Print already-collected rows. Fleet callers use this after merging local and
+ * remote JSON so text, limits, and JSON keep exactly one renderer. */
+export declare function printComputerSessionRows(rows: ComputerRunRow[], opts: {
+    json?: boolean;
+    limit?: number;
+}): void;