@zgeoff/atc 2.6.0 → 2.7.0

package/src/daemon/daemon.ts

@@ -4,27 +4,35 @@ 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;
@@ -71,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.
@@ -81,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
@@ -164,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.
@@ -374,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);
     }
@@ -394,6 +484,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 +499,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 +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);
 
@@ -535,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);
       }
@@ -720,6 +828,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 +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();
@@ -743,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() {},
     },
@@ -773,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/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;
+}

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,
+  };
+}

package/src/daemon/session-runtime.ts

@@ -37,6 +37,15 @@ export class SessionRuntime {
   // clears it, and a spawn that never reports leaves it stranded harmlessly.
   pendingLastUsed = false;
 
+  // When the agent reported SessionStart since its terminal last booted, or
+  // null before it has. A message queues for a grace window after that, and
+  // beyond it only if a tap has attached since the boot.
+  startedAt: number | null = null;
+
+  // Whether a tap has attached since the terminal last booted. A tap that
+  // later dropped may be restarting, so it keeps the inbox open.
+  tapAttached = false;
+
   dispose(): void {
     clearTimeout(this.resizeTimer);
     clearTimeout(this.detectTimer);

package/src/daemon/tap-registry.ts

@@ -0,0 +1,67 @@
+import type { MessageID } from '../shared/message-id';
+import type { SessionID } from '../shared/session-id';
+
+interface TapEntry<TClient> {
+  readonly client: TClient;
+  readonly claimed: Set<MessageID>;
+}
+
+/**
+ * Which connection taps each session's inbox; one tap per session, the
+ * latest wins; each message is handed to a tap once.
+ */
+export class TapRegistry<TClient> {
+  private readonly bySession = new Map<SessionID, TapEntry<TClient>>();
+
+  /**
+   * Makes the client the session's tap and returns the client it displaced,
+   * or null when there was none or it is the same connection.
+   */
+  attach(sessionID: SessionID, client: TClient): TClient | null {
+    const previous = this.bySession.get(sessionID)?.client ?? null;
+
+    this.bySession.set(sessionID, { client, claimed: new Set() });
+
+    return previous === client ? null : previous;
+  }
+
+  detachAll(client: TClient): void {
+    for (const [sessionID, entry] of this.bySession) {
+      if (entry.client === client) {
+        this.bySession.delete(sessionID);
+      }
+    }
+  }
+
+  /**
+   * Forgets the session's tap and returns its client, or null when the
+   * session had none.
+   */
+  removeSession(sessionID: SessionID): TClient | null {
+    const previous = this.bySession.get(sessionID)?.client ?? null;
+
+    this.bySession.delete(sessionID);
+
+    return previous;
+  }
+
+  hasTap(sessionID: SessionID): boolean {
+    return this.bySession.has(sessionID);
+  }
+
+  isTap(sessionID: SessionID, client: TClient): boolean {
+    return this.bySession.get(sessionID)?.client === client;
+  }
+
+  claimDelivery(sessionID: SessionID, messageID: MessageID): TClient | null {
+    const entry = this.bySession.get(sessionID);
+
+    if (entry === undefined || entry.claimed.has(messageID)) {
+      return null;
+    }
+
+    entry.claimed.add(messageID);
+
+    return entry.client;
+  }
+}

package/src/mcp-server.ts

@@ -187,6 +187,38 @@ const TOOLS: readonly MCPTool[] = [
       'Catch up on the fleet: session events (started, prompt-submitted, needs-input, turn-done, ended) since a cursor, oldest first, each with the session id and name. Without a cursor it returns the most recent events. Pass the returned cursor next time. waitMs holds the call open until an event arrives.',
     inputSchema: EVENTS_READ_INPUT,
   },
+  {
+    name: 'atc_session_message',
+    description:
+      "Send a session a message and get its id back; poll atc_message_get with the id for its status and answer. The message waits in the session inbox until the session takes it, and its status moves accepted, delivered, answered. A message is refused as unsupported when the session's agent has no message tap (Grok, Codex), or when a Claude session reported SessionStart more than 15 seconds ago and no tap has attached since. It is refused as session_dead when the session has no live process and as no_such_session for an unknown id. Otherwise it queues, including while a session restores or after its tap dropped. The message is never typed into the terminal.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session: { type: 'string', description: 'The atc session id, from atc_session_list' },
+        text: { type: 'string', description: 'The message text' },
+        from: {
+          type: 'string',
+          description:
+            'Who the message is from; defaults to the calling session id, or mcp outside a session',
+        },
+      },
+      required: ['session', 'text'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'atc_message_get',
+    description:
+      'Read one message sent with atc_session_message: its id, session, from, text, status (accepted, delivered, or answered), the answer once answered, and the sentAt, deliveredAt, and answeredAt timestamps. Poll it until the status is answered.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message: { type: 'string', description: 'The message id atc_session_message returned' },
+      },
+      required: ['message'],
+      additionalProperties: false,
+    },
+  },
 ];
 
 /**
@@ -424,6 +456,30 @@ async function runTool(
 
       return JSON.stringify(ok, null, 2);
     }
+    case 'atc_session_message': {
+      const caller = process.env['ATC_SESSION_ID'];
+      const given = args['from'];
+      let from = 'mcp';
+
+      if (typeof given === 'string' && given !== '') {
+        from = given;
+      } else if (caller !== undefined && caller !== '') {
+        from = caller;
+      }
+
+      const ok = await client.sendRequest('session.message', {
+        session: args['session'],
+        text: args['text'],
+        from,
+      });
+
+      return JSON.stringify(ok, null, 2);
+    }
+    case 'atc_message_get': {
+      const ok = await client.sendRequest('message.get', { message: args['message'] });
+
+      return JSON.stringify(ok, null, 2);
+    }
     default: {
       throw new Error(`unknown tool '${name}'`);
     }

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

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { buildOptionalBoolean } from '../shared/build-optional-boolean';
 import { buildOptionalString } from '../shared/build-optional-string';
 import { toAgentSessionID } from '../shared/to-agent-session-id';
+import { toMessageID } from '../shared/to-message-id';
 import { toSessionID } from '../shared/to-session-id';
 
 const EJECT_DEFAULT_PROMPT =
@@ -97,6 +98,17 @@ export const REQUEST_PARAM_SCHEMAS = {
     limit: buildDefaultedNumber(50).transform((v) => Math.min(Math.max(Math.trunc(v), 1), 200)),
     waitMs: buildDefaultedNumber(0).transform((v) => Math.min(Math.max(Math.trunc(v), 0), 30_000)),
   }),
+  'session.message': SESSION_DEFAULTED.extend({
+    from: buildDefaultedNonEmptyString('unknown'),
+    text: buildDefaultedString(''),
+  }).refine((v) => v.text !== '', { message: 'session.message requires text' }),
+  'session.tap': SESSION_DEFAULTED,
+  'message.get': z
+    .object({ message: buildDefaultedString('').transform(toMessageID) })
+    .refine((v) => v.message !== '', { message: 'message.get requires a message' }),
+  'message.ack': SESSION_DEFAULTED.extend({
+    message: buildDefaultedString('').transform(toMessageID),
+  }).refine((v) => v.message !== '', { message: 'message.ack requires a message' }),
 } as const;
 
 function buildDefaultedString(fallback: string) {

package/src/report.ts

@@ -0,0 +1,32 @@
+import { sendReport } from './shared/report';
+import { REPORT_KINDS } from './shared/report-kinds';
+
+/**
+ * Runs inside wrangled sessions: reads the final text from stdin verbatim
+ * and forwards it to the atc socket as a Report envelope of the given kind
+ * for the given message. Always exits 0 so it never blocks the session it
+ * reports on.
+ */
+export async function runReport(kind: string, message: string): Promise<void> {
+  try {
+    const sock = process.env['ATC_SOCKET'];
+    const atcId = process.env['ATC_SESSION_ID'];
+
+    if (
+      sock !== undefined &&
+      sock !== '' &&
+      atcId !== undefined &&
+      atcId !== '' &&
+      REPORT_KINDS.some((known) => known === kind) &&
+      message !== ''
+    ) {
+      const answer = await new Response(Bun.stdin.stream()).text();
+
+      const line = `${JSON.stringify({ atcId, event: 'Report', payload: { kind, message, answer } })}\n`;
+
+      await sendReport(sock, line, 2000);
+    }
+  } catch {}
+
+  process.exit(0);
+}

package/src/shared/message-id.ts

@@ -0,0 +1,7 @@
+import type { Tagged } from 'type-fest';
+
+/**
+ * An atc-minted message id; keys the messages table and every message
+ * request and event.
+ */
+export type MessageID = Tagged<string, 'MessageID'>;

package/src/shared/report-kinds.ts

@@ -0,0 +1,3 @@
+export const REPORT_KINDS = ['answered'] as const;
+
+export type ReportKind = (typeof REPORT_KINDS)[number];