@zgeoff/atc 2.11.0 → 2.12.0

package/src/daemon/effect-remains-error.ts

@@ -0,0 +1,13 @@
+/**
+ * Thrown by an idempotent effect's start when it failed after the effect
+ * began and could not confirm taking it back, so the effect may still stand.
+ * The ledger keeps the key as outcome_unknown instead of releasing it, and a
+ * retry under the key never runs the effect a second time.
+ */
+export class EffectRemainsError extends Error {
+  constructor(message: string, options?: Readonly<ErrorOptions>) {
+    super(message, options);
+
+    this.name = 'EffectRemainsError';
+  }
+}

package/src/daemon/execution-provider.ts

@@ -0,0 +1,103 @@
+/**
+ * The host a session's harness runs on: it starts a process in a
+ * pseudo-terminal and, as its capabilities declare, unpacks files into its
+ * filesystem and runs commands there. The daemon starts every session
+ * terminal through this interface, so a new host is a provider, not a
+ * change to the session code. The daemon checks a capability before it
+ * calls the operation behind it, and a request needing one the provider
+ * lacks fails with `unsupported_operation`.
+ */
+export interface ExecutionProvider {
+  // The provider kind a target's config selects, such as `local-pty`.
+  readonly kind: string;
+  readonly capabilities: ExecutionCapabilities;
+
+  // Starts a process in a pseudo-terminal of the given size.
+  readonly spawnHarness: (spec: HarnessSpec) => HarnessHandle;
+
+  // Unpacks a tar archive into a directory, creating the directory first.
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- archive bytes have no readonly form
+  readonly transferArchive: (archive: Uint8Array, dir: string) => Promise<void>;
+
+  // Runs a command to completion and returns what it printed.
+  readonly runCommand: (spec: CommandSpec) => Promise<CommandResult>;
+}
+
+/**
+ * What a provider can do. The terminal capabilities split so a host that can
+ * show output but not take input, or not resize, says so; `suspend` and
+ * `destroy` cover the lifecycle of a host that outlives its process.
+ */
+export interface ExecutionCapabilities {
+  // Start a harness in a pseudo-terminal.
+  readonly spawn: boolean;
+
+  // Stream a running harness's output to attached clients.
+  readonly attach: boolean;
+
+  // Write keystrokes to a running harness.
+  readonly input: boolean;
+
+  // Change a running harness's terminal size.
+  readonly resize: boolean;
+
+  // End a running harness.
+  readonly kill: boolean;
+
+  // Unpack an archive into the host's filesystem.
+  readonly transfer: boolean;
+
+  // Run a command on the host to completion.
+  readonly run: boolean;
+
+  // Run an agent turn without a terminal, through the agent's own runner.
+  readonly headless: boolean;
+
+  // Pause the host and resume it later with its state intact.
+  readonly suspend: boolean;
+
+  // Delete the host and everything on it.
+  readonly destroy: boolean;
+}
+
+export type ExecutionCapability = keyof ExecutionCapabilities;
+
+export interface HarnessSpec {
+  readonly bin: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string>>;
+  readonly cols: number;
+  readonly rows: number;
+}
+
+/**
+ * A running harness. Output and exit arrive through listeners, each
+ * subscription detachable on its own.
+ */
+export interface HarnessHandle {
+  readonly onData: (listener: (data: string) => void) => HarnessSubscription;
+  readonly onExit: (listener: (exit: HarnessExit) => void) => HarnessSubscription;
+  readonly write: (data: string) => void;
+  readonly resize: (cols: number, rows: number) => void;
+  readonly kill: () => void;
+}
+
+interface HarnessSubscription {
+  readonly dispose: () => void;
+}
+
+interface HarnessExit {
+  readonly exitCode: number;
+}
+
+export interface CommandSpec {
+  readonly argv: readonly string[];
+  readonly cwd: string;
+}
+
+export interface CommandResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}

package/src/daemon/find-execution-refusal.ts

