@zgeoff/atc 3.3.1 → 3.4.1

package/src/test-utils/build-stub-brokered-agent-adapter.ts

@@ -0,0 +1,96 @@
+import type { AgentAdapter } from '../agents/agent-adapter';
+import { buildMockAgentAdapter } from './build-mock-agent-adapter';
+
+interface StubBrokeredAgentAdapterConfig {
+  readonly id: string;
+
+  // Whether the agent starts only behind the broker; false lets it start
+  // on a target that reaches no broker.
+  readonly brokerRequired: boolean;
+
+  // Whether the agent takes its credential from the broker at the moment
+  // of the call, as a config change can turn it on or off for an agent
+  // whose sessions already exist.
+  readonly isSelected: () => boolean;
+}
+
+/**
+ * An agent adapter for daemon tests that takes the credential of a GLM
+ * gateway from impd's broker: the auth profile `glm`, a custom bearer
+ * secret `glm` for api.z.ai, behind the gateway at
+ * https://api.z.ai/api/anthropic with the placeholder
+ * `ANTHROPIC_AUTH_TOKEN`. A guest spawn under a binding runs a shell that
+ * prints `revision <n>` for the binding's revision and then sleeps, with
+ * the binding's variables and `CLAUDE_CONFIG_DIR` set to `claude-config`
+ * in the guest folder; a guest spawn without one, and a local spawn, sleep.
+ * Every other member is the plain agent adapter's.
+ */
+export function buildStubBrokeredAgentAdapter(
+  config: StubBrokeredAgentAdapterConfig,
+): AgentAdapter {
+  return buildMockAgentAdapter({
+    id: config.id,
+    profile: {
+      label: 'GLM',
+      kind: 'claude',
+      bin: 'sh',
+      models: null,
+      spawnOptions: {
+        model: {
+          supported: false,
+          values: null,
+          examples: [],
+          default: null,
+          backendEffect: null,
+          note: null,
+        },
+        effort: {
+          supported: false,
+          values: null,
+          examples: [],
+          default: null,
+          backendEffect: null,
+          note: null,
+        },
+      },
+    },
+    planGuestSpawn: (_opts, guest) =>
+      guest.auth === undefined
+        ? { bin: 'sleep', args: ['30'], files: {} }
+        : {
+            bin: 'sh',
+            args: ['-c', `echo "revision ${String(guest.auth.revision)}"; exec sleep 30`],
+            files: {},
+            env: { ...guest.auth.env, CLAUDE_CONFIG_DIR: `${guest.dir}/claude-config` },
+          },
+    findAuthSelection: () =>
+      config.isSelected()
+        ? {
+            brokerRequired: config.brokerRequired,
+            gateway: {
+              id: 'glm',
+              baseURL: 'https://api.z.ai/api/anthropic',
+              auth: {
+                profiles: ['glm'],
+                placeholderEnv: { ANTHROPIC_AUTH_TOKEN: 'imp-broker-placeholder' },
+              },
+            },
+            profiles: new Map([
+              [
+                'glm',
+                {
+                  name: 'glm',
+                  secret: 'glm',
+                  kind: 'custom',
+                  host: 'api.z.ai',
+                  header: 'authorization',
+                  scheme: 'bearer',
+                  env: {},
+                  dependencies: [],
+                },
+              ],
+            ]),
+          }
+        : null,
+  });
+}

package/src/test-utils/build-stub-brokered-gateway-adapter.ts

