@zgeoff/atc 2.36.0 → 2.37.0

package/src/shared/collect-gateways.ts

@@ -1,20 +1,10 @@
 import { z } from 'zod';
 import type { AgentID } from './agent-id';
 import { buildOptionalStringArray } from './build-optional-string-array';
+import { checkGatewayAuth } from './check-gateway-auth';
+import type { GatewayAuth } from './check-gateway-auth';
 import type { AuthProfile } from './collect-auth-profiles';
-import { isBrokerVariable } from './is-broker-variable';
 import { isRecord } from './report';
-import { resolveAuthProfiles } from './resolve-auth-profiles';
-
-/**
- * The auth profiles a gateway's sessions are bound to through impd's
- * broker, and the variables each session gets in place of a credential,
- * every value the fixed placeholder.
- */
-export interface GatewayAuth {
-  readonly profiles: readonly string[];
-  readonly placeholderEnv: Readonly<Record<string, string>>;
-}
 
 /**
  * A Claude-compatible backend the Claude CLI is pointed at: its own agent id,
@@ -125,162 +115,6 @@ export function collectGateways(
   return { gateways, errors };
 }
 
-interface GatewayEntry {
-  readonly baseURL?: string | undefined;
-  readonly apiKeyHelper?: string | undefined;
-  readonly env: Readonly<Record<string, string>>;
-  readonly settings?: Readonly<Record<string, unknown>> | undefined;
-}
-
-// The gateway's auth, or every problem that refuses it. The checks cover
-// each place a session's environment comes from: the gateway env, the
-// settings env, and the placeholders, and which of them would win.
-function checkGatewayAuth(
-  raw: unknown,
-  entry: GatewayEntry,
-  authProfiles: ReadonlyMap<string, AuthProfile>,
-): GatewayAuth | string[] {
-  const auth = parseGatewayAuth(raw);
-
-  if (typeof auth === 'string') {
-    return [auth];
-  }
-
-  const problems: string[] = [];
-
-  if (entry.apiKeyHelper !== undefined) {
-    problems.push(
-      'apiKeyHelper cannot be set together with auth, which supplies the credential through the broker',
-    );
-  }
-
-  if (entry.settings?.['apiKeyHelper'] !== undefined) {
-    problems.push(
-      'settings.apiKeyHelper cannot be set together with auth, which supplies the credential through the broker',
-    );
-  }
-
-  const settingsEnv = toEnvKeys(entry.settings?.['env']);
-
-  problems.push(
-    ...collectEnvProblems('env', Object.keys(entry.env)),
-    ...collectEnvProblems('settings.env', settingsEnv),
-    ...collectPlaceholderProblems(auth.placeholderEnv),
-  );
-
-  for (const key of Object.keys(auth.placeholderEnv)) {
-    for (const [source, keys] of [
-      ['env', Object.keys(entry.env)],
-      ['settings.env', settingsEnv],
-    ] as const) {
-      if (keys.includes(key)) {
-        problems.push(`placeholderEnv.${key} is also set in ${source}, which would override it`);
-      }
-    }
-  }
-
-  const resolution = resolveAuthProfiles(authProfiles, auth.profiles);
-
-  if ('problem' in resolution) {
-    problems.push(resolution.problem.message);
-  } else {
-    const hostProblem = findBaseURLProblem(entry.baseURL ?? '', resolution.resolved.hosts);
-
-    if (hostProblem !== null) {
-      problems.push(hostProblem);
-    }
-  }
-
-  return problems.length > 0 ? problems : auth;
-}
-
-// The value every placeholder variable holds; impd's broker swaps the real
-// credential in on the host's side.
-const PLACEHOLDER = 'imp-broker-placeholder';
-
-function parseGatewayAuth(raw: unknown): GatewayAuth | string {
-  const profiles = isRecord(raw) ? raw['profiles'] : undefined;
-
-  if (
-    !isRecord(raw) ||
-    !Array.isArray(profiles) ||
-    profiles.length === 0 ||
-    !profiles.every((name) => typeof name === 'string')
-  ) {
-    return 'auth must be an object with a non-empty profiles array';
-  }
-
-  const placeholderEnv = raw['placeholderEnv'] ?? {};
-
-  if (!isRecord(placeholderEnv) || Array.isArray(placeholderEnv)) {
-    return 'placeholderEnv must be an object of variable names';
-  }
-
-  const env: Record<string, string> = {};
-
-  for (const [key, value] of Object.entries(placeholderEnv)) {
-    if (value !== PLACEHOLDER) {
-      return `placeholderEnv.${key} must be ${PLACEHOLDER}`;
-    }
-
-    env[key] = value;
-  }
-
-  return { profiles: profiles.map(String), placeholderEnv: env };
-}
-
-// A settings env's variable names; anything but an object sets none.
-function toEnvKeys(value: unknown): string[] {
-  return isRecord(value) && !Array.isArray(value) ? Object.keys(value) : [];
-}
-
-// Variables Claude reads its endpoint and credential from. Only the
-// placeholders may set a credential variable, and the base URL comes from
-// `baseURL` alone, whose host is checked against the profiles.
-const CREDENTIAL_VARIABLES: ReadonlySet<string> = new Set([
-  'ANTHROPIC_AUTH_TOKEN',
-  'ANTHROPIC_API_KEY',
-]);
-
-const BASE_URL_VARIABLE = 'ANTHROPIC_BASE_URL';
-
-function collectEnvProblems(source: string, keys: readonly string[]): string[] {
-  return keys
-    .filter(
-      (key) => isBrokerVariable(key) || CREDENTIAL_VARIABLES.has(key) || key === BASE_URL_VARIABLE,
-    )
-    .map((key) => `${source} must not set ${key}`);
-}
-
-function collectPlaceholderProblems(env: Readonly<Record<string, string>>): string[] {
-  return Object.keys(env)
-    .filter((key) => isBrokerVariable(key) || key === BASE_URL_VARIABLE)
-    .map((key) => `placeholderEnv must not set ${key}`);
-}
-
-// The broker matches a request by the exact host it connects to on the
-// default https port, so the base URL must be https on that port, with a
-// host one of the selected profiles covers.
-function findBaseURLProblem(baseURL: string, hosts: readonly string[]): string | null {
-  let url: URL;
-
-  try {
-    url = new URL(baseURL);
-  } catch {
-    return 'baseURL must be an https URL with no port or user info';
-  }
-
-  if (url.protocol !== 'https:' || url.port !== '' || url.username !== '' || url.password !== '') {
-    return 'baseURL must be an https URL with no port or user info';
-  }
-
-  if (!hosts.includes(url.hostname)) {
-    return `baseURL host ${url.hostname} is not a host of the selected profiles (${hosts.join(', ')})`;
-  }
-
-  return null;
-}
-
 // Claude Code settings the sessions of this gateway are started with, on top of
 // the ones atc writes itself. Anything but an object is no extra settings.
 function buildOptionalSettings() {

package/src/shared/collect-legacy-agents.ts

@@ -0,0 +1,77 @@
+import type { AgentEntry } from './collect-agents';
+import type { AuthProfile } from './collect-auth-profiles';
+import { collectClaudeAuth } from './collect-claude-auth';
+import { collectGateways } from './collect-gateways';
+
+/**
+ * The agent keys of the old config.json shape, already defaulted: a binary and arguments per harness, and the raw `claudeAuth`
+ * and `gateways` values.
+ */
+interface LegacyAgentKeys {
+  readonly claudeBin: string;
+  readonly claudeArgs: readonly string[];
+  readonly claudeAuth: unknown;
+  readonly grokBin: string;
+  readonly grokArgs: readonly string[];
+  readonly codexBin: string;
+  readonly codexArgs: readonly string[];
+  readonly gateways: unknown;
+}
+
+interface LegacyAgents {
+  readonly agents: AgentEntry[];
+
+  // The problems that left a Claude auth or a gateway out, in the text the
+  // old keys always reported.
+  readonly errors: string[];
+}
+
+/**
+ * Translates the old agent keys to registry entries: `claude`, `grok`, and
+ * `codex` in that order, then each gateway the old parse accepts, in file
+ * order. The parse is the old lenient one, so an absent or wrong-typed field
+ * takes its default.
+ */
+export function collectLegacyAgents(
+  keys: LegacyAgentKeys,
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): LegacyAgents {
+  const claudeAuth = collectClaudeAuth(keys.claudeAuth, authProfiles);
+  const gateways = collectGateways(keys.gateways, keys.claudeBin, keys.claudeArgs, authProfiles);
+
+  const agents: AgentEntry[] = [
+    {
+      id: 'claude',
+      kind: 'claude',
+      label: 'Claude',
+      mark: 'c',
+      bin: keys.claudeBin,
+      args: keys.claudeArgs,
+      env: {},
+      ...(claudeAuth.auth === null
+        ? {}
+        : { auth: { profiles: claudeAuth.auth.profiles, placeholderEnv: {} } }),
+    },
+    {
+      id: 'grok',
+      kind: 'grok',
+      label: 'Grok',
+      mark: 'g',
+      bin: keys.grokBin,
+      args: keys.grokArgs,
+      env: {},
+    },
+    {
+      id: 'codex',
+      kind: 'codex',
+      label: 'Codex',
+      mark: 'c',
+      bin: keys.codexBin,
+      args: keys.codexArgs,
+      env: {},
+    },
+    ...gateways.gateways.map((gateway): AgentEntry => ({ ...gateway, kind: 'claude' })),
+  ];
+
+  return { agents, errors: [...claudeAuth.errors, ...gateways.errors] };
+}

