@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/auto-pull.js

@@ -1,47 +1,19 @@
-/**
- * Background sync for tracked git repos:
- *   - System repo (~/.agents/.system/) is read-only locally — fast-forward auto-pull is safe.
- *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
- *     `git fetch` and write a status marker. `agents doctor` surfaces these markers
- *     as a "Repo updates" section instead of printing to stderr on every command.
- *     Pulling is left to the user via `agents repo pull`.
- *
- * Public API:
- *   spawnDetachedSync()      — fire-and-forget; never blocks the foreground command.
- *   readRepoBehindMarkers()  — synchronous; reads markers without consuming them.
- *   shouldSkipDetachedSync() — parent-side recency gate (RUSH-2324).
- *   markDetachedSyncComplete() — worker stamps a completed cycle for the parent gate.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { getFetchCacheDir } from './state.js';
 import { backgroundSpawnOptions } from './platform/process.js';
-/**
- * Shared 5-minute recency window for per-repo locks (worker) and the parent
- * spawn gate (RUSH-2324). Worker skips a repo when its lock mtime is younger
- * than this; the parent skips the entire detached spawn when a recent cycle
- * completed or every existing lock is still within the window.
- */
 export const SYNC_LOCK_TTL_MS = 5 * 60 * 1000;
-/** Where lock files and per-repo status markers live. */
 function fetchStateDir() {
     return getFetchCacheDir();
 }
-/** Per-repo lock file path. mtime acts as a recency check. */
 export function lockFilePath(alias, fetchDir) {
     return path.join(fetchDir ?? fetchStateDir(), `${alias}.lock`);
 }
-/** Per-repo status marker path (for user/extras only). */
 export function statusFilePath(alias, fetchDir) {
     return path.join(fetchDir ?? fetchStateDir(), `${alias}.status.json`);
 }
-/**
- * Stamp written at the end of every detached-worker cycle (including the
- * no-target / all-locks-skipped path). Parent `spawnDetachedSync` stats this
- * one file instead of forking a child on every ordinary CLI invocation.
- */
 export function lastSyncStampPath(fetchDir) {
     return path.join(fetchDir ?? fetchStateDir(), '.last-sync');
 }
@@ -53,25 +25,6 @@ function isMtimeFresh(filePath, now, ttlMs) {
         return false;
     }
 }
