@phnx-labs/agents-cli 1.22.119 → 1.22.121

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

@@ -1,40 +1,8 @@
-/**
- * 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 { readSession } from '../../identity/client.js';
 import { selectStorageBackendKind } from '../../storage/selection.js';
 import { loadR2Config } from './config.js';
 import { managedSessionsBaseUrl } from './managed-config.js';
-/** Env var that forces the BYO path. Value must be exactly `byo`. */
 export const SESSIONS_BACKEND_ENV = 'AGENTS_SESSIONS_BACKEND';
-/**
- * The sessions surface's BYO-override signals: an explicit `--byo`, a
- * caller-supplied static write token, or `AGENTS_SESSIONS_BACKEND=byo`. Detecting
- * WHICH signals count is surface-specific; the managed-vs-BYO decision itself is
- * the shared policy. A persisted r2.backups bundle is deliberately NOT an
- * override — a signed-in user still backs up to managed unless they opt out.
- */
 function sessionsByoOverride(opts) {
     if (opts.byo === true)
         return true;
@@ -42,20 +10,11 @@ function sessionsByoOverride(opts) {
         return true;
     return (process.env[SESSIONS_BACKEND_ENV] ?? '').trim().toLowerCase() === 'byo';
 }
-/** True when the shared policy resolves to the managed principal for sessions. */
 export function shouldUseManagedSessions(opts = {}) {
     return (selectStorageBackendKind({ byoOverride: sessionsByoOverride(opts), session: opts.session }) ===
         'managed');
 }
-/**
- * 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 function resolveSessionsBackend(opts = {}) {
-    // Resolve identity ONCE. Reading it for selection and then again for the
-    // backend creates a race where logout can flip the principal mid-preflight.
     const session = opts.session === undefined ? readSession() : opts.session;
     const explicitByo = sessionsByoOverride(opts);
     if (selectStorageBackendKind({ byoOverride: explicitByo, session }) === 'managed') {
@@ -71,14 +30,10 @@ export function resolveSessionsBackend(opts = {}) {
         }
         return { kind: 'managed', baseUrl: managedSessionsBaseUrl(), token: session.access_token, userId };
     }
-    // BYO: the existing r2.backups bundle. loadR2Config throws an actionable error
-    // when the bundle is missing or locked.
     try {
         return { kind: 'byo', r2: loadR2Config() };
     }
     catch (err) {
-        // A user who is simply signed out (not an explicit --byo) and has no bundle
-        // should hear about the zero-setup managed path FIRST, then the BYO one.
         if (!explicitByo) {
             throw new Error("Not signed in, and no r2.backups bucket is configured. Run 'agents auth login' to " +
                 'back up to the managed Phoenix store (zero setup), or add the r2.backups bundle to ' +

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

@@ -11,43 +11,16 @@
  * background sync. Credentials come from the `r2.backups` secrets bundle (OS
  * keychain on macOS, libsecret on Linux) — never from env or disk.
  */
-/** Secrets bundle holding the R2 credentials. */
 export declare const SYNC_BUNDLE = "r2.backups";
 export interface R2Config {
     accountId: string;
     bucket: string;
     accessKeyId: string;
     secretAccessKey: string;
-    /** S3-compatible endpoint for the account (no bucket, no trailing slash). */
     endpoint: string;
-    /**
-     * Shared 32-byte key (hex or base64) for client-side transcript encryption,
-     * held in the bundle as `R2_SYNC_ENC_KEY`. Optional and deliberately separate
-     * from the R2 credentials so rotating the access token never orphans already
-     * encrypted bundles. `agents sessions export --encrypt` prefers this key when
-     * present, else mints and prints an ephemeral one — see transcript-crypto.ts.
-     */
     syncEncKey?: string;
 }
-/** Drop the cached resolution so the next call reads the bundle fresh. Called on
- *  daemon SIGHUP (to pick up rotated credentials) and between tests. */
 export declare function clearR2ConfigCache(): void;
-/**
- * Resolve R2 credentials, reading the keychain at most once per process. The
- * read is `agentOnly` (resolveR2Config), so it never prompts: a `never`/no-ACL or
- * broker-held bundle resolves silently and is memoized; a locked `hold`/`always`
- * bundle throws the actionable "unlock r2.backups" error. Throws (not memoized)
- * when the bundle/keys are missing or locked — isSyncConfigured catches the throw
- * and degrades to no-transport.
- */
 export declare function loadR2Config(): R2Config;
-/**
- * True when the sync bundle exists and resolves, without throwing. A missing OR
- * locked bundle resolves to false (session-sync degrades to no-transport) and,
- * because the `agentOnly` read never prompts, it is re-checked each cycle — so a
- * later `agents secrets add` / `agents secrets unlock r2.backups` is picked up
- * promptly with no daemon restart. `now` is accepted for a stable test signature
- * but no longer gates a cooldown (there is no prompt-bearing failure to back off).
- */
 export declare function isSyncConfigured(_now?: number): boolean;
 export { machineId, normalizeHost } from '../../machine-id.js';

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

@@ -12,24 +12,8 @@
  * keychain on macOS, libsecret on Linux) — never from env or disk.
  */
 import { readAndResolveBundleEnvSync } from '../../secrets-client.js';
