@zgeoff/atc 1.0.3 → 2.1.0

package/src/daemon/daemon-connection.ts

@@ -15,6 +15,7 @@ import type { SessionID } from '../shared/session-id';
 import type { FleetEntry } from '../store/fleet-entry';
 import type { Dims } from './attach-registry';
 import type { AnswerResult } from './permission-registry';
+import type { ScreenText } from './screen-model';
 import type { SessionDescriptor } from './sessions';
 
 interface SpawnParams {
@@ -41,6 +42,7 @@ export interface DaemonContext {
   readonly quitDaemon: () => void;
   readonly ackSession: (id: SessionID) => boolean;
   readonly buildResumeCommand: (id: SessionID) => string | null;
+  readonly readSessionScreen: (id: SessionID) => Promise<ScreenText | 'missing' | 'no_screen'>;
   readonly answerPermission: (request: string, decision: string) => AnswerResult;
   readonly restoreFleet: (cols: number, rows: number) => Promise<number>;
   readonly attachSession: (
@@ -168,7 +170,7 @@ export class DaemonConnection {
 
     for (const [sessionID, dropped] of this.desynced) {
       this.desynced.delete(sessionID);
-      this.sendEvent({ v: PROTOCOL_V, ev: 'session.desync', s: sessionID, dropped });
+      this.sendEvent({ v: PROTOCOL_V, ev: 'SessionDesync', s: sessionID, dropped });
       void this.ctx.resyncClient(sessionID, this);
     }
   }
@@ -304,6 +306,29 @@ export class DaemonConnection {
 
         return;
       }
+      case 'session.screen': {
+        const parsed = parseRequestParams('session.screen', req.p);
+
+        if (!parsed.ok) {
+          this.sendErr(req.id, 'bad_args', parsed.message);
+
+          return;
+        }
+
+        const id = parsed.data.session;
+
+        const screen = await this.ctx.readSessionScreen(id);
+
+        if (screen === 'missing') {
+          this.sendErr(req.id, 'no_such_session', `no session '${id}'`);
+        } else if (screen === 'no_screen') {
+          this.sendErr(req.id, 'session_dead', `session '${id}' has no captured screen`);
+        } else {
+          this.sendOk(req.id, { ...screen });
+        }
+
+        return;
+      }
       case 'session.eject': {
         const parsed = parseRequestParams('session.eject', req.p);
 

package/src/daemon/daemon.ts

@@ -2,6 +2,7 @@ import { unlinkSync, writeFileSync } from 'node:fs';
 import type { AgentAdapter } from '../agents/agent-adapter';
 import { MAX_CHUNK, PROTOCOL_V } from '../protocol/protocol';
 import type { EventMsg } from '../protocol/protocol';
+import type { HooksConfig } from '../shared/collect-hooks';
 import type { SessionID } from '../shared/session-id';
 import { StateStore } from '../store/state-store';
 import { AttachRegistry } from './attach-registry';
@@ -9,6 +10,8 @@ import { buildSessionEvent } from './build-session-event';
 import { DaemonConnection } from './daemon-connection';
 import type { DaemonContext, OutputClient } from './daemon-connection';
 import { startHookServer } from './hooks';
+import { makeHookRunner } from './make-hook-runner';
+import type { HookScope } from './make-hook-runner';
 import { PermissionRegistry } from './permission-registry';
 import { restoreFleet } from './restore-fleet';
 import { runEjectHandoff } from './run-eject-handoff';
@@ -16,6 +19,7 @@ import { ScreenModel } from './screen-model';
 import { SessionRuntime } from './session-runtime';
 import { SessionManager } from './sessions';
 import type { SessionDescriptor, SessionState } from './sessions';
+import { startEventsServer } from './start-events-server';
 import { startHeadlessTurn } from './start-headless-turn';
 
 export interface DaemonOptions {
@@ -39,6 +43,14 @@ export interface DaemonOptions {
   // When set, the daemon's pid is written here and removed on stop.
   readonly pidPath?: string;
 
+  // When set, a read-only events socket listens here and streams every
+  // broadcast event as NDJSON to any subscriber, no handshake required.
+  readonly eventsSocketPath?: string;
+
+  // User-configured hooks, keyed by wire-event name; each broadcast event
+  // fires its matching commands, observational and fire-and-forget.
+  readonly hooks?: HooksConfig;
+
   // Where the statusline contract file is written; defaults to the real one.
   readonly statusPath?: string;
 
@@ -86,27 +98,55 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   const mgr = new SessionManager(opts.adapter, store, opts.statusPath, opts.adapters ?? []);
   const clients = new Set<DaemonConnection>();
 
-  const emitEvent = (event: EventMsg) => {
+  const runHooks = makeHookRunner(opts.hooks ?? {});
+
+  const eventsServer =
+    opts.eventsSocketPath === undefined
+      ? null
+      : startEventsServer({
+          socketPath: opts.eventsSocketPath,
+          collectSnapshot: () =>
+            mgr.collectDescriptors().map((session) => ({
+              v: PROTOCOL_V,
+              ev: 'SessionAdded',
+              session,
+            })),
+          ...(opts.queueBytes === undefined ? {} : { queueBytes: opts.queueBytes }),
+        });
+
+  const emitEvent = (event: EventMsg, scope: HookScope | null = null) => {
     for (const client of clients) {
       client.sendEvent(event);
     }
+
+    eventsServer?.broadcast(event);
+    runHooks(event, scope);
+  };
+
+  const findHookScope = (sessionID: SessionID): HookScope | null => {
+    const s = mgr.sessions.find((x) => x.id === sessionID);
+
+    return s === undefined ? null : { cwd: s.cwd, repoRoot: s.repoRoot };
   };
 
   const registry = new PermissionRegistry();
 
   registry.onRequested = (req) => {
-    emitEvent({
-      v: PROTOCOL_V,
-      ev: 'permission.requested',
-      request: req.id,
-      s: req.sessionID,
-      message: req.message,
-      respondable: req.respondable,
-    });
+    emitEvent(
+      {
+        v: PROTOCOL_V,
+        ev: 'PermissionRequested',
+        request: req.id,
+        s: req.sessionID,
+        message: req.message,
+        respondable: req.respondable,
+      },
+      findHookScope(req.sessionID),
+    );
   };
 
   registry.onResolved = (id, decision) => {
-    emitEvent({ v: PROTOCOL_V, ev: 'permission.resolved', request: id, decision });
+    emitEvent({ v: PROTOCOL_V, ev: 'PermissionResolved', request: id, decision });
   };
 
   // One runtime per live session: its screen model, output sequence
@@ -161,7 +201,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
       client.sendOutput(
         sessionID,
-        { v: PROTOCOL_V, ev: 'session.output', s: sessionID, seq, d: chunk },
+        { v: PROTOCOL_V, ev: 'SessionOutput', s: sessionID, seq, d: chunk },
         chunk.length,
       );
     }
@@ -190,13 +230,16 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       runtime.dims = dims;
     }
 
-    emitEvent({
-      v: PROTOCOL_V,
-      ev: 'session.resized',
-      s: sessionID,
-      cols: dims.cols,
-      rows: dims.rows,
-    });
+    emitEvent(
+      {
+        v: PROTOCOL_V,
+        ev: 'SessionResized',
+        s: sessionID,
+        cols: dims.cols,
+        rows: dims.rows,
+      },
+      findHookScope(sessionID),
+    );
   };
 
   // Debounced so two clients resizing in opposite directions cannot produce
@@ -258,7 +301,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
       seq++;
 
-      const event: EventMsg = { v: PROTOCOL_V, ev: 'session.output', s: s.id, seq, d: chunk };
+      const event: EventMsg = { v: PROTOCOL_V, ev: 'SessionOutput', s: s.id, seq, d: chunk };
 
       for (const conn of conns) {
         conn.sendOutput(s.id, event, chunk.length);
@@ -270,6 +313,20 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     }
   };
 
+  // A detach can outlive its session — a kill removes the session before the
+  // client's connection closes — and a gone session already broadcast
+  // SessionRemoved, so a descriptor miss emits nothing.
+  const emitSessionDetached = (sessionID: SessionID) => {
+    const session = mgr.collectDescriptors().find((x) => x.id === sessionID);
+
+    if (session !== undefined) {
+      emitEvent(
+        { v: PROTOCOL_V, ev: 'SessionDetached', session },
+        { cwd: session.cwd, repoRoot: session.repoRoot },
+      );
+    }
+  };
+
   // Permission requests are synthesized from attention transitions: entering
   // needs_you opens one, and leaving it (answered directly in the terminal,
   // or the session dying) dismisses whatever is pending. Each session's
@@ -319,7 +376,9 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     const event = buildSessionEvent(mgr, kind, s);
 
     if (event !== null) {
-      emitEvent(event);
+      // The scope comes from the session object rather than a descriptor
+      // lookup, so dir-filtered hooks still fire for a removed session.
+      emitEvent(event, { cwd: s.cwd, repoRoot: s.repoRoot });
     }
   };
 
@@ -466,6 +525,18 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       return true;
     },
     buildResumeCommand: (id) => mgr.buildResumeCommand(id),
+
+    // A killed session keeps its last screen until a second kill removes
+    // it, so a reader can still see what the agent printed before it died.
+    readSessionScreen: (id) => {
+      if (!mgr.sessions.some((x) => x.id === id)) {
+        return Promise.resolve('missing');
+      }
+
+      const screen = runtimes.get(id)?.screen ?? null;
+
+      return screen === null ? Promise.resolve('no_screen') : screen.renderText();
+    },
     answerPermission: (request, decision) => registry.answer(request, decision),
     attachSession: (client, sessionID, dims) => {
       const s = mgr.sessions.find((x) => x.id === sessionID);
@@ -488,17 +559,27 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       // only redraws its live region, never the rows above it.
       applyEffectiveDims(sessionID);
       void sendReplay(sessionID, client);
+      const attached = getDescriptor(mgr, sessionID);
+
+      emitEvent(
+        { v: PROTOCOL_V, ev: 'SessionAttached', session: attached },
+        { cwd: attached.cwd, repoRoot: attached.repoRoot },
+      );
 
       return 'ok';
     },
     detachSession: (client, sessionID) => {
-      attachments.detach(sessionID, client);
+      if (!attachments.detach(sessionID, client)) {
+        return;
+      }
 
       scheduleResize(sessionID);
+      emitSessionDetached(sessionID);
     },
     detachClient: (client) => {
       for (const sessionID of attachments.detachAll(client)) {
         scheduleResize(sessionID);
+        emitSessionDetached(sessionID);
       }
     },
     writeSessionInput: (sessionID, data) => {
@@ -570,6 +651,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
   stopDaemon = async () => {
     server.stop(true);
+    eventsServer?.stop();
     reporter.stop(true);
     mgr.killAll();
 

package/src/daemon/make-hook-runner.ts

@@ -0,0 +1,84 @@
+import type { EventMsg } from '../protocol/protocol';
+import type { HookEntry, HooksConfig } from '../shared/collect-hooks';
+
+/**
+ * The session paths a hook's `dir` filter is matched against. Null when the
+ * event carries no session, in which case only unfiltered hooks fire.
+ */
+export interface HookScope {
+  readonly cwd: string;
+  readonly repoRoot: string;
+}
+
+export type RunHooks = (event: EventMsg, scope: HookScope | null) => void;
+
+/**
+ * Builds the daemon's hook runner. Each call fires every configured command
+ * for the event's name, with the wire-event JSON on stdin and the event name
+ * in `ATC_EVENT`. Hooks are observational and fire-and-forget: the daemon
+ * never waits on one, a run past its timeout is killed, and a nonzero exit
+ * or spawn failure is logged to stderr and otherwise ignored.
+ */
+export function makeHookRunner(hooks: HooksConfig): RunHooks {
+  return (event, scope) => {
+    for (const entry of hooks[event.ev] ?? []) {
+      if (entry.dir === undefined || isInScope(entry.dir, scope)) {
+        runHook(entry, event);
+      }
+    }
+  };
+}
+
+function isInScope(dir: string, scope: HookScope | null): boolean {
+  if (scope === null) {
+    return false;
+  }
+
+  return isUnderDir(scope.repoRoot, dir) || isUnderDir(scope.cwd, dir);
+}
+
+// Path-segment containment: /a/b contains /a/b and /a/b/c, never /a/bc.
+function isUnderDir(candidate: string, dir: string): boolean {
+  const prefix = dir === '/' ? '/' : `${dir}/`;
+
+  return candidate === dir || candidate.startsWith(prefix);
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+function runHook(entry: HookEntry, event: EventMsg): void {
+  let proc: ReturnType<typeof Bun.spawn>;
+
+  try {
+    proc = Bun.spawn(['/bin/sh', '-c', entry.command], {
+      stdin: Buffer.from(`${JSON.stringify(event)}\n`),
+      stdout: 'ignore',
+      stderr: 'ignore',
+      env: { ...process.env, ATC_EVENT: event.ev },
+    });
+  } catch (error) {
+    console.error(`atc hook for ${event.ev} failed to spawn: ${String(error)}`);
+
+    return;
+  }
+
+  // Unref'd so an in-flight hook never keeps the daemon process alive; a
+  // hook orphaned by daemon exit is on its own.
+  const timer = setTimeout(() => {
+    proc.kill();
+  }, entry.timeout ?? DEFAULT_TIMEOUT_MS);
+
+  timer.unref();
+
+  void (async () => {
+    try {
+      const code = await proc.exited;
+
+      if (code !== 0) {
+        console.error(`atc hook for ${event.ev} exited ${code}`);
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  })();
+}

package/src/daemon/screen-model.ts

@@ -2,6 +2,12 @@ import { SerializeAddon } from '@xterm/addon-serialize';
 import { Terminal } from '@xterm/headless';
 import { RESET_INPUT_MODES } from '../shared/reset-input-modes';
 
+export interface ScreenText {
+  readonly text: string;
+  readonly cols: number;
+  readonly rows: number;
+}
+
 // The serializer already re-emits the modes the vt engine models (mouse
 // tracking, bracketed paste, focus events); these are the ones it drops.
 const REPLAYED_DEC_MODES = new Set([1006, 1007, 2031]);
@@ -84,21 +90,34 @@ export class ScreenModel {
     });
   }
 
-  // The terminal parses asynchronously, and bytes recorded while a flush is
-  // awaited re-arm it — so the replay drains until no newer write is
-  // pending. Serializing earlier would omit bytes already streamed live to
-  // clients, and the replay's leading clear would erase them from the
-  // client's screen for good.
+  // Serializing before the flush drains would omit bytes already streamed
+  // live to clients, and the replay's leading clear would erase them from
+  // the client's screen for good.
   async renderReplay(): Promise<string> {
-    let pending: Promise<void>;
+    await this.waitForFlush();
 
-    do {
-      pending = this.flushed;
+    return RESET_INPUT_MODES + this.renderVisibleScreen() + this.renderInputModes();
+  }
 
-      await pending;
-    } while (pending !== this.flushed);
+  // The visible rows of whichever buffer the session is showing, as plain
+  // text with no escape sequences: one line per row, trailing blanks
+  // trimmed from each row, trailing blank rows dropped. Drains pending
+  // writes first, so text recorded just before the read is never missing.
+  async renderText(): Promise<ScreenText> {
+    await this.waitForFlush();
 
-    return RESET_INPUT_MODES + this.renderVisibleScreen() + this.renderInputModes();
+    const buffer = this.term.buffer.active;
+    const lines: string[] = [];
+
+    for (let y = 0; y < this.term.rows; y++) {
+      lines.push((buffer.getLine(buffer.baseY + y)?.translateToString(true) ?? '').trimEnd());
+    }
+
+    while (lines.length > 0 && lines.at(-1) === '') {
+      lines.pop();
+    }
+
+    return { text: lines.join('\n'), cols: this.term.cols, rows: this.term.rows };
   }
 
   updateDims(cols: number, rows: number): void {
@@ -109,6 +128,18 @@ export class ScreenModel {
     this.term.dispose();
   }
 
+  // The terminal parses asynchronously, and bytes recorded while a flush is
+  // awaited re-arm it — so this drains until no newer write is pending.
+  private async waitForFlush(): Promise<void> {
+    let pending: Promise<void>;
+
+    do {
+      pending = this.flushed;
+
+      await pending;
+    } while (pending !== this.flushed);
+  }
+
   // A session on the alternate screen serializes as the normal buffer, a
   // buffer switch, then the alternate buffer. The switch clears nothing on a
   // terminal already in alternate mode — and the client always is, since its

package/src/daemon/start-events-server.ts

@@ -0,0 +1,97 @@
+import { unlinkSync } from 'node:fs';
+import { OutboundQueue } from '../protocol/outbound-queue';
+import { encodeMessage } from '../protocol/protocol';
+import type { EventMsg } from '../protocol/protocol';
+
+interface EventsServerOptions {
+  readonly socketPath: string;
+
+  // Events replayed to a subscriber the moment it connects, ahead of any
+  // live broadcast, so a subscriber learns the current fleet without
+  // speaking the client protocol.
+  readonly collectSnapshot: () => readonly EventMsg[];
+
+  // Outbound queue capacity per subscriber; small values force the overflow
+  // disconnect in tests.
+  readonly queueBytes?: number;
+}
+
+export interface EventsServer {
+  readonly broadcast: (event: EventMsg) => void;
+  readonly stop: () => void;
+}
+
+interface Subscriber {
+  readonly queue: OutboundQueue;
+  readonly end: () => void;
+}
+
+/**
+ * Starts the read-only events listener. A subscriber connects with no
+ * handshake and receives NDJSON wire events: first the snapshot, then every
+ * broadcast behind it. Input on the socket is ignored. A subscriber whose
+ * outbound queue overflows is disconnected rather than stalled — on
+ * reconnect it gets a fresh snapshot instead of the backlog it missed.
+ */
+export function startEventsServer(opts: EventsServerOptions): EventsServer {
+  const subscribers = new Set<Subscriber>();
+
+  try {
+    unlinkSync(opts.socketPath);
+  } catch {}
+
+  const server = Bun.listen<Subscriber>({
+    unix: opts.socketPath,
+    socket: {
+      open(socket) {
+        const subscriber: Subscriber = {
+          queue: new OutboundQueue(socket, opts.queueBytes),
+          end: () => {
+            socket.end();
+          },
+        };
+
+        socket.data = subscriber;
+
+        subscribers.add(subscriber);
+
+        for (const event of opts.collectSnapshot()) {
+          if (!subscriber.queue.send(encodeMessage(event))) {
+            subscriber.end();
+
+            return;
+          }
+        }
+      },
+      data() {},
+      drain(socket) {
+        socket.data.queue.drain();
+      },
+      close(socket) {
+        subscribers.delete(socket.data);
+      },
+      error() {},
+    },
+  });
+
+  return {
+    broadcast(event) {
+      const line = encodeMessage(event);
+
+      for (const subscriber of subscribers) {
+        if (!subscriber.queue.send(line)) {
+          subscriber.end();
+        }
+      }
+    },
+    stop() {
+      server.stop(true);
+
+      for (const subscriber of subscribers) {
+        subscriber.end();
+      }
+
+      subscribers.clear();
+    },
+  };
+}

package/src/events.ts

@@ -0,0 +1,33 @@
+import { eventsSocketPath } from './shared/config';
+
+/**
+ * Streams the daemon's events socket to stdout, one NDJSON wire event per
+ * line, until the daemon closes the connection. When no daemon is
+ * listening, prints a hint to stderr and exits nonzero instead of booting
+ * one.
+ */
+export async function runEvents(): Promise<void> {
+  const closed = Promise.withResolvers<void>();
+
+  try {
+    await Bun.connect({
+      unix: eventsSocketPath,
+      socket: {
+        data(_socket, buf) {
+          process.stdout.write(buf);
+        },
+        close() {
+          closed.resolve();
+        },
+        error() {
+          closed.resolve();
+        },
+      },
+    });
+  } catch {
+    console.error(`atc events: no daemon at ${eventsSocketPath} — start atc first`);
+    process.exit(1);
+  }
+
+  await closed.promise;
+}

package/src/mcp-server.ts

@@ -74,6 +74,12 @@ const TOOLS: readonly MCPTool[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'atc_session_screen',
+    description:
+      'Read the current terminal screen of a session as plain text, without attaching to it. Use it to see what a session printed or what it is waiting on before answering it with atc_session_input. A killed session keeps its last screen.',
+    inputSchema: SESSION_INPUT,
+  },
   {
     name: 'atc_session_update',
     description:
@@ -262,6 +268,11 @@ async function runTool(
 
       return 'sent';
     }
+    case 'atc_session_screen': {
+      const ok = await client.sendRequest('session.screen', { session: args['session'] });
+
+      return typeof ok['text'] === 'string' ? ok['text'] : JSON.stringify(ok);
+    }
     case 'atc_session_update': {
       await client.sendRequest('session.update', {
         session: args['session'],

package/src/protocol/protocol.ts

@@ -5,7 +5,7 @@ import { isRecord } from '../shared/report';
  * per line. Three message kinds, distinguished by which fields are present —
  * request (id + m), response (id + ok or err), event (ev).
  */
-export const PROTOCOL_V = 2;
+export const PROTOCOL_V = 3;
 
 // Control lines are capped before buffering; PTY output is split into chunks
 // so a queued response is delayed by at most one chunk.

package/src/protocol/request-param-schemas.ts

@@ -64,6 +64,7 @@ export const REQUEST_PARAM_SCHEMAS = {
     message: 'session.resize requires positive cols and rows',
   }),
   'session.resumeCommand': SESSION_DEFAULTED,
+  'session.screen': SESSION_DEFAULTED,
   'session.eject': SESSION_DEFAULTED.extend({
     prompt: buildDefaultedNonEmptyString(EJECT_DEFAULT_PROMPT),
   }),