@zgeoff/atc 0.1.0

package/src/mcp-server.ts

@@ -0,0 +1,272 @@
+import { bootDaemonClient } from './boot-daemon';
+import { DaemonError } from './daemon-error';
+import { isRecord } from './report';
+
+// The slice of the daemon client the tool handlers need.
+interface FleetCaller {
+  readonly sendRequest: (
+    m: string,
+    p?: Readonly<Record<string, unknown>>,
+  ) => Promise<Readonly<Record<string, unknown>>>;
+}
+
+const PROTOCOL_FALLBACK = '2025-06-18';
+
+interface MCPTool {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+
+const NO_INPUT: Readonly<Record<string, unknown>> = {
+  type: 'object',
+  properties: {},
+  additionalProperties: false,
+};
+
+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,
+};
+
+const TOOLS: readonly MCPTool[] = [
+  {
+    name: 'atc_session_list',
+    description:
+      'List every session the atc daemon hosts: id, name, working directory, state (running, needs_you, done, exited), unread flag, and last activity.',
+    inputSchema: NO_INPUT,
+  },
+  {
+    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.',
+    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' },
+      },
+      required: ['cwd'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'atc_session_input',
+    description:
+      'Type a line of text into a running session, as if the operator typed it and pressed enter. Use it to answer a session that is waiting on input.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session: { type: 'string', description: 'The atc session id' },
+        text: { type: 'string', description: 'The line to type; a newline is appended' },
+      },
+      required: ['session', 'text'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'atc_session_kill',
+    description: 'Kill a session. A second kill on a dead session removes it from the list.',
+    inputSchema: SESSION_INPUT,
+  },
+  {
+    name: 'atc_session_ack',
+    description: 'Clear a session unread flag without attaching to it.',
+    inputSchema: SESSION_INPUT,
+  },
+  {
+    name: 'atc_resume_command',
+    description:
+      'Build the shell command that reopens a session outside atc (cd into its directory and claude --resume its id).',
+    inputSchema: SESSION_INPUT,
+  },
+  {
+    name: 'atc_dirs_list',
+    description: 'List directories sessions were previously spawned from, most recent first.',
+    inputSchema: NO_INPUT,
+  },
+];
+
+/**
+ * An MCP server over stdio bridging to the atc daemon: any MCP client —
+ * including a wrangled session — can list, spawn, and drive the fleet.
+ * stdout carries only JSON-RPC lines; the daemon is booted on demand.
+ */
+export async function runMCPServer(build: string): Promise<void> {
+  const client = await bootDaemonClient();
+
+  const decoder = new TextDecoder('utf-8');
+
+  let buffer = '';
+
+  for await (const chunk of Bun.stdin.stream()) {
+    buffer += decoder.decode(chunk, { stream: true });
+
+    const lines = buffer.split('\n');
+
+    buffer = lines.pop() ?? '';
+
+    for (const line of lines) {
+      if (line.trim() === '') {
+        continue;
+      }
+
+      await applyRPCLine(client, build, line);
+    }
+  }
+
+  client.stop();
+}
+
+async function applyRPCLine(client: FleetCaller, build: string, line: string): Promise<void> {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return;
+  }
+
+  if (!isRecord(parsed) || typeof parsed['method'] !== 'string') {
+    return;
+  }
+
+  const method = parsed['method'];
+  const id = parsed['id'];
+  const params = isRecord(parsed['params']) ? parsed['params'] : {};
+
+  // Notifications carry no id and get no response.
+  if (id === undefined || id === null) {
+    return;
+  }
+
+  if (typeof id !== 'string' && typeof id !== 'number') {
+    return;
+  }
+
+  switch (method) {
+    case 'initialize': {
+      const requested = params['protocolVersion'];
+
+      sendResult(id, {
+        protocolVersion: typeof requested === 'string' ? requested : PROTOCOL_FALLBACK,
+        capabilities: { tools: {} },
+        serverInfo: { name: 'atc', version: build },
+      });
+
+      return;
+    }
+    case 'ping': {
+      sendResult(id, {});
+
+      return;
+    }
+    case 'tools/list': {
+      sendResult(id, { tools: TOOLS });
+
+      return;
+    }
+    case 'tools/call': {
+      await applyToolCall(client, id, params);
+
+      return;
+    }
+    default: {
+      sendError(id, -32_601, `unknown method '${method}'`);
+    }
+  }
+}
+
+async function applyToolCall(
+  client: FleetCaller,
+  id: string | number,
+  params: Readonly<Record<string, unknown>>,
+): Promise<void> {
+  const name = typeof params['name'] === 'string' ? params['name'] : '';
+  const args = isRecord(params['arguments']) ? params['arguments'] : {};
+
+  try {
+    const text = await runTool(client, name, args);
+
+    sendResult(id, { content: [{ type: 'text', text }] });
+  } catch (error) {
+    let msg = String(error);
+
+    if (error instanceof DaemonError) {
+      msg = `${error.code}: ${error.message}`;
+    } else if (error instanceof Error) {
+      msg = error.message;
+    }
+
+    sendResult(id, { content: [{ type: 'text', text: msg }], isError: true });
+  }
+}
+
+async function runTool(
+  client: FleetCaller,
+  name: string,
+  args: Readonly<Record<string, unknown>>,
+): Promise<string> {
+  switch (name) {
+    case 'atc_session_list': {
+      const ok = await client.sendRequest('session.list');
+
+      return JSON.stringify(ok['sessions'], null, 2);
+    }
+    case 'atc_session_spawn': {
+      const ok = await client.sendRequest('session.spawn', {
+        cwd: args['cwd'],
+        ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
+        ...(typeof args['prompt'] === 'string' ? { prompt: args['prompt'] } : {}),
+        cols: 100,
+        rows: 30,
+      });
+
+      return JSON.stringify(ok['session'], null, 2);
+    }
+    case 'atc_session_input': {
+      await client.sendRequest('session.input', {
+        session: args['session'],
+        d: `${typeof args['text'] === 'string' ? args['text'] : ''}\n`,
+      });
+
+      return 'sent';
+    }
+    case 'atc_session_kill': {
+      await client.sendRequest('session.kill', { session: args['session'] });
+
+      return 'killed';
+    }
+    case 'atc_session_ack': {
+      await client.sendRequest('session.ack', { session: args['session'] });
+
+      return 'acked';
+    }
+    case 'atc_resume_command': {
+      const ok = await client.sendRequest('session.resumeCommand', { session: args['session'] });
+
+      return typeof ok['command'] === 'string' ? ok['command'] : JSON.stringify(ok);
+    }
+    case 'atc_dirs_list': {
+      const ok = await client.sendRequest('dirs.list');
+
+      return JSON.stringify(ok['dirs'], null, 2);
+    }
+    default: {
+      throw new Error(`unknown tool '${name}'`);
+    }
+  }
+}
+
+function sendResult(id: string | number, result: Readonly<Record<string, unknown>>): void {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`);
+}
+
+function sendError(id: string | number, code: number, message: string): void {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } })}\n`);
+}

