@zgeoff/atc 2.5.1 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.5.1",
+  "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

@@ -46,6 +46,23 @@ export interface AdapterEvent {
   // Claude resume-existence path. Distinct from nameSource: a naming
   // handle is not a resume gate.
   transcriptSource?: string;
+
+  // The agent's whole final message for a finished turn; detail holds a bounded preview of it.
+  result?: string;
+}
+
+export interface TranscriptToolUse {
+  readonly name: string;
+  readonly input: string;
+}
+
+export interface TranscriptRow {
+  readonly role: 'user' | 'assistant';
+  readonly text: string;
+  readonly tools: readonly TranscriptToolUse[];
+
+  // Epoch ms from the line's timestamp.
+  readonly at: number | null;
 }
 
 export interface NameUpdate {
@@ -107,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: (
@@ -118,4 +139,9 @@ export interface AgentAdapter {
     cwd: string,
     agentSessionID: AgentSessionID | undefined,
   ) => string | null;
+
+  // Turns one line of the agent's transcript file into a conversation row,
+  // null for a line that is not one. Absent: atc cannot read this agent's
+  // transcript.
+  readonly parseTranscriptLine?: (line: string) => TranscriptRow | null;
 }

package/src/agents/claude-adapter.ts

@@ -16,6 +16,7 @@ import type {
   SpawnOptions,
   SpawnPlan,
 } from './agent-adapter';
+import { parseClaudeTranscriptLine } from './parse-claude-transcript-line';
 import { truncateDetail } from './truncate-detail';
 import { writeHookSettings } from './write-hook-settings';
 
@@ -44,6 +45,10 @@ export class ClaudeAdapter implements AgentAdapter {
   // Claude's hooks are authoritative; no screen heuristics needed.
   readonly screenDetector = null;
 
+  readonly parseTranscriptLine = parseClaudeTranscriptLine;
+
+  readonly takesMessages = true;
+
   private readonly config: Config;
 
   // Written on first spawn so constructing the adapter touches no state.
@@ -110,7 +115,7 @@ export class ClaudeAdapter implements AgentAdapter {
           ...named,
           kind: 'turn-done',
           ...(lastMessage !== undefined && lastMessage !== ''
-            ? { detail: truncateDetail(lastMessage) }
+            ? { detail: truncateDetail(lastMessage), result: lastMessage }
             : {}),
         };
       }

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) {
@@ -117,7 +119,7 @@ export class CodexAdapter implements AgentAdapter {
           ...named,
           kind: 'turn-done',
           ...(lastMessage !== undefined && lastMessage !== ''
-            ? { detail: truncateDetail(lastMessage) }
+            ? { detail: truncateDetail(lastMessage), result: lastMessage }
             : {}),
         };
       }

package/src/agents/gateway-adapter.ts

@@ -14,6 +14,7 @@ import type {
   SpawnPlan,
 } from './agent-adapter';
 import { ClaudeAdapter } from './claude-adapter';
+import { parseClaudeTranscriptLine } from './parse-claude-transcript-line';
 import { writeHookSettings } from './write-hook-settings';
 
 /**
@@ -33,6 +34,11 @@ export class GatewayAdapter implements AgentAdapter {
   // The CLI's hooks are authoritative; no screen heuristics needed.
   readonly screenDetector = null;
 
+  // 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>();
@@ -269,7 +271,7 @@ function buildTurnDoneEvent(named: Readonly<AdapterEvent>, payload: GrokHookPayl
     ...named,
     kind: 'turn-done',
     ...(lastMessage !== undefined && lastMessage !== ''
-      ? { detail: truncateDetail(lastMessage) }
+      ? { detail: truncateDetail(lastMessage), result: lastMessage }
       : {}),
   };
 }

package/src/agents/parse-claude-transcript-line.ts

@@ -0,0 +1,107 @@
+import { isRecord } from '../shared/report';
+import { truncateToBytes } from '../shared/truncate-to-bytes';
+import type { TranscriptRow, TranscriptToolUse } from './agent-adapter';
+
+// One row must stay far under the protocol's line cap.
+const MAX_ROW_TEXT_BYTES = 16_384;
+
+export function parseClaudeTranscriptLine(line: string): TranscriptRow | null {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+
+  if (!isRecord(parsed)) {
+    return null;
+  }
+
+  const type = parsed['type'];
+
+  if (type !== 'user' && type !== 'assistant') {
+    return null;
+  }
+
+  if (parsed['isSidechain'] === true || parsed['isMeta'] === true) {
+    return null;
+  }
+
+  const message = parsed['message'];
+
+  if (!isRecord(message)) {
+    return null;
+  }
+
+  const content = message['content'];
+  const texts: string[] = [];
+  const tools: TranscriptToolUse[] = [];
+
+  if (typeof content === 'string') {
+    texts.push(content);
+  } else if (Array.isArray(content)) {
+    for (const block of content as unknown[]) {
+      if (!isRecord(block)) {
+        continue;
+      }
+
+      const text = block['text'];
+      const name = block['name'];
+
+      if (block['type'] === 'text' && typeof text === 'string') {
+        texts.push(text);
+      } else if (block['type'] === 'tool_use' && typeof name === 'string') {
+        tools.push({ name, input: formatToolInput(block['input']) });
+      }
+    }
+  } else {
+    return null;
+  }
+
+  const text = texts.join('\n');
+
+  if (text === '' && tools.length === 0) {
+    return null;
+  }
+
+  const timestamp = parsed['timestamp'];
+  const parsedAt = typeof timestamp === 'string' ? Date.parse(timestamp) : Number.NaN;
+
+  return {
+    role: type,
+    text: truncateToBytes(text, MAX_ROW_TEXT_BYTES),
+    tools,
+    at: Number.isNaN(parsedAt) ? null : parsedAt,
+  };
+}
+
+const TOOL_INPUT_KEYS = [
+  'command',
+  'file_path',
+  'path',
+  'pattern',
+  'url',
+  'query',
+  'description',
+  'prompt',
+];
+
+function formatToolInput(input: unknown): string {
+  if (!isRecord(input)) {
+    return '';
+  }
+
+  let summary = JSON.stringify(input);
+
+  for (const key of TOOL_INPUT_KEYS) {
+    const value = input[key];
+
+    if (typeof value === 'string') {
+      summary = value;
+      break;
+    }
+  }
+
+  return summary.length <= 200 ? summary : `${summary.slice(0, 199)}…`;
+}

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-fleet-events.ts

@@ -0,0 +1,35 @@
+import { encodeCursor } from '../protocol/encode-cursor';
+import type { StoredEvent } from '../store/state-store';
+import type { SessionDescriptor } from './sessions';
+
+export interface FleetEvent {
+  readonly cursor: string;
+  readonly at: number;
+  readonly session: string;
+  readonly name: string | null;
+  readonly kind: string;
+  readonly detail: string | null;
+}
+
+export function buildFleetEvents(
+  rows: readonly StoredEvent[],
+  sessions: readonly SessionDescriptor[],
+): FleetEvent[] {
+  return rows.map((row) => {
+    // A restore re-mints atc ids, so the agent session id is the stable link.
+    const live =
+      (row.agentSessionID === null
+        ? undefined
+        : sessions.find((s) => s.agentSessionID === row.agentSessionID)) ??
+      sessions.find((s) => s.id === row.atcID);
+
+    return {
+      cursor: encodeCursor({ kind: 'events', id: row.id }),
+      at: row.at,
+      session: live?.id ?? row.atcID,
+      name: live?.name ?? null,
+      kind: row.kind,
+      detail: row.detail,
+    };
+  });
+}

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