@phnx-labs/agents-cli 1.22.40 → 1.22.42

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

@@ -1,6 +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, type ProfileName, type ConnectionKey } from './types.js';
 import { type ReapOptions } from './hygiene.js';
 import { type RefOpts, type RefNode } from './refs.js';
 import type { TargetFilter } from './types.js';
@@ -50,22 +50,25 @@ interface ProfileConnection {
     port: number;
     pid: number;
     electron?: boolean;
-    /** 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.
+     * 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`.
      */
-    profileName?: string;
+    browserType?: BrowserType;
+    /** Raw `url:<v>` / `title:<v>` filter copied from the profile config. */
+    targetFilter?: 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.
+     * The runtime key this connection is registered under in `this.connections`
+     * (`<profile>@<endpoint>`, plus `.<fork>` for an Electron fork; a bare name
+     * for a legacy pre-composite dir). Also keys the profile's runtime dir, so
+     * downloads and session captures land under `.cache/browser/<key>/`.
      */
-    bareName?: string;
-    forkedFrom?: string;
+    key?: ConnectionKey;
+    /** The bare, user-facing profile name this connection belongs to. */
+    profile?: ProfileName;
+    forkedFrom?: ConnectionKey;
     tasks: Map<string, Task>;
     windowId?: string;
     targetCache?: {
@@ -83,18 +86,20 @@ interface ProfileConnection {
 }
 /** 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;
@@ -127,6 +132,12 @@ export declare function resolveTaskIdentity(forwarded: {
 };
 export declare class BrowserService {
     private static readonly SOURCE_PREFIX;
+    /**
+     * Live browsers, keyed by {@link ConnectionKey} — NOT by profile name. The
+     * branded key type is what makes `connections.get(someProfileName)` (the
+     * RUSH-2709 miss that made `status --profile <name>` return empty for a
+     * running `<name>@endpoint-0`) fail to compile.
+     */
     private connections;
     private forkingProfiles;
     private consoleLogs;
@@ -157,7 +168,10 @@ export declare class BrowserService {
         name: string;
         tabId?: string;
         windowId?: string;
-        profile: string;
+        /** BARE profile name — what the caller asked for, never the runtime key. */
+        profile: ProfileName;
+        /** Runtime key the task actually landed on (`<profile>@<endpoint>`). */
+        key: ConnectionKey;
         skill?: ResolvedDomainSkill;
     }>;
     /**
@@ -192,6 +206,25 @@ export declare class BrowserService {
      * page that has since redirected elsewhere simply does not match, and the
      * caller opens a tab as before.
      */
+    /** Is this CDP target already registered to any task on the connection? */
+    private targetIsClaimed;
+    /**
+     * The CDP targets a task may CLOSE — its own tabs minus any it merely
+     * borrowed. A borrowed tab existed before the task did (see `Task.borrowedTabs`),
+     * so closing it would remove something the task never opened.
+     */
+    private closeableTargetIds;
+    /**
+     * A page target that `navigate` may take over on a browser which cannot create
+     * tabs (Arc). Deliberately narrow: only a tab ALREADY showing the requested URL
+     * -- re-showing that document there is what the caller asked for -- or an empty
+     * new-tab page. A target any task already owns is left alone. Note the honest
+     * limit: reusing a matching tab still RELOADS it, discarding scroll position and
+     * unsaved form state. Arc cannot open a tab at all, so some intrusion is
+     * unavoidable to show the document; a reload is the smallest one, and the tab is
+     * borrowed rather than owned so it is never closed.
+     */
+    private pickReusableTargetWithoutCreate;
     private adoptTabShowing;
     /**
      * Every live task across every connected profile — the reaper's input
@@ -199,7 +232,7 @@ export declare class BrowserService {
      * daemon's live state, so callers only read it and act through `stop`.
      */
     listTasks(): Array<{
-        profile: string;
+        profile: ConnectionKey;
         task: Task;
     }>;
     /**
@@ -216,13 +249,13 @@ export declare class BrowserService {
         ok: boolean;
         profile?: string;
     }>;
-    stopProfile(profileName: string): Promise<void>;
-    navigate(taskId: string, url: string, profileName?: string): Promise<{
+    stopProfile(profileRef: ProfileName | ConnectionKey): Promise<void>;
+    navigate(taskId: string, url: string, profileRef?: ProfileName | ConnectionKey): Promise<{
         tabId: string;
         url: string;
         created: boolean;
     }>;
-    tabAdd(taskId: string, url: string, profileName?: string): Promise<{
+    tabAdd(taskId: string, url: string, profileRef?: ProfileName | ConnectionKey): Promise<{
         tabId: string;
         url: string;
     }>;
@@ -238,7 +271,7 @@ export declare class BrowserService {
     private resolveTabHint;
     private resolveCurrentTab;
     private getCdpTargetId;
-    tabs(taskId?: string, profileName?: string): Promise<TabInfo[]>;
+    tabs(taskId?: string, profileRef?: ProfileName | ConnectionKey): Promise<TabInfo[]>;
     tabClose(taskId: string, tabHint?: string): Promise<void>;
     evaluate(taskId: string, tabHint: string | undefined, expression: string): Promise<unknown>;
     screenshot(taskId: string, tabHint?: string, outputPath?: string, quality?: 'compressed' | 'raw'): Promise<{
@@ -320,7 +353,25 @@ export declare class BrowserService {
     stageUpload(source: string): {
         path: string;
     };
-    status(profileName?: string): Promise<ProfileStatus[]>;
+    /**
+     * Status for one profile (bare name) or every live profile.
+     *
+     * `profileName` is a {@link ProfileName} — a BARE name, never a runtime key.
+     * Every candidate is selected by the one rule ({@link keyBelongsToProfile}),
+     * and a scoped query that finds no live connection falls through to disk, so
+     * `status --profile comet-local` reports the LIVE `comet-local@endpoint-0`
+     * instead of the empty list it used to return (RUSH-2709).
+     */
+    status(profileRef?: ProfileName | ConnectionKey): Promise<ProfileStatus[]>;
+    /**
+     * Rebuild a profile's status from its runtime dirs when no live connection is
+     * registered — a daemon that never connected this profile, or a browser
+     * started by an earlier daemon.
+     *
+     * Takes a BARE profile name and walks every runtime key that belongs to it
+     * ({@link listProfileCacheDirs}), including the legacy pre-composite dir named
+     * exactly the profile.
+     */
     private reconcileFromDisk;
     private profileStatusFromDisk;
     setViewport(taskId: string, width: number, height: number, options?: {
@@ -385,13 +436,22 @@ export declare class BrowserService {
      * already resolved the endpoint and built the `effectiveProfile` with
      * the per-endpoint binary/targetFilter overrides applied; we just use it.
      *
-     * `effectiveProfile.name` is the composite identifier (`<profile>@<endpoint>`)
-     * so per-endpoint pid/port files don't collide when the same app runs
-     * locally and remotely at the same time.
+     * `key` is the runtime key (`<profile>@<endpoint>`) and is what every on-disk
+     * lookup uses, so per-endpoint pid/port files don't collide when the same app
+     * runs locally and remotely at the same time. It is a SEPARATE argument
+     * because `effectiveProfile.name` stays the bare, user-facing name (RUSH-2709).
      */
     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;
     /** Map key for a task on a connection (tasks are keyed by `name`). */
@@ -420,7 +480,7 @@ export declare class BrowserService {
     }): Promise<{
         conn: ProfileConnection;
         task: Task;
-        profileName: string;
+        key: ConnectionKey;
         created: boolean;
     } | null>;
     private listTasksForCaller;
@@ -468,6 +528,7 @@ export declare class BrowserService {
      */
     private rehydrateTaskFromDisk;
     private getTabsForTask;
+    /** Live status for ONE registered connection, addressed by its runtime key. */
     private getProfileStatus;
     private getTarget;
     private getSessionId;