@phnx-labs/agents-cli 1.22.114 → 1.22.115

package/dist/lib/browser/runtime-state.d.ts

@@ -144,10 +144,59 @@ export declare function listAllProfileSnapshots(): ProfileSnapshot[];
  * alone — we'd rather leak than wrongly kill a user-owned process that
  * happens to share metadata.
  */
+/**
+ * Clean up what a DEAD daemon genuinely left behind — which is not the browser.
+ *
+ * A live local browser outliving its daemon is the NORMAL case, not an orphan.
+ * `BrowserService.shutdown` deliberately closes only CDP and leaves the browser
+ * running, and on macOS the spawn is detached so the daemon's own positive-pid
+ * `killTree` reaches the daemon alone. This reaper used to read "the recorded
+ * `daemonPid` has exited" as "everything it recorded is garbage" and SIGTERM the
+ * browser — so replacing the daemon (a menubar activation, an upgrade, a crash
+ * restart) killed a browser the user was looking at, and `clearProfileRuntime`
+ * then removed the `port`/meta that {@link readProfileRuntime} needs, so even a
+ * survivor could not be re-attached and a second browser would launch beside it.
+ *
+ * The three cases are now decided independently:
+ *
+ * - **A live local browser/electron is preserved untouched** — not signalled, not
+ *   cleared, and its `daemonPid` deliberately NOT rewritten. Ownership is adopted
+ *   only after an identity-checked attach succeeds (`adoptProfileRuntimeOwner`,
+ *   called from the reuse branch in `BrowserService.connectProfile`), so nothing
+ *   claims a browser it has not proven it can talk to. Re-running this is a no-op.
+ * - **A dead browser record is cleared**, with no signal sent: there is nothing
+ *   alive to signal, and the stale pid/port would otherwise mislead the next
+ *   attach.
+ * - **A stale tunnel IS reaped.** A local `ssh -L` cannot outlive its purpose, so
+ *   a dead owner does make it an orphan. This is the one thing the old code was
+ *   right about; it just shared a code path with the browser.
+ *
+ * The accepted trade: a genuinely leaked browser from a long-dead daemon is no
+ * longer force-killed here. Idle/abandoned cleanup has its own owner in
+ * `browser/hygiene.ts` (session-dead + idle), which the daemon's periodic tick and
+ * `agents browser prune` both call — that is the right place for it, because it can
+ * tell "idle and abandoned" from "in use right now" and this function cannot.
+ */
 export declare function reapOrphanedProcesses(): {
     reaped: number;
     details: string[];
 };
+/**
+ * Take ownership of a runtime record after an identity-checked attach succeeded.
+ *
+ * Called from the reuse branch in `BrowserService.connectProfile`, which has just
+ * probed `/json/version` and run `verifyBrowserIdentity` against the profile's
+ * expected browser family — so by this point the process on the recorded port is
+ * proven to be ours. Only then may a new service claim it.
+ *
+ * Rewrites `daemonPid` ALONE. Every other field — `pid`, `port`, `command`,
+ * `userDataDir`, `spawnedAt`, `kind`, `tunnelPid` — is the original launch's
+ * metadata and stays exactly as recorded: this is an ownership handover, not a
+ * re-registration, and rewriting the rest would lose the provenance the reaper and
+ * the hygiene pass both read. A record that has since disappeared is left alone
+ * rather than recreated from a partial view.
+ */
+export declare function adoptProfileRuntimeOwner(profileName: string, daemonPid?: number): boolean;
 /**
  * True when ANY cache dir belonging to this profile still has a live browser or
  * SSH tunnel, or an open task. The composite naming (`<name>@<endpoint>`) means
@@ -233,4 +282,10 @@ export declare function buildProfilePrunePlan(): Promise<PrunePlan>;
  * went, matching what `--dry-run` printed.
  */
 export declare function pruneProfiles(plan: PrunePlan): Promise<PrunePlan>;
