@phnx-labs/agents-cli 1.22.70 → 1.22.71

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

@@ -0,0 +1,61 @@
+/**
+ * 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 `lib/share/backend.ts` (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';
+export type SessionsBackendKind = 'managed' | 'byo';
+/** Env var that forces the BYO path. Value must be exactly `byo`. */
+export declare const SESSIONS_BACKEND_ENV = "AGENTS_SESSIONS_BACKEND";
+export 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;
+}
+export interface ByoSessionsBackend {
+    kind: 'byo';
+    /** The resolved r2.backups credentials for the S3-compatible client. */
+    r2: R2Config;
+}
+export type SessionsBackend = ManagedSessionsBackend | ByoSessionsBackend;
+export 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;

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

@@ -0,0 +1,89 @@
+/**
+ * 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 `lib/share/backend.ts` (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;
+    if (opts.writeToken)
+        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') {
+        if (!session) {
+            throw new Error("Not signed in. Run 'agents auth login' to back up sessions to your Phoenix account.");
+        }
+        if (!session.access_token) {
+            throw new Error("Session has no access token. Run 'agents auth login' again.");
+        }
+        const userId = (session.userId ?? '').trim();
+        if (!userId) {
+            throw new Error("Signed in but the session has no user id. Run 'agents auth login' again.");
+        }
+        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 ' +
+                'use your own bucket: agents secrets add r2.backups R2_ACCOUNT_ID R2_BUCKET_NAME R2_ACCESS_KEY_ID R2_SECRET_ACCESS_KEY');
+        }
+        throw err;
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 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";
+/** Isolated Cloudflare resources for the managed session-backup store. */
+export interface SessionsConfig {
+    baseUrl: string;
+    accountId: string;
+    workerName: string;
+    bucketName: string;
+    domain?: string;
+}
+/** Public base URL of the managed sessions Worker, no trailing slash. */
+export declare function managedSessionsBaseUrl(): string;

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

