@zgeoff/atc 3.3.1 → 3.4.1

package/src/test-utils/create-stub-bin.ts

@@ -0,0 +1,19 @@
+import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Creates a stand-in command-line tool: the script, shebang included, as an
+ * executable file under the directory, which it creates when missing.
+ * Returns the script's path. Writing over an existing file replaces its
+ * content and makes it executable as well, so a test can swap a tool's
+ * behaviour mid-run.
+ */
+export function createStubBin(dir: string, name: string, script: string): string {
+  const path = join(dir, name);
+
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, script);
+  chmodSync(path, 0o755);
+
+  return path;
+}

package/src/test-utils/create-stub-claude.ts

@@ -0,0 +1,75 @@
+import { createStubBin } from './create-stub-bin';
+
+interface StubClaudeConfig {
+  // The command atc runs as, which the stub's tap and restart go through.
+  readonly atc: readonly string[];
+
+  // The composer script the stub finishes in when the home asks for it.
+  readonly composer: string;
+}
+
+/**
+ * Creates a stand-in for the Claude CLI as `fake-claude` under the
+ * directory and returns its path. Like the real CLI, it runs the
+ * `SessionStart` hook command from the `--settings` file atc passed it
+ * through a shell, feeding each hook its JSON payload on stdin, so a session
+ * reports with the command line atc wrote for its agent. It prints its
+ * arguments, its TERM, and whether it inherited a parent-session variable,
+ * appends its atc session id to `$HOME/fake-claude-starts.log`, reports a
+ * `SessionStart` as `fake-1` and a `Notification` asking for permission, then
+ * echoes each input line as `GOT:<line>`.
+ *
+ * Files in `$HOME` steer a scenario: `fake-claude-dies-<id>` exits at once
+ * when the stub resumes that agent session; `fake-claude-hold-start` reports
+ * nothing and only echoes input; `fake-claude-composer` runs the composer
+ * instead; `fake-claude-gate` waits for one input line before it reports,
+ * and the first stub to find it removes it; `fake-claude-own-id` reports the
+ * atc session id as the agent session; `fake-claude-restart` runs
+ * `atc daemon restart` into `$HOME/restart.out` after `SessionStart`, and the
+ * first stub to find it removes it; `fake-claude-tap` runs `atc tap` into
+ * `$HOME/tap.jsonl`; `fake-claude-events.jsonl` holds more hook payloads to
+ * report, one per line, after the `Notification`; `fake-claude-exit` exits
+ * once they are reported.
+ */
+export function createStubClaude(dir: string, config: StubClaudeConfig): string {
+  const atc = config.atc.map((part) => `"${part}"`).join(' ');
+
+  return createStubBin(
+    dir,
+    'fake-claude',
+    `#!/usr/bin/env bash
+echo "FAKE_CLAUDE_UP args: $@"
+echo "FAKE_CLAUDE_TERM:[\${TERM-unset}]"
+echo "FAKE_CLAUDE_PARENT:[\${CLAUDE_CODE_ATC_TEST-unset}]"
+echo "$ATC_SESSION_ID" >> "$HOME/fake-claude-starts.log"
+settings=""
+resume=""
+prev=""
+for arg in "$@"; do
+  if [ "$prev" = "--settings" ]; then settings="$arg"; fi
+  if [ "$prev" = "--resume" ]; then resume="$arg"; fi
+  prev="$arg"
+done
+if [ -n "$resume" ] && [ -f "$HOME/fake-claude-dies-$resume" ]; then exit 0; fi
+if [ -f "$HOME/fake-claude-hold-start" ]; then while read -r line; do echo "GOT:$line"; done; exit 0; fi
+if [ -f "$HOME/fake-claude-composer" ]; then exec "${process.execPath}" "${config.composer}"; fi
+hookCommand="$("${process.execPath}" -e 'const s = JSON.parse(require("fs").readFileSync(process.argv.at(-1), "utf8")); console.log(s.hooks.SessionStart[0].hooks[0].command)' "$settings" < /dev/null)"
+hookReport() { sh -c "$hookCommand"; }
+sessionID="fake-1"
+if [ -f "$HOME/fake-claude-own-id" ]; then sessionID="$ATC_SESSION_ID"; fi
+if [ -f "$HOME/fake-claude-gate" ]; then rm "$HOME/fake-claude-gate"; read -r _; fi
+printf '{"hook_event_name":"SessionStart","session_id":"%s","transcript_path":"%s/fake-transcript.jsonl"}' "$sessionID" "$HOME" | hookReport
+if [ -f "$HOME/fake-claude-restart" ]; then rm "$HOME/fake-claude-restart"; ${atc} daemon restart > "$HOME/restart.out" 2>&1; fi
+if [ -f "$HOME/fake-claude-tap" ]; then ${atc} tap --session "$ATC_SESSION_ID" >> "$HOME/tap.jsonl" & fi
+printf '{"hook_event_name":"Notification","session_id":"%s","message":"needs permission"}' "$sessionID" | hookReport
+if [ -f "$HOME/fake-claude-events.jsonl" ]; then
+  while IFS= read -r ev; do
+    [ -n "$ev" ] || continue
+    printf '%s' "$ev" | hookReport
+  done < "$HOME/fake-claude-events.jsonl"
+fi
+if [ -f "$HOME/fake-claude-exit" ]; then exit 0; fi
+while read -r line; do echo "GOT:$line"; done
+`,
+  );
+}

