@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/audit/log.js

@@ -1,13 +1,3 @@
-/**
- * Run-dispatch recording (issue #347) — now a thin write into the unified
- * event stream (`emit('run.dispatched', …)`). The historical hash-chained file
- * at `~/.agents/.history/audit/log.jsonl` is still readable via
- * `readAuditLog` / `verifyAuditChain` for pre-unification history; new runs do
- * NOT append there. Operators list run outcomes with:
- *
- *   agents events --include runs
- *   agents events audit          # nested alias of the above
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
@@ -15,24 +5,10 @@ import { sha256 } from '../staleness/fingerprint.js';
 import { getHistoryDir } from '../state.js';
 import { ensureLockTarget, withFileLock } from '../fs-atomic.js';
 import { emit } from '../feed/events.js';
-/** First record's `prevHash` — a fixed anchor so the chain has a root. */
 export const GENESIS_HASH = 'GENESIS';
-/**
- * Absolute path to the append-only audit log. Lives under `.history/` — the
- * durable-but-machine-local runtime bucket that is gitignored and never synced
- * by `agents repo push/pull`. Keeping it here (not under a top-level, tracked
- * `~/.agents/` path) means the token-bearing `repo` field can never leak into a
- * version-controlled DotAgents repo, and no cross-machine pull can fork the chain.
- */
 export function getAuditLogPath() {
     return path.join(getHistoryDir(), 'audit', 'log.jsonl');
 }
-/**
- * Deterministic JSON: object keys sorted recursively so the same logical
- * record always serializes to the same bytes (hashing must be reproducible
- * across processes and machines). Values here are all primitives, but the
- * recursion keeps it correct if the record ever nests.
- */
 function canonicalJSON(value) {
     if (value === null || typeof value !== 'object')
         return JSON.stringify(value);
@@ -42,18 +18,16 @@ function canonicalJSON(value) {
     const keys = Object.keys(obj).sort();
     return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalJSON(obj[k])).join(',') + '}';
 }
-/** Compute the sealing hash for a record whose `prevHash` is already set. */
 function hashRecord(record) {
     return sha256(canonicalJSON(record));
 }
