@zgeoff/atc 3.3.0 → 3.4.0

package/src/grants.ts

@@ -1,33 +1,58 @@
 import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { collectGrants } from './mcp/collect-grants';
 import { openMCPAuth } from './mcp/open-mcp-auth';
 import { revokeGrant } from './mcp/revoke-grant';
-import { mcpAuthDBFile, stateDir } from './shared/config';
+import { mcpAuthDBFile } from './shared/config';
+
+// Where the command's lines and its exit code go: the console and the
+// process by default.
+interface GrantsIO {
+  readonly print: (line: string) => void;
+  readonly printError: (line: string) => void;
+  readonly setExitCode: (code: number) => void;
+}
+
+const PROCESS_IO: GrantsIO = {
+  print: (line) => {
+    console.log(line);
+  },
+  printError: (line) => {
+    console.error(line);
+  },
+  setExitCode: (code) => {
+    process.exitCode = code;
+  },
+};
 
 /**
  * Runs `atc grants`: lists the grants clients of `atc mcp --http` hold, or
  * revokes one. A revoked grant's tokens stop working at once, and its client
  * has to go through approval again. It opens the authorization server's
- * database directly, so it works whether or not the server is running.
+ * database at `dbPath` directly, so it works whether or not the server is
+ * running. Revoking a grant that does not exist sets exit code 1.
  */
