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

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

@@ -7,6 +7,7 @@ import type {
   TProviderSettingsDocument,
 } from '@robota-sdk/agent-framework';
 import { createProviderCommandModule } from '../provider-command-module.js';
+import { scriptedContext } from './scripted-interaction.js';
 
 const providerDefinitions: readonly IProviderDefinition[] = [
   {
@@ -93,7 +94,8 @@ function createExecutor(adapter: IProviderCommandSettingsAdapter): SystemCommand
   return new SystemCommandExecutor([...(module.systemCommands ?? [])]);
 }
 
-const session = {} as ICommandHostContext;
+/** Context with no interactive renderer attached (headless/automation). */
+const headlessContext = {} as ICommandHostContext;
 
 describe('createProviderCommandModule', () => {
   it('contributes /provider metadata and executable command from the provider package', () => {
@@ -107,7 +109,7 @@ describe('createProviderCommandModule', () => {
     expect(module.systemCommands?.map((command) => command.name)).toEqual(['provider']);
   });
 
-  it('lists provider profiles from injected merged settings', async () => {
+  it('asks the user to pick a provider profile from injected merged settings', async () => {
     const { adapter } = createSettingsAdapter({
       currentProvider: 'openai',
       providers: {
@@ -116,18 +118,21 @@ describe('createProviderCommandModule', () => {
       },
     });
 
-    const result = await createExecutor(adapter).execute('provider', session, 'list');
+    const { context, requests } = scriptedContext([{ type: 'cancelled' }]);
+    const result = await createExecutor(adapter).execute('provider', context, 'list');
 
     expect(result?.success).toBe(true);
-    expect(result?.message).toContain('* openai');
-    expect(result?.message).toContain('anthropic');
-    expect(result?.interaction?.prompt).toMatchObject({
-      kind: 'choice',
-      title: 'Select provider profile',
-    });
+    const picker = requests[0];
+    expect(picker?.title).toBe('Select provider profile');
+    expect(picker?.options?.map((option) => option.label)).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('* openai'),
+        expect.stringContaining('anthropic'),
+      ]),
+    );
   });
 
-  it('opens a provider profile picker from /provider without CLI-owned routing', async () => {
+  it('returns a plain text list when no interactive renderer is attached', async () => {
     const { adapter } = createSettingsAdapter({
       currentProvider: 'openai',
       providers: {
@@ -136,14 +141,31 @@ describe('createProviderCommandModule', () => {
       },
     });
 
-    const result = await createExecutor(adapter).execute('provider', session, '');
-    const selected = await result?.interaction?.submit('anthropic');
+    const result = await createExecutor(adapter).execute('provider', headlessContext, 'list');
 
+    expect(result?.success).toBe(true);
     expect(result?.message).toContain('* openai');
-    expect(selected?.interaction?.prompt).toMatchObject({
-      kind: 'choice',
-      title: 'Provider profile: anthropic',
+    expect(result?.message).toContain('anthropic');
+  });
+
+  it('opens a provider profile action menu from /provider after picking a profile', async () => {
+    const { adapter } = createSettingsAdapter({
+      currentProvider: 'openai',
+      providers: {
+        openai: { type: 'openai', model: 'supergemma4-26b-uncensored-v2' },
+        anthropic: { type: 'anthropic', model: 'claude-sonnet-4-6' },
+      },
     });
+
+    const { context, requests } = scriptedContext([
+      { type: 'answer', values: ['anthropic'] },
+      { type: 'cancelled' },
+    ]);
+    const result = await createExecutor(adapter).execute('provider', context, '');
+
+    expect(result?.success).toBe(true);
+    expect(requests[0]?.title).toBe('Select provider profile');
+    expect(requests[1]?.title).toBe('Provider profile: anthropic');
   });
 
   it('switches provider immediately via /provider switch without confirmation dialog', async () => {
@@ -158,9 +180,12 @@ describe('createProviderCommandModule', () => {
       {},
     );
 
-    const result = await createExecutor(adapter).execute('provider', session, 'switch openai');
+    const result = await createExecutor(adapter).execute(
+      'provider',
+      headlessContext,
+      'switch openai',
+    );
 
-    expect(result?.interaction).toBeUndefined();
     expect(result?.message).toBe(
       'Switched to openai (supergemma4-26b-uncensored-v2). History preserved.',
     );
@@ -182,16 +207,17 @@ describe('createProviderCommandModule', () => {
       {},
     );
 
-    const listed = await createExecutor(adapter).execute('provider', session, 'list');
-    const selected = await listed?.interaction?.submit('openai');
-    const switchRequested = await selected?.interaction?.submit('switch');
+    const { context } = scriptedContext([
+      { type: 'answer', values: ['openai'] },
+      { type: 'answer', values: ['switch'] },
+    ]);
+    const result = await createExecutor(adapter).execute('provider', context, 'list');
 
-    expect(switchRequested?.message).toBe(
+    expect(result?.message).toBe(
       'Switched to openai (supergemma4-26b-uncensored-v2). History preserved.',
     );
-    expect(switchRequested?.interaction).toBeUndefined();
     expect(readTarget().currentProvider).toBe('openai');
-    expect(switchRequested?.effects).toEqual([
+    expect(result?.effects).toEqual([
       { type: 'provider-hot-swap-requested', profileName: 'openai' },
     ]);
   });
@@ -211,19 +237,19 @@ describe('createProviderCommandModule', () => {
       {},
     );
 
-    const listed = await createExecutor(adapter).execute('provider', session, 'list');
-    const selected = await listed?.interaction?.submit('anthropic');
-    const editRequested = await selected?.interaction?.submit('edit');
-
-    expect(editRequested?.interaction?.prompt).toMatchObject({
-      kind: 'text',
-      title: 'anthropic API key',
-      placeholder: '(unchanged)',
-      masked: true,
-    });
+    const { context, requests } = scriptedContext([
+      { type: 'answer', values: ['anthropic'] },
+      { type: 'answer', values: ['edit'] },
+      { type: 'answer', values: [], text: '' },
+      { type: 'answer', values: [], text: 'claude-opus-4-5' },
+    ]);
+    const completed = await createExecutor(adapter).execute('provider', context, 'list');
 
-    const modelPrompt = await editRequested?.interaction?.submit('');
-    const completed = await modelPrompt?.interaction?.submit('claude-opus-4-5');
+    const apiKeyRequest = requests[2];
+    expect(apiKeyRequest?.title).toBe('anthropic API key');
+    expect(apiKeyRequest?.allowFreeText).toBe(true);
+    expect(apiKeyRequest?.placeholder).toBe('(unchanged)');
+    expect(apiKeyRequest?.masked).toBe(true);
 
     expect(readTarget()).toMatchObject({
       providers: {
@@ -252,16 +278,15 @@ describe('createProviderCommandModule', () => {
       },
     });
 
-    const listed = await createExecutor(adapter).execute('provider', session, 'list');
-    const selected = await listed?.interaction?.submit('openai');
-    const duplicateRequested = await selected?.interaction?.submit('duplicate');
-    const completed = await duplicateRequested?.interaction?.submit('');
+    const { context, requests } = scriptedContext([
+      { type: 'answer', values: ['openai'] },
+      { type: 'answer', values: ['duplicate'] },
+      { type: 'answer', values: [], text: '' },
+    ]);
+    const completed = await createExecutor(adapter).execute('provider', context, 'list');
 
-    expect(duplicateRequested?.interaction?.prompt).toMatchObject({
-      kind: 'text',
-      title: 'Duplicate openai as',
-      placeholder: 'openai-copy',
-    });
+    expect(requests[2]?.title).toBe('Duplicate openai as');
+    expect(requests[2]?.placeholder).toBe('openai-copy');
     expect(readTarget()).toMatchObject({
       providers: {
         'openai-copy': {
@@ -292,11 +317,16 @@ describe('createProviderCommandModule', () => {
       },
     );
 
-    const listed = await createExecutor(adapter).execute('provider', session, 'list');
-    const selected = await listed?.interaction?.submit('anthropic');
-    const deleteRequested = await selected?.interaction?.submit('delete');
-    const completed = await deleteRequested?.interaction?.submit('yes');
+    const { context, requests } = scriptedContext([
+      { type: 'answer', values: ['anthropic'] },
+      { type: 'answer', values: ['delete'] },
+      { type: 'answer', values: ['yes'] },
+    ]);
+    const completed = await createExecutor(adapter).execute('provider', context, 'list');
 
+    // The confirm prompt must actually be issued — guards against a silent drop of the
+    // confirmation step that would still "delete and pass".
+    expect(requests[2]?.title).toBe('Delete provider profile anthropic?');
     expect(completed?.message).toBe('Provider profile deleted: anthropic.');
     expect(readTarget()).toEqual({
       currentProvider: 'openai',
@@ -324,16 +354,17 @@ describe('createProviderCommandModule', () => {
       },
     );
 
-    const listed = await createExecutor(adapter).execute('provider', session, 'list');
-    const selected = await listed?.interaction?.submit('anthropic');
-    const deleteRequested = await selected?.interaction?.submit('delete');
-    const replacementPrompt = await deleteRequested?.interaction?.submit('yes');
-    const completed = await replacementPrompt?.interaction?.submit('openai');
+    const { context, requests } = scriptedContext([
+      { type: 'answer', values: ['anthropic'] },
+      { type: 'answer', values: ['delete'] },
+      { type: 'answer', values: ['yes'] },
+      { type: 'answer', values: ['openai'] },
+    ]);
+    const completed = await createExecutor(adapter).execute('provider', context, 'list');
 
-    expect(replacementPrompt?.interaction?.prompt).toMatchObject({
-      kind: 'choice',
-      title: 'Replacement provider for anthropic',
-    });
+    // The confirm precedes the replacement picker — assert both so neither step can be dropped silently.
+    expect(requests[2]?.title).toBe('Delete provider profile anthropic?');
+    expect(requests[3]?.title).toBe('Replacement provider for anthropic');
     expect(readTarget()).toEqual({
       currentProvider: 'openai',
       providers: {
@@ -361,30 +392,39 @@ describe('createProviderCommandModule', () => {
       {},
     );
 
-    const listed = await createExecutor(adapter).execute('provider', session, 'list');
-    const selected = await listed?.interaction?.submit('anthropic');
-    const deleteRequested = await selected?.interaction?.submit('delete');
+    const { context } = scriptedContext([
+      { type: 'answer', values: ['anthropic'] },
+      { type: 'answer', values: ['delete'] },
+    ]);
+    const result = await createExecutor(adapter).execute('provider', context, 'list');
 
-    expect(deleteRequested?.success).toBe(false);
-    expect(deleteRequested?.message).toContain('not stored in the active write target');
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('not stored in the active write target');
   });
 
   it('owns provider setup flow and writes settings after generic prompt submissions', async () => {
     const { adapter, readTarget } = createSettingsAdapter({}, {});
-    const first = await createExecutor(adapter).execute('provider', session, 'add openai');
-
-    expect(first?.interaction?.prompt).toMatchObject({
-      kind: 'text',
-      title: 'OpenAI-compatible base URL',
-      description:
-        '  Setup help: Official: OpenAI-compatible local server docs - https://lmstudio.ai/docs/developer',
-      placeholder: 'http://localhost:1234/v1',
-      allowEmpty: true,
-    });
 
-    const second = await first?.interaction?.submit('');
-    const third = await second?.interaction?.submit('');
-    const completed = await third?.interaction?.submit('');
+    const { context, requests } = scriptedContext([
+      { type: 'answer', values: [], text: '' },
+      { type: 'answer', values: [], text: '' },
+      { type: 'answer', values: [], text: '' },
+    ]);
+    const completed = await createExecutor(adapter).execute('provider', context, 'add openai');
+
+    expect(requests[0]?.title).toBe('OpenAI-compatible base URL');
+    expect(requests[0]?.description).toBe(
+      '  Setup help: Official: OpenAI-compatible local server docs - https://lmstudio.ai/docs/developer',
+    );
+    expect(requests[0]?.placeholder).toBe('http://localhost:1234/v1');
+    expect(requests[0]?.allowEmpty).toBe(true);
+    // All three setup steps must be asked in order — a dropped step would otherwise be hidden by the
+    // scripted double returning the surplus answers to whatever remains.
+    expect(requests.map((request) => request.title)).toEqual([
+      'OpenAI-compatible base URL',
+      'OpenAI-compatible model',
+      'OpenAI-compatible API key',
+    ]);
 
     expect(readTarget()).toMatchObject({
       currentProvider: 'openai',
@@ -406,6 +446,35 @@ describe('createProviderCommandModule', () => {
     ]);
   });
 
+  it('asks the user to pick a provider type when /provider add is called without one', async () => {
+    const { adapter, readTarget } = createSettingsAdapter({}, {});
+
+    const { context, requests } = scriptedContext([
+      { type: 'answer', values: ['openai'] },
+      { type: 'answer', values: [], text: '' },
+      { type: 'answer', values: [], text: '' },
+      { type: 'answer', values: [], text: '' },
+    ]);
+    const completed = await createExecutor(adapter).execute('provider', context, 'add');
+
+    expect(requests[0]?.title).toBe('Select provider');
+    expect(requests[0]?.options?.map((option) => option.value)).toEqual(['openai', 'anthropic']);
+    expect(readTarget()).toMatchObject({
+      currentProvider: 'openai',
+      providers: { openai: { type: 'openai' } },
+    });
+    expect(completed?.success).toBe(true);
+  });
+
+  it('reports usage for /provider add without a type when no renderer is attached', async () => {
+    const { adapter } = createSettingsAdapter({}, {});
+
+    const result = await createExecutor(adapter).execute('provider', headlessContext, 'add');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('Usage: provider add <type>');
+  });
+
   it('creates another profile when provider type already exists', async () => {
     const { adapter, readTarget } = createSettingsAdapter(
       {
@@ -421,11 +490,13 @@ describe('createProviderCommandModule', () => {
       },
       {},
     );
-    const first = await createExecutor(adapter).execute('provider', session, 'add openai');
-    const second = await first?.interaction?.submit('');
-    const third = await second?.interaction?.submit('');
 
-    await third?.interaction?.submit('');
+    const { context } = scriptedContext([
+      { type: 'answer', values: [], text: '' },
+      { type: 'answer', values: [], text: '' },
+      { type: 'answer', values: [], text: '' },
+    ]);
+    await createExecutor(adapter).execute('provider', context, 'add openai');
 
     expect(readTarget()).toMatchObject({
       currentProvider: 'openai-2',
@@ -465,7 +536,7 @@ describe('createProviderCommandModule', () => {
     });
     const result = await new SystemCommandExecutor([...(module.systemCommands ?? [])]).execute(
       'provider',
-      session,
+      headlessContext,
       'test openai',
     );
 

package/src/provider/__tests__/scripted-interaction.ts

@@ -0,0 +1,28 @@
+import type { IActionRequest, IUserInteraction, TActionResponse } from '@robota-sdk/agent-core';
+import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+
+/**
+ * Build a command host context whose `getUserInteraction().ask` replays a scripted sequence of
+ * responses (CMD-004 test double). Each `ask` records the request it received (so tests can assert on
+ * the rendered action shape) and returns the next scripted answer; once the script is exhausted it
+ * returns `{ type: 'cancelled' }`, mirroring a user dismissing the prompt.
+ */
+export function scriptedContext(answers: readonly TActionResponse[]): {
+  context: ICommandHostContext;
+  requests: IActionRequest[];
+} {
+  const requests: IActionRequest[] = [];
+  let index = 0;
+  const ui: IUserInteraction = {
+    ask: (request) => {
+      requests.push(request);
+      const answer = answers[index];
+      index += 1;
+      return Promise.resolve(answer ?? { type: 'cancelled' });
+    },
+  };
+  const context = {
+    getUserInteraction: () => ui,
+  } as Partial<ICommandHostContext> as ICommandHostContext;
+  return { context, requests };
+}

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

@@ -1,30 +1,38 @@
-import { findProviderDefinition, formatSupportedProviderTypes } from '@robota-sdk/agent-core';
+import {
+  findProviderDefinition,
+  formatSupportedProviderTypes,
+  selectAction,
+} from '@robota-sdk/agent-core';
 import { testProviderProfileCommand } from '@robota-sdk/agent-framework';
 
 import { buildProviderSwitch } from './provider-command-profile-operations.js';
-import { createProviderProfileSelectionInteraction } from './provider-command-profile.js';
-import { createSetupFlow, createProviderSetupInteraction } from './provider-command-setup.js';
+import { askProviderProfileSelection } from './provider-command-profile.js';
+import { createSetupFlow, runProviderAddSetup } from './provider-command-setup.js';
 import { formatProviderSetupChoiceLabel } from './provider-setup-flow.js';
 
+import type { IUserInteraction } from '@robota-sdk/agent-core';
 import type {
+  ICommandHostContext,
   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';
 
 export async function executeProviderCommand(
+  context: ICommandHostContext,
   args: string,
   options: IProviderCommandModuleOptions,
 ): Promise<ICommandResult> {
+  const ui = context.getUserInteraction?.();
   const settings = options.settings.readMergedSettings();
   const trimmedArgs = args.trim();
   if (trimmedArgs.length === 0) {
-    return buildProviderProfilePicker(settings.currentProvider, settings.providers, options);
+    return buildProviderProfilePicker(ui, settings.currentProvider, settings.providers, options);
   }
   const [subcommand = 'current', profileArg] = trimmedArgs.split(/\s+/);
 
   if (subcommand === 'list') {
-    return buildProviderProfilePicker(settings.currentProvider, settings.providers, options);
+    return buildProviderProfilePicker(ui, settings.currentProvider, settings.providers, options);
   }
   if (subcommand === 'current' || subcommand === '') {
     return {
@@ -36,7 +44,7 @@ export async function executeProviderCommand(
     return buildProviderSwitch(settings.providers, profileArg, options);
   }
   if (subcommand === 'test') {
-    return await testProviderProfileCommand(
+    return testProviderProfileCommand(
       settings.currentProvider,
       settings.providers,
       profileArg,
@@ -44,7 +52,7 @@ export async function executeProviderCommand(
     );
   }
   if (subcommand === 'add') {
-    return buildProviderSetup(profileArg, options);
+    return buildProviderSetup(ui, profileArg, options);
   }
 
   return {
@@ -53,20 +61,20 @@ export async function executeProviderCommand(
   };
 }
 
+/**
+ * List the provider profiles. With an interactive renderer attached, drive the inline profile picker
+ * (CMD-004); without one (headless/automation) or with no profiles, return the formatted list as text.
+ */
 function buildProviderProfilePicker(
+  ui: IUserInteraction | undefined,
   currentProvider: string | undefined,
   providers: Record<string, IProviderProfileSettings> | undefined,
   options: IProviderCommandModuleOptions,
-): ICommandResult {
-  const message = formatProviderList(currentProvider, providers);
-  if (Object.keys(providers ?? {}).length === 0) {
-    return { message, success: true };
+): Promise<ICommandResult> | ICommandResult {
+  if (!ui || Object.keys(providers ?? {}).length === 0) {
+    return { message: formatProviderList(currentProvider, providers), success: true };
   }
-  return {
-    message,
-    success: true,
-    interaction: createProviderProfileSelectionInteraction(currentProvider, providers, options),
-  };
+  return askProviderProfileSelection(ui, currentProvider, providers, options);
 }
 
 function formatProviderList(
@@ -104,16 +112,24 @@ function formatCurrentProvider(
   ].join('\n');
 }
 
+/**
+ * Configure a provider profile. With an explicit `type`, run the setup wizard directly; without one,
+ * ask the user to pick a provider type first (CMD-004). Without an interactive renderer, setup cannot
+ * proceed — return usage text instead of a silent guess.
+ */
 function buildProviderSetup(
+  ui: IUserInteraction | undefined,
   type: string | undefined,
   options: IProviderCommandModuleOptions,
-): ICommandResult {
+): Promise<ICommandResult> | ICommandResult {
   if (type === undefined || type.length === 0) {
-    return {
-      message: 'Provider setup requested. Select a provider to continue.',
-      success: true,
-      interaction: createProviderSelectionInteraction(options),
-    };
+    if (!ui) {
+      return {
+        message: `Usage: provider add <type>. Supported: ${formatSupportedProviderTypes(options.providerDefinitions)}`,
+        success: false,
+      };
+    }
+    return askProviderSetupType(ui, options);
   }
   if (findProviderDefinition(options.providerDefinitions, type) === undefined) {
     return {
@@ -121,34 +137,35 @@ function buildProviderSetup(
       success: false,
     };
   }
-  return {
-    message: `Provider setup requested: ${type}`,
-    success: true,
-    interaction: createProviderSetupInteraction(createSetupFlow(type, options), options),
-  };
+  if (!ui) {
+    return {
+      message: `Provider setup for "${type}" requires an interactive session.`,
+      success: false,
+    };
+  }
+  return runProviderAddSetup(ui, createSetupFlow(type, options), options);
 }
 
-function createProviderSelectionInteraction(
+async function askProviderSetupType(
+  ui: IUserInteraction,
   options: IProviderCommandModuleOptions,
-): ICommandInteraction {
-  return {
-    prompt: {
-      kind: 'choice' as const,
-      title: 'Select provider',
-      options: options.providerDefinitions.map((definition) => ({
-        value: definition.type,
-        label: formatProviderSetupChoiceLabel(definition),
-      })),
-      maxVisible: 6,
-    },
-    submit: (value: string) => {
-      const flow = createSetupFlow(value, options);
-      return {
-        message: `Provider setup requested: ${value}`,
-        success: true,
-        interaction: createProviderSetupInteraction(flow, options),
-      };
-    },
-    cancel: () => ({ message: 'Provider setup cancelled.', success: true }),
-  };
+): Promise<ICommandResult> {
+  const typeOptions = options.providerDefinitions.map((definition) => ({
+    value: definition.type,
+    label: formatProviderSetupChoiceLabel(definition),
+  }));
+  const response = await ui.ask(
+    selectAction('provider-type', 'Select provider', typeOptions, { maxVisible: 6 }),
+  );
+  if (response.type !== 'answer' || response.values[0] === undefined) {
+    return { message: 'Provider setup cancelled.', success: true };
+  }
+  const type = response.values[0];
+  if (findProviderDefinition(options.providerDefinitions, type) === undefined) {
+    return {
+      message: `Usage: provider add <type>. Supported: ${formatSupportedProviderTypes(options.providerDefinitions)}`,
+      success: false,
+    };
+  }
+  return runProviderAddSetup(ui, createSetupFlow(type, options), options);
 }

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

@@ -6,11 +6,7 @@ import type {
   IProviderCommandSettingsAdapter,
   ISystemCommand as TSystemCommand,
 } 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 type { IProviderCommandModuleOptions, IProviderCommandSettingsAdapter };
 
 function buildProviderSubcommands(): ICommand[] {
@@ -56,22 +52,11 @@ function createProviderSystemCommand(options: IProviderCommandModuleOptions): TS
     modelInvocable: false,
     argumentHint: entry.argumentHint,
     subcommands: entry.subcommands,
-    execute: async (_session, args) => executeProviderCommand(args, options),
+    lifecycle: 'inline',
+    execute: (context, args) => executeProviderCommand(context, args, options),
   };
 }
 
-const PROVIDER_INTERACTION_HINTS: Record<string, ICommandInteractionHint> = {
-  provider: {
-    type: 'pick',
-    getItems: () =>
-      buildProviderSubcommands().map((sub) => ({
-        label: sub.name,
-        value: sub.name,
-        description: sub.description,
-      })),
-  },
-};
-
 export function createProviderCommandModule(
   options: IProviderCommandModuleOptions,
 ): TCommandModule {
@@ -79,6 +64,5 @@ export function createProviderCommandModule(
     name: 'agent-command-provider',
     commandSources: [new ProviderCommandSource()],
     systemCommands: [createProviderSystemCommand(options)],
-    interactionHints: PROVIDER_INTERACTION_HINTS,
   };
 }