@zgeoff/atc 3.3.1 → 3.4.0

package/src/test-utils/build-mock-daemon-record.ts

@@ -0,0 +1,26 @@
+import { faker } from '@faker-js/faker';
+import type { DaemonRecord } from '../shared/find-daemon-record';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * The record a daemon writes beside its state directory, for a daemon with
+ * no events socket and no TCP listener. The pid and the socket paths are
+ * arbitrary. Overrides replace the defaults field by field.
+ */
+export function buildMockDaemonRecord(
+  overrides: MockOverrides<DaemonRecord, keyof DaemonRecord> = {},
+): DaemonRecord {
+  const dir = faker.system.directoryPath();
+
+  return mergeDeep<DaemonRecord>(
+    {
+      pid: faker.number.int({ min: 2, max: 4_194_304 }),
+      socketPath: `${dir}/atc-daemon.sock`,
+      reporterSocketPath: `${dir}/atc.sock`,
+      eventsSocketPath: null,
+      listenPort: null,
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-fleet-entry.ts

@@ -0,0 +1,33 @@
+import { faker } from '@faker-js/faker';
+import { toAgentSessionID } from '../shared/to-agent-session-id';
+import { toSessionID } from '../shared/to-session-id';
+import type { FleetEntry } from '../store/fleet-entry';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * The fields the defaults set; every other field is absent until an
+ * override gives it whole.
+ */
+type DefaultedKey = 'sessionID' | 'name' | 'cwd' | 'agentSessionID' | 'agent';
+
+/**
+ * A fleet row for a live Claude session on the local target: a fresh
+ * session id and a fresh agent session id, so it restores as resumable,
+ * with an arbitrary name and directory and every optional field absent.
+ * Overrides merge into fresh defaults at every depth.
+ */
+export function buildMockFleetEntry(
+  overrides: MockOverrides<FleetEntry, DefaultedKey> = {},
+): FleetEntry {
+  return mergeDeep<FleetEntry, DefaultedKey>(
+    {
+      sessionID: toSessionID(faker.string.uuid()),
+      name: faker.word.noun(),
+      cwd: faker.system.directoryPath(),
+      agentSessionID: toAgentSessionID(faker.string.uuid()),
+      agent: 'claude',
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-gateway-config.ts

@@ -0,0 +1,32 @@
+import { faker } from '@faker-js/faker';
+import type { GatewayConfig } from '../shared/collect-gateways';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * The fields the defaults set; every other field is absent until an
+ * override gives it whole.
+ */
+type DefaultedKey = 'id' | 'label' | 'mark' | 'bin' | 'args' | 'baseURL' | 'env';
+
+/**
+ * A Claude-compatible backend with no arguments, no environment, no helper
+ * command, no settings, and no auth. The id, label, mark, binary, and base
+ * URL are arbitrary. Overrides merge into fresh defaults at every depth.
+ */
+export function buildMockGatewayConfig(
+  overrides: MockOverrides<GatewayConfig, DefaultedKey> = {},
+): GatewayConfig {
+  return mergeDeep<GatewayConfig, DefaultedKey>(
+    {
+      id: faker.string.alpha({ length: 8, casing: 'lower' }),
+      label: faker.company.name(),
+      mark: faker.string.alpha({ length: 1, casing: 'lower' }),
+      bin: faker.system.filePath(),
+      args: [],
+      baseURL: faker.internet.url(),
+      env: {},
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-imp-identity.ts

@@ -0,0 +1,18 @@
+import { faker } from '@faker-js/faker';
+import type { ImpIdentity } from '../daemon/imp-port';
+
+/**
+ * An impd token identity with an arbitrary name that manages the imps
+ * matching `atc-*` and may grant no secret. An override replaces the field
+ * it names.
+ */
+export function buildMockImpIdentity(overrides: Partial<ImpIdentity> = {}): ImpIdentity {
+  return {
+    kind: 'token',
+    name: faker.word.noun(),
+    scope: 'manage',
+    imps: ['atc-*'],
+    grantable: [],
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-key-binding-claim.ts

@@ -0,0 +1,34 @@
+import { faker } from '@faker-js/faker';
+import type { GatewayStore } from '../federation/gateway-store';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * The binding a keyed request claims in the gateway store, before any
+ * outcome or send is recorded for it.
+ */
+type KeyBindingClaim = Parameters<GatewayStore['claimBinding']>[0];
+
+/**
+ * A claim of a keyed spawn by an arbitrary principal under an arbitrary
+ * key, bound to an arbitrary daemon that announced an arbitrary retention,
+ * with an arbitrary payload hash and claim id. Overrides replace the
+ * defaults field by field.
+ */
+export function buildMockKeyBindingClaim(
+  overrides: MockOverrides<KeyBindingClaim, keyof KeyBindingClaim> = {},
+): KeyBindingClaim {
+  return mergeDeep<KeyBindingClaim>(
+    {
+      principal: faker.string.alphanumeric(12),
+      operation: 'session.spawn',
+      key: faker.string.alphanumeric(16),
+      daemon: faker.string.alpha({ length: 8, casing: 'lower' }),
+      daemonID: faker.string.uuid(),
+      retentionMs: faker.number.int({ min: 1000, max: 86_400_000 }),
+      payloadHash: faker.string.hexadecimal({ length: 64, casing: 'lower', prefix: '' }),
+      claimID: faker.string.uuid(),
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-message-record.ts

@@ -0,0 +1,22 @@
+import { faker } from '@faker-js/faker';
+import { toMessageID } from '../shared/to-message-id';
+import { toSessionID } from '../shared/to-session-id';
+import type { MessageRecord } from '../store/message-record';
+
+/**
+ * A message accepted for a session and not yet delivered: a fresh message
+ * id and a fresh atc id, an arbitrary sender, text, and send time, and no
+ * agent session id, delivery, answer, or turn. An override replaces the
+ * field it names.
+ */
+export function buildMockMessageRecord(overrides: Partial<MessageRecord> = {}): MessageRecord {
+  return {
+    id: toMessageID(faker.string.uuid()),
+    atcID: toSessionID(faker.string.uuid()),
+    from: faker.person.firstName(),
+    text: faker.lorem.sentence(),
+    status: 'accepted',
+    sentAt: faker.date.past().getTime(),
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-mirror-session.ts

@@ -0,0 +1,42 @@
+import { faker } from '@faker-js/faker';
+import type { MirrorSession } from '../client/to-mirror-session';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * A client's mirror of a live, running Claude session in a local terminal
+ * on the `local` target: read, unpinned, not resumable, unable to eject,
+ * with no parent and the agent's default model. The id, name, directory,
+ * last message, and times are arbitrary. Overrides replace the defaults
+ * field by field.
+ */
+export function buildMockMirrorSession(
+  overrides: MockOverrides<MirrorSession, keyof MirrorSession> = {},
+): MirrorSession {
+  const cwd = faker.system.directoryPath();
+
+  return mergeDeep<MirrorSession>(
+    {
+      id: faker.string.uuid(),
+      name: faker.word.noun(),
+      cwd,
+      pinned: false,
+      lastAttachedAt: faker.date.recent().getTime(),
+      repoRoot: cwd,
+      state: 'running',
+      unread: false,
+      lastMsg: faker.lorem.sentence(),
+      createdAt: faker.date.past().getTime(),
+      kind: 'pty',
+      alive: true,
+      resumable: false,
+      canEject: false,
+      agent: 'claude',
+      parent: null,
+      target: 'local',
+      model: null,
+      harness: 'running',
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-registry-daemon.ts

@@ -0,0 +1,28 @@
+import { faker } from '@faker-js/faker';
+import type { RegistryDaemon } from '../federation/types';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * A registry daemon with an arbitrary name, address, pinned daemon id,
+ * and token. Its incarnation is the first 8 characters of the
+ * daemon id in play, the override's when one is given, so a gateway id
+ * built from it routes back unless an override sets the incarnation too.
+ * Overrides merge into fresh defaults at every depth.
+ */
+export function buildMockRegistryDaemon(
+  overrides: MockOverrides<RegistryDaemon, keyof RegistryDaemon> = {},
+): RegistryDaemon {
+  const daemonID = overrides.daemonID ?? faker.string.uuid();
+
+  return mergeDeep<RegistryDaemon>(
+    {
+      name: faker.string.alpha({ length: 8, casing: 'lower' }),
+      address: { host: faker.internet.ipv4(), port: faker.internet.port() },
+      daemonID,
+      incarnation: daemonID.slice(0, 8),
+      token: faker.string.hexadecimal({ length: 32, casing: 'lower', prefix: '' }),
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-session-descriptor.ts

@@ -0,0 +1,66 @@
+import { faker } from '@faker-js/faker';
+import type { SessionDescriptor } from '../daemon/sessions';
+import { toDaemonID } from '../shared/to-daemon-id';
+import { toSessionID } from '../shared/to-session-id';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * The fields the defaults set; every other field is absent until an
+ * override gives it whole.
+ */
+type DefaultedKey =
+  | 'id'
+  | 'name'
+  | 'cwd'
+  | 'state'
+  | 'unread'
+  | 'lastMsg'
+  | 'agent'
+  | 'pinned'
+  | 'lastAttachedAt'
+  | 'repoRoot'
+  | 'namedBy'
+  | 'createdAt'
+  | 'kind'
+  | 'alive'
+  | 'canEject'
+  | 'locator'
+  | 'lifecycle';
+
+/**
+ * The wire view of a live, running Claude session in a local terminal on
+ * the `local` target, as `session.list` and the session events carry it:
+ * read, unpinned, named by the user, with no parent, workspace, model, or
+ * agent session id. The id, name, directories, last message, times, and
+ * daemon id are arbitrary. Overrides merge into fresh defaults at every
+ * depth.
+ */
+export function buildMockSessionDescriptor(
+  overrides: MockOverrides<SessionDescriptor, DefaultedKey> = {},
+): SessionDescriptor {
+  const cwd = faker.system.directoryPath();
+
+  return mergeDeep<SessionDescriptor, DefaultedKey>(
+    {
+      id: toSessionID(faker.string.uuid()),
+      name: faker.word.noun(),
+      cwd,
+      state: 'running',
+      unread: false,
+      lastMsg: faker.lorem.sentence(),
+      agent: 'claude',
+      pinned: false,
+      lastAttachedAt: faker.date.recent().getTime(),
+      repoRoot: cwd,
+      namedBy: 'user',
+      createdAt: faker.date.past().getTime(),
+      kind: 'pty',
+      alive: true,
+      canEject: false,
+      locator: { daemonID: toDaemonID(faker.string.uuid()), targetID: 'local' },
+      lifecycle: { desired: 'run', vm: 'none', harness: 'running', attachment: 'local' },
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-session.ts

@@ -0,0 +1,43 @@
+import { faker } from '@faker-js/faker';
+import type { Session } from '../daemon/sessions';
+import { toSessionID } from '../shared/to-session-id';
+
+/**
+ * A session manager's record of an exited Claude session on the `local`
+ * target with no terminal: read, unpinned, auto-named, with no parent,
+ * withheld env, workspace, model, or agent session id, and its own host.
+ * The id, name, directories, and times are arbitrary. An override replaces
+ * the field it names.
+ */
+export function buildMockSession(overrides: Partial<Session> = {}): Session {
+  const id = overrides.id ?? toSessionID(faker.string.uuid());
+  const cwd = faker.system.directoryPath();
+
+  return {
+    id,
+    name: faker.word.noun(),
+    cwd,
+    kind: 'pty',
+    pty: null,
+    state: 'exited',
+    unread: false,
+    lastMsg: '',
+    agent: 'claude',
+    pinned: false,
+    lastAttachedAt: faker.date.recent().getTime(),
+    repoRoot: cwd,
+    namedBy: 'auto',
+    createdAt: faker.date.past().getTime(),
+    parent: null,
+    target: 'local',
+    targetIdentity: 'local-pty:test',
+    withheldEnv: [],
+    desired: 'run',
+    vm: 'none',
+    attachment: 'local',
+    suspended: false,
+    hostKey: id,
+    bridgeEpoch: 0,
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-sortable-session-view.ts

@@ -0,0 +1,20 @@
+import { faker } from '@faker-js/faker';
+import type { SortableSessionView } from '../protocol/sortable-session-view';
+
+/**
+ * The ordering fields of a running, unpinned, top-level session, as the
+ * session list sorts it. The id and both times are arbitrary.
+ */
+export function buildMockSortableSessionView(
+  overrides: Partial<SortableSessionView> = {},
+): SortableSessionView {
+  return {
+    id: faker.string.uuid(),
+    parent: null,
+    state: 'running',
+    pinned: false,
+    lastAttachedAt: faker.date.recent().getTime(),
+    createdAt: faker.date.past().getTime(),
+    ...overrides,
+  };
+}

package/src/test-utils/build-stub-attention-adapter.ts

@@ -0,0 +1,22 @@
+import type { AgentAdapter } from '../agents/agent-adapter';
+import { buildMockAgentAdapter } from './build-mock-agent-adapter';
+
+/**
+ * An agent adapter for daemon tests whose hooks report attention: id
+ * `claude`, a spawn that runs `sleep 30`, sessions that take inbox
+ * messages, a `Notification` hook read as needing input and every other
+ * hook as a submitted prompt, and `claude --resume` as the resume command.
+ * It reads nothing from a hook's payload, so a payload's session id binds
+ * nothing. Every other member is the mock adapter's. An override replaces
+ * the member it names.
+ */
+export function buildStubAttentionAdapter(overrides: Partial<AgentAdapter> = {}): AgentAdapter {
+  return buildMockAgentAdapter({
+    takesMessages: true,
+    normalizeHook: (hook) => ({
+      kind: hook.event === 'Notification' ? 'needs-input' : 'prompt-submitted',
+    }),
+    buildResumeCommand: () => 'claude --resume',
+    ...overrides,
+  });
+}

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

@@ -0,0 +1,20 @@
+import type { BridgeContext } from '../daemon/start-session-bridge';
+
+/**
+ * The daemon's side of a session bridge, for tests that drive one bridge
+ * without a daemon behind it: no live session, hook events that go nowhere,
+ * every report recorded, every tap attached, every ack for an unknown
+ * message, and detaches that do nothing. An override replaces the member it
+ * names.
+ */
+export function buildStubBridgeContext(overrides: Partial<BridgeContext> = {}): BridgeContext {
+  return {
+    findSession: () => {},
+    applyHookEvent: () => {},
+    applyReport: () => Promise.resolve(true),
+    attachTap: () => 'ok',
+    ackMessage: () => Promise.resolve('unknown'),
+    detachTap: () => {},
+    ...overrides,
+  };
+}

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-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),
+  };
+}