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

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

@@ -0,0 +1,109 @@
+import type {
+  ICommandInteraction,
+  ICommandResult,
+  IProviderCommandModuleOptions,
+  IProviderProfileSettings,
+} from '@robota-sdk/agent-framework';
+import { testProviderProfileCommand } from '@robota-sdk/agent-framework';
+import {
+  buildProviderEdit,
+  buildProviderSwitch,
+  formatProviderChoiceLabel,
+} from './provider-command-profile-operations.js';
+import {
+  buildProviderDelete,
+  buildProviderDuplicate,
+} from './provider-command-profile-lifecycle.js';
+
+const ACTION_SWITCH = 'switch';
+const ACTION_EDIT = 'edit';
+const ACTION_TEST = 'test';
+const ACTION_DUPLICATE = 'duplicate';
+const ACTION_DELETE = 'delete';
+const ACTION_CANCEL = 'cancel';
+
+export function createProviderProfileSelectionInteraction(
+  currentProvider: string | undefined,
+  providers: Record<string, IProviderProfileSettings> | undefined,
+  options: IProviderCommandModuleOptions,
+): ICommandInteraction {
+  return {
+    prompt: {
+      kind: 'choice',
+      title: 'Select provider profile',
+      options: Object.entries(providers ?? {}).map(([name, profile]) => ({
+        value: name,
+        label: formatProviderChoiceLabel(name, profile, currentProvider),
+      })),
+      maxVisible: 8,
+    },
+    submit: (value) => buildProviderProfileActionMenu(value, options),
+    cancel: () => ({ message: 'Provider profile selection cancelled.', success: true }),
+  };
+}
+
+function buildProviderProfileActionMenu(
+  profileName: string,
+  options: IProviderCommandModuleOptions,
+): ICommandResult {
+  const settings = options.settings.readMergedSettings();
+  if (!settings.providers?.[profileName]) {
+    return { message: `Provider profile "${profileName}" was not found.`, success: false };
+  }
+  return {
+    message: `Provider profile selected: ${profileName}`,
+    success: true,
+    interaction: createProviderProfileActionInteraction(profileName, options),
+  };
+}
+
+function createProviderProfileActionInteraction(
+  profileName: string,
+  options: IProviderCommandModuleOptions,
+): ICommandInteraction {
+  return {
+    prompt: {
+      kind: 'choice',
+      title: `Provider profile: ${profileName}`,
+      options: [
+        { value: ACTION_SWITCH, label: 'Switch' },
+        { value: ACTION_EDIT, label: 'Edit' },
+        { value: ACTION_TEST, label: 'Test' },
+        { value: ACTION_DUPLICATE, label: 'Duplicate' },
+        { value: ACTION_DELETE, label: 'Delete' },
+        { value: ACTION_CANCEL, label: 'Cancel' },
+      ],
+    },
+    submit: (value) => executeProviderProfileAction(profileName, value, options),
+    cancel: () => ({ message: 'Provider profile action cancelled.', success: true }),
+  };
+}
+
+async function executeProviderProfileAction(
+  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(profileName, options);
+    case ACTION_TEST:
+      return await testProviderProfileCommand(
+        settings.currentProvider,
+        settings.providers,
+        profileName,
+        options,
+      );
+    case ACTION_DUPLICATE:
+      return buildProviderDuplicate(profileName, options);
+    case ACTION_DELETE:
+      return buildProviderDelete(profileName, options);
+    case ACTION_CANCEL:
+      return { message: 'Provider profile action cancelled.', success: true };
+    default:
+      return { message: `Unknown provider profile action "${action}".`, success: false };
+  }
+}

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