package/src/test-utils/create-stub-codex.ts

@@ -0,0 +1,31 @@
+import { createStubBin } from './create-stub-bin';
+
+interface StubCodexConfig {
+  // The command atc runs as; the stub reports each hook through its
+  // `hook-report --agent codex`, as the hook entries atc prints for Codex do.
+  readonly atc: readonly string[];
+
+  // The composer script the stub finishes in.
+  readonly composer: string;
+}
+
+/**
+ * Creates a stand-in for the Codex CLI as `fake-codex` under the directory
+ * and returns its path. It prints its arguments, reports a `SessionStart`
+ * as `fake-codex-1` with its working directory and a rollout under `$HOME`,
+ * then a `Stop` whose last message is `pong`, then runs the composer.
+ */
+export function createStubCodex(dir: string, config: StubCodexConfig): string {
+  const report = `${config.atc.map((part) => `"${part}"`).join(' ')} hook-report --agent codex`;
+
+  return createStubBin(
+    dir,
+    'fake-codex',
+    `#!/usr/bin/env bash
+echo "FAKE_CODEX_UP args: $@"
+printf '{"hook_event_name":"SessionStart","session_id":"fake-codex-1","transcript_path":"%s/fake-rollout.jsonl","cwd":"%s","source":"startup"}' "$HOME" "$PWD" | ${report}
+printf '{"hook_event_name":"Stop","session_id":"fake-codex-1","transcript_path":"%s/fake-rollout.jsonl","last_assistant_message":"pong"}' "$HOME" | ${report}
+exec "${process.execPath}" "${config.composer}"
+`,
+  );
+}

package/src/test-utils/create-stub-composer.ts

@@ -0,0 +1,65 @@
+import { createStubBin } from './create-stub-bin';
+
+/**
+ * Creates the composer the stub agents finish in, as `fake-composer.js`
+ * under the directory, and returns its path; run it with bun. It is modelled
+ * on the TUIs Codex and Grok draw: raw mode with bracketed paste on. Each
+ * read is one input event batch. A bracketed paste lands in the composer
+ * whole, newlines kept; a lone CR outside a paste submits; a lone LF is
+ * Ctrl-J and adds a newline; any other read of more than one byte is a paste
+ * burst whose line breaks stay in the composer. A read that ends partway
+ * into a paste marker holds that part for the next read. It prints
+ * `FAKE_COMPOSER_READY` once paste mode is on, every byte received so far as
+ * `RECEIVED:<json>` after each read, and each submission as `SUBMIT:<json>`.
+ */
+export function createStubComposer(dir: string): string {
+  return createStubBin(
+    dir,
+    'fake-composer.js',
+    String.raw`const OPEN = '\u001B[200~';
+const CLOSE = '\u001B[201~';
+let composer = '';
+let pasting = false;
+let held = '';
+let received = '';
+process.stdin.setRawMode(true);
+process.stdout.write('\u001B[?2004hFAKE_COMPOSER_READY\r\n');
+process.stdin.on('data', (buf) => {
+  const chunk = buf.toString('utf8');
+  received += chunk;
+  process.stdout.write('RECEIVED:' + JSON.stringify(received) + '\r\n');
+  let rest = held + chunk;
+  held = '';
+  const cut = rest.lastIndexOf('\u001B');
+  const tail = cut === -1 ? '' : rest.slice(cut);
+  if (tail !== '' && tail.length < CLOSE.length && (OPEN.startsWith(tail) || CLOSE.startsWith(tail))) {
+    held = tail;
+    rest = rest.slice(0, cut);
+  }
+  while (rest !== '') {
+    if (pasting) {
+      const end = rest.indexOf(CLOSE);
+      composer += (end === -1 ? rest : rest.slice(0, end)).replaceAll('\r', '\n');
+      pasting = end === -1;
+      rest = end === -1 ? '' : rest.slice(end + CLOSE.length);
+      continue;
+    }
+    if (rest.startsWith(OPEN)) {
+      pasting = true;
+      rest = rest.slice(OPEN.length);
+      continue;
+    }
+    const next = rest.indexOf(OPEN);
+    const plain = next === -1 ? rest : rest.slice(0, next);
+    rest = next === -1 ? '' : rest.slice(next);
+    if (plain === '\r') {
+      process.stdout.write('SUBMIT:' + JSON.stringify(composer) + '\r\n');
+      composer = '';
+    } else {
+      composer += plain.replaceAll('\r', '\n');
+    }
+  }
+});
+`,
+  );
+}

