@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/session/remote-preview-cache.js

@@ -1,4 +1,3 @@
-/** Bounded, single-owner preview fetch with a durable requester cache and cross-process coalescing. */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { createHash } from 'node:crypto';
@@ -8,25 +7,13 @@ import { getCacheDir } from '../state.js';
 import { isCompleteSessionId } from './discover.js';
 import { fetchPeerPreviewEnvelope, } from './remote/remote-list.js';
 import { readRemotePreviewCache, writeRemotePreviewCacheFailure, writeRemotePreviewCacheSuccess, withSessionDBTimeout, REMOTE_PREVIEW_ENVELOPE_MAX_BYTES, } from './db.js';
-/** How long a successful fetch is served with zero SSH on an ordinary call. */
 const REMOTE_PREVIEW_FRESH_MS = 45_000;
-/** Exponential backoff after a failed fetch, capped, so a persistently
- * unreachable/erroring peer is not re-dialed on every call. */
 function nextAttemptBackoffMs(consecutiveFailures) {
     const capped = Math.min(consecutiveFailures, 6);
     return Math.min(30_000 * 2 ** (capped - 1), 30 * 60_000);
 }
-/**
- * Overall interactive budget for a call that must actually dial the peer:
- * lease-wait + SSH attempt. A caller that provides its own `timeoutMs` still
- * has this outer ceiling applied, since the lease-wait time is additive to it.
- */
 const REMOTE_PREVIEW_TOTAL_DEADLINE_MS = 10_000;
 const CACHE_BUSY_TIMEOUT_MS = 250;
-/** Default SSH attempt bound for this fast path specifically — tighter than
- * the general-purpose picker's `PEER_PREVIEW_TIMEOUT_MS` (15s), which is
- * tuned for an interactive "peek" the user is already waiting on, not a
- * budget-conscious automated caller. */
 const REMOTE_PREVIEW_SSH_TIMEOUT_MS = 8_000;
 function cacheKey(device, sessionId) {
     return `${device}::${sessionId}`;
@@ -50,8 +37,6 @@ export async function getRemoteSessionPreview(sessionId, device, opts = {}, deps
         return noCacheOutcome(normalizedDevice, 'The session preview cache is unavailable. Try again.');
     }
 }
