@phnx-labs/agents-cli 1.21.1 → 1.21.3

package/dist/lib/resources.js

@@ -15,6 +15,16 @@ import { WorkflowsHandler } from './resources/workflows.js';
 import { isCapable } from './capabilities.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';
 import { isNameActiveInResourceProfile } from './resource-profiles.js';
+import { resolveSnapshotSha } from './git.js';
+/** Build a ResolvedResource with a lazy, memoized `snapshotSha` getter. */
+function withProvenance(base) {
+    return {
+        ...base,
+        get snapshotSha() {
+            return resolveSnapshotSha(base.repoRoot);
+        },
+    };
+}
 function profiledKind(kind) {
     switch (kind) {
         case 'commands':
@@ -70,19 +80,19 @@ export function resolveResource(kind, name, cwd) {
     const projectDir = getProjectAgentsDir(cwd);
     const extraRepos = getEnabledExtraRepos();
     const candidates = [
-        ...(projectDir ? [[path.join(projectDir, kind), 'project']] : []),
-        [path.join(getUserAgentsDir(), kind), 'user'],
-        [path.join(getSystemAgentsDir(), kind), 'system'],
-        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias]),
+        ...(projectDir ? [[path.join(projectDir, kind), 'project', projectDir]] : []),
+        [path.join(getUserAgentsDir(), kind), 'user', getUserAgentsDir()],
+        [path.join(getSystemAgentsDir(), kind), 'system', getSystemAgentsDir()],
+        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias, e.dir]),
     ];
-    for (const [dir, source] of candidates) {
+    for (const [dir, source, repoRoot] of candidates) {
         if (!fs.existsSync(dir))
             continue;
         // Try exact name (for directories like skills/subagents)
         const exactPath = path.join(dir, name);
         if (fs.existsSync(exactPath)) {
             if (resourceIsActive(kind, name, source)) {
-                return { name, path: exactPath, source };
+                return withProvenance({ name, path: exactPath, source, repoRoot });
             }
             continue;
         }
@@ -94,7 +104,7 @@ export function resolveResource(kind, name, cwd) {
             const withExt = exactPath + ext;
             if (fs.existsSync(withExt)) {
                 if (resourceIsActive(kind, name, source)) {
-                    return { name, path: withExt, source };
+                    return withProvenance({ name, path: withExt, source, repoRoot });
                 }
                 continue;
             }
@@ -113,12 +123,12 @@ export function listResources(kind, cwd) {
     const projectDir = getProjectAgentsDir(cwd);
     const extraRepos = getEnabledExtraRepos();
     const roots = [
-        ...(projectDir ? [[path.join(projectDir, kind), 'project']] : []),
-        [path.join(getUserAgentsDir(), kind), 'user'],
-        [path.join(getSystemAgentsDir(), kind), 'system'],
-        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias]),
+        ...(projectDir ? [[path.join(projectDir, kind), 'project', projectDir]] : []),
+        [path.join(getUserAgentsDir(), kind), 'user', getUserAgentsDir()],
+        [path.join(getSystemAgentsDir(), kind), 'system', getSystemAgentsDir()],
+        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias, e.dir]),
     ];