@@ -0,0 +1,50 @@
+import type { AgentAdapter } from '../agents/agent-adapter';
+import { buildMockAgentAdapter } from './build-mock-agent-adapter';
+
+/**
+ * An agent adapter `glm` for daemon tests that only starts behind impd's
+ * broker and takes the credential of a GLM gateway from it: the auth
+ * profile `glm`, a custom bearer secret `glm` for api.z.ai, behind the
+ * gateway at https://api.z.ai/api/anthropic with the placeholder
+ * `ANTHROPIC_AUTH_TOKEN`. Every guest spawn sleeps, with the binding's
+ * variables, when it has one, and `CLAUDE_CONFIG_DIR` set to
+ * `claude-config` in the guest folder. Every other member is the plain
+ * agent adapter's.
+ */
+export function buildStubBrokeredGatewayAdapter(): AgentAdapter {
+  return buildMockAgentAdapter({
+    id: 'glm',
+    planGuestSpawn: (_opts, guest) => ({
+      bin: 'sleep',
+      args: ['30'],
+      files: {},
+      env: { ...guest.auth?.env, CLAUDE_CONFIG_DIR: `${guest.dir}/claude-config` },
+    }),
+    findAuthSelection: () => ({
+      brokerRequired: true,
+      gateway: {
+        id: 'glm',
+        baseURL: 'https://api.z.ai/api/anthropic',
+        auth: {
+          profiles: ['glm'],
+          placeholderEnv: { ANTHROPIC_AUTH_TOKEN: 'imp-broker-placeholder' },
+        },
+      },
+      profiles: new Map([
+        [
+          'glm',
+          {
+            name: 'glm',
+            secret: 'glm',
+            kind: 'custom',
+            host: 'api.z.ai',
+            header: 'authorization',
+            scheme: 'bearer',
+            env: {},
+            dependencies: [],
+          },
+        ],
+      ]),
+    }),
+  });
+}

package/src/test-utils/build-stub-channel-opener.ts

@@ -0,0 +1,45 @@
+type ChannelOpener<Address, Channel> = (address: Address) => Promise<Channel>;
+
+interface StubChannelOpenerOptions {
+  // The position of the dial to hold, counting from 1; no dial is held
+  // without it.
+  readonly holdDial?: number;
+}
+
+/**
+ * A dial function that opens each connection with the opener at the dial's
+ * position in the list, and every dial past the end with the last one, so
+ * a test can send a first connection to one place and every reconnect to
+ * another. The dial at `holdDial` waits before it opens: `waitForHeld`
+ * resolves once that dial has started, and `releaseHeld` lets it go on.
+ * `countOpened` returns how many dials it has made.
+ */
+export function buildStubChannelOpener<Address, Channel>(
+  openers: readonly [ChannelOpener<Address, Channel>, ...ChannelOpener<Address, Channel>[]],
+  options: StubChannelOpenerOptions = {},
+) {
+  const reached = Promise.withResolvers<void>();
+  const released = Promise.withResolvers<void>();
+  let opened = 0;
+
+  return {
+    open: async (address: Address): Promise<Channel> => {
+      opened++;
+
+      const opener = openers[Math.min(opened, openers.length) - 1] ?? openers[0];
+
+      if (opened === options.holdDial) {
+        reached.resolve();
+
+        await released.promise;
+      }
+
+      return opener(address);
+    },
+    countOpened: (): number => opened,
+    waitForHeld: (): Promise<void> => reached.promise,
+    releaseHeld: (): void => {
+      released.resolve();
+    },
+  };
+}

package/src/test-utils/build-stub-claude-headless-run.ts

@@ -0,0 +1,13 @@
+import { mock } from 'bun:test';
+import type { Mock } from 'bun:test';
+import type { ClaudeHeadlessRun } from '../agents/make-claude-headless-runner';
+
+/**
+ * A stand-in for the Claude headless runner an adapter takes: it records
+ * each request and its event hooks, starts no turn, fires no hook, and
+ * hands back a handle whose stop does nothing. A test reads what the
+ * adapter asked for through the mock matchers.
+ */
+export function buildStubClaudeHeadlessRun(): Mock<ClaudeHeadlessRun> {
+  return mock<ClaudeHeadlessRun>(() => ({ stop: () => {} }));
+}

package/src/test-utils/build-stub-client-screens.ts

@@ -0,0 +1,33 @@
+import type { ClientMachineDeps } from '../client/build-client-machine';
+
+/**
+ * The screens a client machine opens, as side effects that each append
+ * their name, and the session or mode they were given, to `calls` in the
+ * order they run, and draw nothing.
+ */
+export function buildStubClientScreens() {
+  const calls: string[] = [];
+
+  const deps: ClientMachineDeps = {
+    openHome: () => {
+      calls.push('openHome');
+    },
+    openAttached: (sessionID) => {
+      calls.push(`openAttached:${sessionID}`);
+    },
+    openOverlay: () => {
+      calls.push('openOverlay');
+    },
+    openHelp: () => {
+      calls.push('openHelp');
+    },
+    openPicker: (resume) => {
+      calls.push(`openPicker:${resume}`);
+    },
+    openEject: (sessionID) => {
+      calls.push(`openEject:${sessionID}`);
+    },
+  };
+
+  return { deps, calls };
+}