-export async function runGrants(revoke: string | null): Promise<void> {
-  mkdirSync(stateDir, { recursive: true });
+export async function runGrants(
+  revoke: string | null,
+  dbPath: string = mcpAuthDBFile,
+  io: GrantsIO = PROCESS_IO,
+): Promise<void> {
+  mkdirSync(dirname(dbPath), { recursive: true });
 
-  const store = await openMCPAuth({ dbPath: mcpAuthDBFile, origin: null });
+  const store = await openMCPAuth({ dbPath, origin: null });
 
   try {
     if (revoke !== null) {
       const revoked = await revokeGrant(store.db, revoke);
 
       if (!revoked) {
-        console.error(`atc grants: no grant has the ID '${revoke}'`);
-
-        process.exitCode = 1;
+        io.printError(`atc grants: no grant has the ID '${revoke}'`);
+        io.setExitCode(1);
 
         return;
       }
 
-      console.log(`Revoked grant ${revoke}`);
+      io.print(`Revoked grant ${revoke}`);
 
       return;
     }
@@ -35,13 +60,13 @@ export async function runGrants(revoke: string | null): Promise<void> {
     const grants = await collectGrants(store.db);
 
     if (grants.length === 0) {
-      console.log('No grants.');
+      io.print('No grants.');
 
       return;
     }
 
     for (const grant of grants) {
-      console.log(
+      io.print(
         `${grant.grantID}  ${grant.clientName}  ${grant.scopes.join(',')}  last used ${grant.lastUsedAt ?? 'never'}`,
       );
     }

package/src/hook-report.ts

@@ -1,6 +1,20 @@
 import { normalizeHookEventName } from './agents/normalize-hook-event';
 import { isRecord, sendReport } from './shared/report';
 
+// Where the reporter reads its event and how it exits: stdin and the
+// process by default.
+interface HookReportIO {
+  readonly readStdin: () => Promise<string>;
+  readonly exit: (code: number) => void;
+}
+
+const PROCESS_IO: HookReportIO = {
+  readStdin: () => new Response(Bun.stdin.stream()).text(),
+  exit: (code) => {
+    process.exit(code);
+  },
+};
+
 /**
  * Runs as a hook inside wrangled sessions. Reads the hook event from stdin
  * (Claude snake_case keys or Grok camelCase keys) and forwards a PascalCase
@@ -9,12 +23,12 @@ import { isRecord, sendReport } from './shared/report';
  * session's own. Always exits 0 so it never blocks the session it reports
  * on.
  */
-export async function runHookReport(agent: string): Promise<void> {
+export async function runHookReport(agent: string, io: HookReportIO = PROCESS_IO): Promise<void> {
   const sock = process.env['ATC_SOCKET'];
   const atcId = process.env['ATC_SESSION_ID'];
 
   if (sock !== undefined && sock !== '' && atcId !== undefined && atcId !== '') {
-    const raw = await new Response(Bun.stdin.stream()).text();
+    const raw = await io.readStdin();
 
     let payload: Record<string, unknown> = {};
 
@@ -33,5 +47,5 @@ export async function runHookReport(agent: string): Promise<void> {
     await sendReport(sock, line, 2000);
   }
 
-  process.exit(0);
+  io.exit(0);
 }

package/src/mcp/read-report-texts.ts

@@ -1,4 +1,6 @@
 import { isRecord } from '../shared/report';
+import { systemClock } from '../shared/system-clock';
+import type { Clock } from '../shared/system-clock';
 import type { FleetCaller } from './types';
 
 // The most report text one events page carries, in UTF-8 bytes: as much as
@@ -26,33 +28,34 @@ type ReportRead = Readonly<Record<string, unknown>>;
  * deadline: it then holds the cursor of the last event it keeps and `more`
  * true, so the next read starts at that report. Every other field of the
  * page, such as a gateway's `unavailable` and `truncated`, passes through
- * unchanged.
+ * unchanged. The deadline runs on `clock`, the wall clock by default.
  */
 export async function readReportTexts(
   caller: FleetCaller,
   page: Readonly<Record<string, unknown>>,
   deadlineMs: number = REPORT_READ_DEADLINE_MS,
+  clock: Clock = systemClock,
 ): Promise<Readonly<Record<string, unknown>>> {
   const raw: unknown = page['events'];
   const events = Array.isArray(raw) ? raw.filter((event) => isRecord(event)) : [];
-  const endsAt = Date.now() + deadlineMs;
+  const endsAt = clock.now() + deadlineMs;
   const timeout = Promise.withResolvers<ReportRead>();
 
-  const timer = setTimeout(() => {
+  const cancel = clock.schedule(() => {
     timeout.resolve({
       textError: `timeout: the report text did not arrive within ${deadlineMs} ms`,
     });
   }, deadlineMs);
 
-  const read = await readPageReports(caller, page, events, endsAt, timeout.promise);
+  const read = await readPageReports(caller, page, events, endsAt, timeout.promise, clock);
 
-  clearTimeout(timer);
+  cancel();
 
   return read;
 }
 
 // The page with its reports read, one at a time, until the budget or the
-// deadline at `endsAt` stops it. A read still out when `timeout` settles
+// deadline at `endsAt` on `clock` stops it. A read still out when `timeout` settles
 // gives way to the timeout it settles with.
 async function readPageReports(
   caller: FleetCaller,
@@ -60,6 +63,7 @@ async function readPageReports(
   events: readonly Readonly<Record<string, unknown>>[],
   endsAt: number,
   timeout: Readonly<Promise<ReportRead>>,
+  clock: Clock,
 ): Promise<Readonly<Record<string, unknown>>> {
   const kept: Readonly<Record<string, unknown>>[] = [];
   let used = 0;
@@ -72,7 +76,7 @@ async function readPageReports(
 
     const last = kept.at(-1);
 
-    if (last !== undefined && Date.now() >= endsAt) {
+    if (last !== undefined && clock.now() >= endsAt) {
       return { ...page, events: kept, cursor: last['cursor'], more: true };
     }
 

package/src/mcp/start-mcp-http-server.ts

@@ -38,6 +38,10 @@ interface MCPHTTPServerOptions {
 
   // Serves `/healthz` and `/readyz` for an orchestrator's probes.
   readonly probes?: boolean;
+
+  // The time pending approvals and the limit on approval starts run on, in
+  // epoch milliseconds; the wall clock when unset.
+  readonly now?: () => number;
 }
 
 /**
@@ -171,7 +175,7 @@ export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise
       origin,
       resource: `${origin}/mcp`,
       store,
-      approvals: new ApprovalState(600_000, () => Date.now()),
+      approvals: new ApprovalState(600_000, options.now ?? (() => Date.now())),
       printApproval: options.printApproval,
     },
   };

package/src/mcp-http-server.ts

@@ -1,11 +1,14 @@
 import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { bootDaemonClient } from './client/boot-daemon';
+import type { DaemonBoot, DaemonBootOptions } from './client/boot-daemon';
 import { DaemonClient } from './client/daemon-client';
 import { collectClients } from './mcp/collect-clients';
 import { openMCPAuth } from './mcp/open-mcp-auth';
 import { ReconnectingCaller } from './mcp/reconnecting-caller';
 import { startMCPHTTPServer } from './mcp/start-mcp-http-server';
-import { mcpAuthDBFile, stateDir } from './shared/config';
+import type { MCPHTTPConfig } from './shared/collect-mcp-http-config';
+import { mcpAuthDBFile } from './shared/config';
 import { loadMCPHTTPConfig } from './shared/load-mcp-http-config';
 
 interface MCPHTTPFlags {
@@ -15,6 +18,41 @@ interface MCPHTTPFlags {
   readonly waitForDaemon: boolean;
 }
 
+// What the server reaches outside itself, the process's own by default: its
+// config, the authorization database, the daemon it boots or waits for, the
+// console, the exit, and the signal listeners that stop it.
+interface MCPHTTPServerIO {
+  readonly loadConfig: () => MCPHTTPConfig;
+  readonly dbPath: string;
+  readonly bootDaemon: (
+    options: DaemonBootOptions,
+  ) => Promise<Pick<DaemonBoot, 'client' | 'socketPath'>>;
+  readonly print: (line: string) => void;
+  readonly printError: (line: string) => void;
+  readonly exit: (code: number) => void;
+  readonly registerSignal: (signal: 'SIGINT' | 'SIGTERM', listener: () => Promise<void>) => void;
+}
+
+const PROCESS_IO: MCPHTTPServerIO = {
+  loadConfig: loadMCPHTTPConfig,
+  dbPath: mcpAuthDBFile,
+  bootDaemon: bootDaemonClient,
+  print: (line) => {
+    console.log(line);
+  },
+  printError: (line) => {
+    console.error(line);
+  },
+  exit: (code) => {
+    process.exit(code);
+  },
+  registerSignal: (signal, listener) => {
+    process.on(signal, () => {
+      void listener();
+    });
+  },
+};
+
 // How long `--wait-for-daemon` waits before it exits. A service manager's
 // restart covers a daemon that takes longer.
 const DAEMON_WAIT_MS = 30_000;
@@ -25,19 +63,38 @@ const DAEMON_WAIT_MS = 30_000;
  * serves MCP over HTTP until Ctrl-C. Approval codes print here, so the
  * terminal running it is where the operator approves a client.
  */
-export async function runMCPHTTPServer(build: string, flags: MCPHTTPFlags): Promise<void> {
-  const config = loadMCPHTTPConfig();
-  const bootOptions = flags.waitForDaemon ? { waitForDaemonMs: DAEMON_WAIT_MS } : {};
-
-  const boot = await bootDaemonClient(bootOptions).catch((error: unknown) => {
-    console.error(`atc mcp --http: ${error instanceof Error ? error.message : String(error)}`);
-
-    return process.exit(1);
-  });
+export async function runMCPHTTPServer(
+  build: string,
+  flags: MCPHTTPFlags,
+  io: MCPHTTPServerIO = PROCESS_IO,
+): Promise<void> {
+  const config = io.loadConfig();
+
+  const bootOptions = flags.waitForDaemon
+    ? {
+        waitForDaemonMs: DAEMON_WAIT_MS,
+        onWaitForDaemon: () => {
+          io.printError(
+            `atc mcp --http: no daemon answers yet; waiting up to ${DAEMON_WAIT_MS / 1000}s for one, without starting it`,
+          );
+        },
+      }
+    : {};
+
+  let boot: Pick<DaemonBoot, 'client' | 'socketPath'>;
+
+  try {
+    boot = await io.bootDaemon(bootOptions);
+  } catch (error) {
+    io.printError(`atc mcp --http: ${error instanceof Error ? error.message : String(error)}`);
+    io.exit(1);
+
+    return;
+  }
 
   boot.client.stop();
 
-  mkdirSync(stateDir, { recursive: true });
+  mkdirSync(dirname(io.dbPath), { recursive: true });
 
   const caller = new ReconnectingCaller(boot.socketPath, build, (path) => DaemonClient.open(path));
 
@@ -48,45 +105,41 @@ export async function runMCPHTTPServer(build: string, flags: MCPHTTPFlags): Prom
     port: flags.port ?? config.port,
     publicURL: flags.publicURL ?? config.publicURL,
     allowedHosts: config.allowedHosts,
-    dbPath: mcpAuthDBFile,
+    dbPath: io.dbPath,
 
     // The line carries a client's name, so control and format characters
     // are dropped before it reaches the operator's terminal.
     printApproval: (line) => {
-      console.log(line.replaceAll(/[\p{Cc}\p{Cf}]/gu, ''));
+      io.print(line.replaceAll(/[\p{Cc}\p{Cf}]/gu, ''));
     },
 
     // Request lines go to stderr, so stdout keeps the approval lines alone.
     printRequest: (line) => {
-      console.error(line);
+      io.printError(line);
     },
   });
 
-  console.log(`atc mcp --http: serving ${server.origin}/mcp, listening on ${server.listening}`);
+  // The handlers go in before the serving line, so a signal sent once the
+  // line appears always finds them.
+  const stopServing = async () => {
+    await server.stop();
+    await caller.stop();
+
+    io.exit(0);
+  };
 
-  const admin = await openMCPAuth({ dbPath: mcpAuthDBFile, origin: null });
+  io.registerSignal('SIGINT', stopServing);
+  io.registerSignal('SIGTERM', stopServing);
+  io.print(`atc mcp --http: serving ${server.origin}/mcp, listening on ${server.listening}`);
+
+  const admin = await openMCPAuth({ dbPath: io.dbPath, origin: null });
   const clients = await collectClients(admin.db);
 
   await admin.close();
 
   if (clients.length === 0) {
-    console.log(
+    io.print(
       'No clients can connect yet. Add one with: atc clients add <name> --redirect-uri <uri>',
     );
   }
-
-  const stopServing = async () => {
-    await server.stop();
-    await caller.stop();
-
-    process.exit(0);
-  };
-
-  process.on('SIGINT', () => {
-    void stopServing();
-  });
-
-  process.on('SIGTERM', () => {
-    void stopServing();
-  });
 }

package/src/report.ts

@@ -16,6 +16,20 @@ interface ReportOptions {
   readonly turn: string;
 }
 
+// Where the reporter reads its text and how it exits: stdin and the process
+// by default.
+interface ReportIO {
+  readonly readStdin: () => Promise<string>;
+  readonly exit: (code: number) => void;
+}
+
+const PROCESS_IO: ReportIO = {
+  readStdin: () => new Response(Bun.stdin.stream()).text(),
+  exit: (code) => {
+    process.exit(code);
+  },
+};
+
 /**
  * Runs inside wrangled sessions: reads stdin verbatim and forwards it to the
  * atc socket as a Report envelope of the given kind. An `answered` report
@@ -26,7 +40,11 @@ interface ReportOptions {
  * given. Inside a remote host it goes to the session bridge instead. Always
  * exits 0 so it never blocks the session it reports on.
  */
-export async function runReport(kind: string, options: ReportOptions): Promise<void> {
+export async function runReport(
+  kind: string,
+  options: ReportOptions,
+  io: ReportIO = PROCESS_IO,
+): Promise<void> {
   try {
     const sock = process.env['ATC_SOCKET'];
     const atcId = process.env['ATC_SESSION_ID'];
@@ -38,7 +56,7 @@ export async function runReport(kind: string, options: ReportOptions): Promise<v
       atcId !== '' &&
       REPORT_KINDS.some((known) => known === kind)
     ) {
-      const stdin = await new Response(Bun.stdin.stream()).text();
+      const stdin = await io.readStdin();
 
       const payload = buildReportPayload(kind, options, stdin);
 
@@ -52,7 +70,7 @@ export async function runReport(kind: string, options: ReportOptions): Promise<v
     }
   } catch {}
 
-  process.exit(0);
+  io.exit(0);
 }
 
 // Inside a remote host, a report goes to the session bridge under an id of

package/src/run-bridge-tap.ts

@@ -29,6 +29,24 @@ const SEEN_LIMIT = 10_000;
 // opened the tap.
 type TapEnd = 'closed' | 'refused' | 'lost' | 'unreachable';
 
+// Where the tap prints and how it exits: stdout, stderr, and the process by
+// default.
+interface BridgeTapIO {
+  readonly writeStdout: (text: string) => Promise<unknown>;
+  readonly printError: (line: string) => void;
+  readonly exit: (code: number) => void;
+}
+
+const PROCESS_IO: BridgeTapIO = {
+  writeStdout: (text) => Bun.write(Bun.stdout, text),
+  printError: (line) => {
+    console.error(line);
+  },
+  exit: (code) => {
+    process.exit(code);
+  },
+};
+
 /**
  * Streams the session's inbox to stdout from inside a remote host, through
  * the session bridge at the given socket. It prints each message once as
@@ -40,21 +58,29 @@ type TapEnd = 'closed' | 'refused' | 'lost' | 'unreachable';
  * outbox still holds. Exits 0 once the inbox closes and 1 when the bridge
  * refuses the tap.
  */
-export async function runBridgeTap(socketPath: string, outbox: string): Promise<void> {
+export async function runBridgeTap(
+  socketPath: string,
+  outbox: string,
+  io: BridgeTapIO = PROCESS_IO,
+): Promise<void> {
   const seen = new Set<string>();
 
   let wait = FIRST_RETRY_MS;
 
   for (;;) {
-    const end = await runTapConnection(socketPath, outbox, seen);
+    const end = await runTapConnection(socketPath, outbox, seen, io);
 
     if (end === 'closed') {
-      process.exit(0);
+      io.exit(0);
+
+      return;
     }
 
     if (end === 'refused') {
-      console.error('atc tap: the session bridge refused the tap');
-      process.exit(1);
+      io.printError('atc tap: the session bridge refused the tap');
+      io.exit(1);
+
+      return;
     }
 
     if (end === 'lost') {
@@ -73,6 +99,7 @@ async function runTapConnection(
 
   // oxlint-disable-next-line prefer-readonly-parameter-types -- the ids the tap printed, which every connection adds to
   seen: Set<string>,
+  io: BridgeTapIO,
 ): Promise<TapEnd> {
   const ended = Promise.withResolvers<TapEnd>();
   let opened = false;
@@ -139,9 +166,11 @@ async function runTapConnection(
         const printed = `${JSON.stringify({ id: message.message, from: message.from, text: message.text, sentAt: message.sentAt })}\n`;
 
         try {
-          await Bun.write(Bun.stdout, printed);
+          await io.writeStdout(printed);
         } catch {
-          process.exit(1);
+          io.exit(1);
+
+          return;
         }
 
         updateSeenIDs(seen, message.message);

package/src/run-config-migrate.ts

@@ -1,19 +1,43 @@
 import { copyFileSync, readFileSync, writeFileSync } from 'node:fs';
 import { buildMigratedConfig } from './build-migrated-config';
 
+// Where the command's output goes, the console by default: text printed as
+// it is, and lines printed to stdout or stderr.
+interface ConfigMigrateIO {
+  readonly printText: (text: string) => void;
+  readonly print: (line: string) => void;
+  readonly printError: (line: string) => void;
+}
+
+const CONSOLE_IO: ConfigMigrateIO = {
+  printText: (text) => {
+    process.stdout.write(text);
+  },
+  print: (line) => {
+    console.log(line);
+  },
+  printError: (line) => {
+    console.error(line);
+  },
+};
+
 /**
  * Runs `atc config migrate`: prints the config.json rewritten around
  * `agents`, or with `write` copies the file to a timestamped backup beside it
  * and rewrites it in place. Returns the exit code. Notes and problems go to
  * stderr and name keys and paths, never values.
  */
-export function runConfigMigrate(file: string, write: boolean): number {
+export function runConfigMigrate(
+  file: string,
+  write: boolean,
+  io: ConfigMigrateIO = CONSOLE_IO,
+): number {
   let text: string;
 
   try {
     text = readFileSync(file, 'utf8');
   } catch {
-    console.error(`atc config migrate: ${file} cannot be read`);
+    io.printError(`atc config migrate: ${file} cannot be read`);
 
     return 1;
   }
@@ -23,7 +47,7 @@ export function runConfigMigrate(file: string, write: boolean): number {
   try {
     raw = JSON.parse(text);
   } catch {
-    console.error(`atc config migrate: ${file} is not valid JSON`);
+    io.printError(`atc config migrate: ${file} is not valid JSON`);
 
     return 1;
   }
@@ -31,23 +55,23 @@ export function runConfigMigrate(file: string, write: boolean): number {
   const result = buildMigratedConfig(raw);
 
   if (result.kind === 'unusable') {
-    console.error(`atc config migrate: ${file}: ${result.detail}`);
+    io.printError(`atc config migrate: ${file}: ${result.detail}`);
 
     return 1;
   }
 
   if (result.kind === 'current') {
-    console.log('config.json already uses agents; nothing to migrate');
+    io.print('config.json already uses agents; nothing to migrate');
 
     return 0;
   }
 
   for (const note of result.notes) {
-    console.error(note);
+    io.printError(note);
   }
 
   if (!write) {
-    process.stdout.write(result.text);
+    io.printText(result.text);
 
     return 0;
   }
@@ -57,7 +81,7 @@ export function runConfigMigrate(file: string, write: boolean): number {
   try {
     copyFileSync(file, backup);
   } catch {
-    console.error(`atc config migrate: ${backup} cannot be written; ${file} is unchanged`);
+    io.printError(`atc config migrate: ${backup} cannot be written; ${file} is unchanged`);
 
     return 1;
   }
@@ -65,13 +89,13 @@ export function runConfigMigrate(file: string, write: boolean): number {
   try {
     writeFileSync(file, result.text);
   } catch {
-    console.error(`atc config migrate: ${file} cannot be written; the backup is at ${backup}`);
+    io.printError(`atc config migrate: ${file} cannot be written; the backup is at ${backup}`);
 
     return 1;
   }
 
-  console.log(`backup: ${backup}`);
-  console.log(`wrote: ${file}`);
+  io.print(`backup: ${backup}`);
+  io.print(`wrote: ${file}`);
 
   return 0;
 }

package/src/run-gateway.ts

@@ -74,8 +74,8 @@ export async function runGateway(build: string, flags: GatewayFlags): Promise<vo
     process.exit(1);
   }
 
-  console.log(`atc-gateway: serving ${server.origin}/mcp, listening on ${server.listening}`);
-
+  // The handlers go in before the serving line, so a signal sent once the
+  // line appears always finds them.
   const stopServing = async () => {
     await server.stop();
     await gateway.stop();
@@ -90,4 +90,6 @@ export async function runGateway(build: string, flags: GatewayFlags): Promise<vo
   process.on('SIGTERM', () => {
     void stopServing();
   });
+
+  console.log(`atc-gateway: serving ${server.origin}/mcp, listening on ${server.listening}`);
 }

package/src/shared/build-atc-command.ts

@@ -4,10 +4,14 @@ import { isCompiledBinary } from './is-compiled-binary';
 /**
  * The argv that runs this build of atc with `args`: the compiled binary is
  * its own entry, and a source run is bun with the CLI entrypoint ahead of
- * the arguments.
+ * the arguments. `compiled` tells the two apart, and defaults to how this
+ * process runs.
  */
-export function buildATCCommand(args: readonly string[]): string[] {
-  return isCompiledBinary()
+export function buildATCCommand(
+  args: readonly string[],
+  compiled: boolean = isCompiledBinary(),
+): string[] {
+  return compiled
     ? [process.execPath, ...args]
     : [process.execPath, join(import.meta.dir, '..', 'cli.ts'), ...args];
 }

package/src/shared/bun-sqlite-driver.ts

@@ -16,6 +16,12 @@ export class BunSqliteDriver implements Driver {
 
   private releaseTurn: () => void = () => {};
 
+  /**
+   * How many acquires are waiting for an earlier caller to release the
+   * connection.
+   */
+  waiting = 0;
+
   constructor(sqlite: Database) {
     this.connection = buildConnection(sqlite);
   }
@@ -32,8 +38,12 @@ export class BunSqliteDriver implements Driver {
       release = resolve;
     });
 
+    this.waiting += 1;
+
     await previous;
 
+    this.waiting -= 1;
+
     if (release !== undefined) {
       this.releaseTurn = release;
     }