@bridge4dev/runner 0.46.1 → 0.47.0

package/dist/agent-cleanup.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { NATIVE_VERSIONS_DIR, nativeVersionsOnDisk } from './agent-install.js';
+import { log } from './log.js';
+/**
+ * Throwing away the Claude versions nobody will run again (Р12, §4.7).
+ *
+ * Anthropic's native installer keeps **every** version it has ever downloaded
+ * as a separate 200–330 MB executable in `~/.local/share/claude/versions/` and
+ * deletes none of them; the launcher on PATH is a symlink pointing at one. On
+ * this very dev server that was five copies and 1.4 GB with the disk 80 % full
+ * (гоча #414) — and stage D now moves the version forward by itself, so what
+ * used to grow by a file a month grows by a file a day.
+ *
+ * Three files are untouchable, and each is a different way to break a machine:
+ *
+ *  1. **whatever the launcher points at.** Delete it and `claude` on PATH is a
+ *     dangling symlink: no sessions, no sign-in, and nothing on the card
+ *     explaining it — `measureAgent` would report a probe failure, which stage 2
+ *     already knows is a state with no way out from the interface.
+ *  2. **the version a rollback would restore.** A failed install puts the
+ *     previous version back by pointing the launcher at its file, so «keep two»
+ *     is not an arbitrary number: it is current + the one behind it.
+ *  3. **a version some process is still executing.** Claude Code launches its
+ *     own helpers by its own path, and a session that started two updates ago is
+ *     running the third file from the end. Unlinking a mapped executable does
+ *     not kill it on Linux, but it does make every later `exec` of that path
+ *     fail — and the caller's own gate (sweep only when this runner is tracking
+ *     no sessions at all) cannot see a process somebody started by hand.
+ */
+/** Current + the one a rollback would restore. Р12 says two, and two it is. */
+export const KEEP_VERSIONS = 2;
+/**
+ * The versions directory, with every symlink in its path resolved.
+ *
+ * Everything this module compares against comes back already resolved —
+ * `realpathSync` on the launcher, `/proc/<pid>/exe` — so an unresolved path here
+ * would fail to match on any machine where a component of `$HOME` is a link, and
+ * fail in the direction that deletes files.
+ *
+ * Falls back to the joined path when the directory does not exist: the caller
+ * then simply finds nothing in it.
+ */
+function versionsDir(homeDir) {
+    const joined = path.join(homeDir, ...NATIVE_VERSIONS_DIR);
+    try {
+        return fs.realpathSync(joined);
+    }
+    catch {
+        return joined;
+    }
+}
+/**
+ * The version the launcher on PATH resolves to, or null.
+ *
+ * Read by resolving the symlink rather than by running `claude --version`: the
+ * question is «which FILE», and this runs on a timer where spawning a 300 MB
+ * binary would be a poor way to ask. `realpath` follows a chain of links, so a
+ * distribution that put its own wrapper in between still answers correctly.
+ */
+export function currentNativeVersion(homeDir) {
+    const launcher = path.join(homeDir, '.local', 'bin', 'claude');
+    try {
+        const resolved = fs.realpathSync(launcher);
+        // BOTH sides resolved, or the comparison fails open. `realpathSync` on the
+        // launcher gives a fully-resolved path, so a plain `path.join` on this side
+        // would not match the moment any component of it is a symlink — `/home`
+        // pointing elsewhere, or a home directory on a mounted volume. The failure
+        // is silent and in the dangerous direction: «not one of ours» means «not
+        // protected», and the file the launcher points at gets deleted.
+        const dir = versionsDir(homeDir);
+        const relative = path.relative(dir, resolved);
+        // Inside the versions directory and one level down, or it is not one of
+        // these files at all — a `claude` that resolves to /usr/bin is somebody
+        // else's install and this sweep has no business near it.
+        return relative && !relative.startsWith('..') && !relative.includes(path.sep) ? relative : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Version files at least one live process is executing right now, best effort.
+ *
+ * `/proc/<pid>/exe` is a symlink to the executable's real path, so this is an
+ * exact answer for every process this user may look at — and an empty answer on
+ * a platform without `/proc`. Unreadable entries are SKIPPED rather than treated
+ * as a match: another user's process cannot be running a file out of this user's
+ * home, and refusing to sweep whenever `/proc` holds anything opaque would mean
+ * never sweeping on a busy machine.
+ */
+export function versionsInUse(homeDir) {
+    // Resolved for the same reason as above: `/proc/<pid>/exe` reads back a fully
+    // resolved path, and comparing it against an unresolved directory would
+    // quietly protect nothing.
+    const dir = versionsDir(homeDir);
+    const busy = new Set();
+    let pids;
+    try {
+        pids = fs.readdirSync('/proc').filter((name) => /^\d+$/.test(name));
+    }
+    catch {
+        return busy;
+    }
+    for (const pid of pids) {
+        let target;
+        try {
+            target = fs.readlinkSync(path.join('/proc', pid, 'exe'));
+        }
+        catch {
+            continue; // gone between readdir and readlink, or not ours to look at
+        }
+        // A deleted-but-mapped executable reads back as `<path> (deleted)`.
+        const file = target.replace(/ \(deleted\)$/, '');
+        if (path.dirname(file) === dir)
+            busy.add(path.basename(file));
+    }
+    return busy;
+}
+/**
+ * Sweep, and say what happened.
+ *
+ * Never throws: this runs on a timer beside live sessions, and a permission
+ * error on one file must cost that file, not the daemon.
+ */
+export function pruneNativeClaudeVersions(options = {}) {
+    const homeDir = options.homeDir ?? process.env['HOME'] ?? os.homedir();
+    const keep = options.keep ?? KEEP_VERSIONS;
+    const dir = versionsDir(homeDir);
+    const result = { removed: [], freedBytes: 0, kept: [] };
+    // Newest first, and only names that ARE versions — the directory is the
+    // vendor's, and a stray file in it is not ours to delete.
+    const versions = nativeVersionsOnDisk(homeDir);
+    if (versions.length <= keep)
+        return result;
+    const current = (options.current ?? currentNativeVersion)(homeDir);
+    const busy = (options.inUse ?? versionsInUse)(homeDir);
+    const remove = options.remove ?? ((file) => fs.rmSync(file, { force: true }));
+    // The keep-list is «the newest N» UNION «the one in use» — computed as a set
+    // rather than by slicing, because the launcher can legitimately point at a
+    // version that is not the newest on disk (a rollback did exactly that), and
+    // slicing alone would then delete the file `claude` resolves to.
+    const survivors = new Set(versions.slice(0, keep));
+    if (current)
+        survivors.add(current);
+    for (const version of versions) {
+        if (survivors.has(version)) {
+            result.kept.push({
+                version,
+                reason: version === current ? 'the launcher points at it' : 'one of the newest',
+            });
+            continue;
+        }
+        if (busy.has(version)) {
+            result.kept.push({ version, reason: 'a process is running it' });
+            continue;
+        }
+        const file = path.join(dir, version);
+        // Measured BEFORE the unlink — afterwards there is nothing left to ask.
+        let size;
+        try {
+            size = fs.statSync(file).size;
+        }
+        catch {
+            // Vanished under us — the vendor's own installer may have tidied it.
+            continue;
+        }
+        try {
+            remove(file);
+            result.removed.push(version);
+            result.freedBytes += size;
+        }
+        catch (error) {
+            log.warn('agent-cleanup: could not remove an old Claude version', {
+                version,
+                error: String(error instanceof Error ? error.message : error),
+            });
+            result.kept.push({ version, reason: 'could not be removed' });
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=agent-cleanup.js.map

package/dist/agent-install.d.ts

@@ -0,0 +1,140 @@
+import { type AgentRuntime } from './agent-registry.js';
+import { type MeasuredAgentVersion } from './agent-versions.js';
+/**
+ * Installing and updating the agent CLIs from the dashboard (plan stage B).
+ *
+ * One command does both: «Install» and «Update» differ only in whether anything
+ * was there before. Like `self-update.ts` this runs software on someone else's
+ * machine, so it is written around its refusals rather than its happy path —
+ * but with three differences from updating the runner, and each one matters:
+ *
+ *  1. **The server never says WHAT to install.** The frame carries an agent key
+ *     from a closed list and a plain version triple; the package name, the
+ *     installer URL and the command are read from the registry compiled into
+ *     this build. A compromised API can pick the version, never the payload.
+ *  2. **The daemon does not restart.** Live sessions keep running on the file
+ *     they already opened, and the new version takes effect for the next one.
+ *     This is the whole point of the work: today the only way to move Claude
+ *     forward is reinstalling the runner, which kills every session on the box.
+ *  3. **Success is decided by running the binary, never by npm's exit code.**
+ *     Гоча #297: an optional platform package that fails to unpack still leaves
+ *     npm exiting 0, and both agents ship their real binary exactly that way.
+ */
+export interface AgentInstallOutcome {
+    ok: boolean;
+    /** Wire key of the agent, echoed back so a late reply can be attributed. */
+    agent: string;
+    /** What was installed before, or null when the agent was absent. */
+    fromVersion: string | null;
+    toVersion?: string;
+    detail?: string;
+    /** True when the install failed AND the previous version was put back. */
+    rolledBack?: boolean;
+}
+export type Exec = (file: string, args: string[], options: {
+    timeout: number;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export interface AgentInstallOptions {
+    /** Wire key from the closed registry list, e.g. `codex`. */
+    agent: string;
+    /** Plain `x.y.z`; anything else is refused before any work happens. */
+    version: string;
+    /**
+     * Allow installing a version older than the one on the machine. There is no
+     * door to this in the interface — it exists so a bad vendor release can be
+     * walked back by hand, and it leaves its own audit line.
+     */
+    allowDowngrade?: boolean;
+    /** Test seam. */
+    exec?: Exec;
+    /** Test seam: how the agent is measured before and after. */
+    measure?: (runtime: AgentRuntime) => Promise<MeasuredAgentVersion>;
+    /** Test seam: the installed runner package directory (defaults to autodetect). */
+    packageDir?: string | null;
+    /** Test seam: the daemon's home directory. */
+    homeDir?: string;
+    /** Test seam: free bytes on the filesystem a path lives on. */
+    freeBytes?: (target: string) => number | null;
+    /** Test seam: fetch the vendor's installer script to a local file. */
+    download?: (url: string, destination: string) => Promise<void>;
+    /** Test seam: re-scan for directories that appeared during the install. */
+    refreshPath?: () => void;
+}
+/**
+ * Anthropic's native installer keeps every version it has ever downloaded as a
+ * separate file here and switches a launcher between them; `claude install
+ * <version>` is how you move the launcher, and that is what makes a rollback
+ * possible at all for a `script`-kind agent.
+ *
+ * Deliberately NOT a registry field: the registry is mirrored character for
+ * character into `@devbridge/shared`, and today `script` has exactly one member.
+ * When a second one arrives (Antigravity ships a script installer too) this
+ * becomes a per-agent field and the mirror grows with it.
+ */
+export declare const NATIVE_VERSIONS_DIR: string[];
+/**
+ * npm and the vendor scripts need PATH, HOME and a writable cache; everything
+ * else is stripped so provider credentials never reach a child that touches the
+ * network, and a stray `npm_config_prefix` cannot redirect the install.
+ */
+declare function installEnv(homeDir: string): NodeJS.ProcessEnv;
+/**
+ * `--include=optional` is not a copy-paste slip next to C5, which takes the flag
+ * OFF the runner's own install. The two say the same thing about different
+ * packages: the runner no longer wants Claude's optional platform binary, while
+ * `@openai/codex` keeps its 320 MB executable in exactly such an optional
+ * package (`@openai/codex-linux-x64`). Dropping it here would install a shim
+ * that cannot run, and npm would still exit 0 — гоча #297, second helping.
+ *
+ * `--ignore-scripts` is safe and checked: neither agent package declares any
+ * lifecycle script.
+ */
+declare function npmInstallArgs(packageName: string, version: string, prefix: string | null): string[];
+/**
+ * The command a human runs when we will not: an agent someone else's package
+ * manager owns, or a machine this daemon cannot write to.
+ */
+export declare function manualAgentInstallCommand(runtime: AgentRuntime, version: string): string;
+/** Versions the native installer has on disk, newest first. */
+export declare function nativeVersionsOnDisk(homeDir: string): string[];
+/**
+ * Fetch the vendor's installer script to a file.
+ *
+ * `curl` rather than Node's `fetch`, and behind an outbound proxy that is the
+ * whole difference between working and not: undici reads no proxy from the
+ * environment, so a machine that reaches the internet only through
+ * `HTTPS_PROXY` failed here — while the script it was fetching would itself
+ * have reached the network perfectly well, because `curl` inside it does read
+ * the environment. Fixing one half and not the other would have been an
+ * improvement nobody could use.
+ *
+ * `curl` is not an extra dependency: the vendor's script runs it on the next
+ * line, so a machine without it cannot install this agent either way.
+ *
+ * Downloaded to a file and never piped into a shell, exactly as before — a
+ * truncated transfer then fails to parse instead of running half a script.
+ * `--fail` turns an HTTP error into a non-zero exit rather than an error page
+ * saved as an installer; `--proto =https` refuses a redirect that leaves TLS.
+ */
+declare function downloadToFile(url: string, destination: string, exec: Exec, env: NodeJS.ProcessEnv): Promise<void>;
+/**
+ * Install or update one agent CLI.
+ *
+ * Never throws: every failure comes back as an outcome, because the caller is a
+ * command handler whose reply is the only thing the dashboard will ever see.
+ */
+export declare function installAgent(options: AgentInstallOptions): Promise<AgentInstallOutcome>;
+export declare const AGENT_INSTALL_INTERNALS: {
+    INSTALL_TIMEOUT_MS: number;
+    MIN_FREE_BYTES: number;
+    downloadToFile: typeof downloadToFile;
+    installEnv: typeof installEnv;
+    nativeVersionsOnDisk: typeof nativeVersionsOnDisk;
+    npmInstallArgs: typeof npmInstallArgs;
+};
+export {};
+//# sourceMappingURL=agent-install.d.ts.map