@zgeoff/atc 2.5.1 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/agents/agent-adapter.ts

@@ -46,6 +46,23 @@ export interface AdapterEvent {
   // Claude resume-existence path. Distinct from nameSource: a naming
   // handle is not a resume gate.
   transcriptSource?: string;
+
+  // The agent's whole final message for a finished turn; detail holds a bounded preview of it.
+  result?: string;
+}
+
+export interface TranscriptToolUse {
+  readonly name: string;
+  readonly input: string;
+}
+
+export interface TranscriptRow {
+  readonly role: 'user' | 'assistant';
+  readonly text: string;
+  readonly tools: readonly TranscriptToolUse[];
+
+  // Epoch ms from the line's timestamp.
+  readonly at: number | null;
 }
 
 export interface NameUpdate {
@@ -118,4 +135,9 @@ export interface AgentAdapter {
     cwd: string,
     agentSessionID: AgentSessionID | undefined,
   ) => string | null;
+
+  // Turns one line of the agent's transcript file into a conversation row,
+  // null for a line that is not one. Absent: atc cannot read this agent's
+  // transcript.
+  readonly parseTranscriptLine?: (line: string) => TranscriptRow | null;
 }

package/src/agents/claude-adapter.ts

@@ -16,6 +16,7 @@ import type {
   SpawnOptions,
   SpawnPlan,
 } from './agent-adapter';
+import { parseClaudeTranscriptLine } from './parse-claude-transcript-line';
 import { truncateDetail } from './truncate-detail';
 import { writeHookSettings } from './write-hook-settings';
 
@@ -44,6 +45,8 @@ export class ClaudeAdapter implements AgentAdapter {
   // Claude's hooks are authoritative; no screen heuristics needed.
   readonly screenDetector = null;
 
+  readonly parseTranscriptLine = parseClaudeTranscriptLine;
+
   private readonly config: Config;
 
   // Written on first spawn so constructing the adapter touches no state.
@@ -110,7 +113,7 @@ export class ClaudeAdapter implements AgentAdapter {
           ...named,
           kind: 'turn-done',
           ...(lastMessage !== undefined && lastMessage !== ''
-            ? { detail: truncateDetail(lastMessage) }
+            ? { detail: truncateDetail(lastMessage), result: lastMessage }
             : {}),
         };
       }

package/src/agents/codex-adapter.ts

@@ -117,7 +117,7 @@ export class CodexAdapter implements AgentAdapter {
           ...named,
           kind: 'turn-done',
           ...(lastMessage !== undefined && lastMessage !== ''
-            ? { detail: truncateDetail(lastMessage) }
+            ? { detail: truncateDetail(lastMessage), result: lastMessage }
             : {}),
         };
       }

package/src/agents/gateway-adapter.ts

@@ -14,6 +14,7 @@ import type {
   SpawnPlan,
 } from './agent-adapter';
 import { ClaudeAdapter } from './claude-adapter';