@@ -0,0 +1,104 @@
+import type {
+  ICommandInteraction,
+  ICommandResult,
+  IProviderCommandModuleOptions,
+  IProviderSetupInput,
+  TCommandInteractionPrompt,
+} from '@robota-sdk/agent-framework';
+import { buildProviderSetupPatch, mergeProviderPatch } from '@robota-sdk/agent-framework';
+import type { IProviderSetupFlowState } from './provider-setup-flow.js';
+import {
+  createProviderSetupFlow,
+  formatProviderSetupHelpLinks,
+  getProviderSetupStep,
+  submitProviderSetupValue,
+  validateProviderSetupValue,
+} from './provider-setup-flow.js';
+
+const PROVIDER_RESTART_EFFECT = {
+  type: 'session-restart-requested',
+  reason: 'other',
+} as const;
+
+export function createSetupFlow(
+  type: string,
+  options: IProviderCommandModuleOptions,
+): IProviderSetupFlowState {
+  return createProviderSetupFlow(type, options.providerDefinitions, {
+    existingProfileNames: Object.keys(options.settings.readMergedSettings().providers ?? {}),
+  });
+}
+
+export function createProviderSetupInteraction(
+  flow: IProviderSetupFlowState,
+  options: IProviderCommandModuleOptions,
+): ICommandInteraction {
+  return {
+    prompt: toProviderSetupStepPrompt(flow),
+    submit: (value) => submitProviderSetupInteractionValue(flow, value, options),
+    cancel: () => ({ message: 'Provider setup cancelled.', success: true }),
+  };
+}
+
+export function toProviderSetupStepPrompt(
+  flow: IProviderSetupFlowState,
+): TCommandInteractionPrompt {
+  const step = getProviderSetupStep(flow);
+  const placeholder =
+    step.masked === true && step.defaultValue !== undefined ? '(unchanged)' : step.defaultValue;
+  return {
+    kind: 'text',
+    title: step.title,
+    ...toProviderSetupPromptDescription(flow),
+    ...(placeholder !== undefined ? { placeholder } : {}),
+    ...(step.defaultValue !== undefined ? { allowEmpty: true } : {}),
+    ...(step.masked !== undefined ? { masked: step.masked } : {}),
+    validate: (value) => validateProviderSetupValue(step, value),
+  };
+}
+
+export function toProviderSetupPromptDescription(
+  flow: IProviderSetupFlowState,
+): { description: string } | Record<string, never> {
+  const description = formatProviderSetupHelpLinks(flow.setupHelpLinks);
+  return description.length > 0 ? { description } : {};
+}
+
+function submitProviderSetupInteractionValue(
+  flow: IProviderSetupFlowState,
+  value: string,
+  options: IProviderCommandModuleOptions,
+): ICommandResult {
+  const result = submitProviderSetupValue(flow, value);
+  if (result.status === 'error') {
+    return {
+      message: result.message,
+      success: false,
+      interaction: createProviderSetupInteraction(flow, options),
+    };
+  }
+  if (result.status === 'complete') {
+    return completeProviderSetup(result.input, options);
+  }
+  return {
+    message: '',
+    success: true,
+    interaction: createProviderSetupInteraction(result.state, options),
+  };
+}
+
+export function completeProviderSetup(
+  input: IProviderSetupInput,
+  options: IProviderCommandModuleOptions,
+): ICommandResult {
+  const target = options.settings.readTargetSettings();
+  const patch = buildProviderSetupPatch(input, {
+    providerDefinitions: options.providerDefinitions,
+  });
+  options.settings.writeTargetSettings(mergeProviderPatch(target, patch));
+  return {
+    message: `Provider ${input.profile} configured. Restarting...`,
+    success: true,
+    effects: [{ ...PROVIDER_RESTART_EFFECT, message: 'Provider setup restart' }],
+  };
+}

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

