@zgeoff/atc 2.19.0 → 2.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.19.0",
+  "version": "2.20.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

@@ -1,4 +1,5 @@
 import type { AdapterEvent } from '../protocol/adapter-event';
+import type { DaemonError } from '../protocol/daemon-error';
 import type { HookEvent } from '../protocol/hook-event';
 import type { AgentID } from '../shared/agent-id';
 import type { AgentSessionID } from '../shared/agent-session-id';
@@ -205,6 +206,10 @@ export interface AgentAdapter {
   // Absent: the agent runs there as a local spawn plans it, with no files.
   readonly planGuestSpawn?: (opts: SpawnOptions, guest: GuestPaths) => GuestSpawnPlan | null;
 
+  // The refusal every start of this agent's harness gets, on any target,
+  // or null when it may start. Absent: no start is refused.
+  readonly findSpawnRefusal?: () => DaemonError | null;
+
   // The command that exits 0 inside a remote host when the agent there can
   // sign in without a person. Absent: atc runs no check.
   readonly planAuthCheck?: () => readonly string[];

package/src/agents/gateway-adapter.ts

@@ -1,4 +1,5 @@
 import type { AdapterEvent } from '../protocol/adapter-event';
+import { DaemonError } from '../protocol/daemon-error';
 import type { HookEvent } from '../protocol/hook-event';
 import type { AgentID } from '../shared/agent-id';
 import type { AgentSessionID } from '../shared/agent-session-id';
@@ -39,7 +40,8 @@ export class GatewayAdapter implements AgentAdapter {
   readonly id: AgentID;
 
   // A headless turn carries the same settings file the terminal spawn does,
-  // so it reaches this backend rather than the default one.
+  // so it reaches this backend rather than the default one. A gateway whose
+  // credential comes through impd's broker runs no headless turn.
   readonly headlessRunner: HeadlessRunner | null;
 
   // The CLI's hooks are authoritative; no screen heuristics needed.
@@ -90,7 +92,7 @@ export class GatewayAdapter implements AgentAdapter {
     this.claude = new ClaudeAdapter(config);
 
     this.headlessRunner =
-      headlessRun === null
+      headlessRun === null || gateway.auth !== undefined
         ? null
         : makeClaudeHeadlessRunner(headlessRun, {
             claudeBin: gateway.bin,
@@ -100,6 +102,21 @@ export class GatewayAdapter implements AgentAdapter {
           });
   }
 
+  // A gateway whose credential comes through impd's broker never starts
+  // until the broker path exists: started without it, the CLI would send
+  // whatever credential it holds to the gateway's host.
+  findSpawnRefusal(): DaemonError | null {
+    if (this.gateway.auth === undefined) {
+      return null;
+    }
+
+    return new DaemonError(
+      'auth_target_unsupported',
+      `gateway '${this.id}' takes its credential from impd's broker, and brokered credentials are not wired yet`,
+      { agent: this.id },
+    );
+  }
+
   planSpawn(opts: SpawnOptions): SpawnPlan {
     return {
       bin: this.gateway.bin,
@@ -142,7 +159,13 @@ export class GatewayAdapter implements AgentAdapter {
   // explicit flag, so that mode overrides the one the CLI would restore, and
   // the generated settings file, because
   // without it the CLI would resume the session against the default backend.
+  // A gateway whose credential comes through impd's broker has none, since
+  // outside atc the broker never reaches it.
   buildResumeCommand(cwd: string, agentSessionID: AgentSessionID | undefined): string | null {
+    if (this.gateway.auth !== undefined) {
+      return null;
+    }
+
     const args = [
       ...this.gateway.args,
       ...buildRestoreModeArgs(this.gateway.args, this.gateway.settings),

package/src/cli.ts

@@ -182,7 +182,12 @@ const main = defineCommand({
             console.error(`atc daemon: config: ${line}`);
           }
 
-          for (const problem of [...cfg.principalErrors, ...cfg.workspaceErrors]) {
+          for (const problem of [
+            ...cfg.principalErrors,
+            ...cfg.workspaceErrors,
+            ...cfg.authProfileErrors,
+            ...cfg.gatewayErrors,
+          ]) {
             console.error(`atc daemon: config: ${problem}`);
           }
 

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

@@ -9,7 +9,8 @@ export interface AgentPick {
 /**
  * The agent choices the spawn and adopt flows offer, in menu order. An agent
  * whose configured binary does not resolve is left out, so every row in the
- * menu is a session that can start. Resolution follows the rule a spawn
+ * menu is a session that can start. A gateway with auth is left out too, since
+ * every start of one is refused. Resolution follows the rule a spawn
  * follows: a bare name comes off PATH, a name carrying a separator is taken
  * as a path, and either way it has to be executable.
  */
@@ -22,7 +23,9 @@ export function collectAgentPicks(config: Config): AgentPick[] {
     { 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 })),
+    ...config.gateways
+      .filter((g) => g.auth === undefined)
+      .map((g) => ({ agent: g.id, label: g.label, bin: g.bin })),
   ];
 
   return candidates

package/src/daemon/build-agent-list.ts

@@ -1,7 +1,8 @@
 import type { AgentAdapter, SpawnOptionSpec } from '../agents/agent-adapter';
 
 interface AgentCapabilities {
-  // Only an installed agent can start a session.
+  // Only an installed agent whose starts are not all refused can start a
+  // session.
   readonly spawn: boolean;
   readonly readTranscript: boolean;
 
@@ -51,6 +52,7 @@ export function buildAgentList(
   return adapters.map((adapter) => {
     const profile = adapter.profile;
     const installed = profile === undefined ? false : isInstalled(profile.bin);
+    const spawnable = installed && (adapter.findSpawnRefusal?.() ?? null) === null;
 
     return {
       id: adapter.id,
@@ -58,7 +60,7 @@ export function buildAgentList(
       kind: profile?.kind ?? adapter.id,
       installed,
       capabilities: {
-        spawn: installed,
+        spawn: spawnable,
         readTranscript: adapter.parseTranscriptLine !== undefined,
         message: adapter.takesMessages,
         attach: true,
@@ -67,8 +69,8 @@ export function buildAgentList(
       },
       models: profile?.models ?? null,
       spawnOptions: {
-        model: buildSpawnOptionEntry(profile?.spawnOptions.model, installed),
-        effort: buildSpawnOptionEntry(profile?.spawnOptions.effort, installed),
+        model: buildSpawnOptionEntry(profile?.spawnOptions.model, spawnable),
+        effort: buildSpawnOptionEntry(profile?.spawnOptions.effort, spawnable),
       },
     };
   });
@@ -86,9 +88,9 @@ const NO_SPAWN_OPTION: SpawnOptionSpec = {
 
 function buildSpawnOptionEntry(
   spec: SpawnOptionSpec | undefined,
-  installed: boolean,
+  spawnable: boolean,
 ): SpawnOptionEntry {
   const resolved = spec ?? NO_SPAWN_OPTION;
 
-  return { ...resolved, available: installed && resolved.supported };
+  return { ...resolved, available: spawnable && resolved.supported };
 }

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

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+import type { AgentID } from '../shared/agent-id';
+import type { AuthProfile } from '../shared/collect-auth-profiles';
+import type { GatewayAuth, 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';
+
+/**
+ * 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
+ * it was, and a change to one it reaches gives another hash.
+ */
+export interface AuthBinding {
+  readonly agent: AgentID;
+  readonly baseURL: string;
+  readonly profiles: readonly string[];
+  readonly secrets: readonly ResolvedAuthSecret[];
+  readonly placeholderEnv: Readonly<Record<string, string>>;
+  readonly hash: string;
+}
+
+type AuthGateway = Pick<GatewayConfig, 'id' | 'baseURL'> & { readonly auth: GatewayAuth };
+
+/**
+ * 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
+ * of the selection or of the config never changes it.
+ */
+export function buildAuthBinding(
+  gateway: AuthGateway,
+  profiles: ReadonlyMap<string, AuthProfile>,
+): { readonly binding: AuthBinding } | { readonly problem: AuthProfileProblem } {
+  const resolution = resolveAuthProfiles(profiles, gateway.auth.profiles);
+
+  if ('problem' in resolution) {
+    return resolution;
+  }
+
+  const secrets = resolution.resolved.secrets;
+
+  return {
+    binding: {
+      agent: gateway.id,
+      baseURL: gateway.baseURL,
+      profiles: resolution.resolved.profiles,
+      secrets,
+      placeholderEnv: gateway.auth.placeholderEnv,
+      hash: createHash('sha256')
+        .update(JSON.stringify(sortJSONKeys({ secrets })))
+        .digest('hex'),
+    },
+  };
+}

package/src/daemon/build-imp-name.ts

@@ -0,0 +1,11 @@
+/**
+ * The imp a host key runs on: the target's imp name prefix and the first
+ * 20 letters and digits of the key, which is the atc session id of the
+ * session that owns the host.
+ */
+export function buildImpName(impPrefix: string, hostKey: string): string {
+  return `${impPrefix}${hostKey
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]/g, '')
+    .slice(0, 20)}`;
+}

package/src/daemon/build-imp-provider.ts

@@ -17,8 +17,12 @@ export interface ImpProviderBuild {
  * so no credential sits in the config. `tokenEnv` holds the name of the
  * daemon's environment variable that carries the token, read once here.
  * `tokenFile` holds the path of a file that carries it, read here and again
- * before each impd call and connection. `image`, `memoryMib`, `guestDir`,
- * and `guestATC` pass through. No provider when `url` is missing, so the
+ * before each impd call and connection. `impPrefix` starts every imp name
+ * the target builds, `atc-` when absent, and must be a lowercase letter
+ * followed by up to 10 lowercase letters, digits or hyphens, so the name
+ * it builds with a host key's 20 characters stays within impd's 31. `image`,
+ * `memoryMib`, `guestDir`, and `guestATC` pass through. No provider when
+ * `url` is missing, so the
  * target lists and refuses every spawn. Both token options, either one not
  * a non-empty string, an unset or empty variable, or an empty or unreadable
  * file is a problem and leaves no provider; a target without either calls
@@ -41,7 +45,17 @@ export function buildImpProvider(
     return { provider: null, problem: source };
   }
 
+  const impPrefix = options['impPrefix'];
+
+  if (impPrefix !== undefined && !isImpPrefix(impPrefix)) {
+    return {
+      provider: null,
+      problem: `target ${JSON.stringify(id)} must give impPrefix as a lowercase letter followed by up to 10 lowercase letters, digits or hyphens, so every imp name it builds is one impd accepts`,
+    };
+  }
+
   const provider = new ImpProvider(new ImpClientPort({ url, readToken: source.readToken }), {
+    ...(impPrefix === undefined ? {} : { impPrefix }),
     ...pickString(options, 'image'),
     ...pickString(options, 'guestDir'),
     ...pickString(options, 'guestATC'),
@@ -105,6 +119,15 @@ function loadTokenSource(
   return { readToken: () => token };
 }
 
+// impd's imp name rule, a lowercase letter then up to 30 lowercase letters,
+// digits or hyphens, with room left for the 20 characters of a host key.
+// It holds no `*`, so the prefix never reads as an imp pattern.
+const IMP_PREFIX = /^[a-z][a-z0-9-]{0,10}$/;
+
+function isImpPrefix(value: unknown): value is string {
+  return typeof value === 'string' && IMP_PREFIX.test(value);
+}
+
 function pickString(
   options: Readonly<Record<string, unknown>>,
   key: 'image' | 'guestDir' | 'guestATC',

package/src/daemon/daemon-connection.ts

@@ -751,6 +751,13 @@ export class DaemonConnection {
         );
       }
 
+      // Checked before any workspace is materialized for the spawn.
+      const refusal = adapter.findSpawnRefusal?.() ?? null;
+
+      if (refusal !== null) {
+        throw refusal;
+      }
+
       const overrides = parseSpawnOverrides(entry, { model: data.model, effort: data.effort });
 
       if (!overrides.ok) {

package/src/daemon/imp-port.ts

@@ -19,8 +19,10 @@ export interface ImpPort {
   // The names of the secrets granted to an imp.
   readonly readGrants: (name: string) => Promise<readonly string[]>;
 
-  // Grants a secret to an imp; granting one it already holds changes
-  // nothing, and nothing in the result distinguishes the two.
+  // Grants a secret to an imp. impd's grant add is idempotent: granting one
+  // the imp already holds changes nothing, and impd returns no creation or
+  // ownership receipt, so nothing in the result tells a new grant from an
+  // existing one or shows who added it.
   readonly createGrant: (name: string, secret: string) => Promise<void>;
 
   // Revokes a secret from an imp, and reports whether impd held the grant.

package/src/daemon/imp-provider.ts

@@ -1,6 +1,7 @@
 import { DaemonError } from '../protocol/daemon-error';
 import { LineDecoder } from '../protocol/line-decoder';
 import { isCompiledBinary } from '../shared/is-compiled-binary';
+import { buildImpName } from './build-imp-name';
 import { buildTarArchive } from './build-tar-archive';
 import type {
   CommandResult,
@@ -20,10 +21,12 @@ import { ImpPortError } from './imp-port-error';
 /**
  * The options an `imp` target takes beside its provider: the image a new
  * imp boots, the memory it gets, the folder inside each imp that atc's
- * files go under, and the path of an atc binary already installed in the
- * image. None holds a credential.
+ * files go under, the path of an atc binary already installed in the
+ * image, and the prefix every imp name the target builds starts with.
+ * None holds a credential.
  */
 export interface ImpTargetOptions {
+  readonly impPrefix?: string;
   readonly image?: string;
   readonly memoryMib?: number;
   readonly guestDir?: string;
@@ -48,6 +51,9 @@ interface ImpProviderOptions {
 // none.
 const GUEST_DIR = '/tmp/atc';
 
+// The start of every imp name when the target sets no prefix.
+const IMP_PREFIX = 'atc-';
+
 // impd takes a lease of 10 to 3600 seconds; the daemon renews at a third of it.
 const LEASE_SECONDS = 600;
 
@@ -86,6 +92,10 @@ export class ImpProvider implements ExecutionProvider {
 
   readonly guest: GuestLayout;
 
+  // The literal start of every imp name this provider builds: the runtime
+  // namespace an impd token's imp patterns are checked against.
+  readonly impPrefix: string;
+
   private readonly port: ImpPort;
 
   private readonly target: ImpTargetOptions;
@@ -109,6 +119,7 @@ export class ImpProvider implements ExecutionProvider {
   constructor(port: ImpPort, target: ImpTargetOptions, options: ImpProviderOptions = {}) {
     this.port = port;
     this.target = target;
+    this.impPrefix = target.impPrefix ?? IMP_PREFIX;
     this.leaseSeconds = options.leaseSeconds ?? LEASE_SECONDS;
     this.reconnectDelaysMs = options.reconnectDelaysMs ?? RECONNECT_DELAYS_MS;
 
@@ -123,10 +134,15 @@ export class ImpProvider implements ExecutionProvider {
     };
   }
 
+  // The imp a host key runs on, under this provider's prefix.
+  getImpName(hostKey: string): string {
+    return buildImpName(this.impPrefix, hostKey);
+  }
+
   // Creates the host's imp when impd holds none, then takes the daemon's
   // lease, which boots or wakes the imp.
   readonly prepareHost = async (request: HostRequest): Promise<void> => {
-    const name = buildImpName(request.host);
+    const name = this.getImpName(request.host);
     const label = `atc-${request.daemonID}`;
 
     this.label = label;
@@ -181,7 +197,7 @@ export class ImpProvider implements ExecutionProvider {
 
   readonly spawnHarness = (spec: HarnessSpec): HarnessHandle => {
     const host = this.hosts.get(spec.host) ?? {
-      name: buildImpName(spec.host),
+      name: this.getImpName(spec.host),
       harnesses: 0,
       renewTimer: null,
       suspending: false,
@@ -257,7 +273,7 @@ export class ImpProvider implements ExecutionProvider {
   // carries what impd showed of the other leases.
   readonly suspendHost = async (hostKey: string): Promise<void> => {
     const host = this.hosts.get(hostKey) ?? {
-      name: buildImpName(hostKey),
+      name: this.getImpName(hostKey),
       harnesses: 0,
       renewTimer: null,
       suspending: false,
@@ -290,7 +306,7 @@ export class ImpProvider implements ExecutionProvider {
   // A destroy ends every lease on the imp with it.
   readonly destroyHost = async (hostKey: string): Promise<void> => {
     const host = this.hosts.get(hostKey);
-    const name = buildImpName(hostKey);
+    const name = this.getImpName(hostKey);
 
     if (host !== undefined) {
       this.stopRenewal(host);
@@ -405,9 +421,9 @@ export class ImpProvider implements ExecutionProvider {
     }
 
     try {
-      return await this.port.runCommand(buildImpName(hostKey), command);
+      return await this.port.runCommand(this.getImpName(hostKey), command);
     } catch (error) {
-      throw toHostRefusal(error, buildImpName(hostKey));
+      throw toHostRefusal(error, this.getImpName(hostKey));
     }
   }
 
@@ -496,17 +512,6 @@ interface ImpHost {
   suspending: boolean;
 }
 
-/**
- * The imp a host key runs on: `atc-` and the first 20 letters and digits of
- * the key, which is the atc session id of the session that owns the host.
- */
-function buildImpName(hostKey: string): string {
-  return `atc-${hostKey
-    .toLowerCase()
-    .replaceAll(/[^a-z0-9]/g, '')
-    .slice(0, 20)}`;
-}
-
 function buildImpSessionName(sessionID: string): string {
   return `atc-${sessionID
     .toLowerCase()

package/src/daemon/restore-fleet.ts

@@ -185,7 +185,7 @@ function isSameSession(s: Session, entry: FleetEntry): boolean {
 
 // The refusals that leave one session without a terminal: its target is
 // misconfigured, gone from the config, changed, has no provider here, or
-// cannot start a terminal.
+// cannot start a terminal, or its agent refuses every start.
 const REFUSED_ADOPT_CODES: ReadonlySet<string> = new Set([
   'unsupported_operation',
   'unknown_target',
@@ -194,6 +194,7 @@ const REFUSED_ADOPT_CODES: ReadonlySet<string> = new Set([
   'target_config_invalid',
   'host_unavailable',
   'auth_not_configured',
+  'auth_target_unsupported',
 ]);
 
 async function tryAdoptTerminal(

package/src/daemon/sessions.ts

@@ -857,6 +857,12 @@ export class SessionManager {
     target: string,
     options: SpawnOptions,
   ): Promise<SpawnPlan> {
+    const refusal = adapter.findSpawnRefusal?.() ?? null;
+
+    if (refusal !== null) {
+      throw refusal;
+    }
+
     if (!provider.remote) {
       await provider.prepareHost({ host: hostKey, daemonID: this.store.daemonID });
 

package/src/protocol/protocol.ts

@@ -48,6 +48,7 @@ const ERROR_CODES = [
   'github_unavailable',
   'host_unavailable',
   'auth_not_configured',
+  'auth_target_unsupported',
   'host_leased',
   'confirmation_required',
   'confirm_token_invalid',

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

@@ -0,0 +1,122 @@
+import { isRecord } from './report';
+
+/**
+ * A named reference to a credential impd holds: the secret's name, never
+ * its value, and the rule impd applies when a request reaches the host,
+ * plus the profiles a session selecting this one needs beside it. Only
+ * the `custom` kind and the `bearer` scheme are bound.
+ */
+export interface AuthProfile {
+  readonly name: string;
+  readonly secret: string;
+  readonly kind: 'custom';
+  readonly host: string;
+  readonly header: string;
+  readonly scheme: 'bearer';
+  readonly dependencies: readonly string[];
+}
+
+interface AuthProfiles {
+  readonly profiles: ReadonlyMap<string, AuthProfile>;
+  readonly errors: readonly string[];
+}
+
+/**
+ * Reads the `authProfiles` map under impd's own rules for secret names,
+ * broker hosts and header names. A profile that breaks a rule is left out
+ * with an error, so a gateway that selects it is refused rather than bound
+ * to a rule impd would reject or apply differently. Dependencies are
+ * names only here; whether they resolve is a property of each selection.
+ */
+export function collectAuthProfiles(raw: unknown): AuthProfiles {
+  if (raw === undefined) {
+    return { profiles: new Map(), errors: [] };
+  }
+
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return { profiles: new Map(), errors: ['authProfiles must be an object of named profiles'] };
+  }
+
+  const profiles = new Map<string, AuthProfile>();
+
+  const errors: string[] = [];
+
+  for (const [name, entry] of Object.entries(raw)) {
+    const parsed = parseAuthProfile(name, entry);
+
+    if (typeof parsed === 'string') {
+      errors.push(`authProfiles.${name}: ${parsed}`);
+    } else {
+      profiles.set(name, parsed);
+    }
+  }
+
+  return { profiles, errors };
+}
+
+// impd's secret name rule: an imp name's form, so a secret name is never a
+// path or a flag.
+const SECRET_NAME = /^[a-z][a-z0-9-]{0,30}$/;
+
+// impd's broker host rule: a lowercase hostname as a CONNECT carries it, with
+// no port and no wildcard, whose last label starts with a letter so an IP
+// address never matches.
+const BROKER_HOST = /^(?:[a-z0-9][a-z0-9-]{0,62}\.)+[a-z][a-z0-9-]{0,62}$/;
+const BROKER_HOST_MAX = 253;
+
+// impd's header name rule.
+const HEADER_NAME = /^[a-z0-9-]{1,64}$/;
+
+// The profile an entry holds, or the first rule it breaks.
+function parseAuthProfile(name: string, entry: unknown): AuthProfile | string {
+  if (!isRecord(entry) || Array.isArray(entry)) {
+    return 'a profile must be an object';
+  }
+
+  const secret = entry['secret'];
+  const host = entry['host'];
+  const header = entry['header'];
+  const scheme = entry['scheme'];
+  const dependencies = entry['dependencies'];
+
+  if (entry['kind'] !== undefined && entry['kind'] !== 'custom') {
+    return 'kind must be custom, the one kind atc binds';
+  }
+
+  if (typeof secret !== 'string' || !SECRET_NAME.test(secret)) {
+    return 'secret must be a lowercase letter followed by up to 30 lowercase letters, digits or hyphens';
+  }
+
+  if (typeof host !== 'string' || host.length > BROKER_HOST_MAX || !BROKER_HOST.test(host)) {
+    return 'host must be a lowercase hostname such as api.example.com';
+  }
+
+  if (typeof header !== 'string' || !HEADER_NAME.test(header)) {
+    return 'header must be a lowercase header name such as authorization';
+  }
+
+  if (scheme !== 'bearer') {
+    return 'scheme must be bearer, the one scheme atc binds';
+  }
+
+  if (entry['user'] !== undefined) {
+    return 'user pairs only with the basic scheme, which atc does not bind';
+  }
+
+  if (
+    dependencies !== undefined &&
+    (!Array.isArray(dependencies) || !dependencies.every((dep) => typeof dep === 'string'))
+  ) {
+    return 'dependencies must be an array of profile names';
+  }
+
+  return {
+    name,
+    secret,
+    kind: 'custom',
+    host,
+    header,
+    scheme,
+    dependencies: dependencies ?? [],
+  };
+}