@phnx-labs/agents-cli 1.22.40 → 1.22.42

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

@@ -1,4 +1,66 @@
-export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'custom';
+export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'arc' | 'custom';
+/**
+ * The user-facing name of a profile — what `agents browser profiles list`
+ * prints and what `--profile <name>` takes. ALWAYS bare: it never carries an
+ * `@<endpoint>` suffix or a `.<fork>` suffix. `BrowserProfile.name` is one.
+ */
+export type ProfileName = string;
+/**
+ * The key of an endpoint preset within a profile (`endpoint-0`, `local`, …) —
+ * see {@link EndpointPreset} and `getEndpointPresets`.
+ */
+export type EndpointName = string;
+/**
+ * The RUNTIME key a live browser is registered under: `<profile>@<endpoint>`,
+ * plus an optional `.<n>` fork suffix for Electron forks. It keys
+ * `BrowserService.connections`, the profile's runtime dir, its `tasks.json`,
+ * and its capture dirs — so one YAML profile can run at several endpoints
+ * concurrently without colliding on disk.
+ *
+ * It is BRANDED on purpose. Before RUSH-2709 both this and a {@link ProfileName}
+ * were bare `string`s and `start()` overwrote `BrowserProfile.name` with the
+ * composite, so a connection key leaked into every user-facing listing and six
+ * consumers each invented their own rule for turning one back into the other.
+ * The brand makes `connections.get(someProfileName)` — the exact miss behind
+ * `status --profile comet-local` returning EMPTY for a live
+ * `comet-local@endpoint-0` — a compile error. Build one ONLY with
+ * {@link connectionKey} (deriving) or {@link asConnectionKey} (adopting a name
+ * that is already a runtime key, e.g. a directory read off disk).
+ */
+export type ConnectionKey = string & {
+    readonly __connectionKey: unique symbol;
+};
+/** The single site that derives a {@link ConnectionKey} from its two parts. */
+export declare function connectionKey(profile: ProfileName, endpoint: EndpointName): ConnectionKey;
+/**
+ * Adopt a string that IS already a runtime key — a runtime directory name, a
+ * `tasks.json` `profile` field, a fork key. Never use it to launder a bare
+ * profile name into a key; use {@link connectionKey} for that.
+ */
+export declare function asConnectionKey(raw: string): ConnectionKey;
+/**
+ * Split a {@link ConnectionKey} back into its parts. The inverse of
+ * {@link connectionKey}, and the ONE rule every consumer uses to decide whether
+ * a runtime key belongs to a profile.
+ *
+ * Tolerates the legacy shape still on disk: a pre-composite key that is just
+ * the bare profile name (`comet-local`).
+ *
+ * A key with no `@` is read as a WHOLE profile name, never as `<name>.<fork>`,
+ * because nothing constrains a profile's name (`createProfile` checks only for
+ * a duplicate name and a port collision). Reading the trailing digits as a fork
+ * would let `stop --profile chrome` claim the runtime dirs of a separate
+ * profile named `chrome.2` and kill its browser. A fork is only ever created
+ * from a composite base (`forkElectronProfile` appends to a `<p>@<e>` key), so
+ * the `@`-bearing branch below is the one that must understand forks.
+ */
+export declare function parseConnectionKey(key: string): {
+    profile: ProfileName;
+    endpoint?: EndpointName;
+    fork?: number;
+};
+/** True when `key` is a runtime key of `profile`. The only reconciliation rule. */
+export declare function keyBelongsToProfile(key: string, profile: ProfileName): boolean;
 /**
  * A single named endpoint preset within a profile. Lets one profile cover
  * the local + remote variants of the same app (e.g. an Electron app on this
@@ -24,7 +86,12 @@ export interface EndpointPreset {
     targetFilter?: string;
 }
 export interface BrowserProfile {
-    name: string;
+    /**
+     * The user-facing profile name, ALWAYS bare — never `name@endpoint`. The
+     * runtime key that carries the endpoint is a separate value
+     * ({@link ConnectionKey}); nothing may write one here.
+     */
+    name: ProfileName;
     description?: string;
     browser: BrowserType;
     binary?: string;
