@zgeoff/atc 2.5.1 → 2.7.0

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/sessions.ts

@@ -7,6 +7,7 @@ import { collectCleanEnv } from '../shared/collect-clean-env';
 import { socketPath, statusFile } from '../shared/config';
 import { resolveRepoRoot } from '../shared/resolve-repo-root';
 import type { SessionID } from '../shared/session-id';
+import { truncateToBytes } from '../shared/truncate-to-bytes';
 import type { FleetEntry, FleetStore } from '../store/fleet-entry';
 import type { HookEvent } from './hooks';
 import { mintSessionID } from './mint-session-id';
@@ -75,6 +76,16 @@ export interface Session {
   // The session that spawned this one as a sub-session; null for a
   // top-level session. One level deep: a sub-session never owns another.
   parent: SessionID | null;
+
+  // the prompt the session was spawned with
+  prompt?: string;
+
+  // the agent's final message from its latest finished turn, capped in size
+  result?: string;
+
+  // the transcript file the agent's hooks last reported. Kept apart from the
+  // resume check so a restored path never changes whether a revive is allowed.
+  transcriptPath?: string;
 }
 
 export class SessionManager {
@@ -180,6 +191,9 @@ export class SessionManager {
       namedBy: 'auto',
       createdAt: Date.now(),
       parent: this.findByAgentSessionID(entry.parent)?.id ?? null,
+      ...(entry.prompt === undefined ? {} : { prompt: entry.prompt }),
+      ...(entry.result === undefined ? {} : { result: entry.result }),
+      ...(entry.transcriptPath === undefined ? {} : { transcriptPath: entry.transcriptPath }),
     };
 
     this.sessions.push(session);
@@ -385,6 +399,7 @@ export class SessionManager {
       namedBy,
       createdAt: Date.now(),
       parent,
+      ...(prompt === '' ? {} : { prompt }),
     };
 
     pty.onData((d) => {
@@ -442,9 +457,9 @@ export class SessionManager {
     return this.sessions.filter((s) => s.parent === id);
   }
 
-  // Returns the normalized event kind so the caller can key lifecycle
-  // bookkeeping on it, or null when no session or adapter matches.
-  applyHook(e: HookEvent): AdapterEvent['kind'] | null {
+  // Returns the normalized event so the caller can key lifecycle bookkeeping
+  // and the event trail on it, or null when no session or adapter matches.
+  applyHook(e: HookEvent): AdapterEvent | null {
     const s = this.sessions.find((x) => x.id === e.atcId);
 
     if (!s) {
@@ -462,15 +477,26 @@ export class SessionManager {
     // Reporters belong to the terminal process; once a session is headless,
     // late reports from the dying terminal must not clobber its state.
     if (s.kind === 'headless') {
-      return ev.kind;
+      return ev;
     }
 
     const focused = this.focusedId === s.id;
     let dirty = false;
+    let persist = false;
+    const rowUpdate: { result?: string; transcriptPath?: string } = {};
+
+    if (ev.transcriptSource !== undefined) {
+      s.transcriptSource = ev.transcriptSource;
+
+      if (s.transcriptPath !== ev.transcriptSource) {
+        s.transcriptPath = ev.transcriptSource;
+        rowUpdate.transcriptPath = ev.transcriptSource;
+      }
+    }
 
     if (ev.agentSessionID !== undefined && s.agentSessionID !== ev.agentSessionID) {
       s.agentSessionID = ev.agentSessionID;
-      void this.writeFleet();
+      persist = true;
       dirty = true;
     }
 
@@ -478,10 +504,6 @@ export class SessionManager {
       s.lastDetail = ev.detail;
     }
 
-    if (ev.transcriptSource !== undefined) {
-      s.transcriptSource = ev.transcriptSource;
-    }
-
     if (ev.nameSource !== undefined) {
       void this.refreshName(s, ev.nameSource);
     }
@@ -507,6 +529,13 @@ export class SessionManager {
         s.unread = !focused;
         s.lastMsg = 'turn done';
         dirty = true;
+
+        if (ev.result !== undefined) {
+          // A runaway final message cannot bloat the fleet row.
+          s.result = truncateToBytes(ev.result, 16_384);
+          rowUpdate.result = s.result;
+        }
+
         break;
       }
       case 'prompt-submitted': {
@@ -537,12 +566,21 @@ export class SessionManager {
       }
     }
 
+    // A fleet rewrite marks every session without a PTY as exited, so only a
+    // new agent session id (which adds or re-keys a row) takes it. Anything
+    // else touches this session's own row.
+    if (persist) {
+      void this.writeFleet();
+    } else if (s.agentSessionID !== undefined) {
+      void this.store.updateFleetEntry(s.agentSessionID, rowUpdate);
+    }
+
     if (dirty) {
       this.onEvent('state', s);
       this.emitChange();
     }
 
-    return ev.kind;
+    return ev;
   }
 
   private async refreshName(s: Session, source: string) {
@@ -731,6 +769,9 @@ export class SessionManager {
         lastAttachedAt: s.lastAttachedAt,
         ...(live ? {} : { exited: true }),
         ...(parent === undefined ? {} : { parent }),
+        ...(s.prompt === undefined ? {} : { prompt: s.prompt }),
+        ...(s.result === undefined ? {} : { result: s.result }),
+        ...(s.transcriptPath === undefined ? {} : { transcriptPath: s.transcriptPath }),
       });
     }
 

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

@@ -53,6 +53,53 @@ const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   { io: 'input' },
 );
 
+const SESSION_READ_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
+  SESSION_ID_BASE.extend({
+    cursor: z
+      .string()
+      .optional()
+      .describe(
+        'The cursor a previous atc_session_read returned; omit to read from the start of the conversation',
+      ),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(200)
+      .optional()
+      .describe('Most rows to return; defaults to 50'),
+  }).strict(),
+  { io: 'input' },
+);
+
+const EVENTS_READ_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
+  z.strictObject({
+    cursor: z
+      .string()
+      .optional()
+      .describe(
+        'The cursor a previous atc_events_read returned; omit to get the most recent events',
+      ),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(200)
+      .optional()
+      .describe('Most events to return; defaults to 50'),
+    waitMs: z
+      .number()
+      .int()
+      .min(0)
+      .max(30_000)
+      .optional()
+      .describe(
+        'How long to wait for a new event when none is pending, in milliseconds; defaults to 0, capped at 30000. Keep it short.',
+      ),
+  }),
+  { io: 'input' },
+);
+
 const TOOLS: readonly MCPTool[] = [
   {
     name: 'atc_session_list',
@@ -122,6 +169,56 @@ const TOOLS: readonly MCPTool[] = [
     description: 'List directories sessions were previously spawned from, most recent first.',
     inputSchema: NO_INPUT,
   },
+  {
+    name: 'atc_session_get',
+    description:
+      'Read one session in a single call: its descriptor (state, unread flag, last activity message), the prompt it was spawned with, when it last reported activity, the prompt or question it is waiting on while it needs you (read-only; answer it with atc_session_input), and the final message of its latest finished turn.',
+    inputSchema: SESSION_INPUT,
+  },
+  {
+    name: 'atc_session_read',
+    description:
+      "Read a session's conversation a page at a time, oldest first: user and assistant messages with tool uses summarised. Pass the returned cursor to continue where you left off; more is true when the page stopped before the end. Claude sessions only; other agents answer unsupported.",
+    inputSchema: SESSION_READ_INPUT,
+  },
+  {
+    name: 'atc_events_read',
+    description:
+      '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,
+    },
+  },
 ];
 
 /**
@@ -138,6 +235,10 @@ export async function runMCPServer(build: string): Promise<void> {
 
   let buffer = '';
 
+  // Each request runs on its own, so a long poll never holds up the others;
+  // responses carry their request's id.
+  const inFlight = new Set<Promise<void>>();
+
   for await (const chunk of Bun.stdin.stream()) {
     buffer += decoder.decode(chunk, { stream: true });
 
@@ -150,10 +251,25 @@ export async function runMCPServer(build: string): Promise<void> {
         continue;
       }
 
-      await applyRPCLine(client, build, line);
+      const finished = Promise.withResolvers<void>();
+
+      inFlight.add(finished.promise);
+
+      void (async () => {
+        try {
+          await applyRPCLine(client, build, line);
+        } catch {
+          // A failed line gets no response, the way a malformed one gets none.
+        } finally {
+          inFlight.delete(finished.promise);
+          finished.resolve();
+        }
+      })();
     }
   }
 
+  await Promise.all(inFlight);
+
   client.stop();
 }
 
@@ -317,6 +433,53 @@ async function runTool(
 
       return JSON.stringify(ok['dirs'], null, 2);
     }
+    case 'atc_session_get': {
+      const ok = await client.sendRequest('session.get', { session: args['session'] });
+
+      return JSON.stringify(ok, null, 2);
+    }
+    case 'atc_session_read': {
+      const ok = await client.sendRequest('session.read', {
+        session: args['session'],
+        ...(typeof args['cursor'] === 'string' ? { cursor: args['cursor'] } : {}),
+        ...(typeof args['limit'] === 'number' ? { limit: args['limit'] } : {}),
+      });
+
+      return JSON.stringify(ok, null, 2);
+    }
+    case 'atc_events_read': {
+      const ok = await client.sendRequest('events.read', {
+        ...(typeof args['cursor'] === 'string' ? { cursor: args['cursor'] } : {}),
+        ...(typeof args['limit'] === 'number' ? { limit: args['limit'] } : {}),
+        ...(typeof args['waitMs'] === 'number' ? { waitMs: args['waitMs'] } : {}),
+      });
+
+      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/decode-cursor.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import type { Cursor } from './encode-cursor';
+
+const WIRE_CURSOR = z.discriminatedUnion('k', [
+  z.object({ k: z.literal('ev'), i: z.number().int().nonnegative() }),
+  z.object({ k: z.literal('tr'), p: z.string(), o: z.number().int().nonnegative() }),
+]);
+
+export function decodeCursor(raw: string): Cursor | null {
+  let json: unknown;
+
+  try {
+    json = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'));
+  } catch {
+    return null;
+  }
+
+  const parsed = WIRE_CURSOR.safeParse(json);
+
+  if (!parsed.success) {
+    return null;
+  }
+
+  if (parsed.data.k === 'ev') {
+    return { kind: 'events', id: parsed.data.i };
+  }
+
+  return { kind: 'transcript', path: parsed.data.p, offset: parsed.data.o };
+}

package/src/protocol/encode-cursor.ts

@@ -0,0 +1,12 @@
+export type Cursor =
+  | { readonly kind: 'events'; readonly id: number }
+  | { readonly kind: 'transcript'; readonly path: string; readonly offset: number };
+
+export function encodeCursor(cursor: Cursor): string {
+  const wire =
+    cursor.kind === 'events'
+      ? { k: 'ev', i: cursor.id }
+      : { k: 'tr', p: cursor.path, o: cursor.offset };
+
+  return Buffer.from(JSON.stringify(wire), 'utf8').toString('base64url');
+}

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 =
@@ -87,6 +88,27 @@ export const REQUEST_PARAM_SCHEMAS = {
     .refine((v) => v.request !== '' && v.decision !== '', {
       message: 'permission.respond requires a request and a decision',
     }),
+  'session.get': SESSION_DEFAULTED,
+  'session.read': SESSION_DEFAULTED.extend({
+    cursor: buildOptionalCursor(),
+    limit: buildDefaultedNumber(50).transform((v) => Math.min(Math.max(Math.trunc(v), 1), 200)),
+  }),
+  'events.read': z.object({
+    cursor: buildOptionalCursor(),
+    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) {
@@ -115,3 +137,11 @@ function buildDefaultedNonEmptyString(fallback: string) {
     z.string().default(fallback),
   );
 }
+
+// An empty cursor reads as no cursor, the way a client starting fresh sends it.
+function buildOptionalCursor() {
+  return z.preprocess(
+    (v) => (typeof v === 'string' && v !== '' ? v : undefined),
+    z.string().optional(),
+  );
+}

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];

package/src/shared/report.ts

@@ -4,12 +4,28 @@
 async function sendLine(sock: string, line: string): Promise<void> {
   const resolvers = Promise.withResolvers<void>();
 
+  const bytes = new TextEncoder().encode(line);
+
+  let written = 0;
+
   await Bun.connect({
     unix: sock,
     socket: {
+      // A write returns the bytes the socket accepted and drops the rest, so
+      // a line larger than the socket buffer goes out across drain calls.
       open(s) {
-        s.write(line);
-        s.end();
+        written += s.write(bytes.subarray(written));
+
+        if (written >= bytes.length) {
+          s.end();
+        }
+      },
+      drain(s) {
+        written += s.write(bytes.subarray(written));
+
+        if (written >= bytes.length) {
+          s.end();
+        }
       },
       close() {
         resolvers.resolve();

package/src/shared/to-message-id.ts

@@ -0,0 +1,11 @@
+import type { MessageID } from './message-id';
+
+/**
+ * Trusts a string as an atc message id. This is the one point in the
+ * codebase where a plain string becomes a `MessageID`, and it adds no
+ * runtime check: the caller asserts the string identifies an atc message.
+ */
+export function toMessageID(id: string): MessageID {
+  // oxlint-disable-next-line no-unsafe-type-assertion -- the one point where a string is trusted as a MessageID
+  return id as MessageID;
+}

package/src/shared/truncate-to-bytes.ts

@@ -0,0 +1,21 @@
+export function truncateToBytes(text: string, maxBytes: number): string {
+  if (Buffer.byteLength(text, 'utf8') <= maxBytes) {
+    return text;
+  }
+
+  const bytes = Buffer.from(text, 'utf8');
+
+  // The cut leaves room for the three-byte ellipsis, or drops the ellipsis
+  // when the cap is smaller than it, and backs up off any continuation byte
+  // so it never lands inside a code point.
+  const hasRoomForEllipsis = maxBytes >= 3;
+  let end = hasRoomForEllipsis ? maxBytes - 3 : Math.max(maxBytes, 0);
+
+  while (end > 0 && ((bytes[end] ?? 0) & 0xc0) === 0x80) {
+    end -= 1;
+  }
+
+  const head = bytes.subarray(0, end).toString('utf8');
+
+  return hasRoomForEllipsis ? `${head}…` : head;
+}

package/src/store/fleet-entry.ts

@@ -18,11 +18,31 @@ export interface FleetEntry {
 
   // The agent session id of the session this one is a sub-session of.
   readonly parent?: AgentSessionID;
+
+  // The prompt the session was spawned with.
+  readonly prompt?: string;
+
+  // The agent's final message from the session's latest finished turn.
+  readonly result?: string;
+
+  // The transcript file the agent's hooks last reported for the session.
+  readonly transcriptPath?: string;
 }
 
 export interface FleetStore {
   readonly loadFleet: () => Promise<FleetEntry[]>;
   readonly writeFleet: (entries: readonly FleetEntry[]) => Promise<void>;
+  readonly updateFleetEntry: (
+    agentSessionID: AgentSessionID,
+    fields: FleetEntryUpdate,
+  ) => Promise<void>;
+}
+
+// The fields a session rewrites on its own row while it runs, without
+// touching any sibling row.
+export interface FleetEntryUpdate {
+  readonly result?: string;
+  readonly transcriptPath?: string;
 }
 
 // A stored fleet row's keys. name, cwd, and the resolved agentSessionID are

package/src/store/message-owner.ts

@@ -0,0 +1,9 @@
+import type { AgentSessionID } from '../shared/agent-session-id';
+import type { SessionID } from '../shared/session-id';
+
+// Which session a message belongs to: the atc id it was sent to, or the
+// agent session id that survives a restore's re-minted atc id.
+export interface MessageOwner {
+  readonly atcID: SessionID;
+  readonly agentSessionID?: AgentSessionID;
+}