@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/lib/browser/remote-control.js

@@ -1,7 +1,7 @@
 /**
  * Consent gate for driving THIS machine's browser from another fleet machine.
  *
- * `browser --host <device>` routes a browser command to `<device>` over SSH (the
+ * `browser --device <device>` routes a browser command to `<device>` over SSH (the
  * fleet passthrough) and runs `agents browser ...` there. Every such remote
  * invocation carries the {@link FLEET_REMOTE_ENV} marker, set once at the fleet
  * dispatch site (`maybeRunOnHost`). A machine only accepts being driven when its
@@ -15,7 +15,7 @@
 import { getConfigValue } from '../device-config.js';
 /** Env marker set on every remote `agents` invocation by `buildRemoteAgentsInvocation`. */
 export const FLEET_REMOTE_ENV = 'AGENTS_FLEET_REMOTE';
-/** True when this process was dispatched to this machine by a fleet `--host` run. */
+/** True when this process was dispatched to this machine by a fleet `--device` run. */
 export function isFleetRemoteInvocation(env = process.env) {
     return env[FLEET_REMOTE_ENV] === '1';
 }
@@ -42,7 +42,7 @@ export function assertRemoteControlAllowed(opts) {
     if (enabled)
         return;
     const who = env.AGENTS_ACTOR_HOST || env.AGENTS_ACTOR || 'A fleet machine';
-    throw new Error(`${who} tried to drive this machine's browser over \`browser --host\`, but remote ` +
+    throw new Error(`${who} tried to drive this machine's browser over \`browser --device\`, but remote ` +
         `browser control is off here. To allow it, run on THIS machine:\n` +
         `  agents browser remote-control on`);
 }

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

@@ -1,3 +1,4 @@
+import { type ProfileScope } from './profiles.js';
 /**
  * Per-profile runtime files we persist under
  * `~/.agents/.cache/browser/<composite>/`:
@@ -114,3 +115,81 @@ export declare function reapOrphanedProcesses(): {
     reaped: number;
     details: string[];
 };
+/**
+ * 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
+ * one profile can own several runtime dirs, so checking only
+ * `getProfileRuntimeDir(name)` would miss a running composite — and prune must
+ * never remove a profile that is in use.
+ *
+ * A recorded `pid: 0` means "attached to a browser someone else launched", so it
+ * is not our process to protect; an open task on that dir still counts as in use.
+ */
+export declare function isProfileInUse(profileName: string): boolean;
+/** Why a profile is considered dead. */
+export type PruneReason = 'binary-missing' | 'never-used';
+export interface PruneCandidate {
+    name: string;
+    scope: ProfileScope;
+    reason: PruneReason;
+    /** Cache dirs that would be removed along with the config entry. */
+    cacheDirs: string[];
+}
+export interface PrunePlan {
+    /** Profiles that would be (or were) removed. */
+    candidates: PruneCandidate[];
+    /** Profiles deliberately left alone, with the guard that kept them. */
+    kept: Array<{
+        name: string;
+        scope: ProfileScope;
+        why: string;
+    }>;
+}
+export declare const PRUNE_REASON_TEXT: Record<PruneReason, string>;
+/**
+ * Decide which browser profiles are dead, WITHOUT touching anything.
+ * `pruneProfiles` executes exactly this plan, so `--dry-run` and the real run
+ * can never disagree.
+ *
+ * Dead means one of {@link PruneReason}: the configured browser cannot launch
+ * here at all, or the profile has never been started so nothing on this disk
+ * refers to it. That second reason is what actually reclaims agent-minted
+ * throwaway profiles (RUSH-2716) — they are created for an installed browser, so
+ * only "never started" identifies them.
+ *
+ * Four guards, and each exists because removing that profile would be wrong
+ * rather than merely tidy:
+ *   - **in use** — a live browser, SSH tunnel, or open task on any of its dirs.
+ *   - **the configured default** — this machine resolves a bare
+ *     `agents browser start` to it; removing it breaks that command.
+ *   - **`default`** — auto-regenerated by `ensureDefaultBrowserProfile`, so
+ *     pruning it is pure churn.
+ *   - **fleet-synced** — deleting one removes it from EVERY machine, so it takes
+ *     the explicit `includeFleet` opt-in.
+ *
+ * Known limitation: `BrowserProfileConfig` records no creation time, so a
+ * profile created seconds ago and not yet started is indistinguishable from an
+ * abandoned one and is reported `never-used`. That is why the verb is explicit
+ * and `--dry-run` exists.
+ */
+export declare function planProfilePrune(profiles: Array<{
+    name: string;
+    scope: ProfileScope;
+    launchableHere: boolean;
+}>, opts?: {
+    includeFleet?: boolean;
+    configuredDefault?: string;
+}): PrunePlan;
+/**
+ * Build the prune plan from live config. Split from {@link planProfilePrune} so
+ * the decision rules stay unit-testable without a configured machine.
+ */
+export declare function buildProfilePrunePlan(opts?: {
+    includeFleet?: boolean;
+}): Promise<PrunePlan>;
+/**
+ * Execute a prune plan: drop each candidate's config entry and wipe its cache
+ * dirs. Returns the plan that was applied so the caller can report exactly what
+ * went, matching what `--dry-run` printed.
+ */
+export declare function pruneProfiles(plan: PrunePlan): Promise<PrunePlan>;

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

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
-import { getProfileRuntimeDir, getBrowserRuntimeDir } from './profiles.js';
+import { getProfileRuntimeDir, getBrowserRuntimeDir, listProfilesWithScope, getConfiguredDefaultProfileName, isProfileLaunchableHere, deleteProfile, DEFAULT_BROWSER_PROFILE_NAME, } from './profiles.js';
 const PID_FILE = 'pid';
 const PORT_FILE = 'port';
 const COMMAND_FILE = 'command';
@@ -247,6 +247,124 @@ export function reapOrphanedProcesses() {
     }
     return { reaped, details };
 }