@@ -0,0 +1,104 @@
+import { DaemonError } from '../protocol/daemon-error';
+import type { TargetConfigError } from '../shared/collect-targets';
+import type { ExecutionTarget } from './build-execution-targets';
+import type { ExecutionCapability } from './execution-provider';
+
+// The target a session runs on and the identity it was bound to there; a
+// null identity is a session not yet bound, which binds to the target as
+// it stands now. A null target is a spawn that names none when the config
+// gives no default.
+interface TargetBinding {
+  readonly target: string | null;
+  readonly targetIdentity: string | null;
+}
+
+/**
+ * The refusal for running work of the given capability on a session's
+ * target, or null when the target serves it. Every path that starts a
+ * harness, writes to one, or runs a headless turn asks this first, so no
+ * path runs a session anywhere but the target it is bound to:
+ *
+ * - `target_config_invalid` when the config file exists but cannot be
+ *   read or parsed, which refuses every target, `local` included; when the
+ *   config's `targets` map, or the target's own entry, is malformed; and
+ *   when there is no target because the config gives no default.
+ * - `unknown_target` when no target holds the id.
+ * - `target_changed` when the target's identity is not the one the session
+ *   was bound to: the name now holds another provider or other options.
+ * - `target_unavailable` when this daemon has no provider of its kind.
+ * - `unsupported_operation` when the provider lacks the capability.
+ */
+export function findExecutionRefusal(
+  targets: ReadonlyMap<string, ExecutionTarget>,
+  errors: readonly TargetConfigError[],
+  binding: TargetBinding,
+  capability: ExecutionCapability,
+): DaemonError | null {
+  const fileError = errors.find((error) => error.scope === 'config');
+
+  if (fileError !== undefined) {
+    return new DaemonError(
+      'target_config_invalid',
+      `config file ${fileError.path} cannot be used (${fileError.problem}: ${fileError.detail}), so no session runs on any target, local included. Fix the file and restart the daemon`,
+      { problem: fileError.problem, path: fileError.path, detail: fileError.detail },
+    );
+  }
+
+  const id = binding.target;
+
+  if (id === null) {
+    const problem =
+      errors.find((error) => error.scope !== 'target')?.problem ??
+      'the targets map holds no local target and no defaultTarget is set';
+
+    return new DaemonError(
+      'target_config_invalid',
+      `no default execution target: ${problem}. Name a target on the spawn, or fix targets in config.json and restart the daemon`,
+      { problem },
+    );
+  }
+
+  const configError = errors.find(
+    (error) => error.scope === 'targets' || (error.scope === 'target' && error.target === id),
+  );
+
+  if (configError !== undefined) {
+    return new DaemonError(
+      'target_config_invalid',
+      `execution target '${id}' cannot be used: ${configError.problem}. Fix targets in config.json and restart the daemon`,
+      { target: id, problem: configError.problem },
+    );
+  }
+
+  const target = targets.get(id);
+
+  if (target === undefined) {
+    return new DaemonError('unknown_target', `no execution target '${id}'`, { target: id });
+  }
+
+  if (binding.targetIdentity !== null && binding.targetIdentity !== target.identity) {
+    return new DaemonError(
+      'target_changed',
+      `execution target '${id}' changed since this session started on it (was ${binding.targetIdentity}, now ${target.identity}). Restore the target's earlier config to use the session, or kill it`,
+      { target: id, boundIdentity: binding.targetIdentity, currentIdentity: target.identity },
+    );
+  }
+
+  if (target.provider === null) {
+    return new DaemonError(
+      'target_unavailable',
+      `execution target '${id}' needs a '${target.kind}' provider, which this daemon does not have`,
+      { target: id, provider: target.kind },
+    );
+  }
+
+  if (!target.provider.capabilities[capability]) {
+    return new DaemonError(
+      'unsupported_operation',
+      `the ${target.provider.kind} execution provider does not support ${capability}`,
+      { provider: target.provider.kind, capability },
+    );
+  }
+
+  return null;
+}

package/src/daemon/idempotency-ledger.ts