+import { parseClaudeTranscriptLine } from './parse-claude-transcript-line';
 import { writeHookSettings } from './write-hook-settings';
 
 /**
@@ -33,6 +34,9 @@ export class GatewayAdapter implements AgentAdapter {
   // The CLI's hooks are authoritative; no screen heuristics needed.
   readonly screenDetector = null;
 
+  // The gateway runs the Claude CLI, which writes the same transcript.
+  readonly parseTranscriptLine = parseClaudeTranscriptLine;
+
   private readonly gateway: GatewayConfig;
 
   private readonly claude: ClaudeAdapter;

package/src/agents/grok-adapter.ts

@@ -269,7 +269,7 @@ function buildTurnDoneEvent(named: Readonly<AdapterEvent>, payload: GrokHookPayl
     ...named,
     kind: 'turn-done',
     ...(lastMessage !== undefined && lastMessage !== ''
-      ? { detail: truncateDetail(lastMessage) }
+      ? { detail: truncateDetail(lastMessage), result: lastMessage }
       : {}),
   };
 }

package/src/agents/parse-claude-transcript-line.ts

@@ -0,0 +1,107 @@
+import { isRecord } from '../shared/report';
+import { truncateToBytes } from '../shared/truncate-to-bytes';
+import type { TranscriptRow, TranscriptToolUse } from './agent-adapter';
+
+// One row must stay far under the protocol's line cap.
+const MAX_ROW_TEXT_BYTES = 16_384;
+
+export function parseClaudeTranscriptLine(line: string): TranscriptRow | null {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+
+  if (!isRecord(parsed)) {
+    return null;
+  }
+
+  const type = parsed['type'];
+
+  if (type !== 'user' && type !== 'assistant') {
+    return null;
+  }
+
+  if (parsed['isSidechain'] === true || parsed['isMeta'] === true) {
+    return null;
+  }
+
+  const message = parsed['message'];
+
+  if (!isRecord(message)) {
+    return null;
+  }
+
+  const content = message['content'];
+  const texts: string[] = [];
+  const tools: TranscriptToolUse[] = [];
+
+  if (typeof content === 'string') {
+    texts.push(content);
+  } else if (Array.isArray(content)) {
+    for (const block of content as unknown[]) {
+      if (!isRecord(block)) {
+        continue;
+      }
+
+      const text = block['text'];
+      const name = block['name'];
+
+      if (block['type'] === 'text' && typeof text === 'string') {
+        texts.push(text);
+      } else if (block['type'] === 'tool_use' && typeof name === 'string') {
+        tools.push({ name, input: formatToolInput(block['input']) });
+      }
+    }
+  } else {
+    return null;
+  }
+
+  const text = texts.join('\n');
+
+  if (text === '' && tools.length === 0) {
+    return null;
+  }
+
+  const timestamp = parsed['timestamp'];
+  const parsedAt = typeof timestamp === 'string' ? Date.parse(timestamp) : Number.NaN;
+
+  return {
+    role: type,
+    text: truncateToBytes(text, MAX_ROW_TEXT_BYTES),
+    tools,
+    at: Number.isNaN(parsedAt) ? null : parsedAt,
+  };
+}
+
+const TOOL_INPUT_KEYS = [
+  'command',
+  'file_path',
+  'path',
+  'pattern',
+  'url',
+  'query',
+  'description',
+  'prompt',
+];
+
+function formatToolInput(input: unknown): string {
+  if (!isRecord(input)) {
+    return '';
+  }
+
+  let summary = JSON.stringify(input);
+
+  for (const key of TOOL_INPUT_KEYS) {
+    const value = input[key];
+
+    if (typeof value === 'string') {
+      summary = value;
+      break;
+    }
+  }
+
+  return summary.length <= 200 ? summary : `${summary.slice(0, 199)}…`;
+}

package/src/daemon/build-fleet-events.ts

@@ -0,0 +1,35 @@
+import { encodeCursor } from '../protocol/encode-cursor';
+import type { StoredEvent } from '../store/state-store';
+import type { SessionDescriptor } from './sessions';
+
+export interface FleetEvent {
+  readonly cursor: string;
+  readonly at: number;
+  readonly session: string;
+  readonly name: string | null;
+  readonly kind: string;
+  readonly detail: string | null;
+}
+
+export function buildFleetEvents(
+  rows: readonly StoredEvent[],
+  sessions: readonly SessionDescriptor[],
+): FleetEvent[] {
+  return rows.map((row) => {
+    // A restore re-mints atc ids, so the agent session id is the stable link.
+    const live =
+      (row.agentSessionID === null
+        ? undefined
+        : sessions.find((s) => s.agentSessionID === row.agentSessionID)) ??
+      sessions.find((s) => s.id === row.atcID);
+
+    return {
+      cursor: encodeCursor({ kind: 'events', id: row.id }),
+      at: row.at,
+      session: live?.id ?? row.atcID,
+      name: live?.name ?? null,
+      kind: row.kind,
+      detail: row.detail,
+    };
+  });
+}

package/src/daemon/daemon-connection.ts

@@ -1,5 +1,7 @@
 import { basename } from 'node:path';
 import type { AgentAdapter, AgentID, SpawnOptions } from '../agents/agent-adapter';
+import { decodeCursor } from '../protocol/decode-cursor';
+import { encodeCursor } from '../protocol/encode-cursor';
 import { OutboundQueue } from '../protocol/outbound-queue';
 import type { SocketWriter } from '../protocol/outbound-queue';
 import { parseRequestParams } from '../protocol/parse-request-params';
@@ -14,6 +16,8 @@ import type { ErrorCode, EventMsg, RequestMsg } from '../protocol/protocol';
 import type { SessionID } from '../shared/session-id';
 import type { FleetEntry } from '../store/fleet-entry';
 import type { Dims } from './attach-registry';
+import type { FleetEvent } from './build-fleet-events';
+import type { TranscriptPage, TranscriptPosition } from './load-transcript-page';
 import type { AnswerResult } from './permission-registry';
 import type { ScreenText } from './screen-model';
 import type { SessionDescriptor } from './sessions';
@@ -30,6 +34,21 @@ interface SpawnParams {
   readonly parent: SessionID | null;
 }
 
+interface SessionRecord {
+  readonly session: SessionDescriptor;
+  readonly prompt: string | null;
+  readonly lastActivityAt: number;
+  readonly pending: { readonly message: string } | null;
+  readonly result: string | null;
+}
+
+// A transcript page with the file it came from, so a cursor into a replaced
+// transcript is distinguishable from one into a grown transcript.
+interface SessionTranscriptRead {
+  readonly path: string;
+  readonly page: TranscriptPage;
+}
+
 export interface DaemonContext {
   readonly build: string;
   readonly collectSessions: () => SessionDescriptor[];
@@ -70,6 +89,17 @@ export interface DaemonContext {
   readonly resyncClient: (sessionID: SessionID, client: OutputClient) => Promise<void>;
   readonly queueBytes?: number;
   readonly getEffectiveDims: (sessionID: SessionID) => Dims;
+  readonly readSessionRecord: (id: SessionID) => Promise<SessionRecord | 'missing'>;
+  readonly loadSessionTranscript: (
+    id: SessionID,
+    from: TranscriptPosition | null,
+    limit: number,
+  ) => Promise<SessionTranscriptRead | 'missing' | 'unsupported'>;
+  readonly readEvents: (
+    afterID: number | null,
+    limit: number,
+    waitMs: number,
+  ) => Promise<FleetEvent[]>;
 }
 
 // The slice of a connection the attach bookkeeping needs: identity plus the
@@ -448,6 +478,21 @@ export class DaemonConnection {
 
         return;
       }
+      case 'session.get': {
+        await this.applySessionGet(req);
+
+        return;
+      }
+      case 'session.read': {
+        await this.applySessionRead(req);
+
+        return;
+      }
+      case 'events.read': {
+        await this.applyEventsRead(req);
+
+        return;
+      }
       default: {
         this.sendErr(req.id, 'unknown_method', `unknown method '${req.m}'`);
       }
@@ -631,6 +676,105 @@ export class DaemonConnection {
     }
   }
 
+  private async applySessionGet(req: RequestMsg): Promise<void> {
+    const parsed = parseRequestParams('session.get', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const id = parsed.data.session;
+
+    const record = await this.ctx.readSessionRecord(id);
+
+    if (record === 'missing') {
+      this.sendErr(req.id, 'no_such_session', `no session '${id}'`);
+
+      return;
+    }
+
+    this.sendOk(req.id, { ...record });
+  }
+
+  private async applySessionRead(req: RequestMsg): Promise<void> {
+    const parsed = parseRequestParams('session.read', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const id = parsed.data.session;
+    let from: TranscriptPosition | null = null;
+
+    if (parsed.data.cursor !== undefined) {
+      const decoded = decodeCursor(parsed.data.cursor);
+
+      if (decoded === null || decoded.kind !== 'transcript') {
+        this.sendErr(req.id, 'bad_args', `'${parsed.data.cursor}' is not a session.read cursor`);
+
+        return;
+      }
+
+      from = { path: decoded.path, offset: decoded.offset };
+    }
+
+    const read = await this.ctx.loadSessionTranscript(id, from, parsed.data.limit);
+
+    if (read === 'missing') {
+      this.sendErr(req.id, 'no_such_session', `no session '${id}'`);
+    } else if (read === 'unsupported') {
+      this.sendErr(
+        req.id,
+        'unsupported',
+        `session '${id}' runs an agent whose transcript atc cannot read`,
+      );
+    } else {
+      this.sendOk(req.id, {
+        rows: read.page.rows,
+        cursor: encodeCursor({ kind: 'transcript', path: read.path, offset: read.page.offset }),
+        more: read.page.more,
+      });
+    }
+  }
+
+  private async applyEventsRead(req: RequestMsg): Promise<void> {
+    const parsed = parseRequestParams('events.read', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    let afterID: number | null = null;
+
+    if (parsed.data.cursor !== undefined) {
+      const decoded = decodeCursor(parsed.data.cursor);
+
+      if (decoded === null || decoded.kind !== 'events') {
+        this.sendErr(req.id, 'bad_args', `'${parsed.data.cursor}' is not an events.read cursor`);
+
+        return;
+      }
+
+      afterID = decoded.id;
+    }
+
+    const events = await this.ctx.readEvents(afterID, parsed.data.limit, parsed.data.waitMs);
+
+    const last = events.at(-1);
+
+    // A cursor always comes back so a client can long-poll from an empty trail.
+    this.sendOk(req.id, {
+      events,
+      cursor: last === undefined ? encodeCursor({ kind: 'events', id: afterID ?? 0 }) : last.cursor,
+    });
+  }
+
   private async applySessionVerb(
     req: RequestMsg,
     method: 'session.kill' | 'session.ack',

package/src/daemon/daemon.ts

@@ -1,15 +1,19 @@
 import { unlinkSync, writeFileSync } from 'node:fs';
-import type { AgentAdapter } from '../agents/agent-adapter';
+import type { AdapterEvent, 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';
+import { buildFleetEvents } from './build-fleet-events';
 import { buildSessionEvent } from './build-session-event';
 import { DaemonConnection } from './daemon-connection';
 import type { DaemonContext, OutputClient } from './daemon-connection';
+import { EventSignal } from './event-signal';
 import { startHookServer } from './hooks';
+import type { HookEvent } from './hooks';
+import { loadTranscriptPage } from './load-transcript-page';
 import { makeHookRunner } from './make-hook-runner';
 import type { HookScope } from './make-hook-runner';
 import { PermissionRegistry } from './permission-registry';
@@ -130,6 +134,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   };
 
   const registry = new PermissionRegistry();
+  const eventSignal = new EventSignal();
 
   registry.onRequested = (req) => {
     emitEvent(
@@ -382,12 +387,20 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     }
   };
 
+  const recordHookEvent = async (e: HookEvent, ev: Readonly<AdapterEvent> | null) => {
+    await store.recordEvent(e, ev);
+
+    eventSignal.emit();
+  };
+
   const reporter = startHookServer((e) => {
+    const ev = mgr.applyHook(e);
+
     if (e.event !== 'Statusline') {
-      void store.recordEvent(e);
+      void recordHookEvent(e, ev);
     }
 
-    const kind = mgr.applyHook(e);
+    const kind = ev?.kind ?? null;
     const runtime = runtimes.get(e.atcId);
 
     if (kind === 'ended') {
@@ -636,6 +649,77 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       runtimes.get(sessionID)?.dims ?? { cols: 80, rows: 24 },
     restoreFleet: (cols, rows) =>
       restoreFleet({ mgr, store, findRuntime, cols, rows, capMs: opts.restoreBootTimeoutMs ?? 0 }),
+    readSessionRecord: async (id) => {
+      const s = mgr.sessions.find((x) => x.id === id);
+
+      if (s === undefined) {
+        return 'missing';
+      }
+
+      // Every session-derived field is taken before the await: a kill or a
+      // hook may change the session meanwhile.
+      const session = getDescriptor(mgr, id);
+      const prompt = s.prompt ?? null;
+      const pending = s.state === 'needs_you' ? { message: s.lastMsg } : null;
+      const result = s.result ?? null;
+      const createdAt = s.createdAt;
+
+      const lastEventAt = await store.loadLastActivityAt(s.id, s.agentSessionID);
+
+      return {
+        session,
+        prompt,
+        lastActivityAt: lastEventAt ?? createdAt,
+        pending,
+        result,
+      };
+    },
+    loadSessionTranscript: async (id, from, limit) => {
+      const s = mgr.sessions.find((x) => x.id === id);
+
+      if (s === undefined) {
+        return 'missing';
+      }
+
+      const parseLine = mgr.findAdapter(s.agent)?.parseTranscriptLine;
+
+      if (parseLine === undefined) {
+        return 'unsupported';
+      }
+
+      const path = s.transcriptPath ?? '';
+
+      if (path === '') {
+        return { path, page: { rows: [], offset: 0, more: false } };
+      }
+
+      // A page stays far under the protocol's 1 MiB line cap.
+      const page = await loadTranscriptPage({ path, from, limit, maxBytes: 262_144, parseLine });
+
+      return { path, page };
+    },
+    readEvents: async (afterID, limit, waitMs) => {
+      const deadline = Date.now() + waitMs;
+
+      // A wake for an event the read leaves out (a heartbeat) loops back to
+      // wait out the rest of the window.
+      for (;;) {
+        const generation = eventSignal.generation;
+
+        const rows =
+          afterID === null
+            ? await store.collectLatestEvents(limit)
+            : await store.collectEventsAfter(afterID, limit);
+
+        const remaining = deadline - Date.now();
+
+        if (rows.length > 0 || remaining <= 0 || eventSignal.disposed) {
+          return buildFleetEvents(rows, mgr.collectDescriptors());
+        }
+
+        await eventSignal.waitForNext(generation, remaining);
+      }
+    },
   };
 
   try {
@@ -675,6 +759,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     }
 
     runtimes.clear();
+    eventSignal.dispose();
 
     await store.stop();
 

package/src/daemon/event-signal.ts

@@ -0,0 +1,54 @@
+/**
+ * Wakes long-polling readers when the event trail grows. A reader notes the
+ * signal's count before it queries and waits from that count, so an event
+ * recorded between the query and the wait is never missed.
+ */
+export class EventSignal {
+  generation = 0;
+
+  disposed = false;
+
+  private readonly waiters = new Set<() => void>();
+
+  emit(): void {
+    this.generation += 1;
+
+    this.drainWaiters();
+  }
+
+  waitForNext(since: number, timeoutMs: number): Promise<void> {
+    if (this.disposed || this.generation !== since || timeoutMs <= 0) {
+      return Promise.resolve();
+    }
+
+    const deferred = Promise.withResolvers<void>();
+
+    const onWake = () => {
+      clearTimeout(timer);
+
+      this.waiters.delete(onWake);
+      deferred.resolve();
+    };
+
+    const timer = setTimeout(onWake, timeoutMs);
+
+    this.waiters.add(onWake);
+
+    return deferred.promise;
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.generation += 1;
+
+    this.drainWaiters();
+  }
+
+  private drainWaiters(): void {
+    for (const wake of this.waiters) {
+      wake();
+    }
+
+    this.waiters.clear();
+  }
+}