package/src/test-utils/build-stub-clock.ts

@@ -0,0 +1,67 @@
+import type { Clock } from '../shared/system-clock';
+
+interface StubTimer {
+  readonly dueAt: number;
+  readonly callback: () => void;
+}
+
+/**
+ * A clock that moves only when the test advances it, for code that takes a
+ * clock in place of the wall clock and the runtime's timers. It starts at
+ * the given epoch milliseconds. `advance` moves the time forward and runs,
+ * in due order, every scheduled callback whose time has come, including
+ * one a callback schedules within the step. `collectPending` returns, in
+ * due order, how many milliseconds each callback still waiting has left,
+ * which lets a test wait until the code under test has scheduled one and
+ * check its delay.
+ */
+export function buildStubClock(startMs: number) {
+  let time = startMs;
+  let nextID = 0;
+
+  const timers = new Map<number, StubTimer>();
+
+  const findDue = (until: number): [number, StubTimer] | null => {
+    let due: [number, StubTimer] | null = null;
+
+    for (const entry of timers) {
+      if (entry[1].dueAt <= until && (due === null || entry[1].dueAt < due[1].dueAt)) {
+        due = entry;
+      }
+    }
+
+    return due;
+  };
+
+  const clock: Clock = {
+    now: () => time,
+    schedule: (callback, delayMs) => {
+      const id = nextID++;
+
+      timers.set(id, { dueAt: time + Math.max(0, delayMs), callback });
+
+      return () => {
+        timers.delete(id);
+      };
+    },
+  };
+
+  return {
+    ...clock,
+    advance(ms: number): void {
+      const until = time + ms;
+
+      for (let due = findDue(until); due !== null; due = findDue(until)) {
+        timers.delete(due[0]);
+
+        time = due[1].dueAt;
+
+        due[1].callback();
+      }
+
+      time = until;
+    },
+    collectPending: (): number[] =>
+      [...timers.values()].map((timer) => timer.dueAt - time).toSorted((a, b) => a - b),
+  };
+}

package/src/test-utils/build-stub-daemon-context.ts

