@zgeoff/atc 2.10.4 → 2.12.0

package/src/client/boot-daemon.ts

@@ -4,6 +4,8 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { toAgentID } from '../agents/agent-adapter';
 import type { AgentID } from '../agents/agent-adapter';
+import type { DaemonFeature } from '../protocol/daemon-features';
+import { parseDaemonFeatures } from '../protocol/parse-daemon-features';
 import { daemonPidFile, daemonRecordFile, daemonSocketPath } from '../shared/config';
 import { findDaemonRecord } from '../shared/find-daemon-record';
 import { getBuild } from '../shared/get-build';
@@ -18,6 +20,9 @@ export interface DaemonBoot {
   readonly stale: boolean;
   readonly lastUsedAgent: AgentID;
 
+  // What the daemon announced it serves; an older daemon announces less.
+  readonly features: ReadonlySet<DaemonFeature>;
+
   // The socket the client reached, which differs from the computed one when
   // the daemon was found through its record in the state directory.
   readonly socketPath: string;
@@ -49,6 +54,7 @@ export async function bootDaemonClient(): Promise<DaemonBoot> {
         client,
         stale: hello['daemon'] !== build,
         lastUsedAgent: toAgentID(hello['lastUsedAgent']),
+        features: parseDaemonFeatures(hello),
         socketPath: opened.socketPath,
       };
     } catch (error) {

package/src/client/daemon-client.ts

@@ -65,9 +65,12 @@ export class DaemonClient {
     return this.sendRequest('daemon.hello', { client: build, auth: { scheme: 'none' } });
   }
 
+  // A request with a principal acts as that principal, within what the
+  // connection may reach.
   sendRequest(
     m: string,
     p?: Readonly<Record<string, unknown>>,
+    as?: string,
   ): Promise<Readonly<Record<string, unknown>>> {
     if (this.closedReason !== null) {
       return Promise.reject(new DaemonError('internal', this.closedReason));
@@ -77,7 +80,16 @@ export class DaemonClient {
     const resolvers = Promise.withResolvers<Readonly<Record<string, unknown>>>();
 
     this.pending.set(id, { resolve: resolvers.resolve, reject: resolvers.reject });
-    this.queue?.send(encodeMessage({ v: PROTOCOL_V, id, m, ...(p === undefined ? {} : { p }) }));
+
+    this.queue?.send(
+      encodeMessage({
+        v: PROTOCOL_V,
+        id,
+        m,
+        ...(p === undefined ? {} : { p }),
+        ...(as === undefined ? {} : { as }),
+      }),
+    );
 
     return resolvers.promise;
   }
@@ -138,7 +150,7 @@ export class DaemonClient {
     if (msg.err === undefined) {
       waiter.resolve(msg.ok ?? {});
     } else {
-      waiter.reject(new DaemonError(msg.err.code, msg.err.msg));
+      waiter.reject(new DaemonError(msg.err.code, msg.err.msg, msg.err.data));
     }
   }
 

package/src/client/spawn-picker.ts

@@ -1,5 +1,6 @@
 import { homedir } from 'node:os';
 import type { AgentID } from '../agents/agent-adapter';
+import { DaemonError } from '../protocol/daemon-error';
 import { loadConfig } from '../shared/config';
 import { collectAgentPicks } from './collect-agent-picks';
 import type { AgentPick } from './collect-agent-picks';
@@ -32,7 +33,8 @@ export interface SpawnPickerDeps<TMirror> {
 /**
  * The modal flow behind n and r: agent, then directory, then name, then an
  * optional first prompt. Every path out of it either attaches the new
- * session or returns the client to the screen it came from.
+ * session or returns the client to the screen it came from. A spawn the
+ * daemon refuses is no path out: the flow stays open and shows why.
  */
 export class SpawnPicker<TMirror extends { readonly id: string }> {
   private readonly deps: SpawnPickerDeps<TMirror>;
@@ -60,6 +62,10 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
   private agent: AgentID = 'claude';
 
+  // The daemon's refusal of the last spawn, shown in place of the hint until
+  // the next key.
+  private refusal: string | null = null;
+
   constructor(deps: SpawnPickerDeps<TMirror>) {
     this.deps = deps;
   }
@@ -82,12 +88,15 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
     this.agent = this.picks[this.selected]?.agent ?? this.deps.getLastUsedAgent();
     this.step = 'agent';
+    this.refusal = null;
 
     process.stdout.write(ansi.clear);
     this.render();
   }
 
   applyKey(buf: Buffer) {
+    this.refusal = null;
+
     const edit = planTextEdit(buf, this.input, {
       isLeaderKey: this.deps.isLeaderKey,
       moves: this.step === 'agent' || this.step === 'dir',
@@ -168,7 +177,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
         selected: -1,
         input: this.input,
         placeholder: formatDirName(this.dir),
-        hint: `session name for ${formatDir(this.dir)} · ⏎ accept · esc back`,
+        hint: this.refusal ?? `session name for ${formatDir(this.dir)} · ⏎ accept · esc back`,
       });
     } else {
       drawPicker({
@@ -177,7 +186,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
         selected: -1,
         input: this.input,
         placeholder: 'optional — ⏎ to start interactive',
-        hint: 'first message for the session · ⏎ spawn · esc back',
+        hint: this.refusal ?? 'first message for the session · ⏎ spawn · esc back',
       });
     }
 
@@ -320,7 +329,21 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
         return;
       }
-    } catch {}
+    } catch (error) {
+      // A refused spawn keeps the picker on the step that sent it, with the
+      // entered text back in the input, so the user can fix the cause and
+      // retry or back out.
+      const reason =
+        error instanceof DaemonError ? `${error.code}: ${error.message}` : String(error);
+
+      this.refusal = `${reason} · ⏎ retry · esc back`;
+      this.input = this.resume ? this.name : prompt;
+
+      process.stdout.write(ansi.clear);
+      this.render();
+
+      return;
+    }
 
     this.deps.toBase();
   }

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

