@robota-sdk/agent-command 3.0.0-beta.76 → 3.0.0-beta.77

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

@@ -1,3 +1,4 @@
+import { confirmAction, isConfirmed, selectAction, textAction } from '@robota-sdk/agent-core';
 import {
   deleteProviderProfile,
   sanitizeProviderProfileName,
@@ -6,48 +7,47 @@ import {
 
 import { formatProviderChoiceLabel } from './provider-command-profile-operations.js';
 
+import type { IUserInteraction } from '@robota-sdk/agent-core';
 import type { IProviderCommandModuleOptions } from '@robota-sdk/agent-framework';
-import type { ICommandInteraction, ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
-const YES = 'yes';
 const MAX_DUPLICATE_PROFILE_SUFFIX = 1000;
 const PROVIDER_RESTART_EFFECT = {
   type: 'session-restart-requested',
   reason: 'other',
 } as const;
 
-export function buildProviderDuplicate(
+export async function buildProviderDuplicate(
+  ui: IUserInteraction,
   profileName: string,
   options: IProviderCommandModuleOptions,
-): ICommandResult {
+): 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));
-  return {
-    message: `Provider duplicate requested: ${profileName}`,
-    success: true,
-    interaction: createProviderDuplicateInteraction(profileName, defaultName, options),
-  };
-}
-
-function createProviderDuplicateInteraction(
-  profileName: string,
-  defaultName: string,
-  options: IProviderCommandModuleOptions,
-): ICommandInteraction {
-  return {
-    prompt: {
-      kind: 'text',
-      title: `Duplicate ${profileName} as`,
-      placeholder: defaultName,
-      allowEmpty: true,
-      validate: (value) => validateDuplicateProfileName(value, defaultName, options),
-    },
-    submit: (value) => completeProviderDuplicate(profileName, value, defaultName, options),
-    cancel: () => ({ message: 'Provider duplicate cancelled.', success: true }),
-  };
+  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(
@@ -90,10 +90,11 @@ function completeProviderDuplicate(
   };
 }
 
-export function buildProviderDelete(
+export async function buildProviderDelete(
+  ui: IUserInteraction,
   profileName: string,
   options: IProviderCommandModuleOptions,
-): ICommandResult {
+): Promise<ICommandResult> {
   const settings = options.settings.readMergedSettings();
   const providers = settings.providers ?? {};
   if (!providers[profileName]) {
@@ -108,40 +109,20 @@ export function buildProviderDelete(
       success: false,
     };
   }
-  return {
-    message: `Provider delete requested: ${profileName}`,
-    success: true,
-    interaction: createProviderDeleteConfirmationInteraction(profileName, options),
-  };
-}
-
-function createProviderDeleteConfirmationInteraction(
-  profileName: string,
-  options: IProviderCommandModuleOptions,
-): ICommandInteraction {
-  return {
-    prompt: {
-      kind: 'choice',
-      title: `Delete provider profile ${profileName}?`,
-      options: [
-        { value: YES, label: 'Yes' },
-        { value: 'no', label: 'No' },
-      ],
-    },
-    submit: (value) => {
-      if (value !== YES) {
-        return { message: 'Provider delete cancelled.', success: true };
-      }
-      return confirmProviderDelete(profileName, options);
-    },
-    cancel: () => ({ message: 'Provider delete cancelled.', success: true }),
-  };
+  const response = await ui.ask(
+    confirmAction('provider-delete', `Delete provider profile ${profileName}?`),
+  );
+  if (!isConfirmed(response)) {
+    return { message: 'Provider delete cancelled.', success: true };
+  }
+  return confirmProviderDelete(ui, profileName, options);
 }
 
-function confirmProviderDelete(
+async function confirmProviderDelete(
+  ui: IUserInteraction,
   profileName: string,
   options: IProviderCommandModuleOptions,
-): ICommandResult {
+): Promise<ICommandResult> {
   const settings = options.settings.readMergedSettings();
   if (settings.currentProvider !== profileName) {
     options.settings.writeTargetSettings(
@@ -155,21 +136,20 @@ function confirmProviderDelete(
       value: name,
       label: formatProviderChoiceLabel(name, profile, settings.currentProvider),
     }));
-  return {
-    message: `Select a replacement provider before deleting ${profileName}.`,
-    success: true,
-    interaction: {
-      prompt: {
-        kind: 'choice',
-        title: `Replacement provider for ${profileName}`,
-        options: replacementOptions,
+  const response = await ui.ask(
+    selectAction(
+      'provider-delete-replacement',
+      `Replacement provider for ${profileName}`,
+      replacementOptions,
+      {
         maxVisible: 8,
       },
-      submit: (replacementName) =>
-        completeActiveProviderDelete(profileName, replacementName, options),
-      cancel: () => ({ message: 'Provider delete cancelled.', success: true }),
-    },
-  };
+    ),
+  );
+  if (response.type !== 'answer' || response.values[0] === undefined) {
+    return { message: 'Provider delete cancelled.', success: true };
+  }
+  return completeActiveProviderDelete(profileName, response.values[0], options);
 }
 
 function completeActiveProviderDelete(

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

@@ -6,19 +6,16 @@ import {
   upsertProviderProfile,
 } from '@robota-sdk/agent-framework';
 
-import {
-  createProviderSetupInteraction,
-  toProviderSetupStepPrompt,
-} from './provider-command-setup.js';
-import { createProviderSetupFlow, submitProviderSetupValue } from './provider-setup-flow.js';
+import { runProviderSetupAsk } from './provider-command-setup.js';
+import { createProviderSetupFlow } from './provider-setup-flow.js';
 
-import type { IProviderSetupFlowState } from './provider-setup-flow.js';
+import type { IUserInteraction } from '@robota-sdk/agent-core';
 import type {
   IProviderCommandModuleOptions,
   IProviderProfileSettings,
   IProviderSetupInput,
 } from '@robota-sdk/agent-framework';
-import type { ICommandInteraction, ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 export function formatProviderChoiceLabel(
   name: string,
@@ -69,10 +66,11 @@ export function buildProviderSwitch(
   };
 }
 
-export function buildProviderEdit(
+export async function buildProviderEdit(
+  ui: IUserInteraction,
   profileName: string,
   options: IProviderCommandModuleOptions,
-): ICommandResult {
+): Promise<ICommandResult> {
   const settings = options.settings.readMergedSettings();
   const profile = settings.providers?.[profileName];
   if (!profile) {
@@ -81,20 +79,22 @@ export function buildProviderEdit(
   if (!profile.type) {
     return { message: `Provider profile "${profileName}" is missing type.`, success: false };
   }
+  let flow;
   try {
-    const flow = createProviderSetupFlow(profile.type, options.providerDefinitions, {
+    flow = createProviderSetupFlow(profile.type, options.providerDefinitions, {
       profileName,
       setCurrent: false,
       initialValues: getProviderProfileSetupValues(profile),
     });
-    return {
-      message: `Provider edit requested: ${profileName}`,
-      success: true,
-      interaction: createProviderEditInteraction(flow, profileName, options),
-    };
   } 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.',
+  );
 }
 
 function getProviderProfileSetupValues(profile: IProviderProfileSettings): {
@@ -109,42 +109,6 @@ function getProviderProfileSetupValues(profile: IProviderProfileSettings): {
   };
 }
 
-function createProviderEditInteraction(
-  flow: IProviderSetupFlowState,
-  profileName: string,
-  options: IProviderCommandModuleOptions,
-): ICommandInteraction {
-  return {
-    prompt: toProviderSetupStepPrompt(flow),
-    submit: (value) => submitProviderEditInteractionValue(flow, profileName, value, options),
-    cancel: () => ({ message: 'Provider edit cancelled.', success: true }),
-  };
-}
-
-function submitProviderEditInteractionValue(
-  flow: IProviderSetupFlowState,
-  profileName: string,
-  value: string,
-  options: IProviderCommandModuleOptions,
-): ICommandResult {
-  const result = submitProviderSetupValue(flow, value);
-  if (result.status === 'error') {
-    return {
-      message: result.message,
-      success: false,
-      interaction: createProviderEditInteraction(flow, profileName, options),
-    };
-  }
-  if (result.status === 'complete') {
-    return completeProviderEdit(result.input, profileName, options);
-  }
-  return {
-    message: '',
-    success: true,
-    interaction: createProviderEditInteraction(result.state, profileName, options),
-  };
-}
-
 function completeProviderEdit(
   input: IProviderSetupInput,
   profileName: string,

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

@@ -1,3 +1,4 @@
+import { selectAction } from '@robota-sdk/agent-core';
 import { testProviderProfileCommand } from '@robota-sdk/agent-framework';
 
 import {
@@ -10,11 +11,12 @@ 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 { ICommandInteraction, ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 const ACTION_SWITCH = 'switch';
 const ACTION_EDIT = 'edit';
@@ -23,64 +25,57 @@ const ACTION_DUPLICATE = 'duplicate';
 const ACTION_DELETE = 'delete';
 const ACTION_CANCEL = 'cancel';
 
-export function createProviderProfileSelectionInteraction(
+/**
+ * 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,
-): 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 }),
-  };
+): 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);
 }
 
-function buildProviderProfileActionMenu(
+async function askProviderProfileAction(
+  ui: IUserInteraction,
   profileName: string,
   options: IProviderCommandModuleOptions,
-): ICommandResult {
+): Promise<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 }),
-  };
+  const response = await ui.ask(
+    selectAction('provider-profile-action', `Provider profile: ${profileName}`, [
+      { 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' },
+    ]),
+  );
+  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,
@@ -90,18 +85,18 @@ async function executeProviderProfileAction(
     case ACTION_SWITCH:
       return buildProviderSwitch(settings.providers, profileName, options);
     case ACTION_EDIT:
-      return buildProviderEdit(profileName, options);
+      return buildProviderEdit(ui, profileName, options);
     case ACTION_TEST:
-      return await testProviderProfileCommand(
+      return testProviderProfileCommand(
         settings.currentProvider,
         settings.providers,
         profileName,
         options,
       );
     case ACTION_DUPLICATE:
-      return buildProviderDuplicate(profileName, options);
+      return buildProviderDuplicate(ui, profileName, options);
     case ACTION_DELETE:
-      return buildProviderDelete(profileName, options);
+      return buildProviderDelete(ui, profileName, options);
     case ACTION_CANCEL:
       return { message: 'Provider profile action cancelled.', success: true };
     default:

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

@@ -1,3 +1,4 @@
+import { textAction } from '@robota-sdk/agent-core';
 import { buildProviderSetupPatch, mergeProviderPatch } from '@robota-sdk/agent-framework';
 
 import {
@@ -5,19 +6,15 @@ import {
   formatProviderSetupHelpLinks,
   getProviderSetupStep,
   submitProviderSetupValue,
-  validateProviderSetupValue,
 } from './provider-setup-flow.js';
 
 import type { IProviderSetupFlowState } from './provider-setup-flow.js';
+import type { IActionRequest, IUserInteraction } from '@robota-sdk/agent-core';
 import type {
   IProviderCommandModuleOptions,
   IProviderSetupInput,
 } from '@robota-sdk/agent-framework';
-import type {
-  ICommandInteraction,
-  ICommandResult,
-  TCommandInteractionPrompt,
-} from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 const PROVIDER_RESTART_EFFECT = {
   type: 'session-restart-requested',
@@ -33,62 +30,70 @@ export function createSetupFlow(
   });
 }
 
-export function createProviderSetupInteraction(
+/** Build the per-step `IActionRequest` for the current setup step (CMD-004 inline ask). */
+function toProviderSetupStepRequest(
   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 {
+  errorMessage?: string,
+): IActionRequest {
   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),
-  };
+  const helpLinks = formatProviderSetupHelpLinks(flow.setupHelpLinks);
+  const description =
+    [errorMessage, helpLinks.length > 0 ? helpLinks : undefined]
+      .filter((part): part is string => part !== undefined && part.length > 0)
+      .join('\n') || undefined;
+  return textAction(`provider-setup-${step.key}`, step.title, {
+    description,
+    placeholder,
+    allowEmpty: step.defaultValue !== undefined,
+    masked: step.masked,
+  });
 }
 
-function toProviderSetupPromptDescription(
+/**
+ * Drive the setup-step engine through inline `ui.ask` calls (CMD-004), re-asking the same step when a
+ * step fails validation (the error is surfaced in the request description). The `complete` sink differs
+ * between the add and edit paths.
+ */
+export async function runProviderSetupAsk(
+  ui: IUserInteraction,
   flow: IProviderSetupFlowState,
-): { description: string } | Record<string, never> {
-  const description = formatProviderSetupHelpLinks(flow.setupHelpLinks);
-  return description.length > 0 ? { description } : {};
+  complete: (input: IProviderSetupInput) => ICommandResult,
+  cancelMessage: string,
+): Promise<ICommandResult> {
+  let state = flow;
+  let errorMessage: string | undefined;
+  for (;;) {
+    const response = await ui.ask(toProviderSetupStepRequest(state, errorMessage));
+    if (response.type === 'cancelled') {
+      return { message: cancelMessage, success: true };
+    }
+    const result = submitProviderSetupValue(state, response.text ?? '');
+    if (result.status === 'error') {
+      errorMessage = result.message;
+      continue;
+    }
+    if (result.status === 'complete') {
+      return complete(result.input);
+    }
+    state = result.state;
+    errorMessage = undefined;
+  }
 }
 
-function submitProviderSetupInteractionValue(
+/** Run the `/provider add` setup wizard inline. */
+export function runProviderAddSetup(
+  ui: IUserInteraction,
   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),
-  };
+): Promise<ICommandResult> {
+  return runProviderSetupAsk(
+    ui,
+    flow,
+    (input) => completeProviderSetup(input, options),
+    'Provider setup cancelled.',
+  );
 }
 
 function completeProviderSetup(

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

@@ -201,6 +201,44 @@ describe('createSessionCommandModule', () => {
     });
   });
 
+  it('CMD-004: confirms before clearing and proceeds on yes', async () => {
+    const clearConversationHistory = vi.fn();
+    const context = {
+      ...createCommandContext(),
+      clearConversationHistory,
+      getUserInteraction: () => ({
+        ask: async () => ({ type: 'answer' as const, values: ['yes'] }),
+      }),
+    };
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('clear', context, '');
+
+    expect(clearConversationHistory).toHaveBeenCalledTimes(1);
+    expect(result?.effects).toEqual([{ type: 'conversation-history-cleared' }]);
+  });
+
+  it('CMD-004: cancels the clear when the user declines', async () => {
+    const clearConversationHistory = vi.fn();
+    const context = {
+      ...createCommandContext(),
+      clearConversationHistory,
+      getUserInteraction: () => ({
+        ask: async () => ({ type: 'answer' as const, values: ['no'] }),
+      }),
+    };
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('clear', context, '');
+
+    expect(clearConversationHistory).not.toHaveBeenCalled();
+    expect(result?.message).toBe('Clear cancelled.');
+  });
+
   it('falls back to runtime clearHistory when the host has not implemented the richer API', async () => {
     const runtime = createRuntime();
     const context = {

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

@@ -15,11 +15,7 @@ import {
 } from './session-command.js';
 
 import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type {
-  ICommand,
-  ICommandInteractionHint,
-  ICommandSource,
-} from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
 
 export function createClearCommandEntry(): ICommand {
   return {
@@ -155,10 +151,6 @@ export class SessionCommandSource implements ICommandSource {
   }
 }
 
-const SESSION_INTERACTION_HINTS: Record<string, ICommandInteractionHint> = {
-  clear: { type: 'confirm', message: 'Clear conversation history?' },
-};
-
 export function createSessionCommandModule(): ICommandModule {
   return {
     name: 'agent-command-session',
@@ -170,6 +162,5 @@ export function createSessionCommandModule(): ICommandModule {
       createCostSystemCommand(),
       createValidateSessionSystemCommand(),
     ],
-    interactionHints: SESSION_INTERACTION_HINTS,
   };
 }

package/src/session/session-command.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { confirmAction, isConfirmed } from '@robota-sdk/agent-core';
 import {
   RENAME_COMMAND_USAGE,
   clearConversationHistory,
@@ -19,7 +20,19 @@ import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 export const CLEAR_COMMAND_MESSAGE = 'Conversation cleared.';
 
-export function executeClearCommand(context: ICommandHostContext, _args: string): ICommandResult {
+export async function executeClearCommand(
+  context: ICommandHostContext,
+  _args: string,
+): Promise<ICommandResult> {
+  // Confirm only when an interactive renderer is attached; with no human the explicit /clear proceeds.
+  const ui = context.getUserInteraction?.();
+  if (ui) {
+    const response = await ui.ask(confirmAction('clear', 'Clear conversation history?'));
+    if (!isConfirmed(response)) {
+      return { success: true, message: 'Clear cancelled.' };
+    }
+  }
+
   clearConversationHistory(context);
   return {
     success: true,