@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/computer-client.d.ts

@@ -1,51 +1,4 @@
-/**
- * computer-client.ts — the ONE process client through which agents-cli talks to
- * the standalone `computer` CLI (PHNX-4075).
- *
- * This is the agents-owned half of the computer extraction, and it is
- * deliberately small. agents-cli no longer carries a helper daemon, an RPC
- * transport, an element cache, an RFB client, or an autonomous loop — the
- * standalone engine owns all of it, exactly as `secrets` took the keychain
- * engine (PHNX-3989) and `sessions` took the transcript engine (PHNX-4012).
- * What stays here is what only the fleet CLI can know: which apps the
- * permissions layer allows, which device a `--device` name resolves to, who the
- * acting session is, and where an action must be recorded.
- *
- * THERE IS NO FALLBACK. A missing executable throws `COMPUTER_BIN_MISSING` with
- * install guidance (DIST-1) rather than silently driving a bundled engine —
- * agents-cli has none to drive, and a fallback would re-couple the two release
- * trains this extraction exists to separate.
- *
- * Transport — inherited-fd passthrough, not request/response:
- *
- * The engine's ENVIRONMENT is inherited verbatim — no overlay. Transport
- * selection (`COMPUTER_HELPER_TCP`, `COMPUTER_HELPER_VNC`,
- * `COMPUTER_HELPER_SOCKET`) is the engine's: it opens the `--device` tunnel and
- * hydrates its own endpoint AND the auth token that goes with it. Publishing a
- * bare endpoint from here would hand the daemon a connection it then rejects
- * with `auth_failed`.
- *
- *   - stdio 0/1/2 are INHERITED. The engine owns the user's terminal: its
- *     stdout is the command's stdout, its `--json` is the command's `--json`,
- *     its prompts reach a real tty. agents-cli never re-formats engine output,
- *     which is what keeps the surface honest as the engine evolves.
- *   - fd 3 (`COMPUTER_CONTEXT_FD`) carries ONE JSON object — the consumer
- *     context built by `lib/computer/context.ts` — written and closed
- *     immediately, so the engine reads to EOF and proceeds.
- *   - fd 4 (`COMPUTER_EVENTS_FD`) carries NDJSON action events back: one JSON
- *     object per line, each an action the engine actually performed. agents-cli
- *     turns those into feed events and `sessions --computer` history
- *     (`lib/computer/record.ts`). The engine may emit none; it must never block
- *     on this pipe.
- *
- * Both fds are anonymous pipes on the child's side, the same shape
- * `secrets-client.ts` settled on after a named FIFO wedged macOS reads. The
- * context is pushed rather than pulled so the engine needs no callback into
- * agents-cli — one direction each way, no reentrancy.
- */
-/** fd the engine reads its one-shot JSON context from. */
 export declare const COMPUTER_CONTEXT_FD = 3;
