Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
8.3 KB
Raw Blame
/**
 * Late writes: a turn's background processes still writing after the turn
 * ended (`cmd &`, `npm install &`, a watcher or a dev server writing a
 * build folder). When the next prompt arrives, its turn must start from the
 * workspace those writes leave, not from one taken while they were still
 * landing. lateWriters() finds the processes a turn left running in the
 * workspace (Linux /proc; elsewhere none are found and nothing is waited
 * for), and settleLateWriters() waits, at most until a cap measured from the
 * turn's end, for them to exit. The wait runs while the prompt is being
 * dispatched, and only when such a process is still running, so a user who
 * types for longer than the cap never waits. Identical in the CLI and the
 * desktop app.
 */
import { readdir, readFile, readlink } from "node:fs/promises";
import { sep } from "node:path";

/** How long after a turn ended its next prompt may wait for the turn's background processes. */
export const LATE_WRITES_CAP_MS = 10_000;
/** How often the processes are looked at again while waiting. */
export const LATE_WRITES_POLL_MS = 200;
/** At most this many processes are reported. */
const MAX_REPORTED = 16;
const MAX_COMMAND_CHARS = 120;
const START_SLACK_MS = 50;

export type LateWriter = { pid: number; command: string };

export type LateWritersInput = {
  /** The workspace: a process whose working directory is in it is a candidate. */
  root: string;
  /** When the turn started (epoch ms): older processes (a dev server from an earlier turn, the user's own shell) are not its. */
  since: number;
  /** Processes never waited for, with their descendants: this app, the engine. */
  exclude: readonly number[];
  /** Tests: the /proc directory and the platform. */
  proc?: string;
  platform?: NodeJS.Platform;
};

type ProcEntry = { pid: number; ppid: number; startedAt: number; uid: number | null; command: string };

/**
 * Boot time (epoch ms), for /proc/<pid>/stat start times: from /proc/uptime
 * (hundredths of a second; `btime` in /proc/stat is whole seconds, too coarse
 * for a job started within a second of its turn), else from `btime`.
 */
async function bootTime(proc: string): Promise<number | null> {
  try {
    const uptime = Number.parseFloat((await readFile(`${proc}/uptime`, "utf8")).split(" ")[0] ?? "");
    if (Number.isFinite(uptime) && uptime > 0) return Date.now() - uptime * 1000;
  } catch {
    // Older or restricted /proc: btime below.
  }
  try {
    const text = await readFile(`${proc}/stat`, "utf8");
    const match = /^btime (\d+)$/m.exec(text);
    return match ? Number(match[1]) * 1000 : null;
  } catch {
    return null;
  }
}

/** USER_HZ: 100 on every Linux the app runs on. */
const CLOCK_TICKS = 100;

async function procEntry(proc: string, pid: number, boot: number): Promise<ProcEntry | null> {
  try {
    const stat = await readFile(`${proc}/${pid}/stat`, "utf8");
    // `pid (comm) state ppid ...`: comm may hold spaces and parentheses; the fields follow the last `)`.
    const close = stat.lastIndexOf(")");
    const open = stat.indexOf("(");
    if (close < 0 || open < 0) return null;
    const fields = stat.slice(close + 2).split(" ");
    const ppid = Number(fields[1]);
    const ticks = Number(fields[19]);
    if (!Number.isFinite(ppid) || !Number.isFinite(ticks)) return null;
    // A zombie has exited: it writes nothing.
    if (fields[0] === "Z") return null;
    let uid: number | null = null;
    try {
      const status = await readFile(`${proc}/${pid}/status`, "utf8");
      const match = /^Uid:\s+(\d+)/m.exec(status);
      uid = match ? Number(match[1]) : null;
    } catch {
      uid = null;
    }
    let command = stat.slice(open + 1, close);
    try {
      const cmdline = (await readFile(`${proc}/${pid}/cmdline`, "utf8")).split("\0").filter(Boolean).join(" ");
      if (cmdline) command = cmdline;
    } catch {
      // The short name will do.
    }
    return { pid, ppid, startedAt: boot + (ticks * 1000) / CLOCK_TICKS, uid, command: command.slice(0, MAX_COMMAND_CHARS) };
  } catch {
    return null;
  }
}

function inside(root: string, path: string): boolean {
  const base = root.endsWith(sep) ? root : `${root}${sep}`;
  return path === root || path.startsWith(base);
}

