@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/proc/readiness.js

@@ -0,0 +1,219 @@
+/**
+ * Readiness detection (background-service-supervision §3.5).
+ *
+ * Two detectors, raced, first one wins:
+ *
+ *  - the URL detector, which is PURE and therefore testable without a socket;
+ *  - the port probe, which is one TCP connect and only runs when the command
+ *    text named a port.
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * EVERY TIMER AND SOCKET HERE IS `unref()`d (I-3). Readiness detection must
+ * never be the reason the CLI does not exit; only the child processes themselves
+ * hold the loop open, and they are reaped on exit.
+ */
+import net from 'node:net';
+import { PROC_LIMITS } from './limits.js';
+/**
+ * A loopback/wildcard `http(s)` URL, with an optional port and path.
+ *
+ * ONE ANCHORED SOURCE OF TRUTH, and written out rather than assembled, because
+ * the obvious shorthand is not a regex at all: `[::1]` inside a pattern is a
+ * CHARACTER CLASS matching `:` or `1`, and unescaped dots match any character.
+ * Both mistakes read as correct.
+ */
+export const READY_URL_RE = /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]|::1)(?::(\d{1,5}))?(\/\S*)?/i;
+/**
+ * Servers that announce a bare port instead of a URL.
+ *
+ * A SEPARATE, SMALLER LIST rather than more alternation in the URL pattern: what
+ * these produce is a PORT and no URL, which is a different result shape and a
+ * different confirmation path (the probe must succeed before anything flips).
+ */
+const PORT_PHRASES = Object.freeze([
+    /listening on (?:port )?(\d{2,5})\b/i,
+    /server running at .*?:(\d{2,5})\b/i,
+    /started server on .*?:(\d{2,5})\b/i,
+    /\bLocal:\s+\S*?:(\d{2,5})\b/i,
+]);
+/**
+ * Normalise a wildcard/IPv6-loopback host to something clickable.
+ *
+ * `0.0.0.0` means "every interface", which a browser cannot open; `::1` and
+ * `[::1]` are correct but unfamiliar. All three become `127.0.0.1`.
+ */
+export function normalizeHost(url) {
+    return url
+        .replace(/:\/\/0\.0\.0\.0/i, '://127.0.0.1')
+        .replace(/:\/\/\[::1\]/i, '://127.0.0.1')
+        .replace(/:\/\/::1/i, '://127.0.0.1');
+}
+/**
+ * The first readiness candidate in `rows`, or `undefined`.
+ *
+ * A MATCH IS A CANDIDATE, NOT A VERDICT (P2-2). A loopback URL printed in a
+ * banner or a `--help` blurb appears BEFORE anything binds, and a bare pattern
+ * would call that service ready in the first 40 ms. Two guards make the trade
+ * explicit, and neither lives here:
+ *
+ *   1. only rows emitted AFTER spawn are scanned (the ring starts empty, so this
+ *      is free), and
+ *   2. when the match yields a PORT, `ReadinessWatcher` confirms with one TCP
+ *      connect before the status flips.
+ *
+ * When the match yields no port the URL is accepted as-is: there is nothing to
+ * probe, and a hostname-only loopback URL in a banner is rare enough to trade
+ * against the complexity of guessing 80 vs 443.
+ */
+export function detectReadyUrl(rows) {
+    for (const row of rows) {
+        const m = READY_URL_RE.exec(row);
+        if (m) {
+            const url = normalizeHost(m[0]);
+            const port = m[1] ? Number.parseInt(m[1], 10) : undefined;
+            return port === undefined ? { url } : { url, port };
+        }
+    }
+    for (const row of rows) {
+        for (const re of PORT_PHRASES) {
+            const m = re.exec(row);
+            if (!m || !m[1])
+                continue;
+            const port = Number.parseInt(m[1], 10);
+            if (Number.isFinite(port) && port > 0 && port <= 65535)
+                return { port };
+        }
+    }
+    return undefined;
+}
+/**
+ * One TCP connect. Resolves `true` when something answered.
+ *
+ * Never rejects, and the socket is destroyed on every path — a probe that leaked
+ * a socket would hold the event loop open exactly as long as the service runs.
+ */
+export function probePort(port, host = '127.0.0.1', timeoutMs = PROC_LIMITS.probeSocketTimeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (answered) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                socket.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve(answered);
+        };
+        const socket = new net.Socket();
+        socket.setTimeout(timeoutMs);
+        socket.once('connect', () => done(true));
+        socket.once('timeout', () => done(false));
+        socket.once('error', () => done(false));
+        try {
+            socket.connect(port, host);
+            socket.unref();
+        }
+        catch {
+            done(false);
+        }
+    });
+}
+/**
+ * Races the URL detector against the port probe and stops at the first hit.
+ *
+ * ONE SHOT. `stop()` is idempotent and is called from every terminal path, so a
+ * service that exits during the window leaves nothing behind.
+ */
+export class ReadinessWatcher {
+    opts;
+    timer;
+    deadline;
+    finished = false;
+    probing = false;
+    probeFn;
+    constructor(opts) {
+        this.opts = opts;
+        this.probeFn = opts.probe ?? ((port) => probePort(port));
+    }
+    start() {
+        if (this.finished)
+            return;
+        this.deadline = setTimeout(() => {
+            if (this.finished)
+                return;
+            this.stop();
+            this.opts.onTimeout();
+        }, this.opts.readyTimeoutMs);
+        this.deadline.unref?.();
+        const hint = this.opts.portHint;
+        if (hint === undefined)
+            return;
+        this.timer = setInterval(() => {
+            if (this.finished || this.probing)
+                return;
+            this.probing = true;
+            void this.probeFn(hint)
+                .then((answered) => {
+                this.probing = false;
+                if (!answered || this.finished)
+                    return;
+                this.settle({ port: hint, url: `http://127.0.0.1:${hint}`, detectedBy: 'probe' });
+            })
+                .catch(() => {
+                this.probing = false;
+            });
+        }, PROC_LIMITS.probeIntervalMs);
+        this.timer.unref?.();
+    }
+    /**
+     * Offer the rows emitted since the last call.
+     *
+     * A MATCH WITH A PORT IS CONFIRMED BY ONE CONNECT before the status flips; a
+     * refused connect leaves the service `starting` and the row is simply not
+     * re-considered on the next call, because the caller passes only NEW rows.
+     */
+    offerRows(rows) {
+        if (this.finished || rows.length === 0)
+            return;
+        const hit = detectReadyUrl(rows);
+        if (!hit)
+            return;
+        if (hit.port === undefined) {
+            this.settle({ ...(hit.url ? { url: hit.url } : {}), detectedBy: 'url' });
+            return;
+        }
+        const port = hit.port;
+        void this.probeFn(port)
+            .then((answered) => {
+            if (!answered || this.finished)
+                return;
+            this.settle({
+                port,
+                url: hit.url ?? `http://127.0.0.1:${port}`,
+                detectedBy: 'url',
+            });
+        })
+            .catch(() => {
+            /* a refused connect is not an error; it just is not ready yet */
+        });
+    }
+    stop() {
+        this.finished = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        if (this.deadline)
+            clearTimeout(this.deadline);
+        this.timer = undefined;
+        this.deadline = undefined;
+    }
+    settle(result) {
+        if (this.finished)
+            return;
+        this.stop();
+        this.opts.onReady(result);
+    }
+}

