agentic-orchestrator 0.1.7 → 0.1.9

package/README.md

@@ -247,6 +247,12 @@ Behavior:
   1. CLI flags (`--agent-provider`, `--agent-model`, `--agent-config`, `--provider-config-env`)
   2. env vars (`AOP_AGENT_PROVIDER`, `AOP_AGENT_MODEL`, `AOP_AGENT_CONFIG`/`AOP_AGENT_CONFIG_JSON`, `AOP_PROVIDER_CONFIG_ENV`)
   3. `config/agentic/orchestrator/agents.yaml` runtime defaults
+- Provider credential resolution (`provider_config_ref`):
+  1. `--provider-config-env <NAME>` if `NAME` exists in env
+  2. `agents.yaml runtime.provider_config_env` if that env var exists
+  3. `AOP_PROVIDER_CONFIG_ENV` fallback:
+     - if it looks like an env-var name and that env var exists, use that value (legacy indirection)
+     - otherwise use `AOP_PROVIDER_CONFIG_ENV` as the direct credential value
 - Runtime start:
   - starts `SupervisorRuntime` with `max_active_features=5`, `max_parallel_gate_runs=3`.
   - `max_iterations_per_phase` resolves from `policy.yaml` (`supervisor.max_iterations_per_phase`, default `6`).
@@ -376,7 +382,7 @@ When `cleanup.auto_after_merge` is enabled in `policy.yaml`, the runtime automat
 
 ### `init`
 
-Initialises agentic orchestrator configuration in the current directory. Generates `policy.yaml`, `gates.yaml`, `agents.yaml`, `adapters.yaml`, and system prompt templates. The wizard also captures default agent `provider`/`model` and `scm-provider`.
+Initialises agentic orchestrator configuration in the current directory. Generates `policy.yaml`, `gates.yaml`, `agents.yaml`, `adapters.yaml`, and system prompt templates. The wizard also captures default agent `provider`/`model`, `scm-provider`, and provider-auth mode.
 
 Schema files are bundled with AOP and validated from the installation path; `aop init` does not copy schemas into the target repository.
 
@@ -414,6 +420,14 @@ At runtime the kernel always composes a canonical full policy by:
 
 Existing repositories with full `policy.yaml` files continue to work without changes — user values override defaults entirely.
 
+#### Provider Auth Flow In `aop init`
+
+- wizard prompt: `Will you use a local agent CLI ... (yes/no)` (default `yes`)
+- if `yes`: init skips `runtime.provider_config_env` in `agents.yaml`
+- if `no`: init asks for provider env var name and checks both process env and repo `.env`
+- if missing: init prompts for a key, stores it in `.env` as `AOP_PROVIDER_CONFIG_ENV`, and writes `runtime.provider_config_env: AOP_PROVIDER_CONFIG_ENV`
+- `aop init --auto` defaults to local-CLI mode and does not emit `provider_config_env`
+
 ### `dashboard`
 
 Starts the web dashboard server (`packages/web-dashboard/`). Provides a real-time Kanban view of all features, review approval/denial, checkout, and SSE-based live updates.
@@ -484,7 +498,7 @@ Supported options:
 | `--agent-provider <codex\\        | claude\\                                                                          | gemini\\                                                     | custom\\                                   | kiro-cli\\ | copilot>` | Provider selection |
 | `--agent-model <model-id>`        | Model selection                                                                   |
 | `--agent-config <json-object>`    | Additional provider-specific agent config (for example command/args payload)      |
-| `--provider-config-env <ENV_VAR>` | Provider auth/config environment variable name                                    |
+| `--provider-config-env <ENV_VAR>` | Provider auth/config env var name for API-backed providers                        |
 | `--transport <mcp\\               | inprocess>`                                                                       | Tool transport selection (default `mcp`)                     |
 | `--takeover-stale-run`            | Allow stale run-lease takeover during `run`                                       |
 | `--project <name>`                | Select project from `multi-project.yaml` (run, status, resume, retry)             |