-/** Secrets bundle holding the R2 credentials. */
 export const SYNC_BUNDLE = 'r2.backups';
-/**
- * Resolve R2 credentials from the `r2.backups` bundle. Throws a clear,
- * actionable error if the bundle or any key is missing — sync cannot proceed
- * without real credentials (no silent fallback).
- */
 function resolveR2Config() {
-    // Session-sync is a BACKGROUND read: the daemon's ~90s cycle (and the ~2-min
-    // watchdog) resolve this on their own, never at a human's request — so it must
-    // NEVER pop a Touch ID sheet, on the interactive launcher included (SEC-13: an
-    // agent launch never raises biometry on its own). The read is always
-    // `agentOnly`: a `never`/no-ACL or broker-held `r2.backups` bundle resolves
-    // silently; a locked `hold`/`always` bundle THROWS the actionable "unlock
-    // r2.backups" message instead of prompting. isSyncConfigured catches that throw
-    // and degrades to no-transport (sync disabled) with no prompt and no crash —
-    // unlock once (`agents secrets unlock r2.backups`) or set it no-ACL
-    // (`agents secrets policy r2.backups never`) for silent zero-friction sync.
     const { env } = readAndResolveBundleEnvSync(SYNC_BUNDLE, { caller: 'session-transport', agentOnly: true });
     const accountId = env.R2_ACCOUNT_ID?.trim();
     const bucket = env.R2_BUCKET_NAME?.trim();
@@ -51,55 +35,20 @@ function resolveR2Config() {
         bucket: bucket,
         accessKeyId: accessKeyId,
         secretAccessKey: secretAccessKey,
-        // Default to the account's R2 endpoint; an explicit R2_ENDPOINT override
-        // points at any S3-compatible store (MinIO, another provider) — which is
-        // also how the feature is verified end-to-end without live R2.
         endpoint: env.R2_ENDPOINT?.trim() || `https://${accountId}.r2.cloudflarestorage.com`,
         syncEncKey,
     };
 }
-// ── Resolution cache ────────────────────────────────────────────────────────
-// The daemon calls isSyncConfigured() + syncSessions() every ~90s. The read is
-// now `agentOnly` (resolveR2Config) so it can NEVER pop Touch ID — a locked bundle
-// throws a cheap, deterministic "unlock r2.backups" error instead. We still resolve
-// at most once per process: a success is memoized for the process lifetime (cleared
-// on daemon SIGHUP via clearR2ConfigCache), so subsequent cycles never touch the
-// keychain again. A failure (absent bundle, or a LOCKED `hold`/`always` bundle) is
-// NOT memoized and never prompts, so it is re-checked each cycle — session-sync
-// degrades to no-transport until the bundle is added / unlocked, then picks it up
-// promptly with no restart.
-//
-// The historical prompt-backoff cooldown (a cancelled Touch ID sheet) is gone: with
-// agentOnly there is no sheet to cancel, so no failure is prompt-bearing and none
-// needs a backoff.
 let cachedConfig = null;
