aws-cli-agent 0.4.0 → 0.6.0

package/dist/config.js

@@ -2,8 +2,8 @@ import fs from 'node:fs';
 import { z } from 'zod';
 import { FILES, PATHS } from './paths.js';
 /**
- * Logging configuration. All three keys are optional in the file; defaults
- * tilt toward "quiet but auditable" — a tool that writes to your AWS account
+ * Logging configuration. All keys are optional in the file; defaults tilt
+ * toward "quiet but auditable" — a tool that writes to your AWS account
  * should leave a paper trail by default, but shouldn't be noisy on the
  * console unless you ask.
  */
@@ -16,9 +16,6 @@ const LoggingSchema = z
     reasoningLog: z.boolean().default(false),
     usageLog: z.boolean().default(true),
 })
-    // zod v4 requires .default() to receive a fully-typed value, not `{}`.
-    // We list every field explicitly here; values must match the inner
-    // .default()s above to avoid silently changing defaults.
     .default({
     level: 'error',
     auditLog: true,
@@ -26,58 +23,72 @@ const LoggingSchema = z
     usageLog: true,
 });
 /**
- * Bedrock-specific configuration. Only meaningful when `provider = bedrock`;
- * both keys are optional within that.
+ * Per-provider configuration for the three keyed providers (Anthropic,
+ * OpenAI, Google). Each block is optional in the file — but when the
+ * top-level `provider` is set to one of these, the matching block must
+ * exist AND contain a `model`. That validation runs in the post-parse
+ * step (see `validateActiveProvider`).
+ *
+ * `apiKey` SECURITY NOTE: Putting the key here means it persists to disk.
+ * Prefer the environment variable (default name, or override via
+ * `apiKeyEnv`). The env var always wins if both are set.
+ */
+const KeyedProviderSchema = z
+    .object({
+    model: z.string().optional(),
+    apiKey: z.string().optional(),
+    apiKeyEnv: z.string().optional(),
+})
+    .optional();
+/**
+ * Bedrock has a different shape: no apiKey (uses the AWS credential chain),
+ * but adds region and profile. Like the keyed providers, this block is
+ * optional in the file but required when `provider = "bedrock"`.
  */
 const BedrockSchema = z
     .object({
+    model: z.string().optional(),
     region: z.string().optional(),
     profile: z.string().optional(),
 })
     .optional();
 export const ConfigSchema = z.object({
-    /** Which remote AI provider to call. */
+    /**
+     * Which provider is active. The matching top-level block (anthropic /
+     * openai / google / bedrock) must exist and contain a `model`. Use
+     * `aca config` to see a working default scaffold.
+     */
     provider: z
         .enum(['anthropic', 'openai', 'google', 'bedrock'])
         .default('anthropic'),
-    /** Model identifier passed to the provider. */
-    model: z.string().default('claude-sonnet-4-5-20250929'),
-    /**
-     * Optional override for the env var name that holds the API key.
-     * Ignored when provider = "bedrock" (Bedrock uses the AWS credential chain).
-     */
-    apiKeyEnv: z.string().optional(),
-    /**
-     * Bedrock provider settings (region + profile). Only used when
-     * provider = "bedrock". See providers.ts for fallback chain.
-     */
+    // Per-provider blocks. Each is independently optional; the active
+    // provider's block is validated separately for completeness.
+    anthropic: KeyedProviderSchema,
+    openai: KeyedProviderSchema,
+    google: KeyedProviderSchema,
     bedrock: BedrockSchema,
     /**
-     * Default AWS region for AWS CLI commands the agent executes. Used when the
-     * user didn't mention a region in the request and history didn't supply one.
-     * Overridable per-run with --region. Independent of `bedrock.region`.
+     * Default AWS region for AWS CLI commands the agent executes. Used when
+     * the user didn't mention a region in the request and history didn't
+     * supply one. Overridable per-run with --region. Independent of
+     * `bedrock.region` (which is for Bedrock API calls, not AWS CLI calls).
      */
     defaultRegion: z.string().optional(),
     /** Max reasoning/tool-use steps before the agent must conclude. */
     maxSteps: z.number().int().min(1).max(50).default(15),
-    /** All logging knobs live here — see LoggingSchema for details. */
+    /** All logging knobs. */
     logging: LoggingSchema,
     /**
-     * Prompt caching. When true, the system prompt + tool definitions (the
-     * long-lived prefix sent on every step) are marked cacheable for providers
-     * that support it. Cache hits cost ~10% of normal input tokens (Anthropic
-     * direct and Bedrock-via-Anthropic). OpenAI auto-caches large prompts and
-     * ignores this flag. Google Gemini's caching API isn't supported yet —
-     * this flag is silently ignored for that provider. Default true: most
-     * users invoke `aca` more than once every 5 minutes, so the cache pays
-     * for itself quickly; users running it rarely can disable it to avoid
-     * the small cache-write premium on each first call.
+     * Prompt caching. When true, the cacheable prefix is marked so providers
+     * that support it can cache hits cheaply (~10% of normal input tokens
+     * on Anthropic and Bedrock-via-Anthropic). OpenAI auto-caches large
+     * prompts and ignores this flag. Google Gemini's caching API isn't
+     * wired up yet; this flag is silently ignored for that provider.
      */
     caching: z.boolean().default(true),
     /**
-     * When true, reasoning steps are echoed to stderr in real time. Independent
-     * of `logging.reasoningLog`: you can have file logging on and console echo
-     * off, or vice versa. Overridable per-run with --verbose.
+     * Echo reasoning to stderr in real time. Independent of
+     * `logging.reasoningLog`. Override per-run with --verbose.
      */
     verbose: z.boolean().default(false),
     /** Auto-approval policy for command/script execution. */
@@ -90,25 +101,97 @@ export const ConfigSchema = z.object({
     })
         .default({ readOnly: true, all: false }),
     /**
-     * When true, every AWS CLI command runs in interactive mode (stdio inherited
-     * from the parent terminal). This is the persistent equivalent of the
-     * `--interactive` / `-i` CLI flag — useful in rare edge cases where the
-     * pattern-based auto-detection misses a command that needs a TTY. Almost
-     * always you want to leave this unset and rely on either the CLI flag for
-     * one-off invocations or the per-tool-call override the agent can set.
+     * Force every AWS CLI command into interactive (TTY) mode. Almost always
+     * leave this unset and use the --interactive / -i CLI flag instead.
      */
     forceInteractive: z.boolean().default(false),
-    /** Maximum number of history entries kept in memory. */
+    /** Max history entries kept in memory. */
     historyLimit: z.number().int().min(0).default(200),
     /**
-     * Directory where the user may save generated bash scripts (offered as an
-     * alternative to executing them inline). Defaults to
+     * Directory where generated bash scripts are saved when the user picks
+     * "Save to disk" at the prompt. Defaults to
      * $XDG_DATA_HOME/aws-cli-agent/scripts.
      */
     scriptFolder: z.string().optional(),
 });