@@ -525,6 +539,14 @@ Provider resolution precedence:
 2. env vars (`AOP_AGENT_PROVIDER`, `AOP_AGENT_MODEL`, `AOP_AGENT_CONFIG`/`AOP_AGENT_CONFIG_JSON`, `AOP_PROVIDER_CONFIG_ENV`)
 3. `config/agentic/orchestrator/agents.yaml` runtime defaults
 
+Provider credential fallback:
+
+1. `--provider-config-env <NAME>` if `NAME` exists
+2. `runtime.provider_config_env` if that env var exists
+3. `AOP_PROVIDER_CONFIG_ENV`:
+   - `AOP_PROVIDER_CONFIG_ENV=OTHER_ENV` and `OTHER_ENV` exists -> use `OTHER_ENV`
+   - otherwise treat `AOP_PROVIDER_CONFIG_ENV` as direct credential value
+
 Transport behavior:
 
 - default transport is `mcp`
@@ -571,7 +593,7 @@ Coverage parser:
 ### Agents (`config/agentic/orchestrator/agents.yaml`)
 
 - role-specific system prompt paths
-- default provider/model/config-env fallback values
+- default provider/model values with optional `runtime.provider_config_env` for API-backed providers
 - optional `runtime.provider_configs.<provider>` objects for provider-specific payloads (for example `kiro-cli chat --agent dev`)
 - `worktree.post_create` commands and `worktree.symlinks` for workspace hook automation
 - stack-specific examples: [`example-configurations/node/`](example-configurations/node) and [`example-configurations/java/`](example-configurations/java)

package/agentic/orchestrator/schemas/agents.schema.json

