@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/daemon/remote-control.js

@@ -0,0 +1,153 @@
+/**
+ * The remote-control service hosts (`hq daemon service remote-control` and
+ * `codex-remote-control`).
+ *
+ * Like the outpost runners, the command (`claude remote-control`, or the box's
+ * Codex runner) runs inside a detached tmux session so it has a terminal. This
+ * host process starts the session and watches it; the daemon supervises the
+ * host:
+ *
+ * - the session ends -> the host exits 1 and the daemon restarts it with
+ *   backoff (replacing the runner's `while true` loop and its watchdogs);
+ * - the daemon stops the host -> the host kills the session and exits 0;
+ * - a new version of the tool is installed (the updater, or the tool's own
+ *   auto-updater) -> once the session has been quiet for 10 minutes, or after
+ *   2 hours at the latest, the host kills the session and exits 0, and the
+ *   daemon starts it again on the new version. Reinstalling the same version
+ *   (a long-running Claude session's auto-updater does that every few
+ *   minutes) and hq-cli releases leave the session alone.
+ *
+ * The tmux server is a private socket (`-L hq-daemon`), so it never touches a
+ * user's own tmux sessions.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+const TMUX_SOCKET = "hq-daemon";
+export const TMUX_SESSION = "remote-control";
+export const CODEX_TMUX_SESSION = "codex-remote-control";
+export function remoteControlArgs(opts) {
+    const args = ["remote-control", "--name", opts.name, "--spawn=same-dir"];
+    if (opts.permissionMode)
+        args.push("--permission-mode", opts.permissionMode);
+    return args;
+}
+/**
+ * The session name a box's own runner script passes to `claude remote-control`
+ * (`--name outpost-1-2`), so taking the runner over keeps the name people see.
+ */
+export function runnerSessionName(script) {
+    const m = /remote-control\b[^\n]*?--name[= ]+"?([^\s"]+)"?/.exec(script);
+    return m ? m[1] : null;
+}
+/** How far above the binary to look for the package that installs it (bin/claude.exe sits one level down). */
+const PACKAGE_SEARCH_DEPTH = 3;
+/**
+ * Which version of a tool is installed: the npm package that installs the
+ * binary (`name@version`), else the binary's real path and size. A native
+ * install's link points at a versioned file, so its real path is the version.
+ * The mtime is left out on purpose: reinstalling the same version rewrites
+ * the file, and that must not restart the session. Null while the tool
+ * cannot be read.
+ */
+export function toolFingerprint(bin) {
+    let real;
+    let size;
+    try {
+        real = fs.realpathSync(bin);
+        size = fs.statSync(real).size;
+    }
+    catch {
+        return null;
+    }
+    let dir = path.dirname(real);
+    for (let i = 0; i < PACKAGE_SEARCH_DEPTH; i++) {
+        const version = packageVersionFor(dir, real);
+        if (version)
+            return version;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return `${real}:${size}`;
+}
+/** `name@version` when `<dir>/package.json` declares `real` as one of its bins. */
+function packageVersionFor(dir, real) {
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof pkg.name !== "string" || typeof pkg.version !== "string")
+        return null;
+    const bins = typeof pkg.bin === "string" ? [pkg.bin] : pkg.bin && typeof pkg.bin === "object" ? Object.values(pkg.bin) : [];
+    const installs = bins.some((b) => typeof b === "string" && path.resolve(dir, b) === real);
+    return installs ? `${pkg.name}@${pkg.version}` : null;
+}
+/**
+ * The tool a host runs: the path it was given, else the one found now. The
+ * daemon's plan leaves the path out, so a reinstall that briefly removes the
+ * tool's link cannot change the plan and restart the session.
+ */
+export function serviceTool(name, given, find) {
+    const tool = given?.trim() || find(name);
+    if (!tool)
+        throw new Error(`the ${name} CLI is not installed`);
+    return tool;
+}
+/** A tool updated on disk restarts its session once quiet this long... */
+export const IDLE_BEFORE_RESTART_MS = 10 * 60_000;
+/** ...or after this long, however busy the session is. */
+export const MAX_RESTART_WAIT_MS = 2 * 60 * 60_000;
+export async function runRemoteControlHost(deps) {
+    const tmux = (...args) => deps.run(deps.tmux, ["-L", TMUX_SOCKET, ...args]);
+    const killSession = () => tmux("kill-session", "-t", deps.session);
+    /** When the session last printed anything, in ms; null when tmux cannot say. */
+    const lastActivity = () => {
+        const r = tmux("display-message", "-p", "-t", deps.session, "#{window_activity}");
+        const secs = r.status === 0 ? Number.parseInt(r.stdout.trim(), 10) : Number.NaN;
+        return Number.isFinite(secs) ? secs * 1000 : null;
+    };
+    // A session left by an earlier host (for example after a crash) is replaced.
+    killSession();
+    const started = tmux("new-session", "-d", "-s", deps.session, "-x", "200", "-y", "50", "-c", deps.cwd, ...deps.argv);
+    if (started.status !== 0) {
+        deps.log(`could not start the tmux session: ${started.stderr.trim() || `tmux exited ${started.status}`}`);
+        return 1;
+    }
+    deps.log(`${deps.label} started in ${deps.cwd}`);
+    const startedWith = deps.binaryFingerprint();
+    let updatedAt = null;
+    for (;;) {
+        if (deps.signal.aborted) {
+            killSession();
+            deps.log(`stopped ${deps.label}`);
+            return 0;
+        }
+        if (tmux("has-session", "-t", deps.session).status !== 0) {
+            deps.log(`the ${deps.label} session ended`);
+            return 1;
+        }
+        const now = deps.now();
+        if (updatedAt === null) {
+            const current = deps.binaryFingerprint();
+            if (startedWith !== null && current !== null && current !== startedWith) {
+                updatedAt = now;
+                deps.log(`${deps.label}: the tool was updated; restarting onto it once the session is quiet (within 2 hours)`);
+            }
+        }
+        if (updatedAt !== null) {
+            const activity = lastActivity();
+            const quiet = activity !== null && now - activity >= IDLE_BEFORE_RESTART_MS;
+            if (quiet || now - updatedAt >= MAX_RESTART_WAIT_MS) {
+                killSession();
+                deps.log(`${deps.label}: restarting onto the updated tool${quiet ? "" : " (the session stayed busy for 2 hours)"}`);
+                return 0;
+            }
+        }
+        await deps.sleep(deps.pollMs);
+    }
+}
+//# sourceMappingURL=remote-control.js.map