package/src/test-utils/create-stub-echo-claude.ts

@@ -0,0 +1,21 @@
+import { createStubBin } from './create-stub-bin';
+
+/**
+ * Creates a stand-in for the Claude CLI as `fake-claude` under the directory
+ * and returns its path. It prints `UP:<pid>`, then reads one line at a time
+ * and prints `GOT:<line>:<pid>` after each, so a test sees which process
+ * took its input. A `quit` line ends it with exit code 3.
+ */
+export function createStubEchoClaude(dir: string): string {
+  return createStubBin(
+    dir,
+    'fake-claude',
+    `#!/usr/bin/env bash
+echo "UP:$$"
+while read -r line; do
+  if [ "$line" = "quit" ]; then exit 3; fi
+  echo "GOT:$line:$$"
+done
+`,
+  );
+}

package/src/test-utils/create-stub-failing-agent-adapter.ts

@@ -0,0 +1,111 @@
+import type { AgentAdapter } from '../agents/agent-adapter';
+import { buildMockAgentAdapter } from './build-mock-agent-adapter';
+
+interface Plan {
+  readonly bin: string;
+  readonly args: readonly string[];
+}
+
+// A named pipe the first spawn's process writes its pid to once it is ready
+// to be killed, and how long the first failing read waits for that pid.
+interface ReadyPipe {
+  readonly path: string;
+  readonly timeoutMs: number;
+}
+
+interface FailingAgentAdapterConfig {
+  // What the first spawn runs, and what every later spawn runs.
+  readonly firstPlan: Plan;
+  readonly laterPlan: Plan;
+
+  // How many reads of the headless runner throw once the first spawn is
+  // planned: one fails the start after its process started, and a second
+  // fails the kill that takes the process back.
+  readonly failedReads: number;
+
+  // The pipe the first failing read waits on. Null fails at once.
+  readonly ready: ReadyPipe | null;
+}
+
+/**
+ * An agent adapter whose first spawn fails after its process has started:
+ * the daemon reads the adapter's headless runner once the process runs, and
+ * that read throws, as many times as the config holds, while every other
+ * read finds no headless runner. Every member but the spawn plan and the
+ * headless runner is the mock adapter's.
+ *
+ * With a ready pipe, the stub makes the pipe at that path, and the first
+ * failing read blocks until a process writes its pid there, which the
+ * headless runner read is synchronous for. A read that finds no writer
+ * within the timeout throws instead of failing the start. `getReadyPID`
+ * returns the pid that read took. `countPlans` reads how many spawns the
+ * adapter has planned.
+ */
+export function createStubFailingAgentAdapter(config: FailingAgentAdapterConfig) {
+  let planned = 0;
+  let readsToFail = 0;
+  let readyPID: number | null = null;
+
+  if (config.ready !== null) {
+    createPipe(config.ready.path);
+  }
+
+  const adapter: AgentAdapter = {
+    ...buildMockAgentAdapter(),
+    planSpawn: () => {
+      planned += 1;
+
+      if (planned > 1) {
+        return { bin: config.laterPlan.bin, args: [...config.laterPlan.args] };
+      }
+
+      readsToFail = config.failedReads;
+
+      return { bin: config.firstPlan.bin, args: [...config.firstPlan.args] };
+    },
+    get headlessRunner() {
+      if (readsToFail === 0) {
+        return null;
+      }
+
+      if (readsToFail === config.failedReads && config.ready !== null) {
+        readyPID = readPID(config.ready);
+      }
+
+      readsToFail -= 1;
+      throw new Error('adapter failed after the process started');
+    },
+  };
+
+  return {
+    adapter,
+    countPlans: () => planned,
+    getReadyPID: (): number => {
+      if (readyPID === null) {
+        throw new Error('no process has written its pid to the ready pipe');
+      }
+
+      return readyPID;
+    },
+  };
+}
+
+function createPipe(path: string): void {
+  const made = Bun.spawnSync(['mkfifo', path]);
+
+  if (made.exitCode !== 0) {
+    throw new Error(`mkfifo could not make ${path} (${made.stderr.toString().trim()})`);
+  }
+}
+
+// Reading the pipe blocks until a writer opens it and closes it, so the
+// read returns once the process has written its pid.
+function readPID(ready: ReadyPipe): number {
+  const read = Bun.spawnSync({ cmd: ['cat', ready.path], timeout: ready.timeoutMs });
+
+  if (read.exitedDueToTimeout === true) {
+    throw new Error(`no process wrote ${ready.path} within ${String(ready.timeoutMs)}ms`);
+  }
+
+  return Number(read.stdout.toString().trim());
+}

