@zgeoff/atc 3.3.1 → 3.4.0

package/src/test-utils/setup-mcp-http.ts

@@ -1,30 +1,15 @@
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import type { AgentAdapter } from '../agents/agent-adapter';
 import { DaemonClient } from '../client/daemon-client';
 import { startDaemon } from '../daemon/daemon';
 import type { DaemonHandle } from '../daemon/daemon';
 import { openMCPAuth } from '../mcp/open-mcp-auth';
 import { ReconnectingCaller } from '../mcp/reconnecting-caller';
 import { startMCPHTTPServer } from '../mcp/start-mcp-http-server';
+import { buildMockAgentAdapter } from './build-mock-agent-adapter';
 import { setupTempDir } from './setup-temp-dir';
 
-const SLEEP_ADAPTER: AgentAdapter = {
-  id: 'claude',
-  headlessRunner: null,
-  screenDetector: null,
-  takesMessages: false,
-  planSpawn: () => ({ bin: 'sleep', args: ['30'] }),
-  normalizeHook: () => ({ kind: 'heartbeat' }),
-  loadName: () => Promise.resolve(null),
-  canResume: () => true,
-  buildResumeCommand: () => null,
-};
-
 interface MCPHTTPSetupOptions {
-  // How long a rotated refresh token still answers with its successor.
-  readonly refreshReuseSeconds?: number;
-
   // Further Host header values the server accepts.
   readonly allowedHosts?: readonly string[];
 }
