@phnx-labs/agents-cli 1.22.8 → 1.22.10

package/dist/commands/harness.js

@@ -11,9 +11,11 @@
  * native harness registry. The `agents profiles` tree stays unchanged.
  */
 import chalk from 'chalk';
-import { addProfile, ensureProviderToken } from './profiles.js';
-import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, profileFromHostModel, authEnvKeyForHost, getProfilePath, validateProfileName, editProfile, renameProfile, } from '../lib/profiles.js';
-import { listPresets } from '../lib/profiles-presets.js';
+import { addProfile, ensureProviderToken, applyFromSecrets } from './profiles.js';
+import { isInteractiveTerminal } from './utils.js';
+import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, editProfile, renameProfile, profileFromHostModel, authEnvKeyForHost, getProfilePath, validateProfileName, } from '../lib/profiles.js';
+import { listPresets, getPreset } from '../lib/profiles-presets.js';
+import { listBundles } from '../lib/secrets/bundles.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName } from '../lib/agents.js';
 /** Short capability summary for a native harness — its supported run modes. */
 function nativeModes(id) {
@@ -85,6 +87,215 @@ function authEnvKeyForHostOrThrow(host) {
     }
     return key;
 }
+/** Map `agents harness edit` flags onto {@link ForkProfileOptions} — the same
+ * override shape `editProfile`/`forkProfile` apply. `--version ''` (unpin) is
+ * handled by the caller ({@link buildEdit}), not here: `forkProfile`'s own
+ * ternary treats an empty string as "no override" and would otherwise inherit
+ * the source's version instead of clearing it. */
+export function buildEditOverrides(opts) {
+    const overrides = {};
+    if (opts.model !== undefined)
+        overrides.model = opts.model;
+    if (opts.baseUrl !== undefined)
+        overrides.baseUrl = opts.baseUrl;
+    if (opts.authProvider !== undefined)
+        overrides.provider = opts.authProvider;
+    if (opts.version)
+        overrides.version = opts.version;
+    if (opts.description !== undefined)
+        overrides.description = opts.description;
+    return overrides;
+}
+/** True when at least one recognized edit flag was given. */
+export function hasEditFlags(opts) {
+    return (opts.model !== undefined ||
+        opts.baseUrl !== undefined ||
+        opts.authProvider !== undefined ||
+        opts.version !== undefined ||
+        opts.description !== undefined ||
+        opts.fallbackModel !== undefined ||
+        opts.fromSecrets !== undefined);
+}
+const EDIT_FLAGS_HELP = 'No changes given. Available flags: --model, --base-url, --auth-provider, --version, --description, --fallback-model, --from-secrets.';
+/**
+ * Build the edited harness for `agents harness edit <name>` — the profile-shape
+ * transform only; the caller applies `--from-secrets`/`--auth-provider` (async
+ * keychain side effects) and persists with `writeProfile`. Mirrors
+ * {@link buildFork}'s split between a pure builder and the action's IO.
+ */
+export function buildEdit(name, opts) {
+    if (!profileExists(name)) {
+        throw new Error(`Harness '${name}' not found. Create it first: agents harness add ${name} ...`);
+    }
+    if (!hasEditFlags(opts)) {
+        throw new Error(EDIT_FLAGS_HELP);
+    }
+    const source = readProfile(name);
+    const edited = editProfile(source, buildEditOverrides(opts));
+    if (opts.version === '')
+        delete edited.host.version;
+    if (opts.fallbackModel !== undefined) {
+        if (opts.fallbackModel === '')
+            delete edited.fallback_model;
+        else
+            edited.fallback_model = opts.fallbackModel;
+    }
+    return edited;
+}
+/** True when `agents harness fork` was given too little to proceed without the wizard. */
+export function forkNeedsWizard(source, name, opts) {
+    if (!source || !name)
+        return true;
+    if (!profileExists(source) && resolveAgentName(source) && !opts.model)
+        return true;
+    return false;
+}
+/** True when `agents harness add` was given too little to proceed without the wizard.
+ * Mirrors {@link addProfile}'s own error condition in ./profiles.js so a bare
+ * `agents harness add <preset-name>` (no flags) still resolves via the preset
+ * fallback instead of being routed into the wizard. */
+export function addNeedsWizard(name, opts) {
+    if (!name)
+        return true;
+    if (opts.preset)
+        return false;
+    if (opts.host && opts.model)
+        return false;
+    if (opts.host || opts.model)
+        return true;
+    return !getPreset(name);
+}
+/**
+ * Shared build+persist flow for a fork — used by `agents harness fork`'s
+ * flag-driven path AND by the wizard (both for `fork` and, when it falls back
+ * to the wizard, `add`), so a wizard run and a hand-written `fork` call build an
+ * identical profile.
+ */
+async function runForkFlow(source, name, opts) {
+    validateProfileName(name);
+    if (profileExists(name) && !opts.force) {
+        throw new Error(`Harness '${name}' already exists. Use --force to overwrite.`);
+    }
+    // Build first so a bad source/flag combination fails before prompting for a
+    // key (or copying one from a bundle) the user would then have stored for
+    // nothing.
+    const forked = buildFork(source, name, opts);
+    if (opts.fromSecrets) {
+        // A fork's `auth` (when present) may just be inherited by reference from
+        // its source, not established for this harness itself -- never trust it
+        // as "safe to rotate" without an explicit --auth-provider.
+        await applyFromSecrets(forked, opts.fromSecrets, opts.authProvider, { allowInheritedAuth: false });
+    }
+    else if (opts.authProvider) {
+        await ensureProviderToken(opts.authProvider, undefined, opts.keyStdin);
+    }
+    writeProfile(forked);
+    console.log(chalk.green(`Harness '${name}' forked from ${source}.`));
+    console.log(chalk.gray(`Try: agents run ${name} "hello"`));
+}
+/** The first `_MODEL`-suffixed env var in a preset's static env block, if any. */
+function presetModel(preset) {
+    return Object.entries(preset.env).find(([k]) => k.endsWith('_MODEL'))?.[1];
+}
+/**
+ * Interactive `agents harness add`/`fork` wizard — runs when required info is
+ * missing and stdout is a TTY (see {@link forkNeedsWizard}, {@link addNeedsWizard}).
+ * Always resolves to the same `(source, name, opts)` shape {@link buildFork}
+ * accepts via {@link runForkFlow}, so a wizard run and a hand-written fork call
+ * build an identical profile.
+ */
+async function runHarnessWizard() {
+    const { select, input } = await import('@inquirer/prompts');
+    const customNames = listProfiles().map((p) => p.name);
+    const source = await select({
+        message: 'Fork from',
+        choices: [
+            ...ALL_AGENT_IDS.map((id) => ({ name: `${AGENTS[id].name}  ${chalk.gray('(native)')}`, value: id })),
+            ...customNames.map((n) => ({ name: `${n}  ${chalk.gray('(custom harness)')}`, value: n })),
+        ],
+    });
+    const presets = listPresets();
+    const CUSTOM = '__custom__';
+    const presetChoice = await select({
+        message: 'Preset',
+        choices: [
+            ...presets.map((p) => ({ name: `${p.name}  ${chalk.gray(p.description.slice(0, 60))}`, value: p.name })),
+            { name: 'Build custom (host + model + provider)', value: CUSTOM },
+        ],
+    });
+    let model;
+    let baseUrl;
+    let authProvider;
+    let defaultName = source;
+    if (presetChoice === CUSTOM) {
+        model = await input({ message: 'Model id' });
+        const NO_AUTH = '__none__';
+        const providers = [...new Set(presets.map((p) => p.provider))];
+        const providerChoice = await select({
+            message: 'Provider',
+            choices: [
+                ...providers.map((p) => ({ name: p, value: p })),
+                { name: 'no auth / host manages its own login', value: NO_AUTH },
+            ],
+        });
+        authProvider = providerChoice === NO_AUTH ? undefined : providerChoice;
+        const baseUrlInput = await input({ message: 'Base URL (optional)', default: '' });
+        baseUrl = baseUrlInput || undefined;
+    }
+    else {
+        const preset = getPreset(presetChoice);
+        model = presetModel(preset);
+        baseUrl = preset.env.ANTHROPIC_BASE_URL || preset.env.OPENAI_BASE_URL;
+        authProvider = preset.authOptional ? undefined : preset.provider;
+        // Pre-fill with the preset's own name (e.g. 'deepseek'), not a model
+        // detail, so users aren't nudged toward baking one into the identity name.
+        defaultName = preset.name;
+    }
+    const name = await input({
+        message: 'Harness name',
+        default: defaultName,
+        validate: (v) => {
+            try {
+                validateProfileName(v);
+                return true;
+            }
+            catch (err) {
+                return err.message;
+            }
+        },
+    });
+    const opts = { model, baseUrl, authProvider };
+    if (authProvider) {
+        const bundles = listBundles();
+        const TYPE_NOW = 'type';
+        const FROM_SECRETS = 'secrets';
+        const keySource = bundles.length > 0
+            ? await select({
+                message: `How should '${authProvider}' get its key?`,
+                choices: [
+                    { name: 'Type a key now', value: TYPE_NOW },
+                    { name: 'Use an existing agents secrets bundle', value: FROM_SECRETS },
+                ],
+            })
+            : TYPE_NOW;
+        if (keySource === FROM_SECRETS) {
+            const bundleName = await select({
+                message: 'Bundle',
+                choices: bundles.map((b) => ({
+                    name: b.description ? `${b.name}  ${chalk.gray(b.description)}` : b.name,
+                    value: b.name,
+                })),
+            });
+            const bundle = bundles.find((b) => b.name === bundleName);
+            const keys = Object.keys(bundle.vars);
+            const key = keys.length === 1
+                ? keys[0]
+                : await select({ message: 'Key', choices: keys.map((k) => ({ name: k, value: k })) });
+            opts.fromSecrets = `${bundleName}:${key}`;
+        }
+    }
+    return { source, name, opts };
+}
 export function registerHarnessCommands(program) {
     const cmd = program
         .command('harness')
@@ -110,6 +321,13 @@ Examples:
   # Per-run model override still wins
   agents run spark --model opencode/big-pickle "quick pass"
 
+  # Edit a harness in place, or give it a new name
+  agents harness edit deepseek --fallback-model deepseek/deepseek-chat-v3
+  agents harness rename deepseek deepseek-classic
+
+  # No args, in an interactive terminal: a wizard walks you through host, model, provider, key
+  agents harness add
+
   # See custom harnesses, addable presets, and native harnesses
   agents harness list
 
@@ -119,18 +337,27 @@ Examples:
   # Custom harnesses are just profiles — this also works via 'agents profiles'
 `);
     cmd
-        .command('add <name>')
-        .description('Create a custom harness from a host + model (or apply a built-in preset).')
+        .command('add [name]')
+        .description('Create a custom harness from a host + model (or apply a built-in preset). Omit flags in a terminal for the interactive wizard.')
         .option('--host <agent>', 'Host CLI to run under (opencode, claude, codex, grok, antigravity, ...) — pair with --model')
         .option('--model <id>', 'Model id to pin on the host (e.g., meta/muse-spark-1.1) — pair with --host')
         .option('--base-url <url>', 'Custom endpoint base URL (claude/codex hosts)')
         .option('--auth-provider <provider>', 'Attach a keychain-backed API key under this provider (for private endpoints)')
         .option('--preset <preset>', 'Apply a built-in preset instead of --host/--model')
         .option('--version <version>', 'Pin the host CLI version (e.g., 1.16.0)')
+        .option('--from-secrets <bundle>[:<key>]', "Copy a value from an agents secrets bundle into this harness's own keychain item, once (not a live link)")
         .option('--key-stdin', 'Read API key from stdin instead of prompting (for scripts/CI)')
         .option('--force', 'Overwrite an existing harness with the same name')
         .action(async (name, opts) => {
         try {
+            if (addNeedsWizard(name, opts)) {
+                if (!isInteractiveTerminal()) {
+                    throw new Error("'agents harness add' needs --preset or --host + --model (or a name and an interactive terminal for the wizard).");
+                }
+                const wiz = await runHarnessWizard();
+                await runForkFlow(wiz.source, wiz.name, { ...wiz.opts, force: opts.force, keyStdin: opts.keyStdin });
+                return;
+            }
             await addProfile(name, opts, 'Harness');
         }
         catch (err) {
@@ -139,13 +366,14 @@ Examples:
         }
     });
     cmd
-        .command('fork <source> <name>')
-        .description('Fork a native harness (claude, opencode, ...) or an existing custom one into a new named harness.')
+        .command('fork [source] [name]')
+        .description('Fork a native harness (claude, opencode, ...) or an existing custom one into a new named harness. Omit args in a terminal for the interactive wizard.')
         .option('--model <id>', 'Model to pin on the fork (required when forking a native harness)')
         .option('--base-url <url>', 'Custom endpoint base URL (claude/codex hosts)')
         .option('--auth-provider <provider>', 'Attach a keychain-backed API key under this provider')
         .option('--version <version>', 'Pin the host CLI version (e.g., 1.16.0)')
         .option('--description <text>', 'One-line description')
+        .option('--from-secrets <bundle>[:<key>]', "Copy a value from an agents secrets bundle into this harness's own keychain item, once (not a live link)")
         .option('--key-stdin', 'Read the API key from stdin instead of prompting (for scripts/CI)')
         .option('--force', 'Overwrite an existing harness with the same name')
         .addHelpText('after', `
@@ -158,21 +386,92 @@ Examples:
 
   # Copy an existing harness and swap only the model
   agents harness fork deepseek deepseek-chat --model deepseek/deepseek-chat-v3
+
+  # Copy a key out of an existing secrets bundle instead of typing it
+  agents harness fork claude corp --model gpt-x --auth-provider corp --from-secrets prod:OPENROUTER_KEY
+
+  # No args, in an interactive terminal: walks through source, preset/model, name, key
+  agents harness fork
 `)
         .action(async (source, name, opts) => {
         try {
-            validateProfileName(name);
-            if (profileExists(name) && !opts.force) {
-                throw new Error(`Harness '${name}' already exists. Use --force to overwrite.`);
+            if (forkNeedsWizard(source, name, opts)) {
+                if (!isInteractiveTerminal()) {
+                    throw new Error("'agents harness fork' needs <source> and <name> (or an interactive terminal for the wizard).");
+                }
+                const wiz = await runHarnessWizard();
+                await runForkFlow(wiz.source, wiz.name, { ...wiz.opts, force: opts.force, keyStdin: opts.keyStdin });
+                return;
+            }
+            await runForkFlow(source, name, opts);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('edit <name>')
+        .description('Edit an existing custom harness in place — model, endpoint, auth, version, description, fallback.')
+        .option('--model <id>', 'Swap the pinned model')
+        .option('--base-url <url>', 'Swap the custom endpoint base URL')
+        .option('--auth-provider <provider>', 'Repoint auth at a different provider (keychain-backed)')
+        .option('--version <version>', 'Re-pin the host CLI version (pass an empty string to unpin)')
+        .option('--description <text>', 'Update the one-line description')
+        .option('--fallback-model <id>', 'Secondary model retried on the same host on a rate limit (pass an empty string to clear it)')
+        .option('--from-secrets <bundle>[:<key>]', "Copy a value from an agents secrets bundle into this harness's own keychain item, once (not a live link)")
+        .option('--key-stdin', 'Read the API key from stdin instead of prompting (for scripts/CI)')
+        .addHelpText('after', `
+Examples:
+  # Swap the pinned model
+  agents harness edit deepseek --model deepseek/deepseek-v3.2
+
+  # Repoint auth at a different provider and re-enter the key
+  agents harness edit corp --auth-provider corp2
+
+  # Unpin the host CLI version
+  agents harness edit spark --version ""
+
+  # Add a same-host fallback model for rate-limit retries
+  agents harness edit deepseek --fallback-model deepseek/deepseek-chat-v3
+
+  # Copy a key out of an existing secrets bundle instead of typing it
+  agents harness edit corp --from-secrets prod:OPENROUTER_KEY
+`)
+        .action(async (name, opts) => {
+        try {
+            const edited = buildEdit(name, opts);
+            if (opts.fromSecrets) {
+                await applyFromSecrets(edited, opts.fromSecrets, opts.authProvider);
             }
-            // Build first so a bad source/flag combination fails before prompting
-            // for a key the user would then have stored for nothing.
-            const forked = buildFork(source, name, opts);
-            if (opts.authProvider)
+            else if (opts.authProvider) {
                 await ensureProviderToken(opts.authProvider, undefined, opts.keyStdin);
-            writeProfile(forked);
-            console.log(chalk.green(`Harness '${name}' forked from ${source}.`));
-            console.log(chalk.gray(`Try: agents run ${name} "hello"`));
+            }
+            writeProfile(edited);
+            console.log(chalk.green(`Harness '${name}' updated.`));
+            console.log(chalk.gray(`Model:  ${profileModelLabel(edited)}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('rename <old-name> <new-name>')
+        .description('Rename a custom harness (updates forkedFrom lineage on any harness forked from it). Errors on a name collision.')
+        .addHelpText('after', `
+Examples:
+  # Rename 'spark' to 'muse'
+  agents harness rename spark muse
+
+  # Rename then run under the new name
+  agents harness rename deepseek ds && agents run ds "hello"
+`)
+        .action((oldName, newName) => {
+        try {
+            renameProfile(oldName, newName);
+            console.log(chalk.green(`Harness '${oldName}' renamed to '${newName}'.`));
+            console.log(chalk.gray(`Try: agents run ${newName} "hello"`));
         }
         catch (err) {
             console.error(chalk.red(err.message));
@@ -246,63 +545,4 @@ Examples:
         }
         console.log(chalk.green(`Harness '${name}' removed.`));
     });
-    cmd
-        .command('edit <name>')
-        .description('Edit a custom harness in place (model, endpoint, host version, description).')
-        // Flags mirror ForkProfileOptions exactly — `editProfile` reuses
-        // `forkProfile`'s override logic, so anything it does not accept would be a
-        // flag that parses and does nothing. There is deliberately no --label: the
-        // header `agents view` prints is derived from the harness name.
-        .option('--model <id>', 'Swap the pinned model (e.g., meta/muse-spark-2.0)')
-        .option('--base-url <url>', 'Set or replace the endpoint base URL (claude/codex hosts)')
-        .option('--version <ver>', 'Re-pin the host CLI version. Empty string unpins (tracks latest).')
-        .option('--description <text>', 'Set the one-line description')
-        .addHelpText('after', `
-Examples:
-  # Upgrade the pinned model
-  agents harness edit spark --model meta/muse-spark-2.0
-
-  # Point to a new private endpoint
-  agents harness edit corp --base-url https://gw.corp/v2
-
-  # Track the host's latest instead of a pinned version
-  agents harness edit spark --version ""
-
-  # The display name is derived from the harness name, so to change it, rename:
-  agents harness rename spark muse-spark
-`)
-        .action((name, opts) => {
-        try {
-            const edited = editProfile(readProfile(name), opts);
-            writeProfile(edited);
-            console.log(chalk.green(`Harness '${name}' updated.`));
-            console.log(chalk.gray(`Model:  ${profileModelLabel(edited)}`));
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('rename <name> <new-name>')
-        .description('Rename a custom harness — updates the file name and its internal name field.')
-        .addHelpText('after', `
-Examples:
-  # Rename 'spark' to 'muse'
-  agents harness rename spark muse
-
-  # Rename then run under the new name
-  agents harness rename deepseek ds && agents run ds "hello"
-`)
-        .action((name, newName) => {
-        try {
-            renameProfile(name, newName);
-            console.log(chalk.green(`Harness '${name}' renamed to '${newName}'.`));
-            console.log(chalk.gray(`Run: agents run ${newName} "hello"`));
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
 }

package/dist/commands/profiles.d.ts

@@ -28,7 +28,49 @@ export interface AddProfileOptions {
     version?: string;
     keyStdin?: boolean;
     force?: boolean;
+    /** `<bundle>` or `<bundle>:<key>` — see {@link applyFromSecrets}. */
+    fromSecrets?: string;
 }
+/**
+ * Copy a value from an `agents secrets` bundle into a profile's own keychain
+ * item — a one-time copy, not a live link. `spec` is `<bundle>` or
+ * `<bundle>:<key>`; the key is required only when the bundle has more than one.
+ *
+ * Reads the bundle value via {@link getKeychainToken} — this pops Touch ID on
+ * macOS once, for that bundle-namespaced item (`agents-cli.secrets.*`, gated by
+ * `keychainItemRequiresUserPresence` in `../lib/secrets/index.ts`) — then writes
+ * it to `keychainItemName(provider)`, a plain `agents-cli.<provider>.token`
+ * item. That item matches neither the `agents-cli.secrets.` nor
+ * `agents-cli.bundles.` prefix, so every later read of the harness's own key is
+ * silent — no repeat Touch ID prompt.
+ *
+ * Provider precedence: an explicit `--auth-provider` on the same call always
+ * wins (freshest intent); otherwise, only when the profile already has a real
+ * auth binding (`profile.auth` is set), its own `provider` (so editing an
+ * already-provisioned harness rotates its existing key without repeating
+ * `--auth-provider`); otherwise the bundle's own name. The `profile.auth`
+ * gate matters because `profileFromHostModel`/`forkProfile` default
+ * `profile.provider` to the *host* id (e.g. `claude`) even when no auth is
+ * attached yet — trusting that default here would silently overwrite the
+ * host's own keychain item (`agents-cli.claude.token`) on a bare `--host
+ * --model --from-secrets` add with no `--auth-provider`.
+ *
+ * Attaches `profile.auth` when the profile has none yet (a bare `--host
+ * --model` harness, or a native-host fork with no prior auth binding).
+ *
+ * `allowInheritedAuth` (default `true`) gates the "reuse `profile.auth`'s own
+ * provider" branch above. It must be `false` when `profile` came from
+ * **forking** an already-provisioned harness: `forkProfile` copies `auth` by
+ * reference from the source when no `--auth-provider` override is given, so
+ * `profile.auth` being set there means "the SOURCE harness's binding", not
+ * "this harness's own" — trusting it would silently overwrite the source's
+ * shared keychain item. Editing a harness's own already-established auth is
+ * the one case where reuse is genuinely correct, so callers on that path keep
+ * the default.
+ */
+export declare function applyFromSecrets(profile: Profile, spec: string, explicitAuthProvider?: string, opts?: {
+    allowInheritedAuth?: boolean;
+}): Promise<void>;
 /**
  * Create a profile ("custom harness"). Two paths:
  *  - `--host <agent> --model <id>`: one-shot custom harness from a host + model

package/dist/commands/profiles.js

@@ -11,7 +11,9 @@ import { readStdinSync } from '../lib/format.js';
 import { spawn } from 'child_process';
 import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileFromPreset, profileFromHostModel, baseUrlEnvKeyForHost, authEnvKeyForHost, validateProfileName, getPresetForProfile, } from '../lib/profiles.js';
 import { getPreset, listPresets, expandPreset } from '../lib/profiles-presets.js';
-import { hasKeychainToken, keychainItemName, setKeychainToken, deleteKeychainToken, } from '../lib/secrets/profiles.js';
+import { hasKeychainToken, keychainItemName, setKeychainToken, deleteKeychainToken, getKeychainToken, } from '../lib/secrets/profiles.js';
+import { parseBundleValue, secretsKeychainItem } from '../lib/secrets/index.js';
+import { readBundle } from '../lib/secrets/bundles.js';
 import { isInteractiveTerminal } from './utils.js';
 import { getAgentsInvocation } from '../lib/daemon.js';
 import { getActiveResourceProfileName, getResourceProfilePreset, listResourceProfileNames, setActiveResourceProfile, upsertResourceProfilePreset, validateResourceProfileName, } from '../lib/resource-profiles.js';
@@ -66,6 +68,87 @@ export async function ensureProviderToken(provider, signupUrl, fromStdin) {
     setKeychainToken(item, token);
     console.log(chalk.green(`Stored in keychain: ${item}`));
 }
+/**
+ * Copy a value from an `agents secrets` bundle into a profile's own keychain
+ * item — a one-time copy, not a live link. `spec` is `<bundle>` or
+ * `<bundle>:<key>`; the key is required only when the bundle has more than one.
+ *
+ * Reads the bundle value via {@link getKeychainToken} — this pops Touch ID on
+ * macOS once, for that bundle-namespaced item (`agents-cli.secrets.*`, gated by
+ * `keychainItemRequiresUserPresence` in `../lib/secrets/index.ts`) — then writes
+ * it to `keychainItemName(provider)`, a plain `agents-cli.<provider>.token`
+ * item. That item matches neither the `agents-cli.secrets.` nor
+ * `agents-cli.bundles.` prefix, so every later read of the harness's own key is
+ * silent — no repeat Touch ID prompt.
+ *
+ * Provider precedence: an explicit `--auth-provider` on the same call always
+ * wins (freshest intent); otherwise, only when the profile already has a real
+ * auth binding (`profile.auth` is set), its own `provider` (so editing an
+ * already-provisioned harness rotates its existing key without repeating
+ * `--auth-provider`); otherwise the bundle's own name. The `profile.auth`
+ * gate matters because `profileFromHostModel`/`forkProfile` default
+ * `profile.provider` to the *host* id (e.g. `claude`) even when no auth is
+ * attached yet — trusting that default here would silently overwrite the
+ * host's own keychain item (`agents-cli.claude.token`) on a bare `--host
+ * --model --from-secrets` add with no `--auth-provider`.
+ *
+ * Attaches `profile.auth` when the profile has none yet (a bare `--host
+ * --model` harness, or a native-host fork with no prior auth binding).
+ *
+ * `allowInheritedAuth` (default `true`) gates the "reuse `profile.auth`'s own
+ * provider" branch above. It must be `false` when `profile` came from
+ * **forking** an already-provisioned harness: `forkProfile` copies `auth` by
+ * reference from the source when no `--auth-provider` override is given, so
+ * `profile.auth` being set there means "the SOURCE harness's binding", not
+ * "this harness's own" — trusting it would silently overwrite the source's
+ * shared keychain item. Editing a harness's own already-established auth is
+ * the one case where reuse is genuinely correct, so callers on that path keep
+ * the default.
+ */
+export async function applyFromSecrets(profile, spec, explicitAuthProvider, opts) {
+    const sep = spec.indexOf(':');
+    const bundleName = sep === -1 ? spec : spec.slice(0, sep);
+    const requestedKey = sep === -1 ? undefined : spec.slice(sep + 1);
+    const bundle = readBundle(bundleName);
+    const keys = Object.keys(bundle.vars);
+    const key = requestedKey ?? (keys.length === 1 ? keys[0] : undefined);
+    if (!key) {
+        throw new Error(keys.length === 0
+            ? `Bundle '${bundleName}' has no keys.`
+            : `Bundle '${bundleName}' has ${keys.length} keys (${keys.join(', ')}); pick one with --from-secrets ${bundleName}:<key>.`);
+    }
+    if (!(key in bundle.vars)) {
+        throw new Error(`Bundle '${bundleName}' has no key '${key}'. Available: ${keys.join(', ') || '(none)'}.`);
+    }
+    const parsed = parseBundleValue(bundle.vars[key]);
+    let value;
+    if ('literal' in parsed) {
+        value = parsed.literal;
+    }
+    else if (parsed.ref.provider === 'keychain') {
+        value = getKeychainToken(secretsKeychainItem(bundle.name, parsed.ref.value));
+    }
+    else {
+        throw new Error(`Bundle '${bundleName}' key '${key}' is a '${parsed.ref.provider}:' reference, not a keychain-backed secret — --from-secrets only copies keychain-backed values.`);
+    }
+    if (profile.auth && !explicitAuthProvider && opts?.allowInheritedAuth === false) {
+        throw new Error(`Harness '${profile.name}' inherited its auth binding from the harness it was forked from ` +
+            `(provider '${profile.provider}') — pass --auth-provider <name> explicitly with --from-secrets ` +
+            `on a fork, so it never silently overwrites the source harness's shared keychain item.`);
+    }
+    const provider = explicitAuthProvider || (profile.auth ? profile.provider : undefined) || bundleName;
+    const item = keychainItemName(provider);
+    setKeychainToken(item, value);
+    if (!profile.auth) {
+        const envVar = authEnvKeyForHost(profile.host.agent);
+        if (!envVar) {
+            throw new Error(`Host '${profile.host.agent}' has no known auth env var; --from-secrets cannot attach auth to this harness.`);
+        }
+        profile.provider = provider;
+        profile.auth = { envVar, keychainItem: item };
+        profile.authOptional = false;
+    }
+}
 /**
  * Create a profile ("custom harness"). Two paths:
  *  - `--host <agent> --model <id>`: one-shot custom harness from a host + model
@@ -98,7 +181,8 @@ export async function addProfile(name, opts, label = 'Profile') {
                 throw new Error(`--auth-provider is set but host '${host}' has no known auth env var. Use a preset or a hand-written profile YAML.`);
             }
             authEnvVar = key;
-            await ensureProviderToken(opts.authProvider, undefined, opts.keyStdin);
+            if (!opts.fromSecrets)
+                await ensureProviderToken(opts.authProvider, undefined, opts.keyStdin);
         }
         const profile = profileFromHostModel(name, host, opts.model, {
             version: opts.version,
@@ -106,6 +190,8 @@ export async function addProfile(name, opts, label = 'Profile') {
             provider: opts.authProvider,
             authEnvVar,
         });
+        if (opts.fromSecrets)
+            await applyFromSecrets(profile, opts.fromSecrets, opts.authProvider);
         writeProfile(profile);
         console.log(chalk.green(`${label} '${name}' added — ${host} + ${opts.model}.`));
         console.log(chalk.gray(`Try: agents run ${name} "hello"`));
@@ -118,10 +204,12 @@ export async function addProfile(name, opts, label = 'Profile') {
         throw new Error(`No preset '${presetName}'.\nAvailable presets: ${listPresets().map((p) => p.name).join(', ')}\n` +
             'Or build a custom harness: --host <agent> --model <id>.');
     }
-    if (!preset.authOptional) {
+    if (!opts.fromSecrets && !preset.authOptional) {
         await ensureProviderToken(preset.provider, preset.signupUrl, opts.keyStdin);
     }
     const profile = profileFromPreset(name, preset, opts.version);
+    if (opts.fromSecrets)
+        await applyFromSecrets(profile, opts.fromSecrets, opts.authProvider);
     writeProfile(profile);
     console.log(chalk.green(`${label} '${name}' added.`));
     console.log(chalk.gray(`Try: agents run ${name} "hello"`));