@@ -0,0 +1,164 @@
+import { DaemonError } from '../protocol/daemon-error';
+import type { EffectTarget, IdempotencyRecord } from '../store/idempotency-record';
+import type { StateStore } from '../store/state-store';
+import { EffectRemainsError } from './effect-remains-error';
+
+// A request's idempotency key, the hash of the payload it came with, and
+// the principal the request acts as when it is not the ledger's own.
+export interface KeyedRequest {
+  readonly key: string;
+  readonly payloadHash: string;
+  readonly principal?: string;
+}
+
+interface IdempotentCall<T> {
+  readonly operation: string;
+  readonly keyed: KeyedRequest;
+
+  // The id the effect runs under, minted before the claim records it.
+  readonly effectRef: string;
+
+  // Starts the effect. A plain throw means nothing took effect, so the claim
+  // is dropped for a retry to run fresh; an EffectRemainsError means the
+  // effect may still stand, so the claim is kept as outcome_unknown.
+  readonly start: () => T | Promise<T>;
+
+  // Resolves once the effect is durable; the claim completes only after.
+  readonly settle: () => Promise<void>;
+
+  // The answer to a retry of a completed key.
+  readonly replay: (record: IdempotencyRecord) => T | Promise<T>;
+
+  // The target the effect's session is bound to, recorded with the
+  // completed key; absent or null for an effect bound to none.
+  readonly findEffectTarget?: (result: T) => EffectTarget | null;
+}
+
+/**
+ * Runs keyed effects at most once per key for each principal: the
+ * request's own, else the ledger's. The first
+ * request claims the key with its payload's hash and the pre-minted effect
+ * id, runs the effect, and completes the key with its answer once the
+ * effect is durable. A retry with the same payload replays the completed
+ * answer; one with a different payload is `idempotency_conflict`; one whose
+ * effect a stopped daemon may or may not have run is `outcome_unknown` with
+ * the effect id in `data.effectRef`, and never starts the effect again.
+ */
+export class IdempotencyLedger {
+  private readonly store: StateStore;
+
+  private readonly principal: string;
+
+  // One promise chain per key, so two requests under the same key never
+  // interleave their claim and completion on one daemon.
+  private readonly locks = new Map<string, Promise<void>>();
+
+  constructor(store: StateStore, principal: string) {
+    this.store = store;
+    this.principal = principal;
+  }
+
+  async run<T extends Readonly<Record<string, unknown>>>(call: IdempotentCall<T>): Promise<T> {
+    const lockKey = JSON.stringify([
+      call.keyed.principal ?? this.principal,
+      call.operation,
+      call.keyed.key,
+    ]);
+
+    const previous = this.locks.get(lockKey) ?? Promise.resolve();
+    const released = Promise.withResolvers<void>();
+
+    const chained = (async () => {
+      await previous;
+      await released.promise;
+    })();
+
+    this.locks.set(lockKey, chained);
+
+    await previous;
+
+    try {
+      return await this.runClaimed(call);
+    } finally {
+      released.resolve();
+
+      if (this.locks.get(lockKey) === chained) {
+        this.locks.delete(lockKey);
+      }
+    }
+  }
+
+  private async runClaimed<T extends Readonly<Record<string, unknown>>>(
+    call: IdempotentCall<T>,
+  ): Promise<T> {
+    const id = {
+      principal: call.keyed.principal ?? this.principal,
+      operation: call.operation,
+      key: call.keyed.key,
+    };
+
+    const held = await this.store.claimIdempotencyKey({
+      ...id,
+      payloadHash: call.keyed.payloadHash,
+      effectRef: call.effectRef,
+      at: Date.now(),
+    });
+
+    if (held !== null) {
+      return answerHeldKey(call, held);
+    }
+
+    let result: T;
+
+    try {
+      result = await call.start();
+    } catch (error) {
+      if (error instanceof EffectRemainsError) {
+        await this.store.updateIdempotencyOutcomeUnknown(id, Date.now());
+
+        throw new DaemonError(
+          'outcome_unknown',
+          `the ${call.operation} under idempotency key '${call.keyed.key}' failed and its effect may still stand; check ${call.effectRef} before retrying under a new key`,
+          { effectRef: call.effectRef },
+        );
+      }
+
+      await this.store.removeIdempotencyKey(id);
+
+      throw error;
+    }
+
+    // A settle that fails leaves the claim in progress: the effect started,
+    // so the next daemon start marks its outcome unknown rather than letting
+    // a retry run it again.
+    await call.settle();
+
+    await this.store.updateIdempotencyCompleted(
+      id,
+      JSON.stringify(result),
+      Date.now(),
+      call.findEffectTarget?.(result) ?? null,
+    );
+
+    return result;
+  }
+}
+
+function answerHeldKey<T>(call: IdempotentCall<T>, held: IdempotencyRecord): T | Promise<T> {
+  if (held.payloadHash !== call.keyed.payloadHash) {
+    throw new DaemonError(
+      'idempotency_conflict',
+      `idempotency key '${held.key}' was first used with a different ${held.operation} payload`,
+    );
+  }
+
+  if (held.state === 'completed') {
+    return call.replay(held);
+  }
+
+  throw new DaemonError(
+    'outcome_unknown',
+    `the ${held.operation} under idempotency key '${held.key}' was interrupted and may or may not have taken effect; check ${held.effectRef} before retrying under a new key`,
+    { effectRef: held.effectRef },
+  );
+}