+/**
+ * Map of provider → label used in error messages and the migration hint.
+ * Kept here (not in providers.ts) so config-load errors don't depend on
+ * the provider module.
+ */
+const PROVIDER_LABELS = {
+    anthropic: 'anthropic',
+    openai: 'openai',
+    google: 'google',
+    bedrock: 'bedrock',
+};
+/**
+ * Resolve the active provider's model. The schema marks `model` optional
+ * per-block so that we can produce a single coherent error message in
+ * `validateActiveProvider` rather than zod's multi-issue tree. Call this
+ * only after validateActiveProvider has passed.
+ */
+export function getActiveModel(config) {
+    const block = config[config.provider];
+    // model is guaranteed by validateActiveProvider.
+    return block.model;
+}
+/**
+ * Strict post-parse validation for the active provider's block. The active
+ * provider's block must exist and must contain a `model`. Pre-1.0 we treat
+ * this as a hard error rather than scaffolding defaults, so the user always
+ * knows exactly what's being called and at what cost.
+ *
+ * Call this from code paths that actually run the agent — the `run` command.
+ * Subcommands that don't need a provider (`paths`, `config`, `history`)
+ * skip this check, so a user with no config file can still use them.
+ */
+export function validateActiveProvider(config) {
+    const active = config.provider;
+    const block = config[active];
+    if (!block) {
+        throw new Error(`config.provider is "${active}" but no top-level "${PROVIDER_LABELS[active]}" ` +
+            `block was found. At minimum add: ` +
+            `{ "${active}": { "model": "<model-id>" } }. Run \`aca config\` to see a ` +
+            `working default scaffold.`);
+    }
+    if (!block.model) {
+        throw new Error(`config.${active}.model is required. Set it to the model identifier you ` +
+            `want to use (e.g. "claude-sonnet-4-6" for anthropic).`);
+    }
+}
+/**
+ * Detect the pre-0.6 config shape and produce a helpful migration error
+ * rather than the cryptic "Required" zod failures the user would otherwise
+ * get. Heuristic: a top-level `model` or top-level `apiKeyEnv` is a strong
+ * signal of an old config, since neither key exists in the new schema.
+ */
+function detectLegacyShape(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return;
+    const obj = raw;
+    if ('model' in obj || 'apiKeyEnv' in obj) {
+        throw new Error(`Config file uses the pre-0.6.0 shape (top-level "model" / "apiKeyEnv" / ` +
+            `flat "bedrock" block). The new shape moves these into per-provider blocks:\n` +
+            `\n` +
+            `  Old:                              New:\n` +
+            `    "provider": "anthropic",          "provider": "anthropic",\n` +
+            `    "model": "claude-...",            "anthropic": {\n` +
+            `    "apiKeyEnv": "MY_KEY"               "model": "claude-...",\n` +
+            `                                        "apiKeyEnv": "MY_KEY"\n` +
+            `                                      }\n` +
+            `\n` +
+            `For bedrock, move the existing "region"/"profile" alongside a new\n` +
+            `"model" field, all under the "bedrock" block.\n` +
+            `\n` +
+            `To start fresh: rename your old config, run \`aca config\`, then copy values across.`);
+    }
+}
 export function loadConfig() {
     if (!fs.existsSync(FILES.config)) {
+        // No file = pure defaults. Strict validation is deferred to callers
+        // who actually need the provider (the `run` command), so subcommands
+        // like `paths`, `config`, `history` work without a config file.
         return ConfigSchema.parse({});
     }
     let raw;
@@ -118,14 +201,41 @@ export function loadConfig() {
     catch (err) {
         throw new Error(`Config file at ${FILES.config} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
     }
+    detectLegacyShape(raw);
     return ConfigSchema.parse(raw);
 }
-/** Write a default config file if none exists. Returns the path either way. */
+/**
+ * Write a default config file if none exists. Scaffolds only the active
+ * provider's block (just `model`), deliberately not creating slots for
+ * other providers (less to read) and not scaffolding `apiKey` (less
+ * temptation to put secrets on disk).
+ *
+ * Sets mode 0600 on the file. This doesn't protect against a user editing
+ * with `cp` or moving the file later, but ensures that the file as we
+ * create it isn't world-readable.
+ */
 export function writeDefaultConfig() {
     fs.mkdirSync(PATHS.config, { recursive: true });
     if (!fs.existsSync(FILES.config)) {
-        const defaults = ConfigSchema.parse({});
-        fs.writeFileSync(FILES.config, JSON.stringify(defaults, null, 2) + '\n');
+        const defaults = {
+            provider: 'anthropic',
+            anthropic: { model: 'claude-sonnet-4-6' },
+            maxSteps: 15,
+            logging: {
+                level: 'error',
+                auditLog: true,
+                reasoningLog: false,
+                usageLog: true,
+            },
+            caching: true,
+            verbose: false,
+            autoApprove: { readOnly: true, all: false },
+            forceInteractive: false,
+            historyLimit: 200,
+        };
+        fs.writeFileSync(FILES.config, JSON.stringify(defaults, null, 2) + '\n', {
+            mode: 0o600,
+        });
     }
     return FILES.config;
 }

package/dist/errors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Sentinel error: the user pressed Ctrl-C during a prompt. Thrown from
+ * inside tool `execute()` functions when Inquirer throws ExitPromptError,
+ * propagated up through the agent loop, caught at the cli.ts boundary
+ * where it triggers a clean exit with status 130.
+ *
+ * Using a custom class (not a string match) gives us reliable
+ * `instanceof UserCancelledError` checks across all the places that need
+ * to handle the cancellation differently from real errors.
+ */
+export declare class UserCancelledError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Sentinel error: the AWS CLI returned an exit code in FATAL_AWS_EXIT_CODES
+ * (252-255). These indicate an unrecoverable condition — auth failure,
+ * missing credentials, malformed request, AWS service failure — and
+ * retrying won't help. The tool throws this instead of returning a result,
+ * so the model never gets a chance to retry. The agent loop catches it,
+ * propagates the stderr to the user, and exits 1.
+ *
+ * Carries the original cmd, exitCode, and stderr so cli.ts can surface
+ * them to the user.
+ */
+export declare class FatalAwsCliError extends Error {
+    readonly cmd: string;
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(cmd: string, exitCode: number, stderr: string);
+}
+/**
+ * AWS CLI exit codes that indicate an unrecoverable condition:
+ *   252 — Command-line parsing errors (typically a bug in our agent or
+ *         the CLI itself; retrying won't help)
+ *   253 — Profile/credentials not found in the credential chain
+ *   254 — Client-side error (4xx from the service — auth, permission,
+ *         malformed request)
+ *   255 — Server-side error (5xx from the service — internal AWS issues)
+ *
+ * Anything else non-zero is a soft error (resource not found, etc.) and
+ * gets returned to the model normally — it may try a different approach.
+ * The model is bounded by `maxSteps` for runaway loops; we deliberately
+ * don't impose a separate soft-failure cap.
+ *
+ * Exit code 130 (SIGINT) in interactive mode is treated as a clean user
+ * cancellation, not an error — see aws-cli.ts's `effectivelyOk` rule.
+ */
+export declare const FATAL_AWS_EXIT_CODES: Set<number>;
+/**
+ * Wrap an Inquirer prompt call so that:
+ *
+ *   1. The prompt's question text renders on stderr, not stdout. Critical
+ *      for `aca "..." > file.txt` — without this, the prompt would be
+ *      silently swallowed into the redirected file while the user stared
+ *      at a frozen terminal waiting for an invisible question.
+ *
+ *   2. Ctrl-C (which Inquirer reports as `ExitPromptError`) becomes our
+ *      `UserCancelledError` sentinel. The Inquirer error class isn't
+ *      easily importable, so we detect by `.name`.
+ *
+ * The `output` option lives on Inquirer's `context` parameter (the second
+ * positional argument), NOT on the config object. Spreading it into the
+ * config silently does nothing — TypeScript accepts the extra property,
+ * but at runtime Inquirer ignores it. Pass the prompt as a thunk so we
+ * can inject the context at the call site:
+ *
+ *   const ok = await wrapPrompt((ctx) =>
+ *     confirm({ message: 'Execute?', default: true }, ctx),
+ *   );
+ *
+ * The thunk pattern is slightly more verbose than `wrapPrompt(confirm(...))`
+ * was, but it's the only shape that lets us centralize the context
+ * injection. Forgetting to pass `ctx` through to the Inquirer call is
+ * impossible to do silently — TypeScript will infer ctx's type and lint
+ * unused parameters.
+ */
+export declare function wrapPrompt<T>(factory: (ctx: {
+    output: NodeJS.WritableStream;
+}) => Promise<T>): Promise<T>;

package/dist/errors.js

@@ -0,0 +1,96 @@
+/**
+ * Sentinel error: the user pressed Ctrl-C during a prompt. Thrown from
+ * inside tool `execute()` functions when Inquirer throws ExitPromptError,
+ * propagated up through the agent loop, caught at the cli.ts boundary
+ * where it triggers a clean exit with status 130.
+ *
+ * Using a custom class (not a string match) gives us reliable
+ * `instanceof UserCancelledError` checks across all the places that need
+ * to handle the cancellation differently from real errors.
+ */
+export class UserCancelledError extends Error {
+    constructor(message = 'User cancelled the operation.') {
+        super(message);
+        this.name = 'UserCancelledError';
+    }
+}
+/**
+ * Sentinel error: the AWS CLI returned an exit code in FATAL_AWS_EXIT_CODES
+ * (252-255). These indicate an unrecoverable condition — auth failure,
+ * missing credentials, malformed request, AWS service failure — and
+ * retrying won't help. The tool throws this instead of returning a result,
+ * so the model never gets a chance to retry. The agent loop catches it,
+ * propagates the stderr to the user, and exits 1.
+ *
+ * Carries the original cmd, exitCode, and stderr so cli.ts can surface
+ * them to the user.
+ */
+export class FatalAwsCliError extends Error {
+    cmd;
+    exitCode;
+    stderr;
+    constructor(cmd, exitCode, stderr) {
+        super(`AWS CLI exited with code ${exitCode} (unrecoverable): ${stderr.trim() || '<no stderr>'}`);
+        this.cmd = cmd;
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+        this.name = 'FatalAwsCliError';
+    }
+}
+/**
+ * AWS CLI exit codes that indicate an unrecoverable condition:
+ *   252 — Command-line parsing errors (typically a bug in our agent or
+ *         the CLI itself; retrying won't help)
+ *   253 — Profile/credentials not found in the credential chain
+ *   254 — Client-side error (4xx from the service — auth, permission,
+ *         malformed request)
+ *   255 — Server-side error (5xx from the service — internal AWS issues)
+ *
+ * Anything else non-zero is a soft error (resource not found, etc.) and
+ * gets returned to the model normally — it may try a different approach.
+ * The model is bounded by `maxSteps` for runaway loops; we deliberately
+ * don't impose a separate soft-failure cap.
+ *
+ * Exit code 130 (SIGINT) in interactive mode is treated as a clean user
+ * cancellation, not an error — see aws-cli.ts's `effectivelyOk` rule.
+ */
+export const FATAL_AWS_EXIT_CODES = new Set([252, 253, 254, 255]);
+/**
+ * Wrap an Inquirer prompt call so that:
+ *
+ *   1. The prompt's question text renders on stderr, not stdout. Critical
+ *      for `aca "..." > file.txt` — without this, the prompt would be
+ *      silently swallowed into the redirected file while the user stared
+ *      at a frozen terminal waiting for an invisible question.
+ *
+ *   2. Ctrl-C (which Inquirer reports as `ExitPromptError`) becomes our
+ *      `UserCancelledError` sentinel. The Inquirer error class isn't
+ *      easily importable, so we detect by `.name`.
+ *
+ * The `output` option lives on Inquirer's `context` parameter (the second
+ * positional argument), NOT on the config object. Spreading it into the
+ * config silently does nothing — TypeScript accepts the extra property,
+ * but at runtime Inquirer ignores it. Pass the prompt as a thunk so we
+ * can inject the context at the call site:
+ *
+ *   const ok = await wrapPrompt((ctx) =>
+ *     confirm({ message: 'Execute?', default: true }, ctx),
+ *   );
+ *
+ * The thunk pattern is slightly more verbose than `wrapPrompt(confirm(...))`
+ * was, but it's the only shape that lets us centralize the context
+ * injection. Forgetting to pass `ctx` through to the Inquirer call is
+ * impossible to do silently — TypeScript will infer ctx's type and lint
+ * unused parameters.
+ */
+export async function wrapPrompt(factory) {
+    try {
+        return await factory({ output: process.stderr });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'ExitPromptError') {
+            throw new UserCancelledError();
+        }
+        throw err;
+    }
+}

package/dist/providers.d.ts

@@ -1,16 +1,29 @@
 import type { LanguageModel } from 'ai';
 import type { Config } from './config.js';
+import type { Logger } from './logger.js';
 /**
  * Build a LanguageModel from config.
  *
- * For anthropic / openai / google: API keys are read from environment
- * variables only — never from the config file — to keep secrets out of disk
- * state we don't own.
+ * Per-provider config lives under the matching top-level block:
+ *   config.anthropic.{model, apiKey, apiKeyEnv}
+ *   config.openai.{model, apiKey, apiKeyEnv}
+ *   config.google.{model, apiKey, apiKeyEnv}
+ *   config.bedrock.{model, region, profile}
  *
- * For bedrock: no API key is needed. Authentication uses the standard AWS
- * credential chain (env vars, AWS_PROFILE, ~/.aws/credentials, SSO, IMDS,
- * container roles). Optionally `bedrockProfile` pins a specific named profile,
- * which is useful when the account hosting Bedrock model access is different
- * from the accounts the agent operates against.
+ * For anthropic / openai / google, API key resolution order (per-provider):
+ *   1. Env var named by `<provider>.apiKeyEnv` if set in config
+ *   2. Default env var for the provider (ANTHROPIC_API_KEY etc.)
+ *   3. `<provider>.apiKey` from config (last resort — persists to disk)
+ *   4. Throw with all options listed
+ *
+ * For bedrock: no API key. The AWS credential chain (env vars, AWS_PROFILE,
+ * ~/.aws/credentials, SSO, IMDS, container roles) is used. `bedrock.profile`
+ * optionally pins a specific named profile — useful when the account hosting
+ * Bedrock model access is different from the accounts the agent operates
+ * against.
+ *
+ * The `logger` parameter is used to emit a debug-level note when the key
+ * resolves from config instead of env, so an investigator can see "this run
+ * read the key from disk" in general.log. The key itself is never logged.
  */
-export declare function createModel(config: Config): LanguageModel;
+export declare function createModel(config: Config, logger?: Logger): LanguageModel;

package/dist/providers.js

@@ -3,6 +3,10 @@ import { createOpenAI } from '@ai-sdk/openai';
 import { createGoogleGenerativeAI } from '@ai-sdk/google';
 import { createAmazonBedrock } from '@ai-sdk/amazon-bedrock';
 import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+/**
+ * Map provider → default env-var name. Used as the second fallback in the
+ * resolution chain (see `requireKey`).
+ */
 const DEFAULT_KEY_ENV = {
     anthropic: 'ANTHROPIC_API_KEY',
     openai: 'OPENAI_API_KEY',
@@ -11,49 +15,100 @@ const DEFAULT_KEY_ENV = {
 /**
  * Build a LanguageModel from config.
  *
- * For anthropic / openai / google: API keys are read from environment
- * variables only — never from the config file — to keep secrets out of disk
- * state we don't own.
+ * Per-provider config lives under the matching top-level block:
+ *   config.anthropic.{model, apiKey, apiKeyEnv}
+ *   config.openai.{model, apiKey, apiKeyEnv}
+ *   config.google.{model, apiKey, apiKeyEnv}
+ *   config.bedrock.{model, region, profile}
+ *
+ * For anthropic / openai / google, API key resolution order (per-provider):
+ *   1. Env var named by `<provider>.apiKeyEnv` if set in config
+ *   2. Default env var for the provider (ANTHROPIC_API_KEY etc.)
+ *   3. `<provider>.apiKey` from config (last resort — persists to disk)
+ *   4. Throw with all options listed
+ *
+ * For bedrock: no API key. The AWS credential chain (env vars, AWS_PROFILE,
+ * ~/.aws/credentials, SSO, IMDS, container roles) is used. `bedrock.profile`
+ * optionally pins a specific named profile — useful when the account hosting
+ * Bedrock model access is different from the accounts the agent operates
+ * against.
  *
- * For bedrock: no API key is needed. Authentication uses the standard AWS
- * credential chain (env vars, AWS_PROFILE, ~/.aws/credentials, SSO, IMDS,
- * container roles). Optionally `bedrockProfile` pins a specific named profile,
- * which is useful when the account hosting Bedrock model access is different
- * from the accounts the agent operates against.
+ * The `logger` parameter is used to emit a debug-level note when the key
+ * resolves from config instead of env, so an investigator can see "this run
+ * read the key from disk" in general.log. The key itself is never logged.
  */
-export function createModel(config) {
+export function createModel(config, logger) {
     switch (config.provider) {
         case 'anthropic': {
-            const apiKey = requireKey(config, 'anthropic');
-            return createAnthropic({ apiKey })(config.model);
+            const block = config.anthropic; // validated upstream
+            const apiKey = requireKey('anthropic', block.apiKey, block.apiKeyEnv, logger);
+            return createAnthropic({ apiKey })(block.model);
         }
         case 'openai': {
-            const apiKey = requireKey(config, 'openai');
-            return createOpenAI({ apiKey })(config.model);
+            const block = config.openai;
+            const apiKey = requireKey('openai', block.apiKey, block.apiKeyEnv, logger);
+            return createOpenAI({ apiKey })(block.model);
         }
         case 'google': {
-            const apiKey = requireKey(config, 'google');
-            return createGoogleGenerativeAI({ apiKey })(config.model);
+            const block = config.google;
+            const apiKey = requireKey('google', block.apiKey, block.apiKeyEnv, logger);
+            return createGoogleGenerativeAI({ apiKey })(block.model);
         }
         case 'bedrock': {
-            const region = config.bedrock?.region ??
-                process.env.AWS_REGION ??
-                process.env.AWS_DEFAULT_REGION;
+            const block = config.bedrock;
+            const region = block.region ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION;
             if (!region) {
                 throw new Error('Bedrock requires a region. Set "bedrock.region" in config or AWS_REGION env var.');
             }
-            const credentialProvider = config.bedrock?.profile
-                ? fromNodeProviderChain({ profile: config.bedrock.profile })
+            const credentialProvider = block.profile
+                ? fromNodeProviderChain({ profile: block.profile })
                 : fromNodeProviderChain();
-            return createAmazonBedrock({ region, credentialProvider })(config.model);
+            return createAmazonBedrock({ region, credentialProvider })(block.model);
         }
     }
 }
-function requireKey(config, provider) {
-    const envName = config.apiKeyEnv ?? DEFAULT_KEY_ENV[provider];
-    const apiKey = process.env[envName];
-    if (!apiKey) {
-        throw new Error(`Missing API key. Set environment variable ${envName} (or override "apiKeyEnv" in config).`);
+/**
+ * Three-tier API key resolution. Returns the key (never logs it). Emits a
+ * debug-level note when the key came from config rather than env, so an
+ * investigator looking at general.log can see what happened.
+ *
+ * When `apiKeyEnv` is set in config but the named env var is empty, we emit
+ * a warning to stderr and fall through to the default env var. The warning
+ * matters because `apiKeyEnv` is an explicit user instruction ("read the
+ * key from THIS variable") — silently using a different source could send
+ * the wrong account's request to the model provider.
+ */
+function requireKey(provider, configKey, configKeyEnv, logger) {
+    // 1. Custom env var name from config takes precedence — when it's set.
+    if (configKeyEnv) {
+        const v = process.env[configKeyEnv];
+        if (v)
+            return v;
+        // The user told us where to look, but the variable is empty. This is
+        // almost always a mistake (typo'd var name, forgot to export it,
+        // wrong shell). Surface it loudly so they fix it; then fall through
+        // to the default env var so the run can still succeed if that's set.
+        process.stderr.write(`Warning: config.${provider}.apiKeyEnv names "${configKeyEnv}" but ` +
+            `that environment variable is not set. Falling back to the default ` +
+            `(${DEFAULT_KEY_ENV[provider]}) or config.${provider}.apiKey.\n`);
+        logger?.warn(`${provider}: configured apiKeyEnv "${configKeyEnv}" is not set in the environment.`);
+    }
+    // 2. Default env var for the provider.
+    const defaultEnv = DEFAULT_KEY_ENV[provider];
+    const fromDefaultEnv = process.env[defaultEnv];
+    if (fromDefaultEnv)
+        return fromDefaultEnv;
+    // 3. Config-stored key — last resort. Note it.
+    if (configKey) {
+        logger?.debug(`${provider}: API key loaded from config file (no env var set). ` +
+            `Prefer ${configKeyEnv ?? defaultEnv} env var for production use.`);
+        return configKey;
     }
-    return apiKey;
+    // 4. Nothing.
+    throw new Error(`No API key found for provider "${provider}". Set one of:\n` +
+        (configKeyEnv
+            ? `  - env var ${configKeyEnv} (named by config.${provider}.apiKeyEnv)\n`
+            : '') +
+        `  - env var ${defaultEnv} (default for ${provider})\n` +
+        `  - config.${provider}.apiKey (persists to disk — env var preferred)`);
 }