@zgeoff/atc 0.1.11 → 1.0.0

package/src/{sessions.ts → daemon/sessions.ts}

@@ -1,14 +1,15 @@
-import { readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { writeFileSync } from 'node:fs';
 import { spawn } from 'bun-pty';
 import type { IPty } from 'bun-pty';
-import { toAgentKind } from './agent-adapter';
-import type { AdapterEvent, AgentAdapter, AgentKind } from './agent-adapter';
-import { collectCleanEnv } from './collect-clean-env';
-import { socketPath, stateDir, statusFile } from './config';
+import type { AdapterEvent, AgentAdapter, AgentID } from '../agents/agent-adapter';
+import type { AgentSessionID } from '../shared/agent-session-id';
+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 type { FleetEntry, FleetStore } from '../store/fleet-entry';
 import type { HookEvent } from './hooks';
-import { isRecord } from './report';
-import { resolveRepoRoot } from './resolve-repo-root';
+import { mintSessionID } from './mint-session-id';
 
 export type SessionState = 'running' | 'needs_you' | 'done' | 'exited';
 
@@ -17,15 +18,15 @@ export type SessionEventKind = 'added' | 'state' | 'renamed' | 'removed';
 // The over-the-wire view of a session: everything but the PTY handle, plus
 // the surface kind.
 export interface SessionDescriptor {
-  readonly id: string;
+  readonly id: SessionID;
   readonly name: string;
   readonly cwd: string;
   readonly state: SessionState;
   readonly unread: boolean;
   readonly lastMsg: string;
   readonly lastDetail?: string;
-  readonly agentSessionID?: string;
-  readonly agent: AgentKind;
+  readonly agentSessionID?: AgentSessionID;
+  readonly agent: AgentID;
   readonly pinned: boolean;
   readonly lastAttachedAt: number;
   readonly repoRoot: string;
@@ -33,10 +34,14 @@ export interface SessionDescriptor {
   readonly createdAt: number;
   readonly kind: 'pty' | 'headless';
   readonly alive: boolean;
+
+  // Whether this session's agent can run a headless turn, so the client can
+  // offer the eject action without knowing which agent it is.
+  readonly canEject: boolean;
 }
 
 export interface Session {
-  id: string;
+  id: SessionID;
   name: string;
   cwd: string;
   kind: 'pty' | 'headless';
@@ -45,8 +50,8 @@ export interface Session {
   unread: boolean;
   lastMsg: string;
   lastDetail?: string;
-  agentSessionID?: string;
-  agent: AgentKind;
+  agentSessionID?: AgentSessionID;
+  agent: AgentID;
   transcriptSource?: string;
   pinned: boolean;
 
@@ -64,84 +69,10 @@ export interface Session {
   createdAt: number;
 }
 
-let counter = 0;
-
-export interface FleetEntry {
-  readonly name: string;
-  readonly cwd: string;
-  readonly agentSessionID: string;
-  readonly agent: AgentKind;
-  readonly pinned?: boolean;
-  readonly lastAttachedAt?: number;
-}
-
-const fleetFile = join(stateDir, 'fleet.json');
-
-export interface FleetStore {
-  readonly loadFleet: () => FleetEntry[];
-  readonly writeFleet: (entries: readonly FleetEntry[]) => void;
-}
-
-const jsonFleetStore: FleetStore = {
-  loadFleet: () => loadFleet(),
-  writeFleet: (entries) => {
-    try {
-      writeFileSync(fleetFile, JSON.stringify(entries, null, 2));
-    } catch {}
-  },
-};
-
-export function parseFleetEntry(raw: unknown): FleetEntry | undefined {
-  if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['cwd'] !== 'string') {
-    return undefined;
-  }
-
-  // Fleet files written before the id key was agent-neutral carry it under
-  // its Claude-era name.
-  const agentSessionID = raw['agentSessionID'] ?? raw['claudeId'];
-
-  if (typeof agentSessionID !== 'string') {
-    return undefined;
-  }
-
-  return {
-    name: raw['name'],
-    cwd: raw['cwd'],
-    agentSessionID,
-    agent: toAgentKind(raw['agent']),
-    ...(raw['pinned'] === true ? { pinned: true } : {}),
-    ...(typeof raw['lastAttachedAt'] === 'number' ? { lastAttachedAt: raw['lastAttachedAt'] } : {}),
-  };
-}
-
-function loadFleet(): FleetEntry[] {
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(fleetFile, 'utf8'));
-
-    if (!Array.isArray(parsed)) {
-      return [];
-    }
-
-    const entries: FleetEntry[] = [];
-
-    for (const entry of parsed) {
-      const parsedEntry = parseFleetEntry(entry);
-
-      if (parsedEntry !== undefined) {
-        entries.push(parsedEntry);
-      }
-    }
-
-    return entries;
-  } catch {
-    return [];
-  }
-}
-
 export class SessionManager {
   sessions: Session[] = [];
 
-  focusedId: string | null = null;
+  focusedId: SessionID | null = null;
 
   onOutput: (s: Session, data: string) => void = () => {};
 
@@ -149,9 +80,12 @@ export class SessionManager {
 
   onEvent: (kind: SessionEventKind, s: Session) => void = () => {};
 
-  private readonly fallback: AgentAdapter;
+  // Whether any registered adapter has a screen detector, decided once at
+  // construction since the registry never changes afterward. Lets a hot path
+  // that only cares about this answer skip walking live sessions to find it.
+  readonly hasScreenDetector: boolean;
 
-  private readonly adapters: Partial<Readonly<Record<AgentKind, AgentAdapter>>>;
+  private readonly adapters: Readonly<Record<AgentID, AgentAdapter>>;
 
   private readonly store: FleetStore;
 
@@ -159,31 +93,30 @@ export class SessionManager {
 
   constructor(
     fallback: AgentAdapter,
-    store: FleetStore = jsonFleetStore,
+    store: FleetStore,
     statusPath: string | undefined = statusFile,
-    adapters: Partial<Readonly<Record<AgentKind, AgentAdapter>>> = {},
+    adapters: readonly AgentAdapter[] = [],
   ) {
-    this.fallback = fallback;
-    this.adapters = adapters;
+    // Each adapter names the id it answers to, so a registry key can never
+    // disagree with the adapter behind it. A later one wins the id.
+    this.adapters = Object.fromEntries([fallback, ...adapters].map((a) => [a.id, a]));
+    this.hasScreenDetector = Object.values(this.adapters).some((a) => a.screenDetector !== null);
     this.store = store;
     this.statusPath = statusPath ?? statusFile;
   }
 
   /**
-   * Adapter for this kind, or null when none is registered. Never returns a
-   * different kind than the one asked for.
+   * Adapter registered under this id, or null when there is none. Lookup
+   * never falls back to another id: a session whose agent is not registered
+   * is unsupported, not somebody else's spawn.
    */
-  findAdapter(kind: AgentKind): AgentAdapter | null {
-    if (kind === 'claude') {
-      return this.adapters.claude ?? this.fallback;
-    }
-
-    return this.adapters[kind] ?? null;
+  findAdapter(id: AgentID): AgentAdapter | null {
+    return this.adapters[id] ?? null;
   }
 
   // Hands a live terminal session off to a headless run: the terminal dies,
   // the record lives on as a headless session and keeps its screen history.
-  yankHeadless(id: string): Session | null {
+  yankHeadless(id: SessionID): Session | null {
     const s = this.sessions.find((x) => x.id === id);
 
     if (!s || s.pty === null || s.agentSessionID === undefined) {
@@ -206,17 +139,31 @@ export class SessionManager {
 
   // Registers a fleet entry as a session with no terminal yet, so a
   // fleet-wide restore can show every incoming session at once; adopting it
-  // later attaches the terminal.
+  // later attaches the terminal. Exited entries come back as killed
+  // sessions: still listed and revivable, never auto-adopted.
   restore(entry: FleetEntry): Session {
+    const exited = entry.exited === true;
+
+    // An entry whose agent is no longer registered still gets its row, so a
+    // backend dropped from the config shows as itself instead of vanishing or
+    // reviving under another agent. Adopting a terminal for it is refused.
+    let lastMsg = 'waiting to restore';
+
+    if (exited) {
+      lastMsg = 'killed';
+    } else if (this.findAdapter(entry.agent) === null) {
+      lastMsg = `no adapter for '${entry.agent}'`;
+    }
+
     const session: Session = {
-      id: `s${++counter}-${Date.now().toString(36)}`,
+      id: mintSessionID(),
       name: entry.name,
       cwd: entry.cwd,
       kind: 'headless',
       pty: null,
-      state: 'running',
+      state: exited ? 'exited' : 'running',
       unread: false,
-      lastMsg: 'waiting to restore',
+      lastMsg,
       agentSessionID: entry.agentSessionID,
       agent: entry.agent,
       pinned: entry.pinned ?? false,
@@ -235,7 +182,7 @@ export class SessionManager {
 
   // Adopts a headless session back into a terminal: a fresh PTY resumes the
   // same agent session id.
-  adoptTerminal(id: string, cols: number, rows: number): Session | null {
+  adoptTerminal(id: SessionID, cols: number, rows: number): Session | null {
     const s = this.sessions.find((x) => x.id === id);
 
     if (!s || s.pty !== null || s.agentSessionID === undefined) {
@@ -280,7 +227,7 @@ export class SessionManager {
       this.emitChange();
     });
 
-    this.writeFleet();
+    void this.writeFleet();
     this.onEvent('state', s);
     this.emitChange();
 
@@ -292,7 +239,7 @@ export class SessionManager {
    * user strength, so auto-summaries stop overwriting it while an
    * in-session rename still wins. Pinned sessions lead every list.
    */
-  updateSession(id: string, name?: string, pinned?: boolean): boolean {
+  updateSession(id: SessionID, name?: string, pinned?: boolean): boolean {
     const s = this.sessions.find((x) => x.id === id);
 
     if (s === undefined) {
@@ -312,14 +259,14 @@ export class SessionManager {
       this.onEvent('state', s);
     }
 
-    this.writeFleet();
+    void this.writeFleet();
     this.writeStatus();
     this.emitChange();
 
     return true;
   }
 
-  updateSurfaceState(id: string, state: SessionState, msg: string) {
+  updateSurfaceState(id: SessionID, state: SessionState, msg: string) {
     const s = this.sessions.find((x) => x.id === id);
 
     if (!s || s.kind !== 'headless') {
@@ -336,7 +283,7 @@ export class SessionManager {
 
   // The detector-stack screen tier reports through here: only flips between
   // running and needs_you — hook-driven done/exited states always win.
-  updateAttention(id: string, state: 'needs_you' | 'running', msg: string) {
+  updateAttention(id: SessionID, state: 'needs_you' | 'running', msg: string) {
     const s = this.sessions.find((x) => x.id === id);
 
     if (!s || s.pty === null || s.state === state) {
@@ -362,17 +309,17 @@ export class SessionManager {
     return this.sessions.find((s) => s.id === this.focusedId) ?? null;
   }
 
-  // resume: true opens the agent's own session picker; a string resumes that
-  // specific agent session id (fleet restore).
+  // resume: true opens the agent's own session picker; an agent session id
+  // resumes that specific session (fleet restore).
   spawn(
     cwd: string,
     name: string,
     prompt: string,
     cols: number,
     rows: number,
-    resume: boolean | string = false,
+    resume: boolean | AgentSessionID = false,
     namedBy: 'user' | 'auto' = 'auto',
-    agent: AgentKind = 'claude',
+    agent: AgentID = 'claude',
   ): Session {
     const adapter = this.findAdapter(agent);
 
@@ -380,7 +327,7 @@ export class SessionManager {
       throw new Error(`no adapter for agent '${agent}'`);
     }
 
-    const id = `s${++counter}-${Date.now().toString(36)}`;
+    const id = mintSessionID();
     const plan = adapter.planSpawn({ prompt, resume });
 
     const pty = spawn(plan.bin, plan.args, {
@@ -435,7 +382,7 @@ export class SessionManager {
     });
 
     this.sessions.push(session);
-    this.writeFleet();
+    void this.writeFleet();
     this.writeStatus();
     this.onEvent('added', session);
 
@@ -460,6 +407,7 @@ export class SessionManager {
       createdAt: s.createdAt,
       kind: s.kind,
       alive: s.pty !== null || (s.kind === 'headless' && s.state !== 'exited'),
+      canEject: (this.findAdapter(s.agent)?.headlessRunner ?? null) !== null,
     }));
   }
 
@@ -491,9 +439,7 @@ export class SessionManager {
 
     if (ev.agentSessionID !== undefined && s.agentSessionID !== ev.agentSessionID) {
       s.agentSessionID = ev.agentSessionID;
-
-      this.writeFleet();
-
+      void this.writeFleet();
       dirty = true;
     }
 
@@ -587,13 +533,13 @@ export class SessionManager {
       s.namedBy = update.namedBy;
     }
 
-    this.writeFleet();
+    void this.writeFleet();
     this.onEvent('renamed', s);
     this.emitChange();
   }
 
   // Shell command that re-opens this session outside atc (or anywhere).
-  buildResumeCommand(id: string): string | null {
+  buildResumeCommand(id: SessionID): string | null {
     const s = this.sessions.find((x) => x.id === id);
 
     if (!s) {
@@ -603,7 +549,7 @@ export class SessionManager {
     return this.findAdapter(s.agent)?.buildResumeCommand(s.cwd, s.agentSessionID) ?? null;
   }
 
-  attach(id: string) {
+  attach(id: SessionID) {
     const s = this.sessions.find((x) => x.id === id);
 
     if (!s) {
@@ -612,8 +558,7 @@ export class SessionManager {
 
     s.unread = false;
     s.lastAttachedAt = Date.now();
-
-    this.writeFleet();
+    void this.writeFleet();
 
     // Attaching answers the attention request: a still-pending prompt
     // re-flags it via the next notification.
@@ -626,7 +571,7 @@ export class SessionManager {
     this.emitChange();
   }
 
-  ack(id: string) {
+  ack(id: SessionID) {
     const s = this.sessions.find((x) => x.id === id);
 
     if (s) {
@@ -638,7 +583,10 @@ export class SessionManager {
     this.emitChange();
   }
 
-  kill(id: string) {
+  // A kill's response is the caller's cue that the session is safely
+  // archived, so the write it depends on must land before that response
+  // goes out.
+  async kill(id: SessionID): Promise<void> {
     const s = this.sessions.find((x) => x.id === id);
 
     if (!s) {
@@ -663,7 +611,8 @@ export class SessionManager {
       this.onEvent('removed', s);
     }
 
-    this.writeFleet();
+    await this.writeFleet();
+
     this.emitChange();
   }
 
@@ -691,26 +640,31 @@ export class SessionManager {
 
   // Persisted continuously so a crash (or quit) leaves a restorable fleet.
   // Deliberate kills rewrite the file; unexpected session/atc deaths do not,
-  // so the last known fleet survives for `R` restore.
-  writeFleet() {
+  // so the last known fleet survives for `R` restore. Sessions whose
+  // terminal is gone persist as exited entries, so the killed archive
+  // survives a daemon restart too.
+  async writeFleet(): Promise<void> {
     const fleet: FleetEntry[] = [];
 
     for (const s of this.sessions) {
+      if (s.agentSessionID === undefined) {
+        continue;
+      }
+
       const live = s.pty !== null || (s.kind === 'headless' && s.state !== 'exited');
 
-      if (live && s.agentSessionID !== undefined) {
-        fleet.push({
-          name: s.name,
-          cwd: s.cwd,
-          agentSessionID: s.agentSessionID,
-          agent: s.agent,
-          ...(s.pinned ? { pinned: true } : {}),
-          lastAttachedAt: s.lastAttachedAt,
-        });
-      }
+      fleet.push({
+        name: s.name,
+        cwd: s.cwd,
+        agentSessionID: s.agentSessionID,
+        agent: s.agent,
+        ...(s.pinned ? { pinned: true } : {}),
+        lastAttachedAt: s.lastAttachedAt,
+        ...(live ? {} : { exited: true }),
+      });
     }
 
-    this.store.writeFleet(fleet);
+    await this.store.writeFleet(fleet);
   }
 
   countStates() {

package/src/{start-headless-run.ts → daemon/start-headless-run.ts}

@@ -1,6 +1,7 @@
 import { query } from '@anthropic-ai/claude-agent-sdk';
-import { collectCleanEnv } from './collect-clean-env';
-import { isRecord } from './report';
+import type { AgentSessionID } from '../shared/agent-session-id';
+import { collectCleanEnv } from '../shared/collect-clean-env';
+import { isRecord } from '../shared/report';
 
 const PERMISSION_MODES = [
   'default',
@@ -14,8 +15,9 @@ const PERMISSION_MODES = [
 interface HeadlessRunOptions {
   readonly cwd: string;
   readonly prompt: string;
-  readonly resume?: string;
+  readonly resume?: AgentSessionID;
   readonly permissionMode?: string;
+  readonly settings?: string;
 }
 
 interface HeadlessRunHooks {
@@ -56,6 +58,10 @@ export function startHeadlessRun(
           },
           ...(opts.resume === undefined ? {} : { resume: opts.resume }),
           ...(mode === undefined ? {} : { permissionMode: mode }),
+
+          // The same generated file the terminal spawn passes, so the turn
+          // runs against the session's own backend and instrumentation.
+          ...(opts.settings === undefined ? {} : { extraArgs: { settings: opts.settings } }),
         },
       });
 

package/src/daemon/start-headless-turn.ts

@@ -0,0 +1,57 @@
+import type { SessionID } from '../shared/session-id';
+import type { SessionRuntime } from './session-runtime';
+import type { SessionManager } from './sessions';
+
+/**
+ * Starts one headless turn for a session: finds its adapter's headless
+ * runner, wires the run's output and completion into the session manager,
+ * and records the live handle on the session's runtime. Returns false
+ * without starting anything when the session is unknown, its agent has no
+ * headless runner, or a turn is already running.
+ */
+export function startHeadlessTurn(
+  mgr: SessionManager,
+  findRuntime: (sessionID: SessionID) => SessionRuntime | undefined,
+  sessionID: SessionID,
+  prompt: string,
+): boolean {
+  const s = mgr.sessions.find((x) => x.id === sessionID);
+  const runner = s === undefined ? null : (mgr.findAdapter(s.agent)?.headlessRunner ?? null);
+  const runtime = findRuntime(sessionID);
+
+  if (s === undefined || runner === null || runtime === undefined || runtime.headlessRun !== null) {
+    return false;
+  }
+
+  mgr.updateSurfaceState(sessionID, 'running', 'headless turn running');
+
+  const handle = runner(
+    {
+      cwd: s.cwd,
+      prompt,
+      ...(s.agentSessionID === undefined ? {} : { resume: s.agentSessionID }),
+      permissionMode: 'auto',
+    },
+    {
+      onOutput: (text) => {
+        mgr.onOutput(s, text);
+      },
+      onDone: (summary) => {
+        runtime.headlessRun = null;
+
+        const doneMsg = summary === '' ? 'headless turn done' : summary;
+
+        mgr.updateSurfaceState(sessionID, 'done', doneMsg);
+      },
+      onNeedsYou: (msg) => {
+        runtime.headlessRun = null;
+
+        mgr.updateSurfaceState(sessionID, 'needs_you', msg);
+      },
+    },
+  );
+
+  runtime.headlessRun = handle;
+
+  return true;
+}

package/src/hook-report.ts

@@ -1,5 +1,5 @@
-import { normalizeHookEventName } from './normalize-hook-event';
-import { isRecord, sendReport } from './report';
+import { normalizeHookEventName } from './agents/normalize-hook-event';
+import { isRecord, sendReport } from './shared/report';
 
 /**
  * Runs as a hook inside wrangled sessions. Reads the hook event from stdin

package/src/mcp-server.ts

@@ -1,6 +1,8 @@
-import { bootDaemonClient } from './boot-daemon';
-import { DaemonError } from './daemon-error';
-import { isRecord } from './report';
+import { z } from 'zod';
+import { bootDaemonClient } from './client/boot-daemon';
+import { DaemonError } from './protocol/daemon-error';
+import { REQUEST_PARAM_SCHEMAS } from './protocol/request-param-schemas';
+import { isRecord } from './shared/report';
 
 // The slice of the daemon client the tool handlers need.
 interface FleetCaller {
@@ -18,20 +20,32 @@ interface MCPTool {
   readonly inputSchema: Readonly<Record<string, unknown>>;
 }
 
-const NO_INPUT: Readonly<Record<string, unknown>> = {
-  type: 'object',
-  properties: {},
-  additionalProperties: false,
-};
+const NO_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(z.strictObject({}));
 
-const SESSION_INPUT: Readonly<Record<string, unknown>> = {
-  type: 'object',
-  properties: {
-    session: { type: 'string', description: 'The atc session id, from atc_session_list' },
-  },
-  required: ['session'],
-  additionalProperties: false,
-};
+/**
+ * The session id shape MCP tool schemas require: present and described.
+ * The wire request schemas below share a defaulted-session shape instead,
+ * since they tolerate an absent session by defaulting it to an empty
+ * string.
+ */
+const SESSION_ID_BASE = z.object({
+  session: z.string().describe('The atc session id, from atc_session_list'),
+});
+
+const SESSION_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(SESSION_ID_BASE.strict());
+const SPAWN_SCHEMA = REQUEST_PARAM_SCHEMAS['session.spawn'];
+
+const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
+  z.strictObject({
+    cwd: SPAWN_SCHEMA.shape.cwd.describe('Absolute path of the working directory'),
+    name: SPAWN_SCHEMA.shape.name.describe('Session name; defaults to the directory basename'),
+    prompt: SPAWN_SCHEMA.shape.prompt.describe('First message for the session'),
+    agent: SPAWN_SCHEMA.shape.agent.describe(
+      'Which registered agent id to spawn; defaults to claude',
+    ),
+  }),
+  { io: 'input' },
+);
 
 const TOOLS: readonly MCPTool[] = [
   {
@@ -43,22 +57,8 @@ const TOOLS: readonly MCPTool[] = [
   {
     name: 'atc_session_spawn',
     description:
-      '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,
-    },
+      'Spawn a new session in a directory. Optional agent is an agent id the daemon has registered, such as claude, grok, or codex; omitted agent is always Claude, never the TUI last-used value. An unregistered id is rejected. Returns the new session descriptor. Give it a prompt to start it working immediately.',
+    inputSchema: SPAWN_INPUT,
   },
   {
     name: 'atc_session_input',
@@ -243,22 +243,11 @@ async function runTool(
     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 }
-          : {}),
+        ...(rawAgent === undefined ? {} : { agent: rawAgent }),
         cols: 100,
         rows: 30,
       });