@@ -54,7 +54,7 @@
         },
         "provider_config_env": {
           "type": "string",
-          "description": "Name of an environment variable whose value is a JSON provider-config blob. Takes lower priority than the CLI flag but higher than this file."
+          "description": "Optional env var name for API-backed provider credentials/config. Local CLI providers typically omit this. Runtime also supports AOP_PROVIDER_CONFIG_ENV fallback (legacy indirection or direct credential value)."
         },
         "provider_configs": {
           "type": "object",

package/apps/control-plane/src/cli/dashboard-command-handler.ts

@@ -1,10 +1,46 @@
 import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const execFileAsync = promisify(execFile);
+const DASHBOARD_WORKSPACE = '@aop/web-dashboard';
+
+async function hasDashboardCli(repoRoot: string): Promise<boolean> {
+  const candidates = [
+    path.join(repoRoot, 'node_modules', '.bin', 'next'),
+    path.join(repoRoot, 'packages', 'web-dashboard', 'node_modules', '.bin', 'next'),
+  ];
+  for (const candidate of candidates) {
+    try {
+      await fs.access(candidate);
+      return true;
+    } catch {
+      // continue
+    }
+  }
+  return false;
+}
+
+async function ensureDashboardDependencies(
+  repoRoot: string,
+  env: NodeJS.ProcessEnv,
+): Promise<void> {
+  if (await hasDashboardCli(repoRoot)) {
+    return;
+  }
+
+  await execFileAsync(
+    'npm',
+    ['install', '--workspace', DASHBOARD_WORKSPACE, '--no-audit', '--no-fund'],
+    {
+      cwd: repoRoot,
+      env,
+    },
+  );
+}
 
 export class DashboardCommandHandler {
   async execute(options: {
@@ -14,7 +50,6 @@ export class DashboardCommandHandler {
   }): Promise<Record<string, unknown>> {
     const port = options.port ?? 3000;
     const repoRoot = path.resolve(__dirname, '../../../../');
-    const dashboardWorkspace = '@aop/web-dashboard';
     const devMode = options.dev === true;
     const foreground = options.foreground === true || devMode;
 
@@ -25,8 +60,10 @@ export class DashboardCommandHandler {
       AOP_ROOT: process.cwd(),
     };
 
+    await ensureDashboardDependencies(repoRoot, env);
+
     if (devMode) {
-      const child = spawn('npm', ['run', '--workspace', dashboardWorkspace, 'dev'], {
+      const child = spawn('npm', ['run', '--workspace', DASHBOARD_WORKSPACE, 'dev'], {
         cwd: repoRoot,
         env,
         stdio: 'inherit',
@@ -38,13 +75,13 @@ export class DashboardCommandHandler {
       return { ok: true, data: { message: 'Dashboard stopped', port, mode: 'dev' } };
     }
 
-    await execFileAsync('npm', ['run', '--workspace', dashboardWorkspace, 'build'], {
+    await execFileAsync('npm', ['run', '--workspace', DASHBOARD_WORKSPACE, 'build'], {
       cwd: repoRoot,
       env,
     });
 
     if (foreground) {
-      const child = spawn('npm', ['run', '--workspace', dashboardWorkspace, 'start'], {
+      const child = spawn('npm', ['run', '--workspace', DASHBOARD_WORKSPACE, 'start'], {
         cwd: repoRoot,
         env,
         stdio: 'inherit',
@@ -56,7 +93,7 @@ export class DashboardCommandHandler {
       return { ok: true, data: { message: 'Dashboard stopped', port, mode: 'production' } };
     }
 
-    const child = spawn('npm', ['run', '--workspace', dashboardWorkspace, 'start'], {
+    const child = spawn('npm', ['run', '--workspace', DASHBOARD_WORKSPACE, 'start'], {
       cwd: repoRoot,
       env,
       detached: true,

package/apps/control-plane/src/cli/env-file.ts

@@ -0,0 +1,115 @@
+import fs from 'node:fs/promises';
+
+export type EnvFileValues = Record<string, string>;
+
+const SAFE_UNQUOTED_ENV_VALUE = /^[A-Za-z0-9_./:@+=-]+$/;
+
+function unquoteValue(raw: string): string {
+  const trimmed = raw.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function parseEnvLine(line: string): { key: string; value: string } | null {
+  const trimmed = line.trim();
+  if (trimmed.length === 0 || trimmed.startsWith('#')) {
+    return null;
+  }
+
+  const normalized = trimmed.startsWith('export ') ? trimmed.slice('export '.length) : trimmed;
+  const separatorIndex = normalized.indexOf('=');
+  if (separatorIndex <= 0) {
+    return null;
+  }
+
+  const key = normalized.slice(0, separatorIndex).trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    return null;
+  }
+
+  const value = normalized.slice(separatorIndex + 1);
+  return { key, value: unquoteValue(value) };
+}
+
+function formatEnvValue(value: string): string {
+  if (SAFE_UNQUOTED_ENV_VALUE.test(value)) {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+
+export async function readEnvFileValues(envPath: string): Promise<EnvFileValues> {
+  let content: string;
+  try {
+    content = await fs.readFile(envPath, 'utf8');
+  } catch {
+    return {};
+  }
+
+  const values: EnvFileValues = {};
+  for (const line of content.split(/\r?\n/)) {
+    const parsed = parseEnvLine(line);
+    if (!parsed) {
+      continue;
+    }
+    values[parsed.key] = parsed.value;
+  }
+  return values;
+}
+
+export function readNonEmptyEnvValue(
+  key: string,
+  runtimeEnv: NodeJS.ProcessEnv,
+  envFileValues: EnvFileValues,
+): string | null {
+  const runtimeValue = runtimeEnv[key];
+  if (typeof runtimeValue === 'string' && runtimeValue.trim().length > 0) {
+    return runtimeValue;
+  }
+
+  const fileValue = envFileValues[key];
+  if (typeof fileValue === 'string' && fileValue.trim().length > 0) {
+    return fileValue;
+  }
+
+  return null;
+}
+
+export async function upsertEnvFileValue(
+  envPath: string,
+  key: string,
+  value: string,
+): Promise<void> {
+  let content = '';
+  try {
+    content = await fs.readFile(envPath, 'utf8');
+  } catch {
+    // create file from scratch
+  }
+
+  const lines = content.length > 0 ? content.split(/\r?\n/) : [];
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const matcher = new RegExp(`^\\s*(?:export\\s+)?${escapedKey}\\s*=`);
+  const nextLine = `${key}=${formatEnvValue(value)}`;
+
+  let replaced = false;
+  for (let index = 0; index < lines.length; index += 1) {
+    if (matcher.test(lines[index])) {
+      lines[index] = nextLine;
+      replaced = true;
+      break;
+    }
+  }
+
+  if (!replaced) {
+    lines.push(nextLine);
+  }
+
+  const normalized = `${lines.join('\n').replace(/\n*$/, '')}\n`;
+  await fs.writeFile(envPath, normalized, 'utf8');
+}

package/apps/control-plane/src/cli/help-command-handler.ts

@@ -25,7 +25,7 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
       { flag: '--agent-config <PATH>', description: 'Path to agent config file' },
       {
         flag: '--provider-config-env <var>',
-        description: 'Env var name that holds provider API key',
+        description: 'Env var name used for API-backed provider auth/config',
       },
       { flag: '--transport <inprocess|mcp>', description: 'Tool transport layer (default: mcp)' },
       { flag: '--takeover-stale-run', description: 'Take over a stale run lease' },

package/apps/control-plane/src/cli/init-command-handler.ts

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
 import { SchemaRegistry } from '../core/schemas.js';
 import { loadComposedPolicy } from '../application/services/policy-loader-service.js';
+import { readEnvFileValues, readNonEmptyEnvValue, upsertEnvFileValue } from './env-file.js';
 import {
   AGENT_PROVIDER_SLOT,
   SCM_PROVIDER_SLOT,
@@ -47,6 +48,8 @@ interface WizardConfig {
   framework: TestFramework;
   defaultProvider: string;
   defaultModel: string;
+  providerConfigEnv: string | null;
+  providerCredentialBootstrapped: boolean;
   scmProvider: string;
   notifications: {
     desktop: boolean;
@@ -402,6 +405,9 @@ capabilities:
 }
 
 function generateAgentsYaml(wizard: WizardConfig): string {
+  const providerConfigEnvLine = wizard.providerConfigEnv
+    ? `  provider_config_env: ${wizard.providerConfigEnv}\n`
+    : '';
   return `version: 1
 roles:
   planner:
@@ -414,8 +420,7 @@ missing_prompt_behavior: ignore
 runtime:
   default_provider: ${wizard.defaultProvider}
   default_model: ${wizard.defaultModel}
-  provider_config_env: AOP_PROVIDER_CONFIG_ENV
-  role_provider_overrides: {}
+${providerConfigEnvLine}  role_provider_overrides: {}
 `;
 }
 
@@ -512,7 +517,26 @@ async function askWithDefault(
   return raw.length > 0 ? raw : defaultValue;
 }
 
+function parseYesNo(raw: string, fallback: boolean): boolean {
+  const normalized = raw.trim().toLowerCase();
+  if (normalized === 'yes' || normalized === 'y' || normalized === 'true') {
+    return true;
+  }
+  if (normalized === 'no' || normalized === 'n' || normalized === 'false') {
+    return false;
+  }
+  return fallback;
+}
+
+function defaultProviderConfigEnvName(provider: string): string {
+  if (provider === 'gemini') {
+    return 'GEMINI_API_KEY';
+  }
+  return 'AOP_PROVIDER_CONFIG_ENV';
+}
+
 async function collectWizardConfig(
+  repoRoot: string,
   defaults: {
     branch: string;
     framework: TestFramework;
@@ -524,6 +548,8 @@ async function collectWizardConfig(
 ): Promise<WizardConfig> {
   const prompt = promptFactory();
   try {
+    const envFilePath = path.join(repoRoot, '.env');
+    const envFileValues = await readEnvFileValues(envFilePath);
     const supportedProviders = new Set(
       globalAdapterRegistry.list(AGENT_PROVIDER_SLOT.name).map((adapter) => adapter.name),
     );
@@ -567,6 +593,42 @@ async function collectWizardConfig(
       webhookUrl = (await prompt.question('Webhook URL []: ')).trim();
     }
 
+    const localCliAnswer = await askWithDefault(
+      prompt,
+      'Will you use a local agent CLI (codex/claude-code/kiro-cli/copilot)? (yes/no)',
+      'yes',
+    );
+    const usesLocalCli = parseYesNo(localCliAnswer, true);
+
+    let providerConfigEnv: string | null = null;
+    let providerCredentialBootstrapped = false;
+
+    if (!usesLocalCli) {
+      const envVarName = await askWithDefault(
+        prompt,
+        'Provider config env var name',
+        defaultProviderConfigEnvName(defaultProviderRaw),
+      );
+      const envValue = readNonEmptyEnvValue(envVarName, process.env, envFileValues);
+
+      if (envValue) {
+        providerConfigEnv = envVarName;
+      } else {
+        output.write(
+          `Environment variable "${envVarName}" was not found in process env or ${envFilePath}.\n`,
+        );
+        let pastedKey = '';
+        while (pastedKey.length === 0) {
+          pastedKey = (
+            await prompt.question('Paste provider key to store in AOP_PROVIDER_CONFIG_ENV: ')
+          ).trim();
+        }
+        await upsertEnvFileValue(envFilePath, 'AOP_PROVIDER_CONFIG_ENV', pastedKey);
+        providerConfigEnv = 'AOP_PROVIDER_CONFIG_ENV';
+        providerCredentialBootstrapped = true;
+      }
+    }
+
     return {
       baseBranch,
       defaultProvider: parseAdapterName(
@@ -575,6 +637,8 @@ async function collectWizardConfig(
         defaults.defaultProvider,
       ),
       defaultModel,
+      providerConfigEnv,
+      providerCredentialBootstrapped,
       scmProvider: parseAdapterName(
         scmProviderRaw,
         supportedScmProviders,
@@ -633,6 +697,8 @@ export class InitCommandHandler {
           baseBranch: gitContext.defaultBranch,
           defaultProvider: DEFAULT_AGENT_PROVIDER,
           defaultModel: DEFAULT_AGENT_MODEL,
+          providerConfigEnv: null,
+          providerCredentialBootstrapped: false,
           scmProvider: DEFAULT_SCM_PROVIDER,
           maxParallelGateRuns: 3,
           dashboardPort: 3000,
@@ -646,6 +712,7 @@ export class InitCommandHandler {
           },
         }
       : await collectWizardConfig(
+          this.repoRoot,
           {
             branch: gitContext.defaultBranch,
             framework,
@@ -758,6 +825,9 @@ export class InitCommandHandler {
         'To generate a full explicit policy with all advanced controls, re-run: aop init --advanced-policy --force',
       );
     }
+    if (wizard.providerCredentialBootstrapped) {
+      nextSteps.push('Stored provider credential in .env as AOP_PROVIDER_CONFIG_ENV.');
+    }
 
     return {
       ok: true,

package/apps/control-plane/src/cli/retry-command-handler.ts

@@ -113,7 +113,6 @@ export class RetryCommandHandler {
 
     const gate = await callCliTool(this.toolClient, this.runId, TOOLS.GATES_RUN, {
       feature_id: featureId,
-      profile: null,
       mode: inferredMode,
     });
     const retryExecuted = true;

package/apps/control-plane/src/core/kernel.ts

@@ -1001,9 +1001,7 @@ export class AopKernel {
     await atomicWriteJson(runLeasePath, data);
   }
 
-  async acquireRunLease(
-    input: AcquireRunLeaseInput,
-  ): Promise<{
+  async acquireRunLease(input: AcquireRunLeaseInput): Promise<{
     data: {
       runtime_sessions: RuntimeSessionsSnapshot;
       took_over_stale: boolean;

package/apps/control-plane/src/core/tool-caller.ts

@@ -1,10 +1,25 @@
 export type RuntimeRole = 'orchestrator' | 'planner' | 'builder' | 'qa';
 
+export interface GatesRunToolArgs {
+  feature_id: string;
+  mode: string;
+  profile?: string;
+  operation_id?: string;
+}
+
+export interface ToolArgsByName {
+  'gates.run': GatesRunToolArgs;
+}
+
+export type ToolArgs<TToolName extends string> = TToolName extends keyof ToolArgsByName
+  ? ToolArgsByName[TToolName]
+  : Record<string, unknown>;
+
 export interface ToolCaller {
-  callTool<TData = Record<string, unknown>>(
+  callTool<TData = Record<string, unknown>, TToolName extends string = string>(
     role: RuntimeRole,
-    toolName: string,
-    args: Record<string, unknown>,
+    toolName: TToolName,
+    args: ToolArgs<TToolName>,
   ): Promise<{ ok: true; data: TData }>;
 }
 

package/apps/control-plane/src/interfaces/cli/bootstrap.ts

@@ -24,6 +24,7 @@ import { RetryCommandHandler } from '../../cli/retry-command-handler.js';
 import { SendCommandHandler } from '../../cli/send-command-handler.js';
 import { AttachCommandHandler } from '../../cli/attach-command-handler.js';
 import { HelpCommandHandler } from '../../cli/help-command-handler.js';
+import { readEnvFileValues } from '../../cli/env-file.js';
 import { MultiProjectLoader } from '../../application/multi-project-loader.js';
 import { NullWorkerProvider, resolveProviderSelection } from '../../providers/providers.js';
 import type { RuntimeContext } from '../../cli/types.js';
@@ -154,6 +155,12 @@ export async function runCli(
   }
 
   try {
+    const envFileValues = await readEnvFileValues(path.join(repoRoot, '.env'));
+    const effectiveEnv: NodeJS.ProcessEnv = {
+      ...envFileValues,
+      ...runtime.env,
+    };
+
     if (!SUPPORTED_COMMANDS.has(options.command)) {
       printError(ERROR_CODES.INVALID_CLI_ARGS, `Unknown command: ${options.command}`, {
         command: options.command,
@@ -264,7 +271,7 @@ export async function runCli(
       try {
         selection = resolveProviderSelection({
           cli: options as unknown as Record<string, string | undefined>,
-          env: runtime.env,
+          env: effectiveEnv,
           agentsConfig: kernel.getAgentsConfig(),
         });
       } catch {
@@ -290,7 +297,7 @@ export async function runCli(
       const handler = new ResumeCommandHandler();
       const payload = await handler.execute({
         repoRoot,
-        env: runtime.env,
+        env: effectiveEnv,
         runId,
         transport,
         options,
@@ -362,7 +369,7 @@ export async function runCli(
     const handler = new RunCommandHandler();
     const payload = await handler.execute({
       repoRoot,
-      env: runtime.env,
+      env: effectiveEnv,
       runId,
       transport,
       options,

package/apps/control-plane/src/providers/providers.ts

@@ -31,6 +31,7 @@ interface ResolveSelectionInput {
 }
 
 type ResolveSelectionRuntimeConfig = NonNullable<ResolveSelectionInput['agentsConfig']>['runtime'];
+const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -87,8 +88,66 @@ function resolveConfiguredAgentConfig(
   return null;
 }
 
+function readNonEmptyEnvValue(env: NodeJS.ProcessEnv, key: string | null): string | null {
+  if (!key) {
+    return null;
+  }
+  const value = env[key];
+  if (typeof value !== 'string') {
+    return null;
+  }
+  return value.trim().length > 0 ? value : null;
+}
+
+function resolveProviderCredentialReference(
+  cliProviderConfigEnv: string | undefined,
+  configProviderConfigEnv: string | undefined,
+  env: NodeJS.ProcessEnv,
+): { providerConfigEnv: string | null; providerConfigRef: string | null } {
+  const cliConfiguredName = cliProviderConfigEnv?.trim() || null;
+  const configConfiguredName = configProviderConfigEnv?.trim() || null;
+  const unresolvedConfiguredName = cliConfiguredName ?? configConfiguredName ?? null;
+
+  const cliValue = readNonEmptyEnvValue(env, cliConfiguredName);
+  if (cliValue) {
+    return { providerConfigEnv: cliConfiguredName, providerConfigRef: cliValue };
+  }
+
+  const configValue = readNonEmptyEnvValue(env, configConfiguredName);
+  if (configValue) {
+    return { providerConfigEnv: configConfiguredName, providerConfigRef: configValue };
+  }
+
+  const aopFallback = readNonEmptyEnvValue(env, 'AOP_PROVIDER_CONFIG_ENV');
+  if (aopFallback) {
+    if (ENV_VAR_NAME_PATTERN.test(aopFallback)) {
+      const indirectValue = readNonEmptyEnvValue(env, aopFallback);
+      if (indirectValue) {
+        return { providerConfigEnv: aopFallback, providerConfigRef: indirectValue };
+      }
+    }
+
+    return {
+      providerConfigEnv: 'AOP_PROVIDER_CONFIG_ENV',
+      providerConfigRef: aopFallback,
+    };
+  }
+
+  return {
+    providerConfigEnv: unresolvedConfiguredName,
+    providerConfigRef: null,
+  };
+}
+
 export const SUPPORTED_PROVIDERS: Set<string> = new Set(REGISTERED_PROVIDER_NAMES);
-export const AUTH_REQUIRED_PROVIDERS: Set<string> = new Set(['codex', 'claude', 'gemini']);
+export const LOCAL_CLI_PROVIDERS: Set<string> = new Set([
+  'codex',
+  'claude',
+  'kiro-cli',
+  'copilot',
+  'custom',
+]);
+export const CREDENTIAL_REQUIRED_PROVIDERS: Set<string> = new Set(['gemini']);
 export type ProviderSelectionResolver = (input: ResolveSelectionInput) => ProviderSelection;
 
 export const resolveProviderSelection: ProviderSelectionResolver = ({ cli, env, agentsConfig }) => {
@@ -98,11 +157,11 @@ export const resolveProviderSelection: ProviderSelectionResolver = ({ cli, env,
   const model =
     cli.agent_model || env.AOP_AGENT_MODEL || agentsConfig?.runtime?.default_model || null;
 
-  const providerConfigEnv =
-    cli.provider_config_env ||
-    env.AOP_PROVIDER_CONFIG_ENV ||
-    agentsConfig?.runtime?.provider_config_env ||
-    null;
+  const { providerConfigEnv, providerConfigRef } = resolveProviderCredentialReference(
+    cli.provider_config_env,
+    agentsConfig?.runtime?.provider_config_env,
+    env,
+  );
 
   if (!provider) {
     const error = new Error(ERROR_CODES.AGENT_PROVIDER_NOT_CONFIGURED) as AppError;
@@ -117,7 +176,7 @@ export const resolveProviderSelection: ProviderSelectionResolver = ({ cli, env,
     throw error;
   }
 
-  if (AUTH_REQUIRED_PROVIDERS.has(provider) && (!providerConfigEnv || !env[providerConfigEnv])) {
+  if (CREDENTIAL_REQUIRED_PROVIDERS.has(provider) && !providerConfigRef) {
     const error = new Error(ERROR_CODES.PROVIDER_AUTH_MISSING) as AppError;
     error.code = ERROR_CODES.PROVIDER_AUTH_MISSING;
     error.details = {
@@ -140,7 +199,7 @@ export const resolveProviderSelection: ProviderSelectionResolver = ({ cli, env,
     provider,
     model: model ?? `${provider}-default`,
     provider_config_env: providerConfigEnv,
-    provider_config_ref: providerConfigEnv ? (env[providerConfigEnv] ?? null) : null,
+    provider_config_ref: providerConfigRef,
     agent_config: agentConfig,
   };
 };