-/** Cap on a caller-supplied `--revision` value: it's an opaque cursor, never
- * free text, so this is a sanity bound, not a format check. */
 const REVISION_MAX_CHARS = 128;
 function isValidRevision(revision) {
     return revision.length > 0 && revision.length <= REVISION_MAX_CHARS;
@@ -70,18 +55,13 @@ async function fetchOrServe(sessionId, device, opts, deps) {
         try {
             accessCache(() => writeRemotePreviewCacheFailure(device, sessionId, reason, nextAttemptBackoffMs, opts.now ?? Date.now()));
         }
-        catch { /* The response still carries the failure and any previously read content. */ }
+        catch { }
     };
     const revision = opts.revision !== undefined && isValidRevision(opts.revision) ? opts.revision : undefined;
     if (!opts.refresh && cached?.ok && cached.consecutiveFailures === 0) {
         const revisionConfirmedUnchanged = revision !== undefined
             && cached.lastCallerRevision !== undefined
             && revision === cached.lastCallerRevision;
-        // A revision was supplied and there is no prior recorded caller revision,
-        // or it DIFFERS: skip the TTL bypass below (activity-driven invalidation)
-        // and fall through to a real attempt, still subject to backoff. No
-        // revision supplied at all: fall back to the plain TTL freshness window,
-        // unchanged from before `--revision` existed.
         const age = now - cached.fetchedAt;
         const withinFreshWindow = revision === undefined && age >= 0 && age < REMOTE_PREVIEW_FRESH_MS;
         if (revisionConfirmedUnchanged || withinFreshWindow) {
@@ -90,42 +70,24 @@ async function fetchOrServe(sessionId, device, opts, deps) {
         }
     }
     if (!opts.refresh && cached && now < cached.nextAttemptAt) {
-        // Still inside the negative-backoff window from a recent failure: honor
-        // it rather than dialing again, and serve whatever the cache holds.
         const reason = cached.failureReason ?? 'peer unreachable';
         return cached.ok ? staleFromCache(cached, device, reason) : noCacheOutcome(device, reason);
     }
-    // From here on we are actually about to dial the peer. This is the
-    // realistic duplication case (one CLI process per user action, e.g. the
-    // Menu worker shelling out a fresh `agents sessions preview` per click), so
-    // this takes a bounded, OS-visible lease keyed on (device, sessionId) —
-    // never an in-process-only guard, which cannot help two separate processes.
     const beforeFetchedAt = cached?.fetchedAt ?? 0;
     const timeoutMs = opts.timeoutMs ?? REMOTE_PREVIEW_SSH_TIMEOUT_MS;
     const priorConsecutiveFailures = cached?.consecutiveFailures ?? 0;
     const attempt = async (remainingMs) => {
         const afterLease = readCache();
         if (afterLease?.ok && afterLease.consecutiveFailures === 0 && afterLease.fetchedAt > beforeFetchedAt) {
-            // Another process completed a SUCCESSFUL fetch for this exact
-            // (device, id) while we waited for the lease — reuse it. True under
-            // --refresh too: refresh means "current data now", and data fetched a
-            // moment ago while we queued already IS current.
             return freshFromCache(afterLease, device);
         }
         if (!opts.refresh && afterLease && now < afterLease.nextAttemptAt) {
-            // Another process just recorded a FAILURE (and its backoff) while we
-            // waited: honor it rather than firing a second attempt right behind it.
             return afterLease.ok
                 ? staleFromCache(afterLease, device, afterLease.failureReason ?? 'peer unreachable')
                 : noCacheOutcome(device, afterLease.failureReason ?? 'peer unreachable');
         }
         if (opts.refresh && afterLease
             && afterLease.consecutiveFailures > priorConsecutiveFailures) {
-            // Even under --refresh (which otherwise ignores backoff): another
-            // process's OWN refresh attempt just failed while we waited for the
-            // lease. Reuse that failure rather than immediately trying a third
-            // time — "explicit retry" still means at most one attempt per genuinely
-            // concurrent request, not one per caller.
             const reason = afterLease.failureReason ?? 'peer unreachable';
             return afterLease.ok ? staleFromCache(afterLease, device, reason) : noCacheOutcome(device, reason);
         }
@@ -144,10 +106,6 @@ async function fetchOrServe(sessionId, device, opts, deps) {
         }
         const validation = validateEnvelope(result.envelope, sessionId, device);
         if (!validation.ok) {
-            // A peer answered, but the payload doesn't check out (wrong session id,
-            // wrong schema version, malformed shape — a version-skewed or
-            // misbehaving peer). Never cache it under this id/device key, and never
-            // pass it through as if it were a genuine success.
             recordFailure(validation.reason);
             if (cached?.ok)
                 return staleFromCache(cached, device, validation.reason);
@@ -155,11 +113,6 @@ async function fetchOrServe(sessionId, device, opts, deps) {
         }
         const envelopeBytes = Buffer.byteLength(JSON.stringify(result.envelope), 'utf8');
         if (envelopeBytes > REMOTE_PREVIEW_ENVELOPE_MAX_BYTES) {
-            // The live fetch genuinely succeeded, but the payload is too large to
-            // persist AND too large to hand back unbounded. Never silently pass an
-            // oversized blob through as "fresh" — degrade to the last-good stale
-            // copy (explicitly labeled) when one exists, else an explicit bounded
-            // error, and do not cache the oversized response either way.
             const reason = `peer response was ${envelopeBytes} bytes, over the ${REMOTE_PREVIEW_ENVELOPE_MAX_BYTES}-byte bounded-cache limit`;
             recordFailure(reason);
             if (cached?.ok)
@@ -181,10 +134,6 @@ async function fetchOrServe(sessionId, device, opts, deps) {
     };
     try {
         return await withBoundedRemoteLease(device, sessionId, timeoutMs, deadlineAt, attempt, () => {
-            // Could not acquire the lease within the interactive budget (another
-            // process is holding it, presumably mid-fetch, longer than our deadline).
-            // Degrade to whatever the cache holds rather than piling on a second SSH
-            // attempt — bounded wait, no serial redial, no unbounded queueing.
             const current = cached;
             if (current?.ok)
                 return staleFromCache(current, device, 'another request for this session was already in flight');
@@ -196,16 +145,6 @@ async function fetchOrServe(sessionId, device, opts, deps) {
         return cached?.ok ? staleFromCache(cached, device, reason) : noCacheOutcome(device, reason);
     }
 }
-/**
- * Validate a peer's response before it is trusted at all: schema-version 1,
- * a `session` object present, its `id` an EXACT non-empty string match for
- * the id we asked for (never missing/null/numeric/mismatched), and — when the
- * peer names its own machine — that name must agree with the device we
- * actually dialed. Without these checks a version-skewed, misbehaving, or
- * misconfigured peer's response could be cached under the WRONG key (this
- * caller's requested sessionId) or attributed to the wrong owning device,
- * poisoning a later read for a completely different session/device pair.
- */
 function validateEnvelope(envelope, sessionId, device) {
     const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
     const text = (value) => typeof value === 'string' && value.trim().length > 0;
@@ -260,14 +199,10 @@ function validateEnvelope(envelope, sessionId, device) {
         return { ok: false, reason: 'The device has no recorded session details available yet.' };
     return { ok: true };
 }
-/** Cross-process lock target for one (device, sessionId) pair. Deliberately a
- * separate lock namespace from `refresh-coordinator.ts` — different SLA,
- * different consumers, no reason to share contention. */
 function leaseTarget(device, sessionId) {
     const digest = createHash('sha256').update(`${device}::${sessionId}`).digest('hex');
     return path.join(getCacheDir(), 'remote-preview-locks', `${digest}.lock`);
 }
-/** Lock wait, transport, and cache writes share one deadline; no pending retry outlives the call. */
 async function withBoundedRemoteLease(device, sessionId, fetchTimeoutMs, deadlineAt, fn, onDeadline) {
     const target = leaseTarget(device, sessionId);
     await fs.mkdir(path.dirname(target), { recursive: true });
@@ -278,9 +213,6 @@ async function withBoundedRemoteLease(device, sessionId, fetchTimeoutMs, deadlin
         if (error?.code !== 'EEXIST')
             throw error;
     }
-    // Stale slightly above the fetch's own bound: a genuinely dead holder
-    // (crashed mid-fetch) is reclaimed soon after its own attempt would have
-    // timed out anyway; a live holder's lock never goes stale mid-fetch.
     const staleMs = fetchTimeoutMs + 2_000;
     let release;
     while (!release && Date.now() < deadlineAt) {
@@ -301,7 +233,6 @@ async function withBoundedRemoteLease(device, sessionId, fetchTimeoutMs, deadlin
         return onDeadline();
     const remainingMs = deadlineAt - Date.now();
     if (remainingMs <= 0) {
-        // Acquired right at the wire: no budget left to do any real work with it.
         if (release) {
             await release();
             await cleanupLeaseFile(target);
@@ -318,17 +249,11 @@ async function withBoundedRemoteLease(device, sessionId, fetchTimeoutMs, deadlin
         }
     }
 }
-/** Best-effort removal of the lease marker file after release, so the
- * lock directory doesn't grow one file per (device, sessionId) pair this box
- * has ever previewed. Self-healing either way: `withBoundedRemoteLease`
- * recreates it on demand (`{ flag: 'wx' }` — a no-op if it's still there). */
 async function cleanupLeaseFile(target) {
     try {
         await fs.unlink(target);
     }
     catch {
-        // Another concurrent caller may already be using it, or it's already
-        // gone — either way, nothing to do.
     }
 }
 function describeFailure(result) {

package/dist/lib/session/remote.js

@@ -1,3 +1 @@
-// Moved to ./remote/remote.ts (move 4 of the core-module refactor).
-// Kept as a re-export shim so existing importers don't break.
 export * from './remote/remote.js';

package/dist/lib/session/resume-command.d.ts

@@ -1,7 +1 @@
-/**
- * The one public command used by UI and lifecycle consumers to reopen a session.
- * `agents sessions resume` owns identity resolution, source-device routing,
- * version/home selection, and harness-specific continuation; callers must not
- * recreate it.
- */
 export declare function buildCanonicalResumeCommand(sessionId: string): string[];

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

@@ -1,9 +1,3 @@
-/**
- * The one public command used by UI and lifecycle consumers to reopen a session.
- * `agents sessions resume` owns identity resolution, source-device routing,
- * version/home selection, and harness-specific continuation; callers must not
- * recreate it.
- */
 export function buildCanonicalResumeCommand(sessionId) {
     return ['agents', 'sessions', 'resume', sessionId];
 }

package/dist/lib/session/resume-owner.d.ts

@@ -1,55 +1,4 @@
-/**
- * Where a session may be resumed — the one place that answers "does this
- * transcript belong to another machine?" and, when it does, runs the resume
- * THERE instead of here.
- *
- * A session's agent state lives on the box that produced it: the harness keeps
- * its own conversation store under that machine's home, and `machine` on a
- * SessionMeta records where the transcript originated (see session/types.ts).
- * A row can reach this box two ways and BOTH are remote-owned:
- *
- *  - a **synced mirror** — locally readable at `backups/<agent>/<machine>/…`,
- *    which is exactly why the old code could not tell: the transcript file is
- *    right there, so nothing failed until the harness was asked to resume a
- *    conversation it has never seen;
- *  - a **live fan-out row** (`_remote`), whose `filePath` is on the peer's disk.
- *
- * Resuming either one locally starts the harness against state it does not
- * have. Before RUSH-2022 that happened silently — `sessions-resume.ts` even fell
- * back to `process.cwd()` when the recorded cwd did not exist locally, so a
- * remote session resumed in whatever directory the user happened to be in.
- *
- * Callers act on the answer differently, and the difference is deliberate:
- * `agents sessions resume` HOPS to the owner over SSH, while
- * `resumeSessionInPlace` — the local takeover every routed caller reaches only
- * after deciding — REFUSES. The batch `sessions resume` needs no check of its
- * own: each of its tabs runs the canonical `agents sessions resume <id>`
- * (lib/session/resume-command.ts), which routes itself.
- */
-import type { SessionMeta } from './types.js';
-/**
- * Set on the SSH hop that sends a resume to its owning device: the far side must
- * run it, never route again.
- *
- * An env var rather than a flag, deliberately. The fleet is mixed-version — a
- * peer on the released CLI would die on an unknown `--here` with
- * `error: unknown option '--here'`, breaking the very hop this feature adds. An
- * unrecognized exported variable is inert on every version, so routing works
- * against old and new peers alike. The far side deletes it after reading
- * ({@link consumeResumePinned}) so it cannot leak into the agent's own children.
- */
+import type { SessionMeta } from '@phnx-labs/sessions-cli/reader';
 export declare const RESUME_PINNED_ENV = "AGENTS_RESUME_PINNED";
-/**
- * Whether this process was handed a resume by its owner-routing hop — read once,
- * then cleared so a nested `agents sessions resume` inside the running agent still routes
- * normally.
- */
 export declare function consumeResumePinned(): boolean;
-/**
- * The peer that owns `session`'s state, or `undefined` when this machine does.
- *
- * Undefined is also the answer for an untagged row (`machine` unset — a session
- * obtained outside `discoverSessions`): there is nothing to route to, so the
- * caller keeps the local behaviour rather than inventing a target.
- */
 export declare function sessionOwnerDevice(session: Pick<SessionMeta, 'machine'>): string | undefined;

package/dist/lib/session/resume-owner.js

@@ -1,69 +1,13 @@
-/**
- * Where a session may be resumed — the one place that answers "does this
- * transcript belong to another machine?" and, when it does, runs the resume
- * THERE instead of here.
- *
- * A session's agent state lives on the box that produced it: the harness keeps
- * its own conversation store under that machine's home, and `machine` on a
- * SessionMeta records where the transcript originated (see session/types.ts).
- * A row can reach this box two ways and BOTH are remote-owned:
- *
- *  - a **synced mirror** — locally readable at `backups/<agent>/<machine>/…`,
- *    which is exactly why the old code could not tell: the transcript file is
- *    right there, so nothing failed until the harness was asked to resume a
- *    conversation it has never seen;
- *  - a **live fan-out row** (`_remote`), whose `filePath` is on the peer's disk.
- *
- * Resuming either one locally starts the harness against state it does not
- * have. Before RUSH-2022 that happened silently — `sessions-resume.ts` even fell
- * back to `process.cwd()` when the recorded cwd did not exist locally, so a
- * remote session resumed in whatever directory the user happened to be in.
- *
- * Callers act on the answer differently, and the difference is deliberate:
- * `agents sessions resume` HOPS to the owner over SSH, while
- * `resumeSessionInPlace` — the local takeover every routed caller reaches only
- * after deciding — REFUSES. The batch `sessions resume` needs no check of its
- * own: each of its tabs runs the canonical `agents sessions resume <id>`
- * (lib/session/resume-command.ts), which routes itself.
- */
 import { isSelfHost } from '../devices/self-host.js';
-/**
- * Set on the SSH hop that sends a resume to its owning device: the far side must
- * run it, never route again.
- *
- * An env var rather than a flag, deliberately. The fleet is mixed-version — a
- * peer on the released CLI would die on an unknown `--here` with
- * `error: unknown option '--here'`, breaking the very hop this feature adds. An
- * unrecognized exported variable is inert on every version, so routing works
- * against old and new peers alike. The far side deletes it after reading
- * ({@link consumeResumePinned}) so it cannot leak into the agent's own children.
- */
 export const RESUME_PINNED_ENV = 'AGENTS_RESUME_PINNED';
-/**
- * Whether this process was handed a resume by its owner-routing hop — read once,
- * then cleared so a nested `agents sessions resume` inside the running agent still routes
- * normally.
- */
 export function consumeResumePinned() {
     const pinned = process.env[RESUME_PINNED_ENV] === '1';
     delete process.env[RESUME_PINNED_ENV];
     return pinned;
 }
-/**
- * The peer that owns `session`'s state, or `undefined` when this machine does.
- *
- * Undefined is also the answer for an untagged row (`machine` unset — a session
- * obtained outside `discoverSessions`): there is nothing to route to, so the
- * caller keeps the local behaviour rather than inventing a target.
- */
 export function sessionOwnerDevice(session) {
     const owner = session.machine?.trim();
     if (!owner)
         return undefined;
-    // `isSelfHost` matches every identity this box answers to — `machineId()`
-    // itself, the tailnet dnsName and its short form, loopback (devices/
-    // self-host.ts `selfAliases`) — so a mirror tagged with this machine's tailnet
-    // name is local, not a peer (cf. RUSH-2114). No separate `machineId()`
-    // comparison: it is one of those aliases.
     return isSelfHost(owner) ? undefined : owner;
 }

package/dist/lib/session/run-names.d.ts

@@ -1,18 +1,3 @@
-/**
- * Run-name index: the join between a `agents run --name <slug>` handle and the
- * session id of the run it named.
- *
- * `agents run` records `<sessionId>.json` here at launch whenever both a name
- * and a session id are known up front (Claude pre-mints its id — see spawnAgent;
- * a teams teammate's Claude session id is its agent id). The session-discovery
- * pass reads these sidecars and SEEDS the session label by id (via
- * seedLabelsFromNames) — the launch handle becomes the label, refined later by an
- * agent-generated title. Idempotent and re-applied every scan, so seeds survive
- * transcript rescans without being parsed out of the transcript itself.
- *
- * Mirrors the host-task sidecar convention (`~/.agents/.cache/hosts/<id>.json`),
- * one small JSON per run under `~/.agents/.cache/run-names/`.
- */
 interface RunNameRecord {
     sessionId: string;
     name: string;
@@ -21,15 +6,6 @@ interface RunNameRecord {
     ts: number;
 }
 export declare function runNamesDir(): string;
-/**
- * Record a run's `--name` handle keyed by its session id. Best-effort: a failed
- * write must never break the run itself. No-op without both a name and id.
- */
 export declare function recordRunName(rec: Omit<RunNameRecord, 'ts'>): void;
-/**
- * Build the sessionId → name map from every run-name sidecar, for
- * seedLabelsFromNames to apply onto the index as label seeds. Returns an empty
- * map when the dir doesn't exist yet.
- */
 export declare function buildRunNameMap(): Map<string, string | null>;
 export {};

package/dist/lib/session/run-names.js

@@ -1,18 +1,3 @@
-/**
- * Run-name index: the join between a `agents run --name <slug>` handle and the
- * session id of the run it named.
- *
- * `agents run` records `<sessionId>.json` here at launch whenever both a name
- * and a session id are known up front (Claude pre-mints its id — see spawnAgent;
- * a teams teammate's Claude session id is its agent id). The session-discovery
- * pass reads these sidecars and SEEDS the session label by id (via
- * seedLabelsFromNames) — the launch handle becomes the label, refined later by an
- * agent-generated title. Idempotent and re-applied every scan, so seeds survive
- * transcript rescans without being parsed out of the transcript itself.
- *
- * Mirrors the host-task sidecar convention (`~/.agents/.cache/hosts/<id>.json`),
- * one small JSON per run under `~/.agents/.cache/run-names/`.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from '../state.js';
@@ -22,10 +7,6 @@ export function runNamesDir() {
 function recordFile(sessionId) {
     return path.join(runNamesDir(), `${sessionId}.json`);
 }
-/**
- * Record a run's `--name` handle keyed by its session id. Best-effort: a failed
- * write must never break the run itself. No-op without both a name and id.
- */
 export function recordRunName(rec) {
     if (!rec.sessionId || !rec.name)
         return;
@@ -34,14 +15,8 @@ export function recordRunName(rec) {
         fs.writeFileSync(recordFile(rec.sessionId), JSON.stringify({ ...rec, ts: Date.now() }, null, 2));
     }
     catch {
-        /* the run is already launching; the name is a convenience, not load-bearing */
     }
 }
-/**
- * Build the sessionId → name map from every run-name sidecar, for
- * seedLabelsFromNames to apply onto the index as label seeds. Returns an empty
- * map when the dir doesn't exist yet.
- */
 export function buildRunNameMap() {
     const map = new Map();
     let files;
@@ -58,7 +33,6 @@ export function buildRunNameMap() {
                 map.set(rec.sessionId, rec.name);
         }
         catch {
-            /* skip a corrupt sidecar */
         }
     }
     return map;