-/** Drop the cached resolution so the next call reads the bundle fresh. Called on
- *  daemon SIGHUP (to pick up rotated credentials) and between tests. */
 export function clearR2ConfigCache() {
     cachedConfig = null;
 }
-/**
- * Resolve R2 credentials, reading the keychain at most once per process. The
- * read is `agentOnly` (resolveR2Config), so it never prompts: a `never`/no-ACL or
- * broker-held bundle resolves silently and is memoized; a locked `hold`/`always`
- * bundle throws the actionable "unlock r2.backups" error. Throws (not memoized)
- * when the bundle/keys are missing or locked — isSyncConfigured catches the throw
- * and degrades to no-transport.
- */
 export function loadR2Config() {
     if (cachedConfig)
         return cachedConfig;
     cachedConfig = resolveR2Config();
     return cachedConfig;
 }
-/**
- * True when the sync bundle exists and resolves, without throwing. A missing OR
- * locked bundle resolves to false (session-sync degrades to no-transport) and,
- * because the `agentOnly` read never prompts, it is re-checked each cycle — so a
- * later `agents secrets add` / `agents secrets unlock r2.backups` is picked up
- * promptly with no daemon restart. `now` is accepted for a stable test signature
- * but no longer gates a cooldown (there is no prompt-bearing failure to back off).
- */
 export function isSyncConfigured(_now = Date.now()) {
     if (cachedConfig)
         return true;
@@ -108,12 +57,7 @@ export function isSyncConfigured(_now = Date.now()) {
         return true;
     }
     catch {
-        // Absent or locked bundle — never prompted (agentOnly), so no backoff: keep
-        // re-checking each cycle for fast pickup once the bundle is added / unlocked.
         return false;
     }
 }
-// machineId() and normalizeHost() now live in the dependency-free leaf
-// ../../machine-id.ts so low-level modules (state.ts) can use them without an
-// import cycle. Re-exported here for existing importers.
 export { machineId, normalizeHost } from '../../machine-id.js';

package/dist/lib/session/sync/managed-config.d.ts

@@ -1,21 +1,4 @@
-/**
- * Isolated Cloudflare resource choices for the managed session-backup store.
- *
- * The managed sessions backend is the Phoenix-gated, zero-setup path behind
- * `agents sessions export --to-r2` / `import --from-r2` for a signed-in user —
- * the sessions analogue of the managed `agents traces sync` store. A signed-in
- * user never has to provision their own `r2.backups` bucket; the CLI talks to
- * this already-live Worker under their Phoenix bearer.
- *
- * Mirrors `lib/traces/config.ts` + `managedTracesBaseUrl()`. The endpoint host
- * is its own subdomain (a separate Worker + bucket from traces/share), so the
- * blast radius of a bug or a quota exhaustion is one surface, not three.
- */
-/** Managed sessions Worker domain — its own subdomain, separate from traces/share. */
 export declare const DEFAULT_SESSIONS_DOMAIN = "sessions.agents-cli.sh";
-/** Cloudflare Worker name for the managed sessions deployment. */
 export declare const DEFAULT_SESSIONS_WORKER_NAME = "agents-sessions";
-/** R2 bucket name backing the managed sessions Worker. */
 export declare const DEFAULT_SESSIONS_BUCKET_NAME = "agents-sessions";
-/** Public base URL of the managed sessions Worker, no trailing slash. */
 export declare function managedSessionsBaseUrl(): string;

package/dist/lib/session/sync/managed-config.js

