@zgeoff/atc 2.5.1 → 2.6.0

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/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/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,24 @@ 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,
+  },
 ];
 
 /**
@@ -138,6 +203,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 +219,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 +401,29 @@ 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);
+    }
     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

@@ -87,6 +87,16 @@ 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)),
+  }),
 } as const;
 
 function buildDefaultedString(fallback: string) {
@@ -115,3 +125,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/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/run-migrations.ts

@@ -12,6 +12,9 @@ interface FleetTable {
   agent: string;
   exited: number;
   parent: string | null;
+  prompt: string | null;
+  result: string | null;
+  transcript_path: string | null;
 }
 
 interface EventsTable {
@@ -21,6 +24,8 @@ interface EventsTable {
   event: string;
   message: string | null;
   session_id: string | null;
+  kind: string | null;
+  detail: string | null;
 }
 
 interface SpawnHistoryTable {
@@ -46,9 +51,9 @@ export interface StateStoreSchema {
 
 // Every shape the fleet table has shipped with: the oldest carries only
 // agent_session_id under its Claude-era name plus name and cwd, and each
-// later step adds one column the daemon grew to depend on. events,
-// spawn_history, and prefs have carried one shape since they were added, so
-// they need only their initial creation.
+// later step adds one column the daemon grew to depend on. events later gains
+// columns of its own, while spawn_history and prefs have carried one shape
+// since they were added.
 const MIGRATIONS: Record<string, Migration> = {
   '001_create_initial_schema': {
     async up(db: Kysely<StateStoreSchema>) {
@@ -125,6 +130,42 @@ const MIGRATIONS: Record<string, Migration> = {
       await db.schema.alterTable('fleet').addColumn('parent', 'text').execute();
     },
   },
+  '008_add_fleet_prompt_result_transcript': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema.alterTable('fleet').addColumn('prompt', 'text').execute();
+      await db.schema.alterTable('fleet').addColumn('result', 'text').execute();
+      await db.schema.alterTable('fleet').addColumn('transcript_path', 'text').execute();
+    },
+  },
+  '009_add_events_kind_detail': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema.alterTable('events').addColumn('kind', 'text').execute();
+      await db.schema.alterTable('events').addColumn('detail', 'text').execute();
+    },
+  },
+  '010_add_events_trail_indexes': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema
+        .createIndex('events_atc_id_ts')
+        .ifNotExists()
+        .on('events')
+        .columns(['atc_id', 'ts'])
+        .execute();
+
+      await db.schema
+        .createIndex('events_session_id_ts')
+        .ifNotExists()
+        .on('events')
+        .columns(['session_id', 'ts'])
+        .execute();
+
+      // Partial, so the trail reads walk only the rows they return. The
+      // predicate text must match the reads' filter for SQLite to pick it.
+      await sql`CREATE INDEX IF NOT EXISTS events_trail ON events (id) WHERE kind IS NOT NULL AND kind != 'heartbeat'`.execute(
+        db,
+      );
+    },
+  },
 };
 
 const PROVIDER: MigrationProvider = {