@@ -84,8 +151,24 @@ export interface Task {
      * short machine id can stay addressable while status stays readable.
      */
     label?: string;
-    profile: string;
+    /**
+     * The RUNTIME key of the browser this task lives on (`<profile>@<endpoint>`),
+     * not the bare profile name — it addresses the runtime dir this task's
+     * `tasks.json` and captures are written under. Use
+     * {@link parseConnectionKey} to get the user-facing name out of it.
+     */
+    profile: ConnectionKey;
     tabs: Record<string, string>;
+    /**
+     * Tabs this task DRIVES but did not create, by shortId — a tab that already
+     * existed in the browser and was reused because the browser cannot open new
+     * ones (Arc: `Target.createTarget` crashes it, #2778/#2786). Every close path
+     * skips these: the task never opened the tab, so closing it on `done` would
+     * take away something that was there first. Same rule `adoptTabShowing`
+     * states for unowned pages, kept when reuse is unavoidable rather than
+     * optional.
+     */
+    borrowedTabs?: string[];
     currentTabId?: string;
     createdAt: number;
     /**
@@ -142,7 +225,16 @@ export interface TabInfo {
     task: string;
 }
 export interface ProfileStatus {
-    name: string;
+    /**
+     * The BARE profile name — what the user passed to `--profile` and what
+     * `status` prints. The endpoint is reported separately in {@link endpoint};
+     * the raw runtime key (if a caller genuinely needs it) is {@link key}.
+     */
+    name: ProfileName;
+    /** Endpoint preset this browser is running at, when the key carries one. */
+    endpoint?: EndpointName;
+    /** The runtime key backing this status: `<profile>@<endpoint>[.<fork>]`. */
+    key?: ConnectionKey;
     running: boolean;
     port?: number;
     pid?: number;

package/dist/lib/browser/types.js

@@ -1,3 +1,54 @@
+/** The single site that derives a {@link ConnectionKey} from its two parts. */
+export function connectionKey(profile, endpoint) {
+    return `${profile}@${endpoint}`;
+}
+/**
+ * Adopt a string that IS already a runtime key — a runtime directory name, a
+ * `tasks.json` `profile` field, a fork key. Never use it to launder a bare
+ * profile name into a key; use {@link connectionKey} for that.
+ */
+export function asConnectionKey(raw) {
+    return raw;
+}
+/**
+ * Split a {@link ConnectionKey} back into its parts. The inverse of
+ * {@link connectionKey}, and the ONE rule every consumer uses to decide whether
+ * a runtime key belongs to a profile.
+ *
+ * Tolerates the legacy shape still on disk: a pre-composite key that is just
+ * the bare profile name (`comet-local`).
+ *
+ * A key with no `@` is read as a WHOLE profile name, never as `<name>.<fork>`,
+ * because nothing constrains a profile's name (`createProfile` checks only for
+ * a duplicate name and a port collision). Reading the trailing digits as a fork
+ * would let `stop --profile chrome` claim the runtime dirs of a separate
+ * profile named `chrome.2` and kill its browser. A fork is only ever created
+ * from a composite base (`forkElectronProfile` appends to a `<p>@<e>` key), so
+ * the `@`-bearing branch below is the one that must understand forks.
+ */
+export function parseConnectionKey(key) {
+    // LAST `@`, not the first: a profile name may itself contain one (`me@work`),
+    // and splitting on the first would report its profile as `me` — so
+    // `status --profile me@work` would find nothing for a running browser.
+    const at = key.lastIndexOf('@');
+    if (at === -1)
+        return { profile: key };
+    const profile = key.slice(0, at);
+    const rest = key.slice(at + 1);
+    const dot = rest.indexOf('.');
+    if (dot === -1)
+        return { profile, endpoint: rest };
+    const fork = Number(rest.slice(dot + 1));
+    return {
+        profile,
+        endpoint: rest.slice(0, dot),
+        fork: Number.isFinite(fork) ? fork : undefined,
+    };
+}
+/** True when `key` is a runtime key of `profile`. The only reconciliation rule. */
+export function keyBelongsToProfile(key, profile) {
+    return parseConnectionKey(key).profile === profile;
+}
 export const TASK_ID_REGEX = /^[a-z0-9][a-z0-9-]*$/;
 export function isValidTaskId(id) {
     return TASK_ID_REGEX.test(id) && id.length <= 64;

package/dist/lib/catchup.js

@@ -38,7 +38,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { readJob, writeRunMeta, getRunDir, } from './scheduling/routines.js';
 import { detectOverdueJobs } from './overdue.js';
-import { executeJobDetached } from './runner.js';
+import { executeJobDetached } from './daemon/runner.js';
 /**
  * Is this routine allowed to run late? Default true — a routine you scheduled
  * is one you expect to have run, so losing a fire silently is never the helpful

package/dist/lib/computer/actions.d.ts

@@ -1,4 +1,4 @@
-import type { ComputerClient } from '../computer-rpc.js';
+import type { ComputerClient } from './computer-rpc.js';
 export interface AppInfo {
     pid: number;
     name: string;

package/dist/lib/computer/actions.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'node:crypto';
-import { resolvePolicyPath } from '../computer-rpc.js';
+import { resolvePolicyPath } from './computer-rpc.js';
 import { COMPUTER_INPUT_GATED_VERBS, formatComputerPermissionGrantHint } from '../permissions.js';
 import { emit as emitEvent } from '../feed/events.js';
 import { recordComputerSession } from '../session/db.js';

package/dist/lib/{computer-rpc.js → computer/computer-rpc.js}

@@ -16,7 +16,7 @@ import { createConnection } from 'net';
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { getHelpersDir, getLogsDir, getUserPermissionsDir, getPermissionsDir } from './state.js';
+import { getHelpersDir, getLogsDir, getUserPermissionsDir, getPermissionsDir } from '../state.js';
 // Resolve the socket path used by the launchd-managed daemon. Internal
 // scratch — lives under getHelpersDir() (~/.agents/.cache/helpers/),
 // matching browser.sock.
@@ -174,10 +174,10 @@ export function writeComputerPeers(allowedExecPaths) {
 export function resolveHelperExec() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        // Local build (running from the agents-cli checkout). apps/cli/dist/lib -> repo root (4 up) -> native/computer-mac.
-        path.resolve(here, '..', '..', '..', '..', 'native', 'computer-mac', 'dist', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
-        // Bundled with the npm package.
-        path.resolve(here, '..', 'computer-helper', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
+        // Local build (running from the agents-cli checkout). apps/cli/dist/lib/computer -> repo root (5 up) -> native/computer-mac.
+        path.resolve(here, '..', '..', '..', '..', '..', 'native', 'computer-mac', 'dist', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
+        // Bundled with the npm package (dist/lib/computer -> dist/).
+        path.resolve(here, '..', '..', 'computer-helper', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
     ];
     for (const c of candidates) {
         if (fs.existsSync(c))

package/dist/lib/computer/dispatch.d.ts

@@ -1,4 +1,4 @@
-import type { ComputerClient } from '../computer-rpc.js';
+import type { ComputerClient } from './computer-rpc.js';
 import { type AppInfo } from './actions.js';
 import type { VerbDispatcher } from './loop.js';
 declare function rpcMethodFor(verb: string): string;

package/dist/lib/computer/download.d.ts

@@ -4,7 +4,7 @@
  *
  * The helper is a signed + notarized universal `.app` bundle published as a
  * GitHub release asset per tagged CLI version — the same distribution model as
- * the Windows helper (see `lib/ssh-tunnel.ts`). A fresh `npm i -g` machine has
+ * the Windows helper (see `lib/computer/ssh-tunnel.ts`). A fresh `npm i -g` machine has
  * no local build, so `agents computer setup` / `agents setup computer` fetch the
  * asset for the running CLI version, verify its sha256 against the published
  * `.sha256`, then verify the code signature (Developer ID Team + notarization)

package/dist/lib/computer/download.js

@@ -4,7 +4,7 @@
  *
  * The helper is a signed + notarized universal `.app` bundle published as a
  * GitHub release asset per tagged CLI version — the same distribution model as
- * the Windows helper (see `lib/ssh-tunnel.ts`). A fresh `npm i -g` machine has
+ * the Windows helper (see `lib/computer/ssh-tunnel.ts`). A fresh `npm i -g` machine has
  * no local build, so `agents computer setup` / `agents setup computer` fetch the
  * asset for the running CLI version, verify its sha256 against the published
  * `.sha256`, then verify the code signature (Developer ID Team + notarization)
@@ -21,8 +21,8 @@ import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { getCacheDir } from '../state.js';
 import { getCliVersion } from '../version.js';
-import { parseSha256Asset, sha256File } from '../ssh-tunnel.js';
-import { resolveHelperApp } from '../computer-rpc.js';
+import { parseSha256Asset, sha256File } from './ssh-tunnel.js';
+import { resolveHelperApp } from './computer-rpc.js';
 /** GitHub repo whose `v<version>` releases carry the helper asset. */
 export const HELPER_RELEASE_REPO = 'phnx-labs/agents-cli';
 /** The zipped `.app` release asset name. */

package/dist/lib/{ssh-tunnel.d.ts → computer/ssh-tunnel.d.ts}

@@ -17,7 +17,7 @@
  *     `devices/connect` primitives — no parallel SSH implementation.
  */
 import { type ChildProcess } from 'child_process';
-import { type DeviceProfile } from './devices/registry.js';
+import { type DeviceProfile } from '../devices/registry.js';
 export interface StartTunnelOptions {
     /**
      * Detach the tunnel so it OUTLIVES this CLI process. Used by

package/dist/lib/{ssh-tunnel.js → computer/ssh-tunnel.js}

@@ -24,14 +24,14 @@ import { fileURLToPath } from 'url';
 import { randomBytes, createHash } from 'crypto';
 import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
-import { sshExec, SSH_OPTS, assertValidSshTarget } from './ssh-exec.js';
-import { backgroundSpawnOptions } from './platform/process.js';
-import { encodePowerShell } from './browser/drivers/ssh.js';
-import { getDevice } from './devices/registry.js';
-import { deviceIdentityArgs, sshTargetFor } from './devices/connect.js';
-import { hostNameFor } from './devices/ssh-config.js';
-import { getCacheDir } from './state.js';
-import { getCliVersion } from './version.js';
+import { sshExec, SSH_OPTS, assertValidSshTarget } from '../ssh-exec.js';
+import { backgroundSpawnOptions } from '../platform/process.js';
+import { encodePowerShell } from '../browser/drivers/ssh.js';
+import { getDevice } from '../devices/registry.js';
+import { deviceIdentityArgs, sshTargetFor } from '../devices/connect.js';
+import { hostNameFor } from '../devices/ssh-config.js';
+import { getCacheDir } from '../state.js';
+import { getCliVersion } from '../version.js';
 import { openComputerClient, resolveTcpEndpoint } from './computer-rpc.js';
 /** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure.
  *
@@ -115,10 +115,10 @@ export const WIN_HELPER_TOKEN_FILE = 'helper-token';
 export function resolveWinHelperExe() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        // Running from the agents-cli checkout. apps/cli/dist/lib -> repo root (4 up) -> native/computer-win.
-        path.resolve(here, '..', '..', '..', '..', 'native', 'computer-win', 'dist', WIN_HELPER_EXE),
-        // Bundled with the npm package (dist/lib -> package root).
-        path.resolve(here, '..', 'computer-helper-win', WIN_HELPER_EXE),
+        // Running from the agents-cli checkout. apps/cli/dist/lib/computer -> repo root (5 up) -> native/computer-win.
+        path.resolve(here, '..', '..', '..', '..', '..', 'native', 'computer-win', 'dist', WIN_HELPER_EXE),
+        // Bundled with the npm package (dist/lib/computer -> dist/).
+        path.resolve(here, '..', '..', 'computer-helper-win', WIN_HELPER_EXE),
     ];
     for (const c of candidates) {
         if (fs.existsSync(c))

package/dist/lib/daemon/daemon.js

@@ -17,7 +17,7 @@ import { listJobs as listAllJobs } from '../scheduling/routines.js';
 import { syncAllProjectRoutines } from '../routines-project.js';
 import { JobScheduler } from '../scheduler.js';
 import { MonitorEngine } from '../monitors/engine.js';
-import { executeJobDetached, monitorRunningJobs, listLiveRoutineChildren } from '../runner.js';
+import { executeJobDetached, monitorRunningJobs, listLiveRoutineChildren } from './runner.js';
 import { detectOverdueJobs, notifyOverdue } from '../overdue.js';
 import { runCatchup } from '../catchup.js';
 import { notifyRoutineStart, notifyRoutineFinish, notifyRoutineStartFailed } from '../routine-notify.js';

package/dist/lib/{runner.d.ts → daemon/runner.d.ts}

@@ -13,12 +13,12 @@
  * limit is detected mid-run (foreground `executeJob` only — detached daemon
  * fires once with the pre-flight pick).
  */
-import type { JobConfig, RunMeta } from './scheduling/routines.js';
-import { readMeta } from './state.js';
-import type { AgentId } from './types.js';
-import { type FallbackEntry } from './exec.js';
-import type { LoopDeps } from './loop.js';
-import { resolveRunVersion, resolveAccountVersion, type RotateResult } from './accounting/rotate.js';
+import type { JobConfig, RunMeta } from '../scheduling/routines.js';
+import { readMeta } from '../state.js';
+import type { AgentId } from '../types.js';
+import { type FallbackEntry } from '../exec.js';
+import type { LoopDeps } from '../loop.js';
+import { resolveRunVersion, resolveAccountVersion, type RotateResult } from '../accounting/rotate.js';
 /** Result of a completed job execution, including metadata and optional report. */
 export interface RunResult {
     meta: RunMeta;
@@ -142,11 +142,11 @@ export declare function pinJobBinary(cmd: string[], agent: AgentId, version: str
  * registry or a real dispatch.
  */
 export declare function assertRoutineAccountLocalForPlacement(config: Pick<JobConfig, 'name' | 'account'>, mode: 'host' | 'cloud', deps?: {
-    account?: import('./account-registry.js').UnifiedAccount | null;
+    account?: import('../account-registry.js').UnifiedAccount | null;
     readMeta?: typeof readMeta;
 }): Promise<void>;
-export declare function dispatchPlacedJob(config: JobConfig, target: import('./routines-placement.js').PlacementTarget, attempt: RoutineAttempt, deps?: {
-    account?: import('./account-registry.js').UnifiedAccount | null;
+export declare function dispatchPlacedJob(config: JobConfig, target: import('../routines-placement.js').PlacementTarget, attempt: RoutineAttempt, deps?: {
+    account?: import('../account-registry.js').UnifiedAccount | null;
     host?: typeof executeJobOnHost;
     cloud?: typeof executeJobOnCloud;
 }): Promise<RunResult | undefined>;
@@ -160,7 +160,7 @@ export declare function buildHostDispatchOptions(config: JobConfig, ctx: {
     remoteCwd: string | undefined;
     runDir: string;
     detached: boolean;
-}): import('./hosts/run-target.js').HostPromptRun;
+}): import('../hosts/run-target.js').HostPromptRun;
 export declare function dispatchesViaAgentsRun(config: Pick<JobConfig, 'workflow' | 'resume'>): boolean;
 /**
  * Merge sandbox/base env with the canonical per-version exec env