@phnx-labs/agents-cli 1.22.46 → 1.22.49

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

@@ -1,5 +1,6 @@
-import type { BrowserProfile } from './types.js';
+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:
@@ -168,26 +154,82 @@ export declare function effectiveLocalPort(profile: BrowserProfile): number | un
  */
 export declare function findFreeProfilePort(): Promise<number>;
 /**
- * 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.
+ * Refuse a profile whose LOCAL port another profile already owns.
  *
- * 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.
+ * Every CDP/SSH profile ends up listening on (or tunneling to) the same LOCAL
+ * port number as the one configured in the endpoint URL — SSH profiles reuse
+ * `?port=N` locally, so we no longer scope by host. Two profiles that would
+ * need the same local port can't both run at the same time.
  *
- * Existing profiles are NOT migrated: this only decides where a NEW entry is
- * written, so a fleet profile created before this change keeps syncing.
+ * `opts.ignore` is the profile's own name on an edit. Without it every edit
+ * collides with itself, since the stored copy still owns the port being kept.
  */
-export declare function createProfile(profile: BrowserProfile, opts?: {
-    fleet?: boolean;
-}): Promise<void>;
+export declare function assertLocalPortFree(profile: BrowserProfile, opts?: {
+    ignore?: string;
+}): 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>;
+/** Fields an existing profile may be edited in place.
+ *
+ * Deliberately a SUBSET of {@link BrowserProfile}. `name` and `browser` are
+ * identity, not settings: both key the on-disk runtime dir
+ * ({@link getProfileRuntimeDir}) and any live `<name>@<endpoint>` connection, so
+ * changing either orphans the cached browser data. Delete and recreate instead.
+ */
+export type EditableProfileFields = Partial<Pick<BrowserProfile, 'description' | 'binary' | 'electron' | 'targetFilter' | 'endpoints' | 'chrome' | 'secrets' | 'viewport'>>;
+export interface EditProfileResult {
+    profile: BrowserProfile;
+    devices: string[];
+    /** Field names that actually changed. Empty means the edit was a no-op. */
+    changed: string[];
+}
+/**
+ * Merge `patch` onto the stored profile and persist it in the store it already
+ * lives in (see {@link updateProfile} for the scope rules).
+ *
+ * Runs {@link createProfile}'s validations against the MERGED record, not just
+ * the patched fields — a binary edit re-resolves the browser path, a
+ * targetFilter edit re-checks the electron gate, and the local-port scan runs
+ * with this profile excluded so an unchanged port is not a self-collision.
+ */
+export declare function editProfile(name: string, patch: EditableProfileFields): Promise<EditProfileResult>;
+/**
+ * Throw if `name` cannot be used for a NEW profile.
+ *
+ * Shared by `profiles create` and {@link renameProfile} so the two cannot drift
+ * — the shape rule used to live inline in the command, which is how `rename`
+ * would have accepted a name `create` rejects.
+ *
+ * `default` is refused because it is the reserved ALIAS meaning "whatever
+ * profile this machine is configured to use" (RUSH-2709). A literal profile by
+ * that name makes `--profile default` mean two different things.
+ */
+export declare function assertRegistrableProfileName(name: string): void;
+/**
+ * Rename a profile, taking its on-disk state with it.
+ *
+ * `editProfile` deliberately refuses a name change, and this is why: the name
+ * keys the runtime dir ({@link getProfileRuntimeDir}), every fork/endpoint dir
+ * derived from it, and the `browser.profile` pointer. Delete-and-recreate — the
+ * only route before this — silently abandons the browser's `--user-data-dir`,
+ * which is where a profile's logins live. On a real agent browser that is
+ * gigabytes of session state and every account it has ever signed into.
+ *
+ * Refuses when the profile is in use: moving a `--user-data-dir` out from under
+ * a running browser corrupts it.
+ */
+export declare function renameProfile(from: ProfileName, to: ProfileName): Promise<{
+    devices: string[];
+    movedDirs: string[];
+    repointedDefault: boolean;
+    repointedViewer: boolean;
+    /** Peers still pinning the OLD name, and which key each used. */
+    stalePins: Array<{
+        device: string;
+        key: 'browser.profile' | 'browser.viewer';
+    }>;
+}>;
 export declare function deleteProfile(name: string): Promise<void>;
 /**
  * Pad `text` to exactly `width` visible characters, truncating with an ellipsis
@@ -211,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.