@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,4 +1,3 @@
-/** Stdin grew past {@link REMOTE_STDOUT_MAX_BYTES}; the payload was refused unread. */
 export declare class UsageIngestInputTooLargeError extends Error {
     readonly limitBytes: number;
     constructor(limitBytes: number);

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

@@ -1,41 +1,7 @@
-/**
- * The `agents __usage-ingest` receiver — the worker side of the usage exchange
- * (PHNX-3392 usage-sync, PHNX-4116 transport over SSH).
- *
- * 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.
- *
- * 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.
- *
- * 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';
 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) {
@@ -44,12 +10,6 @@ export class UsageIngestInputTooLargeError extends Error {
         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();
@@ -77,7 +37,6 @@ function readStdin(limitBytes = REMOTE_STDOUT_MAX_BYTES) {
         } });
     });
 }
-/** `--from <path>` reads the payload from a file instead of stdin (Windows path). */
 function fromFileArg(argv) {
     const i = argv.indexOf('--from');
     return i !== -1 && argv[i + 1] ? argv[i + 1] : null;
@@ -125,9 +84,6 @@ export async function runUsageIngest(argv = process.argv.slice(3)) {
                 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}`);

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

@@ -25,30 +25,15 @@ 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 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 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 `__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;
@@ -67,7 +52,6 @@ interface PublishUsageSnapshotResult {
     error: string | null;
     path: string | null;
 }
-/** 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;
@@ -80,44 +64,20 @@ export interface PublishOwnFleetStateResult {
         status: string;
         error: string | null;
     };
-    /** Every publisher failure, as `<field>: <message>` — logged by the caller, never fatal. */
     errors: string[];
 }
-/**
- * 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 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;
@@ -127,21 +87,11 @@ interface ApplyPeerStateOptions {
 }
 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[];
@@ -155,24 +105,14 @@ interface ExchangeOptions {
 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;
     outcomes: PeerExchangeOutcome[];
 }
-/**
- * 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 exchangeFleetStateWithPeers(options?: ExchangeOptions): Promise<ExchangeResult>;
 export {};

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

@@ -25,13 +25,9 @@ import { FLEET_SHARED_STATE_VERSION, parseFleetSharedDeviceStateEnvelope, readFl
 import { getUserAgentsDir } from '../state.js';
 import { machineId, normalizeHost } from '../session/sync/config.js';
 import { exportClaudeUsageCacheRows, ingestPeerClaudeUsageRows, } from './usage.js';
-/** Cadence of the usage-sync tick — the trust window for a `sync` snapshot. */
 export const USAGE_SYNC_INTERVAL_MS = 15 * 60_000;
-/** Re-publish an unchanged windowed row at least this often so workers' 15-min trust does not lapse. */
 export const USAGE_PUBLISH_HEARTBEAT_MS = 10 * 60_000;
-/** Per-peer SSH budget for one exchange; a peer past it is skipped this tick. */
 export const USAGE_EXCHANGE_PEER_TIMEOUT_MS = 20_000;
-/** Marks the start of the JSON reply on the peer's stdout, so login-shell noise before it is ignored. */
 export const FLEET_STATE_REPLY_MARKER = '@@AGENTS_FLEET_STATE@@';
 function usageMeterSignature(row) {
     return JSON.stringify({
@@ -42,11 +38,6 @@ function usageMeterSignature(row) {
         pollerDevice: row.pollerDevice ?? null,
     });
 }
-/**
- * Keep the previously published `capturedAt` when meters have not moved and
- * the last publish is still inside the heartbeat. Stops statusline re-renders
- * from rewriting the own-state file every few seconds.
- */
 export function mergeUsageRowsForPublish(previous, next, nowMs = Date.now()) {
     if (!previous)
         return next;
@@ -64,7 +55,6 @@ export function mergeUsageRowsForPublish(previous, next, nowMs = Date.now()) {
     }
     return out;
 }
-/** Publish this headed device's stable usage snapshot into its own state file. */
 export async function publishUsageSnapshotToSharedStore(options = {}) {
     const result = {
         published: false,
@@ -100,15 +90,7 @@ export async function publishUsageSnapshotToSharedStore(options = {}) {
     }
     return result;
 }
-/**
- * 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).
- */
+// Peer exchange carries usage, auth verdict, and session digests only; credentials never cross device roles.
 export async function publishOwnFleetState(options = {}) {
     const errors = [];
     const usage = await publishUsageSnapshotToSharedStore(options);
@@ -138,7 +120,7 @@ export async function publishOwnFleetState(options = {}) {
         errors.push(`auth: ${auth.error}`);
     return { usage, mirror, auth, errors };
 }
-/** This device's exchange envelope, from its own state file (or usage-only from the cache). */
+// Workers never initiate or poll OAuth usage; only headed peers publish the usage rows they own.
 export function buildFleetStatePayload(options = {}) {
     const device = options.device ?? machineId();
     if (options.usageOnly) {
@@ -153,16 +135,9 @@ export function buildFleetStatePayload(options = {}) {
     const state = readOwnFleetSharedDeviceState(device, options.userAgentsDir);
     return { v: 2, state, ...(options.errors?.length ? { errors: options.errors } : {}) };
 }
-/** Serialize the reply as the peer prints it: marker line, then one JSON line. */
 export function formatFleetStateReply(payload) {
     return `${FLEET_STATE_REPLY_MARKER}\n${JSON.stringify(payload)}\n`;
 }
-/**
- * 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 function parseFleetStateExchangeInput(raw) {
     let parsed;
     try {
@@ -182,7 +157,6 @@ export function parseFleetStateExchangeInput(raw) {
     }
     if (record.v === 1) {
         const rows = record.rows;
-        // `typeof [] === 'object'` — an array is NOT a rows map.
         if (typeof rows !== 'object' || rows === null || Array.isArray(rows)) {
             throw new Error('unrecognized usage-sync payload shape');
         }
@@ -190,7 +164,6 @@ export function parseFleetStateExchangeInput(raw) {
     }
     throw new Error('unrecognized usage-sync payload shape');
 }
-/** Extract the reply envelope from a peer's stdout (text before the marker is login-shell noise). */
 export function parseFleetStateReply(stdout) {
     const idx = stdout.lastIndexOf(FLEET_STATE_REPLY_MARKER);
     if (idx === -1) {
@@ -204,11 +177,6 @@ export function parseFleetStateReply(stdout) {
         throw new Error('reply is not a v2 exchange envelope');
     return payload;
 }
-/**
- * Rows as the receiver stores them: provenance `sync` (so the trust window is
- * `USAGE_SYNC_TRUST_MS`, not the local-capture bar) and the poller pinned to the
- * device that actually read the endpoint, defaulting to the sender.
- */
 function stampSyncRows(rows, sender) {
     const out = {};
     for (const [identity, incoming] of Object.entries(rows)) {
@@ -218,13 +186,7 @@ function stampSyncRows(rows, sender) {
     }
     return out;
 }
-/**
- * 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.
- */
+// Peer state is newest-wins and can never overwrite this device's own publisher file.
 export async function applyPeerFleetState(state, options = {}) {
     const self = normalizeHost(options.device ?? machineId());
     if (normalizeHost(state.device) === self) {
@@ -237,11 +199,8 @@ export async function applyPeerFleetState(state, options = {}) {
         : 0;
     return { path: write.path, merged, receivedAt };
 }
-/** The remote command one exchange runs on a peer, in the peer's shell dialect. */
 export async function buildFleetStateExchangeCommand(os) {
     const { buildRemoteAgentsInvocation, buildWindowsStdinAgentsCommand, remoteShellFor } = await import('../hosts/remote-cmd.js');
-    // The Windows `agents.ps1` shim does not forward ssh-piped stdin, so the
-    // payload goes through a temp file and `--from <path>` there.
     return remoteShellFor(os) === 'powershell'
         ? buildWindowsStdinAgentsCommand(['__usage-ingest', '--reply'])
         : buildRemoteAgentsInvocation(['__usage-ingest', '--reply'], undefined, os);
@@ -261,13 +220,7 @@ async function defaultPeers(self) {
         .filter((d) => normalizeHost(d.name) !== self && isDialableDevice(d))
         .sort((a, b) => a.name.localeCompare(b.name));
 }
-/**
- * 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.
- */
+// Bound peers independently so one slow device cannot stall the rest of the exchange.
 export async function exchangeFleetStateWithPeers(options = {}) {
     const device = options.device ?? machineId();
     const self = normalizeHost(device);