@boxxy/worker-atc 0.0.1 → 0.1.4

package/README.md

@@ -1,7 +1,40 @@
-# @boxxy/worker-atc
+<div align="center">
+  <h1>@boxxy/worker-atc</h1>
 
-This version, 0.0.1, is a placeholder. It holds no code. It reserves the name on npm so that the
-boxxy release can publish every real version from CI with provenance.
+  <p>
+    <a href="https://www.npmjs.com/package/@boxxy/worker-atc"><img src="https://img.shields.io/npm/v/@boxxy/worker-atc" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
 
-Install a version above 0.0.1. The source lives in [`adapters/worker-atc`](https://github.com/zgeoff/boxxy/tree/main/adapters/worker-atc)
-of the [boxxy repo](https://github.com/zgeoff/boxxy).
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
+
+boxxy's worker port on atc: it starts, reads, sleeps, wakes, stops and forgets the agent sessions
+that run boxxy's attempts.
+
+`createAtcWorker({ client, trustedFolders })` takes an atc client that the app builds and connects,
+and the folders the agent trusts on each worker target. It is the only package that imports
+`@atcx/contract`.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/worker-atc) with Bun:
+
+```bash
+bun add @boxxy/worker-atc
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- `createAtcWorker`, the `WorkerKind` port of `@boxxy/model` on atc's `session.*` calls.
+- `AtcClient`, the atc calls the adapter makes, typed from atc's published contract.
+- `./test-utils/create-fake-atc-client`, an atc daemon in memory for tests.
+
+## Documentation
+
+[The atc worker](../../docs/design/boxxy/v1-lifecycle.md#the-atc-worker) in the attempt lifecycle
+maps each port method to its atc call, and each atc answer to the port's outcome.

package/dist/create-atc-worker.d.ts

@@ -0,0 +1,8 @@
+import type { WorkerKind } from '@boxxy/model';
+import type { AtcClient } from './types.ts';
+interface AtcWorkerInput {
+    readonly client: AtcClient;
+    readonly trustedFolders: Readonly<Record<string, readonly string[]>>;
+}
+export declare function createAtcWorker(input: AtcWorkerInput): WorkerKind;
+export {};

package/dist/find-caller-identity.d.ts

@@ -0,0 +1,3 @@
+import type { CallerIdentity } from '@boxxy/model';
+import type { AtcSession } from './types.ts';
+export declare function findCallerIdentity(session: AtcSession): CallerIdentity | null;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createAtcWorker } from './create-atc-worker.ts';
+export type { AtcClient, AtcSession, AtcSessionRead } from './types.ts';

package/dist/is-capacity-refusal.d.ts

@@ -0,0 +1,2 @@
+import type { AtcError } from './parse-atc-error.ts';
+export declare function isCapacityRefusal(error: AtcError): boolean;

package/dist/is-folder-trusted.d.ts

@@ -0,0 +1 @@
+export declare function isFolderTrusted(trustedFolders: readonly string[], folder: string): boolean;

package/dist/parse-atc-error.d.ts

@@ -0,0 +1,7 @@
+import type { ErrorCode } from '@atcx/contract';
+export interface AtcError {
+    readonly code: ErrorCode;
+    readonly problem: string | null;
+    readonly message: string;
+}
+export declare function parseAtcError(error: unknown): AtcError | null;

package/dist/test-utils/build-mock-atc-session-read.d.ts

@@ -0,0 +1,8 @@
+import type { AtcSession, AtcSessionRead } from '../types.ts';
+type MockSession = Partial<Omit<AtcSession, 'lifecycle'>> & {
+    readonly lifecycle?: Partial<AtcSession['lifecycle']>;
+};
+export declare function buildMockAtcSessionRead(overrides?: Partial<Omit<AtcSessionRead, 'session'>> & {
+    readonly session?: MockSession;
+}): AtcSessionRead;
+export {};

package/dist/test-utils/create-fake-atc-client.d.ts

@@ -0,0 +1,30 @@
+import type { ErrorCode } from '@atcx/contract';
+import type { Clock } from '@boxxy/model';
+import type { AtcClient, AtcSession } from '../types.ts';
+export type FakeTargetKind = 'local' | 'suspending';
+type FakeCall = keyof AtcClient['session'];
+export type FakeSessionPatch = Partial<Pick<AtcSession, 'state' | 'lastAttachedAt' | 'host' | 'agentSessionID'>> & {
+    readonly harness?: AtcSession['lifecycle']['harness'];
+    readonly desired?: AtcSession['lifecycle']['desired'];
+    readonly lastActivityAt?: number;
+};
+export interface FakeAtcClient extends AtcClient {
+    readonly calls: readonly {
+        readonly call: FakeCall;
+        readonly input: unknown;
+    }[];
+    listMessages: (session: string) => readonly string[];
+    patchSession: (session: string, patch: FakeSessionPatch) => void;
+    failNext: (call: FakeCall, error: Error) => void;
+}
+export declare class FakeAtcError extends Error {
+    readonly code: ErrorCode;
+    readonly data: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: ErrorCode, data?: Readonly<Record<string, unknown>>);
+}
+interface FakeAtcClientInput {
+    readonly clock: Clock;
+    readonly targets: Readonly<Record<string, FakeTargetKind>>;
+}
+export declare function createFakeAtcClient(input: FakeAtcClientInput): FakeAtcClient;
+export {};

package/dist/to-session-reading.d.ts

@@ -0,0 +1,3 @@
+import type { SessionReading } from '@boxxy/model';
+import type { AtcSessionRead } from './types.ts';
+export declare function toSessionReading(read: AtcSessionRead): SessionReading;

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+import type { DAEMON_CONTRACT } from '@atcx/contract';
+import type { z } from 'zod';
+type SessionProcedures = (typeof DAEMON_CONTRACT)['session'];
+type InputOf<Procedure> = Procedure extends {
+    '~orpc': {
+        inputSchema?: infer Schema;
+    };
+} ? z.input<Schema> : never;
+type OutputOf<Procedure> = Procedure extends {
+    '~orpc': {
+        outputSchema?: infer Schema;
+    };
+} ? z.output<Schema> : never;
+type CallOf<Procedure> = (input: InputOf<Procedure>) => Promise<OutputOf<Procedure>>;
+export type AtcSession = OutputOf<SessionProcedures['get']>['session'];
+export type AtcSessionRead = OutputOf<SessionProcedures['get']>;
+export interface AtcClient {
+    readonly session: {
+        readonly spawn: (input: InputOf<SessionProcedures['spawn']>) => Promise<{
+            readonly session: AtcSession;
+        }>;
+        readonly get: (input: InputOf<SessionProcedures['get']>) => Promise<AtcSessionRead>;
+        readonly list: (input: InputOf<SessionProcedures['list']>) => Promise<{
+            readonly sessions: readonly AtcSession[];
+        }>;
+        readonly kill: CallOf<SessionProcedures['kill']>;
+        readonly adopt: CallOf<SessionProcedures['adopt']>;
+        readonly forget: CallOf<SessionProcedures['forget']>;
+        readonly message: CallOf<SessionProcedures['message']>;
+    };
+}
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boxxy/worker-atc",
-  "version": "0.0.1",
-  "description": "Placeholder that reserves the name; the first real version comes from the boxxy release",
+  "version": "0.1.4",
+  "description": "boxxy's worker port on atc: starts, reads, sleeps, wakes, stops and forgets agent sessions",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/adapters/worker-atc#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
   "license": "MIT",
@@ -11,10 +11,36 @@
     "directory": "adapters/worker-atc"
   },
   "files": [
-    "README.md",
-    "LICENSE"
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
   ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./test-utils/*": "./src/test-utils/*.ts"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "@atcx/contract": "7.13.0",
+    "@boxxy/model": "0.1.4",
+    "ts-pattern": "5.9.2",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@boxxy/dispatch": "0.1.4"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
   }
 }

package/src/create-atc-worker.ts

@@ -0,0 +1,257 @@
+import type {
+  AtcSessionId,
+  AttemptRow,
+  SessionReading,
+  StartOutcome,
+  WorkerKind,
+} from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import { findCallerIdentity } from './find-caller-identity.ts';
+import { isCapacityRefusal } from './is-capacity-refusal.ts';
+import { isFolderTrusted } from './is-folder-trusted.ts';
+import { parseAtcError } from './parse-atc-error.ts';
+import { toSessionReading } from './to-session-reading.ts';
+import type { AtcClient, AtcSession } from './types.ts';
+
+interface AtcWorkerInput {
+  readonly client: AtcClient;
+
+  // by worker target: the folders that the agent on the target trusts, each with its subfolders
+  readonly trustedFolders: Readonly<Record<string, readonly string[]>>;
+}
+
+// The worker port on atc. Every call reaches atc through the client; a refusal that carries an atc
+// code answers `refused`, and a call that got no atc answer answers `unknown`.
+export function createAtcWorker(input: AtcWorkerInput): WorkerKind {
+  const client = input.client.session;
+
+  // a spawn whose answer was lost leaves the attempt with no session, which carries its spawn name
+  const readSessionID = async (attempt: AttemptRow): Promise<AtcSessionId | null> => {
+    if (attempt.atcSession !== null) {
+      return attempt.atcSession;
+    }
+
+    const listed = await client.list({});
+
+    return findNamedSession(listed.sessions, `boxxy/${attempt.id}`);
+  };
+
+  const readSession = async (session: AtcSessionId): Promise<SessionReading> => {
+    try {
+      const read = await client.get({ session });
+
+      return toSessionReading(read);
+    } catch (error) {
+      if (parseAtcError(error)?.code === 'no_such_session') {
+        return { kind: 'absent' };
+      }
+
+      throw error;
+    }
+  };
+
+  // wakes a stopped session; a session that runs already answers as it is
+  const resumeSession = async (session: AtcSessionId): Promise<StartOutcome> => {
+    try {
+      const read = await client.get({ session });
+
+      if (read.session.lifecycle.harness === 'running') {
+        return toStarted(read.session);
+      }
+
+      await client.adopt({ session });
+
+      const adopted = await client.get({ session });
+
+      return toStarted(adopted.session);
+    } catch (error) {
+      return toStartFailure(error);
+    }
+  };
+
+  return {
+    start: async (request) => {
+      if (!isFolderTrusted(input.trustedFolders[request.target] ?? [], request.cwd)) {
+        return { kind: 'refused', cause: 'other', reason: 'worker folder not trusted' };
+      }
+
+      try {
+        const answer = await client.spawn({
+          target: request.target,
+          cwd: request.cwd,
+          name: request.name,
+          prompt: request.prompt,
+          agent: request.agent,
+          model: request.model,
+          effort: request.effort,
+          idempotencyKey: request.idempotencyKey,
+        });
+
+        return toStarted(answer.session);
+      } catch (error) {
+        // after a daemon restart, a keyed spawn that ran answers this until the fleet restore
+        // lists its session
+        if (parseAtcError(error)?.code === 'no_such_session') {
+          return { kind: 'unknown', reason: 'the spawn ran, and its session is not listed yet' };
+        }
+
+        return toStartFailure(error);
+      }
+    },
+    reconcile: async (attempt) => {
+      const session = await readSessionID(attempt);
+
+      return session === null ? { kind: 'absent' } : readSession(session);
+    },
+    suspend: async (attempt, ifIdleSince) => {
+      try {
+        const session = await readSessionID(attempt);
+
+        if (session === null) {
+          return { kind: 'refused', reason: 'no such session' };
+        }
+
+        const read = await client.get({ session });
+
+        const reading = toSessionReading(read);
+
+        if (reading.kind !== 'running') {
+          return { kind: 'suspended' };
+        }
+
+        if (ifIdleSince !== null && reading.lastActivityAt > ifIdleSince) {
+          return { kind: 'active' };
+        }
+
+        // a plain kill of a session that already exited forgets it, so every kill is stop-only
+        await client.kill({ session, stopOnly: true });
+
+        return { kind: 'suspended' };
+      } catch (error) {
+        return toCallFailure(error);
+      }
+    },
+    resume: async (attempt) => {
+      try {
+        const session = await readSessionID(attempt);
+
+        return session === null
+          ? { kind: 'refused', cause: 'other', reason: 'no such session' }
+          : await resumeSession(session);
+      } catch (error) {
+        return toStartFailure(error);
+      }
+    },
+    stop: async (attempt) => {
+      try {
+        const session = await readSessionID(attempt);
+
+        if (session === null) {
+          return { kind: 'absent' };
+        }
+
+        await client.kill({ session, stopOnly: true });
+
+        return { kind: 'stopped' };
+      } catch (error) {
+        return parseAtcError(error)?.code === 'no_such_session'
+          ? { kind: 'absent' }
+          : toCallFailure(error);
+      }
+    },
+    forget: async (session) => {
+      try {
+        const first = await client.forget({ session, refuseLive: true });
+
+        // a target that destroys its hosts answers a confirm token first, for a second call
+        if ('confirmToken' in first) {
+          await client.forget({ session, refuseLive: true, confirmToken: first.confirmToken });
+        }
+
+        return { kind: 'forgotten' };
+      } catch (error) {
+        return parseAtcError(error)?.code === 'no_such_session'
+          ? { kind: 'absent' }
+          : toCallFailure(error);
+      }
+    },
+    resumeKept: async (kept, request) => {
+      const woken = await resumeSession(kept.atcSession);
+
+      if (woken.kind !== 'started') {
+        return woken;
+      }
+
+      try {
+        await client.message({
+          session: kept.atcSession,
+          text: request.prompt,
+          idempotencyKey: request.idempotencyKey,
+        });
+
+        return woken;
+      } catch (error) {
+        // the claim spawns a fresh session in its place, so the kept one must not run on
+        await client.kill({ session: kept.atcSession, stopOnly: true }).catch(() => null);
+
+        return toStartFailure(error);
+      }
+    },
+  };
+}
+
+// the latest session with the name
+function findNamedSession(sessions: readonly AtcSession[], name: string): AtcSessionId | null {
+  const latest = sessions
+    .filter((session) => session.name === name)
+    .toSorted((left, right) => right.createdAt - left.createdAt)
+    .at(0);
+
+  return latest === undefined ? null : brandSchemas.atcSessionId.parse(latest.id);
+}
+
+function toStarted(session: AtcSession): StartOutcome {
+  return {
+    kind: 'started',
+    atcSession: brandSchemas.atcSessionId.parse(session.id),
+    agentSession:
+      session.agentSessionID === undefined
+        ? null
+        : brandSchemas.agentSessionId.parse(session.agentSessionID),
+    caller: findCallerIdentity(session),
+  };
+}
+
+function toStartFailure(error: unknown): StartOutcome {
+  const atcError = parseAtcError(error);
+  const failure = toCallFailure(error);
+
+  if (failure.kind === 'unknown' || atcError === null) {
+    return { kind: 'unknown', reason: failure.reason };
+  }
+
+  return {
+    kind: 'refused',
+    cause: isCapacityRefusal(atcError) ? 'capacity' : 'other',
+    reason: failure.reason,
+  };
+}
+
+// atc may or may not have run a call it answers `outcome_unknown` or `idempotency_key_unknown`
+function toCallFailure(error: unknown): {
+  readonly kind: 'refused' | 'unknown';
+  readonly reason: string;
+} {
+  const atcError = parseAtcError(error);
+
+  if (atcError === null) {
+    return { kind: 'unknown', reason: error instanceof Error ? error.message : String(error) };
+  }
+
+  const reason = `${atcError.code}: ${atcError.message}`;
+
+  const unknown =
+    atcError.code === 'outcome_unknown' || atcError.code === 'idempotency_key_unknown';
+
+  return { kind: unknown ? 'unknown' : 'refused', reason };
+}

package/src/find-caller-identity.ts

@@ -0,0 +1,15 @@
+import type { CallerIdentity } from '@boxxy/model';
+import type { AtcSession } from './types.ts';
+
+// The one place that reads who runs a session: the issuer of the host's identity token, with the
+// machine's ID as the subject, never the name. null when the session has no host, or when the host lacks its ID or
+// its issuer: the identity check refuses such a host, so boxxy refuses its calls the same way.
+export function findCallerIdentity(session: AtcSession): CallerIdentity | null {
+  const host = session.host;
+
+  if (host?.id === undefined || host.issuer === undefined) {
+    return null;
+  }
+
+  return { issuer: host.issuer, subject: host.id };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createAtcWorker } from './create-atc-worker.ts';
+export type { AtcClient, AtcSession, AtcSessionRead } from './types.ts';

package/src/is-capacity-refusal.ts

@@ -0,0 +1,8 @@
+import type { AtcError } from './parse-atc-error.ts';
+
+// The one place that decides that the worker target has no free machine. atc's imp provider refuses
+// a host it cannot ready with `host_unavailable`, and puts impd's own error code, in lower case, in
+// the refusal's `problem`; impd answers `RAM_BUDGET_EXCEEDED` when no budget is left for another imp.
+export function isCapacityRefusal(error: AtcError): boolean {
+  return error.code === 'host_unavailable' && error.problem === 'ram_budget_exceeded';
+}

package/src/is-folder-trusted.ts

@@ -0,0 +1,12 @@
+// A folder is trusted when it is one of the trusted folders or lies inside one.
+export function isFolderTrusted(trustedFolders: readonly string[], folder: string): boolean {
+  const path = trimTrailingSlashes(folder);
+
+  return trustedFolders
+    .map((trusted) => trimTrailingSlashes(trusted))
+    .some((trusted) => trusted !== '' && (path === trusted || path.startsWith(`${trusted}/`)));
+}
+
+function trimTrailingSlashes(path: string): string {
+  return path.replace(/\/+$/u, '');
+}

package/src/parse-atc-error.ts

@@ -0,0 +1,35 @@
+import type { ErrorCode } from '@atcx/contract';
+import { ERROR_CODES } from '@atcx/contract';
+import { z } from 'zod';
+
+// A call that atc refused: its code, and the `problem` that a host refusal carries in its data.
+export interface AtcError {
+  readonly code: ErrorCode;
+  readonly problem: string | null;
+  readonly message: string;
+}
+
+const atcErrorSchema = z.object({
+  code: z.enum(ERROR_CODES),
+  message: z.string().optional(),
+  data: z.unknown(),
+});
+
+const problemSchema = z.object({ problem: z.string() });
+
+// null: the error carries no atc code, such as a dropped connection, so atc gave no answer
+export function parseAtcError(error: unknown): AtcError | null {
+  const parsed = atcErrorSchema.safeParse(error);
+
+  if (!parsed.success) {
+    return null;
+  }
+
+  const data = problemSchema.safeParse(parsed.data.data);
+
+  return {
+    code: parsed.data.code,
+    problem: data.success ? data.data.problem : null,
+    message: parsed.data.message ?? '',
+  };
+}

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

@@ -0,0 +1,51 @@
+import { toAgentSessionID, toDaemonID, toSessionID } from '@atcx/contract';
+import type { AtcSession, AtcSessionRead } from '../types.ts';
+
+type MockSession = Partial<Omit<AtcSession, 'lifecycle'>> & {
+  readonly lifecycle?: Partial<AtcSession['lifecycle']>;
+};
+
+// `session.get`'s answer for a session whose agent runs and works on an imp target.
+export function buildMockAtcSessionRead(
+  overrides: Partial<Omit<AtcSessionRead, 'session'>> & { readonly session?: MockSession } = {},
+): AtcSessionRead {
+  const { session = {}, ...read } = overrides;
+  const { lifecycle = {}, ...fields } = session;
+
+  return {
+    session: {
+      id: toSessionID('s1-mock'),
+      name: 'boxxy/mock-attempt',
+      cwd: '/tmp/boxxy-test/repo',
+      state: 'running',
+      unread: false,
+      lastMsg: '',
+      agentSessionID: toAgentSessionID('agent-mock'),
+      agent: 'claude',
+      pinned: false,
+      lastAttachedAt: 1_000_000,
+      repoRoot: '/tmp/boxxy-test/repo',
+      namedBy: 'user',
+      createdAt: 1_000_000,
+      kind: 'pty',
+      alive: true,
+      canEject: false,
+      locator: { daemonID: toDaemonID('mock-daemon'), targetID: 'box' },
+      host: { name: 'imp-mock', id: 'imp-id-mock', issuer: 'https://broker.test' },
+      ...fields,
+      lifecycle: {
+        desired: 'run',
+        vm: 'awake',
+        harness: 'running',
+        attachment: 'detached',
+        ...lifecycle,
+      },
+    },
+    prompt: null,
+    lastActivityAt: 1_000_000,
+    pending: null,
+    result: null,
+    sessionRecord: null,
+    ...read,
+  };
+}

package/src/test-utils/create-fake-atc-client.ts

@@ -0,0 +1,332 @@
+import type { ErrorCode } from '@atcx/contract';
+import { toAgentSessionID, toDaemonID, toSessionID } from '@atcx/contract';
+import type { Clock } from '@boxxy/model';
+import { z } from 'zod';
+import type { AtcClient, AtcSession } from '../types.ts';
+
+// How a target treats a stopped session's host: a `local` target ends the agent process, and a
+// `suspending` target sleeps the host with the process inside, and destroys it on a forget.
+export type FakeTargetKind = 'local' | 'suspending';
+
+type FakeCall = keyof AtcClient['session'];
+
+// What a test changes on a listed session. A field left out keeps the session's value.
+export type FakeSessionPatch = Partial<
+  Pick<AtcSession, 'state' | 'lastAttachedAt' | 'host' | 'agentSessionID'>
+> & {
+  readonly harness?: AtcSession['lifecycle']['harness'];
+  readonly desired?: AtcSession['lifecycle']['desired'];
+  readonly lastActivityAt?: number;
+};
+
+export interface FakeAtcClient extends AtcClient {
+  // every call the client took, in order, with its input
+  readonly calls: readonly { readonly call: FakeCall; readonly input: unknown }[];
+
+  // the text of each message sent to the session, in order
+  listMessages: (session: string) => readonly string[];
+  patchSession: (session: string, patch: FakeSessionPatch) => void;
+
+  // the next call of that procedure rejects with the error and changes nothing
+  failNext: (call: FakeCall, error: Error) => void;
+}
+
+// A refusal as atc's client gives it: the error's `code` and `data`.
+export class FakeAtcError extends Error {
+  readonly code: ErrorCode;
+
+  readonly data: Readonly<Record<string, unknown>> | undefined;
+
+  constructor(code: ErrorCode, data?: Readonly<Record<string, unknown>>) {
+    super(`atc refused the call: ${code}`);
+
+    this.name = 'FakeAtcError';
+    this.code = code;
+    this.data = data;
+  }
+}
+
+interface FakeSession {
+  descriptor: AtcSession;
+  lastActivityAt: number;
+  readonly targetKind: FakeTargetKind;
+  readonly messages: string[];
+  readonly messageKeys: Map<string, string>;
+}
+
+interface FakeAtcClientInput {
+  readonly clock: Clock;
+  readonly targets: Readonly<Record<string, FakeTargetKind>>;
+}
+
+const sessionInputSchema = z.object({ session: z.string() });
+
+// An atc daemon in memory, as atc's docs describe the calls the worker adapter makes. Each session
+// runs on the host `imp-<session ID>`, with the issuer `https://broker.test`.
+export function createFakeAtcClient(input: FakeAtcClientInput): FakeAtcClient {
+  const sessions = new Map<string, FakeSession>();
+  const spawnKeys = new Map<string, string>();
+  const confirmTokens = new Map<string, string>();
+  const failures = new Map<FakeCall, Error>();
+
+  const calls: { call: FakeCall; input: unknown }[] = [];
+  let count = 0;
+
+  // a refusal rejects the call's promise, as a remote call does
+  const answer = <Answer>(
+    call: FakeCall,
+    callInput: unknown,
+    work: () => Answer,
+  ): Promise<Answer> =>
+    Promise.try(() => {
+      calls.push({ call, input: callInput });
+
+      const failure = failures.get(call);
+
+      if (failure !== undefined) {
+        failures.delete(call);
+        throw failure;
+      }
+
+      return work();
+    });
+
+  const getSession = (callInput: unknown): FakeSession => {
+    const session = sessions.get(sessionInputSchema.parse(callInput).session);
+
+    if (session === undefined) {
+      throw new FakeAtcError('no_such_session');
+    }
+
+    return session;
+  };
+
+  const setHarness = (
+    session: FakeSession,
+    harness: AtcSession['lifecycle']['harness'],
+    desired: AtcSession['lifecycle']['desired'],
+  ): void => {
+    session.descriptor = {
+      ...session.descriptor,
+      state: harness === 'running' ? 'running' : 'exited',
+      alive: harness === 'running',
+      lifecycle: { ...session.descriptor.lifecycle, harness, desired },
+    };
+  };
+
+  const createSession = (spawn: Parameters<AtcClient['session']['spawn']>[0]): AtcSession => {
+    const target = spawn.target ?? 'local';
+    const targetKind = input.targets[target];
+
+    if (targetKind === undefined) {
+      throw new FakeAtcError('unknown_target');
+    }
+
+    count += 1;
+
+    const id = `s${count}-fake`;
+    const now = input.clock.now();
+
+    const descriptor: AtcSession = {
+      id: toSessionID(id),
+      name: typeof spawn.name === 'string' ? spawn.name : '',
+      cwd: spawn.cwd ?? '',
+      state: 'running',
+      unread: false,
+      lastMsg: '',
+      agentSessionID: toAgentSessionID(`agent-${count}`),
+      agent: spawn.agent ?? 'claude',
+      pinned: false,
+      lastAttachedAt: now,
+      repoRoot: spawn.cwd ?? '',
+      namedBy: 'user',
+      createdAt: now,
+      kind: 'pty',
+      alive: true,
+      canEject: false,
+      locator: { daemonID: toDaemonID('fake-daemon'), targetID: target },
+      lifecycle: {
+        desired: 'run',
+        vm: targetKind === 'local' ? 'none' : 'awake',
+        harness: 'running',
+        attachment: targetKind === 'local' ? 'local' : 'detached',
+      },
+      host: { name: `imp-${id}`, id: `imp-id-${id}`, issuer: 'https://broker.test' },
+    };
+
+    sessions.set(id, {
+      descriptor,
+      lastActivityAt: now,
+      targetKind,
+      messages: [],
+      messageKeys: new Map(),
+    });
+
+    return descriptor;
+  };
+
+  return {
+    calls,
+    session: {
+      spawn: (spawn) =>
+        answer('spawn', spawn, () => {
+          const key = spawn.idempotencyKey;
+          const known = key === undefined ? undefined : sessions.get(spawnKeys.get(key) ?? '');
+
+          if (known !== undefined) {
+            return { session: known.descriptor };
+          }
+
+          const descriptor = createSession(spawn);
+
+          if (key !== undefined) {
+            spawnKeys.set(key, descriptor.id);
+          }
+
+          return { session: descriptor };
+        }),
+      get: (get) =>
+        answer('get', get, () => {
+          const session = getSession(get);
+
+          return {
+            session: session.descriptor,
+            prompt: null,
+            lastActivityAt: session.lastActivityAt,
+            pending: null,
+            result: null,
+            sessionRecord: null,
+          };
+        }),
+      list: (list) =>
+        answer('list', list, () => ({
+          sessions: [...sessions.values()].map((session) => session.descriptor),
+        })),
+
+      // a plain kill of an exited session forgets it; a stop-only kill leaves it listed
+      kill: (kill) =>
+        answer('kill', kill, () => {
+          const session = getSession(kill);
+
+          if (session.descriptor.lifecycle.harness !== 'running') {
+            if (kill.stopOnly !== true) {
+              sessions.delete(session.descriptor.id);
+            }
+
+            return { stopped: false };
+          }
+
+          if (session.targetKind === 'local') {
+            setHarness(session, 'exited', 'stop');
+          } else {
+            setHarness(session, 'suspended', 'sleep');
+          }
+
+          return { stopped: true };
+        }),
+
+      // atc refuses an adopt of a session that runs with the code of an unknown session
+      adopt: (adopt) =>
+        answer('adopt', adopt, () => {
+          const session = sessions.get(sessionInputSchema.parse(adopt).session);
+
+          if (session === undefined) {
+            throw new FakeAtcError('session_dead');
+          }
+
+          if (session.descriptor.lifecycle.harness === 'running') {
+            throw new FakeAtcError('no_such_session');
+          }
+
+          setHarness(session, 'running', 'run');
+
+          session.lastActivityAt = input.clock.now();
+
+          return {};
+        }),
+
+      // a target that destroys its hosts takes two calls: the first answers a confirm token
+      forget: (forget) =>
+        answer('forget', forget, () => {
+          const session = getSession(forget);
+          const id = session.descriptor.id;
+
+          if (forget.refuseLive === true && session.descriptor.lifecycle.harness === 'running') {
+            throw new FakeAtcError('session_live');
+          }
+
+          if (session.targetKind === 'suspending' && forget.confirmToken === undefined) {
+            confirmTokens.set(`confirm-${id}`, id);
+
+            return { confirmToken: `confirm-${id}`, expiresAt: input.clock.now() + 60_000 };
+          }
+
+          if (
+            session.targetKind === 'suspending' &&
+            confirmTokens.get(forget.confirmToken ?? '') !== id
+          ) {
+            throw new FakeAtcError('confirm_token_invalid');
+          }
+
+          sessions.delete(id);
+
+          return {
+            forgotten: true as const,
+            destroyed: session.targetKind === 'suspending',
+            workspace: { outcome: 'none' as const },
+          };
+        }),
+      message: (message) =>
+        answer('message', message, () => {
+          const session = getSession(message);
+
+          if (session.descriptor.lifecycle.harness !== 'running') {
+            throw new FakeAtcError('session_dead');
+          }
+
+          const key = message.idempotencyKey;
+          const known = key === undefined ? undefined : session.messageKeys.get(key);
+          const id = known ?? `m${session.messages.length + 1}-${session.descriptor.id}`;
+
+          if (known === undefined) {
+            const text = typeof message.text === 'string' ? message.text : '';
+
+            session.messages.push(text);
+
+            session.lastActivityAt = input.clock.now();
+          }
+
+          if (key !== undefined) {
+            session.messageKeys.set(key, id);
+          }
+
+          return { message: id, status: 'queued' as const };
+        }),
+    },
+    listMessages: (session) => sessions.get(session)?.messages ?? [],
+    patchSession: (id, patch) => {
+      const session = sessions.get(id);
+
+      if (session === undefined) {
+        throw new FakeAtcError('no_such_session');
+      }
+
+      const { harness, desired, lastActivityAt, ...fields } = patch;
+
+      session.descriptor = {
+        ...session.descriptor,
+        ...fields,
+        lifecycle: {
+          ...session.descriptor.lifecycle,
+          harness: harness ?? session.descriptor.lifecycle.harness,
+          desired: desired ?? session.descriptor.lifecycle.desired,
+        },
+      };
+
+      session.lastActivityAt = lastActivityAt ?? session.lastActivityAt;
+    },
+    failNext: (call, error) => {
+      failures.set(call, error);
+    },
+  };
+}

package/src/to-session-reading.ts

@@ -0,0 +1,63 @@
+import type { Attention, Instant, SessionReading } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import { match } from 'ts-pattern';
+import { findCallerIdentity } from './find-caller-identity.ts';
+import type { AtcSession, AtcSessionRead } from './types.ts';
+
+// atc lists a session as `exited` whenever its agent process is not running, a process asleep
+// inside its host included, so the reading comes from the harness layer of the lifecycle.
+export function toSessionReading(read: AtcSessionRead): SessionReading {
+  const session = read.session;
+  const atcSession = brandSchemas.atcSessionId.parse(session.id);
+
+  const agentSession =
+    session.agentSessionID === undefined
+      ? null
+      : brandSchemas.agentSessionId.parse(session.agentSessionID);
+
+  return (
+    match(session.lifecycle.harness)
+      .returnType<SessionReading>()
+      .with('running', () => ({
+        kind: 'running',
+        atcSession,
+        agentSession,
+        caller: findCallerIdentity(session),
+        attention: toAttention(session.state),
+        lastActivityAt: toInstant(Math.max(read.lastActivityAt, session.lastAttachedAt)),
+        lastOwnerAt: toInstant(session.lastAttachedAt),
+        usageLimitResetsAt: findUsageLimitResetsAt(),
+      }))
+
+      // `desired` is `run` only when the host slept by itself, with nobody asking
+      .with('suspended', () => ({
+        kind: 'suspended',
+        atcSession,
+        agentSession,
+        asked: session.lifecycle.desired !== 'run',
+      }))
+      .with('exited', () => ({ kind: 'ended', atcSession, agentSession }))
+      .exhaustive()
+  );
+}
+
+// `done`: the turn ended and the session waits for a prompt. `exited` never comes with a running
+// process, and reads as working.
+function toAttention(state: AtcSession['state']): Attention {
+  return match(state)
+    .returnType<Attention>()
+    .with('running', 'exited', () => 'working')
+    .with('needs_you', () => 'needs-input')
+    .with('done', () => 'turn-ended')
+    .exhaustive();
+}
+
+function toInstant(timeMs: number): Instant {
+  return brandSchemas.instant.parse(timeMs);
+}
+
+// atc reports no usage limit yet, so no session reads as stopped at the limit. When atc gives the
+// limit and its reset time, this is the one place that maps them to the reading (v1-open.md).
+function findUsageLimitResetsAt(): Instant | null {
+  return null;
+}

package/src/types.ts

@@ -0,0 +1,40 @@
+import type { DAEMON_CONTRACT } from '@atcx/contract';
+import type { z } from 'zod';
+
+type SessionProcedures = (typeof DAEMON_CONTRACT)['session'];
+
+type InputOf<Procedure> = Procedure extends { '~orpc': { inputSchema?: infer Schema } }
+  ? z.input<Schema>
+  : never;
+
+type OutputOf<Procedure> = Procedure extends { '~orpc': { outputSchema?: infer Schema } }
+  ? z.output<Schema>
+  : never;
+
+type CallOf<Procedure> = (input: InputOf<Procedure>) => Promise<OutputOf<Procedure>>;
+
+// `host` is the VM host that runs the session: sub-sessions on one machine share it, and a session
+// with no VM host has none. atc reports no usage limit.
+export type AtcSession = OutputOf<SessionProcedures['get']>['session'];
+
+// `session.get`'s answer. `lastActivityAt` is the time of the session's last trail event, in
+// milliseconds, or its creation time when it has none.
+export type AtcSessionRead = OutputOf<SessionProcedures['get']>;
+
+// The atc calls that the adapter makes, with atc's own inputs and answers. A call that atc refuses
+// rejects with an error that carries atc's `code` and `data`.
+export interface AtcClient {
+  readonly session: {
+    readonly spawn: (
+      input: InputOf<SessionProcedures['spawn']>,
+    ) => Promise<{ readonly session: AtcSession }>;
+    readonly get: (input: InputOf<SessionProcedures['get']>) => Promise<AtcSessionRead>;
+    readonly list: (
+      input: InputOf<SessionProcedures['list']>,
+    ) => Promise<{ readonly sessions: readonly AtcSession[] }>;
+    readonly kill: CallOf<SessionProcedures['kill']>;
+    readonly adopt: CallOf<SessionProcedures['adopt']>;
+    readonly forget: CallOf<SessionProcedures['forget']>;
+    readonly message: CallOf<SessionProcedures['message']>;
+  };
+}