-/**
- * Whether the parent should skip forking the detached auto-pull worker.
- *
- * True when either:
- *   1. `.last-sync` exists and its mtime is within {@link SYNC_LOCK_TTL_MS}
- *      (a prior cycle completed recently — the common warm path), or
- *   2. the fetch dir has at least one `*.lock` and every lock is still within
- *      the same window (a worker is mid-flight, or a cycle left locks that
- *      still count as fresh).
- *
- * False (spawn) when the stamp is missing/stale and there are no fresh locks
- * — including a missing fetch dir and an empty one. Cheap: one `stat` or one
- * `readdir` + a few `stat`s; never spawns and never reads git.
- *
- * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
- *   production getFetchCacheDir() path.
- * @param now - Override the clock (for tests).
- * @param ttlMs - Override the recency window (for tests).
- */
 export function shouldSkipDetachedSync(fetchDir, now = Date.now(), ttlMs = SYNC_LOCK_TTL_MS) {
     const dir = fetchDir ?? fetchStateDir();
     if (isMtimeFresh(lastSyncStampPath(dir), now, ttlMs))
@@ -88,11 +41,6 @@ export function shouldSkipDetachedSync(fetchDir, now = Date.now(), ttlMs = SYNC_
         return false;
     return locks.every((name) => isMtimeFresh(path.join(dir, name), now, ttlMs));
 }
-/**
- * Record that a detached-worker cycle finished (success, empty targets, or
- * every repo skipped by its lock). Best-effort; a failed write just means the
- * next foreground invocation will re-spawn the worker.
- */
 export function markDetachedSyncComplete(fetchDir) {
     const dir = fetchDir ?? fetchStateDir();
     const stamp = lastSyncStampPath(dir);
@@ -102,32 +50,18 @@ export function markDetachedSyncComplete(fetchDir) {
         fs.writeFileSync(stamp, String(Date.now()));
     }
     catch {
-        /* best-effort */
     }
 }
-/** Spawn the detached worker. No-op when AGENTS_NO_AUTOPULL=1 is set. */
 export function spawnDetachedSync(fetchDir) {
     if (process.env.AGENTS_NO_AUTOPULL === '1')
         return;
-    // RUSH-2324: the spawn itself costs ~7ms mean on a warm box, and the worker
-    // almost always no-ops when a cycle ran in the last five minutes. Inspect
-    // the last-sync stamp + lock mtimes in the parent and skip the fork when
-    // everything is still fresh.
     if (shouldSkipDetachedSync(fetchDir))
         return;
-    // Resolve the worker path relative to the compiled location of this module.
-    // After `tsc`, both files land in the same directory under dist/lib/.
     const here = path.dirname(fileURLToPath(import.meta.url));
     const workerPath = path.join(here, 'auto-pull-worker.js');
     if (!fs.existsSync(workerPath))
         return;
     try {
-        // Scrub AGENTS_BRAND so the background sync always reconciles the FULL
-        // resource set into the shared agent homes. Otherwise a branded foreground
-        // invocation (e.g. `jack …`) would leak its curated/reduced profile into the
-        // detached sync and silently strip skills/plugins for the plain `agents`
-        // user (last-writer-wins on shared homes). Brand curation must stay a
-        // foreground, in-process view — never a background mutation of shared state.
         const { AGENTS_BRAND: _brand, ...unbrandedEnv } = process.env;
         const child = spawn(process.execPath, [workerPath], {
             ...backgroundSpawnOptions(),
@@ -137,21 +71,8 @@ export function spawnDetachedSync(fetchDir) {
         child.unref();
     }
     catch {
-        /* best-effort: never break the foreground command */
     }
 }
-/**
- * Read all current status markers and return those where the local repo is
- * behind upstream. Markers are NOT deleted — they persist until the next
- * background fetch overwrites them with fresh data.
- *
- * Synchronous, cheap (small JSON files). Used by `agents doctor` to surface
- * repo-behind warnings in one place instead of printing to stderr on every
- * command.
- *
- * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
- *   production getFetchCacheDir() path.
- */
 export function readRepoBehindMarkers(fetchDir) {
     const dir = fetchDir ?? fetchStateDir();
     if (!fs.existsSync(dir))

package/dist/lib/beta.d.ts

@@ -1,12 +1,3 @@
-/**
- * User-opt-in beta feature flags.
- *
- * Preview features live in the git-trackable user repo (~/.agents/agents.yaml)
- * when present, and otherwise fall back to the local system state file
- * (~/.agents/.system/agents.yaml). This keeps opt-ins portable for users with a
- * personal agents repo without mixing them into unrelated version capability
- * checks.
- */
 import type { BetaFeatureName } from './types.js';
 export declare const ALL_BETA_FEATURES: readonly ["factory"];
 export declare function getEnabledBetaFeatures(): BetaFeatureName[];

package/dist/lib/beta.js

@@ -1,12 +1,3 @@
-/**
- * User-opt-in beta feature flags.
- *
- * Preview features live in the git-trackable user repo (~/.agents/agents.yaml)
- * when present, and otherwise fall back to the local system state file
- * (~/.agents/.system/agents.yaml). This keeps opt-ins portable for users with a
- * personal agents repo without mixing them into unrelated version capability
- * checks.
- */
 import * as path from 'path';
 import { getAgentsDir, getOptionalUserAgentsDir, readMeta, writeMeta } from './state.js';
 import { readManifest, writeManifest } from './manifest.js';

package/dist/lib/binary-shadow.d.ts

@@ -1,28 +1,6 @@
 export interface AgentsBinaryShadow {
-    /** Path of the shadowing binary as it appears to the caller. */
     path: string;
-    /** Its self-reported version, if we can run it. */
     version?: string;
 }
-/**
- * Whether two path spellings identify the same file.
- *
- * Two spellings of one file rarely compare equal on Windows: `realpathSync` does
- * not expand 8.3 short names, so a path rooted at `os.tmpdir()`
- * (`C:\Users\RUNNER~1\...` on a GitHub runner) never matches the long form
- * (`C:\Users\runneradmin\...`) that `where` reports. Compare by device+inode
- * first and fall back to case-insensitive resolved spellings.
- */
 export declare function sameFile(a: string, b: string): boolean;
-/**
- * Find `agents` installs that are NOT the currently running binary.
- *
- * Checks two sources:
- *   1. The current PATH: if `which agents` / `where agents` resolves to a
- *      different real binary than the one executing this code, it is an active
- *      shadow.
- *   2. Well-known install directories: any executable `agents` whose realpath
- *      differs from the current entry is a latent shadow — it may win under a
- *      different PATH (e.g. the daemon's service-managed PATH).
- */
 export declare function detectAgentsBinaryShadows(currentBin?: string, extraDirs?: readonly string[]): AgentsBinaryShadow[];

package/dist/lib/binary-shadow.js

@@ -1,16 +1,8 @@
-/**
- * Detect `agents` binaries that could shadow the currently running CLI.
- *
- * Scheduled command routines invoke the bare name `agents`. When an older install
- * appears earlier on PATH than the current binary, routines silently run stale
- * code (RUSH-2431). This module finds those shadows so `agents doctor` can warn.
- */
 import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { getAgentsBinPath } from './cli-entry.js';
-/** Realpath of `p`, or `p` itself if it cannot be resolved. */
 function safeRealpath(p) {
     try {
         return fs.realpathSync(p);
@@ -19,15 +11,6 @@ function safeRealpath(p) {
         return p;
     }
 }
-/**
- * Whether two path spellings identify the same file.
- *
- * Two spellings of one file rarely compare equal on Windows: `realpathSync` does
- * not expand 8.3 short names, so a path rooted at `os.tmpdir()`
- * (`C:\Users\RUNNER~1\...` on a GitHub runner) never matches the long form
- * (`C:\Users\runneradmin\...`) that `where` reports. Compare by device+inode
- * first and fall back to case-insensitive resolved spellings.
- */
 export function sameFile(a, b) {
     try {
         const aStat = fs.statSync(a);
@@ -35,24 +18,13 @@ export function sameFile(a, b) {
         if (aStat.dev === bStat.dev && aStat.ino === bStat.ino)
             return true;
     }
-    catch { /* compare their resolved path spellings below */ }
+    catch { }
     const aReal = safeRealpath(a);
     const bReal = safeRealpath(b);
     return process.platform === 'win32'
         ? aReal.toLowerCase() === bReal.toLowerCase()
         : aReal === bReal;
 }
-/**
- * Find `agents` installs that are NOT the currently running binary.
- *
- * Checks two sources:
- *   1. The current PATH: if `which agents` / `where agents` resolves to a
- *      different real binary than the one executing this code, it is an active
- *      shadow.
- *   2. Well-known install directories: any executable `agents` whose realpath
- *      differs from the current entry is a latent shadow — it may win under a
- *      different PATH (e.g. the daemon's service-managed PATH).
- */
 export function detectAgentsBinaryShadows(currentBin = getAgentsBinPath(), extraDirs = defaultWellKnownDirs()) {
     const currentReal = safeRealpath(currentBin);
     const seen = new Set();
@@ -69,10 +41,9 @@ export function detectAgentsBinaryShadows(currentBin = getAgentsBinPath(), extra
                 .trim()
                 .split('\n')[0];
         }
-        catch { /* binary may be unreadable/unrunnable — still report it */ }
+        catch { }
         shadows.push({ path: candidate, version });
     }
-    // Active shadow under the current environment's PATH.
     try {
         const resolver = process.platform === 'win32' ? 'where' : 'which';
         const pathAgents = execFileSync(resolver, ['agents'], { encoding: 'utf-8', env: process.env })
@@ -83,8 +54,7 @@ export function detectAgentsBinaryShadows(currentBin = getAgentsBinPath(), extra
             addIfShadow(pathAgents);
         }
     }
-    catch { /* no `agents` resolved on PATH */ }
-    // Latent shadows in well-known install locations.
+    catch { }
     for (const dir of extraDirs) {
         for (const name of agentBinaryNames()) {
             const candidate = path.join(dir, name);
@@ -92,7 +62,7 @@ export function detectAgentsBinaryShadows(currentBin = getAgentsBinPath(), extra
                 fs.accessSync(candidate, fs.constants.X_OK);
                 addIfShadow(candidate);
             }
-            catch { /* ignore */ }
+            catch { }
         }
     }
     return shadows;

package/dist/lib/boot-profile.d.ts

@@ -1,12 +1,2 @@
-/**
- * Record a named stage boundary. No-op unless `AGENTS_PROFILE_BOOT` is set, so
- * this is free to call unconditionally on the launch path.
- */
 export declare function bootMark(label: string): void;
-/**
- * Print the collected timeline to stderr, once. Called right before the harness
- * child is spawned (the end of the pre-exec window) and again as an
- * `process.on('exit')` backstop for launch paths that error out before spawn.
- * `reason` labels the final boundary (e.g. `spawn`, `exit`).
- */
 export declare function flushBootProfile(reason: string): void;

package/dist/lib/boot-profile.js

@@ -1,39 +1,12 @@
-/**
- * Boot-time profiler for the `agents run` pre-exec phase (PHNX-3585).
- *
- * The AGI EXT "New Claude" boot spends the whole `agents run` wrapper cost
- * BEFORE the harness prints anything — version resolution, account rotation,
- * config sync, login preflight. This module makes that window measurable
- * without a debugger: gate it on `AGENTS_PROFILE_BOOT=1` and the run path
- * stamps named marks, then flushes a per-stage timeline to stderr the instant
- * before the child is spawned (the moment the wrapper's work ends).
- *
- * All marks are `performance.now()` values, which Node measures from
- * `performance.timeOrigin` ≈ process start — so a mark's absolute value is
- * "ms since the `agents` process began", and consecutive marks give the cost
- * of each stage. When the env flag is off, every function here is a couple of
- * cheap branches and pushes nothing, so it is safe to leave wired on the hot
- * path (the committed `scripts/bench-boot.sh` benchmark drives it).
- */
 import { performance } from 'node:perf_hooks';
 const ENABLED = process.env.AGENTS_PROFILE_BOOT === '1' || process.env.AGENTS_PROFILE_BOOT === 'true';
 const marks = [];
 let flushed = false;
-/**
- * Record a named stage boundary. No-op unless `AGENTS_PROFILE_BOOT` is set, so
- * this is free to call unconditionally on the launch path.
- */
 export function bootMark(label) {
     if (!ENABLED)
         return;
     marks.push({ label, at: performance.now() });
 }
-/**
- * Print the collected timeline to stderr, once. Called right before the harness
- * child is spawned (the end of the pre-exec window) and again as an
- * `process.on('exit')` backstop for launch paths that error out before spawn.
- * `reason` labels the final boundary (e.g. `spawn`, `exit`).
- */
 export function flushBootProfile(reason) {
     if (!ENABLED || flushed)
         return;
@@ -41,7 +14,7 @@ export function flushBootProfile(reason) {
     bootMark(reason);
     if (marks.length === 0)
         return;
-    const start = 0; // process start
+    const start = 0;
     const end = marks[marks.length - 1].at;
     const width = Math.max(...marks.map((m) => m.label.length));
     const lines = [];
@@ -54,9 +27,6 @@ export function flushBootProfile(reason) {
     }
     process.stderr.write(lines.join('\n') + '\n');
 }
-// Backstop: a run that exits before reaching the spawn (a login dead-end, a
-// missing install) still emits whatever stages it reached, so the profile is
-// never silently empty.
 if (ENABLED) {
     process.on('exit', () => flushBootProfile('exit'));
 }

package/dist/lib/brand.d.ts

@@ -1,34 +1,14 @@
 import type { BrandConfig } from './types.js';
-/** The default (unbranded) program name. */
 export declare const DEFAULT_CLI_NAME = "agents";
-/**
- * Resolve the name this invocation runs under. The brand shim exports
- * `AGENTS_BRAND`; when unset (a normal `agents`/`ag` call) we are unbranded and
- * everything is byte-identical to before.
- */
 export declare function resolveBrandName(): string;
-/** The active brand name, or null when unbranded. */
 export declare function activeBrandName(): string | null;
-/** True when this process is running under a brand (not the plain `agents` CLI). */
 export declare function isBranded(): boolean;
-/** Names that would clobber an agent CLI shim or the `agents`/`ag` binary. */
 export declare function reservedBrandNames(): Set<string>;
-/** Validate a proposed brand name; returns an error string or null when ok. */
 export declare function validateBrandName(name: string): string | null;
-/** All configured brands, keyed by name. */
 export declare function listBrands(): Record<string, BrandConfig>;
-/** One brand's config, or undefined. */
 export declare function getBrandConfig(name: string): BrandConfig | undefined;
-/**
- * The resource-profile preset name a brand pins, or null. Read on the hot path
- * by resource-profiles.ts to make the active profile brand-scoped.
- */
 export declare function brandProfileName(): string | null;
-/** Built-in top-level commands the active brand has turned off. */
 export declare function disabledCommandsForActiveBrand(): Set<string>;
-/** The preset name a brand owns (one resource profile per brand). */
 export declare function brandPresetName(name: string): string;
-/** Create or replace a brand's config in agents.yaml. */
 export declare function upsertBrand(cfg: BrandConfig): void;
-/** Remove a brand's config (leaves its resource preset unless `purgePreset`). */
 export declare function removeBrand(name: string, purgePreset?: boolean): void;

package/dist/lib/brand.js

@@ -1,61 +1,26 @@
-/**
- * Brand ("white-label") support — let a user run agents-cli under their own
- * personally-named binary (e.g. `jack` instead of `agents`), skinned with their
- * name and pinned to the exact feature set they enable.
- *
- * A brand is minted by `agents setup mine` / `agents setup mine init <name>`, which
- * writes a pure pass-through shim (`~/.agents/.cache/shims/<name>`) that sets
- * `AGENTS_BRAND=<name>` then execs the real agents-cli entrypoint. The entrypoint
- * reads `AGENTS_BRAND` to (a) present its own name/help/errors as the brand, and
- * (b) apply the brand's config: a list of disabled built-in commands plus an
- * optional resource-profile preset that curates skills/plugins/mcp/etc.
- *
- * Brand config lives in `meta.brands[<name>]` (agents.yaml), so it rides
- * `agents repo push/pull` across the fleet like every other user config. The
- * curated resource set reuses the existing resource-profile engine — a brand
- * pins a preset name (`meta.profiles.presets[...]`); see resource-profiles.ts,
- * where the active profile is resolved brand-first.
- */
 import { readMeta, updateMeta } from './state.js';
-// Leaf list only — do NOT import agents.js here. index.ts imports brand on
-// every invocation (resolveBrandName / disabledCommandsForActiveBrand); a
-// static agents import pulls the full agents.ts → versions.ts graph (~90ms)
-// into --version/--help and the secrets-broker hot path (RUSH-2331).
-// reservedBrandNames is only called when minting a brand; AGENT_CLI_COMMANDS
-// is pinned equal to AGENTS[*].cliCommand by agent-cli-commands.test.ts.
 import { AGENT_CLI_COMMANDS } from './agent-cli-commands.js';
-/** The default (unbranded) program name. */
 export const DEFAULT_CLI_NAME = 'agents';
-/** Valid brand names: a letter, then letters/digits/_/- (matches alias rules). */
 const BRAND_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
-/**
- * Resolve the name this invocation runs under. The brand shim exports
- * `AGENTS_BRAND`; when unset (a normal `agents`/`ag` call) we are unbranded and
- * everything is byte-identical to before.
- */
 export function resolveBrandName() {
     const raw = process.env.AGENTS_BRAND?.trim();
     if (raw && BRAND_NAME_PATTERN.test(raw))
         return raw;
     return DEFAULT_CLI_NAME;
 }
-/** The active brand name, or null when unbranded. */
 export function activeBrandName() {
     const name = resolveBrandName();
     return name === DEFAULT_CLI_NAME ? null : name;
 }
-/** True when this process is running under a brand (not the plain `agents` CLI). */
 export function isBranded() {
     return activeBrandName() !== null;
 }
-/** Names that would clobber an agent CLI shim or the `agents`/`ag` binary. */
 export function reservedBrandNames() {
     const reserved = new Set([DEFAULT_CLI_NAME, 'ag']);
     for (const cmd of AGENT_CLI_COMMANDS)
         reserved.add(cmd);
     return reserved;
 }
-/** Validate a proposed brand name; returns an error string or null when ok. */
 export function validateBrandName(name) {
     if (!BRAND_NAME_PATTERN.test(name)) {
         return `Invalid name "${name}". Use a letter, then letters, digits, _ or -.`;
@@ -65,19 +30,12 @@ export function validateBrandName(name) {
     }
     return null;
 }
-/** All configured brands, keyed by name. */
 export function listBrands() {
     return readMeta().brands ?? {};
 }
-/** One brand's config, or undefined. */
 export function getBrandConfig(name) {
     return listBrands()[name];
 }
-/**
- * The active brand's config (from AGENTS_BRAND), or null when unbranded or when
- * the brand is explicitly disabled (`enabled: false`) — a disabled brand's shim
- * still works as a plain pass-through but applies no command/resource curation.
- */
 function getActiveBrandConfig() {
     const name = activeBrandName();
     if (!name)
@@ -87,24 +45,17 @@ function getActiveBrandConfig() {
         return null;
     return cfg;
 }
-/**
- * The resource-profile preset name a brand pins, or null. Read on the hot path
- * by resource-profiles.ts to make the active profile brand-scoped.
- */
 export function brandProfileName() {
     const cfg = getActiveBrandConfig();
     return cfg?.profile ?? null;
 }
-/** Built-in top-level commands the active brand has turned off. */
 export function disabledCommandsForActiveBrand() {
     const cfg = getActiveBrandConfig();
     return new Set(cfg?.disabledCommands ?? []);
 }
-/** The preset name a brand owns (one resource profile per brand). */
 export function brandPresetName(name) {
     return `mine-${name}`;
 }
-/** Create or replace a brand's config in agents.yaml. */
 export function upsertBrand(cfg) {
     updateMeta((meta) => {
         const brands = { ...(meta.brands ?? {}) };
@@ -112,7 +63,6 @@ export function upsertBrand(cfg) {
         return { ...meta, brands };
     });
 }
-/** Remove a brand's config (leaves its resource preset unless `purgePreset`). */
 export function removeBrand(name, purgePreset = false) {
     updateMeta((meta) => {
         const brands = { ...(meta.brands ?? {}) };

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

@@ -1,46 +1,11 @@
-/**
- * context.ts — everything agents-cli knows that the standalone `browser` engine
- * cannot work out for itself, serialized as one JSON object onto fd 3.
- *
- * This is the whole contract of the consumer half (browser-cli integration
- * contract §1). The engine accepts exactly this shape:
- *
- *   version        `1`. The engine matches on it; a field added later must be
- *                  optional so an older engine keeps working.
- *   target         the `--device <name>` target, resolved against the fleet:
- *                  device registry, ssh identity, platform. The engine matches
- *                  its own `--device <alias>` against this instead of reading a
- *                  registry it does not have, then falls back to `~/.ssh/config`.
- *                  Absent for a local invocation.
- *   session        who is acting — actor id and agent session — so an action
- *                  lands in the right session history.
- *   remoteControl  whether THIS machine consents to being driven by a peer.
- *                  agents-cli owns the policy; browser-cli enforces the flag.
- *
- * WHAT IS DELIBERATELY NOT HERE. The CDP/BiDi/Arc endpoint, the IPC socket, the
- * chrome-data store and the profile declarations are the ENGINE's: browser-cli
- * keeps every on-disk path the in-repo subsystem used (integration contract §4)
- * and hydrates its own transport from them. agents-cli publishing an endpoint
- * here would be a second, drifting copy of that answer.
- *
- * The context is PUSHED (written and closed) rather than exposed as a callback,
- * so the engine never re-enters agents-cli and there is exactly one direction of
- * dependency.
- */
-/** A `--device <name>` target, resolved against the fleet. */
 export interface BrowserTargetContext {
-    /** The device name as the user typed it. */
     alias: string;
-    /** `user@host`, already validated against ssh option injection. */
     host: string;
     user: string;
-    /** Bare host — the ssh-config Host name or address, without the user. */
     hostname: string;
     platform: string;
-    /** Per-device ssh identity flags, in argv order. Possibly empty. */
     sshArgs: string[];
 }
-/** Who is acting, so the engine can stamp the action it reports back. */
 interface BrowserSessionContext {
     sessionId?: string;
     launchId?: string;
@@ -54,29 +19,10 @@ interface BrowserContext {
         allowed: boolean;
     };
 }
-/**
- * Whether this machine allows other fleet machines to drive its browser. Reads
- * the device-scope `browser.remote-control` config key. Unset = off (deny).
- * browser-cli reads and writes the same key, so a `remote-control on` typed at
- * either surface agrees.
- */
 export declare function remoteControlEnabled(): boolean;
 interface BuildContextOptions {
-    /** `--device <name>`, if given (only meaningful on `start`). */
     device?: string;
-    /**
-     * A precomputed target, when the caller already resolved the device. When
-     * present, `device` need not be re-resolved.
-     */
     target?: BrowserTargetContext;
 }
-/**
- * Resolve `--device <name>` to a fleet target and build the context handed to
- * the engine on fd 3.
- *
- * Unlike `agents computer`, browser drives ANY platform, so `resolveRemoteDevice`
- * is called with no platform expectation — a `--device` pointing at a Mac, Linux
- * box or Windows host all resolve.
- */
 export declare function buildBrowserContext(opts?: BuildContextOptions): Promise<BrowserContext>;
 export {};

package/dist/lib/browser/context.js

@@ -1,39 +1,6 @@
-/**
- * context.ts — everything agents-cli knows that the standalone `browser` engine
- * cannot work out for itself, serialized as one JSON object onto fd 3.
- *
- * This is the whole contract of the consumer half (browser-cli integration
- * contract §1). The engine accepts exactly this shape:
- *
- *   version        `1`. The engine matches on it; a field added later must be
- *                  optional so an older engine keeps working.
- *   target         the `--device <name>` target, resolved against the fleet:
- *                  device registry, ssh identity, platform. The engine matches
- *                  its own `--device <alias>` against this instead of reading a
- *                  registry it does not have, then falls back to `~/.ssh/config`.
- *                  Absent for a local invocation.
- *   session        who is acting — actor id and agent session — so an action
- *                  lands in the right session history.
- *   remoteControl  whether THIS machine consents to being driven by a peer.
- *                  agents-cli owns the policy; browser-cli enforces the flag.
- *
- * WHAT IS DELIBERATELY NOT HERE. The CDP/BiDi/Arc endpoint, the IPC socket, the
- * chrome-data store and the profile declarations are the ENGINE's: browser-cli
- * keeps every on-disk path the in-repo subsystem used (integration contract §4)
- * and hydrates its own transport from them. agents-cli publishing an endpoint
- * here would be a second, drifting copy of that answer.
- *
- * The context is PUSHED (written and closed) rather than exposed as a callback,
- * so the engine never re-enters agents-cli and there is exactly one direction of
- * dependency.
- */
 import { resolveActor } from '../actor.js';
 import { resolveRemoteDevice } from '../ssh-tunnel.js';
 import { getConfigValue } from '../device-config.js';
-/**
- * Which agent session is acting. The harness-native id first, then agents' own —
- * the same precedence `lib/computer/context.ts` uses.
- */
 function agentSessionId(env = process.env) {
     return env.CODEX_THREAD_ID
         || env.CLAUDE_CODE_SESSION_ID
@@ -43,23 +10,9 @@ function agentSessionId(env = process.env) {
         || env.AGENTS_RUN_ID
         || undefined;
 }
-/**
- * Whether this machine allows other fleet machines to drive its browser. Reads
- * the device-scope `browser.remote-control` config key. Unset = off (deny).
- * browser-cli reads and writes the same key, so a `remote-control on` typed at
- * either surface agrees.
- */
 export function remoteControlEnabled() {
     return getConfigValue('browser.remote-control').value === true;
 }
-/**
- * Resolve `--device <name>` to a fleet target and build the context handed to
- * the engine on fd 3.
- *
- * Unlike `agents computer`, browser drives ANY platform, so `resolveRemoteDevice`
- * is called with no platform expectation — a `--device` pointing at a Mac, Linux
- * box or Windows host all resolve.
- */
 export async function buildBrowserContext(opts = {}) {
     let target = opts.target;
     if (!target && opts.device && opts.device !== 'local') {
@@ -75,8 +28,6 @@ export async function buildBrowserContext(opts = {}) {
     }
     return {
         version: 1,
-        // Spread rather than assigned: a local invocation must not ship a `target`
-        // key at all, so the engine never has to distinguish absent from null.
         ...(target ? { target } : {}),
         session: {
             sessionId: agentSessionId(),