@zgeoff/atc 2.6.0 → 2.8.0

package/src/daemon/daemon-connection.ts

@@ -13,8 +13,10 @@ import {
   encodeMessage,
 } from '../protocol/protocol';
 import type { ErrorCode, EventMsg, RequestMsg } from '../protocol/protocol';
+import type { MessageID } from '../shared/message-id';
 import type { SessionID } from '../shared/session-id';
 import type { FleetEntry } from '../store/fleet-entry';
+import type { MessageRecord } from '../store/message-record';
 import type { Dims } from './attach-registry';
 import type { FleetEvent } from './build-fleet-events';
 import type { TranscriptPage, TranscriptPosition } from './load-transcript-page';
@@ -100,6 +102,18 @@ export interface DaemonContext {
     limit: number,
     waitMs: number,
   ) => Promise<FleetEvent[]>;
+  readonly writeSessionMessage: (
+    sessionID: SessionID,
+    from: string,
+    text: string,
+  ) => Promise<MessageRecord | 'missing' | 'dead' | 'unsupported' | 'no_tap'>;
+  readonly readMessage: (messageID: MessageID) => Promise<MessageView | null>;
+  readonly attachTap: (client: TapClient, sessionID: SessionID) => 'ok' | 'missing' | 'unsupported';
+  readonly ackMessage: (
+    client: TapClient,
+    sessionID: SessionID,
+    messageID: MessageID,
+  ) => Promise<MessageRecord | 'not_tapping' | 'unknown'>;
 }
 
 // The slice of a connection the attach bookkeeping needs: identity plus the
@@ -108,6 +122,18 @@ export interface OutputClient {
   readonly sendOutput: (sessionID: SessionID, event: EventMsg, byteLength: number) => void;
 }
 
+// One message as `message.get` reports it: the session it belongs to now and
+// every field of the record.
+interface MessageView {
+  readonly session: SessionID;
+  readonly record: MessageRecord;
+}
+
+// The slice of a connection a tap subscription needs.
+export interface TapClient {
+  readonly sendEvent: (event: EventMsg) => void;
+}
+
 interface PeerSocket extends SocketWriter {
   readonly end: () => void;
 }