@@ -0,0 +1,94 @@
+import type { AgentAdapter, SpawnOptionSpec } from '../agents/agent-adapter';
+
+interface AgentCapabilities {
+  // Only an installed agent can start a session.
+  readonly spawn: boolean;
+  readonly readTranscript: boolean;
+
+  // Whether a session takes inbox messages through a tap.
+  readonly message: boolean;
+  readonly attach: boolean;
+  readonly screen: boolean;
+  readonly input: boolean;
+}
+
+export interface AgentEntry {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: string;
+
+  // Whether the agent's binary resolves, on PATH or at its configured path.
+  readonly installed: boolean;
+  readonly capabilities: AgentCapabilities;
+  readonly models: Readonly<Record<string, string>> | null;
+  readonly spawnOptions: SpawnOptionEntries;
+}
+
+// A spawn option as `agents.list` shows it: the agent's own spec, plus
+// whether a spawn on this host can pass it now. Only an installed agent's
+// supported option is available.
+export interface SpawnOptionEntry extends SpawnOptionSpec {
+  readonly available: boolean;
+}
+
+interface SpawnOptionEntries {
+  readonly model: SpawnOptionEntry;
+  readonly effort: SpawnOptionEntry;
+}
+
+/**
+ * One `agents.list` entry per registered adapter, in registration order. An
+ * entry carries only the adapter's profile and what its interface offers,
+ * so no environment value, credential, helper command, or base URL reaches
+ * it. Every session runs in a PTY, so each agent can be attached, read as a
+ * screen, and typed into. A stand-in adapter without a profile is listed
+ * under its id as both label and kind.
+ */
+export function buildAgentList(
+  adapters: readonly AgentAdapter[],
+  isInstalled: (bin: string) => boolean,
+): AgentEntry[] {
+  return adapters.map((adapter) => {
+    const profile = adapter.profile;
+    const installed = profile === undefined ? false : isInstalled(profile.bin);
+
+    return {
+      id: adapter.id,
+      label: profile?.label ?? adapter.id,
+      kind: profile?.kind ?? adapter.id,
+      installed,
+      capabilities: {
+        spawn: installed,
+        readTranscript: adapter.parseTranscriptLine !== undefined,
+        message: adapter.takesMessages,
+        attach: true,
+        screen: true,
+        input: true,
+      },
+      models: profile?.models ?? null,
+      spawnOptions: {
+        model: buildSpawnOptionEntry(profile?.spawnOptions.model, installed),
+        effort: buildSpawnOptionEntry(profile?.spawnOptions.effort, installed),
+      },
+    };
+  });
+}
+
+// A stand-in adapter declares no spawn options, so it takes none.
+const NO_SPAWN_OPTION: SpawnOptionSpec = {
+  supported: false,
+  values: null,
+  examples: [],
+  default: null,
+  backendEffect: null,
+  note: null,
+};
+
+function buildSpawnOptionEntry(
+  spec: SpawnOptionSpec | undefined,
+  installed: boolean,
+): SpawnOptionEntry {
+  const resolved = spec ?? NO_SPAWN_OPTION;
+
+  return { ...resolved, available: installed && resolved.supported };
+}

