@zgeoff/atc 2.5.1 → 2.7.0

package/src/daemon/daemon.ts

@@ -1,26 +1,38 @@
 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 { truncateToBytes } from '../shared/truncate-to-bytes';
+import type { MessageOwner } from '../store/message-owner';
+import type { MessageRecord } from '../store/message-record';
 import { StateStore } from '../store/state-store';
+import { ANSWER_BYTE_CAP } from './answer-byte-cap';
 import { AttachRegistry } from './attach-registry';
+import { buildFleetEvents } from './build-fleet-events';
 import { buildSessionEvent } from './build-session-event';
+import { buildSessionMessageEvent } from './build-session-message-event';
 import { DaemonConnection } from './daemon-connection';
-import type { DaemonContext, OutputClient } from './daemon-connection';
+import type { DaemonContext, OutputClient, TapClient } 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 { mintMessageID } from './mint-message-id';
+import { parseReport } from './parse-report';
 import { PermissionRegistry } from './permission-registry';
 import { restoreFleet } from './restore-fleet';
 import { runEjectHandoff } from './run-eject-handoff';
 import { ScreenModel } from './screen-model';
 import { SessionRuntime } from './session-runtime';
 import { SessionManager } from './sessions';
-import type { SessionDescriptor, SessionState } from './sessions';
+import type { Session, SessionDescriptor, SessionState } from './sessions';
 import { startEventsServer } from './start-events-server';
 import { startHeadlessTurn } from './start-headless-turn';
