@zgeoff/atc 2.0.0 → 2.1.0

package/README.md

@@ -97,13 +97,24 @@ reporting works.
   is taken on your machine.
 - [Gateways](./docs/guides/configuration.md#gateways) — run the Claude CLI against Claude-compatible
   backends (GLM and friends), each as its own agent in one fleet.
-- [Daemon hooks](./docs/guides/configuration.md#daemon-hooks) — run your own commands on fleet
-  events, or pipe the full NDJSON event stream from `atc events`.
 - [Attention hooks](./docs/guides/configuration.md#attention-hooks-grok-and-codex) — the Grok and
   Codex self-install in detail.
 
-`atc mcp` exposes the fleet as MCP tools (list, spawn, drive, organise) to any MCP client, wrangled
-sessions included:
+## Integrations
+
+Everything the fleet does broadcasts as a wire event — sessions added, state changes, attaches,
+renames, permission requests. The [events guide](./docs/guides/events.md) covers the three ways to
+consume the stream:
+
+- [Daemon hooks](./docs/guides/events.md#daemon-hooks) — run your own commands on fleet events,
+  straight from `config.json`.
+- [`atc events`](./docs/guides/events.md#atc-events) — the stream on stdout, one NDJSON line per
+  event; pipe it into `jq` or your own tooling.
+- [The events socket](./docs/guides/events.md#the-events-socket) — a read-only unix socket any
+  program can subscribe to, stable across atc upgrades.
+
+`atc mcp` exposes the fleet as MCP tools (list, spawn, drive, read the screen, organise) to any MCP
+client, wrangled sessions included:
 
 ```sh
 claude mcp add --scope user atc -- atc mcp

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Terminal control tower for Claude Code sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
@@ -59,5 +59,9 @@
     "type-fest": "5.8.0",
     "typescript": "7.0.2"
   },
+  "overrides": {
+    "fast-uri": "3.1.6",
+    "qs": "6.16.0"
+  },
   "packageManager": "bun@1.3.10"
 }

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: (
@@ -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

@@ -525,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);

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/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/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),
   }),