package/src/daemon/local-pty-provider.ts

@@ -0,0 +1,83 @@
+import { mkdir } from 'node:fs/promises';
+import { spawn } from 'bun-pty';
+import type {
+  CommandResult,
+  CommandSpec,
+  ExecutionCapabilities,
+  ExecutionProvider,
+  HarnessHandle,
+  HarnessSpec,
+} from './execution-provider';
+
+/**
+ * The `local-pty` provider: harnesses run as child processes of the daemon
+ * on a `bun-pty` pseudo-terminal, and files and commands touch the daemon's
+ * own host. The host is the daemon's machine, so there is nothing to
+ * suspend or destroy.
+ */
+export class LocalPTYProvider implements ExecutionProvider {
+  readonly kind = 'local-pty';
+
+  readonly capabilities: ExecutionCapabilities = {
+    spawn: true,
+    attach: true,
+    input: true,
+    resize: true,
+    kill: true,
+    transfer: true,
+    run: true,
+    headless: true,
+    suspend: false,
+    destroy: false,
+  };
+
+  readonly spawnHarness = (spec: HarnessSpec): HarnessHandle =>
+    spawn(spec.bin, [...spec.args], {
+      name: 'xterm-256color',
+      cols: spec.cols,
+      rows: spec.rows,
+      cwd: spec.cwd,
+      env: { ...spec.env },
+    });
+
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- archive bytes have no readonly form
+  readonly transferArchive = async (archive: Uint8Array, dir: string): Promise<void> => {
+    await mkdir(dir, { recursive: true });
+
+    const result = await this.runCommandWithInput(
+      ['tar', '-x', '-f', '-', '-C', dir],
+      dir,
+      archive,
+    );
+
+    if (result.exitCode !== 0) {
+      throw new Error(`tar exited ${result.exitCode} unpacking into ${dir}: ${result.stderr}`);
+    }
+  };
+
+  readonly runCommand = (spec: CommandSpec): Promise<CommandResult> =>
+    this.runCommandWithInput(spec.argv, spec.cwd, null);
+
+  private async runCommandWithInput(
+    argv: readonly string[],
+    cwd: string,
+
+    // oxlint-disable-next-line prefer-readonly-parameter-types -- input bytes have no readonly form
+    input: Uint8Array | null,
+  ): Promise<CommandResult> {
+    const proc = Bun.spawn([...argv], {
+      cwd,
+      stdin: input ?? 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+
+    return { exitCode, stdout, stderr };
+  }
+}

package/src/daemon/mint-session-id.ts

@@ -1,12 +1,12 @@
+import { randomUUID } from 'node:crypto';
 import type { SessionID } from '../shared/session-id';
 
-let counter = 0;
-
 /**
- * A fresh atc session id: an incrementing counter joined to the current time
- * in base36. Every session the session manager spawns or restores gets one.
+ * A fresh atc session id: a random uuid. Every session the session manager
+ * spawns gets one, and the fleet row keeps it, so the id stays the same
+ * across daemon restarts and fleet restores.
  */
 export function mintSessionID(): SessionID {
   // oxlint-disable-next-line no-unsafe-type-assertion -- this is where atc mints a session id
-  return `s${++counter}-${Date.now().toString(36)}` as SessionID;
+  return randomUUID() as SessionID;
 }

package/src/daemon/parse-spawn-overrides.ts

@@ -0,0 +1,94 @@
+import type { SpawnOverrides } from '../agents/agent-adapter';
+import type { AgentEntry, SpawnOptionEntry } from './build-agent-list';
+
+interface RequestedOverrides {
+  readonly model?: string | undefined;
+  readonly effort?: string | undefined;
+}
+
+interface SpawnRefusal {
+  readonly ok: false;
+  readonly code: 'bad_args' | 'unsupported';
+  readonly message: string;
+}
+
+type ParsedOverrides = { readonly ok: true; readonly overrides: SpawnOverrides } | SpawnRefusal;
+
+/**
+ * Checks a spawn's model and effort against the options the agent list
+ * shows for that agent, so a spawn accepts exactly what `agents.list`
+ * advertises. An option the agent cannot take on this host is unsupported,
+ * never ignored. A value outside an option's closed set, or one that could
+ * pass for a flag, is bad_args.
+ */
+export function parseSpawnOverrides(
+  agent: AgentEntry,
+  requested: RequestedOverrides,
+): ParsedOverrides {
+  const model = requested.model;
+  const effort = requested.effort;
+
+  const refusal =
+    (model === undefined
+      ? null
+      : findOptionRefusal(agent.id, 'model', agent.spawnOptions.model, model)) ??
+    (effort === undefined
+      ? null
+      : findOptionRefusal(agent.id, 'effort', agent.spawnOptions.effort, effort));
+
+  if (refusal !== null) {
+    return refusal;
+  }
+
+  return {
+    ok: true,
+    overrides: {
+      ...(model === undefined ? {} : { model }),
+      ...(effort === undefined ? {} : { effort }),
+    },
+  };
+}
+
+const MAX_VALUE_LENGTH = 200;
+
+// oxlint-disable-next-line no-control-regex -- control characters are what a value is refused for
+const CONTROL_CHARACTER = /[\u0000-\u001F\u007F]/u;
+
+function findOptionRefusal(
+  agentID: string,
+  name: 'model' | 'effort',
+  option: SpawnOptionEntry,
+  value: string,
+): SpawnRefusal | null {
+  if (!option.available) {
+    const reason = option.supported ? 'is not installed on this host' : `takes no ${name}`;
+
+    return { ok: false, code: 'unsupported', message: `agent '${agentID}' ${reason}` };
+  }
+
+  if (value === '' || value.length > MAX_VALUE_LENGTH) {
+    return {
+      ok: false,
+      code: 'bad_args',
+      message: `${name} must be 1 to ${MAX_VALUE_LENGTH} characters`,
+    };
+  }
+
+  if (value.startsWith('-') || CONTROL_CHARACTER.test(value)) {
+    return {
+      ok: false,
+      code: 'bad_args',
+      message: `${name} must not start with '-' or hold control characters`,
+    };
+  }
+
+  if (option.values !== null && !option.values.includes(value)) {
+    return {
+      ok: false,
+      code: 'bad_args',
+      message: `agent '${agentID}' takes ${name} ${option.values.join(', ')}; got '${value}'`,
+    };
+  }
+
+  return null;
+}

package/src/daemon/permission-registry.ts

@@ -30,7 +30,9 @@ export class PermissionRegistry {
 
   private readonly pending = new Map<string, PendingRequest>();
 
-  private readonly resolved = new Set<string>();
+  // Each answered request's session, kept to tell already_answered from
+  // unknown.
+  private readonly resolved = new Map<string, SessionID>();
 
   private counter = 0;
 
@@ -72,6 +74,14 @@ export class PermissionRegistry {
     return 'ok';
   }
 
+  /**
+   * The session a request belongs to, answered or not, or null for a
+   * request this registry never opened.
+   */
+  findSessionID(id: string): SessionID | null {
+    return this.pending.get(id)?.req.sessionID ?? this.resolved.get(id) ?? null;
+  }
+
   answerAll(sessionID: SessionID, decision: string): void {
     for (const [id, entry] of this.pending) {
       if (entry.req.sessionID === sessionID) {
@@ -90,12 +100,12 @@ export class PermissionRegistry {
     clearTimeout(entry.timer);
 
     this.pending.delete(id);
-    this.resolved.add(id);
+    this.resolved.set(id, entry.req.sessionID);
 
-    // The resolved set only exists to tell already_answered from unknown;
+    // The resolved map only exists to tell already_answered from unknown;
     // cap it so a long-lived daemon cannot grow it without bound.
     if (this.resolved.size > 1000) {
-      for (const oldest of this.resolved) {
+      for (const oldest of this.resolved.keys()) {
         this.resolved.delete(oldest);
         break;
       }