@phnx-labs/agents-cli 1.22.69 → 1.22.71

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 {

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

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