@zgeoff/atc 0.1.9 → 0.1.11

package/src/grok-adapter.ts

@@ -0,0 +1,274 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type {
+  AdapterEvent,
+  AgentAdapter,
+  NameUpdate,
+  ResumeCheck,
+  SpawnOptions,
+  SpawnPlan,
+} from './agent-adapter';
+import type { Config } from './config';
+import type { HookEvent } from './hooks';
+import { normalizeHookEventName } from './normalize-hook-event';
+import { isRecord } from './report';
+
+interface GrokSessionHookState {
+  latestPromptID?: string;
+  lastKind: AdapterEvent['kind'];
+}
+
+/**
+ * The Grok Build adapter: spawn arguments, hook payload mapping,
+ * resume semantics, and summary.json name-pulling.
+ */
+export class GrokAdapter implements AgentAdapter {
+  readonly kind = 'grok';
+
+  // Grok has no headless handoff.
+  readonly headlessRunner = null;
+
+  // Grok's hooks are authoritative; no screen heuristics needed.
+  readonly screenDetector = null;
+
+  private readonly config: Config;
+
+  private readonly hookState = new Map<string, GrokSessionHookState>();
+
+  constructor(config: Config) {
+    this.config = config;
+  }
+
+  planSpawn(opts: SpawnOptions): SpawnPlan {
+    return {
+      bin: this.config.grokBin,
+      args: [
+        ...this.config.grokArgs.filter((arg) => arg !== '--leader' && arg !== '--no-leader'),
+        '--no-leader',
+        ...(typeof opts.resume === 'string' ? ['--resume', opts.resume] : []),
+        ...(opts.prompt === '' ? [] : [opts.prompt]),
+      ],
+    };
+  }
+
+  normalizeHook(e: HookEvent): AdapterEvent {
+    const sessionID = e.payload['sessionId'];
+    const cwd = e.payload['cwd'];
+    const promptID = e.payload['promptId'];
+    const subagentType = e.payload['subagentType'];
+
+    const base: AdapterEvent = {
+      kind: 'heartbeat',
+      ...(typeof sessionID === 'string' ? { agentSessionID: sessionID } : {}),
+    };
+
+    const named: AdapterEvent = {
+      ...base,
+      ...(typeof sessionID === 'string' && typeof cwd === 'string'
+        ? { nameSource: buildGrokNameSource(sessionID, cwd) }
+        : {}),
+    };
+
+    if (typeof subagentType === 'string' && subagentType !== '') {
+      return this.emitHook(e.atcId, { ...base, kind: 'heartbeat' });
+    }
+
+    const event = normalizeHookEventName(e.event);
+    const prior = this.hookState.get(e.atcId);
+
+    const stale =
+      typeof promptID === 'string' &&
+      prior?.latestPromptID !== undefined &&
+      promptID !== prior.latestPromptID;
+
+    switch (event) {
+      case 'SessionStart': {
+        return this.emitHook(e.atcId, { ...named, kind: 'started' });
+      }
+      case 'UserPromptSubmit': {
+        const prompt = e.payload['prompt'];
+        const preview = typeof prompt === 'string' ? prompt.slice(0, 80) : '';
+        const submittedID = typeof promptID === 'string' ? promptID : undefined;
+
+        return this.emitHook(
+          e.atcId,
+          {
+            ...named,
+            kind: 'prompt-submitted',
+            ...(preview === '' ? {} : { message: preview, detail: truncateDetail(preview) }),
+          },
+          submittedID,
+        );
+      }
+      case 'Notification': {
+        const notificationType = e.payload['notificationType'];
+        const message = e.payload['message'];
+
+        if (notificationType === 'permission_prompt') {
+          return this.emitHook(e.atcId, {
+            ...base,
+            kind: 'needs-input',
+            ...(typeof message === 'string' && message !== ''
+              ? { message, detail: truncateDetail(message) }
+              : {}),
+          });
+        }
+
+        if (notificationType === 'idle_prompt') {
+          const kind = prior?.lastKind === 'needs-input' ? 'heartbeat' : 'turn-done';
+
+          return this.emitHook(e.atcId, { ...named, kind });
+        }
+
+        return this.emitHook(e.atcId, base);
+      }
+      case 'Stop': {
+        if (e.payload['reason'] !== 'end_turn' || stale) {
+          return this.emitHook(e.atcId, base);
+        }
+
+        return this.emitHook(e.atcId, buildTurnDoneEvent(named, e.payload));
+      }
+      case 'StopFailure':
+      case 'StopCancelled': {
+        if (stale) {
+          return this.emitHook(e.atcId, base);
+        }
+
+        return this.emitHook(e.atcId, buildTurnDoneEvent(named, e.payload));
+      }
+      case 'SessionEnd': {
+        this.hookState.delete(e.atcId);
+
+        return { ...base, kind: 'ended' };
+      }
+      default: {
+        return this.emitHook(e.atcId, base);
+      }
+    }
+  }
+
+  loadName(source: string, namedBy: 'user' | 'auto' | 'agent'): Promise<NameUpdate | null> {
+    const parsed = readSummary(source) ?? readSummary(findGrokSummary(source));
+
+    if (parsed === null) {
+      return Promise.resolve(null);
+    }
+
+    const generated = parsed['generated_title'];
+    const summary = parsed['session_summary'];
+    const title = typeof generated === 'string' ? generated : '';
+    const sessionSummary = typeof summary === 'string' ? summary : '';
+
+    if (parsed['title_is_manual'] === true && title !== '') {
+      return Promise.resolve({ name: title, namedBy: 'agent' });
+    }
+
+    if (namedBy !== 'user' && title !== '') {
+      return Promise.resolve({ name: title });
+    }
+
+    if (namedBy !== 'user' && sessionSummary !== '') {
+      return Promise.resolve({ name: sessionSummary });
+    }
+
+    return Promise.resolve(null);
+  }
+
+  canResume(session: ResumeCheck): boolean {
+    return session.agentSessionID !== undefined;
+  }
+
+  // Shell command that re-opens this session outside atc (or anywhere).
+  buildResumeCommand(cwd: string, agentSessionID: string | undefined): string | null {
+    const resume = agentSessionID === undefined ? 'grok' : `grok --resume ${agentSessionID}`;
+    const quoted = cwd.replaceAll("'", String.raw`'\''`);
+
+    return `cd '${quoted}' && ${resume}`;
+  }
+
+  private emitHook(atcID: string, event: Readonly<AdapterEvent>, promptID?: string): AdapterEvent {
+    const prior = this.hookState.get(atcID);
+    const latestPromptID = promptID ?? prior?.latestPromptID;
+
+    const tracked =
+      event.kind === 'needs-input' ||
+      event.kind === 'prompt-submitted' ||
+      event.kind === 'turn-done'
+        ? event.kind
+        : (prior?.lastKind ?? event.kind);
+
+    this.hookState.set(atcID, {
+      lastKind: tracked,
+      ...(latestPromptID === undefined ? {} : { latestPromptID }),
+    });
+
+    return event;
+  }
+}
+
+function resolveGrokHome(): string {
+  const home = process.env['GROK_HOME'];
+
+  return home !== undefined && home !== '' ? home : join(homedir(), '.grok');
+}
+
+function buildGrokNameSource(sessionID: string, cwd: string): string {
+  return join(resolveGrokHome(), 'sessions', encodeURIComponent(cwd), sessionID, 'summary.json');
+}
+
+function buildTurnDoneEvent(
+  named: Readonly<AdapterEvent>,
+  payload: Readonly<Record<string, unknown>>,
+): AdapterEvent {
+  const lastMessage = payload['lastAssistantMessage'];
+
+  return {
+    ...named,
+    kind: 'turn-done',
+    ...(typeof lastMessage === 'string' && lastMessage !== ''
+      ? { detail: truncateDetail(lastMessage) }
+      : {}),
+  };
+}
+
+function readSummary(source: string | null): Record<string, unknown> | null {
+  if (source === null) {
+    return null;
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(source, 'utf8'));
+
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function findGrokSummary(source: string): string | null {
+  const sessionID = source.split('/').at(-2);
+
+  if (sessionID === undefined || sessionID === '') {
+    return null;
+  }
+
+  const root = join(resolveGrokHome(), 'sessions');
+
+  try {
+    for (const group of readdirSync(root)) {
+      const candidate = join(root, group, sessionID, 'summary.json');
+
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+  } catch {}
+
+  return null;
+}
+
+function truncateDetail(text: string): string {
+  return text.length <= 600 ? text : `${text.slice(0, 599)}…`;
+}

package/src/hook-report.ts

@@ -1,9 +1,11 @@
+import { normalizeHookEventName } from './normalize-hook-event';
 import { isRecord, sendReport } from './report';
 
 /**
- * Runs as a Claude Code hook inside wrangled sessions. Reads the hook event
- * from stdin and forwards it to the atc unix socket. Always exits 0 so it
- * never blocks the session it reports on.
+ * Runs as a hook inside wrangled sessions. Reads the hook event from stdin
+ * (Claude snake_case keys or Grok camelCase keys) and forwards a PascalCase
+ * event name to the atc unix socket. Always exits 0 so it never blocks the
+ * session it reports on.
  */
 export async function runHookReport(): Promise<void> {
   const sock = process.env['ATC_SOCKET'];
@@ -22,7 +24,9 @@ export async function runHookReport(): Promise<void> {
       }
     } catch {}
 
-    const line = `${JSON.stringify({ atcId, event: payload['hook_event_name'], payload })}\n`;
+    const rawName = payload['hook_event_name'] ?? payload['hookEventName'];
+    const event = typeof rawName === 'string' ? normalizeHookEventName(rawName) : rawName;
+    const line = `${JSON.stringify({ atcId, event, payload })}\n`;
 
     await sendReport(sock, line, 2000);
   }

package/src/index.ts

@@ -10,16 +10,25 @@ import { countSessionStates, sortGroupedSessionViews, sortSessionViews } from '.
 import type { SessionState } from './sessions';
 import { ansi, cols, drawHelp, drawHome, drawOverlay, drawPicker, drawStatusBar, rows } from './ui';
 
+type AgentKind = 'claude' | 'grok' | 'codex';
+
 type Mode =
   | 'home'
   | 'attached'
   | 'overlay'
   | 'help'
+  | 'picker-agent'
   | 'picker-dir'
   | 'picker-name'
   | 'picker-prompt'
   | 'picker-eject';
 
+const AGENT_PICKS = [
+  { agent: 'claude' as const, label: 'Claude' },
+  { agent: 'grok' as const, label: 'Grok' },
+  { agent: 'codex' as const, label: 'Codex' },
+];
+
 interface MirrorSession {
   id: string;
   name: string;
@@ -31,9 +40,10 @@ interface MirrorSession {
   unread: boolean;
   lastMsg: string;
   createdAt: number;
-  kind: 'pty' | 'jsonl';
+  kind: 'pty' | 'headless';
   alive: boolean;
   resumable: boolean;
+  agent: AgentKind;
 }
 
 let mode: Mode = 'home';
@@ -58,6 +68,8 @@ let pickerSelected = 0;
 let spawnDir = '';
 let spawnName = '';
 let spawnResume = false;
+let spawnAgent: AgentKind = 'claude';
+let lastUsedAgent: AgentKind = 'claude';
 const stdout = process.stdout;
 
 // Full height: the atc status bar only exists on home/overlay screens;
@@ -251,7 +263,17 @@ function openOverlay() {
 function renderPicker() {
   const verb = spawnResume ? 'adopt' : 'spawn';
 
-  if (mode === 'picker-dir') {
+  if (mode === 'picker-agent') {
+    pickerSelected = Math.min(pickerSelected, AGENT_PICKS.length - 1);
+
+    drawPicker({
+      title: `${verb}: agent`,
+      items: AGENT_PICKS.map((pick) => pick.label),
+      selected: pickerSelected,
+      input: pickerInput,
+      hint: '↑↓ move · ⏎ select · esc cancel',
+    });
+  } else if (mode === 'picker-dir') {
     const items = pickMatches(allDirs, pickerInput).map((d) => formatDir(d));
 
     pickerSelected = Math.min(pickerSelected, Math.max(0, Math.min(items.length, 10) - 1));
@@ -295,9 +317,24 @@ function renderPicker() {
   scheduleStatus();
 }
 
-async function openDirPicker(resume = false) {
+function openAgentPicker(resume = false) {
   spawnResume = resume;
+  spawnAgent = lastUsedAgent;
+  pickerInput = '';
+
+  pickerSelected = Math.max(
+    0,
+    AGENT_PICKS.findIndex((p) => p.agent === lastUsedAgent),
+  );
+
+  mode = 'picker-agent';
 
+  stdout.write(ansi.clear);
+
+  renderPicker();
+}
+
+async function openDirPicker() {
   let recent: string[] = [];
 
   try {
@@ -344,6 +381,7 @@ async function spawnFromPicker(prompt: string) {
       cols: cols(),
       rows: ptyRows(),
       ...(spawnResume ? { resume: true } : {}),
+      agent: spawnAgent,
     });
 
     const spawned = toMirrorSession(ok['session']);
@@ -407,9 +445,10 @@ function toMirrorSession(value: unknown): MirrorSession | null {
     unread: value['unread'],
     lastMsg: value['lastMsg'],
     createdAt: value['createdAt'],
-    kind: value['kind'] === 'jsonl' ? 'jsonl' : 'pty',
+    kind: value['kind'] === 'headless' ? 'headless' : 'pty',
     alive: value['alive'],
-    resumable: typeof value['claudeId'] === 'string',
+    resumable: typeof value['agentSessionID'] === 'string',
+    agent: value['agent'] === 'grok' || value['agent'] === 'codex' ? value['agent'] : 'claude',
   };
 }
 
@@ -429,6 +468,7 @@ function upsertMirror(d: Readonly<MirrorSession>) {
     existing.kind = d.kind;
     existing.alive = d.alive;
     existing.resumable = d.resumable;
+    existing.agent = d.agent;
   }
 }
 
@@ -487,7 +527,7 @@ function applyDaemonEvent(e: EventMsg) {
           s.alive = false;
         }
 
-        if (e['kind'] === 'pty' || e['kind'] === 'jsonl') {
+        if (e['kind'] === 'pty' || e['kind'] === 'headless') {
           s.kind = e['kind'];
         }
 
@@ -507,7 +547,15 @@ function applyDaemonEvent(e: EventMsg) {
           s.lastMsg = e['lastMsg'];
         }
 
-        if (typeof e['claudeId'] === 'string') {
+        if (e['agent'] === 'grok' || e['agent'] === 'codex' || e['agent'] === 'claude') {
+          s.agent = e['agent'];
+        }
+
+        if (typeof e['agentSessionID'] === 'string') {
+          if (!s.resumable) {
+            lastUsedAgent = s.agent;
+          }
+
           s.resumable = true;
         }
       }
@@ -735,7 +783,7 @@ function applyOverlayKey(buf: Buffer) {
   }
 
   if (ch === 'n') {
-    void openDirPicker();
+    openAgentPicker();
 
     return;
   }
@@ -772,7 +820,13 @@ function applyOverlayKey(buf: Buffer) {
     return;
   }
 
-  if (ch === 'H' && sel !== undefined && sel.kind === 'pty' && sel.alive) {
+  if (
+    ch === 'H' &&
+    sel !== undefined &&
+    sel.kind === 'pty' &&
+    sel.alive &&
+    sel.agent === 'claude'
+  ) {
     ejectTarget = sel.id;
     pickerInput = '';
     mode = 'picker-eject';
@@ -784,14 +838,14 @@ function applyOverlayKey(buf: Buffer) {
     return;
   }
 
-  if (ch === 'P' && sel !== undefined && sel.resumable && (sel.kind === 'jsonl' || !sel.alive)) {
+  if (ch === 'P' && sel !== undefined && sel.resumable && (sel.kind === 'headless' || !sel.alive)) {
     void adoptSession(sel.id);
 
     return;
   }
 
   if (ch === 'r') {
-    void openDirPicker(true);
+    openAgentPicker(true);
 
     return;
   }
@@ -893,7 +947,7 @@ function applyTextKey(buf: Buffer, onSubmit: () => void, onCancel: () => void) {
     return;
   }
 
-  if (mode === 'picker-dir') {
+  if (mode === 'picker-dir' || mode === 'picker-agent') {
     if (isDown(buf)) {
       pickerSelected++;
 
@@ -933,6 +987,7 @@ const boot = await bootDaemonClient();
 let client = boot.client;
 let daemonStale = boot.stale;
 
+lastUsedAgent = boot.lastUsedAgent;
 client.onEvent = applyDaemonEvent;
 
 await refreshMirror();
@@ -989,6 +1044,7 @@ async function restartDaemon() {
 
   client = next.client;
   daemonStale = next.stale;
+  lastUsedAgent = next.lastUsedAgent;
   client.onEvent = applyDaemonEvent;
 
   await sendQuiet('fleet.restore', { cols: cols(), rows: ptyRows() });
@@ -1032,13 +1088,13 @@ process.stdin.on('data', (buf: Buffer) => {
       const ch = buf.toString();
 
       if (ch === 'n') {
-        void openDirPicker();
+        openAgentPicker();
 
         return;
       }
 
       if (ch === 'r') {
-        void openDirPicker(true);
+        openAgentPicker(true);
 
         return;
       }
@@ -1065,6 +1121,20 @@ process.stdin.on('data', (buf: Buffer) => {
 
       return;
     }
+    case 'picker-agent': {
+      applyTextKey(
+        buf,
+        () => {
+          spawnAgent = AGENT_PICKS[pickerSelected]?.agent ?? 'claude';
+          void openDirPicker();
+        },
+        () => {
+          toBase();
+        },
+      );
+
+      return;
+    }
     case 'picker-dir': {
       applyTextKey(
         buf,
@@ -1090,7 +1160,18 @@ process.stdin.on('data', (buf: Buffer) => {
           renderPicker();
         },
         () => {
-          toBase();
+          pickerInput = '';
+
+          pickerSelected = Math.max(
+            0,
+            AGENT_PICKS.findIndex((p) => p.agent === spawnAgent),
+          );
+
+          mode = 'picker-agent';
+
+          stdout.write(ansi.clear);
+
+          renderPicker();
         },
       );
 

package/src/mcp-server.ts

@@ -43,13 +43,18 @@ const TOOLS: readonly MCPTool[] = [
   {
     name: 'atc_session_spawn',
     description:
-      'Spawn a new Claude Code session in a directory. Returns the new session descriptor. Give it a prompt to start it working immediately.',
+      'Spawn a new session in a directory. Optional agent is claude, grok, or codex; omitted agent is always Claude, never the TUI last-used value. Returns the new session descriptor. Give it a prompt to start it working immediately.',
     inputSchema: {
       type: 'object',
       properties: {
         cwd: { type: 'string', description: 'Absolute path of the working directory' },
         name: { type: 'string', description: 'Session name; defaults to the directory basename' },
         prompt: { type: 'string', description: 'First message for the session' },
+        agent: {
+          type: 'string',
+          enum: ['claude', 'grok', 'codex'],
+          description: 'Which agent CLI to spawn; defaults to claude',
+        },
       },
       required: ['cwd'],
       additionalProperties: false,
@@ -236,10 +241,24 @@ async function runTool(
       return JSON.stringify(ok['sessions'], null, 2);
     }
     case 'atc_session_spawn': {
+      const rawAgent = args['agent'];
+
+      if (
+        rawAgent !== undefined &&
+        rawAgent !== 'claude' &&
+        rawAgent !== 'grok' &&
+        rawAgent !== 'codex'
+      ) {
+        throw new Error("agent must be 'claude', 'grok', or 'codex'");
+      }
+
       const ok = await client.sendRequest('session.spawn', {
         cwd: args['cwd'],
         ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
         ...(typeof args['prompt'] === 'string' ? { prompt: args['prompt'] } : {}),
+        ...(rawAgent === 'claude' || rawAgent === 'grok' || rawAgent === 'codex'
+          ? { agent: rawAgent }
+          : {}),
         cols: 100,
         rows: 30,
       });

package/src/normalize-hook-event.ts

@@ -0,0 +1,11 @@
+/**
+ * Canonicalize a hook event name to PascalCase. Claude already sends
+ * PascalCase (`SessionStart`); Grok sends snake_case (`session_start`).
+ * Restore stagger and the adapter switch compare the PascalCase form.
+ */
+export function normalizeHookEventName(raw: string): string {
+  return raw
+    .split('_')
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join('');
+}

package/src/pick-tab-target.ts

@@ -8,7 +8,7 @@ interface TabCandidate {
   readonly lastAttachedAt: number;
   readonly createdAt: number;
   readonly alive: boolean;
-  readonly kind: 'pty' | 'jsonl';
+  readonly kind: 'pty' | 'headless';
 }
 
 /**

package/src/print-codex-hook-file.ts

@@ -0,0 +1,26 @@
+import { buildCLICommand } from './build-cli-command';
+
+const CODEX_HOOK_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PermissionRequest',
+  'Stop',
+] as const;
+
+/**
+ * Print the Codex hook entries to stdout. The operator merges them into
+ * `$CODEX_HOME/hooks.json` and trusts them once in the Codex TUI — Codex
+ * parses untrusted hooks but never runs them. atc never writes that path.
+ */
+export function printCodexHookFile(): void {
+  process.stdout.write(buildCodexHookFile());
+}
+
+function buildCodexHookFile(): string {
+  const cmd = buildCLICommand('hook-report');
+  const buildEntry = (timeout: number) => [{ hooks: [{ type: 'command', command: cmd, timeout }] }];
+  const hooks = Object.fromEntries(CODEX_HOOK_EVENTS.map((event) => [event, buildEntry(5)]));
+
+  // Codex caps SessionEnd hooks at three seconds.
+  return `${JSON.stringify({ hooks: { ...hooks, SessionEnd: buildEntry(3) } }, null, 2)}\n`;
+}

package/src/print-grok-hook-file.ts

@@ -0,0 +1,27 @@
+import { buildCLICommand } from './build-cli-command';
+
+const GROK_HOOK_EVENTS = [
+  'SessionStart',
+  'SessionEnd',
+  'UserPromptSubmit',
+  'Stop',
+  'StopFailure',
+  'StopCancelled',
+  'Notification',
+] as const;
+
+/**
+ * Print the Grok hook file to stdout. The operator copies it to
+ * `$GROK_HOME/hooks/atc-reporter.json`; atc never writes that path.
+ */
+export function printGrokHookFile(): void {
+  process.stdout.write(buildGrokHookFile());
+}
+
+function buildGrokHookFile(): string {
+  const cmd = buildCLICommand('hook-report');
+  const entry = [{ hooks: [{ type: 'command', command: cmd, timeout: 5 }] }];
+  const hooks = Object.fromEntries(GROK_HOOK_EVENTS.map((event) => [event, entry]));
+
+  return `${JSON.stringify({ hooks }, null, 2)}\n`;
+}

package/src/protocol.ts

@@ -5,7 +5,7 @@ import { isRecord } from './report';
  * per line. Three message kinds, distinguished by which fields are present —
  * request (id + m), response (id + ok or err), event (ev).
  */
-export const PROTOCOL_V = 1;
+export const PROTOCOL_V = 2;
 
 // Control lines are capped before buffering; PTY output is split into chunks
 // so a queued response is delayed by at most one chunk.