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

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

@@ -0,0 +1,287 @@
+import {
+  ENV_REFERENCE_PREFIX,
+  findProviderDefinition,
+  isEnvReference,
+  selectAction,
+  textAction,
+} from '@robota-sdk/agent-core';
+import {
+  buildProviderSetupPatch,
+  formatOrgPolicyViolationMessage,
+  mergeProviderPatch,
+  suggestProviderProfileName,
+} from '@robota-sdk/agent-framework';
+
+import { runProviderSetupAsk } from './provider-setup-ask.js';
+
+import type { ICredentialKey, IUserInteraction } from '@robota-sdk/agent-core';
+import type {
+  IProviderCommandModuleOptions,
+  IProviderSetupInput,
+  TProviderConnectionStage,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { IProviderSetupFlowState } from './provider-setup-flow.js';
+
+let nextAttempt = 0;
+const STAGE_LABELS: Record<TProviderConnectionStage, string> = {
+  'awaiting-approval': 'Waiting for browser approval',
+  exchanging: 'Completing browser authentication',
+  validating: 'Checking the connection',
+  saving: 'Finishing connection setup',
+};
+
+export function hasProviderConnectionMethods(
+  type: string,
+  options: IProviderCommandModuleOptions,
+): boolean {
+  return (
+    (findProviderDefinition(options.providerDefinitions, type)?.connectionMethods?.length ?? 0) > 0
+  );
+}
+
+/** Both frontends acquire new keys through the host; settings retain references to stored keys. */
+export async function runProviderConnectionSetup(
+  ui: IUserInteraction,
+  flow: IProviderSetupFlowState,
+  options: IProviderCommandModuleOptions,
+  isSetupRequired: boolean,
+  replace = false,
+): Promise<ICommandResult> {
+  const definition = findProviderDefinition(options.providerDefinitions, flow.type);
+  const profile =
+    flow.profileName ??
+    suggestProviderProfileName(
+      { type: flow.type },
+      { existingProfileNames: flow.existingProfileNames },
+    );
+  const initial = options.settings.readMergedSettings();
+  const previous = initial.providers?.[profile];
+  const previousSnapshot = JSON.stringify(previous);
+  if (
+    options.orgPolicy?.allowedProviders &&
+    !options.orgPolicy.allowedProviders.includes(profile)
+  ) {
+    return {
+      success: false,
+      message: formatOrgPolicyViolationMessage(
+        `Provider profile "${profile}" is not allowed by your organization policy.`,
+        options.orgPolicy.adminContact,
+      ),
+    };
+  }
+  const methods = (definition?.connectionMethods ?? []).filter(
+    (method) => options.orgPolicy?.requireApiKeyFromEnv !== true || method === 'api-key',
+  );
+  let description = options.orgPolicy?.requireApiKeyFromEnv
+    ? formatOrgPolicyViolationMessage(
+        'Your organization requires an environment reference such as $ENV:OPENROUTER_API_KEY.',
+        options.orgPolicy.adminContact,
+      )
+    : undefined;
+  for (;;) {
+    const methodAnswer = await ui.ask(
+      selectAction(
+        'provider-connection-method',
+        `Connect with ${definition?.displayName ?? flow.type}`,
+        methods.map((method) => ({
+          value: method,
+          label: method === 'api-key' ? 'API key' : 'Browser',
+        })),
+        { description },
+      ),
+    );
+    if (methodAnswer.type !== 'answer') return cancelled();
+    const method = methodAnswer.values[0];
+    if ((method !== 'api-key' && method !== 'browser') || !methods.includes(method))
+      return cancelled();
+    let apiKey: string | undefined;
+    if (method === 'api-key') {
+      const keyAnswer = await ui.ask(
+        textAction('provider-connection-key', 'API key or $ENV:VARIABLE_NAME', {
+          masked: true,
+          allowEmpty: false,
+        }),
+      );
+      if (keyAnswer.type !== 'answer') return cancelled();
+      apiKey = keyAnswer.text?.trim();
+      if (!apiKey || (options.orgPolicy?.requireApiKeyFromEnv && !isEnvReference(apiKey))) {
+        description = options.orgPolicy?.requireApiKeyFromEnv
+          ? formatOrgPolicyViolationMessage(
+              'Enter an environment reference such as $ENV:OPENROUTER_API_KEY.',
+              options.orgPolicy.adminContact,
+            )
+          : 'An API key is required.';
+        continue;
+      }
+      if (isEnvReference(apiKey)) {
+        const variable = apiKey.slice(ENV_REFERENCE_PREFIX.length).trim();
+        if (!variable || !(options.env ?? process.env)[variable]?.trim()) {
+          description =
+            'The environment reference is unset or invalid. Set its variable, then choose API key to try again.';
+          continue;
+        }
+      }
+    }
+    const controller = new AbortController();
+    let progress: AbortController | undefined;
+    let sequence = 0;
+    const attempt = ++nextAttempt;
+    const stopProgress = (): void => {
+      progress?.abort();
+      progress = undefined;
+    };
+    const onProgress = (stage: TProviderConnectionStage): void => {
+      stopProgress();
+      const prompt = new AbortController();
+      progress = prompt;
+      void ui
+        .ask(
+          selectAction(
+            `provider-connection-progress-${attempt}-${++sequence}`,
+            STAGE_LABELS[stage],
+            [{ value: 'cancel', label: 'Cancel connection' }],
+            { description: 'Keep this session open. You can cancel and choose API key setup.' },
+          ),
+          { signal: prompt.signal },
+        )
+        .then((response) => {
+          if (response.type === 'answer' || !prompt.signal.aborted) controller.abort();
+        })
+        .catch(() => {
+          if (!prompt.signal.aborted) controller.abort();
+        });
+    };
+    let result: ICommandResult | undefined;
+    const persist = async (reference?: ICredentialKey, hostSignal?: AbortSignal): Promise<void> => {
+      stopProgress();
+      const signal = hostSignal ?? controller.signal;
+      let input: IProviderSetupInput | undefined;
+      const modelFlow = {
+        ...flow,
+        profileName: profile,
+        steps: flow.steps.filter((step) => step.key !== 'apiKey' && step.key !== 'baseURL'),
+      };
+      if (modelFlow.steps.length === 0) {
+        input = {
+          profile,
+          type: flow.type,
+          model: definition?.defaults?.model,
+          setCurrent: flow.setCurrent ?? true,
+        };
+      } else {
+        await runProviderSetupAsk(
+          ui,
+          modelFlow,
+          (completed) => {
+            input = completed;
+            return { success: true, message: '' };
+          },
+          'Provider connection cancelled.',
+          signal,
+        );
+      }
+      if (!input || signal.aborted || controller.signal.aborted) {
+        controller.abort();
+        throw new Error('Provider connection cancelled.');
+      }
+      const current = options.settings.readMergedSettings();
+      if (
+        JSON.stringify(current.providers?.[profile]) !== previousSnapshot ||
+        current.currentProvider !== initial.currentProvider
+      ) {
+        throw new Error('Provider connection changed while setup was pending.');
+      }
+      const credential =
+        reference === undefined
+          ? { apiKeyEnv: apiKey?.slice(ENV_REFERENCE_PREFIX.length).trim() }
+          : { apiKeyRef: reference };
+      const patch = buildProviderSetupPatch(
+        { ...input, ...credential },
+        {
+          providerDefinitions: options.providerDefinitions,
+          env: options.env,
+        },
+      );
+      if (replace && previous !== undefined) {
+        const retained = { ...previous };
+        delete retained.apiKey;
+        delete retained.apiKeyRef;
+        patch.providers[profile] = { ...retained, ...patch.providers[profile] };
+      }
+      options.settings.writeTargetSettings(
+        mergeProviderPatch(options.settings.readTargetSettings(), patch),
+      );
+      const active = initial.currentProvider === profile;
+      result = {
+        success: true,
+        message: `Provider ${profile} connected.`,
+        ...(replace
+          ? active
+            ? {
+                hostActions: [
+                  {
+                    type: 'session-restart',
+                    reason: 'other',
+                    message: 'Provider connection restart',
+                  } as const,
+                ],
+              }
+            : {}
+          : {
+              hostActions: isSetupRequired
+                ? [{ type: 'provider-hot-swap', profileName: profile } as const]
+                : [
+                    {
+                      type: 'session-restart',
+                      reason: 'other',
+                      message: 'Provider setup restart',
+                    } as const,
+                  ],
+            }),
+      };
+    };
+    try {
+      if (apiKey !== undefined && isEnvReference(apiKey)) {
+        await persist();
+      } else if (options.connectionHost === undefined) {
+        description =
+          'Host connection support is unavailable. Choose API key and use an environment reference.';
+        continue;
+      } else {
+        await options.connectionHost.connect(
+          {
+            type: flow.type,
+            profile,
+            method,
+            ...(apiKey === undefined ? {} : { apiKey }),
+            signal: controller.signal,
+            ...(method === 'browser' ? { onProgress } : {}),
+          },
+          persist,
+        );
+      }
+      if (result === undefined) throw new Error('The host did not save a connection.');
+      return result;
+    } catch {
+      const recovery =
+        method === 'browser' && flow.type === 'openrouter'
+          ? ' If OpenRouter issued a key during this attempt, it may remain in your account. Review OpenRouter Keys at https://openrouter.ai/keys.'
+          : '';
+      if (controller.signal.aborted) {
+        description = `Connection cancelled. Choose a connection method to try again.${recovery}`;
+        continue;
+      }
+      return {
+        success: false,
+        message: `Connection failed. Retry with ${replace ? `/provider reconnect ${profile}` : `/provider add ${flow.type}`} and choose ${flow.type === 'openrouter' ? 'an ordinary OpenRouter API key or Browser' : 'API key or Browser'}.${recovery}`,
+      };
+    } finally {
+      stopProgress();
+    }
+  }
+}
+
+function cancelled(): ICommandResult {
+  return { success: true, message: 'Provider connection cancelled.' };
+}

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

@@ -0,0 +1,73 @@
+import type { TPromptInput } from './provider-setup-flow.js';
+import type { ITerminalOutput } from '@robota-sdk/agent-core';
+
+export type TOnboardingPath = 'has-key' | 'free-key' | 'local' | 'connect';
+
+export interface IOnboardingResult {
+  path: TOnboardingPath;
+  preselectedType?: string;
+}
+
+const ONBOARDING_PROMPT = `
+  Do you have an API key for an AI provider?
+
+    1. Yes, I have an API key
+    2. No — get a free key (Google Gemini, takes ~2 min)
+    3. No — use a local model (LM Studio, no API key needed)
+
+  Choose [1-3] (default: 1): `;
+
+const GEMINI_GUIDE = `
+  ── Get a free Gemini API key ────────────────────────────────────────────────
+
+  1. Open  https://aistudio.google.com/apikey  in your browser
+  2. Sign in with your Google account
+  3. Click "Create API key"  (takes ~30 seconds)
+  4. Copy the key starting with "AIza..."
+
+  ─────────────────────────────────────────────────────────────────────────────
+`;
+
+const LOCAL_MODEL_GUIDE = `
+  ── Set up a local model with LM Studio ──────────────────────────────────────
+
+  1. Download LM Studio from  https://lmstudio.ai
+  2. Open LM Studio → search for a model (e.g. "llama" or "phi") → Download
+  3. Go to  Developer  tab → click  Start Server
+     (default address: http://localhost:1234)
+
+  When the server is running, come back here and press Enter to continue.
+
+  ─────────────────────────────────────────────────────────────────────────────
+`;
+
+export async function runOnboardingBranch(
+  promptInput: TPromptInput,
+  terminal: ITerminalOutput,
+  offerOpenRouter = false,
+): Promise<IOnboardingResult> {
+  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: ');
+    return { path: 'free-key', preselectedType: 'gemini' };
+  }
+
+  if (choice === '3') {
+    terminal.writeLine(LOCAL_MODEL_GUIDE);
+    await promptInput('  Press Enter when LM Studio server is running: ');
+    return { path: 'local', preselectedType: 'gemma' };
+  }
+
+  return { path: 'has-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;
+  }
+}