package/dist/lib/daemon/requests.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Control requests from `hq daemon restart|trigger`, `hq bot start|stop` and the
+ * updater service to the running supervisor.
+ * Each request is one JSON file in ~/.hq/daemon/requests/; the supervisor
+ * polls the folder, applies requests oldest first, and deletes them. Files
+ * keep this working the same way on macOS, Linux and Windows.
+ */
+export type ControlRequest = {
+    action: "restart";
+    unit?: string;
+} | {
+    action: "trigger";
+    unit: string;
+} | {
+    action: "stop";
+    unit: string;
+}
+/** Re-read persisted configuration and apply any changed blocks immediately. */
+ | {
+    action: "reconcile";
+}
+/** Restart the whole daemon, for example after the updater installed a new CLI. */
+ | {
+    action: "restart-daemon";
+};
+export declare function writeControlRequest(dir: string, request: ControlRequest, now?: () => number): string;
+export declare function takeControlRequests(dir: string): ControlRequest[];
+//# sourceMappingURL=requests.d.ts.map

package/dist/lib/daemon/requests.js

@@ -0,0 +1,65 @@
+/**
+ * Control requests from `hq daemon restart|trigger`, `hq bot start|stop` and the
+ * updater service to the running supervisor.
+ * Each request is one JSON file in ~/.hq/daemon/requests/; the supervisor
+ * polls the folder, applies requests oldest first, and deletes them. Files
+ * keep this working the same way on macOS, Linux and Windows.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ensurePrivateDir } from "./paths.js";
+function isControlRequest(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    if (v.action === "restart")
+        return v.unit === undefined || typeof v.unit === "string";
+    if (v.action === "trigger" || v.action === "stop")
+        return typeof v.unit === "string";
+    if (v.action === "restart-daemon")
+        return true;
+    if (v.action === "reconcile")
+        return true;
+    return false;
+}
+// Orders requests written by one process within the same millisecond; the
+// random part only keeps names from different processes apart.
+let sequence = 0;
+export function writeControlRequest(dir, request, now = Date.now) {
+    ensurePrivateDir(dir);
+    sequence = (sequence + 1) % 1_000_000;
+    const name = `${String(now()).padStart(15, "0")}-${String(sequence).padStart(6, "0")}-${crypto.randomBytes(4).toString("hex")}.json`;
+    const file = path.join(dir, name);
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(request), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    return file;
+}
+export function takeControlRequests(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith(".json")).sort();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const requests = [];
+    for (const name of names) {
+        const file = path.join(dir, name);
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            parsed = null;
+        }
+        fs.rmSync(file, { force: true });
+        if (isControlRequest(parsed))
+            requests.push(parsed);
+    }
+    return requests;
+}
+//# sourceMappingURL=requests.js.map

package/dist/lib/daemon/run.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `hq daemon run` — wires the supervisor to real processes, files and signals.
+ *
+ * Each reconcile re-reads the config and re-probes the host (bots, sign-in,
+ * legacy units, the desktop app), so enabling a service, creating a bot, or
+ * signing in takes effect without restarting the daemon.
+ */
+import { type UnitPlan } from "./catalog.js";
+import { type LegacyUnit } from "./legacy.js";
+import { type MachineType } from "./machine-type.js";
+import { type HostApp } from "./supervisor.js";
+export declare const LOG_ROTATE_BYTES: number;
+/** Exit code for "restart me": non-zero so every service manager relaunches (Windows tasks only restart on failure). */
+export declare const RESTART_EXIT_CODE = 75;
+export interface RunDaemonOptions {
+    foreground?: boolean;
+    /** Started by the OS unit, which relaunches the daemon whenever it exits. */
+    managed?: boolean;
+    /** The app that runs this daemon as its child (it relaunches the daemon on RESTART_EXIT_CODE when also managed). */
+    host?: HostApp;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    nodeBinary: string;
+    hqBinary: string;
+}
+export declare function resolveSyncRunnerPath(): string | null;
+/** The hosted desktop app uses this env value when planning daemon services. */
+export declare function daemonInstantSyncEnabled(env: NodeJS.ProcessEnv, configured?: boolean): boolean;
+export declare function listLocalBots(root?: string): string[];
+export declare function windowsTaskExists(taskName: string): boolean;
+export declare function probeLegacyUnits(platform: NodeJS.Platform, home: string): LegacyUnit[];
+/** Absolute path of `name` on PATH, or null. */
+export declare function findOnPath(name: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * A tool the login user installed (~/.local/bin, ~/.npm-global/bin,
+ * ~/.grok/bin) before anything on PATH, so a box runs and updates the user's
+ * own copy instead of one root installed under /usr.
+ */
+export declare function findUserBinary(name: string, env: NodeJS.ProcessEnv, home: string): string | null;
+/** This CLI is a global package install the updater can replace (not a dev checkout or a project dependency). */
+export declare function cliSelfUpdatable(): boolean;
+/** The HQ desktop app process is running here (it runs its own sync). */
+export declare function desktopAppRunning(platform: NodeJS.Platform): boolean;
+/** A parent (the OS unit, or the app hosting the daemon) starts the daemon again after it exits with RESTART_EXIT_CODE. */
+export declare function restartsForParent(opts: {
+    managed?: boolean;
+    host?: HostApp;
+}): boolean;
+/**
+ * The desktop app runs sync itself, so the daemon's sync unit waits. When the
+ * app hosts the daemon it has handed sync over, and the daemon runs it.
+ */
+export declare function desktopAppManagesSync(opts: {
+    machineType: MachineType;
+    host?: HostApp;
+    legacy: readonly LegacyUnit[];
+    appRunning: () => boolean;
+}): boolean;
+/** Copy-and-truncate, so children appending with O_APPEND keep writing to the live file. */
+export declare function rotateLogs(logsDir: string, maxBytes?: number): number;
+/**
+ * Environment for one service process. The CLI's own update check is off:
+ * a child that updates itself exits 0 and asks to be rerun, which would leave
+ * an on-failure unit down. The daemon's updater handles CLI updates.
+ */
+export declare function unitProcessEnv(base: NodeJS.ProcessEnv, unit: UnitPlan): NodeJS.ProcessEnv;
+/**
+ * A systemd system unit starts the daemon as the login user without the
+ * variables a login session sets, so `systemctl --user` from its services
+ * cannot find the user bus ("Failed to connect to bus: No medium found").
+ * Point them at the user's runtime dir when it exists and nothing set one.
+ */
+export declare function withUserRuntimeDir(env: NodeJS.ProcessEnv, host: {
+    platform: NodeJS.Platform;
+    uid: number;
+    exists: (dir: string) => boolean;
+}): NodeJS.ProcessEnv;
+export declare function runDaemon(opts: RunDaemonOptions): Promise<number>;
+//# sourceMappingURL=run.d.ts.map