@@ -1,23 +1,6 @@
-/**
- * Isolated Cloudflare resource choices for the managed session-backup store.
- *
- * The managed sessions backend is the Phoenix-gated, zero-setup path behind
- * `agents sessions export --to-r2` / `import --from-r2` for a signed-in user —
- * the sessions analogue of the managed `agents traces sync` store. A signed-in
- * user never has to provision their own `r2.backups` bucket; the CLI talks to
- * this already-live Worker under their Phoenix bearer.
- *
- * Mirrors `lib/traces/config.ts` + `managedTracesBaseUrl()`. The endpoint host
- * is its own subdomain (a separate Worker + bucket from traces/share), so the
- * blast radius of a bug or a quota exhaustion is one surface, not three.
- */
-/** Managed sessions Worker domain — its own subdomain, separate from traces/share. */
 export const DEFAULT_SESSIONS_DOMAIN = 'sessions.agents-cli.sh';
-/** Cloudflare Worker name for the managed sessions deployment. */
 export const DEFAULT_SESSIONS_WORKER_NAME = 'agents-sessions';
-/** R2 bucket name backing the managed sessions Worker. */
 export const DEFAULT_SESSIONS_BUCKET_NAME = 'agents-sessions';
-/** Public base URL of the managed sessions Worker, no trailing slash. */
 export function managedSessionsBaseUrl() {
     return `https://${DEFAULT_SESSIONS_DOMAIN}`;
 }

package/dist/lib/session/sync/managed-key.d.ts

@@ -1,43 +1,5 @@
-/**
- * Managed backup encryption key (DEK) — mint, cache, escrow, recover.
- *
- * On the MANAGED path, a session backup is NEVER uploaded in plaintext. Every
- * transcript body is sealed with AES-256-GCM (the same `transcript-crypto.ts`
- * primitives BYO uses) under a 32-byte data-encryption key (DEK) minted per
- * Phoenix user.
- *
- * Where the DEK lives, and the honest trust boundary:
- *   - **Local cache** at `~/.agents/.cache/state/sessions-backup-key.json`
- *     (mode 0600), a `{ [userId]: <base64-dek> }` map so several Phoenix
- *     accounts on one box stay isolated. The Worker escrow remains authoritative.
- *   - **Escrow** at the bearer-gated Worker key `<userId>/__key/backup-dek`, so
- *     a FRESH box that signs in with the same Phoenix account recovers the DEK
- *     with zero setup and can decrypt its own prior backups.
- *
- * Trust boundary (documented honestly — SES-51):
- *   - Confidential vs a raw R2 / Cloudflare bucket read: objects at rest are
- *     ciphertext envelopes (SES-24 holds), and the DEK escrow object is itself
- *     only reachable with the owner's bearer.
- *   - NOT zero-knowledge vs Phoenix: the DEK is escrowed on Phoenix-operated
- *     infrastructure, so the operator *can* recover the key and read a backup.
- *     A user who needs a key Phoenix can never see uses BYO (`--byo`), which
- *     keeps the DEK only in their own `r2.backups` bundle — that is the
- *     zero-knowledge path.
- */
 import type { ManagedSessionsBackupClient } from './net-client.js';
-/** Worker key (relative to the `<userId>/` namespace prefix the client prepends). */
 export declare const ESCROW_REL_KEY = "__key/backup-dek";
-/** Local per-user DEK cache file — a `{ [userId]: base64 }` map, mode 0600. */
 export declare function backupKeyCachePath(): string;
-/** The DEK cached locally for this Phoenix user, or null. */
 export declare function readCachedBackupKey(userId: string): Buffer | null;
-/**
- * Resolve the managed backup DEK for `userId`, minting + escrowing one on first
- * use. NEVER returns null — the managed path must not upload plaintext.
- *
- * The escrow is authoritative. On a missing escrow, the local cache (if any) is
- * restored with a conditional create; otherwise a new key is minted. Concurrent
- * first-use devices race that create, then every loser reads the one winner
- * before encrypting anything, so no backup can be orphaned under a losing DEK.
- */
 export declare function resolveManagedBackupKey(client: ManagedSessionsBackupClient, userId: string): Promise<Buffer>;

package/dist/lib/session/sync/managed-key.js