@@ -0,0 +1,23 @@
+/**
+ * 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

@@ -0,0 +1,45 @@
+/**
+ * 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;
+/** Persist a DEK (base64) for this Phoenix user in the local 0600 cache. */
+export declare function cacheBackupKey(userId: string, b64: string): void;
+/**
+ * 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

@@ -0,0 +1,128 @@
+/**
+ * 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). */
+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');
+}
+function readCache() {
+    try {
+        const raw = fs.readFileSync(backupKeyCachePath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        const cache = Object.create(null);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return cache;
+        for (const [userId, value] of Object.entries(parsed)) {
+            if (typeof value === 'string')
+                cache[userId] = value;
+        }
+        return cache;
+    }
+    catch {
+        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)
+        return null;
+    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. */
+export function cacheBackupKey(userId, b64) {
+    const file = backupKeyCachePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    ensureLockTarget(file, '{}', 0o700);
+    fs.chmodSync(file, 0o600);
+    withFileLock(file, () => {
+        const cache = readCache();
+        cache[userId] = b64;
+        atomicWriteFileSync(file, JSON.stringify(cache, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        fs.chmodSync(file, 0o600);
+    });
+}
+function parseEscrow(body, expectedUserId) {
+    try {
+        const obj = JSON.parse(body);
+        if (obj && obj.v === 1 && obj.userId === expectedUserId &&
+            typeof obj.dek === 'string')
+            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) {
+        const key = parseEscrow(escrowed, userId);
+        if (key) {
+            cacheBackupKey(userId, key.toString('base64'));
+            return key;
+        }
+        throw new Error('Managed session backup key escrow is corrupt or belongs to another account; ' +
+            'refusing to replace it because that would orphan existing encrypted backups.');
+    }
+    const cached = readCachedBackupKey(userId);
+    const b64 = cached?.toString('base64') ?? generateSyncEncKey();
+    const envelope = { v: 1, userId, dek: b64 };
+    const created = await client.putIfAbsent(ESCROW_REL_KEY, JSON.stringify(envelope), 'application/json');
+    if (created) {
+        cacheBackupKey(userId, b64);
+        return Buffer.from(b64, 'base64');
+    }
+    const winnerBody = await client.get(ESCROW_REL_KEY);
+    const winner = winnerBody === null ? null : parseEscrow(winnerBody, userId);
+    if (!winner) {
+        throw new Error('Managed session backup key escrow was contended but no valid winning key could be recovered.');
+    }
+    cacheBackupKey(userId, winner.toString('base64'));
+    return winner;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * 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>;
+    get(key: string): Promise<string | null>;
+    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>;
+}
+export declare class SessionsHttpClient implements ManagedSessionsBackupClient {
+    readonly kind: "managed";
+    private base;
+    private userId;
+    private token;
+    constructor(opts: {
+        baseUrl: string;
+        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

@@ -0,0 +1,117 @@
+/**
+ * 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;
+    userId;
+    token;
+    constructor(opts) {
+        this.base = opts.baseUrl.replace(/\/+$/, '');
+        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}`;
+    }
+    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',
+            headers: this.authHeaders({ 'content-type': contentType }),
+            body,
+        });
+        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',
+            headers: this.authHeaders({ 'content-type': contentType, 'if-none-match': '*' }),
+            body,
+        });
+        if (res.status === 409)
+            return false;
+        if (!res.ok) {
+            throw new Error(`sessions PUT-IF-ABSENT ${key} failed: ${res.status} ${await safeText(res)}`);
+        }
+        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)
+            return null;
+        if (!res.ok)
+            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() });
+        if (!res.ok)
+            throw new Error(`sessions LIST failed: ${res.status} ${await safeText(res)}`);
+        const body = (await res.json());
+        if (!body || !Array.isArray(body.keys))
+            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) {
+            throw new Error(`sessions DELETE ${key} failed: ${res.status} ${await safeText(res)}`);
+        }
+    }
+}
+function safeOwnerSegment(owner) {
+    const value = owner.trim();
+    if (!value || value === '.' || value === '..' || value.includes('/')) {
+        throw new Error(`Invalid managed sessions user id: ${JSON.stringify(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 ||
+        segments.some(segment => !segment || segment === '.' || segment === '..')) {
+        throw new Error(`Invalid managed sessions object key: ${JSON.stringify(key)}`);
+    }
+    return segments;
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 200);
+    }
+    catch {
+        return '';
+    }
+}

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

@@ -0,0 +1,19 @@
+import { type CloudflareRequester } from '../../share/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;
+    accountId: string;
+    workerName?: string;
+    bucketName?: string;
+    phoenixIdBase: string;
+    domain?: string;
+}
+/** Provision the complete isolated sessions deployment using the canonical Worker template. */
+export declare function provisionSessions(opts: ProvisionSessionsOptions): Promise<{
+    baseUrl: string;
+}>;
+export {};

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

@@ -0,0 +1,38 @@
+// Cloudflare orchestration for the managed session-backup store. The generic
+// request primitives live in share/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 '../../share/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;
+    const bucketName = opts.bucketName ?? DEFAULT_SESSIONS_BUCKET_NAME;
+    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);
+    if (!zoneId) {
+        return { baseUrl: `https://${workerName}.${workersDevSubdomain}.workers.dev` };
+    }
+    await addCustomDomain(opts.apiToken, opts.accountId, workerName, zoneId, domain, requestOpts);
+    return { baseUrl: `https://${domain}` };
+}

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

@@ -15,6 +15,7 @@ export interface HeadResult {
     etag: string;
 }
 export declare class R2Client {
+    readonly kind: "byo";
     private aws;
     private base;
     constructor(cfg: R2Config);
@@ -29,6 +30,8 @@ export declare class R2Client {
     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). */
-    list(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[]>;
 }

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

@@ -11,6 +11,7 @@
  */
 import { AwsClient } from 'aws4fetch';
 export class R2Client {
+    kind = 'byo';
     aws;
     base;
     constructor(cfg) {
@@ -84,8 +85,10 @@ export class R2Client {
         } while (token);
         return prefixes;
     }
-    /** List all object keys under a prefix (handles pagination). */
-    async list(prefix) {
+    /** 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;
         do {