@robota-sdk/agent-command 3.0.0-beta.90 → 3.0.0-beta.93

package/src/provider/provider-connection-validation.ts

@@ -0,0 +1,38 @@
+import { normalizeProviderConfig } from '@robota-sdk/agent-core';
+import { validateProviderProfile } from '@robota-sdk/agent-framework';
+
+import type {
+  IProviderCommandModuleOptions,
+  IProviderProfileSettings,
+} from '@robota-sdk/agent-framework';
+
+/** A settings change must not commit a connection its host can no longer resolve. */
+export async function validateProviderConnection(
+  profileName: string,
+  profile: IProviderProfileSettings,
+  options: IProviderCommandModuleOptions,
+): Promise<void> {
+  validateProviderProfile(profileName, profile, {
+    providerDefinitions: options.providerDefinitions,
+    ...(options.env === undefined ? {} : { env: options.env }),
+  });
+  if (profile.apiKeyRef === undefined) return;
+  try {
+    if (options.resolveCredential === undefined)
+      throw new Error('Host credential resolution unavailable.');
+    const resolved = await options.resolveCredential(
+      normalizeProviderConfig(
+        {
+          name: profile.type!,
+          model: profile.model,
+          apiKeyRef: profile.apiKeyRef,
+          baseURL: profile.baseURL,
+        },
+        options.providerDefinitions,
+      ),
+    );
+    if (!resolved.apiKey?.trim()) throw new Error('Host credential unavailable.');
+  } catch {
+    throw new Error(`Saved connection unavailable. Run /provider reconnect ${profileName}.`);
+  }
+}

package/src/provider/provider-onboarding.ts

@@ -1,7 +1,7 @@
 import type { TPromptInput } from './provider-setup-flow.js';
 import type { ITerminalOutput } from '@robota-sdk/agent-core';
 
