@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/session/sync/r2.js

@@ -1,14 +1,3 @@
-/**
- * Minimal S3-compatible client for Cloudflare R2, built on aws4fetch (SigV4
- * over the platform `fetch` + WebCrypto — works identically under Bun and
- * Node >= 22). Only the verbs the backup target needs: put / get / head / list /
- * delete.
- *
- * No mounting, no FUSE: this is a plain object-store client driven on demand by
- * `agents sessions export --to-r2` / `import --from-r2`, which is the only
- * approach that is seamless on both macOS and Linux (Mountpoint for S3 is
- * Linux-only; rclone-mount needs macFUSE).
- */
 import { AwsClient } from 'aws4fetch';
 export class R2Client {
     kind = 'byo';
@@ -27,7 +16,6 @@ export class R2Client {
         const encoded = key.split('/').map(encodeURIComponent).join('/');
         return `${this.base}/${encoded}`;
     }
-    /** Upload an object. Overwrites unconditionally. */
     async put(key, body, contentType = 'application/octet-stream') {
         const res = await this.aws.fetch(this.url(key), {
             method: 'PUT',
@@ -37,7 +25,6 @@ export class R2Client {
         if (!res.ok)
             throw new Error(`R2 PUT ${key} failed: ${res.status} ${await safeText(res)}`);
     }
-    /** Fetch an object as text, or null if it does not exist (404). */
     async get(key) {
         const res = await this.aws.fetch(this.url(key), { method: 'GET' });
         if (res.status === 404)
@@ -46,7 +33,6 @@ export class R2Client {
             throw new Error(`R2 GET ${key} failed: ${res.status} ${await safeText(res)}`);
         return await res.text();
     }
-    /** HEAD an object for size + etag, or null if it does not exist. */
     async head(key) {
         const res = await this.aws.fetch(this.url(key), { method: 'HEAD' });
         if (res.status === 404)
@@ -58,14 +44,12 @@ export class R2Client {
             etag: (res.headers.get('etag') ?? '').replace(/"/g, ''),
         };
     }
-    /** Delete an object (no error if it is already absent). */
     async delete(key) {
         const res = await this.aws.fetch(this.url(key), { method: 'DELETE' });
         if (!res.ok && res.status !== 404) {
             throw new Error(`R2 DELETE ${key} failed: ${res.status}`);
         }
     }
-    /** List immediate sub-prefixes under a prefix (delimiter '/'), e.g. machine dirs. */
     async listPrefixes(prefix) {
         const prefixes = [];
         let token;
@@ -85,9 +69,6 @@ export class R2Client {
         } while (token);
         return prefixes;
     }
-    /** List all object keys under a prefix (handles pagination). An empty prefix
-     *  lists the whole bucket — the default so R2Client satisfies the shared
-     *  {@link SessionsBackupClient} interface (managed lists with no prefix). */
     async list(prefix = '') {
         const keys = [];
         let token;
@@ -109,7 +90,6 @@ export class R2Client {
     }
 }
 const XML_ENTITIES = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'" };
-/** Single pass: sequential replaces would double-decode `&amp;lt;` into `<`. */
 export function decodeXml(s) {
     return s.replace(/&(?:amp|lt|gt|quot|apos);/g, (entity) => XML_ENTITIES[entity] ?? entity);
 }

package/dist/lib/session/sync/transcript-crypto.d.ts

@@ -24,55 +24,18 @@
  * manifest, not the object body, carries the hash.
  */
 import type { R2Config } from './config.js';
-/** Serialized envelope stored as the R2 object body when encryption is on. */
 interface TranscriptEnvelope {
-    /** Envelope format version. */
     v: 1;
     alg: 'aes-256-gcm';
-    /** base64 12-byte GCM nonce, fresh per object. */
     iv: string;
-    /** base64 ciphertext. */
     ct: string;
-    /** base64 16-byte GCM auth tag. */
     tag: string;
 }
-/**
- * Decode the configured `R2_SYNC_ENC_KEY` into a 32-byte key, or null when the
- * bundle does not carry one (encryption off — see pushOwn's warning path).
- *
- * Accepts hex (64 chars) or base64; both must decode to exactly 32 bytes. A key
- * that is present but the wrong length THROWS rather than silently truncating —
- * a malformed key is a configuration bug, not a reason to fall back to a weaker
- * or wrong key.
- */
 export declare function resolveSyncEncKey(cfg: Pick<R2Config, 'syncEncKey'>): Buffer | null;
-/** Generate a fresh 32-byte transcript key, base64-encoded (for provisioning). */
 export declare function generateSyncEncKey(): string;
-/** Seal a transcript body. Returns the serialized envelope to store in R2. */
 export declare function encryptTranscript(plaintext: string, key: Buffer): string;
-/**
- * Parse a stored object body into an envelope, or null when it is not one.
- *
- * A plaintext transcript is NDJSON — many JSON objects, one per line — so it
- * never parses as a single object carrying our `v`/`alg`/`ct`/`tag` fields. That
- * makes envelope-vs-plaintext detection unambiguous and lets a puller read BOTH
- * encrypted objects and any legacy plaintext already in the bucket (the beta
- * uploaded plaintext before this landed). This is format-version handling for a
- * real migration, not a "just in case" fallback.
- */
 export declare function parseEnvelope(body: string): TranscriptEnvelope | null;
-/** True when a stored object body is one of our encryption envelopes. */
 export declare function isTranscriptEnvelope(body: string): boolean;
-/** Open a sealed envelope. Throws on a wrong key / tampered body (GCM tag mismatch). */
 export declare function decryptEnvelope(envelope: TranscriptEnvelope, key: Buffer): string;
-/**
- * Return the plaintext transcript for a fetched object body, transparently
- * decrypting when it is an envelope.
- *
- *  - Envelope + key  → decrypted plaintext.
- *  - Envelope + no key → throws (the object is encrypted but this machine has no
- *    key to read it — surfacing that beats silently mis-merging ciphertext).
- *  - Plaintext body  → returned verbatim (legacy/unencrypted object).
- */
 export declare function decryptTranscriptBody(body: string, key: Buffer | null): string;
 export {};

package/dist/lib/session/sync/transcript-crypto.js

@@ -25,18 +25,9 @@
  */
 import * as crypto from 'crypto';
 const ALG = 'aes-256-gcm';
-const KEY_LEN = 32; // AES-256
-const IV_LEN = 12; // GCM standard nonce
+const KEY_LEN = 32;
+const IV_LEN = 12;
 const TAG_LEN = 16;
-/**
- * Decode the configured `R2_SYNC_ENC_KEY` into a 32-byte key, or null when the
- * bundle does not carry one (encryption off — see pushOwn's warning path).
- *
- * Accepts hex (64 chars) or base64; both must decode to exactly 32 bytes. A key
- * that is present but the wrong length THROWS rather than silently truncating —
- * a malformed key is a configuration bug, not a reason to fall back to a weaker
- * or wrong key.
- */
 export function resolveSyncEncKey(cfg) {
     const raw = cfg.syncEncKey?.trim();
     if (!raw)
@@ -55,11 +46,9 @@ export function resolveSyncEncKey(cfg) {
     }
     return key;
 }
-/** Generate a fresh 32-byte transcript key, base64-encoded (for provisioning). */
 export function generateSyncEncKey() {
     return crypto.randomBytes(KEY_LEN).toString('base64');
 }
-/** Seal a transcript body. Returns the serialized envelope to store in R2. */
 export function encryptTranscript(plaintext, key) {
     const iv = crypto.randomBytes(IV_LEN);
     const cipher = crypto.createCipheriv(ALG, key, iv);
@@ -74,23 +63,13 @@ export function encryptTranscript(plaintext, key) {
     };
     return JSON.stringify(envelope);
 }
-/**
- * Parse a stored object body into an envelope, or null when it is not one.
- *
- * A plaintext transcript is NDJSON — many JSON objects, one per line — so it
- * never parses as a single object carrying our `v`/`alg`/`ct`/`tag` fields. That
- * makes envelope-vs-plaintext detection unambiguous and lets a puller read BOTH
- * encrypted objects and any legacy plaintext already in the bucket (the beta
- * uploaded plaintext before this landed). This is format-version handling for a
- * real migration, not a "just in case" fallback.
- */
 export function parseEnvelope(body) {
     const trimmed = body.trimStart();
     if (!trimmed.startsWith('{'))
-        return null; // NDJSON first line is an object too, but…
+        return null;
     let obj;
     try {
-        obj = JSON.parse(body); // …the WHOLE body must be one JSON value to be an envelope
+        obj = JSON.parse(body);
     }
     catch {
         return null;
@@ -105,11 +84,9 @@ export function parseEnvelope(body) {
     }
     return null;
 }
-/** True when a stored object body is one of our encryption envelopes. */
 export function isTranscriptEnvelope(body) {
     return parseEnvelope(body) !== null;
 }
-/** Open a sealed envelope. Throws on a wrong key / tampered body (GCM tag mismatch). */
 export function decryptEnvelope(envelope, key) {
     const iv = Buffer.from(envelope.iv, 'base64');
     const ct = Buffer.from(envelope.ct, 'base64');
@@ -126,19 +103,10 @@ export function decryptEnvelope(envelope, key) {
         throw new Error('Transcript decryption failed — wrong R2_SYNC_ENC_KEY or corrupt object.');
     }
 }
-/**
- * Return the plaintext transcript for a fetched object body, transparently
- * decrypting when it is an envelope.
- *
- *  - Envelope + key  → decrypted plaintext.
- *  - Envelope + no key → throws (the object is encrypted but this machine has no
- *    key to read it — surfacing that beats silently mis-merging ciphertext).
- *  - Plaintext body  → returned verbatim (legacy/unencrypted object).
- */
 export function decryptTranscriptBody(body, key) {
     const envelope = parseEnvelope(body);
     if (!envelope)
-        return body; // legacy plaintext object
+        return body;
     if (!key) {
         throw new Error('Fetched an encrypted transcript but R2_SYNC_ENC_KEY is not set in the r2.backups bundle. ' +
             'Add the shared key so this machine can decrypt peers\' sessions.');

package/dist/lib/session/sync/worker-template.d.ts

@@ -1,6 +1 @@
-/**
- * Render the managed sessions Worker source. Pure — bindings are wired at
- * deploy time. No `${}` interpolation in the emitted source (string
- * concatenation only) so the outer template literal never captures it.
- */
 export declare function renderSessionsWorkerScript(): string;

package/dist/lib/session/sync/worker-template.js

@@ -1,43 +1,3 @@
-// The Cloudflare Worker that fronts the R2 managed session-backup bucket.
-//
-// SECURITY: like agents-traces (and UNLIKE agents-share), there is NO public GET
-// path here. Every route — PUT, GET, LIST, DELETE — requires a Phoenix bearer;
-// there is NO static-token principal (the zero-knowledge BYO path talks to the
-// user's own R2 bucket directly and never reaches this Worker, so a WRITE_TOKEN
-// here would only be a Phoenix-and-quota bypass — PHNX-3726). The caller must be
-// the record's owner: the path's first segment MUST equal the verified userId. A
-// missing bearer → 401; a wrong owner → 403; public cache headers are NEVER
-// emitted. A stored transcript body MUST be an AES-256-GCM envelope — a plaintext
-// PUT is rejected 422 so readable transcript content can never land in the bucket.
-//
-// Object layout is OPAQUE to the Worker: the CLI stores each session under
-//   <userId>/sessions/<machine>/<agent>/<sessionId>.jsonl          (file-shaped)
-//   <userId>/sessions/<machine>/<agent>/<sessionId>/<relKey>       (dir-shaped)
-// but the Worker only enforces segments[0] === userId and never parses the rest.
-// Deliberately DIFFERENT from traces: there is NO `/all` cross-device merge here.
-// Session transcripts are opaque, client-side-encrypted envelopes — merging or
-// re-projecting them server-side would corrupt them — so the Worker is a pure
-// per-owner blob store with a server-side LIST for restore.
-//
-// Reserved prefixes `__usage` (the CAS quota ledger) and `__key` (the escrowed
-// backup DEK) are owner-bearer only and are NEVER returned by LIST.
-//
-// Routes (all require a Phoenix bearer + segments[0] === userId):
-//   PUT    /<userId>/<key...>     — store an object; quota-charged (413 over quota)
-//   GET    /<userId>/<key...>     — return the stored object (404 if absent)
-//   GET    /<userId>/?list        — JSON array of this owner's keys (no __ prefixes),
-//                                    each relative to <userId>/ (the CLI re-prepends)
-//   DELETE /<userId>/<key...>     — logical delete via hidden tombstone; refunds quota
-//   GET    /                      — 401 (there is no public route)
-//
-// Emitted as a string so it compiles into dist/** with no package.json#files
-// change. `provision.ts` uploads this verbatim as an ES-module Worker with a
-// BUCKET (R2) binding + a PHOENIX_ID_BASE secret.
-/**
- * Render the managed sessions Worker source. Pure — bindings are wired at
- * deploy time. No `${}` interpolation in the emitted source (string
- * concatenation only) so the outer template literal never captures it.
- */
 export function renderSessionsWorkerScript() {
     return `// GENERATED by agents-cli agents sessions — do not edit; edit
 // src/lib/session/sync/worker-template.ts and re-provision.

package/dist/lib/session/testdata/pid-registry-namespace.js

@@ -3,9 +3,7 @@ import fs from 'node:fs';
 import { prunePidSessionRegistry, readPidSessionEntry, writePidSessionEntry } from '../pid-registry.js';
 import { getActiveSessions } from '../active.js';
 import { loadLocalActiveSessions, loadFleetActiveSessions, writeActiveSessionsCache, updateImmutableMemos, readActiveSessionsCache } from '../session-cache.js';
-// Invoked only by the isolated-HOME test fork, inside a real unshare namespace.
 const hostPid = Number(process.argv[2]);
-// Names convey no authority: this is PID 1 with its own procfs in one variant.
 fs.writeFileSync('/proc/self/comm', 'init');
 assert.equal(readPidSessionEntry(hostPid)?.sessionId, 'host-session');
 assert.throws(() => process.kill(hostPid, 0), { code: 'ESRCH' });

package/dist/lib/session/testdata/process-view-private.js

@@ -2,7 +2,6 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import { writePidSessionEntry, readLivePidSessionEntry } from '../pid-registry.js';
 import { writeActiveSessionsCache, readActiveSessionsCache } from '../session-cache.js';
-// A container owns its private home regardless of the name of PID 1.
 assert.equal(process.pid, 1);
 fs.writeFileSync('/proc/self/comm', process.argv[2]);
 writePidSessionEntry({ pid: process.pid, agent: 'codex', sessionId: 'private-home', startedAtMs: Date.now() });

package/dist/lib/session/throughput.d.ts

@@ -1,27 +1,3 @@
-/**
- * Live output-token throughput.
- *
- * Computes a rolling tokens-per-second readout from a session transcript's raw
- * content. This is the single source of truth for the throughput number the
- * Fleet shows next to a running agent — the extension used to carry its
- * own copy of this math (`computeOutputTokensPerSec`); it now reads `tokPerSec`
- * straight off `agents sessions --active --json` instead (issue #741).
- */
-/** Agents whose transcript formats report per-turn output-token usage. */
 type ThroughputAgent = 'claude' | 'codex';
-/**
- * Output-token throughput (tokens/sec) over the last `windowSec` seconds.
- *
- * Sums output tokens (plus reasoning/thoughts tokens when the format reports
- * them separately) from entries whose timestamp falls within the window, and
- * divides by the window length.
- *
- * Formats:
- *   - Claude: JSONL. Each assistant turn is `{type: 'assistant', timestamp,
- *     message: {usage: {output_tokens}}}`.
- *   - Codex:  JSONL. Each token_count event is `{type: 'event_msg', timestamp,
- *     payload: {type: 'token_count', info: {last_token_usage: {output_tokens,
- *     reasoning_output_tokens}}}}`. `last_token_usage` is per-turn (not cumulative).
- */
 export declare function computeTokPerSec(sessionContent: string, agent: ThroughputAgent, windowSec?: number, now?: number): number;
 export {};

package/dist/lib/session/throughput.js

@@ -1,28 +1,4 @@
-/**
- * Live output-token throughput.
- *
- * Computes a rolling tokens-per-second readout from a session transcript's raw
- * content. This is the single source of truth for the throughput number the
- * Fleet shows next to a running agent — the extension used to carry its
- * own copy of this math (`computeOutputTokensPerSec`); it now reads `tokPerSec`
- * straight off `agents sessions --active --json` instead (issue #741).
- */
-/** Rolling window (seconds) the throughput average is computed over. */
 const DEFAULT_THROUGHPUT_WINDOW_SEC = 60;
-/**
- * Output-token throughput (tokens/sec) over the last `windowSec` seconds.
- *
- * Sums output tokens (plus reasoning/thoughts tokens when the format reports
- * them separately) from entries whose timestamp falls within the window, and
- * divides by the window length.
- *
- * Formats:
- *   - Claude: JSONL. Each assistant turn is `{type: 'assistant', timestamp,
- *     message: {usage: {output_tokens}}}`.
- *   - Codex:  JSONL. Each token_count event is `{type: 'event_msg', timestamp,
- *     payload: {type: 'token_count', info: {last_token_usage: {output_tokens,
- *     reasoning_output_tokens}}}}`. `last_token_usage` is per-turn (not cumulative).
- */
 export function computeTokPerSec(sessionContent, agent, windowSec = DEFAULT_THROUGHPUT_WINDOW_SEC, now = Date.now()) {
     const cutoff = now - windowSec * 1000;
     let total = 0;
@@ -60,7 +36,7 @@ export function computeTokPerSec(sessionContent, agent, windowSec = DEFAULT_THRO
                 total += out + reasoning;
             }
         }
-        catch { /* skip malformed line */ }
+        catch { }
     }
     return total / windowSec;
 }

package/dist/lib/session/timeline-pass.d.ts

@@ -1,61 +1,17 @@
-/**
- * The daemon's incremental timeline pass (PHNX-3939).
- *
- * Runs inside the existing `SessionStateService` tick, which is already
- * reader-gated — no watcher, no work — and already visits every live session.
- * This adds the one thing the tick did not do: fold each live transcript's
- * NEW BYTES into its cached {@link TimelineState} and store the bounded
- * projection a session row merges.
- *
- * Three properties keep it off the request path and off the CPU:
- *   - **Reader-gated and budgeted.** Nothing runs unless a `sessions watch`
- *     consumer is attached, and at most `budget` sessions are folded per tick.
- *   - **Appended bytes only.** For the resumable harnesses (Claude and Codex,
- *     line-delimited JSON) a fold reads `size - offset` bytes, not the file.
- *     The same resume rule the tool index already uses (`tool-index.ts`).
- *   - **Complete records only.** Only newline-terminated lines are folded and
- *     the offset advances past those alone, so the 973,963-byte record in one
- *     live transcript on this fleet cannot be folded half-written; the next tick
- *     picks it up whole.
- */
 import type { ActiveSession } from './active.js';
-import type { SessionAgentId, SessionEvent } from './types.js';
-/** Bytes one session may consume in one tick. A bigger backlog catches up over ticks. */
+import type { SessionAgentId, SessionEvent } from '@phnx-labs/sessions-cli/reader';
 export declare const TIMELINE_PASS_MAX_BYTES_PER_SESSION: number;
-/**
- * Ceiling on a whole-file re-parse for a harness with no resumable reader.
- * Beyond it the timeline is reported `partial` rather than wedging the tick —
- * the same honesty rule the tool index applies at its own in-memory limit.
- */
 export declare const TIMELINE_PASS_MAX_WHOLE_FILE_BYTES: number;
-/**
- * How long a non-resumable harness's timeline may go stale before the pass
- * re-parses its transcript whole.
- *
- * Kimi and Grok expose no byte offset to resume from, so their only option is a
- * full parse — and a full parse of a large, actively-appended transcript wedges
- * the Node event loop for seconds (the PHNX-3411 incident, which is why the tool
- * index deferred those two harnesses to their own budgeted pass). Re-parsing
- * every 15 s would reproduce it. One re-parse per minute keeps such a session's
- * timeline current enough for a card that moves about once a minute, at a
- * quarter of the cost.
- */
 export declare const TIMELINE_PASS_NON_RESUMABLE_MIN_INTERVAL_MS = 60000;
 interface TimelinePassResult {
-    /** Sessions whose timeline was folded and written this tick. */
     computed: number;
-    /** Sessions whose cached timeline already matched the transcript bytes. */
     reused: number;
-    /** Sessions skipped: unreadable transcript, no id/file, or no parseable transcript. */
     skipped: number;
 }
 interface TimelinePassOptions {
-    /** Live rows to fold. Defaults to the local active-sessions cache. */
     sessions?: ActiveSession[];
     budget?: number;
-    /** Bytes the whole pass may read this tick, across every session. */
     maxBytes?: number;
-    /** Set false only in tests: the pass is reader-gated exactly like the warm tick. */
     requireReader?: boolean;
     nowMs?: number;
     signal?: AbortSignal;
@@ -64,26 +20,8 @@ interface TimelinePassOptions {
         size: number;
     };
 }
-/**
- * Every event of one transcript, read the way the timeline fold needs them.
- *
- * The single source of truth for "which reader does this harness's timeline
- * use", shared by the daemon pass's non-resumable branch and
- * `agents sessions trace --steps` — so the CLI door and the cached row can never
- * fold two different event streams for the same session.
- */
 export declare function parseTimelineEvents(filePath: string, agent: SessionAgentId): SessionEvent[];
-/**
- * Fold the timelines of the live local sessions, bounded, once per tick.
- * Returns what it did so the daemon tick can log it like every other pass.
- *
- * Async only because resolving the session list needs the session-cache module,
- * which is loaded lazily to keep this off the CLI's startup graph. When the
- * caller already HAS the rows (the daemon tick does — it just gathered them),
- * {@link runTimelinePassSync} is the same work with no dynamic import.
- */
 export declare function runTimelinePass(opts?: TimelinePassOptions): Promise<TimelinePassResult>;
-/** {@link runTimelinePass} over an explicit row list. Pure of the session cache. */
 export declare function runTimelinePassSync(opts: TimelinePassOptions & {
     sessions: ActiveSession[];
 }): TimelinePassResult;