package/src/daemon/build-config-revision.ts

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+import type { TargetConfigError } from '../shared/collect-targets';
+import type { ExecutionTarget } from './build-execution-targets';
+
+/**
+ * A short digest of the target config a daemon runs with: each target's id
+ * and identity, the default target, and the config errors. Two daemons with
+ * the same targets return the same revision, and any change to them
+ * changes it.
+ */
+export function buildConfigRevision(
+  targets: readonly ExecutionTarget[],
+  defaultTarget: string | null,
+  errors: readonly TargetConfigError[],
+): string {
+  const canonical = JSON.stringify({
+    targets: targets.map((target) => [target.id, target.identity]),
+    defaultTarget,
+    errors: errors.map((error) =>
+      error.scope === 'config'
+        ? [error.scope, error.path, error.problem, error.detail]
+        : [error.scope, error.target ?? null, error.problem],
+    ),
+  });
+
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}

package/src/daemon/build-execution-targets.ts

@@ -0,0 +1,34 @@
+import type { TargetConfig } from '../shared/collect-targets';
+import { buildTargetIdentity } from './build-target-identity';
+import type { ExecutionProvider } from './execution-provider';
+import { LocalPTYProvider } from './local-pty-provider';
+
+/**
+ * A configured place sessions run, with the provider that serves it. The
+ * provider is null when this daemon has no provider of the configured kind:
+ * the target still lists, and a spawn to it fails rather than running
+ * anywhere else.
+ */
+export interface ExecutionTarget {
+  readonly id: string;
+  readonly kind: string;
+  readonly options: Readonly<Record<string, unknown>>;
+
+  // The identity a session spawned here binds to.
+  readonly identity: string;
+  readonly provider: ExecutionProvider | null;
+}
+
+/**
+ * Builds one target per configured entry, in config order, each with a
+ * provider of its kind when this daemon has one.
+ */
+export function buildExecutionTargets(configs: readonly TargetConfig[]): ExecutionTarget[] {
+  return configs.map((config) => ({
+    id: config.id,
+    kind: config.provider,
+    options: config.options,
+    identity: buildTargetIdentity(config.provider, config.options),
+    provider: config.provider === 'local-pty' ? new LocalPTYProvider() : null,
+  }));
+}

package/src/daemon/build-fleet-events.ts