package/src/shared/config.ts

@@ -1,18 +1,18 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { z } from 'zod';
+import type { AgentID } from './agent-id';
 import { buildOptionalBoolean } from './build-optional-boolean';
 import { buildOptionalString } from './build-optional-string';
 import { buildOptionalStringArray } from './build-optional-string-array';
+import { collectAgents } from './collect-agents';
+import type { AgentEntry } from './collect-agents';
 import { collectAuthProfiles } from './collect-auth-profiles';
 import type { AuthProfile } from './collect-auth-profiles';
-import { collectClaudeAuth } from './collect-claude-auth';
-import type { ClaudeAuth } from './collect-claude-auth';
 import { collectDirRoots } from './collect-dir-roots';
-import { collectGateways } from './collect-gateways';
-import type { GatewayConfig } from './collect-gateways';
 import { collectHooks } from './collect-hooks';
 import type { HooksConfig } from './collect-hooks';
+import { collectLegacyAgents } from './collect-legacy-agents';
 import { collectPrincipals } from './collect-principals';
 import { collectTargets } from './collect-targets';
 import type { TargetConfig, TargetConfigError } from './collect-targets';
@@ -20,30 +20,28 @@ import { collectWorkspacesConfig } from './collect-workspaces-config';
 import type { WorkspacesConfig } from './collect-workspaces-config';
 import { DEFAULT_GIT_TRANSPORTS } from './default-git-transports';
 import { formatJSONKind } from './format-json-kind';