package/src/test-utils/create-stub-grok.ts

@@ -0,0 +1,44 @@
+import { createStubBin } from './create-stub-bin';
+
+interface StubGrokConfig {
+  // The command atc runs as; the stub reports each hook through its
+  // `hook-report --agent grok`, as the hook file atc prints for Grok does.
+  readonly atc: readonly string[];
+
+  // The composer script the stub finishes in.
+  readonly composer: string;
+}
+
+/**
+ * Creates a stand-in for the Grok CLI as `fake-grok` under the directory and
+ * returns its path. It prints its arguments, reports a `session_start` as
+ * `fake-grok-1` with its working directory and a `notification` asking
+ * permission to edit, prints `FAKE_GROK_HOOKS_DONE` once its reports are
+ * sent, then runs the composer. Files in `$HOME` steer a scenario:
+ * `fake-grok-hold-start` reports nothing and only echoes input lines as
+ * `GOT:<line>`; `fake-grok-events.jsonl` holds the hook payloads to report
+ * after `session_start` in place of the notification, one per line.
+ */
+export function createStubGrok(dir: string, config: StubGrokConfig): string {
+  const report = `${config.atc.map((part) => `"${part}"`).join(' ')} hook-report --agent grok`;
+
+  return createStubBin(
+    dir,
+    'fake-grok',
+    `#!/usr/bin/env bash
+echo "FAKE_GROK_UP args: $@"
+if [ -f "$HOME/fake-grok-hold-start" ]; then while read -r line; do echo "GOT:$line"; done; exit 0; fi
+printf '{"hookEventName":"session_start","sessionId":"fake-grok-1","cwd":"%s"}' "$PWD" | ${report}
+if [ -f "$HOME/fake-grok-events.jsonl" ]; then
+  while IFS= read -r ev; do
+    [ -n "$ev" ] || continue
+    printf '%s' "$ev" | ${report}
+  done < "$HOME/fake-grok-events.jsonl"
+else
+  printf '{"hookEventName":"notification","sessionId":"fake-grok-1","notificationType":"permission_prompt","message":"allow edit?"}' | ${report}
+fi
+echo "FAKE_GROK_HOOKS_DONE"
+exec "${process.execPath}" "${config.composer}"
+`,
+  );
+}

package/src/test-utils/create-stub-guest-clis.ts

