@phnx-labs/agents-cli 1.22.47 → 1.22.49

package/dist/lib/browser/drivers/ssh.d.ts

@@ -16,13 +16,27 @@ export interface SSHConnection {
  * strings differ (no `&` backgrounding, no `lsof`, `.exe` instead of `.app`).
  */
 export type RemoteOs = 'windows' | 'posix';
+export interface SSHConnectOptions {
+    /**
+     * Attach to a browser another device already declared (identity-bearing or
+     * a fungible name we don't declare here). Do not launch a fresh remote
+     * chrome-data, and do not kill that browser when the tunnel closes — it
+     * holds the logins the caller is trying to reach.
+     */
+    persistRemote?: boolean;
+}
+/** Lifecycle for a registry-driven tunnel vs a profile the daemon launched. */
+export declare function persistRemoteLifecycle(persistRemote: boolean): {
+    launchRemote: boolean;
+    killOnCleanup: boolean;
+};
 export declare function connectSSH(endpoint: string, profile: BrowserProfile, 
 /**
- * Runtime key (`<profile>@<endpoint>`) this connection is stored under. It
+ * Runtime key (`<profile>@<device>`) this connection is stored under. It
  * keys the tunnel's runtime record; `profile.name` is the bare, user-facing
  * name and appears only in messages (RUSH-2709).
  */
-key: ConnectionKey): Promise<SSHConnection>;
+key: ConnectionKey, opts?: SSHConnectOptions): Promise<SSHConnection>;
 /**
  * Wrap a PowerShell script as a `-EncodedCommand` invocation. Base64 of the
  * UTF-16LE bytes is a single quote-free token, so it rides through Node spawn

package/dist/lib/browser/drivers/ssh.js

@@ -13,13 +13,19 @@ export { shellQuote };
 // driver's original foreground, stderr-captured behavior exactly.
 import { startSSHTunnel } from '../../computer/ssh-tunnel.js';
 import { encodePwshBase64 } from '../../pwsh.js';
+/** Lifecycle for a registry-driven tunnel vs a profile the daemon launched. */
+export function persistRemoteLifecycle(persistRemote) {
+    return persistRemote
+        ? { launchRemote: false, killOnCleanup: false }
+        : { launchRemote: true, killOnCleanup: true };
+}
 export async function connectSSH(endpoint, profile, 
 /**
- * Runtime key (`<profile>@<endpoint>`) this connection is stored under. It
+ * Runtime key (`<profile>@<device>`) this connection is stored under. It
  * keys the tunnel's runtime record; `profile.name` is the bare, user-facing
  * name and appears only in messages (RUSH-2709).
  */
-key) {
+key, opts = {}) {
     const url = new URL(endpoint);
     if (url.protocol !== 'ssh:') {
         throw new Error(`Invalid SSH endpoint: ${endpoint}`);
@@ -59,7 +65,14 @@ key) {
     // (the launch backgrounds/WMI-spawns regardless), so this does not spuriously
     // fail the reconnect path — only genuine launch failures reach the caller
     // instead of being swallowed and mis-reported later as a tunnel timeout.
-    await ensureRemoteBrowser(user, host, profile.browser, remotePort, remoteOs, profile.binary);
+    //
+    // persistRemote skips the launch: launching would mint a logged-out
+    // `--user-data-dir=/tmp/agents-browser-N` under a name that means a
+    // credentialed browser on the declaring device.
+    const lifecycle = persistRemoteLifecycle(Boolean(opts.persistRemote));
+    if (lifecycle.launchRemote) {
+        await ensureRemoteBrowser(user, host, profile.browser, remotePort, remoteOs, profile.binary);
+    }
     let tunnel;
     if (occupant) {
         // Reuse the existing tunnel rather than spawning a duplicate.
@@ -78,7 +91,19 @@ key) {
         tunnel.kill();
         throw new Error(`SSH tunnel failed to establish to ${host}`);
     }
-    const { wsUrl, browser } = await discoverBrowserWsUrl(localPort, 'localhost', profile.name);
+    let wsUrl;
+    let browser;
+    try {
+        ({ wsUrl, browser } = await discoverBrowserWsUrl(localPort, 'localhost', profile.name));
+    }
+    catch (err) {
+        tunnel.kill();
+        if (opts.persistRemote) {
+            const why = err instanceof Error ? err.message : String(err);
+            throw new Error(`Browser profile "${profile.name}" is declared on ${host}, but nothing is speaking CDP on port ${remotePort}: ${why}`);
+        }
+        throw err;
+    }
     try {
         verifyBrowserIdentity(browser, profile.browser, remotePort, host);
     }
@@ -108,11 +133,13 @@ key) {
         pid: tunnelPid,
         cleanup: () => {
             cdp.close();
-            // Kill the remote browser BEFORE tearing down the tunnel. It runs on a
-            // separate ssh connection (independent of the tunnel we're about to
-            // kill), so tunnel teardown can't cut it off. Fire-and-forget — cleanup
-            // stays synchronous, and killRemoteBrowser never rejects.
-            killRemoteBrowser(user, host, remoteOs, remotePort).catch(() => { });
+            // Kill the remote browser BEFORE tearing down the tunnel — but only
+            // when we launched it. persistRemote is an attach to someone else's
+            // declared browser; killing it would drop the logins the caller came
+            // for. Fire-and-forget — cleanup stays synchronous.
+            if (lifecycle.killOnCleanup) {
+                killRemoteBrowser(user, host, remoteOs, remotePort).catch(() => { });
+            }
             tunnel.kill();
             clearProfileRuntime(key);
         },

package/dist/lib/browser/ipc.js

@@ -398,6 +398,9 @@ export class BrowserIPCServer {
                 };
             }
             request.task = resolved.task.name;
+            if (resolved.created && resolved.picked) {
+                request.picked = resolved.picked;
+            }
             return undefined;
         }
         catch (err) {
@@ -437,7 +440,7 @@ export class BrowserIPCServer {
                     fleetRemote: request.fleetRemote,
                     actor: request.actor,
                 });
