@zgeoff/atc 2.6.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/agents/agent-adapter.ts

@@ -124,6 +124,10 @@ export interface AgentAdapter {
 
   // The detector stack's screen tier; null when hooks are authoritative.
   readonly screenDetector: ScreenDetector | null;
+
+  // Whether a session under this agent can take inbox messages through a tap;
+  // false refuses every message as unsupported.
+  readonly takesMessages: boolean;
   readonly planSpawn: (opts: SpawnOptions) => SpawnPlan;
   readonly normalizeHook: (e: HookEvent) => AdapterEvent;
   readonly loadName: (

package/src/agents/claude-adapter.ts

@@ -47,6 +47,8 @@ export class ClaudeAdapter implements AgentAdapter {
 
   readonly parseTranscriptLine = parseClaudeTranscriptLine;
 
+  readonly takesMessages = true;
+
   private readonly config: Config;
 
   // Written on first spawn so constructing the adapter touches no state.

package/src/agents/codex-adapter.ts

@@ -47,6 +47,8 @@ export class CodexAdapter implements AgentAdapter {
   // Codex's hooks are authoritative; no screen heuristics needed.
   readonly screenDetector = null;
 
+  readonly takesMessages = false;
+
   private readonly config: Config;
 
   constructor(config: Config) {

package/src/agents/gateway-adapter.ts

@@ -37,6 +37,8 @@ export class GatewayAdapter implements AgentAdapter {
   // The gateway runs the Claude CLI, which writes the same transcript.
   readonly parseTranscriptLine = parseClaudeTranscriptLine;
 
+  readonly takesMessages = true;
+
   private readonly gateway: GatewayConfig;
 
   private readonly claude: ClaudeAdapter;

package/src/agents/grok-adapter.ts

@@ -60,6 +60,8 @@ export class GrokAdapter implements AgentAdapter {
   // Grok's hooks are authoritative; no screen heuristics needed.
   readonly screenDetector = null;
 
+  readonly takesMessages = false;
+
   private readonly config: Config;
 
   private readonly hookState = new Map<SessionID, GrokSessionHookState>();

package/src/cli.ts

@@ -63,6 +63,10 @@ const main = defineCommand({
           const restoreBootTimeoutMs =
             Number.isFinite(capOverride) && capOverride >= 0 ? capOverride : 15_000;
 
+          // How long a started session may go without a tap before a message
+          // to it is refused. Tests pin it to 0 to reach the refusal at once.
+          const graceOverride = Number(process.env['ATC_TAP_GRACE_MS']);
+
           const claudeAdapter = new claude.ClaudeAdapter(cfg, (runOpts, hooks) =>
             headless.startHeadlessRun({ ...runOpts, claudeBin: cfg.claudeBin }, hooks),
           );
@@ -89,6 +93,9 @@ const main = defineCommand({
             pidPath: config.daemonPidFile,
             hooks: cfg.hooks,
             restoreBootTimeoutMs,
+            ...(Number.isFinite(graceOverride) && graceOverride >= 0
+              ? { tapGraceMs: graceOverride }
+              : {}),
             ...(Number.isFinite(queueBytes) && queueBytes > 0 ? { queueBytes } : {}),
             onQuit: () => process.exit(0),
           });
@@ -152,6 +159,45 @@ const main = defineCommand({
           await reporter.runHookReport();
         },
       }),
+    tap: () =>
+      defineCommand({
+        meta: {
+          name: 'tap',
+          description: "Stream a session's inbox to stdout as NDJSON, acking each message",
+        },
+        args: {
+          session: {
+            type: 'string',
+            required: true,
+            description: 'The atc session id to tap',
+          },
+        },
+        async run(ctx) {
+          const tap = await import('./tap');
+
+          await tap.runTap(ctx.args.session);
+        },
+      }),
+    report: () =>
+      defineCommand({
+        meta: {
+          name: 'report',
+          description: 'Report a message event from a wrangled session to the atc socket',
+          hidden: true,
+        },
+
+        // Neither arg is required: a citty usage error exits nonzero, and
+        // reporters must always exit 0.
+        args: {
+          kind: { type: 'positional', required: false, default: '' },
+          message: { type: 'string', default: '' },
+        },
+        async run(ctx) {
+          const reporter = await import('./report');
+
+          await reporter.runReport(ctx.args.kind, ctx.args.message);
+        },
+      }),
     statusline: () =>
       defineCommand({
         meta: {

package/src/client/daemon-client.ts

@@ -16,10 +16,14 @@ interface Pending {
 export class DaemonClient {
   onEvent: (event: EventMsg) => void = () => {};
 
+  onClose: () => void = () => {};
+
   private queue: OutboundQueue | null = null;
 
   private buffer = '';
 
+  private readonly decoder = new TextDecoder();
+
   private nextID = 1;
 
   private readonly pending = new Map<number, Pending>();
@@ -33,13 +37,14 @@ export class DaemonClient {
       unix: socketPath,
       socket: {
         data(_s, buf) {
-          client.applyChunk(buf.toString());
+          client.applyChunk(client.decodeChunk(buf));
         },
         drain() {
           client.queue?.drain();
         },
         close() {
           client.drainPending('connection closed');
+          client.onClose();
         },
         error() {},
       },
@@ -74,6 +79,13 @@ export class DaemonClient {
     this.drainPending('client closed');
   }
 
+  // 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
+  private decodeChunk(buf: Uint8Array): string {
+    return this.decoder.decode(buf, { stream: true });
+  }
+
   private applyChunk(chunk: string): void {
     this.buffer += chunk;
 

package/src/daemon/answer-byte-cap.ts

@@ -0,0 +1 @@
+export const ANSWER_BYTE_CAP = 65_536;

package/src/daemon/build-session-message-event.ts

@@ -0,0 +1,29 @@
+import { truncateDetail } from '../agents/truncate-detail';
+import { PROTOCOL_V } from '../protocol/protocol';
+import type { EventMsg } from '../protocol/protocol';
+import type { SessionID } from '../shared/session-id';
+import type { MessageRecord } from '../store/message-record';
+
+/**
+ * The `SessionMessage` event for one message status change, addressed by
+ * the atc session id the message currently belongs to. The event carries
+ * short previews of the text and answer, never the full content, so a
+ * broadcast stays small; `message.get` returns the full message. Delivery
+ * and answer fields appear only once they are set.
+ */
+// oxlint-disable-next-line prefer-readonly-parameter-types -- every field is readonly; the branded id has no readonly form to wrap it in
+export function buildSessionMessageEvent(sessionID: SessionID, record: MessageRecord): EventMsg {
+  return {
+    v: PROTOCOL_V,
+    ev: 'SessionMessage',
+    s: sessionID,
+    message: record.id,
+    status: record.status,
+    from: record.from,
+    textPreview: truncateDetail(record.text),
+    sentAt: record.sentAt,
+    ...(record.deliveredAt === undefined ? {} : { deliveredAt: record.deliveredAt }),
+    ...(record.answeredAt === undefined ? {} : { answeredAt: record.answeredAt }),
+    ...(record.answer === undefined ? {} : { answerPreview: truncateDetail(record.answer) }),
+  };
+}

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
@@ -165,6 +193,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 +498,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 +830,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',