@phnx-labs/agents-cli 1.21.2 → 1.22.0

package/dist/lib/rotate.js

@@ -6,7 +6,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { accountDisplayLabel, getAccountInfo } from './agents.js';
+import { accountDisplayLabel, getAccountInfo, ALL_AGENT_IDS } from './agents.js';
 import { readMeta, writeMeta, getHelpersDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getProjectRunConfigs } from './run-config.js';
@@ -342,6 +342,136 @@ export function pickAvailableCandidate(candidates, preferredVersion, nowMs = Dat
         : undefined;
     return { picked: preferred ?? bestVerified, healthy: sorted, excluded, usageUnverified };
 }
+/**
+ * Classify every harness's candidates into healthy (with a representative
+ * best account) vs excluded (with per-reason counts). Pure — the pick and the
+ * zero-healthy error message both read this, so they can never disagree.
+ *
+ * Health uses the exact account-layer gate (`isRotationEligible`: signed in
+ * AND not maxed on ANY blocking window, weekly included). The representative
+ * best account honors `preferVerified`: confirmed headroom beats apparent
+ * headroom, the same freshness rule the account layer routes on.
+ */
+export function classifyHarnessCandidates(byHarness, nowMs = Date.now()) {
+    const summaries = [];
+    for (const [agent, candidates] of byHarness) {
+        const eligible = candidates.filter(isRotationEligible);
+        if (eligible.length === 0) {
+            const counts = new Map();
+            for (const c of candidates) {
+                const readiness = readinessFromCandidate(c);
+                const reason = readiness.ready ? 'ineligible' : readiness.reason;
+                counts.set(reason, (counts.get(reason) ?? 0) + 1);
+            }
+            summaries.push({
+                agent,
+                candidates,
+                healthy: [],
+                best: null,
+                bestUsedPercent: null,
+                exclusionReasons: [...counts.entries()].map(([reason, n]) => `${n} ${reason}`),
+            });
+            continue;
+        }
+        const sorted = dedupeAndSortCandidates(eligible);
+        const { picked: best } = preferVerified(sorted, nowMs, (from) => from[0]);
+        summaries.push({
+            agent,
+            candidates,
+            healthy: sorted,
+            best,
+            bestUsedPercent: getRoutingUsedPercent(best.usageSnapshot),
+            exclusionReasons: [],
+        });
+    }
+    return summaries;
+}
+/**
+ * Pick a harness for `agents run auto` using weighted random by best-account
+ * headroom (RUSH-2132).
+ *
+ * A harness's capacity is `100 − min(routingUsed% across its healthy accounts)`
+ * — its best account's headroom. The pick reuses `weightedRandomByCapacity` on
+ * the representative best accounts, so host/harness/account layers all share
+ * one sampling behavior. Harnesses with zero healthy accounts are EXCLUDED,
+ * not down-weighted. Returns null when no harness has any healthy account;
+ * call `classifyHarnessCandidates` for the exclusion detail to message with.
+ */
+export function pickHarnessWeighted(byHarness, nowMs = Date.now()) {
+    const summaries = classifyHarnessCandidates(byHarness, nowMs);
+    const healthy = summaries.filter((s) => s.best !== null);
+    const excluded = summaries.filter((s) => s.best === null);
+    if (healthy.length === 0)
+        return null;
+    const pickedBest = weightedRandomByCapacity(healthy.map((s) => s.best));
+    const picked = healthy.find((s) => s.best === pickedBest);
+    return { picked, healthy, excluded };
+}
+/** One-line banner naming the auto-picked harness and why (headroom). */
+export function formatHarnessPickBanner(result) {
+    const { picked, healthy, excluded } = result;
+    const headroom = picked.bestUsedPercent === null
+        ? 'best account headroom unknown'
+        : `best account ${Math.max(0, Math.round(100 - picked.bestUsedPercent))}% headroom`;
+    const ratio = `${healthy.length} of ${healthy.length + excluded.length} harnesses healthy`;
+    return `[agents] auto picked ${picked.agent} (${headroom}, ${ratio})`;
+}
+/**
+ * The earliest FUTURE window reset across these candidates' usage snapshots —
+ * when the first exhausted account becomes usable again. Null when no snapshot
+ * carries a reset timestamp.
+ */
+export function earliestResetAcross(candidates, nowMs = Date.now()) {
+    let earliest = null;
+    for (const c of candidates) {
+        for (const window of c.usageSnapshot?.windows ?? []) {
+            const t = window.resetsAt?.getTime();
+            if (t != null && t > nowMs && (earliest === null || t < earliest)) {
+                earliest = t;
+            }
+        }
+    }
+    return earliest === null ? null : new Date(earliest);
+}
+/**
+ * The `resets <summary>` fragment both zero-healthy errors share. ISO 8601 so
+ * a watchdog can parse the cooldown straight off the line; `unknown` when no
+ * snapshot carries a reset (a parser falls back to its default cooldown).
+ */
+function formatResetSummary(reset) {
+    return reset ? reset.toISOString() : 'unknown (no reset timestamps in any snapshot)';
+}
+/**
+ * The zero-healthy-account error (RUSH-2132). EXACT contract — the Factory
+ * watchdog tail-detects this text: it must contain the literal `no healthy`
+ * and `resets <time>` (parsed for the rotate cooldown). Do not deviate.
+ */
+export function formatNoHealthyAccountError(agent, strategy, excluded, nowMs = Date.now()) {
+    const excludedStr = excluded.length === 0
+        ? 'no installed versions'
+        : excluded.map((c) => {
+            const readiness = readinessFromCandidate(c);
+            const reason = readiness.ready ? 'ineligible' : readiness.reason;
+            return `${c.version} (${reason})`;
+        }).join(', ');
+    const resetSummary = formatResetSummary(earliestResetAcross(excluded, nowMs));
+    return `agents: no healthy ${agent} account under strategy '${strategy}' — excluded: ${excludedStr}; earliest window resets ${resetSummary}. Use --strategy pinned to force the default.`;
+}
+/**
+ * The zero-healthy-harness error for `agents run auto` — names each harness's
+ * exclusion reason plus the earliest reset across all snapshots.
+ */
+export function formatNoHealthyHarnessError(summaries, nowMs = Date.now()) {
+    const excludedStr = summaries.length === 0
+        ? 'no installed harnesses'
+        : summaries.map((s) => {
+            const n = s.candidates.length;
+            const detail = s.exclusionReasons.length > 0 ? s.exclusionReasons.join(', ') : 'no accounts signed in';
+            return `${s.agent} (${n} account${n === 1 ? '' : 's'}: ${detail})`;
+        }).join(', ');
+    const resetSummary = formatResetSummary(earliestResetAcross(summaries.flatMap((s) => s.candidates), nowMs));
+    return `agents: no healthy harness for 'run auto' — excluded: ${excludedStr}; earliest window resets ${resetSummary}. Sign in an account or wait for a window to reset.`;
+}
 export async function collectRunCandidates(agent) {
     const versions = listInstalledVersions(agent);
     const rows = await Promise.all(versions.map(async (version) => {
@@ -400,6 +530,25 @@ export async function collectRunCandidates(agent) {
         };
     });
 }
+/**
+ * Collect run candidates for every harness with ≥1 installed version — the
+ * probe `agents run auto` routes on (the same per-harness account probe
+ * `agents view` aggregates). Harnesses with nothing installed are absent from
+ * the map: not a candidate at all, rather than an excluded one.
+ */
+export async function collectHarnessCandidates(agentIds = ALL_AGENT_IDS) {
+    const entries = await Promise.all(agentIds.map(async (agent) => {
+        if (listInstalledVersions(agent).length === 0)
+            return null;
+        return [agent, await collectRunCandidates(agent)];
+    }));
+    const byHarness = new Map();
+    for (const entry of entries) {
+        if (entry)
+            byHarness.set(entry[0], entry[1]);
+    }
+    return byHarness;
+}
 /**
  * Resolve an account identity to the installed version slot that holds it, over
  * an already-collected candidate list. Pure — no I/O — so it is unit-tested
@@ -478,14 +627,15 @@ function readRotationStamp(agent) {
     catch { /* missing or corrupt — treat as no stamp */ }
     return null;
 }
