@robota-sdk/agent-command 3.0.0-beta.100

package/src/provider/provider-command-profile-lifecycle.ts

@@ -0,0 +1,239 @@
+import { confirmAction, isConfirmed, selectAction, textAction } from '@robota-sdk/agent-core';
+import {
+  deleteProviderProfile,
+  sanitizeProviderProfileName,
+  upsertProviderProfile,
+} from '@robota-sdk/agent-framework';
+
+import { formatProviderChoiceLabel } from './provider-command-profile-operations.js';
+
+import type { IUserInteraction } from '@robota-sdk/agent-core';
+import type {
+  IProviderCommandModuleOptions,
+  IProviderProfileSettings,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+const MAX_DUPLICATE_PROFILE_SUFFIX = 1000;
+const PROVIDER_RESTART_ACTION = {
+  type: 'session-restart',
+  reason: 'other',
+} as const;
+
+export async function buildProviderDuplicate(
+  ui: IUserInteraction,
+  profileName: string,
+  options: IProviderCommandModuleOptions,
+): Promise<ICommandResult> {
+  const settings = options.settings.readMergedSettings();
+  if (!settings.providers?.[profileName]) {
+    return { message: `Provider profile "${profileName}" was not found.`, success: false };
+  }
+  const defaultName = suggestDuplicateProfileName(profileName, Object.keys(settings.providers));
+  let errorMessage: string | undefined;
+  for (;;) {
+    const response = await ui.ask(
+      textAction('provider-duplicate', `Duplicate ${profileName} as`, {
+        description: errorMessage,
+        placeholder: defaultName,
+        allowEmpty: true,
+      }),
+    );
+    if (response.type === 'cancelled') {
+      return { message: 'Provider duplicate cancelled.', success: true };
+    }
+    const value = response.text ?? '';
+    // Re-ask on validation failure, surfacing the reason (CMD-004 re-ask loop replaces the closure).
+    const validationMessage = validateDuplicateProfileName(value, defaultName, options);
+    if (validationMessage !== undefined) {
+      errorMessage = validationMessage;
+      continue;
+    }
+    return completeProviderDuplicate(profileName, value, defaultName, options);
+  }
+}
+
+function validateDuplicateProfileName(
+  value: string,
+  defaultName: string,
+  options: IProviderCommandModuleOptions,
+): string | undefined {
+  const name = normalizeProfileName(value, defaultName);
+  if (name.length === 0) {
+    return 'Required';
+  }
+  if (options.settings.readMergedSettings().providers?.[name] !== undefined) {
+    return `Provider profile "${name}" already exists`;
+  }
+  return undefined;
+}
+
+function completeProviderDuplicate(
+  profileName: string,
+  value: string,
+  defaultName: string,
+  options: IProviderCommandModuleOptions,
+): ICommandResult {
+  const settings = options.settings.readMergedSettings();
+  const sourceProfile = settings.providers?.[profileName];
+  if (!sourceProfile) {
+    return { message: `Provider profile "${profileName}" was not found.`, success: false };
+  }
+  const targetName = normalizeProfileName(value, defaultName);
+  const validationMessage = validateDuplicateProfileName(targetName, defaultName, options);
+  if (validationMessage !== undefined) {
+    return { message: validationMessage, success: false };
+  }
+  options.settings.writeTargetSettings(
+    upsertProviderProfile(options.settings.readTargetSettings(), targetName, { ...sourceProfile }),
+  );
+  return {
+    message: `Provider profile duplicated: ${profileName} -> ${targetName}.`,
+    success: true,
+  };
+}
+
+/**
+ * #3282 §4b: the direct, non-interactive delete itself — no replacement ask (the interactive
+ * per-profile menu's Delete, `buildProviderDelete` below, still offers one); refuses instead when the
+ * profile is the one in use. Never asks to CONFIRM either — its caller in `provider-command-execution`
+ * does that first, when a human can answer, before reaching this function; this function itself is
+ * called only once a delete is already decided (confirmed by a human, or `--confirmed` from the
+ * Settings screen's own ConfirmDialog).
+ */
+export function buildProviderProfileDelete(
+  providers: Record<string, IProviderProfileSettings> | undefined,
+  currentProvider: string | undefined,
+  profileName: string | undefined,
+  options: IProviderCommandModuleOptions,
+): ICommandResult {
+  if (!profileName) {
+    return { message: 'Usage: /provider delete <profile>', success: false };
+  }
+  if (!providers?.[profileName]) {
+    return { message: `Provider profile "${profileName}" was not found.`, success: false };
+  }
+  if (Object.keys(providers).length <= 1) {
+    return { message: 'Cannot delete the only provider profile.', success: false };
+  }
+  if (currentProvider === profileName) {
+    return {
+      message: 'Cannot delete the profile in use. Switch to another profile first.',
+      success: false,
+    };
+  }
+  if (options.settings.readTargetSettings().providers?.[profileName] === undefined) {
+    return {
+      message: `Provider profile "${profileName}" is not stored in the active write target; edit its source settings file or override it before deleting.`,
+      success: false,
+    };
+  }
+  options.settings.writeTargetSettings(
+    deleteProviderProfile(options.settings.readTargetSettings(), profileName),
+  );
+  return { message: `Provider profile deleted: ${profileName}.`, success: true };
+}
+
+export async function buildProviderDelete(
+  ui: IUserInteraction,
+  profileName: string,
+  options: IProviderCommandModuleOptions,
+): Promise<ICommandResult> {
+  const settings = options.settings.readMergedSettings();
+  const providers = settings.providers ?? {};
+  if (!providers[profileName]) {
+    return { message: `Provider profile "${profileName}" was not found.`, success: false };
+  }
+  if (Object.keys(providers).length <= 1) {
+    return { message: 'Cannot delete the only provider profile.', success: false };
+  }
+  if (options.settings.readTargetSettings().providers?.[profileName] === undefined) {
+    return {
+      message: `Provider profile "${profileName}" is not stored in the active write target; edit its source settings file or override it before deleting.`,
+      success: false,
+    };
+  }
+  // #3282 §2: the GUI renders this confirm on its shared ConfirmDialog (id 'provider-delete') with
+  // this exact title — kept in the quoted-name form the TUI's inline picker shows the same way.
+  const response = await ui.ask(
+    confirmAction('provider-delete', `Delete profile "${profileName}"?`),
+  );
+  if (!isConfirmed(response)) {
+    return { message: 'Provider delete cancelled.', success: true };
+  }
+  return confirmProviderDelete(ui, profileName, options);
+}
+
+async function confirmProviderDelete(
+  ui: IUserInteraction,
+  profileName: string,
+  options: IProviderCommandModuleOptions,
+): Promise<ICommandResult> {
+  const settings = options.settings.readMergedSettings();
+  if (settings.currentProvider !== profileName) {
+    options.settings.writeTargetSettings(
+      deleteProviderProfile(options.settings.readTargetSettings(), profileName),
+    );
+    return { message: `Provider profile deleted: ${profileName}.`, success: true };
+  }
+  const replacementOptions = Object.entries(settings.providers ?? {})
+    .filter(([name]) => name !== profileName)
+    .map(([name, profile]) => ({
+      value: name,
+      label: formatProviderChoiceLabel(name, profile, settings.currentProvider),
+    }));
+  const response = await ui.ask(
+    selectAction(
+      'provider-delete-replacement',
+      `Replacement provider for ${profileName}`,
+      replacementOptions,
+      {
+        maxVisible: 8,
+      },
+    ),
+  );
+  if (response.type !== 'answer' || response.values[0] === undefined) {
+    return { message: 'Provider delete cancelled.', success: true };
+  }
+  return completeActiveProviderDelete(profileName, response.values[0], options);
+}
+
+function completeActiveProviderDelete(
+  profileName: string,
+  replacementName: string,
+  options: IProviderCommandModuleOptions,
+): ICommandResult {
+  const settings = options.settings.readMergedSettings();
+  if (settings.providers?.[replacementName] === undefined || replacementName === profileName) {
+    return { message: `Provider profile "${replacementName}" was not found.`, success: false };
+  }
+  const target = deleteProviderProfile(options.settings.readTargetSettings(), profileName);
+  options.settings.writeTargetSettings({ ...target, currentProvider: replacementName });
+  return {
+    message: `Provider profile deleted: ${profileName}. Restarting with ${replacementName}...`,
+    success: true,
+    hostActions: [{ ...PROVIDER_RESTART_ACTION, message: 'Provider delete restart' }],
+  };
+}
+
+function suggestDuplicateProfileName(
+  profileName: string,
+  existingProfileNames: readonly string[],
+): string {
+  const base = sanitizeProviderProfileName(`${profileName}-copy`) ?? 'provider-copy';
+  if (!existingProfileNames.includes(base)) {
+    return base;
+  }
+  for (let index = 2; index < MAX_DUPLICATE_PROFILE_SUFFIX; index += 1) {
+    const candidate = `${base}-${index}`;
+    if (!existingProfileNames.includes(candidate)) {
+      return candidate;
+    }
+  }
+  return `${base}-${Date.now()}`;
+}
+
+function normalizeProfileName(value: string, defaultName: string): string {
+  const raw = value.trim() || defaultName;
+  return sanitizeProviderProfileName(raw) ?? '';
+}

package/src/provider/provider-command-profile-operations.ts

@@ -0,0 +1,218 @@
+import {
+  buildProviderSetupPatch,
+  formatOrgPolicyViolationMessage,
+  isApiKeyPlaintext,
+  setCurrentProvider,
+  upsertProviderProfile,
+} from '@robota-sdk/agent-framework';
+
+import { runProviderSetupAsk } from './provider-command-setup.js';
+import { createProviderSetupFlow } from './provider-setup-flow.js';
+import {
+  hasProviderConnectionMethods,
+  runProviderConnectionSetup,
+} from './provider-connection-setup.js';
+import { validateProviderConnection } from './provider-connection-validation.js';
+
+import type { IUserInteraction } from '@robota-sdk/agent-core';
+import type {
+  IProviderCommandModuleOptions,
+  IProviderProfileSettings,
+  IProviderSetupInput,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+export function formatProviderChoiceLabel(
+  name: string,
+  profile: IProviderProfileSettings,
+  currentProvider: string | undefined,
+): string {
+  const marker = name === currentProvider ? '* ' : '';
+  return `${marker}${name}: ${profile.type ?? 'unknown'} ${profile.model ?? '(no model)'}`;
+}
+
+export async function buildProviderSwitch(
+  providers: Record<string, IProviderProfileSettings> | undefined,
+  profileName: string | undefined,
+  options: IProviderCommandModuleOptions,
+): Promise<ICommandResult> {
+  if (!profileName) {
+    return { message: 'Usage: /provider switch <profile>', success: false };
+  }
+  if (!providers?.[profileName]) {
+    return { message: `Provider profile "${profileName}" was not found.`, success: false };
+  }
+  const { orgPolicy } = options;
+  if (orgPolicy?.allowedProviders && !orgPolicy.allowedProviders.includes(profileName)) {
+    return {
+      message: formatOrgPolicyViolationMessage(
+        `Provider "${profileName}" is not allowed by your organization policy. Allowed: ${orgPolicy.allowedProviders.join(', ')}.`,
+        orgPolicy.adminContact,
+      ),
+      success: false,
+    };
+  }
+  const initial = options.settings.readMergedSettings();
+  if (initial.currentProvider === profileName) {
+    return { message: `Already using provider "${profileName}".`, success: true };
+  }
+  const profile = providers[profileName];
+  // #3282: the hot-swap this returns as a `hostActions` entry builds this exact profile against
+  // these exact definitions (`resolveUserSettingsProviderSwitch` in agent-framework). Validating it
+  // HERE, before anything is written, means a switch that would fail changes nothing on disk — the
+  // previous behavior wrote `currentProvider` unconditionally and let a downstream hot-swap failure
+  // (e.g. "Unknown provider: anthropic. Currently supported: ", an empty list) stand uncorrected.
+  try {
+    await validateProviderConnection(profileName, profile, options);
+  } catch (error) {
+    return {
+      message: `Failed to switch to "${profileName}": ${error instanceof Error ? error.message : String(error)}`,
+      success: false,
+    };
+  }
+  const target = options.settings.readTargetSettings();
+  const merged = options.settings.readMergedSettings();
+  if (
+    merged.currentProvider !== initial.currentProvider ||
+    JSON.stringify(merged.providers?.[profileName]) !== JSON.stringify(profile)
+  ) {
+    return {
+      success: false,
+      message: 'Provider settings changed while switching. Run /provider switch again.',
+    };
+  }
+  const next =
+    target.providers?.[profileName] !== undefined || merged.providers?.[profileName] !== undefined
+      ? { ...target, currentProvider: profileName }
+      : setCurrentProvider(target, profileName);
+  options.settings.writeTargetSettings(next);
+  const modelLabel = profile.model ?? 'unknown model';
+  return {
+    message: `Switched to ${profileName} (${modelLabel}). History preserved.`,
+    success: true,
+    hostActions: [{ type: 'provider-hot-swap', profileName }],
+  };
+}
+
+export async function buildProviderEdit(
+  ui: IUserInteraction,
+  profileName: string,
+  options: IProviderCommandModuleOptions,
+): Promise<ICommandResult> {
+  const settings = options.settings.readMergedSettings();
+  const profile = settings.providers?.[profileName];
+  if (!profile) {
+    return { message: `Provider profile "${profileName}" was not found.`, success: false };
+  }
+  if (!profile.type) {
+    return { message: `Provider profile "${profileName}" is missing type.`, success: false };
+  }
+  let flow;
+  try {
+    flow = createProviderSetupFlow(profile.type, options.providerDefinitions, {
+      includeEditOnlySteps: true,
+      profileName,
+      setCurrent: false,
+      initialValues: getProviderProfileSetupValues(profile),
+    });
+    if (hasProviderConnectionMethods(profile.type, options)) {
+      flow = { ...flow, steps: flow.steps.filter((step) => step.key !== 'apiKey') };
+    }
+  } catch (error) {
+    return { message: error instanceof Error ? error.message : String(error), success: false };
+  }
+  return runProviderSetupAsk(
+    ui,
+    flow,
+    (input) => completeProviderEdit(input, profileName, options),
+    'Provider edit cancelled.',
+  );
+}
+
+/** Explicitly replace this profile's connection; ordinary editing preserves its credential. */
+export async function buildProviderReconnect(
+  ui: IUserInteraction,
+  profileName: string,
+  options: IProviderCommandModuleOptions,
+): Promise<ICommandResult> {
+  const profile = options.settings.readMergedSettings().providers?.[profileName];
+  if (!profile?.type)
+    return { success: false, message: `Provider profile "${profileName}" was not found.` };
+  if (!hasProviderConnectionMethods(profile.type, options)) {
+    return {
+      success: false,
+      message: `Use /provider edit ${profileName} to update this provider's credentials.`,
+    };
+  }
+  const flow = createProviderSetupFlow(profile.type, options.providerDefinitions, {
+    profileName,
+    setCurrent: false,
+    initialValues: { ...(profile.model === undefined ? {} : { model: profile.model }) },
+  });
+  return runProviderConnectionSetup(ui, flow, options, false, true);
+}
+
+function getProviderProfileSetupValues(profile: IProviderProfileSettings): {
+  model?: string;
+  apiKey?: string;
+  baseURL?: string;
+} {
+  return {
+    ...(typeof profile.model === 'string' ? { model: profile.model } : {}),
+    ...(typeof profile.apiKey === 'string' ? { apiKey: profile.apiKey } : {}),
+    ...(typeof profile.baseURL === 'string' ? { baseURL: profile.baseURL } : {}),
+  };
+}
+
+function completeProviderEdit(
+  input: IProviderSetupInput,
+  profileName: string,
+  options: IProviderCommandModuleOptions,
+): ICommandResult {
+  const merged = options.settings.readMergedSettings();
+  const currentProfile = merged.providers?.[profileName];
+  if (!currentProfile) {
+    return { message: `Provider profile "${profileName}" was not found.`, success: false };
+  }
+  const { orgPolicy } = options;
+  if (orgPolicy?.requireApiKeyFromEnv && isApiKeyPlaintext(input.apiKey)) {
+    return {
+      message: formatOrgPolicyViolationMessage(
+        'Your organization policy requires API keys to be stored as environment variable references ($ENV:VAR_NAME), not as plaintext.',
+        orgPolicy.adminContact,
+      ),
+      success: false,
+    };
+  }
+  const target = options.settings.readTargetSettings();
+  const patch = buildProviderSetupPatch(
+    {
+      ...input,
+      ...(input.apiKey === undefined && currentProfile.apiKeyRef !== undefined
+        ? { apiKeyRef: currentProfile.apiKeyRef }
+        : {}),
+      ...(input.apiKey === undefined && currentProfile.apiKey !== undefined
+        ? { apiKey: currentProfile.apiKey }
+        : {}),
+    },
+    {
+      providerDefinitions: options.providerDefinitions,
+      ...(options.env === undefined ? {} : { env: options.env }),
+    },
+  );
+  const updatedProfile = patch.providers[profileName];
+  if (!updatedProfile) {
+    return { message: `Provider profile "${profileName}" was not updated.`, success: false };
+  }
+  options.settings.writeTargetSettings(
+    upsertProviderProfile(target, profileName, { ...currentProfile, ...updatedProfile }),
+  );
+  const isCurrent = merged.currentProvider === profileName;
+  return {
+    message: isCurrent
+      ? `Provider ${profileName} updated. Switching...`
+      : `Provider ${profileName} updated.`,
+    success: true,
+    ...(isCurrent ? { hostActions: [{ type: 'provider-hot-swap' as const, profileName }] } : {}),
+  };
+}

package/src/provider/provider-command-profile.ts

@@ -0,0 +1,116 @@
+import { selectAction } from '@robota-sdk/agent-core';
+import { testProviderProfileCommand } from '@robota-sdk/agent-framework';
+
+import {
+  buildProviderDelete,
+  buildProviderDuplicate,
+} from './provider-command-profile-lifecycle.js';
+import {
+  buildProviderEdit,
+  buildProviderReconnect,
+  buildProviderSwitch,
+  formatProviderChoiceLabel,
+} from './provider-command-profile-operations.js';
+import { hasProviderConnectionMethods } from './provider-connection-setup.js';
+
+import type { IUserInteraction } from '@robota-sdk/agent-core';
+import type {
+  IProviderCommandModuleOptions,
+  IProviderProfileSettings,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+const ACTION_SWITCH = 'switch';
+const ACTION_EDIT = 'edit';
+const ACTION_TEST = 'test';
+const ACTION_DUPLICATE = 'duplicate';
+const ACTION_DELETE = 'delete';
+const ACTION_RECONNECT = 'reconnect';
+
+/**
+ * Ask the user to pick a provider profile, then drive its action menu (CMD-004 inline ask). Replaces
+ * the former returned choice→submit continuation chain — the picker's own option list is the rendered
+ * profile list, so the caller no longer prepends a separate list message.
+ */
+export async function askProviderProfileSelection(
+  ui: IUserInteraction,
+  currentProvider: string | undefined,
+  providers: Record<string, IProviderProfileSettings> | undefined,
+  options: IProviderCommandModuleOptions,
+): Promise<ICommandResult> {
+  const profileOptions = Object.entries(providers ?? {}).map(([name, profile]) => ({
+    value: name,
+    label: formatProviderChoiceLabel(name, profile, currentProvider),
+  }));
+  const response = await ui.ask(
+    selectAction('provider-profile', 'Select provider profile', profileOptions, { maxVisible: 8 }),
+  );
+  if (response.type !== 'answer' || response.values[0] === undefined) {
+    return { message: 'Provider profile selection cancelled.', success: true };
+  }
+  return askProviderProfileAction(ui, response.values[0], options);
+}
+
+async function askProviderProfileAction(
+  ui: IUserInteraction,
+  profileName: string,
+  options: IProviderCommandModuleOptions,
+): Promise<ICommandResult> {
+  const settings = options.settings.readMergedSettings();
+  if (!settings.providers?.[profileName]) {
+    return { message: `Provider profile "${profileName}" was not found.`, success: false };
+  }
+  // #3282 §2: no separate 'cancel' option here — the picker's own persistent Cancel affordance
+  // (every ask renderer offers one, e.g. `PermissionPrompt`'s ghost Cancel button in agent-ui-web)
+  // is the only Cancel a person sees. A second one, indistinguishable from Switch/Edit/Test/Duplicate
+  // in a flat list, was the audited bug (#3282 issue text): "Delete looks the same as Switch... plus
+  // a second Cancel." Order matters too — Switch first as the primary action, then Edit/Test/
+  // Duplicate, with Delete last: a client (the GUI's provider-action menu) that wants Delete
+  // separated and styled destructive can rely on it always being the final entry.
+  const response = await ui.ask(
+    selectAction('provider-profile-action', `Provider profile: ${profileName}`, [
+      { value: ACTION_SWITCH, label: 'Switch' },
+      { value: ACTION_EDIT, label: 'Edit' },
+      ...(hasProviderConnectionMethods(settings.providers[profileName]?.type ?? '', options)
+        ? [{ value: ACTION_RECONNECT, label: 'Reconnect' }]
+        : []),
+      { value: ACTION_TEST, label: 'Test' },
+      { value: ACTION_DUPLICATE, label: 'Duplicate' },
+      { value: ACTION_DELETE, label: 'Delete' },
+    ]),
+  );
+  if (response.type !== 'answer' || response.values[0] === undefined) {
+    return { message: 'Provider profile action cancelled.', success: true };
+  }
+  return executeProviderProfileAction(ui, profileName, response.values[0], options);
+}
+
+async function executeProviderProfileAction(
+  ui: IUserInteraction,
+  profileName: string,
+  action: string,
+  options: IProviderCommandModuleOptions,
+): Promise<ICommandResult> {
+  const settings = options.settings.readMergedSettings();
+  switch (action) {
+    case ACTION_SWITCH:
+      return buildProviderSwitch(settings.providers, profileName, options);
+    case ACTION_EDIT:
+      return buildProviderEdit(ui, profileName, options);
+    case ACTION_RECONNECT:
+      return buildProviderReconnect(ui, profileName, options);
+    case ACTION_TEST:
+      return testProviderProfileCommand(
+        settings.currentProvider,
+        settings.providers,
+        profileName,
+        options,
+      );
+    case ACTION_DUPLICATE:
+      return buildProviderDuplicate(ui, profileName, options);
+    case ACTION_DELETE:
+      return buildProviderDelete(ui, profileName, options);
+    default:
+      return { message: `Unknown provider profile action "${action}".`, success: false };
+  }
+}

package/src/provider/provider-command-setup.ts

@@ -0,0 +1,79 @@
+import { buildProviderSetupPatch, mergeProviderPatch } from '@robota-sdk/agent-framework';
+
+import { createProviderSetupFlow } from './provider-setup-flow.js';
+import { runProviderSetupAsk } from './provider-setup-ask.js';
+import {
+  hasProviderConnectionMethods,
+  runProviderConnectionSetup,
+} from './provider-connection-setup.js';
+
+import type { IProviderSetupFlowState } from './provider-setup-flow.js';
+import type { IUserInteraction } from '@robota-sdk/agent-core';
+import type {
+  IProviderCommandModuleOptions,
+  IProviderSetupInput,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+export { runProviderSetupAsk } from './provider-setup-ask.js';
+
+const PROVIDER_RESTART_ACTION = {
+  type: 'session-restart',
+  reason: 'other',
+} as const;
+
+export function createSetupFlow(
+  type: string,
+  options: IProviderCommandModuleOptions,
+): IProviderSetupFlowState {
+  return createProviderSetupFlow(type, options.providerDefinitions, {
+    existingProfileNames: Object.keys(options.settings.readMergedSettings().providers ?? {}),
+  });
+}
+
+/** Run the `/provider add` setup wizard inline. */
+export function runProviderAddSetup(
+  ui: IUserInteraction,
+  flow: IProviderSetupFlowState,
+  options: IProviderCommandModuleOptions,
+  isSetupRequired: boolean,
+): Promise<ICommandResult> {
+  if (hasProviderConnectionMethods(flow.type, options)) {
+    return runProviderConnectionSetup(ui, flow, options, isSetupRequired);
+  }
+  return runProviderSetupAsk(
+    ui,
+    flow,
+    (input) => completeProviderSetup(input, options, isSetupRequired),
+    'Provider setup cancelled.',
+  );
+}
+
+function completeProviderSetup(
+  input: IProviderSetupInput,
+  options: IProviderCommandModuleOptions,
+  isSetupRequired: boolean,
+): ICommandResult {
+  const target = options.settings.readTargetSettings();
+  const patch = buildProviderSetupPatch(input, {
+    providerDefinitions: options.providerDefinitions,
+    ...(options.env === undefined ? {} : { env: options.env }),
+  });
+  options.settings.writeTargetSettings(mergeProviderPatch(target, patch));
+  // #3282 §3: the session's own live setup-mode state (never settings — an ordinary env-default
+  // session also has no persisted `currentProvider`, and restarts like any other session). Only a
+  // session that itself started with a placeholder provider hot-swaps the real one in; every other
+  // `/provider add`, even a session's first EVER persisted profile, restarts as before.
+  if (isSetupRequired) {
+    return {
+      message: `Provider ${input.profile} configured.`,
+      success: true,
+      hostActions: [{ type: 'provider-hot-swap', profileName: input.profile }],
+    };
+  }
+  return {
+    message: `Provider ${input.profile} configured. Restarting...`,
+    success: true,
+    hostActions: [{ ...PROVIDER_RESTART_ACTION, message: 'Provider setup restart' }],
+  };
+}