@@ -0,0 +1,309 @@
+import type {
+  IProviderDefinition,
+  IProviderSetupHelpLink,
+  IProviderSetupStepDefinition,
+  TProviderSetupField,
+} from '@robota-sdk/agent-core';
+import { findProviderDefinition, formatSupportedProviderTypes } from '@robota-sdk/agent-core';
+import type { IProviderSetupInput } from '@robota-sdk/agent-framework';
+import { suggestProviderProfileName } from '@robota-sdk/agent-framework';
+
+export type TProviderSetupType = string;
+export type TPromptInput = (label: string, masked?: boolean) => Promise<string>;
+
+export interface IProviderSetupPromptStep extends IProviderSetupStepDefinition {
+  key: TProviderSetupField;
+}
+
+export interface IProviderSetupFlowState {
+  type: TProviderSetupType;
+  steps: readonly IProviderSetupPromptStep[];
+  setupHelpLinks: readonly IProviderSetupHelpLink[];
+  stepIndex: number;
+  values: Partial<Record<TProviderSetupField, string>>;
+  existingProfileNames: readonly string[];
+  profileName?: string;
+  setCurrent?: boolean;
+}
+
+export interface IProviderSetupFlowOptions {
+  existingProfileNames?: readonly string[];
+  initialValues?: Partial<Record<TProviderSetupField, string>>;
+  profileName?: string;
+  setCurrent?: boolean;
+}
+
+export type TProviderSetupFlowSubmitResult =
+  | {
+      status: 'next';
+      state: IProviderSetupFlowState;
+    }
+  | {
+      status: 'complete';
+      input: IProviderSetupInput;
+    }
+  | {
+      status: 'error';
+      state: IProviderSetupFlowState;
+      message: string;
+    };
+
+export function createProviderSetupFlow(
+  type: TProviderSetupType,
+  providerDefinitions: readonly IProviderDefinition[],
+  options: IProviderSetupFlowOptions = {},
+): IProviderSetupFlowState {
+  const definition = getProviderSetupDefinition(type, providerDefinitions);
+  return {
+    type,
+    steps: applyProviderSetupInitialValues(
+      getProviderSetupSteps(definition),
+      options.initialValues,
+    ),
+    setupHelpLinks: definition.setupHelpLinks ?? [],
+    stepIndex: 0,
+    values: {},
+    existingProfileNames: options.existingProfileNames ?? [],
+    ...(options.profileName !== undefined ? { profileName: options.profileName } : {}),
+    ...(options.setCurrent !== undefined ? { setCurrent: options.setCurrent } : {}),
+  };
+}
+
+export function formatProviderSetupSelectionPrompt(
+  providerDefinitions: readonly IProviderDefinition[],
+): string {
+  if (providerDefinitions.length === 0) {
+    return '  No providers are available.';
+  }
+  const lines = [
+    '  Select provider:',
+    ...providerDefinitions.map(
+      (definition, index) => `    ${index + 1}. ${formatProviderSetupChoiceLabel(definition)}`,
+    ),
+    `  Provider [1-${providerDefinitions.length}] (default: 1): `,
+  ];
+  return lines.join('\n');
+}
+
+export function resolveProviderSetupSelection(
+  rawValue: string,
+  providerDefinitions: readonly IProviderDefinition[],
+): TProviderSetupType {
+  const value = rawValue.trim();
+  const selectedValue = value.length > 0 ? value : '1';
+  const index = parseProviderSelectionIndex(selectedValue);
+  if (index !== undefined) {
+    const definition = providerDefinitions[index];
+    if (definition !== undefined) {
+      return definition.type;
+    }
+    throw new Error(
+      `Provider selection ${selectedValue} is out of range. Currently supported: ${formatSupportedProviderTypes(providerDefinitions)}`,
+    );
+  }
+  const definition = findProviderDefinition(providerDefinitions, selectedValue);
+  if (definition === undefined) {
+    throw new Error(
+      `Unknown provider: ${selectedValue}. Currently supported: ${formatSupportedProviderTypes(providerDefinitions)}`,
+    );
+  }
+  return definition.type;
+}
+
+export function getProviderSetupStep(state: IProviderSetupFlowState): IProviderSetupPromptStep {
+  const step = state.steps[state.stepIndex];
+  if (step === undefined) {
+    throw new Error(`Provider setup step ${state.stepIndex} is out of range`);
+  }
+  return step;
+}
+
+export function submitProviderSetupValue(
+  state: IProviderSetupFlowState,
+  rawValue: string,
+): TProviderSetupFlowSubmitResult {
+  const step = getProviderSetupStep(state);
+  const value = rawValue.trim() || step.defaultValue || '';
+  const validationMessage = validateProviderSetupValue(step, value);
+  if (validationMessage !== undefined) {
+    return { status: 'error', state, message: validationMessage };
+  }
+
+  const nextState = {
+    ...state,
+    stepIndex: state.stepIndex + 1,
+    values: { ...state.values, [step.key]: value },
+  };
+  if (nextState.stepIndex < state.steps.length) {
+    return { status: 'next', state: nextState };
+  }
+  return { status: 'complete', input: buildProviderSetupInput(nextState) };
+}
+
+export async function runProviderSetupPromptFlow(
+  type: TProviderSetupType,
+  promptInput: TPromptInput,
+  providerDefinitions: readonly IProviderDefinition[],
+  options: IProviderSetupFlowOptions = {},
+): Promise<IProviderSetupInput> {
+  let state = createProviderSetupFlow(type, providerDefinitions, options);
+  const stepCount = state.steps.length;
+  while (state.stepIndex < stepCount) {
+    const step = getProviderSetupStep(state);
+    const value = await promptInput(
+      formatProviderSetupPromptLabel(step, state.setupHelpLinks),
+      step.masked === true,
+    );
+    const result = submitProviderSetupValue(state, value);
+    if (result.status === 'complete') {
+      return result.input;
+    }
+    if (result.status === 'error') {
+      throw new Error(result.message);
+    }
+    state = result.state;
+  }
+  throw new Error('Provider setup flow ended without completion');
+}
+
+export function formatProviderSetupPromptLabel(
+  step: IProviderSetupPromptStep,
+  setupHelpLinks: readonly IProviderSetupHelpLink[] = [],
+): string {
+  const suffix = step.defaultValue !== undefined ? ` (default: ${step.defaultValue})` : '';
+  const setupHelp = formatProviderSetupHelpLinks(setupHelpLinks);
+  const prefix = setupHelp.length > 0 ? `${setupHelp}\n` : '';
+  return `${prefix}  ${step.title}${suffix}: `;
+}
+
+export function formatProviderSetupChoiceLabel(definition: IProviderDefinition): string {
+  const label =
+    definition.displayName !== undefined
+      ? `${definition.displayName} (${definition.type})`
+      : definition.type;
+  return definition.description !== undefined ? `${label} - ${definition.description}` : label;
+}
+
+export function formatProviderSetupHelpLinks(
+  setupHelpLinks: readonly IProviderSetupHelpLink[] = [],
+): string {
+  if (setupHelpLinks.length === 0) {
+    return '';
+  }
+  return setupHelpLinks
+    .map(
+      (link) =>
+        `  Setup help: ${formatProviderSetupHelpLinkKind(link.kind)}: ${link.label} - ${link.url}`,
+    )
+    .join('\n');
+}
+
+function parseProviderSelectionIndex(value: string): number | undefined {
+  if (!/^\d+$/.test(value)) {
+    return undefined;
+  }
+  return Number(value) - 1;
+}
+
+export function validateProviderSetupValue(
+  step: IProviderSetupPromptStep,
+  value: string,
+): string | undefined {
+  if (step.required === true && value.length === 0) {
+    return 'Required';
+  }
+  return undefined;
+}
+
+function getProviderSetupDefinition(
+  type: TProviderSetupType,
+  providerDefinitions: readonly IProviderDefinition[],
+): IProviderDefinition {
+  const definition = findProviderDefinition(providerDefinitions, type);
+  if (definition === undefined) {
+    throw new Error(
+      `Unknown provider: ${type}. Currently supported: ${formatSupportedProviderTypes(providerDefinitions)}`,
+    );
+  }
+  return definition;
+}
+
+function getProviderSetupSteps(definition: IProviderDefinition): IProviderSetupPromptStep[] {
+  if (definition.setupSteps !== undefined) {
+    return [...definition.setupSteps];
+  }
+
+  const steps: IProviderSetupPromptStep[] = [
+    {
+      key: 'model',
+      title: `${definition.type} model`,
+      defaultValue: definition.defaults?.model,
+      required: definition.defaults?.model === undefined,
+    },
+  ];
+  if (definition.defaults?.baseURL !== undefined) {
+    steps.unshift({
+      key: 'baseURL',
+      title: `${definition.type} base URL`,
+      defaultValue: definition.defaults.baseURL,
+    });
+  }
+  if (definition.requiresApiKey === true) {
+    steps.push({
+      key: 'apiKey',
+      title: `${definition.type} API key`,
+      defaultValue: definition.defaults?.apiKey,
+      required: definition.defaults?.apiKey === undefined,
+      masked: true,
+    });
+  }
+  return steps;
+}
+
+function formatProviderSetupHelpLinkKind(kind: IProviderSetupHelpLink['kind']): string {
+  if (kind === 'api-key') {
+    return 'API key';
+  }
+  if (kind === 'console') {
+    return 'Console';
+  }
+  return 'Official';
+}
+
+function applyProviderSetupInitialValues(
+  steps: readonly IProviderSetupPromptStep[],
+  initialValues: Partial<Record<TProviderSetupField, string>> | undefined,
+): IProviderSetupPromptStep[] {
+  if (initialValues === undefined) {
+    return [...steps];
+  }
+  return steps.map((step) => {
+    const initialValue = initialValues[step.key];
+    if (initialValue === undefined) {
+      return step;
+    }
+    return {
+      ...step,
+      defaultValue: initialValue,
+      required: false,
+    };
+  });
+}
+
+function buildProviderSetupInput(state: IProviderSetupFlowState): IProviderSetupInput {
+  const profile =
+    state.profileName ??
+    suggestProviderProfileName(
+      { type: state.type },
+      { existingProfileNames: state.existingProfileNames },
+    );
+  const apiKey = state.values.apiKey;
+  return {
+    profile,
+    type: state.type,
+    model: state.values.model,
+    ...(apiKey !== undefined && apiKey.length > 0 && { apiKey }),
+    ...(state.values.baseURL !== undefined && { baseURL: state.values.baseURL }),
+    setCurrent: state.setCurrent ?? true,
+  };
+}

