@zgeoff/atc 2.5.1 → 2.7.0

package/src/store/message-record.ts

@@ -0,0 +1,18 @@
+import type { AgentSessionID } from '../shared/agent-session-id';
+import type { MessageID } from '../shared/message-id';
+import type { SessionID } from '../shared/session-id';
+
+export type MessageStatus = 'accepted' | 'delivered' | 'answered';
+
+export interface MessageRecord {
+  readonly id: MessageID;
+  readonly atcID: SessionID;
+  readonly agentSessionID?: AgentSessionID;
+  readonly from: string;
+  readonly text: string;
+  readonly status: MessageStatus;
+  readonly sentAt: number;
+  readonly deliveredAt?: number;
+  readonly answeredAt?: number;
+  readonly answer?: string;
+}

package/src/store/run-migrations.ts

@@ -2,6 +2,7 @@ import { sql } from 'kysely';
 import type { Generated, Kysely } from 'kysely';
 import { DEFAULT_MIGRATION_TABLE, Migrator } from 'kysely/migration';
 import type { Migration, MigrationProvider, MigrationResultSet } from 'kysely/migration';
+import type { MessageStatus } from './message-record';
 
 interface FleetTable {
   agent_session_id: string;
@@ -12,6 +13,9 @@ interface FleetTable {
   agent: string;
   exited: number;
   parent: string | null;
+  prompt: string | null;
+  result: string | null;
+  transcript_path: string | null;
 }
 
 interface EventsTable {
@@ -21,6 +25,8 @@ interface EventsTable {
   event: string;
   message: string | null;
   session_id: string | null;
+  kind: string | null;
+  detail: string | null;
 }
 
 interface SpawnHistoryTable {
@@ -33,6 +39,19 @@ interface PrefsTable {
   value: string;
 }
 
+interface MessagesTable {
+  id: string;
+  atc_id: string;
+  agent_session_id: string | null;
+  sender: string;
+  text: string;
+  status: MessageStatus;
+  sent_at: number;
+  delivered_at: number | null;
+  answered_at: number | null;
+  answer: string | null;
+}
+
 /**
  * The state store's schema: what the query builder and the migration
  * ladder both build against.
@@ -42,13 +61,14 @@ export interface StateStoreSchema {
   events: EventsTable;
   spawn_history: SpawnHistoryTable;
   prefs: PrefsTable;
+  messages: MessagesTable;
 }
 
 // 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, prefs, and messages have carried one
+// shape since they were added.
 const MIGRATIONS: Record<string, Migration> = {
   '001_create_initial_schema': {
     async up(db: Kysely<StateStoreSchema>) {
@@ -125,6 +145,77 @@ 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,
+      );
+    },
+  },
+  '011_create_messages': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema
+        .createTable('messages')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('atc_id', 'text', (c) => c.notNull())
+        .addColumn('agent_session_id', 'text')
+        .addColumn('sender', 'text', (c) => c.notNull())
+        .addColumn('text', 'text', (c) => c.notNull())
+        .addColumn('status', 'text', (c) => c.notNull())
+        .addColumn('sent_at', 'integer', (c) => c.notNull())
+        .addColumn('delivered_at', 'integer')
+        .addColumn('answered_at', 'integer')
+        .addColumn('answer', 'text')
+        .execute();
+    },
+  },
+  '012_index_messages_by_owner': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema
+        .createIndex('messages_atc_id_status_sent_at')
+        .ifNotExists()
+        .on('messages')
+        .columns(['atc_id', 'status', 'sent_at'])
+        .execute();
+
+      await db.schema
+        .createIndex('messages_agent_session_id_status_sent_at')
+        .ifNotExists()
+        .on('messages')
+        .columns(['agent_session_id', 'status', 'sent_at'])
+        .execute();
+    },
+  },
 };
 
 const PROVIDER: MigrationProvider = {

package/src/store/state-store.ts

@@ -1,20 +1,44 @@
 import { Database } from 'bun:sqlite';
 import { existsSync, readFileSync } from 'node:fs';
 import { Kysely, SqliteAdapter, SqliteIntrospector, SqliteQueryCompiler, sql } from 'kysely';
+import type { Expression, ExpressionBuilder, SqlBool } from 'kysely';
 import { toAgentID } from '../agents/agent-adapter';
-import type { AgentID } from '../agents/agent-adapter';
+import type { AdapterEvent, AgentID } from '../agents/agent-adapter';
 import type { HookEvent } from '../daemon/hooks';
 import type { AgentSessionID } from '../shared/agent-session-id';
+import type { MessageID } from '../shared/message-id';
+import type { SessionID } from '../shared/session-id';
 import { toAgentSessionID } from '../shared/to-agent-session-id';
+import { toMessageID } from '../shared/to-message-id';
+import { toSessionID } from '../shared/to-session-id';
 import { BunSqliteDriver } from './bun-sqlite-driver';
 import { parseFleetEntry } from './fleet-entry';
-import type { FleetEntry } from './fleet-entry';
+import type { FleetEntry, FleetEntryUpdate } from './fleet-entry';
+import type { MessageOwner } from './message-owner';
+import type { MessageRecord } from './message-record';
 import { runMigrations } from './run-migrations';
 import type { StateStoreSchema } from './run-migrations';
 
+// Spelled as the partial index's predicate so SQLite can match them.
+const TRAIL_FILTER = sql<boolean>`kind IS NOT NULL AND kind != 'heartbeat'`;
+
+export interface StoredEvent {
+  readonly id: number;
+
+  // Epoch ms of ts.
+  readonly at: number;
+  readonly atcID: SessionID;
+  readonly agentSessionID: AgentSessionID | null;
+  readonly kind: string;
+
+  // The event's detail, else the hook's message.
+  readonly detail: string | null;
+}
+
 /**
  * Daemon state in one SQLite store: the restorable fleet, the hook-event
- * debug trail, and the spawn-directory history. The statusline contract
+ * trail that events.read and lastActivityAt read, the spawn-directory
+ * history, and the per-session message inbox. The statusline contract
  * file (status.json) stays a plain file because reporters inside wrangled
  * sessions read it without speaking to the daemon. An existing fleet.json
  * seeds the fleet table once, so upgrading never loses a restorable fleet.
@@ -72,6 +96,9 @@ export class StateStore {
         'agent',
         'exited',
         'parent',
+        'prompt',
+        'result',
+        'transcript_path',
       ])
       .execute();
 
@@ -87,6 +114,9 @@ export class StateStore {
         ...(row.last_attached === null ? {} : { lastAttachedAt: row.last_attached }),
         ...(row.exited === 0 ? {} : { exited: true }),
         ...(row.parent === null ? {} : { parent: toAgentSessionID(row.parent) }),
+        ...(row.prompt === null ? {} : { prompt: row.prompt }),
+        ...(row.result === null ? {} : { result: row.result }),
+        ...(row.transcript_path === null ? {} : { transcriptPath: row.transcript_path }),
       });
     }
 
@@ -132,6 +162,9 @@ export class StateStore {
             agent: entry.agent,
             exited: entry.exited === true ? 1 : 0,
             parent: entry.parent ?? null,
+            prompt: entry.prompt ?? null,
+            result: entry.result ?? null,
+            transcript_path: entry.transcriptPath ?? null,
           })
           .orReplace()
           .execute();
@@ -139,7 +172,27 @@ export class StateStore {
     });
   }
 
-  async recordEvent(e: HookEvent): Promise<void> {
+  // Rewrites fields on one existing row and leaves every other row as it
+  // stands. A session without a row yet is a no-op: the next fleet write
+  // inserts it with these fields.
+  async updateFleetEntry(agentSessionID: AgentSessionID, fields: FleetEntryUpdate): Promise<void> {
+    const values = {
+      ...(fields.result === undefined ? {} : { result: fields.result }),
+      ...(fields.transcriptPath === undefined ? {} : { transcript_path: fields.transcriptPath }),
+    };
+
+    if (Object.keys(values).length === 0) {
+      return;
+    }
+
+    await this.db
+      .updateTable('fleet')
+      .set(values)
+      .where('agent_session_id', '=', agentSessionID)
+      .execute();
+  }
+
+  async recordEvent(e: HookEvent, ev: Readonly<AdapterEvent> | null = null): Promise<void> {
     const rawMessage = e.payload['message'];
     const rawSessionID = e.payload['session_id'] ?? e.payload['sessionId'];
     const message = typeof rawMessage === 'string' ? rawMessage : null;
@@ -154,10 +207,57 @@ export class StateStore {
         event: e.event,
         message,
         session_id: sessionID,
+        kind: ev === null ? null : ev.kind,
+        detail: ev?.detail ?? null,
       })
       .execute();
   }
 
+  async collectEventsAfter(afterID: number, limit: number): Promise<StoredEvent[]> {
+    const rows = await this.db
+      .selectFrom('events')
+      .select(['id', 'ts', 'atc_id', 'session_id', 'kind', 'detail', 'message'])
+      .where('id', '>', afterID)
+      .where(TRAIL_FILTER)
+      .orderBy('id', 'asc')
+      .limit(limit)
+      .execute();
+
+    return buildStoredEvents(rows);
+  }
+
+  async collectLatestEvents(limit: number): Promise<StoredEvent[]> {
+    const rows = await this.db
+      .selectFrom('events')
+      .select(['id', 'ts', 'atc_id', 'session_id', 'kind', 'detail', 'message'])
+      .where(TRAIL_FILTER)
+      .orderBy('id', 'desc')
+      .limit(limit)
+      .execute();
+
+    return buildStoredEvents(rows).toReversed();
+  }
+
+  // Matches the session by either id, since a restore re-mints the atc id
+  // while the agent session id carries on.
+  async loadLastActivityAt(
+    atcID: SessionID,
+    agentSessionID: AgentSessionID | undefined,
+  ): Promise<number | null> {
+    const row = await this.db
+      .selectFrom('events')
+      .select(sql<string | null>`MAX(ts)`.as('ts'))
+      .where((eb) =>
+        eb.or([
+          eb('atc_id', '=', atcID),
+          ...(agentSessionID === undefined ? [] : [eb('session_id', '=', agentSessionID)]),
+        ]),
+      )
+      .executeTakeFirst();
+
+    return row?.ts === null || row?.ts === undefined ? null : Date.parse(row.ts);
+  }
+
   async recordSpawnDir(cwd: string): Promise<void> {
     await this.db
       .insertInto('spawn_history')
@@ -198,6 +298,115 @@ export class StateStore {
       .execute();
   }
 
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- every field is readonly; the branded id has no readonly form to wrap it in
+  async writeMessage(record: MessageRecord): Promise<void> {
+    await this.db
+      .insertInto('messages')
+      .values({
+        id: record.id,
+        atc_id: record.atcID,
+        agent_session_id: record.agentSessionID ?? null,
+        sender: record.from,
+        text: record.text,
+        status: record.status,
+        sent_at: record.sentAt,
+        delivered_at: record.deliveredAt ?? null,
+        answered_at: record.answeredAt ?? null,
+        answer: record.answer ?? null,
+      })
+      .execute();
+  }
+
+  async collectPendingMessages(owner: MessageOwner): Promise<MessageRecord[]> {
+    const rows = await this.db
+      .selectFrom('messages')
+      .selectAll()
+      .where('status', '=', 'accepted')
+      .where((eb) => buildOwnerFilter(eb, owner))
+      .orderBy('sent_at', 'asc')
+      .orderBy(sql`rowid`, 'asc')
+      .execute();
+
+    return rows.map((row) => toMessageRecord(row));
+  }
+
+  async findMessage(id: MessageID, owner: MessageOwner): Promise<MessageRecord | null> {
+    const row = await this.db
+      .selectFrom('messages')
+      .selectAll()
+      .where('id', '=', id)
+      .where((eb) => buildOwnerFilter(eb, owner))
+      .executeTakeFirst();
+
+    return row === undefined ? null : toMessageRecord(row);
+  }
+
+  async findMessageByID(id: MessageID): Promise<MessageRecord | null> {
+    const row = await this.db
+      .selectFrom('messages')
+      .selectAll()
+      .where('id', '=', id)
+      .executeTakeFirst();
+
+    return row === undefined ? null : toMessageRecord(row);
+  }
+
+  async updateMessageDelivered(
+    id: MessageID,
+    owner: MessageOwner,
+    at: number,
+  ): Promise<MessageRecord | null> {
+    const row = await this.db
+      .updateTable('messages')
+      .set({ status: 'delivered', delivered_at: at })
+      .where('id', '=', id)
+      .where('status', '=', 'accepted')
+      .where((eb) => buildOwnerFilter(eb, owner))
+      .returningAll()
+      .executeTakeFirst();
+
+    return row === undefined ? null : toMessageRecord(row);
+  }
+
+  async updateMessageAnswered(
+    id: MessageID,
+    owner: MessageOwner,
+    answer: string,
+    at: number,
+  ): Promise<MessageRecord | null> {
+    const row = await this.db
+      .updateTable('messages')
+      .set({ status: 'answered', answered_at: at, answer })
+      .where('id', '=', id)
+      .where('status', 'in', ['accepted', 'delivered'])
+      .where((eb) => buildOwnerFilter(eb, owner))
+      .returningAll()
+      .executeTakeFirst();
+
+    return row === undefined ? null : toMessageRecord(row);
+  }
+
+  // Messages sent before the agent reported its session id carry no agent
+  // session id; this stamps them once it is known, and moves every message
+  // from a previous agent session id to a changed one.
+  async updateMessageOwner(
+    atcID: SessionID,
+    previous: AgentSessionID | undefined,
+    next: AgentSessionID,
+  ): Promise<void> {
+    await this.db
+      .updateTable('messages')
+      .set({ agent_session_id: next })
+      .where((eb) => {
+        const unstamped = eb.and([eb('atc_id', '=', atcID), eb('agent_session_id', 'is', null)]);
+
+        return previous === undefined
+          ? unstamped
+          : eb.or([unstamped, eb('agent_session_id', '=', previous)]);
+      })
+      .execute();
+  }
+
   async stop(): Promise<void> {
     await this.db.destroy();
 
@@ -235,3 +444,62 @@ export class StateStore {
     } catch {}
   }
 }
+
+interface EventRow {
+  readonly id: number;
+  readonly ts: string;
+  readonly atc_id: string;
+  readonly session_id: string | null;
+  readonly kind: string | null;
+  readonly detail: string | null;
+  readonly message: string | null;
+}
+
+function buildStoredEvents(rows: readonly EventRow[]): StoredEvent[] {
+  const events: StoredEvent[] = [];
+
+  for (const row of rows) {
+    if (row.kind === null) {
+      continue;
+    }
+
+    events.push({
+      id: row.id,
+      at: Date.parse(row.ts),
+      atcID: toSessionID(row.atc_id),
+      agentSessionID: row.session_id === null ? null : toAgentSessionID(row.session_id),
+      kind: row.kind,
+      detail: row.detail ?? row.message,
+    });
+  }
+
+  return events;
+}
+
+function buildOwnerFilter(
+  eb: ExpressionBuilder<StateStoreSchema, 'messages'>, // oxlint-disable-line prefer-readonly-parameter-types -- a kysely expression builder bound to a live query; not meaningfully freezable
+  owner: MessageOwner,
+): Expression<SqlBool> {
+  const byAtcID = eb('atc_id', '=', owner.atcID);
+
+  return owner.agentSessionID === undefined
+    ? byAtcID
+    : eb.or([byAtcID, eb('agent_session_id', '=', owner.agentSessionID)]);
+}
+
+function toMessageRecord(row: Readonly<StateStoreSchema['messages']>): MessageRecord {
+  return {
+    id: toMessageID(row.id),
+    atcID: toSessionID(row.atc_id),
+    ...(row.agent_session_id === null
+      ? {}
+      : { agentSessionID: toAgentSessionID(row.agent_session_id) }),
+    from: row.sender,
+    text: row.text,
+    status: row.status,
+    sentAt: row.sent_at,
+    ...(row.delivered_at === null ? {} : { deliveredAt: row.delivered_at }),
+    ...(row.answered_at === null ? {} : { answeredAt: row.answered_at }),
+    ...(row.answer === null ? {} : { answer: row.answer }),
+  };
+}

package/src/tap.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { DaemonClient } from './client/daemon-client';
+import { DaemonError } from './protocol/daemon-error';
+import { daemonSocketPath } from './shared/config';
+import { getBuild } from './shared/get-build';
+
+const INBOX_MESSAGE_SCHEMA = z.looseObject({
+  message: z.string(),
+  from: z.string(),
+  text: z.string(),
+  sentAt: z.number(),
+});
+
+interface InboxMessage {
+  readonly message: string;
+  readonly from: string;
+  readonly text: string;
+  readonly sentAt: number;
+}
+
+/**
+ * Streams one session's inbox to stdout, one NDJSON line per message, and
+ * acks each message once its line is written. It talks to the daemon that
+ * is already running and never boots one: a tap runs inside the session it
+ * serves, so a restart from here would take the whole fleet down. Exits 1
+ * with a hint when no daemon listens or the session cannot be tapped, and
+ * 0 once the daemon closes the connection or ends the subscription because
+ * another tap replaced it or the session was removed.
+ */
+export async function runTap(session: string): Promise<void> {
+  let client: DaemonClient;
+
+  try {
+    client = await DaemonClient.open(daemonSocketPath);
+  } catch {
+    console.error(`atc tap: no daemon at ${daemonSocketPath} — start atc first`);
+    process.exit(1);
+  }
+
+  const closed = Promise.withResolvers<void>();
+  let written: Promise<void> = Promise.resolve();
+
+  client.onClose = () => {
+    closed.resolve();
+  };
+
+  client.onEvent = (event) => {
+    if (event.ev === 'InboxClosed' && event['s'] === session) {
+      closed.resolve();
+
+      return;
+    }
+
+    if (event.ev !== 'InboxMessage' || event['s'] !== session) {
+      return;
+    }
+
+    const parsed = INBOX_MESSAGE_SCHEMA.safeParse(event);
+
+    if (!parsed.success) {
+      return;
+    }
+
+    const msg: InboxMessage = {
+      message: parsed.data.message,
+      from: parsed.data.from,
+      text: parsed.data.text,
+      sentAt: parsed.data.sentAt,
+    };
+
+    const previous = written;
+
+    written = (async () => {
+      await previous;
+      await ackInboxMessage(client, session, msg);
+    })();
+  };
+
+  try {
+    await client.sendHello(getBuild());
+    await client.sendRequest('session.tap', { session });
+  } catch (error) {
+    console.error(`atc tap: ${formatError(error)}`);
+    client.stop();
+    process.exit(1);
+  }
+
+  await closed.promise;
+  await written;
+
+  process.exit(0);
+}
+
+interface RequestSender {
+  readonly sendRequest: DaemonClient['sendRequest'];
+}
+
+async function ackInboxMessage(
+  client: RequestSender,
+  session: string,
+  msg: InboxMessage,
+): Promise<void> {
+  const line = `${JSON.stringify({ id: msg.message, from: msg.from, text: msg.text, sentAt: msg.sentAt })}\n`;
+
+  try {
+    await Bun.write(Bun.stdout, line);
+  } catch {
+    process.exit(1);
+  }
+
+  try {
+    await client.sendRequest('message.ack', { session, message: msg.message });
+  } catch (error) {
+    console.error(`atc tap: ${formatError(error)}`);
+  }
+}
+
+function formatError(error: unknown): string {
+  return error instanceof DaemonError ? `${error.code}: ${error.message}` : String(error);
+}