package/dist/proc/supervisor.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ProcSupervisor — the owner of every child process this session spawned
+ * (background-service-supervision §3.3 / §3.5 / §3.6).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * ONE REGISTRY, TWO LIFETIMES (I-4). Foreground `bash` children are tracked so
+ * `forceStop()` can reach them; background services are tracked so `Ctrl+C`,
+ * `bash_kill` and process exit can reach them. Splitting those into two
+ * registries is how a force-stop ends up killing the user's dev server, or how a
+ * quit leaves it running. They are two collections in ONE object, and the two
+ * kill entry points are named for which one they own.
+ *
+ * CONSTRUCTED UNCONDITIONALLY (P1-6 / D-9). `cfg.bash.background` gates the
+ * SERVICE half — the `background` tool param, `bash_output`/`bash_kill`, the
+ * prompt block, the status chip — and never the foreground half, because G2
+ * ("bash always settles") and G3 ("Esc, Esc always works") are promised
+ * unconditionally. With the flag off this object holds foreground pids, nothing
+ * else, and allocates no timers.
+ */
+import { type ProcEventListener, type ProcSupervisorPort, type ServiceLogPage, type ServiceSnapshot, type ServiceStartRequest, type ServiceStartResult } from './types.js';
+export interface ProcSupervisorOptions {
+    /** `cfg.bash.readyTimeoutMs`, read once per service at spawn. */
+    readyTimeoutMs: () => number;
+    /** Injected by the tests; production uses a real TCP connect. */
+    probe?: (port: number) => Promise<boolean>;
+}
+export declare class ProcSupervisor implements ProcSupervisorPort {
+    private readonly opts;
+    private readonly services;
+    /**
+     * Live FOREGROUND `bash` children, by pid.
+     *
+     * A `Set` of pids rather than of `ChildProcess` objects: the only thing
+     * `killForeground` needs is the number, and holding the object would keep a
+     * reference to a settled child's stdio for the life of the session.
+     */
+    private readonly foreground;
+    private readonly listeners;
+    private nextId;
+    private disposed;
+    constructor(opts: ProcSupervisorOptions);
+    trackForeground(pid: number | undefined): () => void;
+    /**
+     * Hard-kill every tracked foreground child. Returns how many were signalled.
+     *
+     * THIS IS WHAT ACTUALLY UNBLOCKS A WEDGED `await tool.execute` on rung two of
+     * the Esc ladder. It NEVER touches services: `Esc` interrupts the AGENT,
+     * `Ctrl+C` stops the SERVICES, and that asymmetry is the user's own two
+     * sentences (I-4). A later reader will want to "fix" this by making it kill
+     * everything; that is the bug, not the fix.
+     */
+    killForeground(_reason: 'force'): number;
+    start(req: ServiceStartRequest): Promise<ServiceStartResult>;
+    get(id: string): ServiceSnapshot | undefined;
+    list(): ServiceSnapshot[];
+    read(id: string, since?: number): ServiceLogPage | undefined;
+    liveCount(): number;
+    /**
+     * Stop one service, or every service.
+     *
+     * `SIGTERM` FIRST, `SIGKILL` AFTER `stopGraceMs` — the graceful ladder, which
+     * belongs here rather than in `reapSync` because this path has a live event
+     * loop to run it on. It then CHECKS `process.kill(pid, 0)` and records
+     * `killIncomplete` when the pid is still there (P2-6): an honest warning beats
+     * a silent leak, and `killTree` cannot know on its own whether it worked.
+     */
+    stop(id: string): Promise<ServiceSnapshot[]>;
+    private stopOne;
+    /**
+     * SYNCHRONOUS, TOTAL, IDEMPOTENT. The only entry point a signal hook,
+     * `process.on('exit')` or `handleFatal` may call.
+     *
+     * No escalation ladder, no promises, no logging: a reaper that can block or
+     * throw is worse than one that misses a child. It reaps FOREGROUND children
+     * too, because a `bash` call in flight at quit time is a process nobody else
+     * will ever kill.
+     */
+    reapSync(): void;
+    dispose(): void;
+    subscribe(listener: ProcEventListener): () => void;
+    /**
+     * EVERY LISTENER IS WRAPPED, and that is not defensive noise (I-5). This runs
+     * inside `child.stdout.on('data')`, so a throw here would kill a ten-minute
+     * build because of a render bug. `debug` rather than `warn` because a listener
+     * that throws once throws on every chunk — the same rule, the same reason, as
+     * `AgentController.emitToolOutput`.
+     */
+    private emit;
+    /** Coalesce `output` at the SOURCE — `/bg` and `bash_output` read it too. */
+    private scheduleOutput;
+    /** Release every timer, wake every waiter, and announce the terminal state. */
+    private finish;
+    /**
+     * Evict TERMINAL records only, oldest first, to make room.
+     *
+     * IDS ARE NEVER REUSED (I-6): `nextId` only ever increases, so a stale
+     * `bash_kill({ service: 's1' })` can only be a no-op and never a kill of
+     * something else.
+     */
+    private evictTerminal;
+    private snapshot;
+}