package/src/reset/__tests__/reset-command-module.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import {
+  createResetCommandEntry,
+  createResetCommandModule,
+  executeResetCommand,
+} from '../index.js';
+
+const COMMAND_CONTEXT = {} as ICommandHostContext;
+
+describe('createResetCommandModule', () => {
+  it('provides reset metadata and a user-only executable command from one module owner', () => {
+    const module = createResetCommandModule();
+    const command = module.systemCommands?.[0];
+    const entry = module.commandSources?.[0]?.getCommands()[0];
+
+    expect(module.name).toBe('agent-command-reset');
+    expect(createResetCommandEntry()).toEqual({
+      name: 'reset',
+      displayName: 'Reset Settings',
+      description: 'Delete settings',
+      source: 'reset',
+      modelInvocable: false,
+    });
+    expect(entry).toEqual(createResetCommandEntry());
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'reset',
+        description: 'Delete settings',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+  });
+
+  it('emits a typed settings reset effect without host file I/O', () => {
+    const result = executeResetCommand(COMMAND_CONTEXT, '');
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Reset requested.',
+      data: { resetRequested: true },
+      effects: [{ type: 'settings-reset-requested' }],
+    });
+  });
+
+  it('executes through the SDK system command executor', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createResetCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('reset', COMMAND_CONTEXT, '');
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Reset requested.',
+      data: { resetRequested: true },
+      effects: [{ type: 'settings-reset-requested' }],
+    });
+  });
+});