+import { formatMixedAgentKeys } from './format-mixed-agent-keys';
+import { LEGACY_AGENT_KEYS } from './legacy-agent-keys';
+import { pickDefaultAgent } from './pick-default-agent';
 import { isRecord } from './report';
 import { resolveHomeDir } from './resolve-home-dir';
 
 export interface Config {
-  claudeBin: string;
-  claudeArgs: string[];
-
-  // The auth profiles stock Claude signs in through on a target that
-  // reaches impd's broker, null when it keeps the host's own sign-in there,
-  // and the problems that left an entry out.
-  claudeAuth: ClaudeAuth | null;
-  claudeAuthErrors: readonly string[];
-  grokBin: string;
-  grokArgs: string[];
-  codexBin: string;
-  codexArgs: string[];
+  // The agents atc offers, in menu order, and the problems that left an
+  // entry out.
+  agents: readonly AgentEntry[];
+  agentErrors: readonly string[];
+
+  // The old agent keys a file without `agents` sets, in file order. Empty
+  // for a file that uses `agents` or sets none of them.
+  legacyAgentKeys: readonly string[];
+
+  // The agent a spawn without one runs.
+  defaultAgent: AgentID;
   dirs: DirsConfig;
   workspaces: WorkspacesConfig;
-  gateways: GatewayConfig[];
-
-  // The problems that kept a gateway with auth out of the gateways.
-  gatewayErrors: readonly string[];
 
-  // The credential references a gateway's auth selects from, by profile
+  // The credential references an agent's auth selects from, by profile
   // name, and the problems that kept a profile out.
   authProfiles: ReadonlyMap<string, AuthProfile>;
   authProfileErrors: readonly string[];
@@ -87,14 +85,20 @@ interface LeaderKey {
 }
 
 const DEFAULTS: Config = {
-  claudeBin: 'claude',
-  claudeArgs: [],
-  claudeAuth: null,
-  claudeAuthErrors: [],
-  grokBin: 'grok',
-  grokArgs: [],
-  codexBin: 'codex',
-  codexArgs: [],
+  agents: [
+    {
+      id: 'claude',
+      kind: 'claude',
+      label: 'Claude',
+      mark: 'c',
+      bin: 'claude',
+      args: [],
+      env: {},
+    },
+  ],
+  agentErrors: [],
+  legacyAgentKeys: [],
+  defaultAgent: 'claude',
   dirs: { roots: [] },
   workspaces: {
     githubOwner: null,
@@ -103,8 +107,6 @@ const DEFAULTS: Config = {
     root: null,
     targetRoots: new Map(),
   },
-  gateways: [],
-  gatewayErrors: [],
   authProfiles: new Map(),
   authProfileErrors: [],
   hooks: {},
@@ -139,6 +141,7 @@ export const daemonRecordFile = join(stateDir, 'daemon.json');
 // field parses to undefined rather than failing the file, so a bad config
 // falls back to a default instead of refusing to start atc.
 const CONFIG_SCHEMA = z.object({
+  agents: z.unknown().optional(),
   claudeBin: buildOptionalString(),
   claudeArgs: buildOptionalStringArray(),
   claudeAuth: z.unknown().optional(),
@@ -237,16 +240,17 @@ function tryWriteDefaultConfig(file: string): void {
 }
 
 /**
- * The config.json text a first run writes. It leaves out the targets and
- * principals, so the file holds the one implicit `local` target and no
+ * The config.json text a first run writes: the `claude` agent alone. It
+ * leaves out the targets and principals, so the file holds the one implicit `local` target and no
  * principals until the user sets their own, no auth profiles, and the
  * errors a parse reports, which belong to no file.
  */
 export function renderDefaultConfig(): string {
   const {
-    claudeAuth: _claudeAuth,
-    claudeAuthErrors: _claudeAuthErrors,
-    gatewayErrors: _gatewayErrors,
+    agents: _agents,
+    agentErrors: _agentErrors,
+    legacyAgentKeys: _legacyAgentKeys,
+    defaultAgent: _defaultAgent,
     authProfiles: _authProfiles,
     authProfileErrors: _authProfileErrors,
     targets: _targets,
@@ -264,7 +268,11 @@ export function renderDefaultConfig(): string {
   const { targetRoots, ...rest } = workspaces;
 
   return `${JSON.stringify(
-    { ...written, workspaces: { ...rest, targets: Object.fromEntries(targetRoots) } },
+    {
+      agents: { claude: {} },
+      ...written,
+      workspaces: { ...rest, targets: Object.fromEntries(targetRoots) },
+    },
     null,
     2,
   )}\n`;
@@ -296,23 +304,31 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
     );
   }
 
-  const claudeBin = parsed.data.claudeBin ?? DEFAULTS.claudeBin;
-  const claudeArgs = parsed.data.claudeArgs ?? DEFAULTS.claudeArgs;
-  const grokBin = parsed.data.grokBin ?? DEFAULTS.grokBin;
-  const grokArgs = parsed.data.grokArgs ?? DEFAULTS.grokArgs;
-  const codexBin = parsed.data.codexBin ?? DEFAULTS.codexBin;
-  const codexArgs = parsed.data.codexArgs ?? DEFAULTS.codexArgs;
+  const present = Object.keys(raw).filter((key) => LEGACY_AGENT_KEYS.includes(key));
+
+  if (Object.hasOwn(raw, 'agents') && present.length > 0) {
+    return buildUnusableConfig('config_malformed', file, formatMixedAgentKeys(present));
+  }
+
   const dirs = { roots: collectDirRoots(parsed.data.dirs) };
   const workspaces = collectWorkspacesConfig(parsed.data.workspaces);
   const authProfiles = collectAuthProfiles(parsed.data.authProfiles);
-  const claudeAuth = collectClaudeAuth(parsed.data.claudeAuth, authProfiles.profiles);
 
-  const gateways = collectGateways(
-    parsed.data.gateways,
-    claudeBin,
-    claudeArgs,
-    authProfiles.profiles,
-  );
+  const registry = Object.hasOwn(raw, 'agents')
+    ? collectAgents(parsed.data.agents, authProfiles.profiles)
+    : collectLegacyAgents(
+        {
+          claudeBin: parsed.data.claudeBin ?? 'claude',
+          claudeArgs: parsed.data.claudeArgs ?? [],
+          claudeAuth: parsed.data.claudeAuth,
+          grokBin: parsed.data.grokBin ?? 'grok',
+          grokArgs: parsed.data.grokArgs ?? [],
+          codexBin: parsed.data.codexBin ?? 'codex',
+          codexArgs: parsed.data.codexArgs ?? [],
+          gateways: parsed.data.gateways,
+        },
+        authProfiles.profiles,
+      );
 
   const hooks = collectHooks(parsed.data.hooks);
   const targets = collectTargets(parsed.data.targets, parsed.data.defaultTarget);
@@ -322,18 +338,12 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
     (parsed.data.leader === undefined ? null : decodeLeader(parsed.data.leader)) ?? DEFAULTS.leader;
 
   return {
-    claudeBin,
-    claudeArgs,
-    claudeAuth: claudeAuth.auth,
-    claudeAuthErrors: claudeAuth.errors,
-    grokBin,
-    grokArgs,
-    codexBin,
-    codexArgs,
+    agents: registry.agents,
+    agentErrors: registry.errors,
+    legacyAgentKeys: present,
+    defaultAgent: pickDefaultAgent(registry.agents),
     dirs,
     workspaces: workspaces.workspaces,
-    gateways: gateways.gateways,
-    gatewayErrors: gateways.errors,
     authProfiles: authProfiles.profiles,
     authProfileErrors: authProfiles.errors,
     hooks,

package/src/shared/format-mixed-agent-keys.ts

@@ -0,0 +1,10 @@
+/**
+ * The problem a config.json that sets both `agents` and old agent keys
+ * reports: the keys, as "a", "a and b", or "a, b and c", and where they go.
+ */
+export function formatMixedAgentKeys(keys: readonly string[]): string {
+  const last = keys.at(-1);
+  const list = keys.length < 2 ? keys.join('') : `${keys.slice(0, -1).join(', ')} and ${last}`;
+
+  return `${list} cannot be set together with agents; move them into agents or run 'atc config migrate'`;
+}

package/src/shared/is-subscription-override-variable.ts

@@ -0,0 +1,14 @@
+import { isBrokerVariable } from './is-broker-variable';
+import { OUTRANKING_VARIABLES } from './outranking-variables';
+
+/**
+ * Whether a variable set in a Claude session's environment would override
+ * the subscription sign-in or route the CLI around impd's broker: an
+ * outranking credential, endpoint, or provider selector, the subscription
+ * token variable itself, or a proxy or CA variable.
+ */
+export function isSubscriptionOverrideVariable(key: string): boolean {
+  return OUTRANKING_VARIABLES.has(key) || key === OAUTH_VARIABLE || isBrokerVariable(key);
+}
+
+const OAUTH_VARIABLE = 'CLAUDE_CODE_OAUTH_TOKEN';

package/src/shared/legacy-agent-keys.ts

@@ -0,0 +1,15 @@
+/**
+ * The config.json keys of the old agent shape, which `agents` replaces: the
+ * harness binaries and arguments, the Claude subscription auth, and the
+ * gateway map.
+ */
+export const LEGACY_AGENT_KEYS: readonly string[] = [
+  'claudeBin',
+  'claudeArgs',
+  'claudeAuth',
+  'grokBin',
+  'grokArgs',
+  'codexBin',
+  'codexArgs',
+  'gateways',
+];

package/src/shared/outranking-variables.ts

@@ -0,0 +1,17 @@
+/**
+ * The variables that keep Claude Code from sending the subscription token
+ * to the Anthropic API: a credential it takes ahead of that token, another
+ * endpoint, or a cloud provider it signs in to instead.
+ */
+export const OUTRANKING_VARIABLES: ReadonlySet<string> = new Set([
+  'ANTHROPIC_AUTH_TOKEN',
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_BASE_URL',
+  'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
+  'CLAUDE_CODE_USE_FOUNDRY',
+  'CLAUDE_CODE_USE_MANTLE',
+  'CLAUDE_CODE_USE_ANTHROPIC_AWS',
+  'CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD',
+  'CLAUDE_CODE_USE_GATEWAY',
+]);

package/src/shared/pick-default-agent.ts

@@ -0,0 +1,12 @@
+import type { AgentID } from './agent-id';
+import type { AgentEntry } from './collect-agents';
+
+/**
+ * The agent a spawn without one runs: `claude` when the registry holds an
+ * entry with that id, else the first entry. An empty registry still reports
+ * `claude`, so a spawn is refused for want of an adapter rather than for an
+ * unknown default.
+ */
+export function pickDefaultAgent(agents: readonly AgentEntry[]): AgentID {
+  return agents.find((entry) => entry.id === 'claude')?.id ?? agents[0]?.id ?? 'claude';
+}