-export type TOnboardingPath = 'has-key' | 'free-key' | 'local';
+export type TOnboardingPath = 'has-key' | 'free-key' | 'local' | 'connect';
 
 export interface IOnboardingResult {
   path: TOnboardingPath;
@@ -44,10 +44,19 @@ const LOCAL_MODEL_GUIDE = `
 export async function runOnboardingBranch(
   promptInput: TPromptInput,
   terminal: ITerminalOutput,
+  offerOpenRouter = false,
 ): Promise<IOnboardingResult> {
-  const raw = await promptInput(ONBOARDING_PROMPT);
+  const prompt = offerOpenRouter
+    ? ONBOARDING_PROMPT.replace(
+        '  Choose [1-3]',
+        '    4. Connect with OpenRouter (Browser or API key)\n\n  Choose [1-4]',
+      )
+    : ONBOARDING_PROMPT;
+  const raw = await promptInput(prompt);
   const choice = raw.trim() || '1';
 
+  if (offerOpenRouter && choice === '4') return { path: 'connect', preselectedType: 'openrouter' };
+
   if (choice === '2') {
     terminal.writeLine(GEMINI_GUIDE);
     await promptInput('  Press Enter when you have your API key: ');

package/src/provider/provider-prompt-interaction.ts

@@ -0,0 +1,28 @@
+import type { IUserInteraction } from '@robota-sdk/agent-core';
+import type { TPromptInput } from './provider-setup-flow.js';
+
+/** Adapt existing terminal key/model prompts; browser waiting uses the host's abortable interaction. */
+export function createProviderPromptInteraction(promptInput: TPromptInput): IUserInteraction {
+  return {
+    async ask(request, options) {
+      const choices = request.options ?? [];
+      const labels = [
+        request.description,
+        `  ${request.title}`,
+        ...choices.map((choice, index) => `    ${index + 1}. ${choice.label}`),
+        choices.length > 0 ? '  Choose: ' : `  ${request.placeholder ?? ''}: `,
+      ]
+        .filter((value) => value !== undefined)
+        .join('\n');
+      const answer = await promptInput(labels, request.masked, options);
+      if (options?.signal?.aborted) return { type: 'cancelled' };
+      if (choices.length === 0) return { type: 'answer', values: [], text: answer };
+      const selected =
+        choices[Number(answer.trim() || '1') - 1] ??
+        choices.find((choice) => choice.value === answer.trim());
+      return selected === undefined
+        ? { type: 'cancelled' }
+        : { type: 'answer', values: [selected.value] };
+    },
+  };
+}

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

@@ -0,0 +1,67 @@
+import { textAction } from '@robota-sdk/agent-core';
+
+import {
+  formatProviderSetupHelpLinks,
+  getProviderSetupStep,
+  submitProviderSetupValue,
+} from './provider-setup-flow.js';
+
+import type { IActionRequest, IUserInteraction } from '@robota-sdk/agent-core';
+import type { IProviderSetupInput } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { IProviderSetupFlowState } from './provider-setup-flow.js';
+
+/** Build the per-step `IActionRequest` for the current setup step (CMD-004 inline ask). */
+function toProviderSetupStepRequest(
+  flow: IProviderSetupFlowState,
+  errorMessage?: string,
+): IActionRequest {
+  const step = getProviderSetupStep(flow);
+  const placeholder =
+    step.masked === true && step.defaultValue !== undefined ? '(unchanged)' : step.defaultValue;
+  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 || (step.editOnly === true && step.required !== true),
+    masked: step.masked,
+  });
+}
+
+/**
+ * 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,
+  complete: (input: IProviderSetupInput) => ICommandResult | Promise<ICommandResult>,
+  cancelMessage: string,
+  signal?: AbortSignal,
+): Promise<ICommandResult> {
+  let state = flow;
+  let errorMessage: string | undefined;
+  for (;;) {
+    if (signal?.aborted) return { message: cancelMessage, success: true };
+    const response = await ui.ask(toProviderSetupStepRequest(state, errorMessage), { signal });
+    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;
+  }
+}

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

@@ -10,7 +10,11 @@ import type {
 import type { IProviderSetupInput } from '@robota-sdk/agent-framework';
 
 export type TProviderSetupType = string;
-export type TPromptInput = (label: string, masked?: boolean) => Promise<string>;
+export type TPromptInput = (
+  label: string,
+  masked?: boolean,
+  options?: { signal?: AbortSignal },
+) => Promise<string>;
 
 export interface IProviderSetupPromptStep extends IProviderSetupStepDefinition {
   key: TProviderSetupField;
@@ -28,6 +32,7 @@ export interface IProviderSetupFlowState {
 }
 
 export interface IProviderSetupFlowOptions {
+  includeEditOnlySteps?: boolean;
   existingProfileNames?: readonly string[];
   initialValues?: Partial<Record<TProviderSetupField, string>>;
   profileName?: string;
@@ -58,7 +63,9 @@ export function createProviderSetupFlow(
   return {
     type,
     steps: applyProviderSetupInitialValues(
-      getProviderSetupSteps(definition),
+      getProviderSetupSteps(definition).filter(
+        (step) => step.editOnly !== true || options.includeEditOnlySteps === true,
+      ),
       options.initialValues,
     ),
     setupHelpLinks: definition.setupHelpLinks ?? [],

package/src/provider/provider-startup.ts

@@ -9,6 +9,12 @@ import {
 } from '@robota-sdk/agent-framework';
 
 import { runOnboardingBranch } from './provider-onboarding.js';
+import { createProviderSetupFlow } from './provider-setup-flow.js';
+import {
+  hasProviderConnectionMethods,
+  runProviderConnectionSetup,
+} from './provider-connection-setup.js';
+import { createProviderPromptInteraction } from './provider-prompt-interaction.js';
 import {
   formatProviderSetupSelectionPrompt,
   resolveProviderSetupSelection,
@@ -16,12 +22,15 @@ import {
   type TPromptInput,
 } from './provider-setup-flow.js';
 
-import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type { IProviderDefinition, IUserInteraction } from '@robota-sdk/agent-core';
 import type { ITerminalOutput } from '@robota-sdk/agent-core';
 import type {
   ISettingsDocumentStore,
   TSettingsScope,
   TSettingsSource,
+  IProviderConnectionHost,
+  IOrgPolicy,
+  TProviderSettingsDocument,
 } from '@robota-sdk/agent-framework';
 
 export interface IProviderStartupContext {
@@ -31,6 +40,9 @@ export interface IProviderStartupContext {
   settingsStores: readonly ISettingsDocumentStore[];
   /** Selected host snapshot for configure-time credential reference checks. */
   env?: Record<string, string | undefined>;
+  connectionHost?: IProviderConnectionHost;
+  orgPolicy?: IOrgPolicy;
+  interaction?: IUserInteraction;
 }
 
 export interface IEnsureProviderConfigOptions {
@@ -47,7 +59,11 @@ export async function runProviderStartupSetup(
   terminal: ITerminalOutput,
   providerDefinitions: readonly IProviderDefinition[],
 ): Promise<void> {
-  const onboarding = await runOnboardingBranch(promptInput, terminal);
+  const onboarding = await runOnboardingBranch(
+    promptInput,
+    terminal,
+    providerDefinitions.some((definition) => definition.type === 'openrouter'),
+  );
   const access = resolveSettingsAccess(ctx);
   const existingProfileNames = Object.keys(
     readMergedProviderSettings(access.sources).providers ?? {},
@@ -64,10 +80,45 @@ export async function runProviderStartupSetup(
     type = resolveProviderSetupSelection(providerChoice, providerDefinitions);
   }
 
-  const input = await runProviderSetupPromptFlow(type, promptInput, providerDefinitions, {
-    existingProfileNames,
-  });
-  applyProviderConfiguration(settingsStore, input, { providerDefinitions, env: ctx.env });
+  const setupOptions = {
+    providerDefinitions,
+    env: ctx.env,
+    connectionHost: ctx.connectionHost,
+    orgPolicy: ctx.orgPolicy,
+    settings: {
+      readMergedSettings: () => readMergedProviderSettings(access.sources),
+      readTargetSettings: () => settingsStore.read() as TProviderSettingsDocument,
+      writeTargetSettings: (settings: TProviderSettingsDocument) => settingsStore.write(settings),
+    },
+  };
+  if (hasProviderConnectionMethods(type, setupOptions)) {
+    const definitions =
+      ctx.interaction === undefined
+        ? providerDefinitions.map((definition) => ({
+            ...definition,
+            connectionMethods: definition.connectionMethods?.filter(
+              (method) => method !== 'browser',
+            ),
+          }))
+        : providerDefinitions;
+    if (ctx.interaction === undefined)
+      terminal.writeLine(
+        'Browser connection is unavailable here. API key setup remains available.',
+      );
+    const result = await runProviderConnectionSetup(
+      ctx.interaction ?? createProviderPromptInteraction(promptInput),
+      createProviderSetupFlow(type, definitions, { existingProfileNames }),
+      { ...setupOptions, providerDefinitions: definitions },
+      false,
+    );
+    if (!result.success) throw new ProviderConfigError(result.message);
+    if (result.hostActions === undefined) return;
+  } else {
+    const input = await runProviderSetupPromptFlow(type, promptInput, providerDefinitions, {
+      existingProfileNames,
+    });
+    applyProviderConfiguration(settingsStore, input, { providerDefinitions, env: ctx.env });
+  }
   const language = await promptInput('  Response language (ko/en/ja/zh, default: en): ');
   if (language) {
     const settings = settingsStore.read();
@@ -89,7 +140,9 @@ export async function ensureProviderConfig(
   const merged = readMergedProviderSettings(access.sources);
   const selectedSettings =
     ctx.provider !== undefined ? { ...merged, currentProvider: ctx.provider } : merged;
-  if (checkSettingsDocument(selectedSettings, providerDefinitions, ctx.env ?? options.env) === 'valid') {
+  if (
+    checkSettingsDocument(selectedSettings, providerDefinitions, ctx.env ?? options.env) === 'valid'
+  ) {
     return;
   }
   // Zero-config startup: a recognized provider env key with complete definition defaults
@@ -114,7 +167,9 @@ export async function ensureProviderConfig(
   const updated = readMergedProviderSettings(access.sources);
   const updatedSettings =
     ctx.provider !== undefined ? { ...updated, currentProvider: ctx.provider } : updated;
-  if (checkSettingsDocument(updatedSettings, providerDefinitions, ctx.env ?? options.env) !== 'valid') {
+  if (
+    checkSettingsDocument(updatedSettings, providerDefinitions, ctx.env ?? options.env) !== 'valid'
+  ) {
     throw new ProviderConfigError(options.formatError(providerDefinitions));
   }
 }