@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,57 +1,23 @@
-/**
- * Daemon-warmed cross-surface cache for live session status (RUSH-2062).
- *
- * Problem: menubar / Factory / watchdog / CLI each independently run a full
- * `sessions --active` gather (~9s wall / ~170MB) with no sharing. Measured on
- * zion: back-to-back runs were 9.22s then 8.16s — no speedup, full SSH fan-out
- * every call.
- *
- * Pattern mirrors {@link ../devices/stats-cache.ts} / {@link ../fleet-status.ts}:
- *
- * - **Daemon publish:** each daemon publishes THIS host's local active sessions
- *   (`publishLocalActiveSessions`). Each write appends row deltas to the journal
- *   consumed by long-lived watchers. Publish-own only — no
- *   cross-host SSH from the daemon (avoids the N² fan-out of RUSH-2061).
- * - **Readers** (`loadLocalActiveSessions`, fleet path in `gatherActiveSessions`)
- *   serve the warm snapshot when it is within {@link DEFAULT_ACTIVE_CACHE_MAX_AGE_MS};
- *   `forceRefresh` / age expiry re-gathers live.
- * - **Immutable memo:** per-session fields that only change when the transcript
- *   does (topic, label, cwd, …) are keyed on `(sessionId, transcriptMtimeMs)`.
- *   Live status fields (`status`, `activity`, `preview`, `pidAlive`, …) are
- *   NEVER stored in that memo — they only ride the short-lived snapshot.
- *
- * Best-effort disk IO: a missing/corrupt cache never throws; the caller falls
- * through to a live gather.
- */
 import * as fs from 'fs';
 import { writerProcessView, requireWriterProcessView } from './process-view.js';
 import * as path from 'path';
 import { createMemoryCache } from '../memory-cache.js';
 import { getCacheDir } from '../state.js';
 import { backfillActiveRowsFromIndex, foldRecap, sessionProcessIsLocal } from './active.js';
+import { enrichGlanceFiles } from './glance-files.js';
 import { readSessionSummaryAny, readSessionTimelineAny } from './db.js';
 import { isSummarizerReady } from '../summarizer/config.js';
-/** Snapshot file under `getCacheDir()` (regenerable, gitignored). */
 const SNAPSHOT_FILE = '.active-sessions.json';
-/** Immutable-field memo file (keyed by sessionId + transcript mtime). */
 const IMMUTABLE_FILE = '.active-session-immutable.json';
 const JOURNAL_FILE = '.active-sessions.journal.jsonl';
-/**
- * How long a snapshot may be served before a reader re-gathers.
- * Short on purpose: live status (running/idle/waiting) must not go stale.
- * One-shot readers may re-gather after this ceiling. Long-lived watchers never
- * do: they read one reset then tail the canonical writer journal.
- */
 export const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS = 15_000;
 export function activeSessionJournalIdentity(row) {
     return row.sessionId ?? `${row.context}:${row.kind}:${row.pid ?? ''}:${row.startedAtMs ?? ''}`;
 }
-/** Process-local L1. The atomic snapshot remains the cross-process source. */
 const activeSnapshotMemory = createMemoryCache({
     max: 2,
     ttlMs: DEFAULT_ACTIVE_CACHE_MAX_AGE_MS,
 });