@@ -38,11 +23,14 @@ interface MCPHTTPSetupOptions {
  * `atc clients` and `atc grants` open it, and `addClient` adds a client
  * through it and returns the client id. `restartDaemon` stops the daemon and
  * starts a fresh one on the same socket and database, the way an operator
- * restarts it, with the principals it is given; `countDaemonClients` reads how many connections the current
- * daemon holds open. Hold the result with `await using`.
+ * restarts it, with the principals it is given; `countDaemonClients` reads
+ * how many connections the current daemon holds open. Hold the result with
+ * `await using`.
  */
 export async function setupMCPHTTP(options: MCPHTTPSetupOptions = {}) {
-  const tmp = setupTempDir('atc-mcp-http-');
+  await using stack = new AsyncDisposableStack();
+
+  const tmp = stack.use(setupTempDir('atc-mcp-http-'));
   const socketPath = join(tmp.dir, 'daemon.sock');
   const stateDir = join(tmp.dir, '.local', 'state', 'atc');
 
@@ -57,7 +45,7 @@ export async function setupMCPHTTP(options: MCPHTTPSetupOptions = {}) {
       socketPath,
       reporterSocketPath: join(tmp.dir, 'reporter.sock'),
       build: 'atc/test-build',
-      adapter: SLEEP_ADAPTER,
+      adapter: buildMockAgentAdapter(),
       dbPath: join(tmp.dir, 'state.db'),
       statusPath: join(tmp.dir, 'status.json'),
       principals,
@@ -65,10 +53,14 @@ export async function setupMCPHTTP(options: MCPHTTPSetupOptions = {}) {
 
   let daemon: DaemonHandle = await startTestDaemon();
 
+  stack.defer(() => daemon.stop());
+
   const caller = new ReconnectingCaller(socketPath, 'atc/test-build', (path) =>
     DaemonClient.open(path),
   );
 
+  stack.defer(() => caller.stop());
+
   const server = await startMCPHTTPServer({
     caller,
     build: 'atc/test-build',
@@ -83,13 +75,16 @@ export async function setupMCPHTTP(options: MCPHTTPSetupOptions = {}) {
     printRequest: (line) => {
       requests.push(line);
     },
-    ...(options.refreshReuseSeconds === undefined
-      ? {}
-      : { refreshReuseSeconds: options.refreshReuseSeconds }),
   });
 
+  stack.defer(() => server.stop());
+
   const store = await openMCPAuth({ dbPath, origin: null });
 
+  stack.defer(() => store.close());
+
+  const owned = stack.move();
+
   return {
     home: tmp.dir,
     url: server.url,
@@ -114,13 +109,6 @@ export async function setupMCPHTTP(options: MCPHTTPSetupOptions = {}) {
 
       daemon = await startTestDaemon(principals);
     },
-    async [Symbol.asyncDispose]() {
-      await server.stop();
-      await store.close();
-      await caller.stop();
-      await daemon.stop();
-
-      tmp[Symbol.dispose]();
-    },
+    [Symbol.asyncDispose]: () => owned.disposeAsync(),
   };
 }

package/src/test-utils/spawn-claude-session.ts

@@ -0,0 +1,34 @@
+import { KEYS } from './keys';
+import type { TUIHarness } from './start-tui-harness';
+
+/**
+ * Spawns a Claude session named `name` through the client's spawn flow,
+ * from the home screen or the overlay: the first agent, the first
+ * directory, the name, and no first prompt. Resolves once the fake
+ * `claude` paints, with the capture holding what the client drew since the
+ * prompt step.
+ */
+// oxlint-disable-next-line prefer-readonly-parameter-types -- a harness is a live handle
+export async function spawnClaudeSession(tui: TUIHarness, name: string): Promise<void> {
+  tui.write('n');
+
+  await tui.waitFor('spawn: agent');
+
+  tui.write(KEYS.enter);
+
+  await tui.waitFor('spawn: directory');
+
+  tui.write(KEYS.enter);
+
+  await tui.waitFor('spawn: name');
+
+  tui.reset();
+  tui.write(`${name}${KEYS.enter}`);
+
+  await tui.waitFor('spawn: initial prompt');
+
+  tui.reset();
+  tui.write(KEYS.enter);
+
+  await tui.waitFor('FAKE_CLAUDE_UP');
+}

package/src/test-utils/spawn-grok-session.ts

@@ -0,0 +1,39 @@
+import { KEYS } from './keys';
+import type { TUIHarness } from './start-tui-harness';
+
+/**
+ * Spawns a Grok session named `name` through the client's spawn flow, from
+ * the home screen or the overlay: Grok, the second agent, then the first
+ * directory, the name, and no first prompt. Resolves once the fake `grok`
+ * paints, with the capture holding what the client drew since the prompt
+ * step.
+ */
+// oxlint-disable-next-line prefer-readonly-parameter-types -- a harness is a live handle
+export async function spawnGrokSession(tui: TUIHarness, name: string): Promise<void> {
+  tui.write('n');
+
+  await tui.waitFor('spawn: agent');
+
+  tui.reset();
+  tui.write(KEYS.down);
+
+  await tui.waitFor('\u001B[7mGrok');
+
+  tui.write(KEYS.enter);
+
+  await tui.waitFor('spawn: directory');
+
+  tui.write(KEYS.enter);
+
+  await tui.waitFor('spawn: name');
+
+  tui.reset();
+  tui.write(`${name}${KEYS.enter}`);
+
+  await tui.waitFor('spawn: initial prompt');
+
+  tui.reset();
+  tui.write(KEYS.enter);
+
+  await tui.waitFor('FAKE_GROK_UP');
+}

package/src/test-utils/start-cut-proxy.ts

@@ -20,7 +20,11 @@ export interface CutProxy {
 
   // How many requests of the method the proxy has seen.
   readonly countRequests: () => number;
+
+  // How many answers the proxy has swallowed in hold mode.
+  readonly countHeld: () => number;
   readonly stop: () => void;
+  readonly [Symbol.dispose]: () => void;
 }
 
 // One proxied connection: the target side once it is connected, what the
@@ -33,6 +37,9 @@ interface ProxyLink {
   lineBuffer: string;
   cutting: boolean;
   held: boolean;
+
+  // Counts an answer the link swallows in hold mode.
+  readonly onHold: () => void;
 }
 
 /**
@@ -44,6 +51,7 @@ interface ProxyLink {
 export function startCutProxy(options: CutProxyOptions): CutProxy {
   let cutsLeft = options.cuts;
   let requests = 0;
+  let held = 0;
 
   const links = new Set<Socket<ProxyLink>>();
 
@@ -59,6 +67,9 @@ export function startCutProxy(options: CutProxyOptions): CutProxy {
           lineBuffer: '',
           cutting: false,
           held: false,
+          onHold: () => {
+            held++;
+          },
         };
 
         links.add(client);
@@ -110,17 +121,21 @@ export function startCutProxy(options: CutProxyOptions): CutProxy {
     },
   });
 
+  const stop = () => {
+    for (const client of links) {
+      client.end();
+      client.data.upstream?.end();
+    }
+
+    server.stop(true);
+  };
+
   return {
     port: server.port,
     countRequests: () => requests,
-    stop() {
-      for (const client of links) {
-        client.end();
-        client.data.upstream?.end();
-      }
-
-      server.stop(true);
-    },
+    countHeld: () => held,
+    stop,
+    [Symbol.dispose]: stop,
   };
 }
 
@@ -149,6 +164,8 @@ async function openUpstream(client: Socket<ProxyLink>, options: CutProxyOptions)
           if (options.mode === 'hold') {
             client.data.held = true;
 
+            client.data.onHold();
+
             return;
           }
 

package/src/test-utils/start-daemon-process.ts

@@ -0,0 +1,192 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Subprocess } from 'bun';
+import { DaemonClient } from '../client/daemon-client';
+import { findDaemonRecord } from '../shared/find-daemon-record';
+import { waitFor } from './wait-for';
+
+interface DaemonProcessConfig {
+  // The command atc runs as, such as the source entry under bun or a
+  // compiled binary.
+  readonly command: readonly string[];
+
+  // HOME and XDG_RUNTIME_DIR of the daemon, so its config, state, and
+  // sockets all sit under this directory.
+  readonly home: string;
+
+  // Variables laid over the inherited environment and the default PATH;
+  // `undefined` removes one.
+  readonly env?: Readonly<Record<string, string | undefined>>;
+
+  // Arguments after `atc daemon`.
+  readonly args?: readonly string[];
+}
+
+/**
+ * One boot of the daemon: its process and the file its stderr goes to.
+ */
+interface DaemonBoot {
+  readonly proc: Subprocess;
+  readonly stderrPath: string;
+}
+
+/**
+ * Starts `atc daemon` as its own process on a home, with the test's
+ * environment, HOME and XDG_RUNTIME_DIR at the home, and a PATH of the system
+ * directories alone unless the config's variables set another. It returns at
+ * once; `openClient` waits up to 15 seconds for the socket and connects,
+ * sending no handshake, and fails at once with the daemon's stderr when the
+ * daemon exits before it listens. `restart` stops the daemon with the given
+ * signal, waits for it to exit, and starts another on the same home with the
+ * same config. `readStderr` reads what the current boot printed. Disposal
+ * closes every client it opened, kills the daemon and waits for it to exit,
+ * then kills the daemon the home's state directory records, which a restart
+ * the test asked atc for may have started; a second disposal does nothing.
+ */
+export function startDaemonProcess(config: Readonly<DaemonProcessConfig>) {
+  const socketPath = join(config.home, 'atc-daemon.sock');
+  const stateDir = join(config.home, '.local', 'state', 'atc');
+
+  const clients = new Set<DaemonClient>();
+
+  let boots = 0;
+  let disposed = false;
+
+  const boot = (): DaemonBoot => {
+    boots++;
+
+    const stderrPath = join(config.home, `daemon-${boots}.stderr`);
+
+    const proc = Bun.spawn([...config.command, 'daemon', ...(config.args ?? [])], {
+      env: Object.fromEntries(
+        Object.entries({
+          ...process.env,
+          HOME: config.home,
+          XDG_RUNTIME_DIR: config.home,
+          PATH: '/usr/sbin:/usr/bin:/bin',
+          ...config.env,
+        }).filter((entry): entry is [string, string] => entry[1] !== undefined),
+      ),
+      stdout: 'ignore',
+      stderr: Bun.file(stderrPath),
+    });
+
+    return { proc, stderrPath };
+  };
+
+  let current = boot();
+
+  const readStderr = () => {
+    try {
+      return readFileSync(current.stderrPath, 'utf8');
+    } catch {
+      return '';
+    }
+  };
+
+  // A client that opens after the wait for it ended, or after disposal,
+  // closes at once, so nothing outlives the daemon it reached.
+  const openTrackedClient = async (isAbandoned: () => boolean) => {
+    const client = await DaemonClient.open(socketPath);
+
+    if (disposed || isAbandoned()) {
+      client.stop();
+      throw new Error('the wait for the daemon ended before this client opened');
+    }
+
+    clients.add(client);
+
+    return client;
+  };
+
+  const openClient = async (): Promise<DaemonClient> => {
+    const watched = current.proc;
+    let settled = false;
+    const isSettled = () => settled;
+
+    // A daemon that has exited either refused to start or handed its socket
+    // to a replacement, so one more connect tells the two apart.
+    const openAfterExit = async () => {
+      await watched.exited;
+
+      if (settled || disposed) {
+        return null;
+      }
+
+      try {
+        return await openTrackedClient(isSettled);
+      } catch {
+        throw new Error(
+          `the daemon exited (${String(watched.exitCode ?? watched.signalCode)}) before it listened:\n${readStderr()}`,
+        );
+      }
+    };
+
+    // Polls the socket while the daemon runs. Once the other wait settles or
+    // the daemon is disposed, each attempt resolves empty, which ends the
+    // polling.
+    const openWhenListening = () =>
+      waitFor(() => (settled || disposed ? null : openTrackedClient(isSettled)), {
+        timeoutMs: 15_000,
+        intervalMs: 50,
+      });
+
+    const hasExited = watched.exitCode !== null || watched.signalCode !== null;
+
+    try {
+      const client = await (hasExited
+        ? openAfterExit()
+        : Promise.race([openWhenListening(), openAfterExit()]));
+
+      if (client === null) {
+        throw new Error('the wait for the daemon settled without a client');
+      }
+
+      return client;
+    } finally {
+      settled = true;
+    }
+  };
+
+  return {
+    home: config.home,
+    socketPath,
+    reporterSocketPath: join(config.home, 'atc.sock'),
+    stateDir,
+    get proc(): Subprocess {
+      return current.proc;
+    },
+    readStderr,
+    openClient,
+    async restart(signal: NodeJS.Signals): Promise<void> {
+      current.proc.kill(signal);
+
+      await current.proc.exited;
+
+      current = boot();
+    },
+    async [Symbol.asyncDispose](): Promise<void> {
+      if (disposed) {
+        return;
+      }
+
+      disposed = true;
+
+      for (const client of clients) {
+        client.stop();
+      }
+
+      current.proc.kill('SIGKILL');
+
+      await current.proc.exited;
+
+      const recorded = findDaemonRecord(join(stateDir, 'daemon.json'));
+
+      if (recorded !== null && recorded.pid !== current.proc.pid) {
+        try {
+          process.kill(recorded.pid, 'SIGKILL');
+        } catch {}
+      }
+    },
+  };
+}

package/src/test-utils/start-git-http-server.ts

@@ -5,6 +5,18 @@ interface GitHTTPServer {
   // Every Authorization header a request carried, in arrival order.
   readonly authorizations: string[];
   readonly stop: () => Promise<void>;
+  readonly [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+interface GitHTTPServerOptions {
+  // How long each authenticated request waits before it is served.
+  readonly delayMs?: number;
+
+  // Waits out the delay; a timer unless given.
+  readonly wait?: (ms: number) => Promise<void>;
+
+  // Runs, and is awaited, while each authenticated request is held.
+  readonly onRequest?: () => Promise<void> | void;
 }
 
 /**
@@ -13,13 +25,16 @@ interface GitHTTPServer {
  * carries no basic auth, so a client only clones by authenticating. The
  * backend runs with the environment it is given. With a delay, each
  * authenticated request waits that long before it is served, which makes a
- * clone through it slow.
+ * clone through it slow. An `onRequest` callback runs, and is awaited, while
+ * each authenticated request is held, so it sees the client that sent the
+ * request still running. Stop it with `stop`, or hold it with `await using`.
  */
 export function startGitHTTPServer(
   root: string,
   env: Readonly<Record<string, string | undefined>>,
-  options: { readonly delayMs?: number } = {},
+  options: GitHTTPServerOptions = {},
 ): GitHTTPServer {
+  const wait = options.wait ?? Bun.sleep;
   const authorizations: string[] = [];
 
   const server = Bun.serve({
@@ -38,9 +53,11 @@ export function startGitHTTPServer(
       authorizations.push(authorization);
 
       if (options.delayMs !== undefined) {
-        await Bun.sleep(options.delayMs);
+        await wait(options.delayMs);
       }
 
+      await options.onRequest?.();
+
       const url = new URL(request.url);
 
       const body = await request.arrayBuffer();
@@ -74,6 +91,7 @@ export function startGitHTTPServer(
     url: `http://127.0.0.1:${server.port}/`,
     authorizations,
     stop: () => server.stop(true),
+    [Symbol.asyncDispose]: () => server.stop(true),
   };
 }
 

package/src/test-utils/start-mcp-stdio.ts

@@ -0,0 +1,195 @@
+import { join } from 'node:path';
+import { isRecord } from '../shared/report';
+
+const CLI_PATH = join(import.meta.dir, '..', 'cli.ts');
+
+interface MCPStdioOptions {
+  // The home the server runs with, as its `HOME` and `XDG_RUNTIME_DIR`.
+  readonly home: string;
+
+  // The session id the server sees itself running inside; absent means a
+  // server started outside any session.
+  readonly callerSessionID?: string;
+
+  // A command that stands in for `atc mcp`; absent means this checkout's
+  // `atc mcp`.
+  readonly command?: readonly string[];
+}
+
+/**
+ * One tool call's result as the server returned it: `isError` as sent,
+ * `structured` as its `structuredContent`, and the text of its only content
+ * item.
+ */
+interface MCPToolResult {
+  readonly isError: unknown;
+  readonly text: string;
+  readonly structured: Readonly<Record<string, unknown>> | undefined;
+}
+
+/**
+ * `atc mcp` from this checkout, run as a subprocess over stdio, with an
+ * `initialize` already answered, so the daemon the server boots or joins is
+ * up. `sendRequest` sends one JSON-RPC request under the next id and
+ * resolves with its whole response. `sendToolCall` sends `tools/call` and
+ * resolves with the result, rejecting when the response holds no result, the
+ * result holds anything but one text item, or its structured content is not
+ * an object. `spawnSession` spawns through `atc_session_spawn` and resolves
+ * with the new session's id. A request still unanswered when the server's
+ * stdout ends rejects. When `initialize` fails, the server is stopped
+ * before the start rejects. Disposal stops the server and waits for it to exit,
+ * and a second disposal waits for the same exit; the daemon stays up for
+ * the home to stop.
+ */
+export async function startMCPStdio(options: MCPStdioOptions) {
+  const proc = Bun.spawn([...(options.command ?? [process.execPath, CLI_PATH, 'mcp'])], {
+    env: {
+      ...process.env,
+      HOME: options.home,
+      XDG_RUNTIME_DIR: options.home,
+      PATH: '/usr/sbin:/usr/bin:/bin',
+      ATC_SESSION_ID: options.callerSessionID ?? '',
+      ATC_TAP_GRACE_MS: '0',
+    },
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'ignore',
+  });
+
+  const pending = new Map<number, PromiseWithResolvers<Readonly<Record<string, unknown>>>>();
+
+  void readResponses(proc.stdout, pending);
+  let nextID = 0;
+
+  const sendRequest = (
+    method: string,
+    params?: Readonly<Record<string, unknown>>,
+  ): Promise<Readonly<Record<string, unknown>>> => {
+    nextID += 1;
+
+    const id = nextID;
+    const response = Promise.withResolvers<Readonly<Record<string, unknown>>>();
+
+    pending.set(id, response);
+
+    void proc.stdin.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id, method, ...(params === undefined ? {} : { params }) })}\n`,
+    );
+
+    void proc.stdin.flush();
+
+    return response.promise;
+  };
+
+  const sendToolCall = async (
+    name: string,
+    args: Readonly<Record<string, unknown>>,
+  ): Promise<MCPToolResult> => {
+    const response = await sendRequest('tools/call', { name, arguments: args });
+
+    return toToolResult(response);
+  };
+
+  let stopped = false;
+
+  const stopServer = async (): Promise<void> => {
+    if (!stopped) {
+      stopped = true;
+      void proc.stdin.end();
+      proc.kill();
+    }
+
+    await proc.exited;
+  };
+
+  // A failed initialize stops the server here, before the caller holds it.
+  await using stack = new AsyncDisposableStack();
+
+  stack.defer(stopServer);
+
+  const server = {
+    sendRequest,
+    sendToolCall,
+    async spawnSession(args: Readonly<Record<string, unknown>>): Promise<string> {
+      const spawned = await sendToolCall('atc_session_spawn', args);
+
+      const id = spawned.structured?.['id'];
+
+      if (typeof id !== 'string') {
+        throw new TypeError(`spawn returned no session id: ${spawned.text}`);
+      }
+
+      return id;
+    },
+    [Symbol.asyncDispose]: stopServer,
+  };
+
+  await sendRequest('initialize', {
+    protocolVersion: '2025-06-18',
+    capabilities: {},
+    clientInfo: { name: 'atc-test' },
+  });
+
+  stack.move();
+
+  return server;
+}
+
+/**
+ * Reads the server's stdout as JSON-RPC lines and resolves the pending
+ * request each response's id matches. Once stdout ends, or holds a line that
+ * is not JSON, every request not yet resolved rejects.
+ */
+async function readResponses(
+  stdout: Readonly<ReadableStream<Uint8Array>>,
+  pending: ReadonlyMap<number, PromiseWithResolvers<Readonly<Record<string, unknown>>>>,
+): Promise<void> {
+  const decoder = new TextDecoder('utf-8');
+
+  let buffer = '';
+
+  try {
+    for await (const chunk of stdout) {
+      buffer += decoder.decode(chunk, { stream: true });
+
+      const lines = buffer.split('\n');
+
+      buffer = lines.pop() ?? '';
+
+      for (const line of lines.filter((candidate) => candidate.trim() !== '')) {
+        const parsed: unknown = JSON.parse(line);
+        const id = isRecord(parsed) ? parsed['id'] : undefined;
+        const waiting = typeof id === 'number' ? pending.get(id) : undefined;
+
+        if (isRecord(parsed) && waiting !== undefined) {
+          waiting.resolve(parsed);
+        }
+      }
+    }
+  } catch {
+    // A line that is not JSON ends the reading; the requests still pending
+    // reject below.
+  } finally {
+    for (const [id, waiting] of pending) {
+      waiting.reject(new Error(`atc mcp stopped answering before request ${id}`));
+    }
+  }
+}
+
+function toToolResult(response: Readonly<Record<string, unknown>>): MCPToolResult {
+  const result = response['result'];
+  const content = isRecord(result) ? result['content'] : undefined;
+  const item: unknown = Array.isArray(content) && content.length === 1 ? content[0] : undefined;
+  const structured = isRecord(result) ? result['structuredContent'] : undefined;
+
+  if (
+    !isRecord(result) ||
+    !isRecord(item) ||
+    typeof item['text'] !== 'string' ||
+    (structured !== undefined && !isRecord(structured))
+  ) {
+    throw new TypeError(`tool call returned an unexpected result: ${JSON.stringify(response)}`);
+  }
+
+  return { isError: result['isError'], text: item['text'], structured };
+}