@zgeoff/atc 2.36.0 → 2.37.0

package/src/build-migrated-config.ts

@@ -0,0 +1,184 @@
+import type { AgentEntry } from './shared/collect-agents';
+import { parseConfig } from './shared/config';
+import { formatJSONKind } from './shared/format-json-kind';
+import { formatMixedAgentKeys } from './shared/format-mixed-agent-keys';
+import { LEGACY_AGENT_KEYS } from './shared/legacy-agent-keys';
+import { isRecord } from './shared/report';
+
+/**
+ * What `atc config migrate` makes of a config.json's decoded value: the file
+ * rewritten around `agents` with a note per gateway it could not carry over,
+ * a file that needs no change, or a file it cannot migrate.
+ */
+type MigratedConfig =
+  | { readonly kind: 'migrated'; readonly text: string; readonly notes: readonly string[] }
+  | { readonly kind: 'current' }
+  | { readonly kind: 'unusable'; readonly detail: string };
+
+/**
+ * Rewrites a config.json that uses the old agent keys so it holds the same
+ * agents under `agents`. The old keys are removed and `agents` takes the
+ * place of the first of them, or the end of the file when it sets none. Each
+ * entry holds only the fields that differ from a default. Values are copied
+ * and never reported, so a note names a key and a reason only.
+ */
+export function buildMigratedConfig(raw: unknown): MigratedConfig {
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return {
+      kind: 'unusable',
+      detail: `the root is ${formatJSONKind(raw)}, not an object`,
+    };
+  }
+
+  const present = Object.keys(raw).filter((key) => LEGACY_AGENT_KEYS.includes(key));
+
+  if (Object.hasOwn(raw, 'agents')) {
+    return present.length === 0
+      ? { kind: 'current' }
+      : { kind: 'unusable', detail: formatMixedAgentKeys(present) };
+  }
+
+  const config = parseConfig(raw);
+  const agents: Record<string, unknown> = {};
+
+  for (const entry of config.agents) {
+    agents[entry.id] = renderAgentEntry(entry);
+  }
+
+  const migrated: Record<string, unknown> = {};
+  let placed = false;
+
+  for (const [key, value] of Object.entries(raw)) {
+    if (!LEGACY_AGENT_KEYS.includes(key)) {
+      migrated[key] = value;
+    } else if (!placed) {
+      migrated['agents'] = agents;
+      placed = true;
+    }
+  }
+
+  if (!placed) {
+    migrated['agents'] = agents;
+  }
+
+  return {
+    kind: 'migrated',
+    text: `${JSON.stringify(migrated, null, 2)}\n`,
+    notes: collectDroppedGateways(raw['gateways'], config.agents, config.agentErrors),
+  };
+}
+
+// The fields of an entry that differ from the defaults the `agents` parser
+// applies, so a migrated entry reads as short as one written by hand.
+function renderAgentEntry(entry: AgentEntry): Record<string, unknown> {
+  const rendered: Record<string, unknown> = {};
+
+  if (entry.baseURL !== undefined) {
+    rendered['kind'] = 'claude';
+  }
+
+  if (entry.label !== entry.id && entry.baseURL !== undefined) {
+    rendered['label'] = entry.label;
+  }
+
+  if (
+    entry.baseURL !== undefined &&
+    entry.mark !== String.fromCodePoint(entry.id.codePointAt(0) ?? 0)
+  ) {
+    rendered['mark'] = entry.mark;
+  }
+
+  if (entry.bin !== entry.kind) {
+    rendered['bin'] = entry.bin;
+  }
+
+  if (entry.args.length > 0) {
+    rendered['args'] = entry.args;
+  }
+
+  if (entry.baseURL !== undefined) {
+    rendered['baseURL'] = entry.baseURL;
+  }
+
+  if (entry.apiKeyHelper !== undefined) {
+    rendered['apiKeyHelper'] = entry.apiKeyHelper;
+  }
+
+  if (Object.keys(entry.env).length > 0) {
+    rendered['env'] = entry.env;
+  }
+
+  if (entry.settings !== undefined) {
+    rendered['settings'] = entry.settings;
+  }
+
+  if (entry.auth !== undefined) {
+    rendered['auth'] =
+      Object.keys(entry.auth.placeholderEnv).length > 0
+        ? { profiles: entry.auth.profiles, placeholderEnv: entry.auth.placeholderEnv }
+        : { profiles: entry.auth.profiles };
+  }
+
+  return rendered;
+}
+
+// One note per gateway the old parse left out, with the reason.
+function collectDroppedGateways(
+  raw: unknown,
+  agents: readonly AgentEntry[],
+  errors: readonly string[],
+): string[] {
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return [];
+  }
+
+  // The three built-in agents come first, so the gateways follow them.
+  const kept = new Set(agents.slice(BUILT_IN_COUNT).map((entry) => entry.id));
+
+  const notes: string[] = [];
+
+  for (const [id, entry] of Object.entries(raw)) {
+    if (!isDropped(id, kept)) {
+      continue;
+    }
+
+    notes.push(
+      `atc config migrate: gateways.${id} is left out: ${findDropReason(id, entry, errors)}`,
+    );
+  }
+
+  return notes;
+}
+
+const BUILT_IN_COUNT = 3;
+
+function isDropped(id: string, kept: ReadonlySet<string>): boolean {
+  return id === '__proto__' || !kept.has(id);
+}
+
+function findDropReason(id: string, entry: unknown, errors: readonly string[]): string {
+  if (id === '') {
+    return 'its id is empty';
+  }
+
+  if (id === '__proto__') {
+    return 'its id cannot be used';
+  }
+
+  if (id === 'claude' || id === 'grok' || id === 'codex') {
+    return `its id is the built-in agent ${id}`;
+  }
+
+  const baseURL = isRecord(entry) ? entry['baseURL'] : undefined;
+
+  if (typeof baseURL !== 'string' || baseURL === '') {
+    return 'it has no baseURL';
+  }
+
+  const prefix = `gateways.${id}: `;
+  const problems = errors.filter((error) => error.startsWith(prefix));
+
+  return problems.length > 0
+    ? problems.map((problem) => problem.slice(prefix.length)).join('; ')
+    : 'its entry could not be read';
+}