-/** Keys stored in the immutable memo (transcript-stable). */
 export const IMMUTABLE_FIELD_KEYS = [
     'topic',
     'firstUserMessage',
@@ -73,15 +39,15 @@ export const IMMUTABLE_FIELD_KEYS = [
     'kind',
     'context',
 ];
-/**
- * Live / volatile fields that MUST NOT be served from the immutable memo.
- * They either change without a transcript write (pid death, attach state) or
- * are short-window signals (preview, tok/s). The short snapshot TTL is the
- * only cache that may carry them — and only as a whole-row snapshot.
- */
+// Immutable transcript-mtime memoization must never absorb volatile status, activity, or preview truth.
 export const LIVE_STATUS_KEYS = [
     'status',
     'activity',
+    'model',
+    'failures',
+    'activityHistogram',
+    'userTurns',
+    'subagents',
     'preview',
     'tokPerSec',
     'awaitingReason',
@@ -99,39 +65,25 @@ export const LIVE_STATUS_KEYS = [
     'rateLimited',
     'plan',
 ];
-/**
- * How long after the last reader heartbeat the daemon considers the journal
- * to have no active consumer and skips the expensive `ps`+`lsof` gather.
- *
- * Must be significantly larger than {@link SESSION_WATCH_HEARTBEAT_MS} (15s)
- * so a single delayed heartbeat does not cause a false-idle. Three tick-lengths
- * gives adequate margin while still cutting load within ~45s of the last
- * watcher disconnecting.
- */
 export const ACTIVE_SESSIONS_READER_IDLE_WINDOW_MS = 45_000;
-// ── path overrides (test seam) ─────────────────────────────────────────────
 let snapshotPathOverride = null;
 let immutablePathOverride = null;
 let journalPathOverride = null;
 let readerPresencePathOverride = null;
-/** Test seam: redirect the snapshot file. Returns the previous override. */
 export function setActiveSessionsSnapshotPathForTest(p) {
     const prev = snapshotPathOverride;
     snapshotPathOverride = p;
     activeSnapshotMemory.clear();
     return prev;
 }
-/** Test seam: isolate process-local entries between fixtures. */
 export function clearActiveSnapshotMemoryForTest() {
     activeSnapshotMemory.clear();
 }
-/** Test seam: redirect the immutable-memo file. Returns the previous override. */
 export function setImmutableMemoPathForTest(p) {
     const prev = immutablePathOverride;
     immutablePathOverride = p;
     return prev;
 }
-/** Test seam: redirect the reader-presence file. Returns the previous override. */
 export function setActiveSessionsReaderPresencePathForTest(p) {
     const prev = readerPresencePathOverride;
     readerPresencePathOverride = p;
@@ -151,30 +103,14 @@ const READER_PRESENCE_FILE = '.active-sessions-reader.presence';
 function readerPresencePath() {
     return readerPresencePathOverride ?? path.join(getCacheDir(), READER_PRESENCE_FILE);
 }
-/**
- * Record that a journal consumer is active right now.
- *
- * Called by {@link watchLocalSessions} on startup and on each heartbeat so
- * the daemon warm tick can gate the expensive `ps`+`lsof` gather on reader
- * presence and skip it when no watcher has checked in recently.
- */
 export function noteActiveSessionsJournalReader(nowMs = Date.now()) {
     try {
         const p = readerPresencePath();
         fs.mkdirSync(path.dirname(p), { recursive: true });
         fs.writeFileSync(p, String(nowMs));
     }
-    catch { /* best-effort: a failed write does not block the caller */ }
+    catch { }
 }
-/**
- * True when a journal consumer has signalled its presence within
- * {@link ACTIVE_SESSIONS_READER_IDLE_WINDOW_MS}.
- *
- * Used by the daemon warm tick to decide whether to run the expensive
- * `ps`+`lsof` gather. On an idle box with no watcher the tick skips the
- * gather entirely; the moment a new watcher connects it calls
- * {@link noteActiveSessionsJournalReader} and the following tick gathers.
- */
 export function isActiveSessionsJournalReaderRecent(nowMs = Date.now(), idleWindowMs = ACTIVE_SESSIONS_READER_IDLE_WINDOW_MS) {
     try {
         const content = fs.readFileSync(readerPresencePath(), 'utf8').trim();
@@ -187,24 +123,7 @@ export function isActiveSessionsJournalReaderRecent(nowMs = Date.now(), idleWind
         return false;
     }
 }
-/** Default poll cadence for {@link watchActiveSessionsReaderPresence}. */
 const ACTIVE_SESSIONS_READER_TRANSITION_POLL_MS = 1_000;
-/**
- * Watch for a reader going from absent/idle to present and fire `onConnect`
- * out of band, instead of waiting for the next scheduled warm tick (RUSH-2484).
- *
- * {@link noteActiveSessionsJournalReader} only writes a timestamp — it has no
- * path back to the daemon process that owns the warm tick's `setInterval`. A
- * watcher connecting to a cold or long-idle daemon therefore used to wait up
- * to one full {@link ACTIVE_SESSIONS_WARM_TICK_MS} tick for its first fresh
- * rows. This polls the tiny presence file (not the expensive `ps`+`lsof`
- * gather) at {@link ACTIVE_SESSIONS_READER_TRANSITION_POLL_MS} and calls
- * `onConnect` only on the idle→recent edge, so a steadily-connected reader's
- * repeated heartbeats never re-trigger it and an idle box with no reader never
- * gathers — the CPU win from RUSH-3193 is preserved.
- *
- * Returns a disposer that stops the poll.
- */
 export function watchActiveSessionsReaderPresence(onConnect, opts = {}) {
     const pollMs = opts.pollMs ?? ACTIVE_SESSIONS_READER_TRANSITION_POLL_MS;
     const now = opts.nowMs ?? Date.now;
@@ -218,8 +137,6 @@ export function watchActiveSessionsReaderPresence(onConnect, opts = {}) {
     timer.unref?.();
     return () => clearInterval(timer);
 }
-// ── snapshot read / write ──────────────────────────────────────────────────
-/** Read one scope from the snapshot file (best-effort; missing/corrupt → null). */
 export function readActiveSessionsCache(scope) {
     const memory = activeSnapshotMemory.get(scope);
     if (memory)
@@ -238,10 +155,6 @@ export function readActiveSessionsCache(scope) {
         return null;
     }
 }
-/**
- * Persist a snapshot for one scope (best-effort). Other scopes are preserved
- * so a local warm never drops a fleet snapshot a reader just wrote.
- */
 export function writeActiveSessionsCache(scope, sessions, opts = {}) {
     requireWriterProcessView();
     const snap = {
@@ -262,19 +175,14 @@ export function writeActiveSessionsCache(scope, sessions, opts = {}) {
                 entries = { ...prev.entries };
         }
         catch {
-            // empty
         }
         const hadPrevious = Boolean(entries[scope]);
         const previousSessions = entries[scope]?.sessions ?? [];
         entries[scope] = snap;
         const body = { version: 1, entries };
-        // Atomic replace so a concurrent reader never sees a partial write.
         const tmp = `${snapshotPath()}.tmp`;
         fs.writeFileSync(tmp, JSON.stringify(body));
         fs.renameSync(tmp, snapshotPath());
-        // The snapshot writer is the canonical publisher. Watchers tail this
-        // append-only journal and compute stream deltas; they never trigger their
-        // own full active-session gather on a timer.
         const previous = new Map(previousSessions.map((row) => [activeSessionJournalIdentity(row), row]));
         const next = new Map(sessions.map((row) => [activeSessionJournalIdentity(row), row]));
         const upserts = sessions.filter((row) => {
@@ -290,19 +198,13 @@ export function writeActiveSessionsCache(scope, sessions, opts = {}) {
             }
         }
         catch {
-            // Journal delivery is best-effort; the canonical snapshot remains valid.
         }
         activeSnapshotMemory.set(scope, snap);
     }
     catch {
-        // best-effort
     }
     return snap;
 }
-/**
- * True when a snapshot is still within the freshness window. Pure — the
- * staleness invariant for live status lives here.
- */
 export function isActiveSnapshotFresh(capturedAt, nowMs, maxAgeMs = DEFAULT_ACTIVE_CACHE_MAX_AGE_MS) {
     if (!Number.isFinite(capturedAt) || !Number.isFinite(maxAgeMs))
         return false;
@@ -310,8 +212,6 @@ export function isActiveSnapshotFresh(capturedAt, nowMs, maxAgeMs = DEFAULT_ACTI
         return false;
     return nowMs - capturedAt <= maxAgeMs;
 }
-// ── immutable memo ─────────────────────────────────────────────────────────
-/** Pull only the transcript-stable fields from a live row. */
 export function pickImmutableFields(s) {
     const out = {};
     for (const k of IMMUTABLE_FIELD_KEYS) {
@@ -321,11 +221,6 @@ export function pickImmutableFields(s) {
     }
     return out;
 }
-/**
- * Transcript mtime used as the memo key. Prefer {@link ActiveSession.lastActivityMs}
- * (the transcript's last write); fall back to `startedAtMs` when no activity
- * stamp exists. Returns null when neither is known — caller must not memoize.
- */
 export function transcriptMtimeMs(s) {
     if (typeof s.lastActivityMs === 'number' && Number.isFinite(s.lastActivityMs))
         return s.lastActivityMs;
@@ -341,15 +236,9 @@ function readImmutableFile() {
         }
     }
     catch {
-        // missing/corrupt
     }
     return { version: 1, entries: {} };
 }
-/**
- * Read memoized immutable fields for `(sessionId, mtimeMs)`.
- * Returns null when missing OR when the stored mtime does not match — a
- * transcript rewrite must force re-derivation of topic/label/etc.
- */
 export function readImmutableMemo(sessionId, mtimeMs) {
     if (!sessionId || !Number.isFinite(mtimeMs))
         return null;
@@ -357,10 +246,8 @@ export function readImmutableMemo(sessionId, mtimeMs) {
     const entry = file.entries[sessionId];
     if (!entry || entry.mtimeMs !== mtimeMs)
         return null;
-    // Defence in depth: strip any live-status key that snuck into a bad write.
     return stripLiveStatusKeys({ ...entry.fields });
 }
-/** Persist immutable fields for `(sessionId, mtimeMs)`. Live keys are stripped. */
 export function writeImmutableMemo(sessionId, mtimeMs, fields, nowMs = Date.now()) {
     if (!sessionId || !Number.isFinite(mtimeMs))
         return;
@@ -379,10 +266,8 @@ export function writeImmutableMemo(sessionId, mtimeMs, fields, nowMs = Date.now(
         fs.renameSync(tmp, immutablePath());
     }
     catch {
-        // best-effort
     }
 }
-/** Drop every live-status key from a field bag (defence in depth). */
 export function stripLiveStatusKeys(fields) {
     const out = { ...fields };
     for (const k of LIVE_STATUS_KEYS) {
@@ -391,10 +276,6 @@ export function stripLiveStatusKeys(fields) {
     }
     return out;
 }
-/**
- * True when `fields` contains no live-status key. The invariant the tests pin:
- * the immutable memo never carries status/activity/preview/etc.
- */
 export function assertNoLiveStatusFields(fields) {
     for (const k of LIVE_STATUS_KEYS) {
         if (k in fields && fields[k] !== undefined)
@@ -402,11 +283,6 @@ export function assertNoLiveStatusFields(fields) {
     }
     return true;
 }
-/**
- * Write immutable memos for every session that has an id + transcript mtime.
- * Called after a live gather so the next gather (when mtime is unchanged) can
- * refill identity fields without re-deriving them.
- */
 export function updateImmutableMemos(sessions, nowMs = Date.now()) {
     requireWriterProcessView();
     for (const s of sessions) {
@@ -418,21 +294,6 @@ export function updateImmutableMemos(sessions, nowMs = Date.now()) {
         writeImmutableMemo(s.sessionId, mtime, pickImmutableFields(s), nowMs);
     }
 }
-/**
- * Fill missing immutable fields on a live row from the memo when the transcript
- * mtime matches. Never overwrites a field the live gather already set, and
- * never copies live-status keys.
- */
-/**
- * Merge the daemon-computed session summary (PHNX-3939) onto a live row from the
- * transcript-keyed `session_summaries` cache. This is the low-cost display merge:
- * one indexed by-id read, NEVER a model call — the background
- * SessionSummarizerService is the only producer. It fills only what the cache
- * holds; the `pending`/`skipped` default for a row with no summary yet is applied
- * at the watch-stream boundary ({@link resolveStreamSummaryState}), so a
- * non-stream ActiveSession consumer is unaffected. Best-effort: a DB error leaves
- * the row untouched.
- */
 function mergeSessionSummary(s) {
     if (!s.sessionId)
         return s;
@@ -450,30 +311,14 @@ function mergeSessionSummary(s) {
             s.summaryState = stored.summaryState;
     }
     catch {
-        // best-effort: never let the summary merge break the gather path.
     }
     return s;
 }
-/**
- * The `summaryState` a watch-stream row carries when the merge left it unset:
- * `pending` while the summarizer is READY (enabled AND has an endpoint, so a
- * summary is genuinely coming), `skipped` when it is off OR enabled-but-
- * unconfigured (nothing will ever populate the cache). This is the only place
- * the readiness flag is read on the read path, and it is memoized (PHNX-3939).
- */
 export function resolveStreamSummaryState(current, nowMs = Date.now()) {
     if (current)
         return current;
     return isSummarizerReady(nowMs) ? 'pending' : 'skipped';
 }
-/**
- * Merge the daemon-folded timeline (PHNX-3939) onto a live row from the
- * transcript-keyed `session_timelines` cache. Sibling of
- * {@link mergeSessionSummary} and the same contract: one indexed by-id read of
- * the BOUNDED projection (never the fold's resume state), never a parse, never
- * a model call. `runTimelinePass` in the daemon tick is the only producer.
- * Best-effort — a DB error leaves the row untouched.
- */
 export function mergeSessionTimeline(s) {
     if (!s.sessionId)
         return s;
@@ -481,17 +326,17 @@ export function mergeSessionTimeline(s) {
         const stored = readSessionTimelineAny(s.sessionId);
         if (!stored)
             return s;
+        for (const key of ['model', 'failures', 'activityHistogram', 'userTurns', 'attachments', 'subagents']) {
+            if (stored[key] !== undefined)
+                Object.assign(s, { [key]: stored[key] });
+        }
+        if (s.subagents)
+            s.subAgentCount = s.subagents.length;
         if (s.timeline === undefined)
             s.timeline = stored.timeline;
         if (s.files === undefined && stored.files !== undefined)
             s.files = stored.files;
         if (stored.request) {
-            // `request` is the one field where the FOLD wins over what the gather
-            // already put there. `foldRecap` tidies whatever turn the INDEX had for the
-            // row, which lags a live session by up to a scan; the daemon fold read the
-            // transcript itself this tick and counted the turns. Re-deriving the recap
-            // afterwards keeps the row's title and `userPromptClean` agreeing with the
-            // request they are supposed to describe.
             const changed = s.request?.headline !== stored.request.headline || s.request?.turns !== stored.request.turns;
             s.request = stored.request;
             if (changed)
@@ -499,7 +344,6 @@ export function mergeSessionTimeline(s) {
         }
     }
     catch {
-        // best-effort: never let the timeline merge break the gather path.
     }
     return s;
 }
@@ -521,11 +365,6 @@ export function applyImmutableMemo(s) {
     }
     return s;
 }
-/**
- * Cache-first load of THIS host's active sessions. Default path serves the
- * daemon-warmed snapshot when fresh; `forceRefresh` or an expired snapshot
- * re-gathers and rewrites the cache.
- */
 export async function loadLocalActiveSessions(opts = {}) {
     const now = opts.nowMs ?? Date.now();
     const maxAge = opts.maxAgeMs ?? DEFAULT_ACTIVE_CACHE_MAX_AGE_MS;
@@ -549,25 +388,26 @@ export async function loadLocalActiveSessions(opts = {}) {
     }
     const gather = opts.gather ??
         (async () => {
-            const { getActiveSessions } = await import('./active.js');
-            return getActiveSessions({ localOnly: true });
+            const [{ getActiveSessions }, { machineId }] = await Promise.all([
+                import('./active.js'),
+                import('../machine-id.js'),
+            ]);
+            const self = machineId();
+            const rows = await getActiveSessions({ localOnly: true });
+            for (const s of rows)
+                if (!s.machine)
+                    s.machine = self;
+            return rows;
         });
     const sessions = await gather();
-    // The index owns transcript-derived labels (Claude custom-title / ai-title).
-    // Enrich before publishing so the canonical watch snapshot carries the same
-    // label as one-shot `sessions --active` output.
     backfillActiveRowsFromIndex(sessions);
     for (const s of sessions)
         applyImmutableMemo(s);
+    enrichGlanceFiles(sessions, now);
     updateImmutableMemos(sessions, now);
     const snap = writeCache('local', sessions, { capturedAt: now });
     return { sessions, servedFromCache: false, capturedAt: snap.capturedAt };
 }
-/**
- * Cache-first load of the fleet-wide active set. A prior gather (or any surface
- * that just paid the SSH cost) leaves a fleet snapshot; subsequent menubar /
- * Factory / CLI / watchdog calls within the freshness window share it.
- */
 export async function loadFleetActiveSessions(opts) {
     const now = opts.nowMs ?? Date.now();
     const maxAge = opts.maxAgeMs ?? DEFAULT_ACTIVE_CACHE_MAX_AGE_MS;
@@ -598,9 +438,6 @@ export async function loadFleetActiveSessions(opts) {
         capturedAt: now,
         remoteDeviceCount: live.remoteDeviceCount,
     });
-    // Also refresh the local slice so a `--local` reader benefits from this gather.
-    // Identity is machineId() when available; fall back to "rows with no machine
-    // stamp" so a pure-local gather that never set machine still warms the cache.
     let self;
     try {
         const { machineId } = await import('../machine-id.js');
@@ -609,18 +446,7 @@ export async function loadFleetActiveSessions(opts) {
     catch {
         self = undefined;
     }
-    // Always rewrite the local slice when we know self — including the empty
-    // case. If the last local session just died, leaving a still-fresh snapshot
-    // with ghost rows would make watchdog / `--local` report sessions that are
-    // gone (review on RUSH-2062 / PR #2116).
     if (self !== undefined) {
-        // "Local" here means the PROCESS is on this box, which is not `machine ===
-        // self` for an offloaded run: its shim runs here while the agent executes on
-        // the peer (RUSH-2479). The other writer of this same key,
-        // `loadLocalActiveSessions`, seeds from `getActiveSessions({localOnly:true})`
-        // and keeps that shim — so comparing `machine` here would make the two
-        // disagree and leave `--local` showing or hiding the row depending on which
-        // surface last warmed the 15s cache.
         const localOnly = live.sessions.filter((s) => sessionProcessIsLocal(s, self));
         writeCache('local', localOnly, { capturedAt: now });
     }
@@ -633,10 +459,7 @@ export async function loadFleetActiveSessions(opts) {
         remoteDiscoveryFailed: live.remoteDiscoveryFailed,
     };
 }
-/**
- * Daemon warm entry point: live-gather THIS host and write the local snapshot.
- * Never SSHes. Returns the published row count for the daemon log line.
- */
+// Daemon warm publishes this host only and never SSHes; readers may write fleet snapshots without becoming a second publisher.
 export async function publishLocalActiveSessions(opts = {}) {
     const result = await loadLocalActiveSessions({
         forceRefresh: true,

package/dist/lib/session/short-id.js

@@ -1,4 +1 @@
-// Moved to ../text/short-id.ts (move 1 of the core-module refactor — see
-// .agents/artifacts/2026-08-20/plan-*.md). Kept as a re-export shim so
-// existing importers don't break.
 export * from '../text/short-id.js';

package/dist/lib/session/sync/agents.d.ts

@@ -1,92 +1,24 @@
-/**
- * Per-agent adapter for sync. Each supported agent declares where its
- * transcripts live and how to derive a session id and storage-relative key
- * from a file path. The merge (crdt.ts) and transport (r2.ts) are fully
- * agent-agnostic — adding a new agent is just another entry in SYNC_AGENTS.
- *
- * Mirror layout: synced-in transcripts land under
- *   ~/.agents/.history/backups/<agent>/<machine>/<subdir>/<relKey>
- * which is already a scan root (getAgentSessionDirs scans backups/<agent>/<ts>),
- * so the existing incremental scanner indexes them with no changes. Because the
- * scanner dedups by session id with the live home scanned first, a session that
- * also exists locally always wins — the mirror only ever fills in sessions
- * originated on other machines.
- */
-/** One constituent file of a session — a session has exactly one for file-shaped
- *  agents (Claude, Codex, …), and many for directory-shaped ones (Kimi). */
 export interface SessionFile {
-    /** Absolute path on this machine. */
     absPath: string;
-    /** Path relative to the agent's subdir root — preserved in the mirror layout. */
     relKey: string;
 }
 export interface LocalTranscript {
-    /** Globally-unique session id (the grouping key across machines). */
     sessionId: string;
-    /** Every file that makes up this session. Length 1 for file-shaped agents. */
     files: SessionFile[];
 }
 export interface SyncAgentSpec {
     id: string;
-    /** Config subdir under the agent home that holds transcripts. */
     subdir: string;
-    /** File extension to walk for this agent (defaults to .jsonl). */
     ext?: string;
-    /**
-     * A session is a DIRECTORY of files (e.g. Kimi: state.json + agents/…/wire.jsonl
-     * + per-tool task sidecars), not a single transcript. When set, every file under
-     * the session dir (matching `exts`, passing `fileFilter`) syncs, is stored under
-     * its own R2 sub-key, and is mirrored at its own relative path — instead of the
-     * file-shaped "one transcript per session" model.
-     */
     dirShaped?: boolean;
-    /** Extensions a dir-shaped agent walks (defaults to `[ext ?? '.jsonl']`). */
     exts?: string[];
-    /** Optional per-file exclusion for dir-shaped agents (lock/scratch files, …). */
     fileFilter?(relKey: string): boolean;
-    /**
-     * Extensions whose files are append-only event logs and therefore CRDT-mergeable
-     * (G-Set union across forked copies). A dir-shaped session usually mixes an
-     * append-only conversation log (`wire.jsonl`) with mutable metadata blobs
-     * (`state.json`) — line-unioning the latter would corrupt it, so any file NOT
-     * matching an entry here is reconciled last-writer-wins instead. Undefined (the
-     * file-shaped default) means every file is mergeable — the single `.jsonl`
-     * transcript keeps its existing union behaviour.
-     */
     mergeableExts?: string[];
-    /** Derive the session id from a storage-relative key. */
     sessionIdFromRelKey(relKey: string): string;
 }
-/** True when a file at `relKey` is an append-only log that CRDT-unions across
- *  forks; false when it must be reconciled last-writer-wins (mutable blob). */
 export declare function isMergeableFile(spec: SyncAgentSpec, relKey: string): boolean;
 export declare const SYNC_AGENTS: SyncAgentSpec[];
-/**
- * List this machine's own transcript files for an agent, EXCLUDING the sync
- * mirror (we never re-upload another machine's files under our prefix). Dedups
- * by session id so a session present in multiple version homes is uploaded once.
- */
 export declare function listLocalTranscripts(spec: SyncAgentSpec): LocalTranscript[];
-/**
- * Absolute mirror path for a remote machine's transcript — lands in a scan root.
- *
- * `machine` and `relKey` come from a peer's manifest (untrusted: any peer with
- * write access to the shared bucket controls them). Unlike the push side, which
- * already drops `relKey` starting with `..` when building the manifest, the pull
- * side would otherwise `fs.writeFileSync` at this path with peer-controlled
- * content. `machine` is constrained to a single segment and `relKey` (which may
- * legitimately nest, e.g. `projects/x/y.jsonl`) is contained beneath the
- * per-machine mirror root, so a crafted `relKey` like `../../../.ssh/authorized_keys`
- * cannot write outside `~/.agents/.history/backups/<agent>/<machine>/<subdir>`.
- */
 export declare function mirrorPath(spec: SyncAgentSpec, machine: string, relKey: string): string;
-/**
- * R2 object key for a transcript.
- *  - file-shaped (relKey omitted): sessions/<machine>/<agent>/<sessionId>.jsonl —
- *    unchanged, so existing claude/codex/droid objects keep their keys.
- *  - dir-shaped (relKey given): sessions/<machine>/<agent>/<sessionId>/<relKey> —
- *    one object per constituent file of the session directory.
- */
 export declare function objectKey(machine: string, agentId: string, sessionId: string, relKey?: string): string;
-/** Prefix under which all machine manifests live (for discovery). */
 export declare const SESSIONS_PREFIX = "sessions/";

package/dist/lib/session/sync/backend.d.ts

@@ -1,61 +1,22 @@
-/**
- * SessionsBackend — the token-source seam for `agents sessions export --to-r2` /
- * `import --from-r2`.
- *
- * Two legitimate principals, picked once at backup time through the ONE shared
- * managed-vs-BYO policy (`selectStorageBackendKind`):
- *
- *   - **managed**: the caller is signed in to Phoenix (`readSession()`), no
- *     explicit BYO override. Token is the Phoenix access_token; endpoint is the
- *     managed `sessions.agents-cli.sh` Worker; the namespace is the verified
- *     userId. ZERO Cloudflare setup — the user never provisions an r2.backups
- *     bucket. This is the whole point of the surface (the sessions analogue of
- *     managed `agents traces sync`).
- *   - **byo**: the existing `r2.backups` secrets bundle (`loadR2Config()`).
- *     Unchanged for power users / self-hosters / a zero-knowledge backup that
- *     Phoenix can never read.
- *
- * MANAGED-FIRST — the mere PRESENCE of an r2.backups bundle is NOT a BYO
- * override. A signed-in user with a stale r2.backups bundle still backs up to
- * managed unless they opt out explicitly: `--byo`, `AGENTS_SESSIONS_BACKEND=byo`,
- * or a DI write token. This mirrors the artifact-share backend contract (a
- * persisted BYO config is deliberately not an override) so the product's
- * managed-first contract is identical across surfaces.
- */
 import { type PhoenixSession } from '../../identity/client.js';
 import { type R2Config } from './config.js';
-/** Env var that forces the BYO path. Value must be exactly `byo`. */
 export declare const SESSIONS_BACKEND_ENV = "AGENTS_SESSIONS_BACKEND";
 interface ManagedSessionsBackend {
     kind: 'managed';
-    /** Public base URL of the managed sessions Worker, no trailing slash. */
     baseUrl: string;
-    /** Bearer sent as `Authorization`. The Phoenix access_token. */
     token: string;
-    /** Phoenix userId — the object-store namespace prefix (path segment 0). */
     userId: string;
 }
 interface ByoSessionsBackend {
     kind: 'byo';
-    /** The resolved r2.backups credentials for the S3-compatible client. */
     r2: R2Config;
 }
 type SessionsBackend = ManagedSessionsBackend | ByoSessionsBackend;
 interface ResolveSessionsBackendOpts {
-    /** Force the BYO r2.backups path even when signed in. */
     byo?: boolean;
-    /** DI seam — a static write token selects BYO (tests / self-host). */
     writeToken?: string;
-    /** DI seam — override `readSession()`. `null` means explicitly signed out. */
     session?: PhoenixSession | null;
 }
-/** True when the shared policy resolves to the managed principal for sessions. */
 export declare function shouldUseManagedSessions(opts?: ResolveSessionsBackendOpts): boolean;
-/**
- * Resolve the backend for a session backup / restore. Managed when signed in and
- * no explicit BYO override; otherwise BYO. Fails loud when neither principal can
- * authenticate — the actionable message ("run auth login" or "add r2.backups")
- * lives here, not in the shared policy.
- */
 export declare function resolveSessionsBackend(opts?: ResolveSessionsBackendOpts): SessionsBackend;
 export {};