@@ -1,38 +1,10 @@
-/**
- * Managed backup encryption key (DEK) — mint, cache, escrow, recover.
- *
- * On the MANAGED path, a session backup is NEVER uploaded in plaintext. Every
- * transcript body is sealed with AES-256-GCM (the same `transcript-crypto.ts`
- * primitives BYO uses) under a 32-byte data-encryption key (DEK) minted per
- * Phoenix user.
- *
- * Where the DEK lives, and the honest trust boundary:
- *   - **Local cache** at `~/.agents/.cache/state/sessions-backup-key.json`
- *     (mode 0600), a `{ [userId]: <base64-dek> }` map so several Phoenix
- *     accounts on one box stay isolated. The Worker escrow remains authoritative.
- *   - **Escrow** at the bearer-gated Worker key `<userId>/__key/backup-dek`, so
- *     a FRESH box that signs in with the same Phoenix account recovers the DEK
- *     with zero setup and can decrypt its own prior backups.
- *
- * Trust boundary (documented honestly — SES-51):
- *   - Confidential vs a raw R2 / Cloudflare bucket read: objects at rest are
- *     ciphertext envelopes (SES-24 holds), and the DEK escrow object is itself
- *     only reachable with the owner's bearer.
- *   - NOT zero-knowledge vs Phoenix: the DEK is escrowed on Phoenix-operated
- *     infrastructure, so the operator *can* recover the key and read a backup.
- *     A user who needs a key Phoenix can never see uses BYO (`--byo`), which
- *     keeps the DEK only in their own `r2.backups` bundle — that is the
- *     zero-knowledge path.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from '../../fs-atomic.js';
 import { getRuntimeStateDir } from '../../state.js';
 import { generateSyncEncKey } from './transcript-crypto.js';
-const KEY_LEN = 32; // AES-256
-/** Worker key (relative to the `<userId>/` namespace prefix the client prepends). */
+const KEY_LEN = 32;
 export const ESCROW_REL_KEY = '__key/backup-dek';
-/** Local per-user DEK cache file — a `{ [userId]: base64 }` map, mode 0600. */
 export function backupKeyCachePath() {
     return path.join(getRuntimeStateDir(), 'sessions-backup-key.json');
 }
@@ -53,7 +25,6 @@ function readCache() {
         return Object.create(null);
     }
 }