+/**
+ * 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
+ * one profile can own several runtime dirs, so checking only
+ * `getProfileRuntimeDir(name)` would miss a running composite — and prune must
+ * never remove a profile that is in use.
+ *
+ * A recorded `pid: 0` means "attached to a browser someone else launched", so it
+ * is not our process to protect; an open task on that dir still counts as in use.
+ */
+export function isProfileInUse(profileName) {
+    for (const dir of listProfileCacheDirs(profileName)) {
+        const entry = path.basename(dir);
+        if (readTaskCount(dir) > 0)
+            return true;
+        const meta = readProfileRuntimeMeta(entry);
+        if (!meta)
+            continue;
+        if (meta.pid && isProcessAlive(meta.pid, meta.command))
+            return true;
+        if (meta.tunnelPid && isProcessAlive(meta.tunnelPid, 'ssh'))
+            return true;
+    }
+    return false;
+}
+export const PRUNE_REASON_TEXT = {
+    'binary-missing': 'its browser/binary is not installed on this machine',
+    'never-used': 'it has never been started (no runtime dir)',
+};
+/**
+ * Decide which browser profiles are dead, WITHOUT touching anything.
+ * `pruneProfiles` executes exactly this plan, so `--dry-run` and the real run
+ * can never disagree.
+ *
+ * Dead means one of {@link PruneReason}: the configured browser cannot launch
+ * here at all, or the profile has never been started so nothing on this disk
+ * refers to it. That second reason is what actually reclaims agent-minted
+ * throwaway profiles (RUSH-2716) — they are created for an installed browser, so
+ * only "never started" identifies them.
+ *
+ * Four guards, and each exists because removing that profile would be wrong
+ * rather than merely tidy:
+ *   - **in use** — a live browser, SSH tunnel, or open task on any of its dirs.
+ *   - **the configured default** — this machine resolves a bare
+ *     `agents browser start` to it; removing it breaks that command.
+ *   - **`default`** — auto-regenerated by `ensureDefaultBrowserProfile`, so
+ *     pruning it is pure churn.
+ *   - **fleet-synced** — deleting one removes it from EVERY machine, so it takes
+ *     the explicit `includeFleet` opt-in.
+ *
+ * Known limitation: `BrowserProfileConfig` records no creation time, so a
+ * profile created seconds ago and not yet started is indistinguishable from an
+ * abandoned one and is reported `never-used`. That is why the verb is explicit
+ * and `--dry-run` exists.
+ */
+export function planProfilePrune(profiles, opts = {}) {
+    const plan = { candidates: [], kept: [] };
+    for (const { name, scope, launchableHere } of profiles) {
+        const keep = (why) => { plan.kept.push({ name, scope, why }); };
+        if (scope === 'fleet' && !opts.includeFleet) {
+            keep('fleet-synced (pass --fleet to include it)');
+            continue;
+        }
+        if (name === DEFAULT_BROWSER_PROFILE_NAME) {
+            keep('the auto-detected default profile');
+            continue;
+        }
+        if (opts.configuredDefault && name === opts.configuredDefault) {
+            keep("this machine's configured default profile");
+            continue;
+        }
+        if (isProfileInUse(name)) {
+            keep('in use (live browser, tunnel, or open task)');
+            continue;
+        }
+        const cacheDirs = listProfileCacheDirs(name);
+        if (!launchableHere) {
+            plan.candidates.push({ name, scope, reason: 'binary-missing', cacheDirs });
+            continue;
+        }
+        if (cacheDirs.length === 0) {
+            plan.candidates.push({ name, scope, reason: 'never-used', cacheDirs });
+            continue;
+        }
+        keep('healthy (browser installed, has runtime state)');
+    }
+    return plan;
+}
+/**
+ * Build the prune plan from live config. Split from {@link planProfilePrune} so
+ * the decision rules stay unit-testable without a configured machine.
+ */
+export async function buildProfilePrunePlan(opts = {}) {
+    const scoped = await listProfilesWithScope();
+    return planProfilePrune(scoped.map(({ profile, scope }) => ({
+        name: profile.name,
+        scope,
+        launchableHere: isProfileLaunchableHere(profile),
+    })), { includeFleet: opts.includeFleet, configuredDefault: getConfiguredDefaultProfileName() });
+}
+/**
+ * Execute a prune plan: drop each candidate's config entry and wipe its cache
+ * dirs. Returns the plan that was applied so the caller can report exactly what
+ * went, matching what `--dry-run` printed.
+ */
+export async function pruneProfiles(plan) {
+    for (const candidate of plan.candidates) {
+        await deleteProfile(candidate.name);
+        for (const dir of candidate.cacheDirs) {
+            try {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+            catch { /* already gone */ }
+        }
+        removeProfileCache(candidate.name);
+    }
+    return plan;
+}
 function matchesCommand(pid, expectedCommand) {
     const out = liveProcessCommand(pid);
     if (!out)

package/dist/lib/browser/service.d.ts

@@ -1,5 +1,6 @@
+import { CDPClient } from './cdp.js';
 import { type ResolvedDomainSkill } from './domain-skills.js';
-import { type Task, type TabInfo, type ProfileStatus, type HistoricalTask, type ReapResult } from './types.js';
+import { type Task, type TabInfo, type ProfileStatus, type BrowserType, type HistoricalTask, type ReapResult } from './types.js';
 import { type ReapOptions } from './hygiene.js';
 import { type RefOpts, type RefNode } from './refs.js';
 import type { TargetFilter } from './types.js';
@@ -44,6 +45,76 @@ export declare function pickWindowTarget<T extends {
 export declare function parseSinceUntil(s: string): Date;
 export declare function readNewestMatchingRemoteFileCommand(dir: string, prefix: string, tailLines: number): string;
 export declare function readNewestMatchingFile(dir: string, prefix: string, tailLines: number): string;
+interface ProfileConnection {
+    cdp: CDPClient;
+    port: number;
+    pid: number;
+    electron?: boolean;
+    /**
+     * The profile's declared browser family. Load-bearing for Arc: Arc answers
+     * `Browser.getVersion` but exposes zero CDP page targets and CRASHES on
+     * `Target.createTarget` (verified live, PR #2778), so any tab-creating path
+     * must refuse rather than crash the user's Arc. See `createPageTarget`.
+     */
+    browserType?: BrowserType;
+    /** Raw `url:<v>` / `title:<v>` filter copied from the profile config. */
+    targetFilter?: string;
+    /**
+     * The composite key this connection is registered under in `this.connections`
+     * (`<profile>` / `<profile>@<endpoint>` / `<profile>.<fork>`). It is the same
+     * name used to key the profile's runtime dir, so downloads and session
+     * captures land under `.cache/browser/<profileName>/`. Set at registration.
+     */
+    profileName?: string;
+    /**
+     * Bare YAML profile name without the `@<endpoint>` suffix. Kept so
+     * `status --profile comet-local` matches the composite connection key
+     * `comet-local@endpoint-0` without prefix-matching wrong browsers.
+     */
+    bareName?: string;
+    forkedFrom?: string;
+    tasks: Map<string, Task>;
+    windowId?: string;
+    targetCache?: {
+        targets: TargetInfo[];
+        ts: number;
+    };
+    sessionCache: Map<string, string>;
+    /**
+     * Connection-specific teardown (e.g. killing the SSH tunnel for an ssh://
+     * profile). Must be called whenever the connection is removed from
+     * `this.connections`, otherwise the tunnel leaks across daemon restarts
+     * and hijacks future `cdp://127.0.0.1:N` profiles on the same local port.
+     */
+    cleanup?: () => void;
+}
+/** Join error lines so callers get a next command, not a dead-end message. */
+export declare function actionable(...lines: string[]): string;
+/**
+ * Arc answers `Browser.getVersion` (so a connection succeeds) but exposes zero
+ * CDP page targets via every discovery method and CRASHES when a new tab is
+ * requested via `Target.createTarget` (verified live, PR #2778). It is therefore
+ * not drivable. This is the single clear, actionable error every tab-creating
+ * path throws instead of crashing the user's Arc window.
+ */
+export declare function arcNotDrivableError(profileName?: string): Error;
+/** Derive a human label from an explicit title or a navigated URL. */
+export declare function deriveTaskLabel(opts: {
+    title?: string;
+    url?: string;
+    existing?: string;
+}): string;
+/**
+ * True when `key` is the bare profile name or one of its composite endpoint
+ * keys (`name@endpoint`). Used by status/stop so `comet-local` matches
+ * `comet-local@endpoint-0`.
+ */
+export declare function connectionKeyMatchesProfile(key: string, profileName: string): boolean;
+type TargetInfo = {
+    targetId: string;
+    url?: string;
+    title?: string;
+};
 /** Describes a ref that was re-resolved from a drifted integer via its cached descriptor. */
 export interface HealInfo {
     from: number;
@@ -94,6 +165,8 @@ export declare class BrowserService {
         launchId?: string;
         /** Calling agent session, forwarded from the CLI (see IPCRequest.sessionId). */
         sessionId?: string;
+        /** Explicit human label (`--title`). */
+        title?: string;
     }): Promise<{
         task: string;
         name: string;
@@ -264,6 +337,7 @@ export declare class BrowserService {
     };
     status(profileName?: string): Promise<ProfileStatus[]>;
     private reconcileFromDisk;
+    private profileStatusFromDisk;
     setViewport(taskId: string, width: number, height: number, options?: {
         mobile?: boolean;
         deviceScaleFactor?: number;
@@ -333,9 +407,47 @@ export declare class BrowserService {
     private connectProfile;
     private connectEndpoint;
     private enableDomains;
+    /**
+     * The single path that opens a new CDP page/window target. It exists so the
+     * Arc guard lives in exactly one place: `Target.createTarget` crashes Arc
+     * (verified, PR #2778), so an Arc connection throws a clear, actionable error
+     * here instead of every call site re-checking. Every drivable Chromium-family
+     * browser goes straight through.
+     */
+    private createPageTarget;
     private getOrCreateWindow;
     private hasTaskNamed;
-    private generateUniqueTaskName;
+    /** Map key for a task on a connection (tasks are keyed by `name`). */
+    private taskMapKey;
+    /** Find a task by map key, id, or name on one connection. */
+    private lookupTaskOnConn;
+    private maybeUpdateLabelFromUrl;
+    /**
+     * Resolve a task for a page/close verb.
+     *
+     *   - explicit `task` handle → look up (with disk rehydrate on RAM miss)
+     *   - no handle, exactly one live task for this caller → use it
+     *   - no handle, multiple for this caller → error listing them + `--task`
+     *   - no handle, zero for this caller, createIfMissing → start a new task
+     *   - no handle, zero, !createIfMissing → return null (caller reports "nothing to close")
+     */
+    resolveOrCreateTask(opts: {
+        task?: string;
+        profile?: string;
+        actor?: string;
+        launchId?: string;
+        sessionId?: string;
+        createIfMissing: boolean;
+        title?: string;
+        url?: string;
+    }): Promise<{
+        conn: ProfileConnection;
+        task: Task;
+        profileName: string;
+        created: boolean;
+    } | null>;
+    private listTasksForCaller;
+    private currentUrlHint;
     /**
      * Mark a task as active, so the reaper's idle window measures time since the
      * last real use rather than time since `start` (RUSH-2622).
@@ -356,6 +468,28 @@ export declare class BrowserService {
      */
     private touchTask;
     private findTask;
+    /**
+     * Soft-attach to an already-running browser for a runtime dir.
+     *
+     * Never launches a browser and never clears pid/port files on failure —
+     * `connectProfile` does both, which made `status()` wipe disk state when
+     * CDP was unreachable (CI / post-reaper) and then return an empty list.
+     * Returns null when nothing is speaking CDP so callers can fall through
+     * to disk reconcile.
+     */
+    private attachRunningProfile;
+    /**
+     * Reconnect every profile runtime dir that still has a live browser and
+     * tasks.json entries. Used before identity-based resolution so a daemon
+     * restart does not make the caller's tasks invisible.
+     */
+    private rehydrateAllFromDisk;
+    /**
+     * On a RAM miss, scan profile runtime dirs for a tasks.json entry matching
+     * `taskId`, soft-attach when CDP is still up, and register the connection.
+     * Does not launch browsers or clear runtime files.
+     */
+    private rehydrateTaskFromDisk;
     private getTabsForTask;
     private getProfileStatus;
     private getTarget;
@@ -366,3 +500,4 @@ export declare class BrowserService {
     private saveToHistory;
     getHistory(limit?: number): Promise<HistoricalTask[]>;
 }
+export {};