-    for (const [dir, source] of roots) {
+    for (const [dir, source, repoRoot] of roots) {
         if (!fs.existsSync(dir))
             continue;
         let entries;
@@ -143,11 +153,12 @@ export function listResources(kind, cwd) {
             if (!resourceIsActive(kind, rawName, source))
                 continue;
             seen.add(rawName);
-            results.push({
+            results.push(withProvenance({
                 name: rawName,
                 path: path.join(dir, entry.name),
                 source,
-            });
+                repoRoot,
+            }));
         }
     }
     return results;

package/dist/lib/rotate.d.ts

@@ -24,6 +24,15 @@ export interface RotateCandidate {
     usageStatus: AccountInfo['usageStatus'];
     usageSnapshot: UsageSnapshot | null;
     usageError: string | null;
+    /**
+     * Projected minutes until this account's 5-hour session window caps, as
+     * computed by the daemon's burn-rate refresher and read from the headroom
+     * cache. `null` when unknown (cold cache, idle, or not burning up). Balanced
+     * routing deprioritizes an account projected to cap soon — see
+     * {@link capacityWeight} — so a launch avoids an account racing toward its
+     * limit, not just one already 100%-maxed.
+     */
+    usageMinutesToLimit: number | null;
     plan: string | null;
     signedIn: boolean;
     lastActive: Date | null;
@@ -141,6 +150,24 @@ export declare function checkRunAccountReadiness(agent: AgentId, version: string
  * version so behavior stays predictable.
  */
 export declare function pickBalancedCandidate(candidates: RotateCandidate[], nowMs?: number): RotateResult | null;
+/**
+ * How far from its projected cap an account must be to keep its FULL headroom
+ * weight. Inside this horizon the weight is scaled down linearly toward the
+ * floor, so an account racing toward its 5h cap loses priority before it maxes.
+ */
+export declare const PROJECTION_HORIZON_MIN = 30;
+/**
+ * Weight one candidate by remaining routing capacity, deprioritized by how soon
+ * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
+ * an account with no live snapshot is treated as full-capacity (100) since there
+ * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
+ * projection on the 5h session window) then scales that base: >= horizon (or
+ * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
+ * so a launch avoids an account projected to cap soon, not just a 100%-maxed
+ * one. Pure + exported so the deprioritization is unit-tested directly (a
+ * weighted-random draw is not).
+ */
+export declare function capacityWeight(usedPercent: number | null, minutesToLimit: number | null): number;
 /**
  * Pick an available candidate. Prefers the configured pinned version when that
  * version has usage available; otherwise routes to the candidate with the most

package/dist/lib/rotate.js

@@ -12,6 +12,7 @@ import { listInstalledVersions, getVersionHomePath, resolveVersion } from './ver
 import { getProjectRunConfigs } from './run-config.js';
 import { emit } from './events.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, deriveUsageStatusFromSnapshot, } from './usage.js';
+import { readAccountHeadroom } from './fleet-cache.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
     fs.mkdirSync(dir, { recursive: true });
@@ -264,20 +265,37 @@ function preferVerified(pool, nowMs, choose) {
         usageUnverified: verified.length === 0,
     };
 }
+/**
+ * How far from its projected cap an account must be to keep its FULL headroom
+ * weight. Inside this horizon the weight is scaled down linearly toward the
+ * floor, so an account racing toward its 5h cap loses priority before it maxes.
+ */
+export const PROJECTION_HORIZON_MIN = 30;
+/**
+ * Weight one candidate by remaining routing capacity, deprioritized by how soon
+ * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
+ * an account with no live snapshot is treated as full-capacity (100) since there
+ * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
+ * projection on the 5h session window) then scales that base: >= horizon (or
+ * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
+ * so a launch avoids an account projected to cap soon, not just a 100%-maxed
+ * one. Pure + exported so the deprioritization is unit-tested directly (a
+ * weighted-random draw is not).
+ */
+export function capacityWeight(usedPercent, minutesToLimit) {
+    const base = usedPercent === null ? 100 : Math.max(1, 100 - usedPercent);
+    if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
+        return base;
+    const factor = Math.max(0, Math.min(1, minutesToLimit / PROJECTION_HORIZON_MIN));
+    return Math.max(1, base * factor);
+}
 /**
  * Pick one candidate from `sorted` using weights proportional to remaining
- * routing capacity. Floor each weight at 1 so a near-exhausted-but-still-
- * eligible candidate can still be picked occasionally. When usage is unknown
- * (no live snapshot), treat the candidate as full-capacity (weight 100) — we
- * have no signal to deprioritize it.
+ * routing capacity (see {@link capacityWeight}). Floor each weight at 1 so a
+ * near-exhausted-but-still-eligible candidate can still be picked occasionally.
  */
 function weightedRandomByCapacity(sorted) {
-    const weights = sorted.map((c) => {
-        const used = getRoutingUsedPercent(c.usageSnapshot);
-        if (used === null)
-            return 100;
-        return Math.max(1, 100 - used);
-    });
+    const weights = sorted.map((c) => capacityWeight(getRoutingUsedPercent(c.usageSnapshot), c.usageMinutesToLimit));
     const total = weights.reduce((sum, w) => sum + w, 0);
     if (total <= 0)
         return sorted[0];
@@ -350,26 +368,35 @@ export async function collectRunCandidates(agent) {
             lastActive: info.lastActive,
         };
     }));
-    // These candidates feed a routing decision, so cap how stale their usage may
-    // be (see USAGE_DECISION_MAX_AGE_MS). Past that the fetch blocks on a live
-    // read instead of serving the cache — one bounded, parallel round trip per
-    // account, and none at all inside the 2-minute fresh window that back-to-back
-    // launches hit. A failed read still falls back to the cache; the pick then
-    // routes around it via isUsageVerified rather than trusting the old number.
+    // These candidates feed a routing decision on the `agents run` hot path, so
+    // this read is CACHE-ONLY (`readOnly`): it never blocks on a live provider
+    // fetch. A snapshot older than USAGE_DECISION_MAX_AGE_MS is not trusted for
+    // the pick — but the guard that enforces that is `isUsageVerified` below, not
+    // a blocking refresh here. Keeping the cache fresh is the daemon's job
+    // (`runUsageRefresh`, adaptive + rate-capped, sole-writer per local account),
+    // so a cold `agents run` reads the last daemon-written snapshot instead of
+    // stalling on N parallel HTTP round trips (the measured cold-start stall this
+    // removes). A stale-or-absent snapshot routes as unverified, exactly as a
+    // failed live read did before.
     const { usageByKey } = await getUsageInfoByIdentity(rows.map(({ home, info, version }) => ({
         agentId: agent,
         home,
         cliVersion: version,
         info,
-    })), { maxAgeMs: USAGE_DECISION_MAX_AGE_MS });
+    })), { readOnly: true });
     return rows.map(({ home: _home, info, ...candidate }) => {
         const usageKey = getUsageLookupKey(info);
         const usage = usageKey ? usageByKey.get(usageKey) : undefined;
+        // Projected headroom is a separate cache-only read (also off the network) —
+        // the daemon publishes minutesToLimit; a cold cache yields null and routing
+        // falls back to snapshot-only weighting.
+        const headroom = usageKey ? readAccountHeadroom(usageKey) : null;
         return {
             ...candidate,
             usageKey,
             usageSnapshot: usage?.snapshot ?? null,
             usageError: usage?.error ?? null,
+            usageMinutesToLimit: headroom?.minutesToLimit ?? null,
         };
     });
 }