-/** Read + parse every record in the log, oldest-first. Missing file → []. */
 function readRecords(logPath) {
     let raw;
     try {
         raw = fs.readFileSync(logPath, 'utf-8');
     }
     catch {
-        return []; // no log yet
+        return [];
     }
     const records = [];
     for (const line of raw.split('\n')) {
@@ -64,20 +38,6 @@ function readRecords(logPath) {
     }
     return records;
 }
-/**
- * Append one record to the hash chain and return it. Links to the previous
- * record's `hash` (or `GENESIS_HASH` for the first), computes the sealing
- * hash, and writes a single JSONL line. Synchronous so the record is durable
- * before the caller proceeds.
- *
- * Read-last-hash + append run under the canonical advisory file lock
- * (`withFileLock`, backed by proper-lockfile). Without it, two concurrent
- * writers — the norm under parallel teams/routines dispatch — both read the
- * same last hash and both write `prevHash=H`, forking the chain into a false
- * "tampered" verdict. The lock forces a total order so every record links off
- * the genuinely-previous one. `ensureLockTarget` creates the file first because
- * proper-lockfile locks an existing path.
- */
 export function appendAuditRecord(entry, logPath = getAuditLogPath()) {
     ensureLockTarget(logPath);
     return withFileLock(logPath, () => {
@@ -89,19 +49,12 @@ export function appendAuditRecord(entry, logPath = getAuditLogPath()) {
         return record;
     });
 }
-/**
- * Walk the chain and confirm every record reproduces. A record is valid when
- * (a) its `prevHash` matches the prior record's `hash` (GENESIS for the first)
- * AND (b) recomputing its sealing hash from its own fields reproduces the
- * stored `hash`. Returns the first failing index in `brokenAt`.
- */
 export function verifyAuditChain(logPath = getAuditLogPath()) {
     let records;
     try {
         records = readRecords(logPath);
     }
     catch (err) {
-        // A line that won't even parse is itself tamper evidence — the log is corrupt.
         return { ok: false, brokenAt: 0 };
     }
     let expectedPrev = GENESIS_HASH;
@@ -116,15 +69,9 @@ export function verifyAuditChain(logPath = getAuditLogPath()) {
     }
     return { ok: true };
 }
-/** Read the whole chain, oldest-first. Exposed for `agents events audit verify`. */
 export function readAuditLog(logPath = getAuditLogPath()) {
     return readRecords(logPath);
 }
-/**
- * Resolve a stable repo label for a run: the git remote origin url when the
- * cwd is inside a repo with one, otherwise the cwd itself. Best-effort — any
- * failure falls back to the cwd.
- */
 function repoLabel(cwd) {
     try {
         const res = spawnSync('git', ['-C', cwd, 'config', '--get', 'remote.origin.url'], {
@@ -138,11 +85,6 @@ function repoLabel(cwd) {
         return cwd;
     }
 }
-/**
- * Record ONE dispatched run at the single exec chokepoint into the unified
- * event stream. Non-fatal by contract: any failure is caught and warned, never
- * thrown — a log hiccup must not crash a run that already finished.
- */
 export function recordDispatchedRun(run) {
     try {
         const outcome = run.exitCode === 0 ? 'ok' : 'fail';

package/dist/lib/auth-health.d.ts

@@ -1,117 +1,33 @@
 import { type AccountInfo } from './agents.js';
 import type { AgentId, Meta } from './types.js';
 import { type ProviderProbe } from './accounting/usage.js';
-/**
- * - `live`        — completed an authenticated request (200).
- * - `revoked`     — the server rejected the token (401/403), except Claude
- *                   setup-token `user:profile` scope denials (those are
- *                   `unverified` via `reason: 'usage_scope'` — RUSH-2392).
- * - `expired`     — locally-detected expiry; not network-verified (no refresh on the read path).
- * - `rate_limited`— the account is throttled per its usage snapshot
- *                   ({@link deriveUsageStatusFromSnapshot} / {@link applyUsageHonesty}),
- *                   not per a probe HTTP 429. A 429 from the usage endpoint is
- *                   probe throttling and never produces `rate_limited`: it keeps
- *                   the previous real verdict when one exists within
- *                   {@link AUTH_PROBE_MAX_AGE_MS}, otherwise `unverified` with
- *                   detail `probe throttled (HTTP 429)` (PHNX-4051).
- * - `unverified`  — credential present, not locally expired, but this agent has
- *                   no in-repo probe endpoint (codex/grok), OR the probe
- *                   endpoint cannot prove live for a known non-revocation
- *                   reason (Claude setup-token usage-scope gap — RUSH-2392),
- *                   OR a throttled probe with no fresh previous verdict (PHNX-4051).
- * - `no_evidence` — a credential is present on disk but THIS box has no evidence,
- *                   either way, that it can authenticate: no probe was possible
- *                   (a worker's setup-token box does not probe the usage endpoint)
- *                   and no run outcome has been recorded here yet. Distinct from
- *                   `unverified` (which is "signed in, no probe endpoint exists for
- *                   this harness") — `no_evidence` is "we did not look", the exact
- *                   state PHNX-4116 stops rendering as a verdict word. A worker
- *                   never PUBLISHES this row (it is dropped in
- *                   {@link probeLocalFleetAuth}); it surfaces only as an in-memory
- *                   account-catalog verdict whose display is a FACT (token presence
- *                   + recorded run outcomes), never the word "no_evidence".
- * - `unconfigured`— no usable credential on disk.
- * - `error`       — network/other failure; verdict indeterminate (keep the last known one).
- */
 export type AuthVerdict = 'live' | 'revoked' | 'expired' | 'rate_limited' | 'unverified' | 'no_evidence' | 'unconfigured' | 'error';
 export interface AuthHealth {
     verdict: AuthVerdict;
-    /** epoch ms of the probe. */
     checkedAt: number;
-    /** optional short human detail (e.g. "HTTP 401", a network error). */
     detail?: string;
-    /** account label for display (email / id), when known. Never part of the key. */
     account?: string;
-    /** Stable registered account id. Display labels are never used as identity. */
     accountId?: string;
-    /**
-     * How this row was observed (PHNX-4116). `probe` (default when absent) is a
-     * network/usage-endpoint probe the daemon ran; `run` is a REAL agent run
-     * outcome recorded on exit — a successful inference (`live`) or an auth failure
-     * (`revoked`/`expired`/`rate_limited`). The auth FACT `agents view` renders
-     * (`last used ok 12m ago` vs `last auth failure 401 …`) reads this so a token's
-     * usability is stated as evidence, not inferred from a stale usage file.
-     */
     source?: 'probe' | 'run';
 }
-/** Maximum age of an auth verdict used for automatic routing decisions. */
 export declare const AUTH_PROBE_MAX_AGE_MS: number;
-/** Agents with a live network probe wired up today. The rest are best-effort. */
 export declare const LIVE_PROBE_AGENTS: ReadonlySet<AgentId>;
-/** Map an HTTP status from a live probe to a verdict. Probe 429 never yields `rate_limited` (PHNX-4051). */
 export declare function classifyHttpStatus(status: number): AuthVerdict;
-/** Turn a raw provider probe (from usage.ts) into a verdict. */
 export declare function verdictFromProbe(probe: ProviderProbe): AuthVerdict;
-/** A short human detail line for a probe result (rendered under --verbose). */
 export declare function probeDetail(probe: ProviderProbe): string | undefined;
-/** Uncolored glyph for a verdict (color is applied by the caller). */
 export declare function verdictGlyph(verdict: AuthVerdict): string;
-/** One-word label for matrices/verbose output. */
 export declare function verdictLabel(verdict: AuthVerdict): string;
-/** Roll a set of verdicts (one host×agent's installs) into counts for a matrix cell. */
 export interface VerdictSummary {
     live: number;
-    /**
-     * unverified — signed in, but this agent has no in-repo live-probe endpoint
-     * (codex/grok). A benign, neutral state: the account is present and usable, we
-     * just can't complete a 2xx to prove it. It must NOT be lumped with the soft
-     * `warn` bucket, or a fully-logged-in codex/grok fleet reads as half-degraded
-     * (the exact "cry wolf" the ping matrix used to produce).
-     */
     present: number;
-    /** revoked — the server rejected the token (401/403). Genuinely needs re-login. */
     bad: number;
-    /**
-     * expired / rate_limited / error — degraded or unknown, but NOT "re-login now".
-     * `expired` is soft for kimi/droid (their CLIs refresh the token on next launch;
-     * we don't refresh on the read path), so it must not be lumped with revoked or
-     * we'd cry wolf on a self-healing token.
-     */
     warn: number;
     total: number;
 }
 export declare function summarizeVerdicts(verdicts: AuthVerdict[]): VerdictSummary;
-/** A resolved display color; the caller maps it to chalk. Pure, so it's unit-tested. */
 export type AuthCellColor = 'green' | 'yellow' | 'red' | 'gray' | 'dim';
-/**
- * Color for a single verdict in the per-account (`--verbose`) breakdown. This is
- * the one source of truth shared with {@link authCellColor} so the matrix and the
- * account list can never drift — they did: the matrix painted `expired` yellow
- * while the verbose list painted it *red* (lumped with revoked), directly against
- * the {@link VerdictSummary} contract. Red is reserved for `revoked` (the only
- * "re-login now"); `unverified` is a neutral signed-in state (gray);
- * `expired`/`rate_limited`/`error` are soft (yellow).
- */
 export declare function verdictColor(verdict: AuthVerdict): AuthCellColor;
-/**
- * Color for a matrix cell that rolls up several accounts. Red only when a token
- * was genuinely rejected (`revoked`); yellow for soft/expired; green when at least
- * one account is live-verified and none are soft/revoked; gray when accounts are
- * present but unverifiable (codex/grok) — never the alarming yellow the old
- * renderer used, which made a fully-logged-in fleet read as half-broken.
- */
 export declare function authCellColor(summary: VerdictSummary): AuthCellColor;
-/** Verdicts that mean "this token was rejected by the server — re-login required". */
 export declare function isDeadVerdict(verdict: AuthVerdict): boolean;
 /**
  * A host's rolled-up auth state for the `fleet status` Auth column.
@@ -127,99 +43,29 @@ export declare function isDeadVerdict(verdict: AuthVerdict): boolean;
  * only verdict that actually means "re-login now" ({@link isDeadVerdict}).
  */
 export interface HostAuthSummary {
-    /** Live-verified accounts (a real 2xx). */
     live: number;
-    /** Signed in but this agent has no live-probe endpoint — benign, neutral. */
     present: number;
-    /** Soft/degraded: expired (self-healing) / rate_limited / error. Mild warning. */
     degraded: number;
-    /** Server rejected the token — genuinely needs re-login. */
     revoked: number;
-    /** Total cached rows for this host (0 → the renderer shows "—"). */
     total: number;
-    /** Oldest `checkedAt` (epoch ms) among this host's cached rows, or null when none. */
     oldestCheckedAt: number | null;
 }
-/**
- * Roll every cached (agent, version) row for one host into a {@link HostAuthSummary}
- * plus the age of its stalest entry. Pure — reads the map the caller already
- * loaded via {@link readAuthHealthCache}, so `fleet status` renders the Auth
- * column without any network probe. A host with no cached rows yields an empty
- * summary (total 0), which the renderer shows as "—".
- *
- * Keys are `host:agent:version` ({@link authCacheKey}); we match on the `host:`
- * prefix so agent/version segments can never be mistaken for a host.
- */
 export declare function summarizeHostAuth(cache: Record<string, AuthHealth>, host: string): HostAuthSummary;
-/** Human "3m ago" style age for a checkedAt timestamp. */
 export declare function formatCheckedAge(checkedAt: number, now?: number): string;
-/**
- * Human account label for display (email, else id). NOT used in the cache key —
- * two installs on one host can hold the same account with independently valid
- * tokens, so the key is keyed by version (below), not account.
- */
 export declare function authAccountLabel(info: Pick<AccountInfo, 'email' | 'accountId' | 'userId'> | null | undefined): string | undefined;
-/** Cache key: one entry per install — (host, agent, version). Unique per token. */
 export declare function authCacheKey(host: string, agent: AgentId | string, version: string): string;
-/**
- * Host-independent identity of one probe target — the (agent, version) pair
- * {@link authCacheKey} is keyed by. The separator cannot appear in either half,
- * so an agent id can never run into a version the way a `:` join allows.
- */
 export declare function authTargetKey(agent: AgentId | string, version: string): string;
-/**
- * The `version` slot an account SLOT occupies in the auth cache and the probe
- * rows: `slot:<accountId>`. A slot is a HOME-shaped dir, not an installed
- * version, so it needs its own key or its verdict would collide with (or be
- * silently dropped in favor of) whichever version home the account's label
- * happened to match.
- */
 export declare function slotAuthVersionKey(accountId: string): string;
-/** One account slot on this device that the auth probe must cover. */
 interface SlotAuthInstall extends FleetAuthInstall {
     home: string;
     accountId: string;
 }
-/**
- * Every registered account's slot on this device (PHNX-3940 T1), as probe
- * targets. Before this the probe walked `listInstalledVersions` only, so a
- * slot's verdict was never re-derived after `accounts add/login` wrote it —
- * a slot re-materialized as `unconfigured` while the device doc was unreadable
- * stayed MISSING forever even though its login was live. A slot whose dir is
- * gone is skipped: there is nothing to probe and the row would only say so.
- */
 export declare function enumerateSlotInstalls(meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, agentIds: readonly AgentId[]): SlotAuthInstall[];
-/**
- * {@link authTargetKey} for every local probe target — what a cached row must
- * match to still be about this device. A row outside it is an ORPHAN: its home
- * was uninstalled, so nothing will ever re-probe it and its `checkedAt` is
- * frozen at whatever the last probe left (PHNX-4051).
- */
 export declare function localAuthTargetKeys(agentIds?: readonly AgentId[]): Set<string>;
-/** Read the whole cache (best-effort; a corrupt/missing file yields an empty map). */
 export declare function readAuthHealthCache(): Record<string, AuthHealth>;
-/** Read one entry, or null. */
 export declare function readAuthHealth(host: string, agent: AgentId | string, version: string): AuthHealth | null;
-/** Reconstruct one host's published probe rows for a lease waiter/CLI reader. */
 export declare function readFleetAuthRows(host: string): AuthProbeRow[];
-/**
- * Merge entries into the cache. An incoming `error` verdict (a network blip,
- * not a server rejection) is indeterminate, so it must NOT clobber a prior
- * known verdict — otherwise one 8s timeout flips a `live` chip to `error`,
- * exactly the "cry wolf" the verdict model avoids for `expired`. This is the
- * behaviour promised by the `error` doc on AuthVerdict ("keep the last known
- * one"). A probe-throttled 429 (detail `probe throttled (HTTP 429)`) keeps the
- * previous real verdict when one exists within {@link AUTH_PROBE_MAX_AGE_MS},
- * otherwise becomes `unverified` (PHNX-4051). Pure, so it's unit-tested directly. */
 export declare function mergeAuthHealthEntries(current: Record<string, AuthHealth>, incoming: Record<string, AuthHealth>): Record<string, AuthHealth>;
-/**
- * Merge one or more entries into the cache (best-effort write).
- *
- * `drop` removes entries the writer knows are gone — it runs on the PRE-merge
- * cache, so an incoming row always wins over a drop of the same key and the two
- * can never fight. Only a writer that knows the full truth for the keys it drops
- * may pass one (see {@link writeFleetAuthRows}).
- */
 export declare function writeAuthHealthEntries(entries: Record<string, AuthHealth>, drop?: (key: string) => boolean): void;
 /**
  * Complete a live auth probe for one (agent, home). For claude/kimi/droid this
@@ -232,16 +78,9 @@ export declare function writeAuthHealthEntries(entries: Record<string, AuthHealt
 export declare function probeAuthHealth(agent: AgentId, home: string | undefined, opts?: {
     cliVersion?: string | null;
     info?: AccountInfo | null;
-    /**
-     * Skip the derived-from-usage shortcut and fire a real network probe
-     * (RUSH-3036). Set by `agents devices ping [--strict]`, whose contract is
-     * a genuinely live request that surfaces `revoked` immediately.
-     */
     forceLive?: boolean;
-    /** Daemon tick deadline signal, combined with each probe fetch's own timeout (PHNX-3608). */
     signal?: AbortSignal;
 }): Promise<AuthHealth>;
-/** One probed install on a host. */
 export interface AuthProbeRow {
     agent: AgentId;
     version: string;
@@ -249,72 +88,28 @@ export interface AuthProbeRow {
     accountId?: string;
     health: AuthHealth;
 }
-/** One installed (agent, version) home, tagged with its resolved account label. */
 export interface FleetAuthInstall {
     agent: AgentId;
     version: string;
-    /** Human account label from {@link authAccountLabel}, or undefined when none resolves. */
     account: string | undefined;
-    /** Stable account id when known (slot or resolved via registry) — preferred dedup key. */
     accountId?: string | undefined;
 }
-/**
- * A set of installs that share one provider account and MUST be probed once.
- * The live probe runs against `probe` (the representative home); every entry in
- * `members` — the representative included — then receives that one verdict.
- */
 interface FleetAuthProbeGroup<T extends FleetAuthInstall> {
     probe: T;
     members: T[];
 }
 export declare function groupFleetAuthInstalls<T extends FleetAuthInstall>(installs: readonly T[], isMergeable?: (install: T) => boolean): FleetAuthProbeGroup<T>[];
-/**
- * Enumerate every installed (agent, version) on THIS host and return one row per
- * install (installs with no credential at all are dropped). Shared by
- * `agents fleet ping --local` and the daemon refresh.
- *
- * The live network probe is deduped by account: homes sharing one provider
- * account are probed ONCE and the verdict is fanned out to each home's row, so
- * the daemon's every-3-minute refresh can no longer fire concurrent same-account
- * requests and self-inflict a 429 (RUSH-2111). Each home still gets its own cache
- * row (the cache key is per-version by design — see {@link authCacheKey}).
- */
 export declare function probeLocalFleetAuth(opts?: {
     cliVersion?: string | null;
     agents?: readonly AgentId[];
-    /** Fire real network probes even when fresh usage evidence exists (RUSH-3036) — the `devices ping [--strict]` contract. */
     forceLive?: boolean;
-    /**
-     * Deadline signal from the daemon's supervised auth tick (PHNX-3608). Aborts
-     * the probe's in-flight network work when the tick deadline elapses so it
-     * unwinds instead of leaking a runaway await; on-demand CLI callers omit it.
-     */
     signal?: AbortSignal;
 }): Promise<AuthProbeRow[]>;
-/**
- * Persist a host's probed rows into the cache (keyed by host+agent+version).
- *
- * `installed` — the {@link authTargetKey} set of homes that still exist on
- * `host` ({@link localAuthTargetKeys}) — prunes this host's ORPHAN entries: rows
- * for a version that has since been uninstalled. Nothing re-probes those, so
- * they never age out on their own; they froze the reuse window permanently false
- * and kept surfacing in `agents view` / fleet status (PHNX-4051). Only a caller
- * that enumerated `host`'s real installs may pass it — the `fleet ping` fan-out
- * writes a PEER's rows and cannot enumerate that box's homes, so it omits it and
- * merges as before.
- */
 export declare function writeFleetAuthRows(host: string, rows: AuthProbeRow[], installed?: ReadonlySet<string>): void;
-/**
- * The installed-version label a run outcome falls back to when the account has no
- * slot on this box: the explicit `version`, else the label derived from `home` (a
- * version home is `<versionDir>/home`, so the label is its parent dir's basename).
- * Null when neither resolves. Pure (no fs) so it is unit-tested directly.
- */
 export declare function runOutcomeVersionKey(opts: {
     version?: string | null;
     home?: string | null;
 }): string | null;
-/** A real agent-run outcome — the evidence behind `last used ok` / `last auth failure`. */
 export type RunAuthOutcome = {
     ok: true;
 } | {
@@ -323,13 +118,6 @@ export type RunAuthOutcome = {
     detail?: string;
     resetsAt?: number | null;
 };
-/**
- * Record a REAL run's auth outcome into the auth-health cache with
- * `source: 'run'`. Best-effort and never throws: an unattributable run (no
- * accountId/version/home) writes nothing, and the underlying write already
- * swallows IO errors. Keyed exactly as the catalog reads, so the recorded fact
- * surfaces on the same account row.
- */
 export declare function recordRunAuthOutcome(opts: {
     agent: AgentId | string;
     accountId?: string | null;
@@ -340,7 +128,6 @@ export declare function recordRunAuthOutcome(opts: {
     host?: string;
     now?: number;
 }): void;
-/** `Sep 20 14:02` — the fact timestamp for an auth failure. */
 export declare function factTimestamp(ms: number): string;
 /**
  * The auth FACT `agents view` / `agents accounts` render per account per box