package/src/outbound-queue.ts

@@ -0,0 +1,85 @@
+// The slice of a Bun socket the queue needs; `write` returns bytes accepted.
+export interface SocketWriter {
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- a readonly view cannot satisfy Bun's BufferSource union; the queue never mutates chunks
+  readonly write: (data: Uint8Array) => number;
+}
+
+const encoder = new TextEncoder();
+
+/**
+ * Bounded outbound buffer for one socket. `socket.write()` returns bytes
+ * accepted and silently drops the rest, so every short write parks the
+ * remainder here and the socket's drain callback flushes it. A payload is
+ * never cut mid-line: once its first byte is on the wire, the rest is
+ * queued even past capacity, and only whole not-yet-started payloads are
+ * refused on overflow.
+ */
+export class OutboundQueue {
+  private readonly socket: SocketWriter;
+
+  private readonly capacity: number;
+
+  private chunks: Uint8Array[] = [];
+
+  private queued = 0;
+
+  constructor(socket: SocketWriter, capacity = 2 * 1024 * 1024) {
+    this.socket = socket;
+    this.capacity = capacity;
+  }
+
+  get queuedBytes(): number {
+    return this.queued;
+  }
+
+  // false: the payload was refused whole because the queue is over capacity.
+  send(payload: string): boolean {
+    const bytes = encoder.encode(payload);
+
+    if (this.chunks.length > 0) {
+      if (this.queued + bytes.length > this.capacity) {
+        return false;
+      }
+
+      this.chunks.push(bytes);
+
+      this.queued += bytes.length;
+
+      return true;
+    }
+
+    const wrote = Math.max(this.socket.write(bytes), 0);
+
+    if (wrote < bytes.length) {
+      const rest = bytes.subarray(wrote);
+
+      this.chunks.push(rest);
+
+      this.queued += rest.length;
+    }
+
+    return true;
+  }
+
+  drain(): void {
+    while (this.chunks.length > 0) {
+      const [head] = this.chunks;
+
+      if (head === undefined) {
+        return;
+      }
+
+      const wrote = Math.max(this.socket.write(head), 0);
+
+      this.queued -= wrote;
+
+      if (wrote < head.length) {
+        this.chunks[0] = head.subarray(wrote);
+
+        return;
+      }
+
+      this.chunks.shift();
+    }
+  }
+}