@@ -0,0 +1,81 @@
+import type { DaemonContext } from '../daemon/daemon-context';
+import { TargetAccess } from '../daemon/target-access';
+import { toDaemonID } from '../shared/to-daemon-id';
+
+/**
+ * The daemon a connection serves, for tests that drive one connection
+ * without a daemon behind it: build `atc/test`, daemon id `d-1`, a 64 KiB
+ * outbound queue, a day's idempotency retention, no sessions, `claude` as
+ * the last agent used, an empty fleet, a principal that reaches no target,
+ * every session bound to the `local` target and visible, and resyncs and
+ * detaches that do nothing. Every other
+ * member throws when called, naming itself, so a test that reaches one it
+ * did not wire fails loudly. An override replaces the member it names.
+ */
+export function buildStubDaemonContext(overrides: Partial<DaemonContext> = {}): DaemonContext {
+  return {
+    build: 'atc/test',
+    daemonID: toDaemonID('d-1'),
+    queueBytes: 65_536,
+    idempotencyRetentionMs: 86_400_000,
+    collectSessions: () => [],
+    collectSpawnDirs: makeUnreached('collectSpawnDirs'),
+    collectAgents: makeUnreached('collectAgents'),
+    collectFleet: () => Promise.resolve([]),
+    loadLastUsedAgent: () => Promise.resolve('claude'),
+    findAdapter: makeUnreached('findAdapter'),
+    buildTargetAccess: () => new TargetAccess([]),
+    hasListedPrincipal: makeUnreached('hasListedPrincipal'),
+    findSessionGrant: () => ({ target: 'local', targetIdentity: 'local-pty' }),
+    findTargetIdentity: makeUnreached('findTargetIdentity'),
+    canSeeSession: () => true,
+    isSessionVisible: makeUnreached('isSessionVisible'),
+    findPermissionSession: makeUnreached('findPermissionSession'),
+    resolveSpawnParent: makeUnreached('resolveSpawnParent'),
+    resolveSpawnTarget: makeUnreached('resolveSpawnTarget'),
+    requireWorkspaceTarget: makeUnreached('requireWorkspaceTarget'),
+    buildDefaultWorkspaceDir: makeUnreached('buildDefaultWorkspaceDir'),
+    requireAgentTarget: makeUnreached('requireAgentTarget'),
+    findSource: makeUnreached('findSource'),
+    collectAlternateGitURLs: makeUnreached('collectAlternateGitURLs'),
+    checkRepositoryAccess: makeUnreached('checkRepositoryAccess'),
+    spawnSession: makeUnreached('spawnSession'),
+    killSession: makeUnreached('killSession'),
+    forgetSession: makeUnreached('forgetSession'),
+    revokeSessionAuth: makeUnreached('revokeSessionAuth'),
+    updateSessionAuth: makeUnreached('updateSessionAuth'),
+    updateSession: makeUnreached('updateSession'),
+    quitDaemon: makeUnreached('quitDaemon'),
+    ackSession: makeUnreached('ackSession'),
+    buildResumeCommand: makeUnreached('buildResumeCommand'),
+    readSessionScreen: makeUnreached('readSessionScreen'),
+    readSessionRecord: makeUnreached('readSessionRecord'),
+    loadSessionTranscript: makeUnreached('loadSessionTranscript'),
+    readEvents: makeUnreached('readEvents'),
+    readReport: makeUnreached('readReport'),
+    answerPermission: makeUnreached('answerPermission'),
+    restoreFleet: makeUnreached('restoreFleet'),
+    attachSession: makeUnreached('attachSession'),
+    detachSession: () => {},
+    detachClient: makeUnreached('detachClient'),
+    writeSessionInput: makeUnreached('writeSessionInput'),
+    writeSessionLine: makeUnreached('writeSessionLine'),
+    ejectSession: makeUnreached('ejectSession'),
+    adoptSession: makeUnreached('adoptSession'),
+    resizeSession: makeUnreached('resizeSession'),
+    resyncClient: () => Promise.resolve(),
+    getEffectiveDims: makeUnreached('getEffectiveDims'),
+    writeSessionMessage: makeUnreached('writeSessionMessage'),
+    readMessage: makeUnreached('readMessage'),
+    attachTap: makeUnreached('attachTap'),
+    detachTap: () => {},
+    ackMessage: makeUnreached('ackMessage'),
+    ...overrides,
+  };
+}
+
+function makeUnreached(member: string): () => never {
+  return () => {
+    throw new Error(`the stub daemon context has no ${member}`);
+  };
+}

package/src/test-utils/build-stub-daemon-requests.ts