-/** Decode a base64/hex DEK into a 32-byte key, or null when it is malformed. */
 function decodeDek(raw) {
     const s = (raw ?? '').trim();
     if (!s)
@@ -61,11 +32,9 @@ function decodeDek(raw) {
     const key = /^[0-9a-f]{64}$/i.test(s) ? Buffer.from(s, 'hex') : Buffer.from(s, 'base64');
     return key.length === KEY_LEN ? key : null;
 }
-/** The DEK cached locally for this Phoenix user, or null. */
 export function readCachedBackupKey(userId) {
     return decodeDek(readCache()[userId]);
 }
-/** Persist a DEK (base64) for this Phoenix user in the local 0600 cache. */
 function cacheBackupKey(userId, b64) {
     const file = backupKeyCachePath();
     fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
@@ -86,19 +55,9 @@ function parseEscrow(body, expectedUserId) {
             return decodeDek(obj.dek);
     }
     catch {
-        /* not an escrow envelope */
     }
     return null;
 }
-/**
- * Resolve the managed backup DEK for `userId`, minting + escrowing one on first
- * use. NEVER returns null — the managed path must not upload plaintext.
- *
- * The escrow is authoritative. On a missing escrow, the local cache (if any) is
- * restored with a conditional create; otherwise a new key is minted. Concurrent
- * first-use devices race that create, then every loser reads the one winner
- * before encrypting anything, so no backup can be orphaned under a losing DEK.
- */
 export async function resolveManagedBackupKey(client, userId) {
     const escrowed = await client.get(ESCROW_REL_KEY);
     if (escrowed !== null) {

package/dist/lib/session/sync/net-client.d.ts

@@ -1,26 +1,3 @@
-/**
- * SessionsHttpClient — the managed transport for `agents sessions export
- * --to-r2` / `import --from-r2` when the caller is signed in to Phoenix.
- *
- * Same put / get / list / delete surface as `R2Client` (`./r2.ts`), so the
- * export/import command drives EITHER a managed HTTP client or a BYO S3 client
- * through the one shared {@link SessionsBackupClient} interface. The difference
- * is only the wire: this talks to the managed sessions Worker over `fetch` with
- * a `Authorization: Bearer <phoenix-token>` header (the same request shape as
- * `traces/sync.ts`), instead of SigV4 against R2 directly.
- *
- * The userId namespace prefix is prepended INSIDE this client
- * (`${baseUrl}/${userId}/${key}`), so the caller passes the SAME object key it
- * passes to `R2Client` (`sessions/<machine>/<agent>/<sessionId>.jsonl`). That
- * keeps the BYO object layout (SES-27a) byte-identical while the managed Worker
- * gets its required `segments[0] === userId` prefix.
- */
-/**
- * The verbs the session backup/restore path needs, satisfied by BOTH the
- * managed {@link SessionsHttpClient} and the BYO `R2Client`. `list` takes an
- * optional prefix: BYO passes the `sessions/` prefix; managed ignores it and
- * enumerates the whole owner namespace server-side.
- */
 export interface SessionsBackupClient {
     readonly kind: 'managed' | 'byo';
     put(key: string, body: string | Uint8Array, contentType?: string): Promise<void>;
@@ -28,7 +5,6 @@ export interface SessionsBackupClient {
     list(prefix?: string): Promise<string[]>;
     delete(key: string): Promise<void>;
 }
-/** Managed-only extension used to establish an immutable escrow key. */
 export interface ManagedSessionsBackupClient extends SessionsBackupClient {
     readonly kind: 'managed';
     putIfAbsent(key: string, body: string | Uint8Array, contentType?: string): Promise<boolean>;
@@ -43,23 +19,11 @@ export declare class SessionsHttpClient implements ManagedSessionsBackupClient {
         userId: string;
         token: string;
     });
-    /** `${baseUrl}/<userId>/<key>` with every path segment percent-encoded. */
     private objUrl;
     private authHeaders;
-    /** Upload an object under this owner's namespace. Overwrites unconditionally. */
     put(key: string, body: string | Uint8Array, contentType?: string): Promise<void>;
-    /** Create an object exactly once. A concurrent winner returns false. */
     putIfAbsent(key: string, body: string | Uint8Array, contentType?: string): Promise<boolean>;
-    /** Fetch an object as text, or null if it does not exist (404). */
     get(key: string): Promise<string | null>;
-    /**
-     * List this owner's object keys, each relative to the `<userId>/` prefix (so
-     * they feed straight back into `get`/`delete`). The `prefix` arg is accepted
-     * for interface parity with `R2Client` but ignored — the managed Worker
-     * enumerates the whole owner namespace and excludes the reserved `__` keys
-     * server-side.
-     */
     list(_prefix?: string): Promise<string[]>;
-    /** Delete an object (the Worker refunds its bytes to the quota ledger). */
     delete(key: string): Promise<void>;
 }

package/dist/lib/session/sync/net-client.js

@@ -1,20 +1,3 @@
-/**
- * SessionsHttpClient — the managed transport for `agents sessions export
- * --to-r2` / `import --from-r2` when the caller is signed in to Phoenix.
- *
- * Same put / get / list / delete surface as `R2Client` (`./r2.ts`), so the
- * export/import command drives EITHER a managed HTTP client or a BYO S3 client
- * through the one shared {@link SessionsBackupClient} interface. The difference
- * is only the wire: this talks to the managed sessions Worker over `fetch` with
- * a `Authorization: Bearer <phoenix-token>` header (the same request shape as
- * `traces/sync.ts`), instead of SigV4 against R2 directly.
- *
- * The userId namespace prefix is prepended INSIDE this client
- * (`${baseUrl}/${userId}/${key}`), so the caller passes the SAME object key it
- * passes to `R2Client` (`sessions/<machine>/<agent>/<sessionId>.jsonl`). That
- * keeps the BYO object layout (SES-27a) byte-identical while the managed Worker
- * gets its required `segments[0] === userId` prefix.
- */
 export class SessionsHttpClient {
     kind = 'managed';
     base;
@@ -25,7 +8,6 @@ export class SessionsHttpClient {
         this.userId = safeOwnerSegment(opts.userId);
         this.token = opts.token;
     }
-    /** `${baseUrl}/<userId>/<key>` with every path segment percent-encoded. */
     objUrl(key) {
         const rel = safeObjectKey(key).map(encodeURIComponent).join('/');
         return `${this.base}/${encodeURIComponent(this.userId)}/${rel}`;
@@ -33,7 +15,6 @@ export class SessionsHttpClient {
     authHeaders(extra = {}) {
         return { authorization: `Bearer ${this.token}`, ...extra };
     }
-    /** Upload an object under this owner's namespace. Overwrites unconditionally. */
     async put(key, body, contentType = 'application/octet-stream') {
         const res = await fetch(this.objUrl(key), {
             method: 'PUT',
@@ -43,7 +24,6 @@ export class SessionsHttpClient {
         if (!res.ok)
             throw new Error(`sessions PUT ${key} failed: ${res.status} ${await safeText(res)}`);
     }
-    /** Create an object exactly once. A concurrent winner returns false. */
     async putIfAbsent(key, body, contentType = 'application/octet-stream') {
         const res = await fetch(this.objUrl(key), {
             method: 'PUT',
@@ -57,7 +37,6 @@ export class SessionsHttpClient {
         }
         return true;
     }
-    /** Fetch an object as text, or null if it does not exist (404). */
     async get(key) {
         const res = await fetch(this.objUrl(key), { method: 'GET', headers: this.authHeaders() });
         if (res.status === 404)
@@ -66,13 +45,6 @@ export class SessionsHttpClient {
             throw new Error(`sessions GET ${key} failed: ${res.status} ${await safeText(res)}`);
         return await res.text();
     }
-    /**
-     * List this owner's object keys, each relative to the `<userId>/` prefix (so
-     * they feed straight back into `get`/`delete`). The `prefix` arg is accepted
-     * for interface parity with `R2Client` but ignored — the managed Worker
-     * enumerates the whole owner namespace and excludes the reserved `__` keys
-     * server-side.
-     */
     async list(_prefix) {
         const url = `${this.base}/${encodeURIComponent(this.userId)}/?list`;
         const res = await fetch(url, { method: 'GET', headers: this.authHeaders() });
@@ -83,7 +55,6 @@ export class SessionsHttpClient {
             return [];
         return body.keys.filter((k) => typeof k === 'string');
     }
-    /** Delete an object (the Worker refunds its bytes to the quota ledger). */
     async delete(key) {
         const res = await fetch(this.objUrl(key), { method: 'DELETE', headers: this.authHeaders() });
         if (!res.ok && res.status !== 404) {
@@ -98,7 +69,6 @@ function safeOwnerSegment(owner) {
     }
     return value;
 }
-/** Prevent URL dot-segment normalization from escaping the verified owner path. */
 function safeObjectKey(key) {
     const segments = key.split('/');
     if (segments.length === 0 ||

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

@@ -2,7 +2,6 @@ import { type CloudflareRequester } from '../../cloudflare/provision.js';
 interface ProvisionOptions {
     request?: CloudflareRequester;
 }
-/** Bind the Phoenix identity base URL used to verify every session read and write. */
 export declare function setPhoenixIdBaseSecret(apiToken: string, accountId: string, workerName: string, phoenixIdBase: string, opts?: ProvisionOptions): Promise<void>;
 export interface ProvisionSessionsOptions extends ProvisionOptions {
     apiToken: string;
@@ -12,7 +11,6 @@ export interface ProvisionSessionsOptions extends ProvisionOptions {
     phoenixIdBase: string;
     domain?: string;
 }
-/** Provision the complete isolated sessions deployment using the canonical Worker template. */
 export declare function provisionSessions(opts: ProvisionSessionsOptions): Promise<{
     baseUrl: string;
 }>;

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

@@ -1,21 +1,12 @@
-// Cloudflare orchestration for the managed session-backup store. The generic
-// request primitives live in cloudflare/provision; only the isolated sessions
-// resource choices and Worker template belong here. Mirrors lib/traces/provision.ts.
-//
-// This is the OPERATOR provisioning path — cutting the `agents-sessions` Worker +
-// bucket + custom domain once. Product traffic never runs it; a signed-in user
-// talks to the already-deployed Worker through `SessionsHttpClient`.
 import { addCustomDomain, createBucket, deployWorker, enableWorkersDev, findZoneId, putWorkerSecret, } from '../../cloudflare/provision.js';
 import { DEFAULT_SESSIONS_BUCKET_NAME, DEFAULT_SESSIONS_DOMAIN, DEFAULT_SESSIONS_WORKER_NAME, } from './managed-config.js';
 import { renderSessionsWorkerScript } from './worker-template.js';
-/** Bind the Phoenix identity base URL used to verify every session read and write. */
 export async function setPhoenixIdBaseSecret(apiToken, accountId, workerName, phoenixIdBase, opts = {}) {
     const normalized = phoenixIdBase.replace(/\/+$/, '').trim();
     if (!normalized)
         throw new Error('PHOENIX_ID_BASE is required to verify session requests.');
     await putWorkerSecret(apiToken, accountId, workerName, 'PHOENIX_ID_BASE', normalized, opts);
 }
-/** Provision the complete isolated sessions deployment using the canonical Worker template. */
 export async function provisionSessions(opts) {
     const domain = opts.domain ?? DEFAULT_SESSIONS_DOMAIN;
     const workerName = opts.workerName ?? DEFAULT_SESSIONS_WORKER_NAME;
@@ -23,10 +14,6 @@ export async function provisionSessions(opts) {
     const requestOpts = opts.request ? { request: opts.request } : {};
     await createBucket(opts.apiToken, opts.accountId, bucketName, requestOpts);
     await deployWorker(opts.apiToken, opts.accountId, workerName, renderSessionsWorkerScript(), bucketName, requestOpts);
-    // No WRITE_TOKEN secret: the managed sessions Worker is Phoenix-only (PHNX-3726).
-    // A static token would be a Phoenix-and-quota bypass with no legitimate caller —
-    // the zero-knowledge BYO path uses the user's own R2 bucket directly, never this
-    // Worker.
     await setPhoenixIdBaseSecret(opts.apiToken, opts.accountId, workerName, opts.phoenixIdBase, requestOpts);
     const workersDevSubdomain = await enableWorkersDev(opts.apiToken, opts.accountId, workerName, requestOpts);
     const zoneId = await findZoneId(opts.apiToken, domain, requestOpts);

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

@@ -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 type { R2Config } from './config.js';
 interface HeadResult {
     size: number;
@@ -20,21 +9,12 @@ export declare class R2Client {
     private base;
     constructor(cfg: R2Config);
     private url;
-    /** Upload an object. Overwrites unconditionally. */
     put(key: string, body: string | Uint8Array, contentType?: string): Promise<void>;
-    /** Fetch an object as text, or null if it does not exist (404). */
     get(key: string): Promise<string | null>;
-    /** HEAD an object for size + etag, or null if it does not exist. */
     head(key: string): Promise<HeadResult | null>;
-    /** Delete an object (no error if it is already absent). */
     delete(key: string): Promise<void>;
-    /** List immediate sub-prefixes under a prefix (delimiter '/'), e.g. machine dirs. */
     listPrefixes(prefix: string): Promise<string[]>;
-    /** 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). */
     list(prefix?: string): Promise<string[]>;
 }
-/** Single pass: sequential replaces would double-decode `&amp;lt;` into `<`. */
 export declare function decodeXml(s: string): string;
 export {};