-                return { ok: true, tabId: shown.tabId };
+                return { ok: true, tabId: shown.tabId, message: shown.picked };
             }
             case 'start': {
                 if (!request.profile) {
@@ -461,10 +464,11 @@ export class BrowserIPCServer {
                     tabId: result.tabId,
                     windowTargetId: result.windowId,
                     skill: result.skill,
+                    message: result.picked,
                 };
             }
             // The out-of-process seam onto the abandoned-task reaper: the daemon
-            // owns the live BrowserService, so a CLI verb (`agents browser gc`) can
+            // owns the live BrowserService, so a CLI verb (`agents browser prune`) can
             // only reach `reapAbandoned` through IPC. The daemon's own periodic tick
             // calls the service method directly.
             case 'gc': {
@@ -533,7 +537,8 @@ export class BrowserIPCServer {
                     };
                 }
                 const result = await this.service.navigate(request.task, request.url, request.profile);
-                return { ok: true, tabId: result.tabId, task: request.task };
+                const picked = request.picked;
+                return { ok: true, tabId: result.tabId, task: request.task, message: picked };
             }
             case 'tab-add': {
                 if (!request.task || !request.url) {

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

@@ -1,5 +1,6 @@
 import type { BrowserProfile, ProfileName } from './types.js';
 export type { BrowserProfile } from './types.js';
+export { declaringDevices, profileKind, profileRegistry, type ProfileDeclaration, } from './registry.js';
 /**
  * Name of the profile `ensureDefaultBrowserProfile` auto-detects and pins.
  *
@@ -25,17 +26,9 @@ export declare const LEGACY_DEFAULT_BROWSER_PROFILE_NAME = "default";
  * wins, so no existing config breaks.
  */
 export declare const DEFAULT_PROFILE_ALIAS = "default";
-/**
- * Where a profile is stored, and therefore who sees it:
- *   - `local` — this machine's `devices/<machine>/agents.yaml` (`deviceBrowser`)
- *   - `fleet` — the synced `~/.agents/agents.yaml` (`browser`), visible on every box
- */
-export type ProfileScope = 'local' | 'fleet';
-/** A profile plus the store it actually lives in. */
-export interface ScopedBrowserProfile {
-    profile: BrowserProfile;
-    scope: ProfileScope;
-}
+export type BrowserProfileWithDeclarations = BrowserProfile & {
+    devices: string[];
+};
 /**
  * The device-local configured default profile name (set via
  * `agents browser use`), or undefined when unset. When set, it
@@ -60,14 +53,8 @@ export declare function getProfileDownloadsDir(name: string): string;
  * one-shot migration in migrate.ts folds old captures into here.
  */
 export declare function getProfileSessionsDir(name: string, task: string): string;
-export declare function listProfiles(): Promise<BrowserProfile[]>;
-/**
- * Every visible profile paired with the store it lives in. Same precedence as
- * {@link listProfiles} — a machine-local entry wins a name collision, so a name
- * present in both maps reports `local`, which is the copy that is actually used.
- */
-export declare function listProfilesWithScope(): Promise<ScopedBrowserProfile[]>;
-export declare function getProfile(name: string): Promise<BrowserProfile | null>;
+export declare function listProfiles(): Promise<BrowserProfileWithDeclarations[]>;
+export declare function getProfile(name: string): Promise<BrowserProfileWithDeclarations | null>;
 /**
  * True when `profile` can actually launch or attach on THIS machine.
  *
@@ -79,26 +66,6 @@ export declare function getProfile(name: string): Promise<BrowserProfile | null>
  * for the current machine.
  */
 export declare function isProfileLaunchableHere(profile: BrowserProfile): boolean;
-/**
- * Resolve the profile `agents browser start` uses when no `--profile` is given.
- *
- * Order: (1) the device-local configured default (`agents browser profiles
- * set-default <name>`) when it names an existing profile that can launch here;
- * (2) an existing `default` profile that can launch here; (3) auto-pick the
- * first installed Chromium-family browser per the platform priority list in
- * chrome.ts (macOS: chrome > brave > edge > chromium > comet > arc; Linux: chrome >
- * chromium > brave > edge; Windows: edge > chrome > brave > comet) and pin a
- * `default` profile to it. Throws an actionable error if none of those binaries
- * are installed.
- *
- * "Can launch here" matters because `agents.yaml` syncs across the fleet: a
- * `default` auto-created on macOS carries a `/Applications/...` binary path that
- * doesn't exist on a Linux box. Rather than hand that broken profile back (the
- * top browser roadblock — "Custom binary not found"), we re-detect and
- * regenerate the `default` for this machine. A configured or existing default
- * that no longer exists, or can't launch here, warns and falls through — never a
- * hard fail.
- */
 /**
  * The auto-detected profile this machine already carries, under either name —
  * the current `auto-chrome` or the `default` an older build wrote. Callers that
@@ -137,17 +104,36 @@ export declare function resolveProfileRef(ref?: string): Promise<string | undefi
  * `start`'s resolver. Same order as {@link resolveProfileRef} for an explicit
  * name, but the IMPLICIT path (no `--profile`, or the bare `default` alias with
  * no profile of that name) goes through {@link ensureDefaultBrowserProfile} —
- * which additionally verifies the resolved default can launch on THIS machine,
- * warns and falls through when it can't, and regenerates or creates one.
+ * which additionally verifies the resolved default can launch on THIS machine.
+ * An undeclared configured default is an error. A declared default whose
+ * browser isn't installed here warns and falls through to auto-detect.
  *
  * `start` is the only command that launches a browser, so it is the only one
  * that may do those things; routing a filter-only command through this would
  * warn about, and rewrite, config the user never asked it to touch.
  *
- * Throws when no profile exists and no supported browser is installed —
- * `ensureDefaultBrowserProfile`'s actionable "install one of …" error.
+ * Throws when the configured default is undeclared, or when no profile exists
+ * and no supported browser is installed.
  */
 export declare function resolveProfileRefForStart(ref?: string): Promise<string>;
+/**
+ * Resolve the profile a bare `agents browser start` uses.
+ *
+ * Order: (1) the device-local configured default (`agents browser use <name>`)
+ * when it names a profile that exists and can launch here; (2) an existing
+ * auto-detected profile that can launch here; (3) auto-pick the first installed
+ * Chromium-family browser and pin `auto-chrome` (or repair a stale legacy
+ * `default`) to it.
+ *
+ * Two failure modes at the configured-default step are not the same:
+ *   - No device declares the name (including a leftover central `browser:`
+ *     entry that was never claimed) → throw. Auto-creating `auto-chrome` would
+ *     hand the agent a logged-out browser while `browser.profile` still names
+ *     the credentialed one.
+ *   - The name is declared, but its browser/binary is not installed HERE →
+ *     warn and fall through. That is a missing binary on this box, not a
+ *     missing identity; auto-detect is the existing repair.
+ */
 export declare function ensureDefaultBrowserProfile(): Promise<BrowserProfile>;
 /**
  * Compute the LOCAL port a profile will occupy at runtime:
@@ -181,46 +167,9 @@ export declare function findFreeProfilePort(): Promise<number>;
 export declare function assertLocalPortFree(profile: BrowserProfile, opts?: {
     ignore?: string;
 }): void;
-/**
- * Create a profile. **It lands in this machine's own store by default** — pass
- * `{ fleet: true }` (the CLI's `--fleet`) to put it in the synced `agents.yaml`
- * where every box will see it.
- *
- * Local-by-default is the RUSH-2716 fix. A profile is a local browser install
- * (`binary:` is an absolute path for one OS) bound to a locally chosen free port,
- * so the fleet-synced copy is wrong on every other machine to begin with; and
- * because agents mint throwaway profiles freely, every ad-hoc one was syncing to
- * every machine as junk that nothing cleaned up (`agents browser profiles prune`
- * is the other half of that fix). Opting in with `--fleet` is for a profile that
- * really is fleet config — a remote `ssh://` endpoint, or a named profile whose
- * shape you want on every box.
- *
- * Existing profiles are NOT migrated: this only decides where a NEW entry is
- * written, so a fleet profile created before this change keeps syncing.
- */
-export declare function createProfile(profile: BrowserProfile, opts?: {
-    fleet?: boolean;
-}): Promise<void>;
+/** Declare a profile on this device. The same name may be declared by peers. */
+export declare function createProfile(profile: BrowserProfile): Promise<void>;
 export declare function updateProfile(profile: BrowserProfile): Promise<void>;
-/**
- * Flag a fleet-synced profile whose contents only make sense on ONE machine.
- *
- * A `cdp://` endpoint on loopback always connects on the machine EVALUATING the
- * profile, so a fleet-scope copy does not mean "that browser" — it means "port N
- * on whichever box ran the command". The name then silently resolves to a
- * different, usually logged-out browser on every other machine, which is the
- * worst possible failure for a profile that carries live logins.
- *
- * Reported by `profiles doctor` (a failing `scope` check) and noted in the
- * `kept` reason `profiles prune` prints for a fleet profile. The repair is
- * {@link moveProfileScope}, never an automatic rewrite of the synced doc.
- */
-export declare function misfiledFleetProfile(profile: BrowserProfile, scope: ProfileScope): {
-    misfiled: false;
-} | {
-    misfiled: true;
-    why: string;
-};
 /** Fields an existing profile may be edited in place.
  *
  * Deliberately a SUBSET of {@link BrowserProfile}. `name` and `browser` are
@@ -231,17 +180,9 @@ export declare function misfiledFleetProfile(profile: BrowserProfile, scope: Pro
 export type EditableProfileFields = Partial<Pick<BrowserProfile, 'description' | 'binary' | 'electron' | 'targetFilter' | 'endpoints' | 'chrome' | 'secrets' | 'viewport'>>;
 export interface EditProfileResult {
     profile: BrowserProfile;
-    scope: ProfileScope;
+    devices: string[];
     /** Field names that actually changed. Empty means the edit was a no-op. */
     changed: string[];
-    /**
-     * Set when the write landed machine-locally while a stale fleet copy remains.
-     * Only reachable for {@link isMachineLocalProfile} names that an older version
-     * wrote into the fleet store: {@link updateProfile} pins those local, so this
-     * box sees the edit and every other box keeps the old value. Callers must say
-     * so rather than reporting a clean success.
-     */
-    fleetCopyLeftStale?: boolean;
 }
 /**
  * Merge `patch` onto the stored profile and persist it in the store it already
@@ -279,7 +220,7 @@ export declare function assertRegistrableProfileName(name: string): void;
  * a running browser corrupts it.
  */
 export declare function renameProfile(from: ProfileName, to: ProfileName): Promise<{
-    scope: ProfileScope;
+    devices: string[];
     movedDirs: string[];
     repointedDefault: boolean;
     repointedViewer: boolean;
@@ -289,10 +230,6 @@ export declare function renameProfile(from: ProfileName, to: ProfileName): Promi
         key: 'browser.profile' | 'browser.viewer';
     }>;
 }>;
-export declare function moveProfileScope(name: string, to: ProfileScope): Promise<{
-    from: ProfileScope;
-    to: ProfileScope;
-}>;
 export declare function deleteProfile(name: string): Promise<void>;
 /**
  * Pad `text` to exactly `width` visible characters, truncating with an ellipsis
@@ -316,12 +253,9 @@ export declare function padColumn(text: string, width: number): string;
  * a leading column, explained by a legend line — so the name column carries just
  * the name and `default` in it always means the profile of that name.
  *
- * The SCOPE column is the RUSH-2716 companion: it says whether an entry lives on
- * this machine only (`local`) or in the fleet-synced `agents.yaml` (`fleet`), so
- * "why does this box have a profile I never made here?" is answerable at a
- * glance.
+ * WHERE lists the devices whose own files declare the name.
  */
-export declare function formatProfilesTable(rows: ScopedBrowserProfile[], configuredDefault?: string): string[];
+export declare function formatProfilesTable(rows: BrowserProfileWithDeclarations[], configuredDefault?: string): string[];
 /**
  * Resolve a profile's endpoint presets into a normalized map regardless of
  * whether the YAML uses the legacy `string[]` shape or the new map shape.