@robota-sdk/agent-command 3.0.0-beta.88 → 3.0.0-beta.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-command",
-  "version": "3.0.0-beta.88",
+  "version": "3.0.0-beta.92",
   "description": "Slash-command modules for Robota SDK sessions (/help, /permissions, /mcp, /rewind, …)",
   "type": "module",
   "main": "dist/node/index.js",
@@ -40,12 +40,12 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@robota-sdk/agent-core": "3.0.0-beta.88",
-    "@robota-sdk/agent-framework": "3.0.0-beta.88",
-    "@robota-sdk/agent-interface-command": "3.0.0-beta.88",
-    "@robota-sdk/agent-interface-execution": "3.0.0-beta.88",
-    "@robota-sdk/agent-interface-session": "3.0.0-beta.88",
-    "@robota-sdk/agent-preset": "3.0.0-beta.88"
+    "@robota-sdk/agent-core": "3.0.0-beta.92",
+    "@robota-sdk/agent-framework": "3.0.0-beta.92",
+    "@robota-sdk/agent-interface-command": "3.0.0-beta.92",
+    "@robota-sdk/agent-interface-execution": "3.0.0-beta.92",
+    "@robota-sdk/agent-interface-session": "3.0.0-beta.92",
+    "@robota-sdk/agent-preset": "3.0.0-beta.92"
   },
   "devDependencies": {
     "@types/node": "^22.19.21",

package/src/default/__tests__/provider-environment-forwarding.test.ts

@@ -0,0 +1,98 @@
+/**
+ * #3459 — the default command modules hand `/provider` and `/model` the host's environment snapshot.
+ *
+ * A host that withholds its own credentials from `process.env` passes the snapshot it took first as
+ * `providerEnvironment`. This drives both commands through the factory, with the key gone from the
+ * live env, so it fails exactly when the factory stops forwarding the snapshot.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, describe, expect, it } from 'vitest';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import { createDefaultCommandModules } from '../default-command-modules.js';
+
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type { IProviderCommandSettingsAdapter, TProviderSettingsDocument } from '@robota-sdk/agent-framework';
+
+const KEY = 'OPENAI_API_KEY';
+const providerDefinitions: readonly IProviderDefinition[] = [
+  {
+    type: 'anthropic',
+    displayName: 'anthropic',
+    defaults: { model: 'm' },
+    modelCatalog: { status: 'live', entries: [{ id: 'm', displayName: 'm' }] },
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+  {
+    type: 'openai',
+    displayName: 'openai',
+    defaults: { apiKey: `$ENV:${KEY}` },
+    modelCatalog: { status: 'unavailable' },
+    requiresApiKey: true,
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+];
+
+const SETTINGS: TProviderSettingsDocument = {
+  currentProvider: 'anthropic',
+  providers: { anthropic: { type: 'anthropic', model: 'm' }, openai: { type: 'openai', model: 'gpt-x' } },
+};
+const adapter: IProviderCommandSettingsAdapter = {
+  readMergedSettings: () => SETTINGS,
+  readTargetSettings: () => ({}),
+  writeTargetSettings: () => undefined,
+};
+
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'agent-test-provider-env-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
+function executorThroughFactory(moduleName: string): SystemCommandExecutor {
+  const { modules } = createDefaultCommandModules({
+    cwd: '/work',
+    userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT,
+    providerDefinitions,
+    providerSettingsAdapter: adapter,
+    providerEnvironment: { [KEY]: 'snapshot-key' },
+  });
+  const found = modules.find((module) => module.name === moduleName);
+  if (found === undefined) throw new Error(`${moduleName} was not built`);
+  return new SystemCommandExecutor([...(found.systemCommands ?? [])]);
+}
+
+async function withoutLiveKey<T>(run: () => Promise<T>): Promise<T> {
+  const live = process.env[KEY];
+  delete process.env[KEY];
+  try {
+    return await run();
+  } finally {
+    if (live !== undefined) process.env[KEY] = live;
+  }
+}
+
+describe('#3459: the default command modules forward the provider environment', () => {
+  it('/provider switch checks the key against the snapshot', async () => {
+    const result = await withoutLiveKey(() =>
+      executorThroughFactory('agent-command-provider').execute('provider', createTestCommandHost(), 'switch openai'),
+    );
+
+    expect(result?.success).toBe(true);
+  });
+
+  it('a cross-profile /model checks the key against the snapshot', async () => {
+    const host = createTestCommandHost({ session: { getModelId: () => 'm' } });
+    const result = await withoutLiveKey(() =>
+      executorThroughFactory('agent-command-model').execute('model', host, 'gpt-x'),
+    );
+
+    expect(result?.success).toBe(true);
+  });
+});

package/src/default/default-command-modules.ts

@@ -74,6 +74,11 @@ export interface IDefaultCommandModulesOptions {
    * red when the producer dropped it.
    */
   orgPolicy?: IOrgPolicy;
+  /**
+   * Where `/provider` and `/model` check a `$ENV:` or default credential variable: the host's startup
+   * snapshot when it withholds its own credentials from `process.env`. Absent, `process.env` is read.
+   */
+  providerEnvironment?: Readonly<Record<string, string | undefined>>;
   /** Optional TUI-owned file capability; absent, `/keybindings` says it belongs to an interactive terminal. */
   keybindingsFilePort?: IKeybindingsFilePort;
   /**
@@ -152,6 +157,7 @@ export function createDefaultCommandModules({
   loopOptions,
   enabledCommandModules,
   disabledCommandModules,
+  providerEnvironment,
 }: IDefaultCommandModulesOptions): IDefaultCommandModulesResult {
   const modules: readonly ICommandModule[] = [
     createSkillsCommandModule({ contributionSources: contributionSources ?? [], skillRoots }),
@@ -204,6 +210,7 @@ export function createDefaultCommandModules({
       providerDefinitions,
       settings: providerSettingsAdapter,
       ...(orgPolicy === undefined ? {} : { orgPolicy }),
+      ...(providerEnvironment === undefined ? {} : { env: providerEnvironment }),
     }),
     // #3282 §2: shares the provider command's settings adapter and definitions — one settings write
     // owner, never a second copy that could drift from what `/provider switch` reads and writes.
@@ -211,6 +218,7 @@ export function createDefaultCommandModules({
       providerDefinitions,
       settings: providerSettingsAdapter,
       ...(orgPolicy === undefined ? {} : { orgPolicy }),
+      ...(providerEnvironment === undefined ? {} : { env: providerEnvironment }),
     }),
   ];
   const builtModuleNames = modules.map((module) => module.name);

package/src/model/__tests__/model-command.test.ts

@@ -237,4 +237,29 @@ describe('/model', () => {
     expect(result).toEqual({ message: 'Model selection cancelled.', success: true });
     expect(writeTargetSettings).not.toHaveBeenCalled();
   });
+
+  // #3459: the host withholds its own credentials from `process.env`; the profile's `$ENV:` key is
+  // checked against the snapshot it hands the command instead.
+  it('switches to a profile whose key is only in the host snapshot', async () => {
+    const writeTargetSettings = vi.fn();
+    const host = createTestCommandHost({ session: { getModelId: () => 'claude-sonnet-4-6' } });
+    const keyed = DEFINITIONS.map((definition) =>
+      definition.type === 'openai' ? { ...definition, requiresApiKey: true } : definition,
+    );
+    const options = {
+      ...buildOptions({ writeTargetSettings }),
+      providerDefinitions: keyed,
+      env: { OPENAI_API_KEY: 'snapshot-key' },
+    };
+    const live = process.env['OPENAI_API_KEY'];
+    delete process.env['OPENAI_API_KEY'];
+    try {
+      const result = await executeModelCommand(host, 'gpt-5.1', options);
+
+      expect(result.success).toBe(true);
+      expect(result.hostActions).toEqual([{ type: 'provider-hot-swap', profileName: 'my-openai' }]);
+    } finally {
+      if (live !== undefined) process.env['OPENAI_API_KEY'] = live;
+    }
+  });
 });

package/src/model/model-command.ts

@@ -199,6 +199,7 @@ function switchModelAcrossProfiles(
   try {
     validateProviderProfile(selection.profileName, updatedProfile, {
       providerDefinitions: options.providerDefinitions,
+      ...(options.env === undefined ? {} : { env: options.env }),
     });
   } catch (error) {
     return {

package/src/provider/__tests__/optional-provider-credentials.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest';
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import type { TProviderSettingsDocument } from '@robota-sdk/agent-framework';
+import { createProviderCommandModule } from '../provider-command-module.js';
+import { scriptedContext } from './scripted-interaction.js';
+
+const localDefinition: IProviderDefinition = {
+  type: 'local',
+  defaults: { model: 'installed-model', baseURL: 'http://localhost:1234/v1' },
+  setupSteps: [
+    { key: 'baseURL', title: 'Server URL', defaultValue: 'http://localhost:1234/v1' },
+    { key: 'model', title: 'Installed model', defaultValue: 'installed-model' },
+    { key: 'apiKey', title: 'Server API key (optional)', masked: true, editOnly: true },
+  ],
+  requiresApiKey: false,
+  createProvider: () => {
+    throw new Error('not used');
+  },
+};
+
+function commands(initial: TProviderSettingsDocument = {}) {
+  let settings = initial;
+  const module = createProviderCommandModule({
+    providerDefinitions: [localDefinition],
+    env: { LOCAL_TOKEN: 'synthetic-selected-token' },
+    settings: {
+      readMergedSettings: () => settings,
+      readTargetSettings: () => settings,
+      writeTargetSettings: (next) => {
+        settings = next;
+      },
+    },
+  });
+  return {
+    executor: new SystemCommandExecutor([...(module.systemCommands ?? [])]),
+    read: () => settings,
+    module,
+  };
+}
+
+describe('optional provider credentials', () => {
+  it('adds a keyless profile after only endpoint and model answers', async () => {
+    const { executor, read } = commands();
+    const { context, requests } = scriptedContext([
+      { type: 'answer', values: [], text: '' },
+      { type: 'answer', values: [], text: '' },
+    ]);
+
+    const result = await executor.execute('provider', context, 'add local');
+
+    expect(result?.success).toBe(true);
+    expect(requests.map((request) => request.id)).toEqual([
+      'provider-setup-baseURL',
+      'provider-setup-model',
+    ]);
+    expect(read().providers?.local).toEqual({
+      type: 'local',
+      model: 'installed-model',
+      baseURL: 'http://localhost:1234/v1',
+    });
+  });
+
+  it.each([undefined, '$ENV:LOCAL_TOKEN', 'synthetic-existing-token'])(
+    'allows blank optional key editing and preserves the previous credential %s',
+    async (apiKey) => {
+      const profile = {
+        type: 'local',
+        model: 'installed-model',
+        baseURL: 'http://localhost:1234/v1',
+        ...(apiKey === undefined ? {} : { apiKey }),
+      };
+      const { executor, read } = commands({ providers: { local: profile } });
+      const { context, requests } = scriptedContext([
+        { type: 'answer', values: [], text: '' },
+        { type: 'answer', values: [], text: 'another-installed-model' },
+        { type: 'answer', values: [], text: '' },
+      ]);
+
+      const result = await executor.execute('provider', context, 'edit local');
+
+      expect(result?.success).toBe(true);
+      expect(requests[2]).toMatchObject({
+        id: 'provider-setup-apiKey',
+        masked: true,
+        allowEmpty: true,
+      });
+      expect(JSON.stringify(requests)).not.toContain('synthetic-existing-token');
+      expect(read().providers?.local).toEqual({ ...profile, model: 'another-installed-model' });
+    },
+  );
+
+  it('keeps credential management user-only and advertises the edit recovery action', () => {
+    const { module } = commands();
+    const entry = module.commandSources?.[0]?.getCommands()[0];
+    expect(entry).toMatchObject({ modelInvocable: false });
+    expect(module.systemCommands?.[0]).toMatchObject({
+      modelInvocable: false,
+      userInvocable: true,
+    });
+    expect(entry?.argumentHint).toContain('edit <profile>');
+    expect(entry?.description).toContain('credentials');
+  });
+
+  it.each(['$ENV:MISSING_SERVER_TOKEN', '$ENV:'])(
+    'leaves the working profile untouched when an edit supplies %s',
+    async (apiKey) => {
+      const initial = {
+        providers: {
+          local: {
+            type: 'local',
+            model: 'installed-model',
+            baseURL: 'http://localhost:1234/v1',
+            apiKey: 'synthetic-working-token',
+          },
+        },
+      };
+      const { executor, read } = commands(initial);
+      const { context } = scriptedContext([
+        { type: 'answer', values: [], text: '' },
+        { type: 'answer', values: [], text: '' },
+        { type: 'answer', values: [], text: apiKey },
+      ]);
+      await expect(executor.execute('provider', context, 'edit local')).rejects.toThrow(
+        'missing apiKey',
+      );
+      expect(read()).toEqual(initial);
+    },
+  );
+});

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

@@ -804,4 +804,81 @@ describe('createProviderCommandModule', () => {
       expect(result?.message).toBe('Provider profile "ghost" was not found.');
     });
   });
+
+  // #3459: a host that withholds its own credentials from `process.env` checks `$ENV:` credentials
+  // against the snapshot it took first, which it hands the command as `env`.
+  describe('credentials the host withheld from process.env', () => {
+    const settings: TProviderSettingsDocument = {
+      currentProvider: 'openai',
+      providers: {
+        openai: { type: 'openai', model: 'supergemma4-26b-uncensored-v2' },
+        anthropic: { type: 'anthropic', model: 'claude-sonnet-4-6' },
+      },
+    };
+    const snapshot = { ANTHROPIC_API_KEY: 'snapshot-key' };
+
+    function withoutLiveKey<T>(run: () => Promise<T>): Promise<T> {
+      const live = process.env['ANTHROPIC_API_KEY'];
+      delete process.env['ANTHROPIC_API_KEY'];
+      return run().finally(() => {
+        if (live !== undefined) process.env['ANTHROPIC_API_KEY'] = live;
+      });
+    }
+
+    function executorWithSnapshot(adapter: IProviderCommandSettingsAdapter): SystemCommandExecutor {
+      const module = createProviderCommandModule({ providerDefinitions, settings: adapter, env: snapshot });
+      return new SystemCommandExecutor([...(module.systemCommands ?? [])]);
+    }
+
+    it('switches to a profile whose key is only in the snapshot', async () => {
+      const { adapter, readTarget } = createSettingsAdapter(settings);
+      const result = await withoutLiveKey(() =>
+        executorWithSnapshot(adapter).execute('provider', headlessContext, 'switch anthropic'),
+      );
+
+      expect(result?.success).toBe(true);
+      expect(readTarget().currentProvider).toBe('anthropic');
+    });
+
+    it('adds a profile whose default key is only in the snapshot', async () => {
+      const { adapter, readTarget } = createSettingsAdapter(settings);
+      const { context } = scriptedContext([
+        { type: 'answer', values: [], text: '' },
+        { type: 'answer', values: [], text: '' },
+      ]);
+      const module = createProviderCommandModule({ providerDefinitions, settings: adapter, env: snapshot });
+      const result = await withoutLiveKey(() =>
+        new SystemCommandExecutor([...(module.systemCommands ?? [])]).execute('provider', context, 'add anthropic'),
+      );
+
+      expect(result?.success).not.toBe(false);
+      expect(readTarget().providers?.['anthropic-2']).toMatchObject({ type: 'anthropic' });
+    });
+
+    it('edits a profile whose default key is only in the snapshot', async () => {
+      const { adapter, readTarget } = createSettingsAdapter(settings);
+      const { context } = scriptedContext([
+        { type: 'answer', values: [], text: '' },
+        { type: 'answer', values: [], text: 'claude-opus-4-5' },
+      ]);
+      const module = createProviderCommandModule({ providerDefinitions, settings: adapter, env: snapshot });
+      const result = await withoutLiveKey(() =>
+        new SystemCommandExecutor([...(module.systemCommands ?? [])]).execute('provider', context, 'edit anthropic'),
+      );
+
+      expect(result?.message).toBe('Provider anthropic updated.');
+      expect(readTarget().providers?.['anthropic']).toMatchObject({ model: 'claude-opus-4-5' });
+    });
+
+    it('tests a profile whose key is only in the snapshot', async () => {
+      const { adapter } = createSettingsAdapter(settings);
+      const result = await withoutLiveKey(() =>
+        executorWithSnapshot(adapter).execute('provider', headlessContext, 'test anthropic'),
+      );
+
+      expect(result?.message).toBe(
+        'Provider "anthropic" test passed: Profile fields are valid; no endpoint probe configured.',
+      );
+    });
+  });
 });

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

@@ -15,6 +15,11 @@ function buildProviderSubcommands(): ICommand[] {
     { name: 'list', description: 'List provider profiles', source: 'provider' },
     { name: 'switch', description: 'Hot-swap to another provider profile', source: 'provider' },
     { name: 'add', description: 'Configure a provider profile', source: 'provider' },
+    {
+      name: 'edit',
+      description: 'Edit a profile, including optional server credentials',
+      source: 'provider',
+    },
     { name: 'test', description: 'Test provider profile', source: 'provider' },
   ];
 }
@@ -23,11 +28,13 @@ export function createProviderCommandEntry(): ICommand {
   return {
     name: 'provider',
     displayName: 'Provider Setup',
-    description: 'Manage provider profiles',
+    description:
+      'Show, configure or switch provider profiles. Suggest editing a profile when its URL, model or credentials need correction; returns profile details or the result of the change.',
     source: 'provider',
     // User-only: provider profiles hold account credentials; a credential action.
     modelInvocable: false,
-    argumentHint: 'current | list | switch <profile> | add [type] | test [profile]',
+    argumentHint:
+      'current | list | switch <profile> | add [type] | edit <profile> | test [profile]',
     subcommands: buildProviderSubcommands(),
     example: '/provider switch production',
   };

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

@@ -58,7 +58,10 @@ export function buildProviderSwitch(
   // previous behavior wrote `currentProvider` unconditionally and let a downstream hot-swap failure
   // (e.g. "Unknown provider: anthropic. Currently supported: ", an empty list) stand uncorrected.
   try {
-    validateProviderProfile(profileName, profile, { providerDefinitions: options.providerDefinitions });
+    validateProviderProfile(profileName, profile, {
+      providerDefinitions: options.providerDefinitions,
+      ...(options.env === undefined ? {} : { env: options.env }),
+    });
   } catch (error) {
     return {
       message: `Failed to switch to "${profileName}": ${error instanceof Error ? error.message : String(error)}`,
@@ -96,6 +99,7 @@ export async function buildProviderEdit(
   let flow;
   try {
     flow = createProviderSetupFlow(profile.type, options.providerDefinitions, {
+      includeEditOnlySteps: true,
       profileName,
       setCurrent: false,
       initialValues: getProviderProfileSetupValues(profile),
@@ -146,6 +150,7 @@ function completeProviderEdit(
   const target = options.settings.readTargetSettings();
   const patch = buildProviderSetupPatch(input, {
     providerDefinitions: options.providerDefinitions,
+    ...(options.env === undefined ? {} : { env: options.env }),
   });
   const updatedProfile = patch.providers[profileName];
   if (!updatedProfile) {

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

@@ -46,7 +46,8 @@ function toProviderSetupStepRequest(
   return textAction(`provider-setup-${step.key}`, step.title, {
     description,
     placeholder,
-    allowEmpty: step.defaultValue !== undefined,
+    allowEmpty:
+      step.defaultValue !== undefined || (step.editOnly === true && step.required !== true),
     masked: step.masked,
   });
 }
@@ -105,6 +106,7 @@ function completeProviderSetup(
   const target = options.settings.readTargetSettings();
   const patch = buildProviderSetupPatch(input, {
     providerDefinitions: options.providerDefinitions,
+    ...(options.env === undefined ? {} : { env: options.env }),
   });
   options.settings.writeTargetSettings(mergeProviderPatch(target, patch));
   // #3282 §3: the session's own live setup-mode state (never settings — an ordinary env-default

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

@@ -28,6 +28,7 @@ export interface IProviderSetupFlowState {
 }
 
 export interface IProviderSetupFlowOptions {
+  includeEditOnlySteps?: boolean;
   existingProfileNames?: readonly string[];
   initialValues?: Partial<Record<TProviderSetupField, string>>;
   profileName?: string;
@@ -58,7 +59,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

@@ -89,7 +89,7 @@ export async function ensureProviderConfig(
   const merged = readMergedProviderSettings(access.sources);
   const selectedSettings =
     ctx.provider !== undefined ? { ...merged, currentProvider: ctx.provider } : merged;
-  if (checkSettingsDocument(selectedSettings, providerDefinitions) === '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 +114,7 @@ export async function ensureProviderConfig(
   const updated = readMergedProviderSettings(access.sources);
   const updatedSettings =
     ctx.provider !== undefined ? { ...updated, currentProvider: ctx.provider } : updated;
-  if (checkSettingsDocument(updatedSettings, providerDefinitions) !== 'valid') {
+  if (checkSettingsDocument(updatedSettings, providerDefinitions, ctx.env ?? options.env) !== 'valid') {
     throw new ProviderConfigError(options.formatError(providerDefinitions));
   }
 }