package/dist/lib/routines.d.ts

@@ -504,6 +504,22 @@ export declare function getLatestRun(jobName: string): RunMeta | null;
  * run's prompt.
  */
 export declare function getLatestCompletedRun(jobName: string): RunMeta | null;
+/** Duration + outcome rollup for a job's run history. */
+export interface RoutineStats {
+    /** Total run records (any status, including `missed`). */
+    count: number;
+    failed: number;
+    missed: number;
+    avgMs: number;
+    p50: number;
+    p95: number;
+}
+/**
+ * Fold a job's run history (`listRuns`) into a duration + outcome summary.
+ * `missed` fires (no process ever ran) carry no `duration` and are excluded
+ * from the latency percentiles but still counted in `count`/`missed`.
+ */
+export declare function routineStats(jobName: string): RoutineStats;
 /** Persist run metadata to its run directory as meta.json. */
 export declare function writeRunMeta(meta: RunMeta): void;
 /** Read run metadata from disk. Returns null if missing or corrupt. */

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,6 +965,31 @@ export function getLatestCompletedRun(jobName) {
     }
     return null;
 }
+/**
+ * Fold a job's run history (`listRuns`) into a duration + outcome summary.
+ * `missed` fires (no process ever ran) carry no `duration` and are excluded
+ * from the latency percentiles but still counted in `count`/`missed`.
+ */
+export function routineStats(jobName) {
+    const runs = listRuns(jobName);
+    const failed = runs.filter((r) => r.status === 'failed' || r.status === 'timeout').length;
+    const missed = runs.filter((r) => r.status === 'missed').length;
+    const durations = runs
+        .map((r) => r.duration)
+        .filter((d) => typeof d === 'number' && Number.isFinite(d))
+        .sort((a, b) => a - b);
+    const avgMs = durations.length > 0
+        ? Math.round(durations.reduce((sum, d) => sum + d, 0) / durations.length)
+        : 0;
+    return {
+        count: runs.length,
+        failed,
+        missed,
+        avgMs,
+        p50: Math.round(percentile(durations, 50)),
+        p95: Math.round(percentile(durations, 95)),
+    };
+}
 /** Persist run metadata to its run directory as meta.json. */
 export function writeRunMeta(meta) {
     ensureAgentsDir();

package/dist/lib/runner.js

@@ -46,10 +46,35 @@ const AGENT_COMMANDS = {
 /** Agents the daemon can actually run, derived from the command table above
  * so the `--agent` help and any validation can never drift from it. */
 export const ROUTINE_AGENT_IDS = Object.freeze(Object.keys(AGENT_COMMANDS));
+/**
+ * Where each agent's transcript files live under an overlay HOME, mirroring
+ * `SESSION_ROOT_SPECS` (session/discover.ts) — the CLI's own source of truth
+ * for which on-disk trees hold live session files. Kept in this shape (not a
+ * shared import) because `archiveRoutineTranscripts` only needs a flat
+ * root+ext pair to `walkForFiles`, not the version-home/backup fan-out
+ * `getAgentSessionDirs` does for live discovery.
+ *
+ * `opencode` is deliberately absent: `SESSION_ROOT_SPECS` itself has no entry
+ * for it — its transcripts live in one incrementally-scanned SQLite db
+ * (`scanOpenCodeIncremental`), not a per-session file tree — so there is
+ * nothing here to mirror without inventing a new discovery path.
+ */
 const ROUTINE_TRANSCRIPT_SPECS = {
     claude: [{ root: ['.claude', 'projects'], ext: '.jsonl' }],
     codex: [{ root: ['.codex', 'sessions'], ext: '.jsonl' }],
     cursor: [{ root: ['.cursor', 'projects'], ext: '.jsonl' }],
+    gemini: [{ root: ['.gemini', 'tmp'], ext: '.json' }],
+    antigravity: [{ root: ['.gemini', 'antigravity-cli', 'conversations'], ext: '.db' }],
+    droid: [{ root: ['.factory', 'sessions'], ext: '.jsonl' }],
+    // 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. */
 export function routineSpawnCwd(config, configuredRoot = getProjectRoot()) {
@@ -1080,6 +1105,14 @@ export async function executeJobDetached(config, hooks) {
     // wait); the next schedule tick re-selects if this attempt still fails.
     const launch = await resolveRoutineLaunch(config);
     const version = launch.chain[0]?.version ?? config.version;
+    const timer = createTimer('agent.run', {
+        agent: config.agent,
+        version,
+        jobName: config.name,
+        mode: config.mode,
+        ...redactPrompt(config.prompt),
+        schedule: config.schedule,
+    });
     const resolvedPrompt = resolveJobPrompt(config);
     let cmd = buildJobCommand(config, resolvedPrompt);
     // workflow AND resume dispatch through `agents run` — never binary-pin them (pinning
@@ -1143,6 +1176,7 @@ export async function executeJobDetached(config, hooks) {
             finalizeRunMeta(meta, 'failed', 1, { errorMessage: reason });
             writeRunMeta(meta);
             archiveRoutineTranscripts(meta, runDir, overlayHome);
+            timer.end({ status: 'failed', exitCode: 1, runId, error: reason });
             return meta;
         }
     }
@@ -1164,6 +1198,7 @@ export async function executeJobDetached(config, hooks) {
         const isAuthFailure = !!errorMessage && errorMessage.startsWith('auth_failed:');
         if (status !== 'timeout' && !isAuthFailure)
             extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
+        timer.end({ status, exitCode: exitCode ?? undefined, runId, ...(errorMessage ? { error: errorMessage } : {}) });
         // Fire the finish/output notification AFTER the report is written so the hook
         // can read report.md (RUSH-2030). Best-effort; never breaks finalization.
         safeHook(hooks?.onFinish ? () => hooks.onFinish(meta) : undefined);
@@ -1214,6 +1249,11 @@ export async function executeJobDetached(config, hooks) {
  * `monitorRunningJobs` reaps the record on the next tick.
  */
 function executeCommandJobDetached(config, hooks) {
+    const timer = createTimer('agent.run', {
+        jobName: config.name,
+        mode: config.mode,
+        schedule: config.schedule,
+    });
     const runId = generateRunId();
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
@@ -1259,6 +1299,7 @@ function executeCommandJobDetached(config, hooks) {
         settled = true;
         finalizeRunMeta(meta, status, exitCode, errorMessage ? { errorMessage } : undefined);
         writeRunMeta(meta);
+        timer.end({ status, exitCode, runId, ...(errorMessage ? { error: errorMessage } : {}) });
         // Finish notification (RUSH-2030). For command routines the threshold only
         // surfaces failures, decided in routine-notify.ts. Best-effort.
         safeHook(hooks?.onFinish ? () => hooks.onFinish(meta) : undefined);

package/dist/lib/secrets/usage-db.d.ts

@@ -1,69 +1,34 @@
 /**
- * SQLite-backed usage read-model for `agents secrets`.
- *
- * A small local database at ~/.agents/secrets/secrets.db that records one
- * value-free row for every secret lifecycle/access event a bundle accrues over
- * its life — created, imported, exported, viewed, accessed (read for injection),
- * unlocked. It is the queryable, per-bundle counterpart to the append-only
- * ~/.agents/events.jsonl audit log: the SAME chokepoint (`emitSecretAudit`,
- * lib/secrets/audit.ts) feeds both, and this store answers "how often / how
- * recently / by whom was THIS bundle used?" without scanning the whole event
- * stream. It is a DERIVED index fed off the real access flow — the way
- * sessions.db indexes session metadata — never a second write path an operation
- * has to remember to call.
- *
- * Contract, mirroring the audit log: NEVER a secret value. Only metadata — the
- * bundle name, the event kind, key counts, the resolving agent/host, a status.
- *
- * Every write is best-effort: a failure here (missing runtime SQLite, a locked
- * db, a read-only fs) is swallowed so usage telemetry can never break secret
- * resolution. Set AGENTS_NO_USAGE_TRACK=1 to disable recording entirely (used by
- * tests and by callers that must stay perfectly silent).
+ * Secrets usage read-model — thin adapter over the analytics usage warehouse
+ * (`kind=secret`). Kept so `secrets view` / `list` / `activity` keep their API
+ * while the durable store lives at ~/.agents/.history/analytics/usage.db.
  */
-/** The lifecycle/access events a bundle accrues over its life. */
 export type SecretUsageEvent = 'access' | 'unlock' | 'import' | 'export' | 'create' | 'view';
-/** All event kinds, in the order `view` prints them. */
 export declare const SECRET_USAGE_EVENTS: readonly SecretUsageEvent[];
 export interface RecordUsageParams {
-    /** Bundle the event applies to (required — usage is always per-bundle). */
     bundle: string;
-    /** What happened. */
     event: SecretUsageEvent;
-    /** Resolving agent/harness identity, when known (`*` = a global grant). */
     agent?: string;
-    /** Remote host the value was pulled from / pushed to, when applicable. */
     host?: string;
-    /** Free-form origin label, e.g. 'agent', 'reveal', 'ssh', '1password'. */
     source?: string;
-    /** Outcome; defaults to 'success'. */
     status?: 'success' | 'error';
-    /** How many keys the event touched (names only are ever known here). */
     keyCount?: number;
 }
-/** One event kind's rollup for a bundle. */
 export interface UsageStat {
     count: number;
-    /** ISO 8601 timestamp of the most recent occurrence, or null if never. */
     last: string | null;
 }
-/** Per-bundle usage summary for the `view` / `list` surfaces. */
 export interface BundleUsageSummary {
     bundle: string;
-    /** Every recorded event, all kinds. */
     total: number;
-    /** Rollup per event kind (every kind present, zeroed when unused). */
     events: Record<SecretUsageEvent, UsageStat>;
-    /** Most recent event across all kinds, or null. */
     lastUsedAt: string | null;
-    /** Earliest event across all kinds, or null. */
     firstUsedAt: string | null;
-    /** Event count grouped by resolving agent, most-first. `*` = a global grant. */
     byAgent: Array<{
         agent: string;
         count: number;
     }>;
 }
-/** One recorded event, for the `secrets activity` timeline. */
 export interface SecretUsageHistoryEntry {
     ts: string;
     bundle: string;
@@ -74,33 +39,8 @@ export interface SecretUsageHistoryEntry {
     status: string | null;
     keyCount: number | null;
 }
-/**
- * Record one usage event. Best-effort and value-free — swallows every error and
- * honors AGENTS_NO_USAGE_TRACK so telemetry never blocks or slows a read. Rows
- * with an empty bundle name are ignored (usage is per-bundle by definition).
- *
- * This is called from ONE place only — `emitSecretAudit` (lib/secrets/audit.ts)
- * — so every recorded event has already been written to the events.jsonl audit
- * log through the same chokepoint. Do not call it from a command handler; emit
- * the audit event instead.
- */
 export declare function recordSecretUsage(p: RecordUsageParams): void;
-/**
- * Usage summary for one bundle, or undefined when nothing has ever been
- * recorded (or the DB is unavailable). Never throws.
- */
 export declare function getBundleUsage(bundle: string): BundleUsageSummary | undefined;
-/**
- * Usage summaries for every bundle that has any recorded event, keyed by bundle
- * name. Powers `secrets list --sort uses|used`. Empty map when the DB is
- * unavailable or has no rows. Never throws.
- */
 export declare function getAllBundleUsage(): Map<string, BundleUsageSummary>;
-/**
- * Recent events for the `secrets activity` timeline — one bundle when named,
- * else across all bundles — newest first. Empty when the DB is unavailable.
- * Never throws.
- */
 export declare function getUsageHistory(bundle: string | undefined, limit?: number): SecretUsageHistoryEntry[];
-/** Close the cached handle. Used by tests between temp-db swaps. */
 export declare function closeSecretsUsageDb(): void;