/**
 * The processes a turn left running in the workspace: started since the turn
 * began, working in the workspace, owned by this user, and neither an
 * excluded process nor one of its descendants (the engine's own helpers, a
 * tool call still running). Empty off Linux, or when /proc cannot be read.
 */
export async function lateWriters(input: LateWritersInput): Promise<LateWriter[]> {
  const platform = input.platform ?? process.platform;
  if (platform !== "linux") return [];
  const proc = input.proc ?? "/proc";
  const boot = await bootTime(proc);
  if (boot === null) return [];
  let names: string[];
  try {
    names = await readdir(proc);
  } catch {
    return [];
  }
  const uid = typeof process.getuid === "function" ? process.getuid() : null;
  // Only a process working in the workspace is read in full (another user's cwd cannot even be read).
  const candidates: number[] = [];
  await Promise.all(names.filter((name) => /^\d+$/.test(name)).map(async (name) => {
    const pid = Number(name);
    if (pid === process.pid) return;
    try {
      if (inside(input.root, await readlink(`${proc}/${pid}/cwd`))) candidates.push(pid);
    } catch {
      // Gone, or not this user's.
    }
  }));
  if (candidates.length === 0) return [];
  const entries = new Map<number, ProcEntry | null>();
  const entryOf = async (pid: number): Promise<ProcEntry | null> => {
    if (!entries.has(pid)) entries.set(pid, await procEntry(proc, pid, boot));
    return entries.get(pid) ?? null;
  };
  const excluded = new Set(input.exclude.filter((pid) => Number.isSafeInteger(pid) && pid > 0));
  const excludedTree = async (pid: number): Promise<boolean> => {
    for (let current: number | undefined = pid, hops = 0; current !== undefined && current > 1 && hops < 64; hops += 1) {
      if (excluded.has(current)) return true;
      current = (await entryOf(current))?.ppid;
    }
    return false;
  };
  const found: LateWriter[] = [];
  for (const pid of candidates) {
    const entry = await entryOf(pid);
    // Start times are in clock ticks (10 ms): a job started right as the turn began may read a tick early.
    if (!entry || entry.startedAt < input.since - START_SLACK_MS) continue;
    if (uid !== null && entry.uid !== null && entry.uid !== uid) continue;
    if (await excludedTree(pid)) continue;
    found.push({ pid, command: entry.command });
  }
  found.sort((left, right) => left.pid - right.pid);
  return found.slice(0, MAX_REPORTED);
}

export type SettleResult = {
  /** How long the prompt waited. */
  waitedMs: number;
  /** No process of the turn was left running (or all of them exited within the cap). */
  settled: boolean;
  /** The processes found running when the wait began. */
  processes: LateWriter[];
};

/**
 * Waits for the processes the turn that ended at `endedAt` left running in the
 * workspace to exit, until `endedAt + capMs` at the latest (never past it,
 * whenever it is called). Returns at once when none runs. Never throws.
 */
export async function settleLateWriters(input: LateWritersInput & {
  endedAt: number;
  capMs?: number;
  pollMs?: number;
  now?: () => number;
  sleep?: (ms: number) => Promise<void>;
  signal?: AbortSignal;
}): Promise<SettleResult> {
  const now = input.now ?? Date.now;
  const sleep = input.sleep ?? ((ms: number) => new Promise<void>((resolvePromise) => setTimeout(resolvePromise, ms).unref?.()));
  const deadline = input.endedAt + (input.capMs ?? LATE_WRITES_CAP_MS);
  const started = now();
  let processes: LateWriter[];
  try {
    processes = await lateWriters(input);
  } catch {
    return { waitedMs: 0, settled: true, processes: [] };
  }
  if (processes.length === 0) return { waitedMs: now() - started, settled: true, processes };
  let running = processes;
  while (running.length > 0 && now() < deadline && !input.signal?.aborted) {
    await sleep(Math.min(input.pollMs ?? LATE_WRITES_POLL_MS, Math.max(0, deadline - now())));
    const pids = new Set(running.map((process) => process.pid));
    try {
      running = (await lateWriters(input)).filter((process) => pids.has(process.pid));
    } catch {
      running = [];
    }
  }
  return { waitedMs: now() - started, settled: running.length === 0, processes };
}