@zgeoff/atc 2.40.0 → 2.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.40.0",
+  "version": "2.41.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/agents/agent-adapter.ts

@@ -44,12 +44,17 @@ export interface SpawnPlan {
  * files unpack into. `auth` is given when the harness takes its credential
  * from impd's broker: the revision of the host's runtime auth binding it
  * launches under, which keys any settings the agent writes for it, and the
- * placeholder variables the harness holds in place of a credential.
+ * placeholder variables the harness holds in place of a credential, and
+ * the variables its auth profiles set.
  */
 export interface GuestPaths {
   readonly atc: string | null;
   readonly dir: string;
-  readonly auth?: { readonly revision: number; readonly env: Readonly<Record<string, string>> };
+  readonly auth?: {
+    readonly revision: number;
+    readonly env: Readonly<Record<string, string>>;
+    readonly profileEnv: Readonly<Record<string, string>>;
+  };
 }
 
 /**

package/src/agents/claude-adapter.ts

@@ -290,7 +290,11 @@ export class ClaudeAdapter implements AgentAdapter {
     const padding = typeof userSettings === 'string' ? findStatuslinePadding(userSettings) : 0;
 
     const settings = buildHookSettings(
-      this.buildSettingsProfile({ ...auth.env, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1' }),
+      this.buildSettingsProfile({
+        ...auth.profileEnv,
+        ...auth.env,
+        CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+      }),
       padding,
       argv,
     );
@@ -312,7 +316,7 @@ export class ClaudeAdapter implements AgentAdapter {
         ),
         ...Object.fromEntries(bridge),
       },
-      env: { ...launch.env, ...auth.env },
+      env: { ...launch.env, ...auth.profileEnv, ...auth.env },
     };
   }
 

package/src/agents/gateway-adapter.ts

@@ -224,6 +224,7 @@ export class GatewayAdapter implements AgentAdapter {
         env: {
           ...this.gateway.env,
           ANTHROPIC_BASE_URL: this.gateway.baseURL,
+          ...guest.auth.profileEnv,
           ...guest.auth.env,
           CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
         },
@@ -253,7 +254,7 @@ export class GatewayAdapter implements AgentAdapter {
         ...buildClaudeConfigSeed(null),
         ...Object.fromEntries(bridge),
       },
-      env: { ...launch.env, ...guest.auth.env },
+      env: { ...launch.env, ...guest.auth.profileEnv, ...guest.auth.env },
     };
   }
 
@@ -352,19 +353,31 @@ export class GatewayAdapter implements AgentAdapter {
   }
 
   // The Claude CLI sends ANTHROPIC_AUTH_TOKEN as a bearer authorization
-  // header, the one pairing atc binds, so the placeholders must be that
-  // variable alone, holding the placeholder, for a profile whose rule on
-  // the base URL's host sets that header. Any other variable would put the
-  // placeholder in a header the broker never fills.
+  // header, the one pairing atc binds, so the placeholders must include that
+  // variable, holding the placeholder, for a profile whose rule on the base
+  // URL's host sets that header. Any other variable passes through to the
+  // session for a tool in it, whose own host a selected profile covers,
+  // except a variable the CLI reads as its own credential, which would
+  // compete with the bearer variable and put the placeholder in a header
+  // the broker never fills, and the variable that names the session's
+  // Claude config folder, which atc sets itself.
   private findPlaceholderRefusal(
     env: Readonly<Record<string, string>>,
     profiles: readonly string[],
   ): DaemonError | null {
     const keys = Object.keys(env);
 
-    if (keys.length !== 1 || keys[0] !== BEARER_VARIABLE) {
+    if (!keys.includes(BEARER_VARIABLE)) {
       return this.buildPlaceholderRefusal(
-        `needs ${BEARER_VARIABLE} as its only placeholder variable, which the broker fills as a bearer authorization header; it has ${keys.length === 0 ? 'none' : keys.join(', ')}`,
+        `needs ${BEARER_VARIABLE} among its placeholder variables, which the broker fills as a bearer authorization header; it has ${keys.length === 0 ? 'none' : keys.join(', ')}`,
+      );
+    }
+
+    const competing = keys.find((key) => COMPETING_CREDENTIAL_VARIABLES.has(key));
+
+    if (competing !== undefined) {
+      return this.buildPlaceholderRefusal(
+        `cannot use ${competing} as a placeholder variable, since the Claude CLI reads it as its own credential or config folder beside ${BEARER_VARIABLE}`,
       );
     }
 
@@ -444,6 +457,15 @@ export class GatewayAdapter implements AgentAdapter {
 const BEARER_VARIABLE = 'ANTHROPIC_AUTH_TOKEN';
 const PLACEHOLDER = 'imp-broker-placeholder';
 
+// Variables the Claude CLI reads as its own credential beside the bearer
+// variable, plus the one that points it at the session's config folder,
+// whose launch value a placeholder would overwrite.
+const COMPETING_CREDENTIAL_VARIABLES: ReadonlySet<string> = new Set([
+  'ANTHROPIC_API_KEY',
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'CLAUDE_CONFIG_DIR',
+]);
+
 // The Claude CLI's mode that asks a person before each action.
 const MANUAL_PERMISSION_MODE = 'default';
 

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

@@ -11,8 +11,9 @@ import { sortJSONKeys } from '../shared/sort-json-keys';
  * What a session's runtime is bound to through impd's broker: every
  * profile its gateway's selection reaches, the secrets they need impd to
  * hold with exactly these rules, the placeholder variables in place of a
- * credential, and the endpoint. `hash` covers the secrets and their rules
- * alone, so a change to a profile the binding does not reach leaves it as
+ * credential, the variables the profiles set, and the endpoint. `hash`
+ * covers the secrets and their rules, and the profile variables when there
+ * are any, so a change to a profile the binding does not reach leaves it as
  * it was, and a change to one it reaches gives another hash.
  */
 export interface AuthBinding {
@@ -21,6 +22,7 @@ export interface AuthBinding {
   readonly profiles: readonly string[];
   readonly secrets: readonly ResolvedAuthSecret[];
   readonly placeholderEnv: Readonly<Record<string, string>>;
+  readonly profileEnv: Readonly<Record<string, string>>;
   readonly hash: string;
 }
 
@@ -29,7 +31,7 @@ type AuthGateway = Pick<GatewayConfig, 'id' | 'baseURL'> & { readonly auth: Gate
 /**
  * Plans the binding a gateway's auth asks for against the current auth
  * profiles, or the problem that refuses it. The hash is the SHA-256 of the
- * resolved secrets as canonical JSON, with each list sorted, so the order
+ * resolved secrets (and profile variables, when set) as canonical JSON, with each list sorted, so the order
  * of the selection or of the config never changes it.
  */
 export function buildAuthBinding(
@@ -43,6 +45,8 @@ export function buildAuthBinding(
   }
 
   const secrets = resolution.resolved.secrets;
+  const profileEnv = resolution.resolved.env;
+  const hashed = Object.keys(profileEnv).length === 0 ? { secrets } : { secrets, profileEnv };
 
   return {
     binding: {
@@ -51,8 +55,9 @@ export function buildAuthBinding(
       profiles: resolution.resolved.profiles,
       secrets,
       placeholderEnv: gateway.auth.placeholderEnv,
+      profileEnv,
       hash: createHash('sha256')
-        .update(JSON.stringify(sortJSONKeys({ secrets })))
+        .update(JSON.stringify(sortJSONKeys(hashed)))
         .digest('hex'),
     },
   };

package/src/daemon/sessions.ts

@@ -2014,7 +2014,7 @@ export class SessionManager {
         : {
             atc: guest.atc,
             dir,
-            auth: await this.planGuestAuth(hostKey, auth.mode, auth.binding.placeholderEnv),
+            auth: await this.planGuestAuth(hostKey, auth.mode, auth.binding),
           };
 
     const plan =
@@ -2100,11 +2100,15 @@ export class SessionManager {
   private async planGuestAuth(
     hostKey: SessionID,
     mode: HarnessAuthSetup['mode'],
-    placeholderEnv: Readonly<Record<string, string>>,
+    binding: Pick<AuthBinding, 'placeholderEnv' | 'profileEnv'>,
   ): Promise<NonNullable<GuestPaths['auth']>> {
     const held = mode === 'create' ? null : await this.requireAuthBinder().findBinding(hostKey);
 
-    return { revision: held?.revision ?? 1, env: placeholderEnv };
+    return {
+      revision: held?.revision ?? 1,
+      env: binding.placeholderEnv,
+      profileEnv: binding.profileEnv,
+    };
   }
 
   // Creates the binding of a host a spawn provisions, or verifies the one

package/src/shared/check-gateway-auth.ts

@@ -1,4 +1,5 @@
 import type { AuthProfile } from './collect-auth-profiles';
+import { collectProfileEnvProblems } from './collect-profile-env-problems';
 import { isBrokerVariable } from './is-broker-variable';
 import { isRecord } from './report';
 import { resolveAuthProfiles } from './resolve-auth-profiles';
@@ -75,6 +76,16 @@ export function checkGatewayAuth(
   if ('problem' in resolution) {
     problems.push(resolution.problem.message);
   } else {
+    problems.push(
+      ...collectProfileEnvProblems(
+        [
+          ['env', Object.keys(entry.env)],
+          ['settings.env', settingsEnv],
+        ],
+        resolution.resolved.envOwners,
+      ),
+    );
+
     const hostProblem = findBaseURLProblem(entry.baseURL ?? '', resolution.resolved.hosts);
 
     if (hostProblem !== null) {

package/src/shared/collect-agents.ts

@@ -4,8 +4,10 @@ import type { GatewayAuth } from './check-gateway-auth';
 import type { AuthProfile } from './collect-auth-profiles';
 import { collectClaudeAuth } from './collect-claude-auth';
 import type { ClaudeMCPServer } from './collect-claude-auth';
+import { collectProfileEnvProblems } from './collect-profile-env-problems';
 import { isSubscriptionOverrideVariable } from './is-subscription-override-variable';
 import { isRecord } from './report';
+import { resolveAuthProfiles } from './resolve-auth-profiles';
 
 /**
  * The agent CLI an entry drives, which decides the adapter behind it.
@@ -305,6 +307,10 @@ function readClaudeAuth(
 
   problems.push(...collectSubscriptionProblems(entry));
 
+  if (collected.auth !== null) {
+    problems.push(...collectEntryProfileEnvProblems(entry, collected.auth.profiles, authProfiles));
+  }
+
   if (collected.auth === null) {
     return { problems: [...collected.errors, ...problems] };
   }
@@ -320,6 +326,32 @@ function readClaudeAuth(
   };
 }
 
+// The variables a stock entry sets that its selected profiles also set.
+function collectEntryProfileEnvProblems(
+  entry: AgentEntry,
+  selected: readonly string[],
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): string[] {
+  const resolution = resolveAuthProfiles(authProfiles, selected);
+
+  if ('problem' in resolution) {
+    return [];
+  }
+
+  const settingsEnv = entry.settings?.['env'];
+
+  return collectProfileEnvProblems(
+    [
+      ['env', Object.keys(entry.env)],
+      [
+        'settings.env',
+        isRecord(settingsEnv) && !Array.isArray(settingsEnv) ? Object.keys(settingsEnv) : [],
+      ],
+    ],
+    resolution.resolved.envOwners,
+  );
+}
+
 // What a stock entry with `auth` sets that would override the subscription
 // sign-in or route the CLI around impd's broker.
 function collectSubscriptionProblems(entry: AgentEntry): string[] {

package/src/shared/collect-auth-profiles.ts

@@ -1,3 +1,5 @@
+import { isBrokerVariable } from './is-broker-variable';
+import { isSubscriptionOverrideVariable } from './is-subscription-override-variable';
 import { isRecord } from './report';
 
 /**
@@ -16,6 +18,7 @@ interface CustomAuthProfile {
   readonly host: string;
   readonly header: string;
   readonly scheme: 'bearer';
+  readonly env: Readonly<Record<string, string>>;
   readonly dependencies: readonly string[];
 }
 
@@ -23,6 +26,7 @@ interface GitHubAuthProfile {
   readonly name: string;
   readonly secret: string;
   readonly kind: 'github';
+  readonly env: Readonly<Record<string, string>>;
   readonly dependencies: readonly string[];
 }
 
@@ -112,7 +116,11 @@ function parseAuthProfile(name: string, entry: unknown): AuthProfile | string {
       return `${extra} cannot be set on a github profile, whose hosts and headers impd's github kind fixes`;
     }
 
-    return { name, secret, kind, dependencies: dependencies ?? [] };
+    if (entry['env'] !== undefined) {
+      return "env cannot be set on a github profile, whose placeholders impd's github kind sets";
+    }
+
+    return { name, secret, kind, env: {}, dependencies: dependencies ?? [] };
   }
 
   if (typeof host !== 'string' || host.length > BROKER_HOST_MAX || !BROKER_HOST.test(host)) {
@@ -131,6 +139,12 @@ function parseAuthProfile(name: string, entry: unknown): AuthProfile | string {
     return 'user pairs only with the basic scheme, which atc does not bind';
   }
 
+  const env = parseProfileEnv(entry['env'], host);
+
+  if (typeof env === 'string') {
+    return env;
+  }
+
   return {
     name,
     secret,
@@ -138,6 +152,55 @@ function parseAuthProfile(name: string, entry: unknown): AuthProfile | string {
     host,
     header,
     scheme,
+    env,
     dependencies: dependencies ?? [],
   };
 }
+
+// The value a profile's variable may hold: the placeholder the broker swaps
+// a credential in for, or the profile's own host as an https origin. No
+// other value, so a credential is never written into a profile.
+const ENV_PLACEHOLDER = 'imp-broker-placeholder';
+const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/;
+const RESERVED_ENV_PREFIXES = ['ANTHROPIC_', 'CLAUDE_', 'ATC_'];
+
+const RESERVED_ENV_NAMES: ReadonlySet<string> = new Set(['PATH', 'HOME']);
+
+function parseProfileEnv(raw: unknown, host: string): Record<string, string> | string {
+  if (raw === undefined) {
+    return {};
+  }
+
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return 'env must be an object of variable names';
+  }
+
+  const env: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(raw)) {
+    if (!ENV_NAME.test(key)) {
+      return `env.${key} is not a variable name: use capital letters, digits and underscores`;
+    }
+
+    if (isReservedEnvName(key)) {
+      return `env.${key} cannot be set: atc or impd sets or reserves it`;
+    }
+
+    if (value !== ENV_PLACEHOLDER && value !== `https://${host}`) {
+      return `env.${key} must be ${ENV_PLACEHOLDER} or https://${host}`;
+    }
+
+    env[key] = value;
+  }
+
+  return env;
+}
+
+function isReservedEnvName(key: string): boolean {
+  return (
+    isBrokerVariable(key) ||
+    isSubscriptionOverrideVariable(key) ||
+    RESERVED_ENV_NAMES.has(key) ||
+    RESERVED_ENV_PREFIXES.some((prefix) => key.startsWith(prefix))
+  );
+}

package/src/shared/collect-profile-env-problems.ts

@@ -0,0 +1,16 @@
+/**
+ * Every variable an entry's `env` or `settings.env` sets that one of its
+ * selected auth profiles also sets, which would win over or lose to the
+ * profile's value by order. `owners` maps each profile variable to the
+ * profile that sets it.
+ */
+export function collectProfileEnvProblems(
+  sources: readonly (readonly [string, readonly string[]])[],
+  owners: Readonly<Record<string, string>>,
+): string[] {
+  return sources.flatMap(([source, keys]) =>
+    keys
+      .filter((key) => owners[key] !== undefined)
+      .map((key) => `${source} sets ${key}, which auth profile ${owners[key]} sets`),
+  );
+}

package/src/shared/resolve-auth-profiles.ts

@@ -23,7 +23,8 @@ export interface ResolvedAuthSecret {
 
 /**
  * A selection with its dependencies expanded: every profile it reaches,
- * every host those profiles send a credential to, and the rules grouped by
+ * every host those profiles send a credential to, the variables they set
+ * in the guest with the profile each came from, and the rules grouped by
  * secret, each list sorted so two selections of the same profiles resolve
  * the same.
  */
@@ -31,6 +32,8 @@ interface ResolvedAuthProfiles {
   readonly profiles: readonly string[];
   readonly hosts: readonly string[];
   readonly secrets: readonly ResolvedAuthSecret[];
+  readonly env: Readonly<Record<string, string>>;
+  readonly envOwners: Readonly<Record<string, string>>;
 }
 
 /**
@@ -40,7 +43,8 @@ interface ResolvedAuthProfiles {
  *   the config refused.
  * - `auth_dependency_cycle`: the dependencies loop back on themselves.
  * - `auth_collision`: two profiles send different credentials or rules to
- *   one host, which impd could not tell apart.
+ *   one host, which impd could not tell apart, or set one variable to
+ *   different values.
  */
 export interface AuthProfileProblem {
   readonly code: 'auth_profile_unknown' | 'auth_dependency_cycle' | 'auth_collision';
@@ -85,6 +89,9 @@ export function resolveAuthProfiles(
   const byHost = new Map<string, ProfileRule>();
   const kinds = new Map<string, AuthProfile>();
 
+  const env: Record<string, string> = {};
+  const envOwners: Record<string, string> = {};
+
   for (const profile of ordered) {
     const kindOwner = kinds.get(profile.secret);
 
@@ -99,6 +106,22 @@ export function resolveAuthProfiles(
       };
     }
 
+    for (const [key, value] of Object.entries(profile.env)) {
+      const owner = envOwners[key];
+
+      if (owner === undefined) {
+        env[key] = value;
+        envOwners[key] = profile.name;
+      } else if (env[key] !== value) {
+        return {
+          problem: {
+            code: 'auth_collision',
+            message: `profiles ${owner} and ${profile.name} set ${key} to different values`,
+          },
+        };
+      }
+    }
+
     for (const rule of getProfileRules(profile)) {
       const other = byHost.get(rule.host);
 
@@ -120,6 +143,8 @@ export function resolveAuthProfiles(
       profiles: ordered.map((profile) => profile.name),
       hosts: [...byHost.keys()].toSorted(),
       secrets: buildSecrets([...byHost.values()]),
+      env,
+      envOwners,
     },
   };
 }