@@ -0,0 +1,55 @@
+import { join } from 'node:path';
+import { createStubBin } from './create-stub-bin';
+
+/**
+ * Creates the command-line tools a remote host runs for a session, as
+ * scripts under the directory: `atc` runs the atc CLI from this source tree,
+ * and `claude` is a stand-in agent that prints `UP:<pid>`, then reads one
+ * command per line and prints `GOT:<line>` after each, reporting through
+ * that atc:
+ *
+ * - `start <id>`: a SessionStart for agent session `<id>`, with a
+ *   transcript at a path only the host holds;
+ * - `notify <text>`: a Notification carrying the text;
+ * - `nested <id>`: a SessionStart for agent session `<id>` from a Codex
+ *   harness nested inside the session;
+ * - `forge <session>`: a Notification as atc session `<session>` instead
+ *   of its own;
+ * - `tap <file>`: the session's tap, run in the background and printing
+ *   into the file;
+ * - `answer <message> <text>`: the message answered with the text;
+ * - `note <text>`: a note labelled `progress`.
+ *
+ * Returns each tool's path.
+ */
+export function createStubGuestCLIs(dir: string) {
+  const cliPath = join(import.meta.dir, '..', 'cli.ts');
+
+  const atc = createStubBin(
+    dir,
+    'atc',
+    `#!/bin/sh\nexec "${process.execPath}" "${cliPath}" "$@"\n`,
+  );
+
+  const claude = createStubBin(
+    dir,
+    'claude',
+    `#!/usr/bin/env bash
+echo "UP:$$"
+while read -r line; do
+  case "$line" in
+    start\\ *) printf '{"hook_event_name":"SessionStart","session_id":"%s","transcript_path":"/guest/only/transcript.jsonl"}' "\${line#start }" | "${atc}" hook-report --agent claude ;;
+    notify\\ *) printf '{"hook_event_name":"Notification","message":"%s"}' "\${line#notify }" | "${atc}" hook-report --agent claude ;;
+    nested\\ *) printf '{"hook_event_name":"SessionStart","session_id":"%s","source":"startup"}' "\${line#nested }" | "${atc}" hook-report --agent codex ;;
+    forge\\ *) echo '{"hook_event_name":"Notification","message":"forged"}' | ATC_SESSION_ID="\${line#forge }" "${atc}" hook-report --agent claude ;;
+    tap\\ *) "${atc}" tap --session "$ATC_SESSION_ID" >> "\${line#tap }" 2>&1 & ;;
+    answer\\ *) rest="\${line#answer }"; printf '%s' "\${rest#* }" | "${atc}" report answered --messages "\${rest%% *}" ;;
+    note\\ *) printf '%s' "\${line#note }" | "${atc}" report note --label progress ;;
+  esac
+  echo "GOT:$line"
+done
+`,
+  );
+
+  return { atc, claude };
+}

package/src/test-utils/create-stub-harness-guest.ts

@@ -0,0 +1,35 @@
+import { join } from 'node:path';
+import { createStubBin } from './create-stub-bin';
+
+/**
+ * Creates a stand-in guest program for a harness to run, under the
+ * directory: a script that prints its pid and the terminal size it started
+ * at as `UP:<pid> START:<rows> <cols>`, echoes each line it reads as
+ * `GOT:<line>`, prints `SIZE:<rows> <cols>` on `size`, and exits 3 on
+ * `quit`. On `later` it waits for a line on the named pipe at `burstPath`,
+ * then prints 300000 `x` bytes, more than impd's ring keeps, a newline, and
+ * `BURST_DONE`. Returns the script's path and the pipe's.
+ */
+export function createStubHarnessGuest(dir: string) {
+  const burstPath = join(dir, 'burst');
+
+  Bun.spawnSync(['mkfifo', burstPath]);
+
+  const path = createStubBin(
+    dir,
+    'harness',
+    `#!/usr/bin/env bash
+echo "UP:$$ START:$(stty size)"
+while read -r line; do
+  if [ "$line" = "later" ]; then
+    (cat "${burstPath}" > /dev/null; head -c 300000 /dev/zero | tr '\\0' 'x'; echo; echo "BURST_DONE") &
+  fi
+  if [ "$line" = "size" ]; then echo "SIZE:$(stty size)"; fi
+  if [ "$line" = "quit" ]; then exit 3; fi
+  echo "GOT:$line"
+done
+`,
+  );
+
+  return { path, burstPath };
+}