Honor process provider selection without persisting credentials

Apply AUTOHAND_PROVIDER after global and workspace configuration. Preserve saved provider settings during incidental hook and permission saves. Validate JSON, YAML, TOML, feature gates, and real terminal inference.

Validation: CI=true bun run proof (8,940 unit tests and 111 Tuistory tests passed).

Co-authored-by: Autohand Evolve <code-noreply@autohand.ai>

Author: igorcosta

docs/config-reference.md

@@ -76,6 +76,7 @@ export AUTOHAND_HOME=/custom/path  # Changes ~/.autohand to /custom/path
 | -------------------------------------- | ------------------------------------------------ | -------------------------------- |
 | `AUTOHAND_HOME`                        | Base directory for all Autohand data             | `/custom/path`                   |
 | `AUTOHAND_CONFIG`                      | Custom config file path                          | `/path/to/config.toml`           |
+| `AUTOHAND_PROVIDER`                    | Select provider for this process, overriding global and workspace selection | `autohandai` |
 | `AUTOHAND_MODELS_CATALOG`              | Custom provider model catalog path               | `/path/to/models.json`           |
 | `AUTOHAND_API_URL`                     | API endpoint (overrides config)                  | `https://api.autohand.ai`        |
 | `AUTOHAND_AUTH_URL`                    | Sign-in and account-sync website origin (independent of `AUTOHAND_API_URL`) | `https://autohand.ai` |
@@ -95,6 +96,21 @@ export AUTOHAND_HOME=/custom/path  # Changes ~/.autohand to /custom/path
 | `AUTOHAND_CODE_SIMPLE`                 | Enable bare mode without passing `--bare`        | `1`                              |
 | `AUTOHAND_DISABLE_STATEFUL_READ`       | Emergency opt-out for all stateful-read experiments | `1`                           |
 
+### Process provider selection
+
+Set `AUTOHAND_PROVIDER=autohandai` to select Autohand AI for this process even
+when the global configuration or `.autohand/settings.local.json` selects another
+provider. Supply inference credentials through `AUTOHAND_AI_API_KEY`,
+`AUTOHAND_AI_BASE_URL`, and `AUTOHAND_AI_PLAN`; normal account authentication
+still applies. Existing feature gates remain in effect.
+
+The override accepts the normal built-in, `custom:<id>`, and `extension:<id>`
+provider names. An empty or unsupported explicit value fails startup. Omitting
+the variable preserves normal saved-provider selection. Incidental settings
+saves retain the saved provider selection and its configuration section,
+including credentials, instead of writing process-only values to disk. For
+custom or extension providers, their configuration map is retained from disk.
+
 ### Thinking Level
 
 The `AUTOHAND_THINKING_LEVEL` environment variable controls the depth of reasoning the model uses:

src/config.ts