package/src/cli.ts

@@ -178,6 +178,44 @@ const main = defineCommand({
           await grants.runGrants(ctx.args.revoke ?? null);
         },
       }),
+    config: () =>
+      defineCommand({
+        meta: { name: 'config', description: "Work on atc's config.json" },
+        subCommands: {
+          migrate: () =>
+            defineCommand({
+              meta: {
+                name: 'migrate',
+                description:
+                  'Move the old agent keys of config.json into agents: print the result, or rewrite the file with --write',
+              },
+              args: {
+                write: {
+                  type: 'boolean',
+                  default: false,
+                  description: 'Back the file up beside itself, then rewrite it in place',
+                },
+                file: {
+                  type: 'string',
+                  description: 'The config file to migrate (default ~/.config/atc/config.json)',
+                },
+              },
+              async run(ctx) {
+                const migrate = await import('./run-config-migrate');
+                const config = await import('./shared/config');
+
+                const code = migrate.runConfigMigrate(
+                  ctx.args.file ?? config.configFile,
+                  ctx.args.write,
+                );
+
+                if (code !== 0) {
+                  process.exit(code);
+                }
+              },
+            }),
+        },
+      }),
     daemon: () =>
       defineCommand({
         meta: {
@@ -358,10 +396,7 @@ async function runDaemon(listenArg: string | null, tokenFile: string | null): Pr
 
   const daemon = await import('./daemon/daemon');
   const config = await import('./shared/config');
-  const claude = await import('./agents/claude-adapter');
-  const grok = await import('./agents/grok-adapter');
-  const codex = await import('./agents/codex-adapter');
-  const gateway = await import('./agents/gateway-adapter');
+  const adapterBuilder = await import('./agents/build-agent-adapters');
   const headless = await import('./agents/start-claude-headless-run');
   const targets = await import('./daemon/build-execution-targets');
   const sourceOrder = await import('./sources/build-sources');
@@ -389,12 +424,17 @@ async function runDaemon(listenArg: string | null, tokenFile: string | null): Pr
     ...cfg.principalErrors,
     ...cfg.workspaceErrors,
     ...cfg.authProfileErrors,
-    ...cfg.claudeAuthErrors,
-    ...cfg.gatewayErrors,
+    ...cfg.agentErrors,
   ]) {
     console.error(`atc daemon: config: ${problem}`);
   }
 
+  if (cfg.legacyAgentKeys.length > 0) {
+    console.error(
+      `atc daemon: config: config.json uses the old agent keys (${cfg.legacyAgentKeys.join(', ')}); run 'atc config migrate' to move them into agents`,
+    );
+  }
+
   const sources = sourceOrder.buildSources(
     builtinSources.collectBuiltinSources({
       roots: cfg.dirs.roots,
@@ -423,15 +463,7 @@ async function runDaemon(listenArg: string | null, tokenFile: string | null): Pr
   // How long a started session may go without a tap before a message
   // to it is refused. Tests pin it to 0 to reach the refusal at once.
   const graceOverride = Number(process.env['ATC_TAP_GRACE_MS']);
-
-  const claudeAdapter = new claude.ClaudeAdapter(cfg, headless.startClaudeHeadlessRun);
-  const grokAdapter = new grok.GrokAdapter(cfg);
-  const codexAdapter = new codex.CodexAdapter(cfg);
-
-  const gatewayAdapters = cfg.gateways.map(
-    (entry) => new gateway.GatewayAdapter(entry, cfg, headless.startClaudeHeadlessRun),
-  );
-
+  const adapters = adapterBuilder.buildAgentAdapters(cfg, headless.startClaudeHeadlessRun);
   let handle: Awaited<ReturnType<typeof daemon.startDaemon>>;
 
   try {
@@ -440,8 +472,8 @@ async function runDaemon(listenArg: string | null, tokenFile: string | null): Pr
       reporterSocketPath: config.socketPath,
       eventsSocketPath: config.eventsSocketPath,
       build: getBuild(),
-      adapter: claudeAdapter,
-      adapters: [claudeAdapter, grokAdapter, codexAdapter, ...gatewayAdapters],
+      adapters,
+      defaultAgent: cfg.defaultAgent,
       dbPath: config.dbFile,
       legacyFleetPath: config.legacyFleetFile,
       pidPath: config.daemonPidFile,

package/src/client/collect-agent-picks.ts

@@ -18,14 +18,7 @@ export function collectAgentPicks(config: Config): AgentPick[] {
   // rather than left to the snapshot Bun.which defaults to.
   const opts = { PATH: process.env['PATH'] ?? '' };
 
-  const candidates: readonly (AgentPick & { readonly bin: string })[] = [
-    { agent: 'claude', label: 'Claude', bin: config.claudeBin },
-    { agent: 'grok', label: 'Grok', bin: config.grokBin },
-    { agent: 'codex', label: 'Codex', bin: config.codexBin },
-    ...config.gateways.map((g) => ({ agent: g.id, label: g.label, bin: g.bin })),
-  ];
-
-  return candidates
-    .filter((c) => Bun.which(c.bin, opts) !== null)
-    .map((c) => ({ agent: c.agent, label: c.label }));
+  return config.agents
+    .filter((entry) => Bun.which(entry.bin, opts) !== null)
+    .map((entry) => ({ agent: entry.id, label: entry.label }));
 }

package/src/client/index.ts

@@ -41,7 +41,7 @@ const doneAt = new Map<string, number>();
 
 let focusedID: string | null = null;
 let fleetCount = 0;
-let lastUsedAgent: AgentID = 'claude';
+let lastUsedAgent: AgentID = loadConfig().defaultAgent;
 
 // The readable harness label and tier-alias map per agent: the config alone
 // until the daemon's `agents.list` answer arrives and re-resolves them

package/src/client/resolve-agent-metadata.ts

@@ -12,12 +12,6 @@ export interface AgentMetadata {
   readonly models: Readonly<Record<AgentID, Readonly<Record<string, string>>>>;
 }
 
-const BUILT_IN_LABELS: Readonly<Record<AgentID, string>> = {
-  claude: 'Claude',
-  grok: 'Grok',
-  codex: 'Codex',
-};
-
 /**
  * The labels and model aliases the overlay draws with, resolved from the
  * config a client reads at start and the daemon's `agents.list` answer once
@@ -26,12 +20,12 @@ const BUILT_IN_LABELS: Readonly<Record<AgentID, string>> = {
  * the window before the answer lands.
  */
 export function resolveAgentMetadata(config: Config, listed: unknown): AgentMetadata {
-  const labels: Record<AgentID, string> = { ...BUILT_IN_LABELS };
+  const labels: Record<AgentID, string> = {};
   const models: Record<AgentID, Readonly<Record<string, string>>> = {};
 
-  for (const gateway of config.gateways) {
-    if (isSafeKey(gateway.id)) {
-      labels[gateway.id] = gateway.label;
+  for (const entry of config.agents) {
+    if (isSafeKey(entry.id)) {
+      labels[entry.id] = entry.label;
     }
   }
 

package/src/client/spawn-picker.ts

@@ -434,8 +434,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
       let hint = '↑↓ move · ⏎ select · esc cancel';
 
       if (this.picks.length === 0) {
-        hint =
-          'no agent CLI found — set claudeBin, grokBin, or codexBin in config.json · esc cancel';
+        hint = 'no agent CLI found — set agents in config.json · esc cancel';
       } else if (this.sourcesPending) {
         hint = 'reading targets and sources… · esc cancel';
       }

package/src/daemon/build-auth-binding.ts

@@ -1,7 +1,8 @@
 import { createHash } from 'node:crypto';
 import type { AgentID } from '../shared/agent-id';
+import type { GatewayAuth } from '../shared/check-gateway-auth';
 import type { AuthProfile } from '../shared/collect-auth-profiles';
-import type { GatewayAuth, GatewayConfig } from '../shared/collect-gateways';
+import type { GatewayConfig } from '../shared/collect-gateways';
 import { resolveAuthProfiles } from '../shared/resolve-auth-profiles';
 import type { AuthProfileProblem, ResolvedAuthSecret } from '../shared/resolve-auth-profiles';
 import { sortJSONKeys } from '../shared/sort-json-keys';

package/src/daemon/daemon-connection.ts

@@ -941,7 +941,7 @@ export class DaemonConnection {
       // The target goes first: a config or target problem is the cause a
       // spawn reports, ahead of any agent check that problem can skew.
       const target = ctx.resolveSpawnTarget(data.target);
-      const agent: AgentID = data.agent ?? 'claude';
+      const agent: AgentID = data.agent ?? ctx.collectAgents().spawnDefaults.agent;
       const adapter = ctx.findAdapter(agent);
       const entry = ctx.collectAgents().agents.find((candidate) => candidate.id === agent);
 

package/src/daemon/daemon.ts

@@ -11,6 +11,7 @@ import { MAX_CHUNK, PROTOCOL_V } from '../protocol/protocol';
 import type { EventMsg } from '../protocol/protocol';
 import type { SpawnWorkspaceSource } from '../protocol/request-param-schemas';
 import type { SessionState } from '../protocol/session-state';
+import type { AgentID } from '../shared/agent-id';
 import type { HooksConfig } from '../shared/collect-hooks';
 import type { TargetConfigError } from '../shared/collect-targets';
 import type { InvalidGitTransports } from '../shared/collect-workspaces-config';
@@ -101,13 +102,17 @@ export interface DaemonOptions {
 
   // Build string sent in the handshake and in mismatch errors, e.g. "atc/0.1.0".
   readonly build: string;
-  readonly adapter: AgentAdapter;
+  readonly adapter?: AgentAdapter | null;
 
   // Adapters registered over and above the default one, each keyed by the id
   // it declares. Lookup never falls back across ids: a grok session with no
   // grok adapter is unsupported, not a Claude spawn.
   readonly adapters?: readonly AgentAdapter[];
 
+  // The agent a spawn without one runs, reported in `agents.list`'s spawn
+  // defaults; `claude` when unset.
+  readonly defaultAgent?: AgentID;
+
   // Where sessions run, in config order; one `local` target on the local
   // pseudo-terminal provider when unset. A spawn without a target runs on
   // the default one: `local` when unset and the targets hold it, and none
@@ -888,7 +893,11 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     if (
       before !== undefined &&
       runtime !== undefined &&
-      !isOwnHookEvent(e.agent, before.agent, runtime.hasAgentHookLines)
+      !isOwnHookEvent(
+        e.agent,
+        mgr.findAdapter(before.agent)?.hookAgent ?? before.agent,
+        runtime.hasAgentHookLines,
+      )
     ) {
       return;
     }
@@ -1412,7 +1421,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         targets.some((target) => target.provider?.brokerAuth !== undefined),
       ),
       targets: buildTargetList(targets, defaultTarget),
-      spawnDefaults: { agent: 'claude', target: defaultTarget },
+      spawnDefaults: { agent: opts.defaultAgent ?? 'claude', target: defaultTarget },
       configRevision,
       targetErrors,
       sources: sources.map((source) => ({

package/src/daemon/sessions.ts

@@ -383,7 +383,7 @@ export class SessionManager {
   private nextBridgeEpoch = 1;
 
   constructor(
-    fallback: AgentAdapter,
+    fallback: AgentAdapter | null | undefined,
     store: FleetStore,
     statusPath: string | undefined = statusFile,
     adapters: readonly AgentAdapter[] = [],
@@ -400,7 +400,13 @@ export class SessionManager {
   ) {
     // Each adapter names the id it answers to, so a registry key can never
     // disagree with the adapter behind it. A later one wins the id.
-    this.adapters = Object.fromEntries([fallback, ...adapters].map((a) => [a.id, a]));
+    this.adapters = Object.fromEntries(
+      [...(fallback === null || fallback === undefined ? [] : [fallback]), ...adapters].map((a) => [
+        a.id,
+        a,
+      ]),
+    );
+
     this.hasScreenDetector = Object.values(this.adapters).some((a) => a.screenDetector !== null);
     this.store = store;
     this.statusPath = statusPath ?? statusFile;

package/src/mcp/build-spawn-descriptions.ts

@@ -29,8 +29,8 @@ export function buildSpawnDescriptions(
       : ` When this tool list was built, the host registered: ${formatRoster(agents)}.`;
 
   return {
-    tool: `Spawn a new session in a directory. Optional agent is a registered agent id; omitted agent is always Claude, never the TUI last-used value.${roster} atc_agents_list returns the current agents, whether each is installed, and the model and effort each takes. An unregistered agent, a registered agent that is not installed, and a model or effort the agent does not take are refused before anything spawns. Called from inside an atc session, the new session is a sub-session of the caller unless detached is true. Returns the new session descriptor. Give it a prompt to start it working immediately.`,
-    agent: `Registered agent id to spawn; defaults to claude.${roster} atc_agents_list returns the current list.`,
+    tool: `Spawn a new session in a directory. Optional agent is a registered agent id; omitted agent is the host's default agent (claude when it is registered, else the first registered agent), never the TUI last-used value.${roster} atc_agents_list returns the current agents, whether each is installed, and the model and effort each takes. An unregistered agent, a registered agent that is not installed, and a model or effort the agent does not take are refused before anything spawns. Called from inside an atc session, the new session is a sub-session of the caller unless detached is true. Returns the new session descriptor. Give it a prompt to start it working immediately.`,
+    agent: `Registered agent id to spawn; defaults to claude when it is registered, else the first registered agent.${roster} atc_agents_list returns the current list.`,
   };
 }
 

package/src/run-config-migrate.ts

@@ -0,0 +1,85 @@
+import { copyFileSync, readFileSync, writeFileSync } from 'node:fs';
+import { buildMigratedConfig } from './build-migrated-config';
+
+/**
+ * Runs `atc config migrate`: prints the config.json rewritten around
+ * `agents`, or with `write` copies the file to a timestamped backup beside it
+ * and rewrites it in place. Returns the exit code. Notes and problems go to
+ * stderr and name keys and paths, never values.
+ */
+export function runConfigMigrate(file: string, write: boolean): number {
+  let text: string;
+
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch {
+    console.error(`atc config migrate: ${file} cannot be read`);
+
+    return 1;
+  }
+
+  let raw: unknown;
+
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    console.error(`atc config migrate: ${file} is not valid JSON`);
+
+    return 1;
+  }
+
+  const result = buildMigratedConfig(raw);
+
+  if (result.kind === 'unusable') {
+    console.error(`atc config migrate: ${file}: ${result.detail}`);
+
+    return 1;
+  }
+
+  if (result.kind === 'current') {
+    console.log('config.json already uses agents; nothing to migrate');
+
+    return 0;
+  }
+
+  for (const note of result.notes) {
+    console.error(note);
+  }
+
+  if (!write) {
+    process.stdout.write(result.text);
+
+    return 0;
+  }
+
+  const backup = `${file}.bak-${formatBackupStamp(Date.now())}`;
+
+  try {
+    copyFileSync(file, backup);
+  } catch {
+    console.error(`atc config migrate: ${backup} cannot be written; ${file} is unchanged`);
+
+    return 1;
+  }
+
+  try {
+    writeFileSync(file, result.text);
+  } catch {
+    console.error(`atc config migrate: ${file} cannot be written; the backup is at ${backup}`);
+
+    return 1;
+  }
+
+  console.log(`backup: ${backup}`);
+  console.log(`wrote: ${file}`);
+
+  return 0;
+}
+
+// A UTC time as `20261006T152200Z`.
+function formatBackupStamp(time: number): string {
+  return new Date(time)
+    .toISOString()
+    .replaceAll(/[-:]/gu, '')
+    .replace(/\.\d+Z$/u, 'Z');
+}