@@ -0,0 +1,103 @@
+import { waitFor } from './wait-for';
+
+type DaemonAnswer = Readonly<Record<string, unknown>>;
+
+interface StubRequest {
+  readonly m: string;
+  readonly p: DaemonAnswer;
+  readonly resolve: (answer: DaemonAnswer) => void;
+}
+
+interface StubDaemonRequestsOptions {
+  // A count the client under test raises each time it acts on something,
+  // such as a draw or a callback it makes.
+  readonly countReactions: () => number;
+
+  // Milliseconds each wait for a request or a reaction lasts before it
+  // rejects; five seconds when absent.
+  readonly timeoutMs?: number;
+
+  // The clock each wait reads its deadline from; the wall clock when absent.
+  readonly now?: () => number;
+
+  // Waits out the pause between a wait's checks; a real sleep when absent.
+  readonly wait?: (ms: number) => Promise<void>;
+}
+
+/**
+ * A daemon request channel that answers only when the test says so. Every
+ * request sent through `sendRequest` waits until `answer` or
+ * `answerOldest` resolves it. Each of those waits for a request under the
+ * method to be waiting, resolves the latest or the oldest one, and then
+ * waits for the client to react: to send another request, or to raise the
+ * count `countReactions` reads. A wait that outlasts `timeoutMs` rejects:
+ * with `no <method> request is waiting for an answer` when nothing was
+ * sent under the method, and with `nothing reacted to the <method> answer`
+ * when the client never reacted. A test that takes the `now` and `wait`
+ * of a stub clock steps that timeout without waiting it out. `collectSent` returns the params of every
+ * request sent under a method, answered or not, in the order they were
+ * sent.
+ */
+export function buildStubDaemonRequests(options: StubDaemonRequestsOptions) {
+  const sent: StubRequest[] = [];
+
+  const answered = new Set<StubRequest>();
+
+  const waitOptions = {
+    timeoutMs: options.timeoutMs ?? 5000,
+    now: options.now ?? Date.now,
+    wait: options.wait ?? Bun.sleep,
+  };
+
+  const countAll = () => sent.length + options.countReactions();
+
+  const resolveAndWait = async (request: Readonly<StubRequest>, value: DaemonAnswer) => {
+    const before = countAll();
+
+    answered.add(request);
+    request.resolve(value);
+
+    await waitFor(() => {
+      if (countAll() <= before) {
+        throw new Error(`nothing reacted to the ${request.m} answer`);
+      }
+    }, waitOptions);
+  };
+
+  return {
+    sendRequest(m: string, p: DaemonAnswer = {}): Promise<DaemonAnswer> {
+      return new Promise((resolve) => {
+        sent.push({ m, p, resolve });
+      });
+    },
+    async answer(m: string, value: DaemonAnswer): Promise<void> {
+      const request = await waitFor(() => {
+        const latest = sent.findLast((r) => r.m === m && !answered.has(r));
+
+        if (latest === undefined) {
+          throw new Error(`no ${m} request is waiting for an answer`);
+        }
+
+        return latest;
+      }, waitOptions);
+
+      await resolveAndWait(request, value);
+    },
+    async answerOldest(m: string, value: DaemonAnswer): Promise<void> {
+      const request = await waitFor(() => {
+        const oldest = sent.find((r) => r.m === m && !answered.has(r));
+
+        if (oldest === undefined) {
+          throw new Error(`no ${m} request is waiting for an answer`);
+        }
+
+        return oldest;
+      }, waitOptions);
+
+      await resolveAndWait(request, value);
+    },
+    collectSent(m: string): DaemonAnswer[] {
+      return sent.filter((request) => request.m === m).map((request) => request.p);
+    },
+  };
+}

package/src/test-utils/{fixture-dir-provider.ts → build-stub-dir-provider.ts}