@@ -641,6 +641,14 @@ function normalizeSavedApiBaseUrl(baseUrl: string | undefined): string | undefin
  * Env vars take precedence over config file values
  */
 function mergeEnvVariables(config: AutohandConfig): AutohandConfig {
+  if (process.env.AUTOHAND_PROVIDER !== undefined) {
+    const provider = normalizeProviderName(process.env.AUTOHAND_PROVIDER.trim());
+    if (!provider) {
+      throw new Error("AUTOHAND_PROVIDER must name a supported provider");
+    }
+    config = { ...config, provider };
+  }
+
   config = {
     ...config,
     api: {
@@ -1367,6 +1375,22 @@ export async function saveConfig(
   const { configPath, ...data } = config;
   delete (data as Partial<LoadedConfig>).isNewConfig;
 
+  const processProvider = normalizeProviderName(process.env.AUTOHAND_PROVIDER?.trim());
+  if (processProvider) {
+    // Hook and permission saves must not persist process-only provider credentials.
+    const persisted = await fs.pathExists(configPath) ? await parseConfigFile(configPath) : {};
+    const settingsKey = isCustomProviderName(processProvider) ? "customProviders"
+      : processProvider.startsWith("extension:") ? "extensionProviders"
+        : processProvider === "blueprint-local" ? "blueprintLocal" : processProvider;
+    for (const key of ["provider", settingsKey]) {
+      if (Object.hasOwn(persisted, key)) {
+        Object.assign(data, { [key]: Reflect.get(persisted, key) });
+      } else {
+        Reflect.deleteProperty(data, key);
+      }
+    }
+  }
+
   if (!options.writeAuth) {
     const persisted = await readPersistedAuth(configPath);
     if (persisted.present) {

tests/configProviderEnvironment.spec.ts

@@ -0,0 +1,129 @@
+import fs from 'fs-extra';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getProviderConfig, loadConfig, saveConfig } from '../src/config.js';
+
+describe('process provider selection', () => {
+  let directory: string;
+
+  beforeEach(async () => {
+    directory = await fs.mkdtemp(path.join(os.tmpdir(), 'autohand-provider-env-'));
+    vi.stubEnv('AUTOHAND_PROVIDER', undefined);
+    vi.stubEnv('AUTOHAND_AI_API_KEY', 'fixture-inference-key');
+    vi.stubEnv('AUTOHAND_AI_BASE_URL', 'http://127.0.0.1:12345/v1');
+    vi.stubEnv('AUTOHAND_AI_PLAN', 'cloud');
+  });
+
+  afterEach(async () => {
+    vi.unstubAllEnvs();
+    await fs.remove(directory);
+  });
+
+  const formats = [
+    ['json', '{"provider":"openrouter","auth":{"token":"fixture-account-token"}}'],
+    ['yaml', 'provider: openrouter\nauth:\n  token: fixture-account-token\n'],
+    ['toml', 'provider = "openrouter"\n[auth]\ntoken = "fixture-account-token"\n'],
+  ] as const;
+
+  it.each(formats)('selects Autohand AI over global and workspace %s settings without rewriting them', async (format, content) => {
+    const configPath = path.join(directory, `config.${format}`);
+    const workspace = path.join(directory, 'project');
+    const localPath = path.join(workspace, '.autohand', 'settings.local.json');
+    const localContent = '{"provider":"openai","permissions":{"mode":"restricted"}}';
+    await fs.writeFile(configPath, content);
+    await fs.outputFile(localPath, localContent);
+    vi.stubEnv('AUTOHAND_PROVIDER', 'autohandai');
+
+    const config = await loadConfig(configPath, workspace, { initializeTheme: false });
+
+    expect(config.provider).toBe('autohandai');
+    expect(config.auth?.token).toBe('fixture-account-token');
+    expect(config.permissions?.mode).toBe('restricted');
+    expect(getProviderConfig(config)).toMatchObject({
+      apiKey: 'fixture-inference-key', baseUrl: 'http://127.0.0.1:12345/v1', model: 'fantail',
+    });
+    expect(await fs.readFile(configPath, 'utf8')).toBe(content);
+    expect(await fs.readFile(localPath, 'utf8')).toBe(localContent);
+  });
+
+  it.each(['anthropic', 'custom:acme', 'extension:company-provider', 'vertex'])('accepts the existing provider contract for %s', async provider => {
+    const configPath = path.join(directory, 'config.json');
+    await fs.writeJson(configPath, { provider: 'openrouter' });
+    vi.stubEnv('AUTOHAND_PROVIDER', provider);
+
+    const config = await loadConfig(configPath, undefined, { initializeTheme: false });
+
+    expect(config.provider).toBe(provider === 'vertex' ? 'vertexai' : provider);
+  });
+
+  it.each(['', '   ', 'unknown-provider', 'extension:'])('rejects invalid explicit selection %j instead of silently using a saved provider', async provider => {
+    const configPath = path.join(directory, 'config.json');
+    await fs.writeJson(configPath, { provider: 'openrouter' });
+    vi.stubEnv('AUTOHAND_PROVIDER', provider);
+
+    await expect(loadConfig(configPath, undefined, { initializeTheme: false }))
+      .rejects.toThrow('AUTOHAND_PROVIDER');
+  });
+
+  it('keeps the saved provider when only inference credentials are supplied', async () => {
+    const configPath = path.join(directory, 'config.json');
+    await fs.writeJson(configPath, { provider: 'openrouter' });
+
+    const config = await loadConfig(configPath, undefined, { initializeTheme: false });
+
+    expect(config.provider).toBe('openrouter');
+  });
+
+  it('preserves an explicitly disabled inference feature', async () => {
+    const configPath = path.join(directory, 'config.json');
+    await fs.writeJson(configPath, { provider: 'openrouter', features: { autohand_inference: false } });
+    vi.stubEnv('AUTOHAND_PROVIDER', 'autohandai');
+
+    const config = await loadConfig(configPath, undefined, { initializeTheme: false });
+
+    expect(config.provider).toBe('autohandai');
+    expect(config.features?.autohand_inference).toBe(false);
+    expect(getProviderConfig(config)).toBeNull();
+  });
+
+  it.each(formats)('does not persist process provider settings during an unrelated %s save', async (format, content) => {
+    const configPath = path.join(directory, `config.${format}`);
+    await fs.writeFile(configPath, content);
+    vi.stubEnv('AUTOHAND_PROVIDER', 'autohandai');
+    const config = await loadConfig(configPath, undefined, { initializeTheme: false });
+    config.ui = { completionReportEnabled: false };
+
+    await saveConfig(config);
+    vi.stubEnv('AUTOHAND_PROVIDER', undefined);
+    vi.stubEnv('AUTOHAND_AI_API_KEY', undefined);
+    vi.stubEnv('AUTOHAND_AI_BASE_URL', undefined);
+    vi.stubEnv('AUTOHAND_AI_PLAN', undefined);
+    const saved = await loadConfig(configPath, undefined, { initializeTheme: false });
+
+    expect(saved.provider).toBe('openrouter');
+    expect(saved.autohandai).toBeUndefined();
+    expect(saved.ui?.completionReportEnabled).toBe(false);
+    expect(saved.auth?.token).toBe('fixture-account-token');
+  });
+
+  it('keeps the latest saved provider credentials when another process updates them', async () => {
+    const configPath = path.join(directory, 'config.json');
+    const original = {
+      provider: 'openrouter',
+      autohandai: { plan: 'cloud', authMode: 'api-key', apiKey: 'saved-key', model: 'moa' },
+    };
+    await fs.writeJson(configPath, original);
+    vi.stubEnv('AUTOHAND_PROVIDER', 'autohandai');
+    const config = await loadConfig(configPath, undefined, { initializeTheme: false });
+    const newer = { ...original, provider: 'ollama', autohandai: { ...original.autohandai, apiKey: 'newer-key' } };
+    await fs.writeJson(configPath, newer);
+
+    await saveConfig(config);
+
+    const saved = await fs.readJson(configPath);
+    expect(saved.provider).toBe('ollama');
+    expect(saved.autohandai).toEqual(newer.autohandai);
+    expect(config.autohandai?.apiKey).toBe('fixture-inference-key');
+  });
+});

tests/tuistory/provider-environment.tuistory.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'fs-extra';
+import path from 'node:path';
+import type { Session } from 'tuistory';
+import {
+  createMockAuthServer,
+  createMockAutohandAINativeSequenceServer,
+  createTempAutohandHome,
+  expectCleanExit,
+  exitInteractive,
+  launchBuiltAutohand,
+  waitForExit,
+} from './helpers/autohandTuistory.js';
+
+describe('provider environment startup', () => {
+  it('uses Autohand AI for an actual prompt while preserving saved provider selections', async () => {
+    const auth = await createMockAuthServer();
+    const provider = await createMockAutohandAINativeSequenceServer([
+      { content: 'PROCESS_PROVIDER_OVERRIDE_OK' },
+    ]);
+    const state = await createTempAutohandHome({ config: {
+      provider: 'openrouter',
+      openrouter: { baseUrl: auth.baseUrl },
+      features: { autohand_inference: true },
+      agent: { maxIterations: 2, sessionRetryLimit: 0, autoMemory: false },
+      network: { maxRetries: 0, retryDelay: 0 },
+    } });
+    const localPath = path.join(state.workspaceRoot, '.autohand', 'settings.local.json');
+    await fs.outputJson(localPath, { provider: 'openrouter' });
+    const originalConfig = await fs.readFile(state.configPath, 'utf8');
+    const originalLocal = await fs.readFile(localPath, 'utf8');
+    let session: Session | undefined;
+    try {
+      session = await launchBuiltAutohand([
+        '--path', state.workspaceRoot, '--config', state.configPath,
+        '--prompt', 'Reply with the provider fixture marker.', '--y',
+      ], {
+        autohandHome: state.autohandHome,
+        cwd: state.workspaceRoot,
+        env: {
+          AUTOHAND_PROVIDER: 'autohandai',
+          AUTOHAND_AI_API_KEY: 'fixture-inference-key',
+          AUTOHAND_AI_BASE_URL: provider.baseUrl,
+          AUTOHAND_AI_PLAN: 'cloud',
+          AUTOHAND_AUTH_API_URL: `${auth.baseUrl}/api/auth`,
+        },
+        waitForDataTimeout: 15_000,
+      });
+      await waitForExit(session, 30_000);
+      expect(session.readAll()).toContain('PROCESS_PROVIDER_OVERRIDE_OK');
+      expect(provider.requests).toHaveLength(1);
+      expectCleanExit(session);
+      const saved = await fs.readJson(state.configPath);
+      expect(saved.provider).toBe(JSON.parse(originalConfig).provider);
+      expect(saved.autohandai).toBeUndefined();
+      expect(await fs.readFile(localPath, 'utf8')).toBe(originalLocal);
+    } finally {
+      if (session && !session.exitInfo) await exitInteractive(session);
+      await Promise.all([provider.close(), auth.close(), state.cleanup()]);
+    }
+  }, 45_000);
+});