@phnx-labs/agents-cli 1.22.117 → 1.22.119

package/dist/lib/accounting/usage-ingest.js

@@ -1,35 +1,80 @@
 /**
- * The `agents __usage-ingest` receiver (PHNX-3392 usage-sync).
+ * The `agents __usage-ingest` receiver — the worker side of the usage exchange
+ * (PHNX-3392 usage-sync, PHNX-4116 transport over SSH).
  *
- * A legacy headed peer may pipe a {@link UsageSyncPayload} JSON envelope to our
- * stdin; we merge its identity-keyed rows into the local usage cache newest-wins
- * ({@link ingestPeerClaudeUsageRows}). Hidden internal verb — intercepted in
- * index.ts before bootstrap, so it never triggers an update check or a detached
- * sync, and it writes NOTHING to stdout (the caller only reads the exit code).
+ * A headed peer pipes its daemon-state envelope ({@link FleetStateExchangePayload},
+ * v2) to our stdin. We store it as that peer's `devices/<peer>/daemon-state.json`
+ * (stamped `receivedAt`) and merge its usage rows into the local cache
+ * newest-wins ({@link applyPeerFleetState}). With `--reply` we then refresh our
+ * own fields (session digests, reserved-auth verdict, and usage if this box is
+ * headed) and print our own envelope to stdout after a marker line, so the
+ * headed box holds this device's state without a second round-trip. Without
+ * `--reply` nothing is written to stdout: the ready probe runs this verb ahead
+ * of `agents --version`/`agents view --json` in one shell and parses that
+ * stdout, so a silent ingest is what keeps the probe parseable.
  *
- * Exit codes: 0 = merged (or nothing to merge — an empty payload is not an error),
- * 2 = malformed input. It fails loud on a bad envelope rather than silently
- * accepting a wrong shape, but a busy cache lock degrades to best-effort inside
- * `ingestPeerClaudeUsageRows` like every other cache writer.
+ * The legacy v1 envelope (`{v:1, rows}`) from an older headed peer is still
+ * merged. Hidden internal verb — intercepted in index.ts before bootstrap, so
+ * it never triggers an update check or a detached sync.
  *
- * New daemon ticks use the fleet-shared store instead. This compatibility
- * receiver remains for older installed versions. The payload arrives on stdin,
- * EXCEPT on a Windows receiver: the `agents.ps1`
- * shim does not forward ssh-piped stdin to the node process, so the pusher writes
- * the payload to a temp file and passes `agents __usage-ingest --from <path>`
- * (the same workaround the secrets push uses — `buildWindowsStdinImportCommand`).
+ * Exit codes: 0 = applied (or nothing to apply — an empty payload is not an
+ * error), 2 = malformed or oversized input. It fails loud on a bad envelope
+ * rather than silently accepting a wrong shape, but a busy cache lock degrades
+ * to best-effort inside `ingestPeerClaudeUsageRows` like every other cache
+ * writer. Stdin is bounded at {@link REMOTE_STDOUT_MAX_BYTES} — the same ceiling
+ * the dialer puts on a peer's reply — so a runaway pusher cannot grow this
+ * every-15-min receiver's heap; an overflow stops the read, exits 2, and writes
+ * nothing.
+ *
+ * The payload arrives on stdin, EXCEPT on a Windows receiver: the `agents.ps1`
+ * shim does not forward ssh-piped stdin to the node process, so the pusher
+ * writes the payload to a temp file and passes `--from <path>`
+ * (`buildWindowsStdinAgentsCommand`).
  */
 import * as fs from 'fs';
+import { REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator } from '../ssh-exec.js';
 import { ingestPeerClaudeUsageRows } from './usage.js';