@@ -11,11 +11,11 @@ import type {
 import { LocalPTYProvider } from '../daemon/local-pty-provider';
 
 // One provider operation, in the order the daemon called it.
-type FixtureCall =
+type StubDirCall =
   | { readonly op: 'transfer'; readonly dir: string; readonly bytes: number }
   | { readonly op: 'run'; readonly argv: readonly string[]; readonly cwd: string };
 
-interface FixtureDirOptions {
+interface StubDirOptions {
   // Capabilities the provider declares as missing.
   readonly lacking?: readonly ExecutionCapability[];
 
@@ -25,22 +25,16 @@ interface FixtureDirOptions {
 }
 
 /**
- * An execution provider for tests whose host is a directory tree the test
- * owns: a transfer unpacks the archive with tar into the directory it is
- * given, and a command runs as a child process in its working directory.
- * Paths pass through unchanged, so a test points them into its own temp
- * tree. Every transfer and command is recorded in `calls`. Harnesses start
- * on a local pseudo-terminal, and each one's spec is recorded in
- * `harnesses`.
+ * The directory-tree provider the factory below builds, one per call.
  */
-export class FixtureDirProvider implements ExecutionProvider {
+class StubDirProvider implements ExecutionProvider {
   readonly kind = 'fixture-dir';
 
   readonly remote = false;
 
   readonly capabilities: ExecutionCapabilities;
 
-  readonly calls: FixtureCall[] = [];
+  readonly calls: StubDirCall[] = [];
 
   // Every harness the provider started, as the daemon specified it.
   readonly harnesses: HarnessSpec[] = [];
@@ -49,7 +43,7 @@ export class FixtureDirProvider implements ExecutionProvider {
 
   private readonly terminals = new LocalPTYProvider();
 
-  constructor(options: FixtureDirOptions = {}) {
+  constructor(options: StubDirOptions = {}) {
     const lacking = new Set(options.lacking);
 
     this.capabilities = {
@@ -129,3 +123,17 @@ export class FixtureDirProvider implements ExecutionProvider {
 
   readonly dispose = (): void => {};
 }
+
+/**
+ * Builds an execution provider of kind `fixture-dir` for tests whose host is
+ * a directory tree the test owns: a transfer unpacks the archive with tar
+ * into the directory it is given, and a command runs as a child process in
+ * its working directory. Paths pass through unchanged, so a test points them
+ * into its own temp tree. Every transfer and command is recorded in `calls`.
+ * Harnesses start on a local pseudo-terminal, and each one's spec is
+ * recorded in `harnesses`. Suspending or destroying a host rejects, since
+ * the test's own tree neither sleeps nor goes away.
+ */
+export function buildStubDirProvider(options: StubDirOptions = {}): StubDirProvider {
+  return new StubDirProvider(options);
+}

package/src/test-utils/build-stub-execution-provider.ts

@@ -0,0 +1,112 @@
+import type {
+  ExecutionCapabilities,
+  ExecutionProvider,
+  HarnessSpec,
+} from '../daemon/execution-provider';
+import { LocalPTYProvider } from '../daemon/local-pty-provider';
+
+interface StubExecutionProviderConfig {
+  // The provider kind the daemon reports for the target.
+  readonly kind?: string;
+
+  // Capabilities that differ from a local pseudo-terminal's.
+  readonly capabilities?: Partial<ExecutionCapabilities>;
+
+  /**
+   * Called with each harness spec before the harness starts; a throw from
+   * it aborts the spawn.
+   */
+  readonly onSpawn?: (spec: HarnessSpec) => void;
+}
+
+interface StubExecutionProvider extends ExecutionProvider {
+  // Every host the daemon put to sleep, in order.
+  readonly suspended: string[];
+
+  // Every host the daemon destroyed, in order.
+  readonly destroyed: string[];
+
+  /**
+   * Rejects every host suspend with the error, recording nothing, until
+   * called with null.
+   */
+  readonly setSuspendFailure: (error: Readonly<Error> | null) => void;
+
+  /**
+   * Rejects every host destroy with the error, recording nothing, until
+   * called with null.
+   */
+  readonly setDestroyFailure: (error: Readonly<Error> | null) => void;
+}
+
+/**
+ * An execution provider for daemon tests that runs harnesses, transfers, and
+ * commands on this machine as the local pseudo-terminal provider does, with
+ * the capabilities the config changes on top of its own. It reports each
+ * harness spec to the config before starting it. A host suspend or
+ * destroy does nothing to the machine: it records the host in `suspended` or
+ * `destroyed` and resolves, or rejects with the error a failure setter gave.
+ * The daemon calls them only when the capabilities declare `suspend` or
+ * `destroy`.
+ */
+export function buildStubExecutionProvider(
+  config: StubExecutionProviderConfig = {},
+): StubExecutionProvider {
+  const local = new LocalPTYProvider();
+
+  const onSpawn = config.onSpawn ?? (() => {});
+  const suspended: string[] = [];
+  const destroyed: string[] = [];
+
+  // The errors a suspend and a destroy reject with, or null while they
+  // succeed.
+  const failures: { suspend: Readonly<Error> | null; destroy: Readonly<Error> | null } = {
+    suspend: null,
+    destroy: null,
+  };
+
+  return {
+    kind: config.kind ?? 'stub',
+    remote: false,
+    capabilities: { ...local.capabilities, ...config.capabilities },
+    prepareHost: local.prepareHost,
+    spawnHarness: (spec) => {
+      onSpawn(spec);
+
+      return local.spawnHarness(spec);
+    },
+    transferArchive: local.transferArchive,
+    runCommand: local.runCommand,
+    suspendHost: (host) => {
+      const failure = failures.suspend;
+
+      if (failure !== null) {
+        return Promise.reject(failure);
+      }
+
+      suspended.push(host);
+
+      return Promise.resolve();
+    },
+    destroyHost: (host) => {
+      const failure = failures.destroy;
+
+      if (failure !== null) {
+        return Promise.reject(failure);
+      }
+
+      destroyed.push(host);
+
+      return Promise.resolve();
+    },
+    dispose: local.dispose,
+    suspended,
+    destroyed,
+    setSuspendFailure: (error) => {
+      failures.suspend = error;
+    },
+    setDestroyFailure: (error) => {
+      failures.destroy = error;
+    },
+  };
+}