@@ -121,6 +147,8 @@ export class DaemonConnection {
 
   private buffer = '';
 
+  private readonly decoder = new TextDecoder();
+
   private helloed = false;
 
   // The handshake answer is written before any other response on this
@@ -137,6 +165,13 @@ export class DaemonConnection {
     this.queue = new OutboundQueue(peer, ctx.queueBytes);
   }
 
+  /**
+   * Ends the connection. Safe to call more than once.
+   */
+  dispose(): void {
+    this.peer.end();
+  }
+
   sendEvent(event: EventMsg): void {
     if (this.helloed && !this.queue.send(encodeMessage(event))) {
       this.peer.end();
@@ -165,6 +200,13 @@ export class DaemonConnection {
     }
   }
 
+  // Decodes with state kept across reads, so a multi-byte character split
+  // between two reads decodes whole.
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- a socket read buffer has no readonly form
+  decodeChunk(buf: Uint8Array): string {
+    return this.decoder.decode(buf, { stream: true });
+  }
+
   applyChunk(chunk: string): void {
     const buffered = this.buffer + chunk;
 
@@ -463,6 +505,26 @@ export class DaemonConnection {
 
         return;
       }
+      case 'session.message': {
+        await this.applySessionMessage(req);
+
+        return;
+      }
+      case 'session.tap': {
+        this.applyTap(req);
+
+        return;
+      }
+      case 'message.get': {
+        await this.applyMessageGet(req);
+
+        return;
+      }
+      case 'message.ack': {
+        await this.applyMessageAck(req);
+
+        return;
+      }
       case 'fleet.restore': {
         const parsed = parseRequestParams('fleet.restore', req.p);
 
@@ -775,6 +837,144 @@ export class DaemonConnection {
     });
   }
 
+  private async applySessionMessage(req: RequestMsg): Promise<void> {
+    const parsed = parseRequestParams('session.message', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const sessionID = parsed.data.session;
+
+    const result = await this.ctx.writeSessionMessage(
+      sessionID,
+      parsed.data.from,
+      parsed.data.text,
+    );
+
+    if (result === 'missing') {
+      this.sendErr(req.id, 'no_such_session', `no session '${sessionID}'`);
+
+      return;
+    }
+
+    if (result === 'dead') {
+      this.sendErr(req.id, 'session_dead', `session '${sessionID}' has no live process`);
+
+      return;
+    }
+
+    if (result === 'unsupported') {
+      this.sendErr(
+        req.id,
+        'unsupported',
+        `session '${sessionID}' cannot take messages: its agent has no message tap`,
+      );
+
+      return;
+    }
+
+    if (result === 'no_tap') {
+      this.sendErr(req.id, 'unsupported', `session '${sessionID}' never attached a message tap`);
+
+      return;
+    }
+
+    this.sendOk(req.id, { message: result.id, status: result.status });
+  }
+
+  private applyTap(req: RequestMsg): void {
+    const parsed = parseRequestParams('session.tap', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const sessionID = parsed.data.session;
+    const result = this.ctx.attachTap(this, sessionID);
+
+    if (result === 'missing') {
+      this.sendErr(req.id, 'no_such_session', `no session '${sessionID}'`);
+
+      return;
+    }
+
+    if (result === 'unsupported') {
+      this.sendErr(req.id, 'unsupported', `session '${sessionID}' cannot take messages`);
+
+      return;
+    }
+
+    this.sendOk(req.id, {});
+  }
+
+  private async applyMessageGet(req: RequestMsg): Promise<void> {
+    const parsed = parseRequestParams('message.get', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const messageID = parsed.data.message;
+
+    const view = await this.ctx.readMessage(messageID);
+
+    if (view === null) {
+      this.sendErr(req.id, 'bad_args', `no message '${messageID}'`);
+
+      return;
+    }
+
+    const record = view.record;
+
+    this.sendOk(req.id, {
+      message: record.id,
+      session: view.session,
+      from: record.from,
+      text: record.text,
+      status: record.status,
+      sentAt: record.sentAt,
+      ...(record.deliveredAt === undefined ? {} : { deliveredAt: record.deliveredAt }),
+      ...(record.answeredAt === undefined ? {} : { answeredAt: record.answeredAt }),
+      ...(record.answer === undefined ? {} : { answer: record.answer }),
+    });
+  }
+
+  private async applyMessageAck(req: RequestMsg): Promise<void> {
+    const parsed = parseRequestParams('message.ack', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const sessionID = parsed.data.session;
+    const messageID = parsed.data.message;
+
+    const result = await this.ctx.ackMessage(this, sessionID, messageID);
+
+    if (result === 'not_tapping') {
+      this.sendErr(req.id, 'bad_args', `this connection is not tapping session '${sessionID}'`);
+
+      return;
+    }
+
+    if (result === 'unknown') {
+      this.sendErr(req.id, 'bad_args', `no message '${messageID}' for session '${sessionID}'`);
+
+      return;
+    }
+
+    this.sendOk(req.id, { message: result.id, status: result.status });
+  }
+
   private async applySessionVerb(
     req: RequestMsg,
     method: 'session.kill' | 'session.ack',

package/src/daemon/daemon.ts

@@ -4,27 +4,36 @@ 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 { buildSessionReportEvent } from './build-session-report-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;
@@ -71,6 +80,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.
@@ -81,6 +91,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
@@ -164,6 +178,93 @@ 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;
+    }
+
+    if (report.kind === 'note') {
+      const sender = mgr.sessions.find((x) => x.id === e.atcId);
+
+      if (sender !== undefined) {
+        const capped = { ...report, text: truncateToBytes(report.text, ANSWER_BYTE_CAP) };
+
+        emitEvent(buildSessionReportEvent(sender.id, capped, Date.now()), findHookScope(sender.id));
+      }
+
+      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.
@@ -374,6 +475,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);
     }
@@ -394,6 +497,13 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   };
 
   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') {
@@ -402,6 +512,11 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
     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?.();
@@ -410,6 +525,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);
 
@@ -535,6 +654,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);
       }
@@ -720,6 +841,122 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         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 {
@@ -735,7 +972,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();
@@ -743,12 +980,19 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       close(socket) {
         clients.delete(socket.data);
         ctx.detachClient(socket.data);
+        taps.detachAll(socket.data);
       },
       error() {},
     },
   });
 
   stopDaemon = async () => {
+    // Ends each client itself so every peer sees the close: a stopped
+    // listener does not reliably end the connections it already accepted.
+    for (const client of clients) {
+      client.dispose();
+    }
+
     server.stop(true);
     eventsServer?.stop();
     reporter.stop(true);
@@ -773,6 +1017,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/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/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;
+}