-function readStdin() {
-    return new Promise((resolve) => {
-        let buf = '';
-        process.stdin.setEncoding('utf-8');
+import { applyPeerFleetState, buildFleetStatePayload, formatFleetStateReply, parseFleetStateExchangeInput, publishOwnFleetState, } from './usage-sync.js';
+/** Stdin grew past {@link REMOTE_STDOUT_MAX_BYTES}; the payload was refused unread. */
+export class UsageIngestInputTooLargeError extends Error {
+    limitBytes;
+    constructor(limitBytes) {
+        super(`stdin payload exceeds ${limitBytes} bytes (${limitBytes / (1024 * 1024)} MiB); refusing it unread`);
+        this.limitBytes = limitBytes;
+        this.name = 'UsageIngestInputTooLargeError';
+    }
+}
+/**
+ * Read stdin to EOF, bounded at {@link REMOTE_STDOUT_MAX_BYTES}. On overflow the
+ * stream is destroyed so the pusher gets EPIPE instead of a full drain, and the
+ * promise rejects with {@link UsageIngestInputTooLargeError} — the caller exits
+ * 2 without parsing or writing anything.
+ */
+function readStdin(limitBytes = REMOTE_STDOUT_MAX_BYTES) {
+    return new Promise((resolve, reject) => {
+        const acc = new RemoteUtf8Accumulator();
+        let bytes = 0;
+        let settled = false;
         process.stdin.on('data', (chunk) => {
-            buf += chunk;
+            if (settled)
+                return;
+            bytes += chunk.byteLength;
+            if (bytes > limitBytes) {
+                settled = true;
+                process.stdin.destroy();
+                reject(new UsageIngestInputTooLargeError(limitBytes));
+                return;
+            }
+            acc.write(chunk);
         });
-        process.stdin.on('end', () => resolve(buf));
-        process.stdin.on('error', () => resolve(buf));
+        process.stdin.on('end', () => { if (!settled) {
+            settled = true;
+            resolve(acc.end());
+        } });
+        process.stdin.on('error', () => { if (!settled) {
+            settled = true;
+            resolve(acc.end());
+        } });
     });
 }
 /** `--from <path>` reads the payload from a file instead of stdin (Windows path). */
@@ -37,8 +82,9 @@ function fromFileArg(argv) {
     const i = argv.indexOf('--from');
     return i !== -1 && argv[i + 1] ? argv[i + 1] : null;
 }
-export async function runUsageIngest() {
-    const fromPath = fromFileArg(process.argv.slice(3));
+export async function runUsageIngest(argv = process.argv.slice(3)) {
+    const reply = argv.includes('--reply');
+    const fromPath = fromFileArg(argv);
     let source;
     if (fromPath) {
         try {
@@ -50,28 +96,52 @@ export async function runUsageIngest() {
         }
     }
     else {
-        source = await readStdin();
+        try {
+            source = await readStdin();
+        }
+        catch (err) {
+            if (!(err instanceof UsageIngestInputTooLargeError))
+                throw err;
+            process.stderr.write(`[agents] __usage-ingest: ${err.name}: ${err.message}\n`);
+            return 2;
+        }
     }
     const raw = source.trim();
-    if (!raw)
-        return 0; // nothing piped — a no-op tick, not a failure.
-    let payload;
-    try {
-        payload = JSON.parse(raw);
-    }
-    catch {
-        process.stderr.write('[agents] __usage-ingest: malformed JSON payload\n');
-        return 2;
-    }
-    if (!payload ||
-        payload.v !== 1 ||
-        typeof payload.rows !== 'object' ||
-        payload.rows === null ||
-        Array.isArray(payload.rows) // `typeof [] === 'object'` — an array is NOT a rows map
-    ) {
-        process.stderr.write('[agents] __usage-ingest: unrecognized usage-sync payload shape\n');
-        return 2;
+    const errors = [];
+    if (raw) {
+        let payload;
+        try {
+            payload = parseFleetStateExchangeInput(raw);
+        }
+        catch (err) {
+            process.stderr.write(`[agents] __usage-ingest: ${err.message}\n`);
+            return 2;
+        }
+        if (payload.v === 1) {
+            await ingestPeerClaudeUsageRows(payload.rows);
+        }
+        else {
+            try {
+                await applyPeerFleetState(payload.state);
+            }
+            catch (err) {
+                // A well-formed envelope we refuse (it names this device) is the
+                // sender's mistake, not malformed input: say so on stderr and in the
+                // reply, and still answer so the sender learns what this box holds.
+                const message = err.message;
+                process.stderr.write(`[agents] __usage-ingest: ${message}\n`);
+                errors.push(`ingest: ${message}`);
+                if (!reply)
+                    return 2;
+            }
+        }
     }
-    ingestPeerClaudeUsageRows(payload.rows);
+    if (!reply)
+        return 0;
+    const published = await publishOwnFleetState();
+    errors.push(...published.errors);
+    for (const message of published.errors)
+        process.stderr.write(`[agents] __usage-ingest: ${message}\n`);
+    process.stdout.write(formatFleetStateReply(buildFleetStatePayload({ errors })));
     return 0;
 }

package/dist/lib/accounting/usage-sync.d.ts

@@ -1,29 +1,59 @@
 /**
- * Fleet distribution of identity-keyed Claude usage through the user repo.
+ * Fleet distribution of identity-keyed Claude usage over SSH (PHNX-4116).
  *
- * A headed device can read authoritative usage; a worker's setup-token cannot.
- * Headed daemons therefore publish one snapshot into their conflict-free
- * `~/.agents/devices/<device>/daemon-state.json`. The daemon's bounded Git
- * transport delivers those files automatically; workers merge newest-wins.
- * There is deliberately no device-to-device SSH in this module or its tick.
+ * A headed device can read authoritative usage; a worker's setup-token cannot
+ * (credential-management.md invariant 5: a worker never polls
+ * `/api/oauth/usage`). So the headed daemon's `usage-sync` tick dials every
+ * dialable peer in parallel with `agents __usage-ingest --reply`, sending this
+ * box's own daemon-state envelope on stdin; the peer merges the usage rows into
+ * its cache newest-wins and prints its own envelope back, which the headed box
+ * stores in `~/.agents/devices/<peer>/daemon-state.json` stamped `receivedAt`.
+ * Workers never initiate. A peer that times out is skipped this tick and never
+ * blocks another. Only usage rows, verdicts, and session digests move here —
+ * never a credential (invariant 7: roles never cross).
+ *
+ * This replaced a git exchange over the fleet-synced user repo: every daemon
+ * committed its own file each tick, so the shared store reached 1.1 GiB /
+ * 18,358 commits with 100% of the last 2,000 being `chore(devices): publish
+ * <device> daemon state`, and a worker's clone fell 10k commits behind with
+ * `git fetch timed out` on every tick — a valid setup-token could not be
+ * scheduled because a repo was bloated. Git now carries human-authored
+ * resources only; `devices/<device>/daemon-state.json` is untracked.
  */
 import { type ConfiguredDeviceRole } from '../device-config.js';
+import { type FleetSharedDeviceState } from '../fleet-shared-state.js';
+import type { DeviceProfile } from '../devices/registry.js';
+import type { SshExecResult } from '../ssh-exec.js';
 import { type CachedUsageSnapshot } from './usage.js';
-/** Cadence of the usage-sync git tick — the trust window for a `sync` snapshot. */
+/** Cadence of the usage-sync tick — the trust window for a `sync` snapshot. */
 export declare const USAGE_SYNC_INTERVAL_MS: number;
 /** Re-publish an unchanged windowed row at least this often so workers' 15-min trust does not lapse. */
 export declare const USAGE_PUBLISH_HEARTBEAT_MS: number;
+/** Per-peer SSH budget for one exchange; a peer past it is skipped this tick. */
+export declare const USAGE_EXCHANGE_PEER_TIMEOUT_MS = 20000;
+/** Marks the start of the JSON reply on the peer's stdout, so login-shell noise before it is ignored. */
+export declare const FLEET_STATE_REPLY_MARKER = "@@AGENTS_FLEET_STATE@@";
 /**
  * Keep the previously published `capturedAt` when meters have not moved and
  * the last publish is still inside the heartbeat. Stops statusline re-renders
- * from dirtying the shared store (and taking the git lock) every few seconds.
+ * from rewriting the own-state file every few seconds.
  */
 export declare function mergeUsageRowsForPublish(previous: Record<string, CachedUsageSnapshot> | undefined, next: Record<string, CachedUsageSnapshot>, nowMs?: number): Record<string, CachedUsageSnapshot>;
-/** Legacy hidden ingest/export envelope kept for older fleet CLI compatibility. */
+/** Legacy `__usage-ingest` envelope (v1): bare rows from an older headed peer. */
 export interface UsageSyncPayload {
     v: 1;
     rows: Record<string, CachedUsageSnapshot>;
 }
+/**
+ * The exchange envelope (v2), identical in both directions: a device's own
+ * daemon-state envelope. `errors` carries the replying peer's non-fatal
+ * publisher failures so the headed box can log them against that peer.
+ */
+export interface FleetStateExchangePayload {
+    v: 2;
+    state: FleetSharedDeviceState;
+    errors?: string[];
+}
 interface PublishUsageSnapshotOptions {
     userAgentsDir?: string;
     cachePath?: string;
@@ -37,39 +67,112 @@ interface PublishUsageSnapshotResult {
     error: string | null;
     path: string | null;
 }
-/** Publish this headed device's stable usage snapshot into its owned store file. */
+/** Publish this headed device's stable usage snapshot into its own state file. */
 export declare function publishUsageSnapshotToSharedStore(options?: PublishUsageSnapshotOptions): Promise<PublishUsageSnapshotResult>;
+export interface PublishOwnFleetStateResult {
+    usage: PublishUsageSnapshotResult;
+    mirror: {
+        changed: boolean;
+        count: number;
+        error: string | null;
+    };
+    auth: {
+        status: string;
+        error: string | null;
+    };
+    /** Every publisher failure, as `<field>: <message>` — logged by the caller, never fatal. */
+    errors: string[];
+}
 /**
- * Publish a changed snapshot immediately and exchange the shared repo so
- * workers see it without waiting for the 15-minute tick. No-ops when the
- * serialized store is unchanged (statusline re-renders with the same windows).
+ * Refresh every field this device owns in its own state file: the usage
+ * snapshot (headed only), the session digests, and the reserved-auth readiness
+ * verdict. Run before the envelope is sent (the headed tick) or printed back
+ * (`__usage-ingest --reply`) so a peer always receives current fields. Each
+ * publisher is independent: one failing is reported in `errors` and the others
+ * still land. All three writers are the async, non-blocking variants
+ * (`updateFleetSharedDeviceStateAsync` underneath).
  */
-export declare function pushUsageSnapshotNow(options?: PublishUsageSnapshotOptions & {
-    lockPath?: string;
-    timeoutMs?: number;
-}): Promise<{
-    published: PublishUsageSnapshotResult;
-    transport?: import('../fleet-shared-repo-sync.js').FleetSharedRepoSyncResult;
-}>;
-interface ConsumeUsageSnapshotsOptions {
+export declare function publishOwnFleetState(options?: PublishUsageSnapshotOptions): Promise<PublishOwnFleetStateResult>;
+interface BuildPayloadOptions {
+    device?: string;
     userAgentsDir?: string;
     cachePath?: string;
     role?: ConfiguredDeviceRole;
+    /**
+     * Send only the usage rows (read live from the cache, headed only) — the
+     * placement probe's shape: the dispatcher hands the chosen worker current
+     * numbers without the sessions/auth fields the tick carries.
+     */
+    usageOnly?: boolean;
+    errors?: string[];
+}
+/** This device's exchange envelope, from its own state file (or usage-only from the cache). */
+export declare function buildFleetStatePayload(options?: BuildPayloadOptions): FleetStateExchangePayload;
+/** Serialize the reply as the peer prints it: marker line, then one JSON line. */
+export declare function formatFleetStateReply(payload: FleetStateExchangePayload): string;
+/**
+ * Parse what a peer sent — a v2 exchange envelope, or the legacy v1 bare-rows
+ * envelope from an older headed peer. Throws a clear message on anything else;
+ * the caller decides whether that is exit code 2 (the receiver) or a per-peer
+ * error (the headed tick).
+ */
+export declare function parseFleetStateExchangeInput(raw: string): FleetStateExchangePayload | UsageSyncPayload;
+/** Extract the reply envelope from a peer's stdout (text before the marker is login-shell noise). */
+export declare function parseFleetStateReply(stdout: string): FleetStateExchangePayload;
+interface ApplyPeerStateOptions {
+    userAgentsDir?: string;
+    cachePath?: string;
     device?: string;
-    roles?: Record<string, ConfiguredDeviceRole>;
+    receivedAt?: number;
 }
-interface ConsumeUsageSnapshotsResult {
-    sources: string[];
+export interface ApplyPeerStateResult {
+    path: string;
+    /** Usage rows merged into the local cache (newest-wins per identity). */
     merged: number;
+    receivedAt: number;
+}
+/**
+ * Take a peer's envelope in: store it as that peer's file (stamped `receivedAt`)
+ * and merge its usage rows into this box's cache newest-wins. The same step runs
+ * on both ends — the worker on the pushed envelope, the headed box on the reply.
+ * Both writes take their file lock asynchronously: this runs on the daemon tick
+ * once per peer, and a `sleepSync` lock there freezes every other service.
+ */
+export declare function applyPeerFleetState(state: FleetSharedDeviceState, options?: ApplyPeerStateOptions): Promise<ApplyPeerStateResult>;
+/** The remote command one exchange runs on a peer, in the peer's shell dialect. */
+export declare function buildFleetStateExchangeCommand(os?: string): Promise<string>;
+/** The SSH boundary: run `remoteCmd` on `peer` with `input` on stdin. Injected by tests. */
+export type FleetStateDial = (peer: DeviceProfile, remoteCmd: string, input: string) => Promise<SshExecResult>;
+interface ExchangeOptions {
+    peers?: DeviceProfile[];
+    dial?: FleetStateDial;
+    payload?: FleetStateExchangePayload;
+    device?: string;
+    userAgentsDir?: string;
+    cachePath?: string;
+    timeoutMs?: number;
+}
+export interface PeerExchangeOutcome {
+    device: string;
+    delivered: boolean;
+    /** Set when the peer's reply was stored — PR 5's per-peer freshness input. */
+    receivedAt: number | null;
+    merged: number;
+    /** Why this peer got nothing this tick (timeout, old CLI, mismatched name, …). */
+    error: string | null;
+    /** The peer's own publisher failures, verbatim from its reply. */
+    peerErrors: string[];
+}
+export interface ExchangeResult {
     skipped: string | null;
-    errors: Array<{
-        device: string;
-        message: string;
-    }>;
+    outcomes: PeerExchangeOutcome[];
 }
 /**
- * Read headed publishers from the local user-repo checkout and merge one
- * newest-wins batch into the worker cache. No network or subprocess is touched.
+ * The headed publisher's fan-out: dial every peer in parallel, each under its
+ * own timeout, and apply each reply as it arrives. Never throws for a peer — a
+ * timeout, an old CLI with no `--reply`, or a reply naming the wrong device is
+ * that peer's `error` and the others are unaffected. A non-headed device skips:
+ * workers never initiate (they only answer), so a worker's tick is a no-op here.
  */
-export declare function consumeUsageSnapshotsFromSharedStore(options?: ConsumeUsageSnapshotsOptions): ConsumeUsageSnapshotsResult;
+export declare function exchangeFleetStateWithPeers(options?: ExchangeOptions): Promise<ExchangeResult>;
 export {};