+/**
+ * The executable/image name the live `pid` is running, or null if it can't be
+ * determined. The process-listing API differs per OS: Windows has no `ps`, so
+ * we query `tasklist` (CSV image name in column 1); POSIX uses `ps -o comm=`.
+ */
+export declare function liveProcessCommand(pid: number): string | null;
 export {};

package/dist/lib/browser/runtime-state.js

@@ -258,6 +258,39 @@ function readTaskCount(dir) {
  * alone — we'd rather leak than wrongly kill a user-owned process that
  * happens to share metadata.
  */
+/**
+ * Clean up what a DEAD daemon genuinely left behind — which is not the browser.
+ *
+ * A live local browser outliving its daemon is the NORMAL case, not an orphan.
+ * `BrowserService.shutdown` deliberately closes only CDP and leaves the browser
+ * running, and on macOS the spawn is detached so the daemon's own positive-pid
+ * `killTree` reaches the daemon alone. This reaper used to read "the recorded
+ * `daemonPid` has exited" as "everything it recorded is garbage" and SIGTERM the
+ * browser — so replacing the daemon (a menubar activation, an upgrade, a crash
+ * restart) killed a browser the user was looking at, and `clearProfileRuntime`
+ * then removed the `port`/meta that {@link readProfileRuntime} needs, so even a
+ * survivor could not be re-attached and a second browser would launch beside it.
+ *
+ * The three cases are now decided independently:
+ *
+ * - **A live local browser/electron is preserved untouched** — not signalled, not
+ *   cleared, and its `daemonPid` deliberately NOT rewritten. Ownership is adopted
+ *   only after an identity-checked attach succeeds (`adoptProfileRuntimeOwner`,
+ *   called from the reuse branch in `BrowserService.connectProfile`), so nothing
+ *   claims a browser it has not proven it can talk to. Re-running this is a no-op.
+ * - **A dead browser record is cleared**, with no signal sent: there is nothing
+ *   alive to signal, and the stale pid/port would otherwise mislead the next
+ *   attach.
+ * - **A stale tunnel IS reaped.** A local `ssh -L` cannot outlive its purpose, so
+ *   a dead owner does make it an orphan. This is the one thing the old code was
+ *   right about; it just shared a code path with the browser.
+ *
+ * The accepted trade: a genuinely leaked browser from a long-dead daemon is no
+ * longer force-killed here. Idle/abandoned cleanup has its own owner in
+ * `browser/hygiene.ts` (session-dead + idle), which the daemon's periodic tick and
+ * `agents browser prune` both call — that is the right place for it, because it can
+ * tell "idle and abandoned" from "in use right now" and this function cannot.
+ */
 export function reapOrphanedProcesses() {
     const root = getBrowserRuntimeDir();
     if (!fs.existsSync(root))
@@ -275,28 +308,76 @@ export function reapOrphanedProcesses() {
         // Owning daemon still alive — leave its kids alone.
         if (isProcessAlive(meta.daemonPid))
             continue;
-        // Kill what the dead daemon left behind. Best-effort.
-        const kill = (pid, label) => {
-            if (!pid || pid === 0)
-                return;
-            // Only kill if it matches the recorded command — guards against
-            // pid reuse handing us an unrelated process to murder.
-            if (meta.command && !matchesCommand(pid, meta.command) &&
-                !matchesCommand(pid, 'ssh'))
-                return;
-            try {
-                process.kill(pid, 'SIGTERM');
-                reaped++;
-                details.push(`reaped ${label ?? 'pid'} ${pid} (profile ${profileName})`);
+        // A local `ssh -L` whose owner is gone is genuinely orphaned: nothing is
+        // driving it and it cannot be re-adopted, so it is the one process to signal.
+        // Matched against the recorded command (or `ssh`) so a recycled pid is not
+        // mistaken for our tunnel.
+        if (meta.tunnelPid && meta.tunnelPid !== 0) {
+            const cmdOk = !meta.command
+                || matchesCommand(meta.tunnelPid, meta.command)
+                || matchesCommand(meta.tunnelPid, 'ssh');
+            if (cmdOk) {
+                try {
+                    process.kill(meta.tunnelPid, 'SIGTERM');
+                    reaped++;
+                    details.push(`reaped tunnel ${meta.tunnelPid} (profile ${profileName})`);
+                }
+                catch { /* already gone */ }
             }
-            catch { /* already gone */ }
-        };
-        kill(meta.pid, 'browser');
-        kill(meta.tunnelPid, 'tunnel');
+        }
+        // A tunnel-kind record has no local browser of its own, so clearing it is the
+        // whole cleanup. `pid` on such a record is the REMOTE browser (normally 0) and
+        // is never ours to signal.
+        if (meta.kind === 'tunnel') {
+            clearProfileRuntime(profileName);
+            continue;
+        }
+        // `isProcessAlive` re-checks the recorded command, so a recycled pid does not
+        // read as our browser. A record with no pid at all is stale by definition.
+        const liveBrowser = !!meta.pid && meta.pid !== 0 && isProcessAlive(meta.pid, meta.command);
+        if (liveBrowser) {
+            details.push(`preserved live browser ${meta.pid} (profile ${profileName})`);
+            continue;
+        }
+        // Dead browser: clear the stale record. No signal — there is nothing there.
         clearProfileRuntime(profileName);
+        if (meta.pid)
+            details.push(`cleared dead browser record ${meta.pid} (profile ${profileName})`);
     }
     return { reaped, details };
 }
+/**
+ * Take ownership of a runtime record after an identity-checked attach succeeded.
+ *
+ * Called from the reuse branch in `BrowserService.connectProfile`, which has just
+ * probed `/json/version` and run `verifyBrowserIdentity` against the profile's
+ * expected browser family — so by this point the process on the recorded port is
+ * proven to be ours. Only then may a new service claim it.
+ *
+ * Rewrites `daemonPid` ALONE. Every other field — `pid`, `port`, `command`,
+ * `userDataDir`, `spawnedAt`, `kind`, `tunnelPid` — is the original launch's
+ * metadata and stays exactly as recorded: this is an ownership handover, not a
+ * re-registration, and rewriting the rest would lose the provenance the reaper and
+ * the hygiene pass both read. A record that has since disappeared is left alone
+ * rather than recreated from a partial view.
+ */
+export function adoptProfileRuntimeOwner(profileName, daemonPid = process.pid) {
+    const meta = readProfileRuntimeMeta(profileName);
+    if (!meta)
+        return false;
+    if (meta.daemonPid === daemonPid)
+        return true;
+    const dir = getProfileRuntimeDir(profileName);
+    try {
+        fs.writeFileSync(path.join(dir, META_FILE), JSON.stringify({ ...meta, daemonPid }));
+        return true;
+    }
+    catch {
+        // Losing the handover is not worth failing an otherwise good attach; the next
+        // startup simply preserves the browser again and re-attaches.
+        return false;
+    }
+}
 /**
  * True when ANY cache dir belonging to this profile still has a live browser or
  * SSH tunnel, or an open task. The composite naming (`<name>@<endpoint>`) means
@@ -478,7 +559,7 @@ function matchesCommand(pid, expectedCommand) {
  * determined. The process-listing API differs per OS: Windows has no `ps`, so
  * we query `tasklist` (CSV image name in column 1); POSIX uses `ps -o comm=`.
  */
-function liveProcessCommand(pid) {
+export function liveProcessCommand(pid) {
     try {
         if (process.platform === 'win32') {
             const out = execFileSync('tasklist', ['/FI', `PID eq ${pid}`, '/NH', '/FO', 'CSV'], {

package/dist/lib/browser/service.js

@@ -8,7 +8,7 @@ import { assertRemoteControlAllowedForRequest } from './remote-control.js';
 import { connectLocal } from './drivers/local.js';
 import { connectSSH, shellQuote } from './drivers/ssh.js';
 import { adoptLegacyRuntimeIfLocal, isLegacyEndpointKey, resolveBrowserTarget, shouldForkProfile, } from './resolve-target.js';
-import { clearProfileRuntime, listProfileCacheDirs, readProfileRuntimeMeta, isProcessAlive } from './runtime-state.js';
+import { adoptProfileRuntimeOwner, clearProfileRuntime, listProfileCacheDirs, readProfileRuntimeMeta, isProcessAlive } from './runtime-state.js';
 import { resolveDomainSkill } from './domain-skills.js';
 import { generateTaskId, generateShortId, asConnectionKey, parseConnectionKey, keyBelongsToProfile, } from './types.js';
 import { reapAbandonedTasks, resolveLiveIdentities, taskOwnerIsGone, } from './hygiene.js';
@@ -1212,6 +1212,8 @@ export class BrowserService {
             await this.saveTaskState(task.profile, conn.tasks);
             return { tabId: resolvedTabId };
         }
+        requireCdp(conn, 'enumerate');
+        await conn.cdp.send('Target.activateTarget', { targetId: task.tabs[resolvedTabId] });
         task.currentTabId = resolvedTabId;
         await this.saveTaskState(task.profile, conn.tasks);
         return { tabId: resolvedTabId };
@@ -2771,6 +2773,12 @@ export class BrowserService {
                 await cdp.connect(wsUrl);
                 await this.enableDomains(cdp);
                 const tasks = this.loadTaskState(key);
+                // The attach is now PROVEN: the stored port answered /json/version and
+                // `verifyBrowserIdentity` matched the profile's browser family. Only here
+                // may this service claim a browser the startup reaper deliberately left
+                // alone — it rewrites `daemonPid` only, keeping the original launch's
+                // metadata. An ambiguous identity throws above and adopts nothing.
+                adoptProfileRuntimeOwner(key);
                 return {
                     backend: 'cdp',
                     cdp,
@@ -3398,6 +3406,10 @@ export class BrowserService {
             const port = parseEndpointUrl(resolved.target)?.port ?? 9600;
             try {
                 const ff = await connectFirefox(profile, key, port, { profileDir: profile.userDataDir });
+                // A served port that accepted a fresh BiDi session is this profile's own
+                // Firefox, so claim the record for this daemon (see the local-CDP claim
+                // below for why adoption waits for a proven attach).
+                adoptProfileRuntimeOwner(key);
                 const tasks = this.loadTaskState(key);
                 for (const [k, t] of diskTasks) {
                     if (!tasks.has(k))
@@ -3476,6 +3488,14 @@ export class BrowserService {
             const cdp = new CDPClient();
             await cdp.connect(wsUrl);
             await this.enableDomains(cdp);
+            // This is the path a replacement daemon takes to recover a browser its
+            // predecessor launched, so it is where ownership actually transfers. Only
+            // now — after `verifyBrowserIdentity` confirmed the browser family on the
+            // recorded port and CDP is attached — is it proven that this record
+            // describes a browser we are driving. `adoptProfileRuntimeOwner` rewrites
+            // `daemonPid` alone; an ambiguous identity throws above and adopts
+            // nothing, leaving the record (and the browser) untouched.
+            adoptProfileRuntimeOwner(key);
             const tasks = this.loadTaskState(key);
             for (const [k, t] of diskTasks) {
                 if (!tasks.has(k))

package/dist/lib/cli-resources.js

@@ -23,6 +23,7 @@ import * as yaml from 'yaml';
 import { listResources, resolveResource } from './resources.js';
 import { probeCapture } from './probe.js';
 import { composeWin32CommandLine } from './platform/index.js';
+import { execFileShellSpec } from './platform/exec.js';
 import { localBinDir } from './platform/posixpath.js';
 // ─── Validation primitives ───────────────────────────────────────────────────
 /** Token allowed inside `check:` strings — letters, digits, underscore, dot, slash, dash. */
@@ -457,7 +458,8 @@ export function buildInstallCommand(method) {
 function runInstallMethod(method) {
     if ('npm' in method) {
         assertNpmPackage(method.npm);
-        const r = spawnSync('npm', ['install', '-g', method.npm], { stdio: 'inherit' });
+        const invocation = execFileShellSpec('npm', ['install', '-g', method.npm]);
+        const r = spawnSync(invocation.command, invocation.args, { stdio: 'inherit', shell: invocation.shell });
         if (r.status !== 0) {
             throw new Error(`npm install -g ${method.npm} exited with status ${r.status ?? 'unknown'}`);
         }

package/dist/lib/cloud/dispatch.js

@@ -16,7 +16,7 @@ import { insertTask, updateTaskStatus } from './store.js';
 import { renderStream } from './stream.js';
 import { MissingTargetError, MAX_IMAGES_PER_DISPATCH } from './types.js';
 import { emit } from '../feed/events.js';
-import { shareRuntimeEnv } from '../share/config.js';
+import { shareRuntimeEnv } from '../share-runtime.js';
 /** Map a supported image file extension to its wire mimeType. Rejects anything else. */
 function imageMimeFromPath(file) {
     const ext = path.extname(file).toLowerCase();

package/dist/lib/cloudflare/creds.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_CF_BUNDLE = "cloudflare";
+/** Cloudflare API credentials for provisioning, read from `cloudflare` (or a
+ * user-named bundle). Fuzzy-matches key names so it works across bundle layouts. */
+export declare function readCloudflareCreds(bundle?: string, override?: {
+    apiToken?: string;
+    accountId?: string;
+}): {
+    apiToken: string;
+    accountId: string;
+};

package/dist/lib/cloudflare/creds.js

@@ -0,0 +1,46 @@
+// Cloudflare API credential glue, shared by the commands that provision or read
+// Cloudflare-backed endpoints (`agents traces`, `agents sessions backup`).
+//
+// This used to live in `lib/share/config.ts` alongside the embedded artifact
+// share engine. The share engine moved out to `@phnx-labs/artifacts-cli`
+// (PHNX-3992); `readCloudflareCreds` stayed because it is a generic Cloudflare
+// util that `traces`/`sessions backup` borrow, unrelated to sharing.
+import { bundleExistsSync as bundleExists, readAndResolveBundleEnvSync as readAndResolveBundleEnv, } from '../secrets-client.js';
+export const DEFAULT_CF_BUNDLE = 'cloudflare';
+/** Cloudflare API credentials for provisioning, read from `cloudflare` (or a
+ * user-named bundle). Fuzzy-matches key names so it works across bundle layouts. */
+export function readCloudflareCreds(bundle = DEFAULT_CF_BUNDLE, override) {
+    // Explicit --token/--account bypass the bundle entirely (robust escape hatch).
+    if (override?.apiToken) {
+        return { apiToken: override.apiToken, accountId: override.accountId ?? '' };
+    }
+    // Check existence first: resolving a missing bundle through the process client
+    // surfaces an opaque transport code (e.g. LOCKED), never naming the bundle the
+    // user typed — so name it here.
+    if (!bundleExists(bundle)) {
+        throw new Error(`The '${bundle}' bundle does not exist. ` +
+            `Pass credentials directly with --token <t> [--account <id>], or create it: ` +
+            `agents secrets add ${bundle} CLOUDFLARE_API_TOKEN`);
+    }
+    const { env } = readAndResolveBundleEnv(bundle, {
+        caller: 'cloudflare',
+        // Setup is still a read; only `agents secrets unlock` may authenticate.
+        agentOnly: true,
+    });
+    const find = (re) => {
+        for (const [k, v] of Object.entries(env))
+            if (re.test(k) && v)
+                return v;
+        return '';
+    };
+    const apiToken = env.CLOUDFLARE_API_TOKEN || env.CF_API_TOKEN || find(/API[_-]?TOKEN|(?:^|_)TOKEN$/i);
+    const accountId = override?.accountId || env.CLOUDFLARE_ACCOUNT_ID || env.CF_ACCOUNT_ID || find(/ACCOUNT[_-]?ID/i);
+    if (!apiToken) {
+        const keys = Object.keys(env);
+        throw new Error(`No Cloudflare API token in the '${bundle}' bundle ` +
+            `(keys present: ${keys.length ? keys.join(', ') : 'none'}). ` +
+            `Pass it directly with --token <t> [--account <id>], or add it: ` +
+            `agents secrets add ${bundle} CLOUDFLARE_API_TOKEN`);
+    }
+    return { apiToken, accountId };
+}

package/dist/lib/cloudflare/provision.d.ts

@@ -0,0 +1,35 @@
+/** One compiled non-JS Worker module (e.g. WASM) uploaded alongside the script. */
+export interface WorkerModule {
+    name: string;
+    contentType: string;
+    contents: Uint8Array<ArrayBuffer>;
+}
+/** A Worker script plus any extra modules to upload with it. */
+export interface WorkerBundle {
+    script: string;
+    modules: WorkerModule[];
+}
+export interface CloudflareRequest {
+    apiToken: string;
+    method: string;
+    pathname: string;
+    body?: unknown;
+    form?: FormData;
+}
+export type CloudflareRequester = <T = unknown>(request: CloudflareRequest) => Promise<T>;
+interface ProvisionOptions {
+    request?: CloudflareRequester;
+}
+/** Create the R2 bucket (idempotent). */
+export declare function createBucket(apiToken: string, accountId: string, name: string, opts?: ProvisionOptions): Promise<void>;
+/** Upload the module Worker with an R2 binding (`BUCKET`). Secrets are set via the Workers Secrets API. */
+export declare function deployWorker(apiToken: string, accountId: string, workerName: string, worker: string | WorkerBundle, bucketName: string, opts?: ProvisionOptions): Promise<void>;
+/** Add/update a secret_text binding using Cloudflare's Workers Secrets API. */
+export declare function putWorkerSecret(apiToken: string, accountId: string, workerName: string, name: string, text: string, opts?: ProvisionOptions): Promise<void>;
+/** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */
+export declare function enableWorkersDev(apiToken: string, accountId: string, workerName: string, opts?: ProvisionOptions): Promise<string>;
+/** Resolve a zone id for a domain the token can see, or null if not owned/visible. */
+export declare function findZoneId(apiToken: string, domain: string, opts?: ProvisionOptions): Promise<string | null>;
+/** Map a custom hostname (e.g. `share.getrush.ai`) to the Worker via Workers Custom Domains. */
+export declare function addCustomDomain(apiToken: string, accountId: string, workerName: string, zoneId: string, hostname: string, opts?: ProvisionOptions): Promise<void>;
+export {};

package/dist/lib/cloudflare/provision.js

@@ -0,0 +1,144 @@
+// Generic Cloudflare orchestration — plain `fetch` against the CF REST API (the
+// repo has no CF wrapper). Create an R2 bucket, upload a module Worker with an R2
+// binding, set secrets via the Workers Secrets API, enable the free
+// `*.workers.dev` subdomain, and map a custom domain when the token owns the zone.
+//
+// This was `lib/share/provision.ts`. The artifact share engine moved out to
+// `@phnx-labs/artifacts-cli` (PHNX-3992), but `agents traces` provisions its own
+// isolated Cloudflare-backed store with the SAME primitives — so the generic
+// layer relocated here (share-specific lifecycle/collab/managed helpers left
+// with the share engine). `traces/provision.ts` is now the only consumer.
+const CF_API = 'https://api.cloudflare.com/client/v4';
+async function cf(apiToken, method, pathname, body, form) {
+    const headers = { authorization: `Bearer ${apiToken}` };
+    let payload;
+    if (form) {
+        payload = form; // fetch sets multipart boundary
+    }
+    else if (body !== undefined) {
+        headers['content-type'] = 'application/json';
+        payload = JSON.stringify(body);
+    }
+    const res = await fetch(`${CF_API}${pathname}`, { method, headers, body: payload });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok || json.success === false) {
+        const msg = (json.errors ?? []).map((e) => `${e.code ?? ''} ${e.message ?? ''}`.trim()).join('; ') ||
+            res.statusText;
+        throw new Error(`Cloudflare ${method} ${pathname} failed (${res.status}): ${msg}`);
+    }
+    return json.result;
+}
+const defaultCloudflareRequester = (request) => cf(request.apiToken, request.method, request.pathname, request.body, request.form);
+/** True if the CF error looks like "the thing already exists" (idempotent create). */
+function isAlreadyExists(e) {
+    return /already exists|duplicate|10004|10014/i.test(String(e));
+}
+/** Create the R2 bucket (idempotent). */
+export async function createBucket(apiToken, accountId, name, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
+    try {
+        await request({
+            apiToken,
+            method: 'POST',
+            pathname: `/accounts/${accountId}/r2/buckets`,
+            body: { name },
+        });
+    }
+    catch (e) {
+        if (!isAlreadyExists(e))
+            throw e;
+    }
+}
+/** Upload the module Worker with an R2 binding (`BUCKET`). Secrets are set via the Workers Secrets API. */
+export async function deployWorker(apiToken, accountId, workerName, worker, bucketName, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
+    const metadata = {
+        main_module: 'worker.js',
+        compatibility_date: '2024-11-06',
+        bindings: [
+            { type: 'r2_bucket', name: 'BUCKET', bucket_name: bucketName },
+        ],
+    };
+    const form = new FormData();
+    form.set('metadata', new Blob([JSON.stringify(metadata)], { type: 'application/json' }));
+    const bundle = typeof worker === 'string' ? { script: worker, modules: [] } : worker;
+    form.set('worker.js', new Blob([bundle.script], { type: 'application/javascript+module' }), 'worker.js');
+    for (const module of bundle.modules) {
+        form.set(module.name, new Blob([module.contents], { type: module.contentType }), module.name);
+    }
+    await request({
+        apiToken,
+        method: 'PUT',
+        pathname: `/accounts/${accountId}/workers/scripts/${workerName}`,
+        form,
+    });
+}
+/** Add/update a secret_text binding using Cloudflare's Workers Secrets API. */
+export async function putWorkerSecret(apiToken, accountId, workerName, name, text, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
+    await request({
+        apiToken,
+        method: 'PUT',
+        pathname: `/accounts/${accountId}/workers/scripts/${workerName}/secrets`,
+        body: { name, text, type: 'secret_text' },
+    });
+}
+/** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */
+export async function enableWorkersDev(apiToken, accountId, workerName, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
+    await request({
+        apiToken,
+        method: 'POST',
+        pathname: `/accounts/${accountId}/workers/scripts/${workerName}/subdomain`,
+        body: {
+            enabled: true,
+            previews_enabled: false,
+        },
+    });
+    const sub = await request({
+        apiToken,
+        method: 'GET',
+        pathname: `/accounts/${accountId}/workers/subdomain`,
+    });
+    if (!sub?.subdomain) {
+        throw new Error('No workers.dev subdomain on this account yet — register one at dash.cloudflare.com → Workers → Subdomain, then re-run.');
+    }
+    return sub.subdomain;
+}
+/** Resolve a zone id for a domain the token can see, or null if not owned/visible. */
+export async function findZoneId(apiToken, domain, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
+    // Try the exact name, then the registrable parent (share.getrush.ai -> getrush.ai).
+    const candidates = [domain, domain.split('.').slice(-2).join('.')];
+    for (const name of candidates) {
+        const zones = await request({
+            apiToken,
+            method: 'GET',
+            pathname: `/zones?name=${encodeURIComponent(name)}`,
+        }).catch(() => []);
+        if (zones?.length)
+            return zones[0].id;
+    }
+    return null;
+}
+/** Map a custom hostname (e.g. `share.getrush.ai`) to the Worker via Workers Custom Domains. */
+export async function addCustomDomain(apiToken, accountId, workerName, zoneId, hostname, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
+    try {
+        await request({
+            apiToken,
+            method: 'PUT',
+            pathname: `/accounts/${accountId}/workers/domains`,
+            body: {
+                zone_id: zoneId,
+                hostname,
+                service: workerName,
+                environment: 'production',
+            },
+        });
+    }
+    catch (e) {
+        if (!isAlreadyExists(e))
+            throw e;
+    }
+}

package/dist/lib/computer/sessions-list.d.ts

@@ -26,7 +26,61 @@ export interface ComputerAction {
     agent?: string;
     machineId?: string;
     hostname?: string;
+    /**
+     * The file a successful `screenshot` action actually wrote.
+     *
+     * Recorded by the standalone engine only AFTER the write succeeded, so its
+     * presence is proof the file existed — which is why nothing here ever derives
+     * a path from the verb. An action from before the producer carried this field
+     * has no capture, and that is reported honestly as none rather than guessed at
+     * from an output flag that may never have been written.
+     */
+    capture?: {
+        path: string;
+        kind: 'screenshot';
+        name: string;
+        bytes?: number;
+    };
 }
+/**
+ * The standalone engine's OWN action ledger.
+ *
+ * `agents computer` is a thin consumer of the standalone `computer` engine
+ * (PHNX-4075), and that engine ALWAYS appends every action it performs to
+ * `<cache>/computer/actions/<day>.jsonl` — independently of whether agents-cli
+ * was in the call at all. So a `computer` command the operator ran directly
+ * appears ONLY here: it never reached `recordComputerAction`, so it is in
+ * neither the feed event ledger nor `computer_sessions`. Reading only those two
+ * meant the actions an operator actually performed were invisible to every
+ * agents-cli surface.
+ */
+export declare function standaloneComputerActionsDir(): string;
+/**
+ * Read the standalone ledger, newest day first, bounded by `limit` actions.
+ *
+ * Bounded by construction: days are read newest-first and reading stops as soon
+ * as the budget is met, so a box with months of history costs the same as one
+ * with a day of it.
+ */
+export declare function listStandaloneComputerActions(opts?: {
+    limit?: number;
+    dir?: string;
+    observer?: string;
+}): ComputerAction[];
+/**
+ * Union the two ledgers, preferring the standalone record for any run present in
+ * both.
+ *
+ * Dedupe keys on `invocationId`, NOT on a timestamp or pid. When a command is
+ * forwarded through `agents computer`, BOTH stores receive it — and the
+ * forwarding rewrites `ts` and `pid` on the way through, so the two copies of one
+ * action do not agree on either. `invocationId` is minted by the engine and
+ * echoed unchanged, which makes it the only field that identifies the same run in
+ * both files. A legacy feed record with no invocationId cannot be matched to
+ * anything, so it is kept: dropping it would lose history the standalone ledger
+ * never had.
+ */
+export declare function mergeComputerActionSources(standalone: ComputerAction[], legacy: ComputerAction[]): ComputerAction[];
 /** Read `computer.action` events straight from the durable event ledger,
  *  newest first, bounded by `limit`. Malformed/legacy records (missing
  *  `command` or `pid`, or an unparseable `ts`) are skipped, never thrown —
@@ -94,6 +148,7 @@ export declare function groupIntoComputerRuns(actions: ComputerAction[], resolve
 export declare function buildComputerSessionRows(opts?: {
     limit?: number;
     machine?: string;
+    observer?: string;
 }): ComputerRunRow[];
 /**
  * Search predicate for the interactive picker: task text, machine/remote