-/** fd the engine writes NDJSON action events to. */
 export declare const COMPUTER_EVENTS_FD = 4;
 export declare class ComputerClientError extends Error {
     code: string;
@@ -53,98 +6,39 @@ export declare class ComputerClientError extends Error {
 }
 export declare function isComputerClientError(err: unknown): err is ComputerClientError;
 export declare function isStandaloneComputer(bin: string): boolean;
-/**
- * Resolve the standalone executable. `COMPUTER_BIN` wins so a dev build can be
- * driven without touching PATH.
- *
- * Resolution uses `findInPath`, which skips `~/.agents/.cache/shims`. That skip
- * is load-bearing here for the same reason it is in `sessions-client.ts`: a
- * leftover `computer` alias shim execs `agents computer`, and resolving it would
- * recurse into this process (the 1.22.85 secrets fork bomb, agi-cli#3532).
- */
 export declare function resolveComputerBin(): string;
-/** A `.js` bin is run through this runtime; a real executable is exec'd directly. */
 export declare function invocation(bin: string): {
     command: string;
     prefix: string[];
 };
-/**
- * One action the engine performed, as it appears on the NDJSON events fd.
- *
- * This is the engine's wire shape, not a translation of it: the engine emits
- * `{event: "computer.action", command, invocationId, pid, targetPid, bundle,
- * host, task, sessionId, launchId, actor}`. `command` — not `verb` — is the
- * field that names the action, and it is what marks a line as an action event.
- */
 export interface ComputerActionEvent {
-    /** Always `computer.action` on this stream. */
     event?: string;
-    /** The verb the engine ran (`click`, `type`, `screenshot`, …). */
     command: string;
-    /** The engine's own id for this run — the grouping key for a session row. */
     invocationId?: string;
-    /** The engine process's pid. */
     pid?: number;
-    /** pid of the app the action targeted, when the engine resolved one. */
     targetPid?: number;
-    /** Bundle id / app identifier the action targeted. */
     bundle?: string;
-    /** The driven device for a `--device` invocation; absent when local. */
     host?: string;
-    /** `run --task` description, only on the task marker. */
     task?: string;
-    /** Identity, echoed back from the context this CLI handed the engine. */
     sessionId?: string;
     launchId?: string;
     actor?: string;
-    /** Free-form detail the engine attaches (coordinates, text length, …). */
     [key: string]: unknown;
 }
-/**
- * Split a growing buffer into complete NDJSON lines. Pure so the framing rules —
- * blank lines skipped, a non-JSON line dropped rather than crashing the CLI, a
- * trailing partial line carried forward — are unit-testable without a spawn.
- *
- * A malformed line is dropped, not thrown: these events are telemetry riding
- * alongside a user-visible action that already happened. Failing the command
- * because its receipt was unreadable would be strictly worse than losing the
- * receipt. The action itself already failed loud on its own channel if it failed.
- */
 export declare function parseEventLines(buffer: string): {
     events: ComputerActionEvent[];
     rest: string;
 };
 interface RunComputerOptions {
-    /** argv handed to the standalone, after the program name. */
     argv: string[];
-    /** The consumer context serialized onto fd 3. */
     context: unknown;
-    /** Called once per action event the engine reports on fd 4. */
     onEvent?: (event: ComputerActionEvent) => void;
-    /**
-     * Capture the engine's stdout instead of inheriting the terminal.
-     *
-     * Used only where agents-cli must READ an answer rather than show it — the
-     * `agents setup computer` wizard polling `status --json` for trust. Verbs
-     * never capture: re-printing engine output would make agents-cli a formatter
-     * for a surface it no longer owns.
-     */
     capture?: boolean;
 }
 interface RunComputerResult {
     exitCode: number;
-    /** Engine stdout, only when `capture` was set. */
     stdout: string;
 }
-/**
- * Run the standalone engine with the consumer context on fd 3 and the action
- * event stream on fd 4. Resolves with the engine's exit code; the caller
- * propagates it so `agents computer` exits exactly as the engine did.
- *
- * Throws `COMPUTER_BIN_MISSING` when the standalone is not installed. Every
- * other failure is the engine's own, reported on the inherited stderr.
- */
 export declare function runComputer(opts: RunComputerOptions): Promise<RunComputerResult>;
-/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
 export declare function _resetComputerClientForTest(): void;
 export {};

package/dist/lib/computer-client.js

@@ -1,56 +1,13 @@
-/**
- * computer-client.ts — the ONE process client through which agents-cli talks to
- * the standalone `computer` CLI (PHNX-4075).
- *
- * This is the agents-owned half of the computer extraction, and it is
- * deliberately small. agents-cli no longer carries a helper daemon, an RPC
- * transport, an element cache, an RFB client, or an autonomous loop — the
- * standalone engine owns all of it, exactly as `secrets` took the keychain
- * engine (PHNX-3989) and `sessions` took the transcript engine (PHNX-4012).
- * What stays here is what only the fleet CLI can know: which apps the
- * permissions layer allows, which device a `--device` name resolves to, who the
- * acting session is, and where an action must be recorded.
- *
- * THERE IS NO FALLBACK. A missing executable throws `COMPUTER_BIN_MISSING` with
- * install guidance (DIST-1) rather than silently driving a bundled engine —
- * agents-cli has none to drive, and a fallback would re-couple the two release
- * trains this extraction exists to separate.
- *
- * Transport — inherited-fd passthrough, not request/response:
- *
- * The engine's ENVIRONMENT is inherited verbatim — no overlay. Transport
- * selection (`COMPUTER_HELPER_TCP`, `COMPUTER_HELPER_VNC`,
- * `COMPUTER_HELPER_SOCKET`) is the engine's: it opens the `--device` tunnel and
- * hydrates its own endpoint AND the auth token that goes with it. Publishing a
- * bare endpoint from here would hand the daemon a connection it then rejects
- * with `auth_failed`.
- *
- *   - stdio 0/1/2 are INHERITED. The engine owns the user's terminal: its
- *     stdout is the command's stdout, its `--json` is the command's `--json`,
- *     its prompts reach a real tty. agents-cli never re-formats engine output,
- *     which is what keeps the surface honest as the engine evolves.
- *   - fd 3 (`COMPUTER_CONTEXT_FD`) carries ONE JSON object — the consumer
- *     context built by `lib/computer/context.ts` — written and closed
- *     immediately, so the engine reads to EOF and proceeds.
- *   - fd 4 (`COMPUTER_EVENTS_FD`) carries NDJSON action events back: one JSON
- *     object per line, each an action the engine actually performed. agents-cli
- *     turns those into feed events and `sessions --computer` history
- *     (`lib/computer/record.ts`). The engine may emit none; it must never block
- *     on this pipe.
- *
- * Both fds are anonymous pipes on the child's side, the same shape
- * `secrets-client.ts` settled on after a named FIFO wedged macOS reads. The
- * context is pushed rather than pulled so the engine needs no callback into
- * agents-cli — one direction each way, no reentrancy.
- */
+/* Thin client for the standalone computer CLI: no bundled fallback or duplicate engine. */
+/* stdio is inherited; fd3 sends one context object and fd4 receives NDJSON action events. */
+/* Anonymous one-way pipes avoid credentials in endpoint metadata and named-FIFO deadlocks. */
+/* Pass env unchanged: the engine owns the tunnel endpoint and matching auth; agents-cli must not publish a bare endpoint. */
 import { spawn } from 'node:child_process';
 import { realpathSync, existsSync } from 'node:fs';
 import * as path from 'node:path';
 import { findInPath } from './agent-spec/agents.js';
 const INSTALL_HINT = 'npm i -g @phnx-labs/computer-cli';
-/** fd the engine reads its one-shot JSON context from. */
 export const COMPUTER_CONTEXT_FD = 3;
-/** fd the engine writes NDJSON action events to. */
 export const COMPUTER_EVENTS_FD = 4;
 export class ComputerClientError extends Error {
     code;
@@ -75,18 +32,9 @@ export function isStandaloneComputer(bin) {
     try {
         real = realpathSync(real);
     }
-    catch { /* spawn reports missing explicit paths */ }
+    catch { }
     return !/\.(cmd|ps1)$/i.test(real) && !real.endsWith(path.join('dist', 'computer.js'));
 }
-/**
- * Resolve the standalone executable. `COMPUTER_BIN` wins so a dev build can be
- * driven without touching PATH.
- *
- * Resolution uses `findInPath`, which skips `~/.agents/.cache/shims`. That skip
- * is load-bearing here for the same reason it is in `sessions-client.ts`: a
- * leftover `computer` alias shim execs `agents computer`, and resolving it would
- * recurse into this process (the 1.22.85 secrets fork bomb, agi-cli#3532).
- */
 export function resolveComputerBin() {
     if (cachedBin)
         return cachedBin;
@@ -100,22 +48,11 @@ export function resolveComputerBin() {
     cachedBin = computerEntrypoint(resolved);
     return cachedBin;
 }
-/** A `.js` bin is run through this runtime; a real executable is exec'd directly. */
 export function invocation(bin) {
     if (/\.[mc]?js$/.test(bin))
         return { command: process.execPath, prefix: [bin] };
     return { command: bin, prefix: [] };
 }
-/**
- * Split a growing buffer into complete NDJSON lines. Pure so the framing rules —
- * blank lines skipped, a non-JSON line dropped rather than crashing the CLI, a
- * trailing partial line carried forward — are unit-testable without a spawn.
- *
- * A malformed line is dropped, not thrown: these events are telemetry riding
- * alongside a user-visible action that already happened. Failing the command
- * because its receipt was unreadable would be strictly worse than losing the
- * receipt. The action itself already failed loud on its own channel if it failed.
- */
 export function parseEventLines(buffer) {
     const events = [];
     const parts = buffer.split('\n');
@@ -131,19 +68,10 @@ export function parseEventLines(buffer) {
             }
         }
         catch {
-            // Unreadable receipt — see above.
         }
     }
     return { events, rest };
 }
-/**
- * Run the standalone engine with the consumer context on fd 3 and the action
- * event stream on fd 4. Resolves with the engine's exit code; the caller
- * propagates it so `agents computer` exits exactly as the engine did.
- *
- * Throws `COMPUTER_BIN_MISSING` when the standalone is not installed. Every
- * other failure is the engine's own, reported on the inherited stderr.
- */
 export async function runComputer(opts) {
     const bin = resolveComputerBin();
     const { command, prefix } = invocation(bin);
@@ -158,8 +86,6 @@ export async function runComputer(opts) {
     const contextPipe = child.stdio[COMPUTER_CONTEXT_FD];
     const eventsPipe = child.stdio[COMPUTER_EVENTS_FD];
     if (contextPipe) {
-        // An engine that exits before reading the context (bad argv, `--help`)
-        // closes fd 3 and we get EPIPE. That is a normal race, not a failure.
         contextPipe.on('error', () => { });
         contextPipe.end(JSON.stringify(opts.context) + '\n');
     }
@@ -183,7 +109,6 @@ export async function runComputer(opts) {
         });
         eventsPipe.on('error', () => resolve());
         eventsPipe.on('end', () => {
-            // A final line with no trailing newline still counts.
             const { events } = parseEventLines(pending.endsWith('\n') ? pending : pending + '\n');
             pending = '';
             for (const event of events)
@@ -196,8 +121,6 @@ export async function runComputer(opts) {
             reject(new ComputerClientError('COMPUTER_SPAWN_FAILED', `Could not run \`${bin}\`: ${err.message}`));
         });
         child.on('close', (code, signal) => {
-            // A signalled child has no exit code; report the conventional 128+n so
-            // callers and shells see a non-zero status instead of a false success.
             if (code == null)
                 return resolve(signal ? 128 + (osSignalNumber(signal) ?? 0) : 1);
             resolve(code);
@@ -206,16 +129,12 @@ export async function runComputer(opts) {
     await drained;
     return { exitCode, stdout };
 }
-/** Signal name → number for the 128+n exit convention. Only the ones a tunnelled
- * or interrupted engine realistically dies on; anything else contributes 0 and
- * still yields a non-zero status. */
 function osSignalNumber(signal) {
     const table = {
         SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGPIPE: 13, SIGTERM: 15,
     };
     return table[signal];
 }
-/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
 export function _resetComputerClientForTest() {
     cachedBin = undefined;
 }

package/dist/lib/concurrency.d.ts

@@ -1,19 +1,5 @@
-/**
- * Bounded, order-preserving async mapper.
- *
- * Runs `fn` over `items` with at most `concurrency` calls in flight, and — when
- * `staggerMs` is set — spaces successive task starts at least that far apart so
- * spawns trickle out instead of firing as one simultaneous burst. Results come
- * back in input order regardless of completion order.
- *
- * The stagger matters beyond scheduling: a burst of identical child spawns (per-PID
- * `lsof`, multi-dotfile scans) reads to behavioral EDR as recon/enumeration. A
- * bounded, spread-out spawn rate produces the same data without the burst signature.
- */
 interface BoundedMapOptions {
-    /** Maximum number of `fn` calls running at once. Coerced to >= 1. */
     concurrency: number;
-    /** Minimum spacing (ms) between successive task starts. 0 (default) = no spacing. */
     staggerMs?: number;
 }
 export declare function mapBounded<T, R>(items: readonly T[], fn: (item: T, index: number) => Promise<R>, opts: BoundedMapOptions): Promise<R[]>;

package/dist/lib/concurrency.js

@@ -8,9 +8,6 @@ export async function mapBounded(items, fn, opts) {
     if (items.length === 0)
         return results;
     let cursor = 0;
-    // Shared gate: the earliest time the next task is allowed to start. Updated
-    // atomically (no await between read and write) so parallel workers each claim
-    // a distinct slot spaced `stagger` apart.
     let nextStart = 0;
     async function worker() {
         for (;;) {

package/dist/lib/config-drift.d.ts

@@ -1,37 +1,6 @@
-/**
- * Config drift: has THIS box drained its device-scoped state into its own
- * `devices/<host>/agents.yaml`, or is it still carrying per-box state in the
- * shared top-level `agents.yaml`?
- *
- * PHNX-3315 P1 heals a frozen top-level header and drains the central `browser:`
- * tombstone; P2 folds `fleet.discovery` / `fleet.ignored`, the `hosts:` registry,
- * and device-scoped native `accounts:` out of central and into the device doc.
- * Each fold-and-delete migration is idempotent and runs on config access / daemon
- * boot / install — so a converged box shows NO drift. A box that has NOT run the
- * fold yet (stale checkout, never re-synced) still holds those blocks centrally,
- * and until now that was INVISIBLE: `agents sync status` only reported per-agent
- * "N missing", so an un-drained box was discovered the hard way — as a mystery
- * `agents repo pull` conflict when two boxes rewrote the same shared map.
- *
- * This detector is READ-ONLY and must NOT trigger the migration (that would drain
- * the very leak it is trying to surface): it reads the raw top-level user file
- * directly, never `readMeta()` (system-merged) and never the migration hook.
- */
 export interface ConfigDrift {
-    /** Top-level `agents.yaml` header != the current META_HEADER (the P1 case). */
     staleHeader: boolean;
-    /**
-     * Labels of central blocks that should have folded into this box's device doc
-     * but still linger — the P1 `browser` tombstone and the P2 `fleet` / `hosts` /
-     * `accounts` device-scoped writers. Empty on a drained box.
-     */
     centralLeaks: string[];
 }
-/**
- * Inspect this box's on-disk state for config drift. Pure read — no migration, no
- * writes. Mirrors the gather step of {@link migrateDeviceConfigStores} (plus the
- * browser tombstone) so a leak here is exactly what a fold would drain.
- */
 export declare function detectConfigDrift(): ConfigDrift;
-/** True when either drift class is present. */
 export declare function hasConfigDrift(d: ConfigDrift): boolean;

package/dist/lib/config-drift.js

@@ -1,42 +1,15 @@
-/**
- * Config drift: has THIS box drained its device-scoped state into its own
- * `devices/<host>/agents.yaml`, or is it still carrying per-box state in the
- * shared top-level `agents.yaml`?
- *
- * PHNX-3315 P1 heals a frozen top-level header and drains the central `browser:`
- * tombstone; P2 folds `fleet.discovery` / `fleet.ignored`, the `hosts:` registry,
- * and device-scoped native `accounts:` out of central and into the device doc.
- * Each fold-and-delete migration is idempotent and runs on config access / daemon
- * boot / install — so a converged box shows NO drift. A box that has NOT run the
- * fold yet (stale checkout, never re-synced) still holds those blocks centrally,
- * and until now that was INVISIBLE: `agents sync status` only reported per-agent
- * "N missing", so an un-drained box was discovered the hard way — as a mystery
- * `agents repo pull` conflict when two boxes rewrote the same shared map.
- *
- * This detector is READ-ONLY and must NOT trigger the migration (that would drain
- * the very leak it is trying to surface): it reads the raw top-level user file
- * directly, never `readMeta()` (system-merged) and never the migration hook.
- */
 import { hasStaleMetaHeader, readTopLevelUserMeta } from './state.js';
 function isMap(v) {
     return !!v && typeof v === 'object' && !Array.isArray(v);
 }
-/**
- * Inspect this box's on-disk state for config drift. Pure read — no migration, no
- * writes. Mirrors the gather step of {@link migrateDeviceConfigStores} (plus the
- * browser tombstone) so a leak here is exactly what a fold would drain.
- */
 export function detectConfigDrift() {
     const staleHeader = hasStaleMetaHeader();
     const raw = readTopLevelUserMeta();
     const centralLeaks = [];
     if (raw) {
-        // P1: the leftover central `browser:` tombstone (should fold into deviceBrowser).
         if (isMap(raw.browser) && Object.keys(raw.browser).length > 0) {
             centralLeaks.push('browser');
         }
-        // P2: fleet.discovery / fleet.ignored, and the short-lived per-device config
-        // store under fleet.devices.<name>.config — all fold into the device doc.
         const fleet = isMap(raw.fleet) ? raw.fleet : undefined;
         if (fleet) {
             if (isMap(fleet.discovery) && Object.keys(fleet.discovery).length > 0) {
@@ -51,13 +24,9 @@ export function detectConfigDrift() {
                     centralLeaks.push('fleet.devices.*.config');
             }
         }
-        // P2: the central `hosts:` registry (should fold into deviceHosts).
         if (isMap(raw.hosts) && Object.keys(raw.hosts).length > 0) {
             centralLeaks.push('hosts');
         }
-        // P2: central native accounts marked scope:'device' — identity PII that
-        // belongs in the device doc, off the git-tracked shared file. Fleet-shared /
-        // version-scoped identities stay central and are NOT a leak.
         const accounts = isMap(raw.accounts) ? raw.accounts : undefined;
         const native = accounts && isMap(accounts.native) ? accounts.native : undefined;
         if (native && Object.values(native).some((a) => isMap(a) && a.scope === 'device')) {
@@ -66,7 +35,6 @@ export function detectConfigDrift() {
     }
     return { staleHeader, centralLeaks };
 }
-/** True when either drift class is present. */
 export function hasConfigDrift(d) {
     return d.staleHeader || d.centralLeaks.length > 0;
 }

package/dist/lib/config-keys.d.ts

@@ -1,23 +1,7 @@
-/**
- * Unified config key grammar for `agents config`.
- *
- * Translates user-facing dotted keys like `run.claude@*.tier.best` into the
- * existing storage locations (run.defaults, model.tiers, config.*,
- * defaultBrowserProfile, deviceConfig.*) so the new command barrel can sit on
- * top of the current YAML schema without a migration.
- */
 import type { AgentId } from './types.js';
 import { type ModelTier } from './model-tiers.js';
-/** The top-level scope of a unified config key. */
 export type ConfigScope = 'run' | 'interactive' | 'auto' | 'browser' | 'project' | 'device' | 'summarizer' | 'updates' | 'menubar';
-/**
- * The AGI Menu preference leaf names under `menubar.menu.*` (PHNX-3999). The
- * types, defaults, and enum validation for each live in `device-config.ts`'s
- * CONFIG_KEYS (user scope); this list is only the parser's allow-set so an
- * unknown `menubar.menu.<x>` fails loud here instead of at the store.
- */
-export declare const MENUBAR_MENU_PROPERTIES: readonly ["defaultProject", "workingRowsShown", "showPreviews", "projectPriorityFilter", "hideCompletedMilestones", "bannerWhenNeedsYou", "includeOtherDeviceRequests", "groupBy", "thenBy", "projectScope", "projectSort", "ticketSort", "showPullRequests", "sessionUpdates", "deviceSort", "headlessAgent", "headlessFallbackAgent", "headlessPlacement"];
-/** A run-time default key: model, mode, effort, or tier override. */
+export declare const MENUBAR_MENU_PROPERTIES: readonly ["defaultProject", "workingRowsShown", "showPreviews", "projectPriorityFilter", "hideCompletedMilestones", "bannerWhenNeedsYou", "includeOtherDeviceRequests", "groupBy", "thenBy", "projectScope", "projectSort", "ticketSort", "showPullRequests", "sessionUpdates", "deviceSort", "headlessAgent", "headlessFallbackAgent", "headlessPlacement", "pinnedProjects", "tabOrder", "hiddenTabs", "groupTicketsByMilestone", "prGroupOpen", "prGroupMerged"];
 export interface ParsedRunConfigKey {
     scope: 'run';
     agent: AgentId;
@@ -25,19 +9,14 @@ export interface ParsedRunConfigKey {
     property: 'model' | 'mode' | 'effort' | 'tier';
     tier?: ModelTier;
 }
-/** The interactive host pin. */
 export interface ParsedInteractiveConfigKey {
     scope: 'interactive';
     property: 'host';
 }
-/** Which devices automatic placement (`--device auto`) may pick. */
 export interface ParsedAutoConfigKey {
     scope: 'auto';
     property: 'pool';
 }
-/** A browser key: the profile agents drive or the browser that shows the user a
- *  page (both device-scope, self or peer), or `device` — the user-scope fleet
- *  hub every box drives by default, which is central and never peer-targeted. */
 export interface ParsedBrowserConfigKey {
     scope: 'browser';
     property: 'profile' | 'viewer' | 'device';
@@ -47,72 +26,29 @@ export interface ParsedProjectConfigKey {
     scope: 'project';
     property: 'root';
 }
-/** A per-device configuration key. */
 export interface ParsedDeviceConfigKey {
     scope: 'device';
     device: string;
     property: DeviceConfigProperty;
 }
-/** The daemon session-summarizer keys (PHNX-3939). */
 export interface ParsedSummarizerConfigKey {
     scope: 'summarizer';
     property: 'enabled' | 'baseUrl' | 'model';
 }
-/**
- * The managed-harness auto-update switch (PHNX-3940): `updates.auto` (global)
- * or `updates.<agent>.auto` (one harness — `agent` is set).
- */
 export interface ParsedUpdatesConfigKey {
     scope: 'updates';
     property: 'auto';
     agent?: AgentId;
 }
-/** An AGI Menu preference key: `menubar.menu.<property>` (user-scope, PHNX-3999). */
 export interface ParsedMenubarConfigKey {
     scope: 'menubar';
-    /** Leaf name under `menubar.menu.` — one of {@link MENUBAR_MENU_PROPERTIES}. */
     property: string;
 }
 export type ParsedConfigKey = ParsedRunConfigKey | ParsedInteractiveConfigKey | ParsedAutoConfigKey | ParsedBrowserConfigKey | ParsedProjectConfigKey | ParsedDeviceConfigKey | ParsedSummarizerConfigKey | ParsedUpdatesConfigKey | ParsedMenubarConfigKey;
 export type DeviceConfigProperty = 'role' | 'max-agents' | 'scheduler' | 'daemon' | 'watchdog' | 'tmux' | 'browser.remote-control' | 'browser.task-idle-minutes' | 'notes' | 'browser.profile' | 'browser.viewer' | 'computer.host' | 'formFactor';
-/** Normalize agent@version to use `@` consistently. */
 export declare function formatAgentVersion(agent: AgentId, version: string): string;
-/**
- * Parse a unified config key into its structured representation.
- *
- * Supported forms:
- *   run.<agent@version>.model
- *   run.<agent@version>.mode
- *   run.<agent@version>.effort
- *   run.<agent@version>.tier.<cheap|default|best|ultra>
- *   interactive.host
- *   auto.pool
- *   browser.profile
- *   project.root
- *   devices.<name>.role
- *   devices.<name>.max-agents
- *   devices.<name>.scheduler
- *   devices.<name>.daemon
- *   devices.<name>.watchdog
- *   devices.<name>.tmux
- *   devices.<name>.browser.remote-control
- *   devices.<name>.browser.task-idle-minutes
- *   devices.<name>.notes
- *   devices.<name>.browser.profile
- */
 export declare function parseConfigKey(key: string): ParsedConfigKey;
-/** Render a parsed key back to its canonical dotted string. */
 export declare function formatConfigKey(parsed: ParsedConfigKey): string;
-/** List every canonical key the command documents, with wildcards expanded to a concrete example. */
 export declare function listKnownConfigKeys(): string[];
-/**
- * Map a parsed device property to the internal device-config key name.
- * This is the bridge between the friendly `agents config` surface and the
- * existing CONFIG_KEYS registry in lib/device-config.ts.
- */
 export declare function devicePropertyToConfigName(property: DeviceConfigProperty): string;
-/**
- * Map a parsed key to the human-readable "where is this stored" note.
- * Useful for `agents config list --source` output.
- */
 export declare function configKeyStorageHint(parsed: ParsedConfigKey): string;