@@ -23,7 +23,8 @@ export function buildFleetEvents(
   sessions: readonly SessionDescriptor[],
 ): FleetEvent[] {
   return rows.map((row) => {
-    // A restore re-mints atc ids, so the agent session id is the stable link.
+    // Rows written before atc session ids stayed stable across restores
+    // carry an earlier atc id, so the agent session id links them.
     const live =
       (row.agentSessionID === null
         ? undefined

package/src/daemon/build-payload-hash.ts

@@ -0,0 +1,31 @@
+import { createHash } from 'node:crypto';
+import { isRecord } from '../shared/report';
+
+/**
+ * The SHA-256 of a request's params as canonical JSON: object keys sorted
+ * at every depth, with the idempotency key itself left out. Two requests
+ * that differ only in key order or in their idempotency key hash the same.
+ */
+export function buildPayloadHash(params: Readonly<Record<string, unknown>>): string {
+  const { idempotencyKey: _ignored, ...payload } = params;
+
+  return createHash('sha256')
+    .update(JSON.stringify(sortKeys(payload)))
+    .digest('hex');
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortKeys(item));
+  }
+
+  if (!isRecord(value)) {
+    return value;
+  }
+
+  return Object.fromEntries(
+    Object.keys(value)
+      .toSorted()
+      .map((key) => [key, sortKeys(value[key])]),
+  );
+}

package/src/daemon/build-scoped-context.ts

@@ -0,0 +1,232 @@
+import { DaemonError } from '../protocol/daemon-error';
+import type { SessionID } from '../shared/session-id';
+import { toSessionID } from '../shared/to-session-id';
+import { buildTargetForbiddenError } from './build-target-forbidden-error';
+import { buildTargetIdentity } from './build-target-identity';
+import type { DaemonContext } from './daemon-connection';
+import type { KeyedRequest } from './idempotency-ledger';
+import type { TargetAccess, TargetGrant } from './target-access';
+
+/**
+ * The daemon as a principal with the given access sees it. Its keyed
+ * spawns and messages hold their keys in the given namespace, apart from
+ * every other namespace's. A session on a target outside the access does
+ * not exist here: every lookup of it answers as a lookup of an unknown
+ * session does, so the request's own handling refuses it with the words
+ * and data it gives a session that never existed. Lists leave such
+ * sessions out, and a spawn may use only a target the access holds, a
+ * spawn's replayed answer included. A kill, or a pin, of a session whose
+ * sub-sessions reach past the access is refused whole, before anything
+ * changes.
+ */
+export function buildScopedContext(
+  ctx: DaemonContext,
+  access: TargetAccess,
+  keyNamespace: string,
+): DaemonContext {
+  // A keyed request's key, held in this namespace alone.
+  const buildPrincipalKey = (keyed: KeyedRequest | null): KeyedRequest | null =>
+    keyed === null ? null : { ...keyed, principal: keyNamespace };
+
+  const canSee = (id: SessionID): boolean => {
+    const grant = ctx.findSessionGrant(id);
+
+    return grant !== null && access.canUse(grant);
+  };
+
+  const canUseTarget = (target: string): boolean => {
+    const targetIdentity = ctx.findTargetIdentity(target);
+
+    return targetIdentity !== null && access.canUse({ target, targetIdentity });
+  };
+
+  // The target a session is bound to: the live session's, else its fleet
+  // row's, else null for a session the daemon holds nowhere.
+  const findGrant = async (id: SessionID): Promise<TargetGrant | null> => {
+    const live = ctx.findSessionGrant(id);
+
+    if (live !== null) {
+      return live;
+    }
+
+    const fleet = await ctx.collectFleet();
+
+    const entry = fleet.find((row) => row.sessionID === id);
+
+    if (entry === undefined) {
+      return null;
+    }
+
+    return {
+      target: entry.target ?? 'local',
+      targetIdentity: entry.targetIdentity ?? buildTargetIdentity('local-pty', {}),
+    };
+  };
+
+  // Throws the refusal a fresh spawn to the session's target gets when a
+  // held key's refusal carries a session out of reach.
+  const requireSessionInReach = async (id: SessionID): Promise<void> => {
+    const grant = await findGrant(id);
+
+    if (grant !== null && !access.canUse(grant)) {
+      throw buildTargetForbiddenError(grant.target);
+    }
+  };
+
+  // Throws the refusal of a change to a session whose sub-sessions the
+  // change would reach too when any of them is out of reach. The refusal
+  // holds only the session the caller sent, never a sub-session's id or
+  // how many there are.
+  const requireTreeInReach = (id: SessionID, action: string): void => {
+    if (ctx.collectChildIDs(id).every((child) => canSee(child))) {
+      return;
+    }
+
+    throw new DaemonError(
+      'target_forbidden',
+      `this client may not ${action} session '${id}': it has a sub-session on a target this client may not use`,
+      { session: id },
+    );
+  };
+
+  return {
+    ...ctx,
+    collectSessions: () => ctx.collectSessions().filter((session) => canSee(session.id)),
+    collectAgents: () => {
+      const list = ctx.collectAgents();
+      const defaultTarget = list.spawnDefaults.target;
+
+      return {
+        ...list,
+        targets: list.targets.filter((target) => canUseTarget(target.id)),
+        spawnDefaults: {
+          ...list.spawnDefaults,
+          target: defaultTarget !== null && canUseTarget(defaultTarget) ? defaultTarget : null,
+        },
+
+        // The config file's own problem holds a path on the daemon's host,
+        // which is the owner's alone.
+        targetErrors: list.targetErrors.filter((error) => {
+          if (error.scope === 'config') {
+            return false;
+          }
+
+          return error.target === undefined || canUseTarget(error.target);
+        }),
+      };
+    },
+    collectFleet: async () => {
+      const fleet = await ctx.collectFleet();
+
+      return fleet.filter((entry) => canSee(entry.sessionID));
+    },
+    resolveSpawnTarget: (requested) => {
+      if (requested !== undefined) {
+        requireTarget(canUseTarget, requested);
+      }
+
+      const target = ctx.resolveSpawnTarget(requested);
+
+      requireTarget(canUseTarget, target);
+
+      return target;
+    },
+    spawnSession: async (plan, keyed) => {
+      let answer: Readonly<Record<string, unknown>>;
+
+      // A held key's replay is checked against the target its session was
+      // bound to, inside the spawn, before its answer leaves the daemon.
+      try {
+        answer = await ctx.spawnSession(plan, buildPrincipalKey(keyed), access);
+      } catch (error) {
+        // A held key's refusal may carry the session its spawn made.
+        if (error instanceof DaemonError && typeof error.data?.['effectRef'] === 'string') {
+          await requireSessionInReach(toSessionID(error.data['effectRef']));
+        }
+
+        throw error;
+      }
+
+      return answer;
+    },
+    killSession: (id) => {
+      if (!canSee(id)) {
+        return Promise.resolve(false);
+      }
+
+      requireTreeInReach(id, 'kill');
+
+      return ctx.killSession(id);
+    },
+    updateSession: (id, name, pinned) => {
+      if (!canSee(id)) {
+        return false;
+      }
+
+      if (pinned !== undefined) {
+        requireTreeInReach(id, 'pin');
+      }
+
+      return ctx.updateSession(id, name, pinned);
+    },
+    ackSession: (id) => canSee(id) && ctx.ackSession(id),
+    buildResumeCommand: (id) => (canSee(id) ? ctx.buildResumeCommand(id) : null),
+    readSessionScreen: (id) =>
+      canSee(id) ? ctx.readSessionScreen(id) : Promise.resolve('missing' as const),
+    answerPermission: (request, decision) => {
+      const owner = ctx.findPermissionSession(request);
+
+      return owner !== null && canSee(owner) ? ctx.answerPermission(request, decision) : 'unknown';
+    },
+    attachSession: (client, sessionID, dims) =>
+      canSee(sessionID) ? ctx.attachSession(client, sessionID, dims) : 'missing',
+    detachSession: (client, sessionID) => {
+      if (canSee(sessionID)) {
+        ctx.detachSession(client, sessionID);
+      }
+    },
+    writeSessionInput: (sessionID, data) =>
+      canSee(sessionID) ? ctx.writeSessionInput(sessionID, data) : 'missing',
+    ejectSession: (id, prompt) => (canSee(id) ? ctx.ejectSession(id, prompt) : 'missing'),
+    adoptSession: (id, cols, rows) => (canSee(id) ? ctx.adoptSession(id, cols, rows) : 'missing'),
+    resizeSession: (client, sessionID, dims) =>
+      canSee(sessionID) && ctx.resizeSession(client, sessionID, dims),
+    readSessionRecord: (id) =>
+      canSee(id) ? ctx.readSessionRecord(id) : Promise.resolve('missing' as const),
+    loadSessionTranscript: (id, from, limit) =>
+      canSee(id) ? ctx.loadSessionTranscript(id, from, limit) : Promise.resolve('missing' as const),
+    readEvents: (afterID, limit, waitMs, sessionID, outer) => {
+      const merged = outer === null ? access : outer.merge(access);
+
+      return ctx.readEvents(afterID, limit, waitMs, sessionID, merged);
+    },
+    writeSessionMessage: (sessionID, from, text, keyed) =>
+      canSee(sessionID)
+        ? ctx.writeSessionMessage(sessionID, from, text, buildPrincipalKey(keyed))
+        : Promise.resolve('missing' as const),
+    readMessage: async (messageID, waitMs) => {
+      // The owner is checked before any wait, so a message outside the
+      // access answers at once, as an unknown message does.
+      const view = await ctx.readMessage(messageID, 0);
+
+      if (view === null || !canSee(view.session)) {
+        return null;
+      }
+
+      return waitMs === 0 ? view : ctx.readMessage(messageID, waitMs);
+    },
+    attachTap: (client, sessionID) =>
+      canSee(sessionID) ? ctx.attachTap(client, sessionID) : 'missing',
+    ackMessage: (client, sessionID, messageID) =>
+      canSee(sessionID)
+        ? ctx.ackMessage(client, sessionID, messageID)
+        : Promise.resolve('unknown' as const),
+  };
+}
+
+// Throws the refusal of a spawn to a target the access leaves out.
+function requireTarget(canUseTarget: (target: string) => boolean, target: string): void {
+  if (!canUseTarget(target)) {
+    throw buildTargetForbiddenError(target);
+  }
+}

package/src/daemon/build-target-access.ts

@@ -0,0 +1,33 @@
+import type { ExecutionTarget } from './build-execution-targets';
+import { buildTargetIdentity } from './build-target-identity';
+import { TargetAccess } from './target-access';
+
+/**
+ * The targets a principal may use. With no principals in the config, every
+ * principal gets the implicit `local` target alone: the name `local` with
+ * the identity of a `local-pty` target without options, so a `local` that
+ * now holds another provider or other options is outside it. With
+ * principals, a principal gets each target its entry lists that the config
+ * holds, at that target's identity now, and an unknown principal gets none.
+ */
+export function buildTargetAccess(
+  principals: ReadonlyMap<string, readonly string[]> | null,
+  targets: ReadonlyMap<string, ExecutionTarget>,
+  principal: string,
+): TargetAccess {
+  if (principals === null) {
+    return new TargetAccess([
+      { target: 'local', targetIdentity: buildTargetIdentity('local-pty', {}) },
+    ]);
+  }
+
+  const granted = principals.get(principal) ?? [];
+
+  return new TargetAccess(
+    granted.flatMap((id) => {
+      const target = targets.get(id);
+
+      return target === undefined ? [] : [{ target: id, targetIdentity: target.identity }];
+    }),
+  );
+}

package/src/daemon/build-target-forbidden-error.ts

@@ -0,0 +1,13 @@
+import { DaemonError } from '../protocol/daemon-error';
+
+/**
+ * The refusal of a spawn to a target the principal may not use, which a
+ * replay of a held spawn key outside the principal's reach answers with too.
+ */
+export function buildTargetForbiddenError(target: string): DaemonError {
+  return new DaemonError(
+    'target_forbidden',
+    `this client may not use execution target '${target}'. Grant it to the client under principals in config.json and restart the daemon`,
+    { target },
+  );
+}

package/src/daemon/build-target-identity.ts

@@ -0,0 +1,22 @@
+import { createHash } from 'node:crypto';
+import { sortJSONKeys } from '../shared/sort-json-keys';
+
+/**
+ * The identity a session binds to when it spawns on a target: the provider
+ * kind, a colon, and the first 16 hex digits of a sha256 over the target's
+ * options with sorted keys. A target name reused with another provider or
+ * other options has another identity. Target options hold no credential
+ * values, only references such as an environment variable's name, so the
+ * identity never derives from a secret.
+ */
+export function buildTargetIdentity(
+  kind: string,
+  options: Readonly<Record<string, unknown>>,
+): string {
+  const digest = createHash('sha256')
+    .update(JSON.stringify(sortJSONKeys(options)))
+    .digest('hex')
+    .slice(0, 16);
+
+  return `${kind}:${digest}`;
+}