package/src/permission-registry.ts

@@ -0,0 +1,104 @@
+export interface PermissionRequest {
+  readonly id: string;
+  readonly sessionID: string;
+  readonly message: string;
+  readonly respondable: boolean;
+}
+
+export type AnswerResult = 'ok' | 'already_answered' | 'unsupported' | 'unknown';
+
+interface PendingRequest {
+  readonly req: PermissionRequest;
+  readonly timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Pending permission requests with first-response-wins arbitration. The
+ * first answer resolves a request and every later answer reports
+ * already_answered; an unanswered request times out to deny; requests that
+ * stop mattering (the session was answered directly or died) resolve as
+ * dismissed. Resolution always reaches the callbacks exactly once.
+ */
+export class PermissionRegistry {
+  onRequested: (req: PermissionRequest) => void = () => {};
+
+  onResolved: (id: string, decision: string) => void = () => {};
+
+  private readonly timeoutMs: number;
+
+  private readonly pending = new Map<string, PendingRequest>();
+
+  private readonly resolved = new Set<string>();
+
+  private counter = 0;
+
+  constructor(timeoutMs = 60_000) {
+    this.timeoutMs = timeoutMs;
+  }
+
+  open(sessionID: string, message: string, respondable: boolean): PermissionRequest {
+    const id = `p${++this.counter}`;
+    const req: PermissionRequest = { id, sessionID, message, respondable };
+
+    const timer = setTimeout(() => {
+      this.removeRequest(id, 'deny');
+    }, this.timeoutMs);
+
+    this.pending.set(id, { req, timer });
+    this.onRequested(req);
+
+    return req;
+  }
+
+  answer(id: string, decision: string): AnswerResult {
+    if (this.resolved.has(id)) {
+      return 'already_answered';
+    }
+
+    const entry = this.pending.get(id);
+
+    if (entry === undefined) {
+      return 'unknown';
+    }
+
+    if (!entry.req.respondable) {
+      return 'unsupported';
+    }
+
+    this.removeRequest(id, decision);
+
+    return 'ok';
+  }
+
+  answerAll(sessionID: string, decision: string): void {
+    for (const [id, entry] of this.pending) {
+      if (entry.req.sessionID === sessionID) {
+        this.removeRequest(id, decision);
+      }
+    }
+  }
+
+  private removeRequest(id: string, decision: string): void {
+    const entry = this.pending.get(id);
+
+    if (entry === undefined) {
+      return;
+    }
+
+    clearTimeout(entry.timer);
+
+    this.pending.delete(id);
+    this.resolved.add(id);
+
+    // The resolved set only exists to tell already_answered from unknown;
+    // cap it so a long-lived daemon cannot grow it without bound.
+    if (this.resolved.size > 1000) {
+      for (const oldest of this.resolved) {
+        this.resolved.delete(oldest);
+        break;
+      }
+    }
+
+    this.onResolved(id, decision);
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,129 @@
+import { isRecord } from './report';
+
+/**
+ * The daemon/client wire dialect: NDJSON over a unix socket, one JSON object
+ * 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;
+
+// Control lines are capped before buffering; PTY output is split into chunks
+// so a queued response is delayed by at most one chunk.
+export const MAX_LINE = 1_048_576;
+export const MAX_CHUNK = 65_536;
+
+const ERROR_CODES = [
+  'protocol_mismatch',
+  'unauthorized',
+  'unknown_method',
+  'bad_args',
+  'no_such_session',
+  'session_dead',
+  'unsupported',
+  'already_answered',
+  'too_slow',
+  'internal',
+] as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[number];
+
+interface ProtocolError {
+  readonly code: ErrorCode;
+  readonly msg: string;
+}
+
+export interface RequestMsg {
+  readonly v: number;
+  readonly id: number;
+  readonly m: string;
+  readonly p?: Readonly<Record<string, unknown>>;
+}
+
+export interface ResponseMsg {
+  readonly v: number;
+  readonly id: number;
+  readonly ok?: Readonly<Record<string, unknown>>;
+  readonly err?: ProtocolError;
+}
+
+export interface EventMsg {
+  readonly v: number;
+  readonly ev: string;
+  readonly [field: string]: unknown;
+}
+
+export type DecodedMsg =
+  | { readonly kind: 'request'; readonly msg: RequestMsg }
+  | { readonly kind: 'response'; readonly msg: ResponseMsg }
+  | { readonly kind: 'event'; readonly msg: EventMsg }
+  | { readonly kind: 'malformed'; readonly reason: string };
+
+/**
+ * Classifies one NDJSON line. Unknown fields pass through untouched so
+ * additive evolution never breaks a peer; a line that parses but fits no
+ * message kind is malformed, and the caller closes the connection.
+ */
+export function decodeMessage(line: string): DecodedMsg {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return { kind: 'malformed', reason: 'not valid JSON' };
+  }
+
+  if (!isRecord(parsed) || typeof parsed['v'] !== 'number') {
+    return { kind: 'malformed', reason: 'missing v' };
+  }
+
+  if (typeof parsed['ev'] === 'string') {
+    return { kind: 'event', msg: { ...parsed, v: parsed['v'], ev: parsed['ev'] } };
+  }
+
+  if (typeof parsed['id'] !== 'number') {
+    return { kind: 'malformed', reason: 'missing id' };
+  }
+
+  if (typeof parsed['m'] === 'string') {
+    const p = parsed['p'];
+
+    return {
+      kind: 'request',
+      msg: {
+        v: parsed['v'],
+        id: parsed['id'],
+        m: parsed['m'],
+        ...(isRecord(p) ? { p } : {}),
+      },
+    };
+  }
+
+  const ok = parsed['ok'];
+  const err = parsed['err'];
+
+  if (isRecord(ok) || isProtocolError(err)) {
+    return {
+      kind: 'response',
+      msg: {
+        v: parsed['v'],
+        id: parsed['id'],
+        ...(isRecord(ok) ? { ok } : {}),
+        ...(isProtocolError(err) ? { err } : {}),
+      },
+    };
+  }
+
+  return { kind: 'malformed', reason: 'no m, ok, or err' };
+}
+
+export function encodeMessage(msg: EventMsg | RequestMsg | ResponseMsg): string {
+  return `${JSON.stringify(msg)}\n`;
+}
+
+function isProtocolError(value: unknown): value is ProtocolError {
+  return (
+    isRecord(value) &&
+    typeof value['msg'] === 'string' &&
+    ERROR_CODES.some((code) => code === value['code'])
+  );
+}

package/src/report.ts

@@ -0,0 +1,33 @@
+// Fire-and-forget delivery of one JSON line to the atc unix socket, used by
+// the hook and statusline commands running inside wrangled sessions. Never
+// throws: a dead socket must not break the session doing the reporting.
+async function sendLine(sock: string, line: string): Promise<void> {
+  const resolvers = Promise.withResolvers<void>();
+
+  await Bun.connect({
+    unix: sock,
+    socket: {
+      open(s) {
+        s.write(line);
+        s.end();
+      },
+      close() {
+        resolvers.resolve();
+      },
+      data() {},
+      error() {},
+    },
+  });
+
+  await resolvers.promise;
+}
+
+export async function sendReport(sock: string, line: string, timeoutMs: number): Promise<void> {
+  try {
+    await Promise.race([sendLine(sock, line), Bun.sleep(timeoutMs)]);
+  } catch {}
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/screen-model.ts

@@ -0,0 +1,48 @@
+import { SerializeAddon } from '@xterm/addon-serialize';
+import { Terminal } from '@xterm/headless';
+
+/**
+ * A per-session vt state machine: consumes every PTY byte continuously and
+ * renders the current screen as an ANSI replay string, so attaching a
+ * client is an instant repaint instead of a resize jiggle. Scrollback is
+ * capped aggressively — the model exists for the current screen, not
+ * history; transcripts on disk are the durable copy.
+ */
+export class ScreenModel {
+  private readonly term: Terminal;
+
+  private readonly serializer: SerializeAddon;
+
+  private flushed: Promise<void> = Promise.resolve();
+
+  constructor(cols: number, rows: number) {
+    this.term = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 300 });
+    this.serializer = new SerializeAddon();
+
+    this.term.loadAddon(this.serializer);
+  }
+
+  record(data: string): void {
+    this.flushed = new Promise((resolve) => {
+      this.term.write(data, () => {
+        resolve();
+      });
+    });
+  }
+
+  // The terminal parses asynchronously; the replay waits for every recorded
+  // byte to land in the buffer before serializing.
+  async renderReplay(): Promise<string> {
+    await this.flushed;
+
+    return this.serializer.serialize();
+  }
+
+  updateDims(cols: number, rows: number): void {
+    this.term.resize(cols, rows);
+  }
+
+  stop(): void {
+    this.term.dispose();
+  }
+}