package/src/reset/index.ts

@@ -0,0 +1,2 @@
+export { createResetCommandModule, createResetCommandEntry } from './reset-command-module.js';
+export { executeResetCommand } from './reset-command.js';

package/src/reset/reset-command-module.ts

@@ -0,0 +1,49 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import { executeResetCommand } from './reset-command.js';
+
+const RESET_COMMAND_DESCRIPTION = 'Delete settings';
+
+export function createResetCommandEntry(): ICommand {
+  return {
+    name: 'reset',
+    displayName: 'Reset Settings',
+    description: RESET_COMMAND_DESCRIPTION,
+    source: 'reset',
+    modelInvocable: false,
+  };
+}
+
+function createResetSystemCommand(): ISystemCommand {
+  const entry = createResetCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: true,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executeResetCommand,
+  };
+}
+
+export class ResetCommandSource implements ICommandSource {
+  readonly name = 'reset';
+
+  getCommands(): ICommand[] {
+    return [createResetCommandEntry()];
+  }
+}
+
+export function createResetCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-reset',
+    commandSources: [new ResetCommandSource()],
+    systemCommands: [createResetSystemCommand()],
+  };
+}

package/src/reset/reset-command.ts

@@ -0,0 +1,10 @@
+import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+
+export function executeResetCommand(_context: ICommandHostContext, _args: string): ICommandResult {
+  return {
+    success: true,
+    message: 'Reset requested.',
+    data: { resetRequested: true },
+    effects: [{ type: 'settings-reset-requested' }],
+  };
+}