@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/commands/config.js

@@ -0,0 +1,401 @@
+/**
+ * Unified configuration command barrel.
+ *
+ * `agents config` consolidates the fragmented config surface into one namespace:
+ *   - run defaults (model, mode, effort)
+ *   - tier overrides (folded into the run namespace)
+ *   - interactive host
+ *   - usage primary host
+ *   - browser profile
+ *   - local projects root
+ *   - per-device config keys
+ *
+ * The underlying YAML schema is unchanged; this command translates the new key
+ * grammar into reads/writes of the existing stores.
+ */
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { parseConfigKey, formatAgentVersion, devicePropertyToConfigName, configKeyStorageHint, } from '../lib/config-keys.js';
+import { resolveRunDefaults, setRunDefaultModel, setRunDefaultMode, setRunDefaultEffort, unsetRunDefault, } from '../lib/run-defaults.js';
+import { resolveTierOverride, setTierOverride, clearTierOverride } from '../lib/model-tier-overrides.js';
+import { getConfigValue, setConfigValue, unsetConfigValue, listConfig, } from '../lib/device-config.js';
+import { readMeta, updateMeta } from '../lib/state.js';
+import { MODEL_TIERS } from '../lib/model-tiers.js';
+import { machineId } from '../lib/machine-id.js';
+import { getProjectRoot, setProjectRoot } from '../lib/project-root.js';
+/** Parse a boolean value the same way `agents devices configure` does. */
+function parseBool(value, key) {
+    const v = value.trim().toLowerCase();
+    if (v === 'on' || v === 'true')
+        return true;
+    if (v === 'off' || v === 'false')
+        return false;
+    throw new Error(`Config key '${key}' expects a boolean ('on' or 'off'), got '${value}'.`);
+}
+/** Parse the value for a given key, enforcing type rules. */
+function parseValue(key, parsed, raw) {
+    switch (parsed.scope) {
+        case 'run':
+            return raw.trim();
+        case 'interactive':
+            return raw.trim();
+        case 'usage':
+            return raw.trim();
+        case 'browser':
+            return raw.trim();
+        case 'project':
+            return raw.trim();
+        case 'device': {
+            switch (parsed.property) {
+                case 'max-agents':
+                    if (!/^\d+$/.test(raw.trim())) {
+                        throw new Error(`Config key '${key}' expects an integer, got '${raw}'.`);
+                    }
+                    return Number.parseInt(raw.trim(), 10);
+                case 'scheduler':
+                case 'daemon':
+                case 'watchdog':
+                case 'browser.remote-control':
+                    return parseBool(raw, key);
+                case 'notes':
+                    return raw.trim();
+                case 'browser.profile':
+                    return raw.trim();
+            }
+        }
+    }
+}
+/** Write a value for a parsed config key. */
+function setConfig(parsed, value) {
+    switch (parsed.scope) {
+        case 'run': {
+            const selector = `${parsed.agent}:${parsed.version}`;
+            if (parsed.property === 'tier') {
+                setTierOverride(selector, parsed.tier, value);
+                return;
+            }
+            if (parsed.property === 'model') {
+                setRunDefaultModel(selector, value);
+            }
+            else if (parsed.property === 'mode') {
+                setRunDefaultMode(selector, value);
+            }
+            else {
+                setRunDefaultEffort(selector, value);
+            }
+            return;
+        }
+        case 'interactive': {
+            setConfigValue('interactive.host', value);
+            return;
+        }
+        case 'usage': {
+            setConfigValue('usage.primary-host', value);
+            return;
+        }
+        case 'browser': {
+            // Device-local default lives in the central fleet.devices.<name>.config
+            // block (same store `agents devices config` / getConfigValue use). Bare
+            // browser.profile targets this machine; devices.<name>.browser.profile
+            // targets a peer.
+            setConfigValue('browser.profile', value, parsed.device ? { device: parsed.device } : undefined);
+            return;
+        }
+        case 'project':
+            setProjectRoot(value);
+            return;
+        case 'device': {
+            const configName = devicePropertyToConfigName(parsed.property);
+            if (parsed.property === 'notes') {
+                const existing = getConfigValue('notes', { device: parsed.device }).value ?? [];
+                setConfigValue('notes', [...existing, value], { device: parsed.device });
+            }
+            else {
+                setConfigValue(configName, value, { device: parsed.device });
+            }
+            return;
+        }
+    }
+}
+/** Unset a parsed config key. */
+function unsetConfig(parsed) {
+    switch (parsed.scope) {
+        case 'run': {
+            const selector = `${parsed.agent}:${parsed.version}`;
+            if (parsed.property === 'tier') {
+                return clearTierOverride(selector, parsed.tier);
+            }
+            return unsetRunDefault(selector);
+        }
+        case 'interactive': {
+            const had = getConfigValue('interactive.host').value !== undefined;
+            unsetConfigValue('interactive.host');
+            return had;
+        }
+        case 'usage': {
+            const had = getConfigValue('usage.primary-host').value !== undefined;
+            unsetConfigValue('usage.primary-host');
+            return had;
+        }
+        case 'browser': {
+            const target = parsed.device ? { device: parsed.device } : undefined;
+            const had = getConfigValue('browser.profile', target).value !== undefined;
+            unsetConfigValue('browser.profile', target);
+            return had;
+        }
+        case 'project': {
+            const had = getProjectRoot() !== undefined;
+            updateMeta((meta) => {
+                const { projectRoot: _projectRoot, ...rest } = meta;
+                return rest;
+            });
+            return had;
+        }
+        case 'device': {
+            const configName = devicePropertyToConfigName(parsed.property);
+            const had = getConfigValue(configName, { device: parsed.device }).value !== undefined;
+            unsetConfigValue(configName, { device: parsed.device });
+            return had;
+        }
+    }
+}
+/** Read the stored value for a parsed config key. */
+function getConfig(parsed) {
+    switch (parsed.scope) {
+        case 'run': {
+            const defaults = resolveRunDefaults(parsed.agent, parsed.version);
+            if (parsed.property === 'tier') {
+                return resolveTierOverride(parsed.agent, parsed.version)[parsed.tier];
+            }
+            return defaults[parsed.property];
+        }
+        case 'interactive':
+            return getConfigValue('interactive.host').value;
+        case 'usage':
+            return getConfigValue('usage.primary-host').value;
+        case 'browser': {
+            return getConfigValue('browser.profile', parsed.device ? { device: parsed.device } : undefined).value;
+        }
+        case 'project':
+            return getProjectRoot();
+        case 'device': {
+            const configName = devicePropertyToConfigName(parsed.property);
+            return getConfigValue(configName, { device: parsed.device }).value;
+        }
+    }
+}
+/** Format a config value for display. */
+function formatValue(value) {
+    if (value === undefined)
+        return chalk.gray('(unset)');
+    if (typeof value === 'boolean')
+        return value ? chalk.green('true') : chalk.red('false');
+    return chalk.cyan(JSON.stringify(value));
+}
+/** Collect all set config entries for a given device scope (self or peer). */
+function* listRunConfigEntries() {
+    const meta = readMeta();
+    for (const [selector, defaults] of Object.entries(meta.run?.defaults ?? {})) {
+        const [agent, version] = selector.split(':');
+        if (!agent || !version)
+            continue;
+        const base = `run.${formatAgentVersion(agent, version)}`;
+        const d = defaults;
+        for (const prop of ['model', 'mode', 'effort']) {
+            if (d[prop] !== undefined) {
+                const key = `${base}.${prop}`;
+                yield { key, value: d[prop], hint: configKeyStorageHint(parseConfigKey(key)) };
+            }
+        }
+    }
+    for (const [selector, tiers] of Object.entries(meta.model?.tiers ?? {})) {
+        const [agent, version] = selector.split(':');
+        if (!agent || !version)
+            continue;
+        const base = `run.${formatAgentVersion(agent, version)}.tier`;
+        for (const tier of MODEL_TIERS) {
+            const value = tiers[tier];
+            if (value !== undefined) {
+                const key = `${base}.${tier}`;
+                yield { key, value, hint: configKeyStorageHint(parseConfigKey(key)) };
+            }
+        }
+    }
+}
+/** Collect central non-run config entries. */
+function* listCentralConfigEntries() {
+    const meta = readMeta();
+    if (meta.config?.interactiveHost !== undefined) {
+        yield { key: 'interactive.host', value: meta.config.interactiveHost, hint: 'config.interactiveHost' };
+    }
+    if (meta.config?.usagePrimaryHost !== undefined) {
+        yield { key: 'usage.primary-host', value: meta.config.usagePrimaryHost, hint: 'config.usagePrimaryHost' };
+    }
+    if (meta.projectRoot !== undefined) {
+        yield { key: 'project.root', value: meta.projectRoot, hint: 'devices.<self>.projectRoot' };
+    }
+    // This machine's default browser profile lives in fleet.devices.<self>.config
+    // (device-config), not the legacy top-level Meta.defaultBrowserProfile field.
+    const browserProfile = getConfigValue('browser.profile').value;
+    if (browserProfile !== undefined) {
+        const key = 'browser.profile';
+        yield { key, value: browserProfile, hint: configKeyStorageHint(parseConfigKey(key)) };
+    }
+}
+/** Collect device-scope config entries. */
+function* listDeviceConfigEntries(device) {
+    for (const entry of listConfig({ device })) {
+        if (entry.value === undefined)
+            continue;
+        const prefix = `devices.${device}.`;
+        let key;
+        switch (entry.spec.name) {
+            case 'agents.max-concurrent':
+                key = `${prefix}max-agents`;
+                break;
+            case 'scheduler.enabled':
+                key = `${prefix}scheduler`;
+                break;
+            case 'daemon.enabled':
+                key = `${prefix}daemon`;
+                break;
+            case 'watchdog.enabled':
+                key = `${prefix}watchdog`;
+                break;
+            case 'browser.remote-control':
+                key = `${prefix}browser.remote-control`;
+                break;
+            case 'notes':
+                key = `${prefix}notes`;
+                break;
+            case 'browser.profile':
+                // The self device's default browser profile is already surfaced as the
+                // top-level `browser.profile` key; skip it here to avoid duplication.
+                if (device === machineId())
+                    continue;
+                key = `${prefix}browser.profile`;
+                break;
+            default:
+                continue;
+        }
+        yield { key, value: entry.value, hint: configKeyStorageHint(parseConfigKey(key)) };
+    }
+}
+export function registerConfigCommand(program) {
+    const config = program
+        .command('config')
+        .description('Get, set, list, and unset run defaults, tier overrides, the projects root, and device options.');
+    setHelpSections(config, {
+        examples: `
+      agents config set run.claude@*.model best
+      agents config set run.claude@*.tier.best claude-opus-4-8
+      agents config set run.claude@2.1.45.model claude-opus-4-8
+      agents config set run.claude@*.mode auto
+      agents config set interactive.host zion
+      agents config set usage.primary-host zion
+      agents config set browser.profile work
+      agents config set project.root ~/src/github.com/<you>
+      agents config set devices.mac-mini.max-agents 4
+      agents config get run.claude@*.model
+      agents config get usage.primary-host
+      agents config unset run.claude@*.tier.best
+      agents config unset usage.primary-host
+      agents config list
+    `,
+        notes: `
+      Every agent/harness reference uses agent@version. Use * for all versions.
+      Tier overrides are part of the run namespace: run.<agent@version>.tier.<tier>.
+      Project root is auto-inferred from the current Git repository when unset.
+    `,
+    });
+    config
+        .command('list')
+        .description('List configured config keys and their values')
+        .option('--device <name>', 'List config for a specific device instead of this machine')
+        .option('--json', 'Output machine-readable JSON')
+        .action((opts) => {
+        try {
+            const entries = [];
+            if (!opts.device) {
+                entries.push(...listRunConfigEntries());
+                entries.push(...listCentralConfigEntries());
+                entries.push(...listDeviceConfigEntries(machineId()));
+            }
+            else {
+                entries.push(...listDeviceConfigEntries(opts.device));
+            }
+            entries.sort((a, b) => a.key.localeCompare(b.key));
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(entries, null, 2) + '\n');
+                return;
+            }
+            if (entries.length === 0) {
+                console.log(chalk.gray('No config values set.'));
+                console.log(chalk.gray("Set one with: agents config set run.claude@*.model best"));
+                return;
+            }
+            console.log(chalk.bold('Config\n'));
+            for (const { key, value, hint } of entries) {
+                console.log(`  ${chalk.cyan(key.padEnd(42))} ${formatValue(value)}`);
+                console.log(`  ${''.padEnd(42)} ${chalk.gray(hint)}`);
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    config
+        .command('get <key>')
+        .description('Get the current value of a config key')
+        .option('--json', 'Output machine-readable JSON')
+        .action((key, opts) => {
+        try {
+            const parsed = parseConfigKey(key);
+            const value = getConfig(parsed);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ key, value: value ?? null }, null, 2) + '\n');
+                return;
+            }
+            console.log(`${chalk.cyan(key)} = ${formatValue(value)}`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    config
+        .command('set <key> <value>')
+        .description('Set a config key')
+        .action((key, value) => {
+        try {
+            const parsed = parseConfigKey(key);
+            const typed = parseValue(key, parsed, value);
+            setConfig(parsed, typed);
+            console.log(chalk.green('Set:') + ` ${chalk.cyan(key)} = ${formatValue(typed)}`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    config
+        .command('unset <key>')
+        .description('Unset a config key (restore default behavior)')
+        .action((key) => {
+        try {
+            const parsed = parseConfigKey(key);
+            const removed = unsetConfig(parsed);
+            if (removed) {
+                console.log(chalk.green(`Unset ${key}`));
+            }
+            else {
+                console.log(chalk.gray(`No value set for ${key}`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/cp.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `agents cp <src> <dst>` — first-class fleet file transfer.
+ *
+ * Accepts `host:path` on either side (local = bare absolute path). Resolves
+ * `~` and `$HOME` remote paths ON the remote before transfer so a `$HOME` in
+ * the remote spec can never silently expand to the local user's home directory
+ * — the documented silent-failure class in `remote-dispatch-mutation-safety`.
+ *
+ * Reuses the same SSH fabric (SSH_OPTS, deviceIdentityArgs, resolveDeviceTarget)
+ * that `agents ssh` and `--host` dispatch use.
+ */
+import type { Command } from 'commander';
+/**
+ * A remote endpoint — host (device name or user@device) and a path on that
+ * host. The path may begin with `~` or `$HOME`; {@link resolveRemotePath}
+ * expands those on the remote before transfer.
+ */
+export interface RemoteEndpoint {
+    isRemote: true;
+    /** Device name, user@device, or ad-hoc host literal. */
+    host: string;
+    /** Path as given by the caller — may contain `~` or `$HOME`. */
+    path: string;
+}
+/** A local endpoint — an absolute local path. */
+export interface LocalEndpoint {
+    isRemote: false;
+    /** Absolute local path. */
+    path: string;
+}
+export type Endpoint = RemoteEndpoint | LocalEndpoint;
+/**
+ * Parse one CLI token into an {@link Endpoint}.
+ *
+ * Grammar: `host:path` is remote; anything else is local. The host part must
+ * not contain a `/` (that would be a local absolute path with a colon in it —
+ * unusual but valid; the colon test covers the common fleet pattern and rejects
+ * the almost-never-seen edge case in favour of local-path semantics).
+ *
+ * Windows drive letters (`C:path`) are excluded by requiring the host part to
+ * be at least two characters and not a single capital letter.
+ */
+export declare function parseEndpoint(token: string): Endpoint;
+/**
+ * Resolve the remote HOME directory in one SSH round-trip. Returns the
+ * absolute path (always starts with `/`), or throws on failure.
+ */
+export declare function resolveRemoteHome(target: string, extraSshArgs: string[]): Promise<string>;
+/**
+ * Pure home-prefix expansion. Given a remote HOME (already resolved on the
+ * remote) and a raw path token, substitute a leading `~` or `$HOME`. Paths
+ * without those prefixes are returned unchanged. Never consults
+ * `process.env.HOME` — the local home must not leak into a remote path.
+ */
+export declare function expandRemoteHomePrefix(rawPath: string, remoteHome: string): string;
+/**
+ * Expand a remote path's leading `~` or literal `$HOME` to an absolute path
+ * resolved **on the remote**, not locally. A path that already starts with `/`
+ * is returned unchanged (no round-trip).
+ *
+ * This is the safeguard against the silent-failure class: a `$HOME` or `~`
+ * that would expand to the **local** user's home if left in a shell command.
+ */
+export declare function resolveRemotePath(rawPath: string, target: string, extraSshArgs: string[]): Promise<string>;
+/**
+ * Build the argv for the `scp` invocation. Pure — no spawning — so it is
+ * unit-testable.
+ *
+ * `scp` accepts ssh `-o` options, so `SSH_OPTS` flows through unchanged.
+ * Identity args (`-i key -o IdentitiesOnly=yes`) are included only when a
+ * single remote device is involved; for two-remote transfers the identity
+ * applies to both connections, which works when the fleet uses a shared key.
+ *
+ * Remote endpoints are formatted as `user@host:path` (or bare `host:path`),
+ * local endpoints as their absolute path. Paths have already been resolved
+ * (no `~` or `$HOME`) by the time this is called.
+ */
+export declare function buildScpArgv({ srcSpec, dstSpec, identityArgs, recursive, }: {
+    srcSpec: string;
+    dstSpec: string;
+    identityArgs: string[];
+    recursive: boolean;
+}): string[];
+export declare function registerCpCommand(program: Command): void;