+import { TapRegistry } from './tap-registry';
 
 export interface DaemonOptions {
   readonly socketPath: string;
@@ -67,6 +79,7 @@ export interface DaemonOptions {
   // single revive waits for that signal before moving on regardless, so a
   // session that never reports cannot stall the rest. Zero waits forever.
   readonly restoreBootTimeoutMs?: number;
+  readonly tapGraceMs?: number;
 
   // Called after a client-requested quit has stopped the daemon; the real
   // entrypoint exits the process, tests leave it unset.
@@ -77,6 +90,10 @@ export interface DaemonHandle {
   readonly stop: () => Promise<void>;
 }
 
+// How long a started Claude session may go without a tap before a message to
+// it is refused.
+const TAP_GRACE_MS = 15_000;
+
 /**
  * The daemon: owns the sessions, the client-protocol listener, and the
  * reporter listener. Protocol requests are NDJSON lines, one response per
@@ -130,6 +147,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   };
 
   const registry = new PermissionRegistry();
+  const eventSignal = new EventSignal();
 
   registry.onRequested = (req) => {
     emitEvent(
@@ -159,6 +177,81 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   const findRuntime = (sessionID: SessionID) => runtimes.get(sessionID);
 
   const attachments = new AttachRegistry<OutputClient>();
+  const taps = new TapRegistry<TapClient>();
+
+  // Writes accepted messages one at a time so the store's insertion order is
+  // the order of their sent times, which the inbox drains by.
+  let lastMessageWrite: Promise<void> = Promise.resolve();
+
+  // Hands one pending message to the session's tap, once, and reports whether
+  // it did. The event goes to the tap connection alone: it never reaches
+  // other clients, the events socket, or hooks.
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- every field is readonly; the branded id has no readonly form to wrap it in
+  const sendInboxMessage = (sessionID: SessionID, record: MessageRecord): boolean => {
+    const tap = taps.claimDelivery(sessionID, record.id);
+
+    if (tap === null) {
+      return false;
+    }
+
+    tap.sendEvent({
+      v: PROTOCOL_V,
+      ev: 'InboxMessage',
+      s: sessionID,
+      message: record.id,
+      from: record.from,
+      text: record.text,
+      sentAt: record.sentAt,
+    });
+
+    return true;
+  };
+
+  // Reads the backlog from the store before sending anything, so a tap's
+  // ok response is always queued ahead of its first message. It sends one
+  // unclaimed message per call and the tap's ack calls it again, so the
+  // backlog never outgrows the connection's outbound queue.
+  const drainInbox = async (sessionID: SessionID) => {
+    const s = mgr.sessions.find((x) => x.id === sessionID);
+
+    if (s === undefined) {
+      return;
+    }
+
+    try {
+      const pending = await store.collectPendingMessages(buildMessageOwner(s));
+
+      for (const record of pending) {
+        if (sendInboxMessage(sessionID, record)) {
+          return;
+        }
+      }
+    } catch {}
+  };
+
+  const applyReport = async (e: HookEvent) => {
+    const report = parseReport(e.payload);
+
+    if (report === null) {
+      return;
+    }
+
+    const s = mgr.sessions.find((x) => x.id === e.atcId);
+    const owner = s === undefined ? { atcID: e.atcId } : buildMessageOwner(s);
+
+    try {
+      const answered = await store.updateMessageAnswered(
+        report.message,
+        owner,
+        truncateToBytes(report.answer, ANSWER_BYTE_CAP),
+        Date.now(),
+      );
+
+      if (answered !== null) {
+        emitEvent(buildSessionMessageEvent(e.atcId, answered), findHookScope(e.atcId));
+      }
+    } catch {}
+  };
 
   // The screen tier of the detector stack: once a session's output has
   // quiesced, judge the serialized screen and flip running/needs_you.
@@ -369,6 +462,8 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
     if (kind === 'removed') {
       attachments.removeSession(s.id);
+
+      emitInboxClosed(taps.removeSession(s.id), s.id, 'removed');
       runtimes.get(s.id)?.dispose();
       runtimes.delete(s.id);
     }
@@ -382,13 +477,33 @@ 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) => {
+    if (e.event === 'Report') {
+      void applyReport(e);
+
+      return;
+    }
+
+    const previousAgentSessionID = mgr.sessions.find((s) => s.id === e.atcId)?.agentSessionID;
+    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);
+    const currentAgentSessionID = mgr.sessions.find((s) => s.id === e.atcId)?.agentSessionID;
+
+    if (currentAgentSessionID !== undefined && currentAgentSessionID !== previousAgentSessionID) {
+      void store.updateMessageOwner(e.atcId, previousAgentSessionID, currentAgentSessionID);
+    }
 
     if (kind === 'ended') {
       runtime?.pendingEject?.();
@@ -397,6 +512,10 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     // A revived session announcing itself is the cue a staggered restore
     // waits on before booting the next one.
     if (kind === 'started') {
+      if (runtime !== undefined) {
+        runtime.startedAt = Date.now();
+      }
+
       runtime?.bootWaiter?.();
       const started = mgr.sessions.find((s) => s.id === e.atcId);
 
@@ -522,6 +641,8 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
       if (runtime !== undefined) {
         runtime.dims = { cols, rows };
+        runtime.startedAt = null;
+        runtime.tapAttached = false;
 
         runtime.screen ??= new ScreenModel(cols, rows);
       }
@@ -636,6 +757,193 @@ 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);
+      }
+    },
+    writeSessionMessage: async (sessionID, from, text) => {
+      const s = mgr.sessions.find((x) => x.id === sessionID);
+
+      if (s === undefined) {
+        return 'missing';
+      }
+
+      if (!(s.pty !== null || (s.kind === 'headless' && s.state !== 'exited'))) {
+        return 'dead';
+      }
+
+      if (mgr.findAdapter(s.agent)?.takesMessages !== true) {
+        return 'unsupported';
+      }
+
+      const runtime = runtimes.get(sessionID);
+
+      if (
+        runtime !== undefined &&
+        runtime.startedAt !== null &&
+        !runtime.tapAttached &&
+        Date.now() - runtime.startedAt >= (opts.tapGraceMs ?? TAP_GRACE_MS)
+      ) {
+        return 'no_tap';
+      }
+
+      const previousWrite = lastMessageWrite;
+      const written = Promise.withResolvers<void>();
+
+      lastMessageWrite = written.promise;
+
+      await previousWrite;
+
+      const record: MessageRecord = {
+        id: mintMessageID(),
+        atcID: sessionID,
+        ...(s.agentSessionID === undefined ? {} : { agentSessionID: s.agentSessionID }),
+        from,
+        text,
+        status: 'accepted',
+        sentAt: Date.now(),
+      };
+
+      try {
+        await store.writeMessage(record);
+      } finally {
+        written.resolve();
+      }
+
+      emitEvent(buildSessionMessageEvent(sessionID, record), findHookScope(sessionID));
+
+      await drainInbox(sessionID);
+
+      return record;
+    },
+    attachTap: (client, sessionID) => {
+      const s = mgr.sessions.find((x) => x.id === sessionID);
+
+      if (s === undefined) {
+        return 'missing';
+      }
+
+      if (mgr.findAdapter(s.agent)?.takesMessages !== true) {
+        return 'unsupported';
+      }
+
+      emitInboxClosed(taps.attach(sessionID, client), sessionID, 'replaced');
+
+      const runtime = runtimes.get(sessionID);
+
+      if (runtime !== undefined) {
+        runtime.tapAttached = true;
+      }
+
+      void drainInbox(sessionID);
+
+      return 'ok';
+    },
+    readMessage: async (messageID) => {
+      const record = await store.findMessageByID(messageID);
+
+      if (record === null) {
+        return null;
+      }
+
+      const owner = mgr.sessions.find(
+        (x) =>
+          x.id === record.atcID ||
+          (record.agentSessionID !== undefined && x.agentSessionID === record.agentSessionID),
+      );
+
+      return { session: owner?.id ?? record.atcID, record };
+    },
+    ackMessage: async (client, sessionID, messageID) => {
+      const s = mgr.sessions.find((x) => x.id === sessionID);
+
+      if (s === undefined || !taps.isTap(sessionID, client)) {
+        return 'not_tapping';
+      }
+
+      const owner = buildMessageOwner(s);
+
+      const delivered = await store.updateMessageDelivered(messageID, owner, Date.now());
+
+      void drainInbox(sessionID);
+
+      if (delivered !== null) {
+        emitEvent(buildSessionMessageEvent(sessionID, delivered), findHookScope(sessionID));
+
+        return delivered;
+      }
+
+      const current = await store.findMessage(messageID, owner);
+
+      return current ?? 'unknown';
+    },
   };
 
   try {
@@ -651,7 +959,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         clients.add(socket.data);
       },
       data(socket, buf) {
-        socket.data.applyChunk(buf.toString());
+        socket.data.applyChunk(socket.data.decodeChunk(buf));
       },
       drain(socket) {
         socket.data.drain();
@@ -659,6 +967,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       close(socket) {
         clients.delete(socket.data);
         ctx.detachClient(socket.data);
+        taps.detachAll(socket.data);
       },
       error() {},
     },
@@ -675,6 +984,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     }
 
     runtimes.clear();
+    eventSignal.dispose();
 
     await store.stop();
 
@@ -688,6 +998,23 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   return { stop: stopDaemon };
 }
 
+// Tells a tap its subscription is over so the `atc tap` process behind it
+// exits instead of idling on a session it no longer serves.
+function emitInboxClosed(
+  tap: TapClient | null,
+  sessionID: SessionID,
+  reason: 'replaced' | 'removed',
+): void {
+  tap?.sendEvent({ v: PROTOCOL_V, ev: 'InboxClosed', s: sessionID, reason });
+}
+
+function buildMessageOwner(s: Session): MessageOwner {
+  return {
+    atcID: s.id,
+    ...(s.agentSessionID === undefined ? {} : { agentSessionID: s.agentSessionID }),
+  };
+}
+
 function hasResumableTranscript(mgr: SessionManager, id: SessionID): boolean {
   const s = mgr.sessions.find((x) => x.id === id);
 

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

package/src/daemon/hooks.ts

@@ -10,19 +10,28 @@ export interface HookEvent {
   payload: Record<string, unknown>;
 }
 
+// Per-connection read state: the unterminated tail of the line in progress,
+// and a streaming decoder so a multi-byte character split across two reads
+// decodes whole.
+interface HookConnection {
+  pending: string;
+  readonly decoder: TextDecoder;
+}
+
 export function startHookServer(onEvent: (e: HookEvent) => void, path: string = socketPath) {
   try {
     unlinkSync(path);
   } catch {}
 
-  return Bun.listen<string>({
+  return Bun.listen<HookConnection>({
     unix: path,
     socket: {
       data(socket, buf) {
-        const buffered = (socket.data ?? '') + buf.toString();
+        const conn = socket.data;
+        const buffered = conn.pending + conn.decoder.decode(buf, { stream: true });
         const lines = buffered.split('\n');
 
-        socket.data = lines.pop() ?? '';
+        conn.pending = lines.pop() ?? '';
 
         for (const line of lines) {
           if (line.trim() === '') {
@@ -48,7 +57,7 @@ export function startHookServer(onEvent: (e: HookEvent) => void, path: string =
         }
       },
       open(socket) {
-        socket.data = '';
+        socket.data = { pending: '', decoder: new TextDecoder() };
       },
       error() {},
     },

package/src/daemon/load-transcript-page.ts

@@ -0,0 +1,101 @@
+import type { TranscriptRow } from '../agents/agent-adapter';
+
+export interface TranscriptPosition {
+  readonly path: string;
+  readonly offset: number;
+}
+
+export interface TranscriptPage {
+  readonly rows: TranscriptRow[];
+  readonly offset: number;
+  readonly more: boolean;
+}
+
+interface TranscriptPageRequest {
+  readonly path: string;
+  readonly from: TranscriptPosition | null;
+  readonly limit: number;
+  readonly maxBytes: number;
+  readonly parseLine: (line: string) => TranscriptRow | null;
+}
+
+export async function loadTranscriptPage(req: TranscriptPageRequest): Promise<TranscriptPage> {
+  const file = Bun.file(req.path);
+
+  if (!(await file.exists())) {
+    return {
+      rows: [],
+      offset: req.from?.path === req.path ? req.from.offset : 0,
+      more: false,
+    };
+  }
+
+  const size = file.size;
+
+  // One read window; a line longer than this is skipped unparsed.
+  const windowBytes = 1_048_576;
+
+  // A cursor from another file, or past the end of a replaced one, starts over.
+  let offset =
+    req.from !== null && req.from.path === req.path && req.from.offset <= size
+      ? req.from.offset
+      : 0;
+
+  const rows: TranscriptRow[] = [];
+
+  const decoder = new TextDecoder();
+
+  let bytes = 0;
+  let skipping = false;
+
+  while (offset < size) {
+    const chunk = await file.slice(offset, Math.min(offset + windowBytes, size)).bytes();
+
+    let lineStart = 0;
+    let newline = chunk.indexOf(0x0a, lineStart);
+
+    if (newline === -1) {
+      // A trailing partial line is left for the next read. A short read means the
+      // file shrank underneath us, so it ends the scan rather than skipping a line.
+      if (chunk.length < Math.min(windowBytes, size - offset) || offset + chunk.length >= size) {
+        break;
+      }
+
+      offset += chunk.length;
+      skipping = true;
+      continue;
+    }
+
+    while (newline !== -1) {
+      const row = skipping
+        ? null
+        : req.parseLine(decoder.decode(chunk.subarray(lineStart, newline)));
+
+      skipping = false;
+
+      if (row !== null) {
+        const rowBytes = Buffer.byteLength(JSON.stringify(row));
+
+        if (rows.length > 0 && bytes + rowBytes > req.maxBytes) {
+          return { rows, offset: offset + lineStart, more: true };
+        }
+
+        rows.push(row);
+
+        bytes += rowBytes;
+      }
+
+      lineStart = newline + 1;
+
+      if (rows.length >= req.limit) {
+        return { rows, offset: offset + lineStart, more: true };
+      }
+
+      newline = chunk.indexOf(0x0a, lineStart);
+    }
+
+    offset += lineStart;
+  }
+
+  return { rows, offset, more: false };
+}

package/src/daemon/mint-message-id.ts

@@ -0,0 +1,12 @@
+import { randomUUID } from 'node:crypto';
+import type { MessageID } from '../shared/message-id';
+
+/**
+ * A fresh atc message id: a random uuid behind an `m-` prefix. The id is a
+ * persisted primary key, so it is random rather than counted and stays
+ * unique across daemon restarts.
+ */
+export function mintMessageID(): MessageID {
+  // oxlint-disable-next-line no-unsafe-type-assertion -- this is where atc mints a message id
+  return `m-${randomUUID()}` as MessageID;
+}

package/src/daemon/parse-report.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import type { MessageID } from '../shared/message-id';
+import { REPORT_KINDS } from '../shared/report-kinds';
+import type { ReportKind } from '../shared/report-kinds';
+import { toMessageID } from '../shared/to-message-id';
+
+export interface Report {
+  readonly kind: ReportKind;
+  readonly message: MessageID;
+  readonly answer: string;
+}
+
+const REPORT_SCHEMA = z.object({
+  kind: z.enum(REPORT_KINDS),
+  message: z.string().min(1),
+  answer: z.string(),
+});
+
+/**
+ * Parses a Report envelope's payload into the report its kind discriminates,
+ * or null when it matches no known kind.
+ */
+export function parseReport(payload: Readonly<Record<string, unknown>>): Report | null {
+  const parsed = REPORT_SCHEMA.safeParse(payload);
+
+  if (!parsed.success) {
+    return null;
+  }
+
+  return {
+    kind: parsed.data.kind,
+    message: toMessageID(parsed.data.message),
+    answer: parsed.data.answer,
+  };
+}