-export async function resolveRunVersion(agent, strategy, cwd = process.cwd()) {
+export async function resolveRunVersion(agent, strategy, cwd = process.cwd(), collect = collectRunCandidates) {
     const fallback = resolveVersion(agent, cwd);
     if (strategy === 'pinned') {
         return { version: fallback, rotation: null };
     }
+    const candidates = await collect(agent);
     const rotation = strategy === 'available'
-        ? await selectAvailableVersion(agent, fallback)
-        : await selectBalancedVersion(agent);
+        ? pickAvailableCandidate(candidates, fallback)
+        : pickBalancedCandidate(candidates);
     if (rotation) {
         // `available` is sticky to the pinned default when healthy. Use the 60s
         // anti-collision stamp to nudge parallel callers off the same version.
@@ -503,7 +653,7 @@ export async function resolveRunVersion(agent, strategy, cwd = process.cwd()) {
         emit('rotation.resolved', { module: 'rotate', agent, version: rotation.picked.version, strategy, healthy: rotation.healthy.length, excluded: rotation.excluded.length });
         return { version: rotation.picked.version, rotation };
     }
-    return { version: fallback, rotation: null };
+    return { version: fallback, rotation: null, exhausted: candidates.length > 0 ? candidates : undefined };
 }
 /**
  * Cap on the number of healthy accounts a single run will re-dispatch through

package/dist/lib/routines.js

@@ -16,6 +16,7 @@ import { atomicWriteFileSync } from './fs-atomic.js';
 import { ALL_AGENT_IDS } from './agents.js';
 import { machineId, normalizeHost } from './machine-id.js';
 import { resolveActor } from './actor.js';
+import { percentile } from './percentile.js';
 export const HOST_STRATEGIES = ['local', 'host', 'fleet', 'cloud'];
 /** Canonical set of accepted GitHub trigger events — single source for validation. */
 export const GITHUB_TRIGGER_EVENTS = [
@@ -964,20 +965,6 @@ export function getLatestCompletedRun(jobName) {
     }
     return null;
 }
-/** Percentile of a sorted-ascending array (linear interpolation). p in [0,100]. */
-function percentile(sorted, p) {
-    if (sorted.length === 0)
-        return 0;
-    if (sorted.length === 1)
-        return sorted[0];
-    const rank = (p / 100) * (sorted.length - 1);
-    const lo = Math.floor(rank);
-    const hi = Math.ceil(rank);
-    if (lo === hi)
-        return sorted[lo];
-    const frac = rank - lo;
-    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
-}
 /**
  * Fold a job's run history (`listRuns`) into a duration + outcome summary.
  * `missed` fires (no process ever ran) carry no `duration` and are excluded

package/dist/lib/runner.d.ts

@@ -17,7 +17,7 @@ import type { JobConfig, RunMeta } from './routines.js';
 import type { AgentId } from './types.js';
 import { type FallbackEntry } from './exec.js';
 import type { LoopDeps } from './loop.js';
-import { type RotateResult } from './rotate.js';
+import { resolveRunVersion, type RotateResult } from './rotate.js';
 /** Result of a completed job execution, including metadata and optional report. */
 export interface RunResult {
     meta: RunMeta;
@@ -49,7 +49,9 @@ export interface RoutineLaunchPlan {
  *
  * Workflows are left alone — `agents run <workflow>` owns selection.
  */
-export declare function resolveRoutineLaunch(config: JobConfig, cwd?: string): Promise<RoutineLaunchPlan>;
+export declare function resolveRoutineLaunch(config: JobConfig, cwd?: string, deps?: {
+    resolveRunVersion?: typeof resolveRunVersion;
+}): Promise<RoutineLaunchPlan>;
 /**
  * Rewrite `cmd[0]` to the absolute binary for `agent@version` when installed.
  * Bypasses the bare-name shim so a sandboxed HOME / missing default pin cannot

package/dist/lib/runner.js

@@ -29,7 +29,7 @@ import { reconcileTask as reconcileHostTask } from './hosts/reconcile.js';
 import { backgroundSpawnOptions } from './platform/process.js';
 import { walkForFiles } from './fs-walk.js';
 import { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js';
-import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
+import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, formatNoHealthyAccountError, } from './rotate.js';
 import { readAuthHealth, isDeadVerdict } from './auth-health.js';
 import { machineId } from './machine-id.js';
 import { isSelfUpdatingAgent } from './agents.js';
@@ -66,7 +66,14 @@ const ROUTINE_TRANSCRIPT_SPECS = {
     gemini: [{ root: ['.gemini', 'tmp'], ext: '.json' }],
     antigravity: [{ root: ['.gemini', 'antigravity-cli', 'conversations'], ext: '.db' }],
     droid: [{ root: ['.factory', 'sessions'], ext: '.jsonl' }],
-    kimi: [{ root: ['.kimi-code', 'sessions'], ext: '.json' }],
+    // Kimi splits a session across two files (session/discover.ts:4382-4384):
+    // state.json (title/timestamps) and agents/main/wire.jsonl (the actual
+    // conversation). Both extensions are needed — .json alone archives only
+    // the metadata shell and silently drops every message.
+    kimi: [
+        { root: ['.kimi-code', 'sessions'], ext: '.json' },
+        { root: ['.kimi-code', 'sessions'], ext: '.jsonl' },
+    ],
     grok: [{ root: ['.grok', 'sessions'], ext: '.json' }],
 };
 /** Stable working directory for routine children, independent of the daemon's launch cwd. */
@@ -323,7 +330,7 @@ function readCommandExitCode(runDir) {
  *
  * Workflows are left alone — `agents run <workflow>` owns selection.
  */
-export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
+export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {}) {
     if (config.workflow) {
         return { chain: [], rotation: null, pinned: false };
     }
@@ -357,10 +364,12 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
     const strategy = getConfiguredRunStrategy(agent, cwd);
     let version;
     let rotation = null;
+    let exhausted;
     try {
-        const resolved = await resolveRunVersion(agent, strategy, cwd);
+        const resolved = await (deps.resolveRunVersion ?? resolveRunVersion)(agent, strategy, cwd);
         version = resolved.version ?? undefined;
         rotation = resolved.rotation;
+        exhausted = resolved.exhausted;
         if (rotation) {
             const label = rotation.picked.email
                 ? `${rotation.picked.email} · ${agent}@${rotation.picked.version}`
@@ -378,7 +387,7 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
                 process.stderr.write(`[agents] routine ${config.name}: skipped ${reasons}\n`);
             }
         }
-        else if (!version) {
+        else if (!version && !exhausted) {
             process.stderr.write(`[agents] routine ${config.name}: strategy ${strategy} found no usable ${agent} version; ` +
                 `falling back to default pin\n`);
         }
@@ -386,6 +395,13 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
     catch (err) {
         process.stderr.write(`[agents] routine ${config.name}: strategy ${strategy} skipped: ${err.message}\n`);
     }
+    // Zero healthy accounts is NOT a "fall back to the default pin" case — that
+    // pin is exactly the exhausted account an unattended routine would hammer
+    // every tick (RUSH-2132). Throwing fails the job run (nonzero), and the
+    // message text is the contract the Factory watchdog tail-detects.
+    if (exhausted) {
+        throw new Error(formatNoHealthyAccountError(agent, strategy, exhausted));
+    }
     if (!version) {
         version = resolveVersion(agent, cwd) ?? undefined;
     }

package/dist/lib/session/bash-command.js

@@ -64,6 +64,7 @@ const TOOL_REGISTRY = {
     mv: { category: 'shell', signal: 'low', action: 'moving files' },
     cp: { category: 'shell', signal: 'low', action: 'copying files' },
     mkdir: { category: 'shell', signal: 'low', action: 'making directories' },
+    rmdir: { category: 'shell', signal: 'low', action: 'removing directories' },
     touch: { category: 'shell', signal: 'low', action: 'touching files' },
     echo: { category: 'shell', signal: 'low', action: 'echoing' },
     printf: { category: 'shell', signal: 'low', action: 'printing' },
@@ -115,6 +116,13 @@ const VALUE_FLAGS = {
     kubectl: new Set(['-n', '--namespace', '--kubeconfig', '--context', '--cluster', '--user', '-s', '--server', '--as', '--token', '--cache-dir', '--request-timeout']),
     rush: new Set(),
     openclaw: new Set(),
+    // The repo's own toolchain — heavy in real transcripts (`agents` alone was the
+    // top unrecognized token). Two-level so they bucket by subcommand
+    // (`agents sessions`, `linear list`) instead of one flat `other` pile (#1830).
+    // `ag` is deliberately NOT here — it is the silver searcher in TOOL_REGISTRY,
+    // not the agents alias, in this classifier's world.
+    agents: new Set(['-H', '--host', '--device']),
+    linear: new Set(),
 };
 /** Tools whose bucket key includes the second token (subcommand). */
 const TWO_LEVEL_TOOLS = new Set(Object.keys(VALUE_FLAGS));
@@ -141,8 +149,8 @@ export function unwrapCommand(cmd) {
     const prefix = s.match(/^(?:sudo|time)(?:\s+(?:-[uUgGhpCrtDR]\s+\S+|-\S+))*\s+(.+)$/);
     if (prefix)
         return unwrapCommand(prefix[1]);
-    // cd foo && command
-    const cd = s.match(/^cd\s+\S+\s*&&\s*(.+)$/);
+    // cd foo && command  (also `cd foo; command` and newline-separated `cd foo\ncommand`)
+    const cd = s.match(/^cd\s+\S+\s*(?:&&|;|\n)\s*([\s\S]+)$/);
     if (cd)
         return unwrapCommand(cd[1]);
     // npx / bunx
@@ -191,7 +199,11 @@ function splitOnOperators(cmd) {
             i += 2;
             continue;
         }
-        if (ch === '|' || ch === ';') {
+        // A newline separates commands the same way `;` does (an unquoted, un-escaped
+        // line break), so `cd X\ncmd` splits into two segments instead of reading as
+        // one `cd` command — the top source of `other` classifications (#1830). A
+        // `\`-continued line never reaches here (handled by the escape branch above).
+        if (ch === '|' || ch === ';' || ch === '\n') {
             if (current.trim())
                 parts.push(current.trim());
             current = '';
@@ -247,22 +259,61 @@ function scanSubcommand(tokens, tool) {
     }
     return '';
 }
+/**
+ * The classifier reads only the executable and the first non-flag token, both at
+ * the very head of the first simple command. Tokenizing the *entire* command —
+ * every pipeline segment, multi-KB heredoc bodies included — to reach the first
+ * word cost up to ~1ms per call (a 7.8KB `cat <<HEREDOC …` classified on the word
+ * `cat`). Tokenize only this much of the head instead: enough for the executable
+ * plus a subcommand and its flags, never a heredoc tail (#1830, ~3.3x faster).
+ */
+const CLASSIFY_HEAD_LIMIT = 200;
+/**
+ * Tokens of the first simple command only, tokenizing just the head of the
+ * unwrapped string. Mirrors {@link tokenizeBash}'s first-segment result for
+ * short commands but skips the cost of tokenizing the whole command; the full
+ * multi-segment tokenizer stays available for callers that need every segment.
+ */
+function firstSimpleCommandTokens(command) {
+    const unwrapped = unwrapCommand(command);
+    const head = unwrapped.length > CLASSIFY_HEAD_LIMIT ? unwrapped.slice(0, CLASSIFY_HEAD_LIMIT) : unwrapped;
+    const firstSegment = splitOnOperators(head)[0] ?? '';
+    if (!firstSegment)
+        return [];
+    try {
+        return shlexSplit(firstSegment);
+    }
+    catch {
+        // The head cut a quote mid-string (e.g. a long quoted flag value like
+        // `git -c http.extraheader="Authorization: Bearer …" fetch`), so shlex threw
+        // on the unbalanced quote. A whitespace split of the truncated head would
+        // mis-read the value as the subcommand, so re-tokenize the FULL first
+        // segment instead — only the rare throw path pays that cost.
+        const fullFirst = splitOnOperators(unwrapped)[0] ?? firstSegment;
+        try {
+            return shlexSplit(fullFirst);
+        }
+        catch {
+            // Genuinely unbalanced quoting even in the full segment — a whitespace
+            // split of the full segment still yields the leading executable.
+            return fullFirst.split(/\s+/).filter(Boolean);
+        }
+    }
+}
 /**
  * Classify the first simple command in a Bash string. Returns coarse metadata
  * (tool name, category, subcommand, human action) used for summaries and
  * activity logging. Unknown executables fall back to `other`.
  */
 export function classifyBashCommand(command) {
-    const simpleCommands = tokenizeBash(command);
-    if (!simpleCommands.length) {
-        return { tool: 'other', category: 'other', subcommand: '', action: 'running command', summary: '', signal: 'low' };
-    }
-    const tokens = simpleCommands[0];
+    const tokens = firstSimpleCommandTokens(command);
     if (!tokens.length) {
         return { tool: 'other', category: 'other', subcommand: '', action: 'running command', summary: '', signal: 'low' };
     }
     const first = tokens[0];
-    const baseRaw = first.replace(/^[./]+/, '').toLowerCase();
+    // Reduce a path executable to its basename so `~/.agents/skills/linear/scripts/linear`,
+    // `/usr/bin/git`, and `./tool` all resolve by tool name, not the full path (#1830).
+    const baseRaw = first.replace(/^.*\//, '').toLowerCase();
     const base = baseRaw.endsWith('.exe') ? baseRaw.slice(0, -4) : baseRaw;
     const canonical = ALIAS_MAP.get(base);
     const info = canonical ? TOOL_REGISTRY[canonical] : undefined;

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

@@ -8,10 +8,11 @@
  */
 import Database from '../sqlite.js';
 import type { SessionAgentId, SessionMeta } from './types.js';
+import { type IndexedToolCall } from './tool-calls.js';
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 22;
+export declare const SCHEMA_VERSION = 30;
 /** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
@@ -54,6 +55,9 @@ export interface SessionRow {
     linear_project_url: string | null;
     actor: string | null;
     initiated_by: string | null;
+    /** NULL means "not yet computed" (a row scanned before this field existed) — see rowToMeta. */
+    used_browser: number | null;
+    used_computer: number | null;
 }
 /** File stat snapshot used to detect changes between scan runs. */
 export interface ScanStamp {
@@ -88,6 +92,20 @@ export interface QueryOptions {
      * with NULLs sorted last so unpriced rows never crowd out real data.
      */
     sortBy?: 'timestamp' | 'cost' | 'duration';
+    /** Internal warm-cache path; callers must validate the small final result set. */
+    skipExistenceCheck?: boolean;
+    /**
+     * Only sessions that invoked this skill (#12), joined against
+     * session_resource_usage.kind='skill'. Matches either the full stored name
+     * (bare, or `plugin:name` for a plugin skill) or just the short name after
+     * the colon — `--skill design` finds a session that used `rush:design`.
+     */
+    skill?: string;
+    /**
+     * Only sessions that used a skill or slash-command owned by this plugin
+     * (#12), joined against session_resource_usage.plugin.
+     */
+    plugin?: string;
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export declare function getDB(): Database.Database;
@@ -189,6 +207,9 @@ export declare function upsertSessionsBatch(entries: Array<{
     scan?: ScanStamp;
     parserState?: string;
     contentText?: string;
+    toolCalls?: IndexedToolCall[];
+    toolScan?: ScanStamp;
+    toolIndexMode?: 'replace' | 'append';
 }>): void;
 /**
  * Sync labels for a set of sessions. For each id in the map, if the stored