@prohost/cli 0.4.1 → 0.5.0

package/dist/liveness.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Client-side liveness for the event-stream socket.
+ *
+ * The server pings every 30 seconds and closes a socket that has not answered
+ * for 60. That contract only helps when the close actually arrives. A laptop
+ * that sleeps loses the server's FIN, the kernel keeps the TCP connection in
+ * ESTABLISHED, and `ws` — which reacts to `close` and `error` alone — sees a
+ * socket that is open, quiet, and never coming back. One paired agent sat on
+ * exactly that for three weeks: connected as far as the client could tell,
+ * unreachable as far as the server was concerned, and nothing on either side
+ * with a reason to say so.
+ *
+ * So the client keeps its own deadline. Every frame the server sends — pings
+ * included — is a proof of life; ninety seconds without one (three missed
+ * pings, comfortably past the server's own 60 s reaper) means the connection
+ * is dead whatever the kernel thinks, and the socket is torn down locally so
+ * the ordinary reconnect path runs. TCP keepalive is switched on as a second,
+ * kernel-level probe, and a periodic heartbeat line makes a stalled daemon
+ * visible in its log instead of indistinguishable from a healthy quiet one.
+ */
+/** Silence tolerated before the socket is declared dead: three missed pings. */
+export declare const PING_LIVENESS_MS = 90000;
+/** Delay before the kernel starts sending TCP keepalive probes on an idle socket. */
+export declare const TCP_KEEPALIVE_DELAY_MS = 30000;
+/** How often a connected harness writes its "still here" line. */
+export declare const HEARTBEAT_LOG_INTERVAL_MS = 300000;
+/**
+ * The slice of a `ws` client this module touches — narrow so that the test
+ * doubles, which implement only what the harness calls, satisfy it too.
+ */
+export interface LivenessSocket {
+    close(): void;
+    /** `ws` has it; the handwritten test doubles may not. */
+    terminate?(): void;
+}
+export interface LivenessOptions {
+    /** Silence window before {@link ServerLiveness.onSilence} fires. */
+    timeoutMs?: number;
+    /** Cadence of {@link ServerLiveness.onHeartbeat}. Tests shorten it. */
+    heartbeatIntervalMs?: number;
+    /** Clock, injectable so a test can age the connection without waiting. */
+    now?: () => number;
+    /** Called once when the window elapses with no frame. Receives the silence in ms. */
+    onSilence: (silentMs: number) => void;
+    /** Called on each heartbeat tick with the liveness state of the moment. */
+    onHeartbeat?: (state: LivenessState) => void;
+}
+export interface LivenessState {
+    /** Milliseconds since the last frame of any kind from the server. */
+    sinceLastFrameMs: number;
+    /** Milliseconds since the last `ping` — `undefined` before the first one. */
+    sinceLastPingMs: number | undefined;
+}
+/**
+ * Tracks the server's frames for one socket lifetime and fires when they stop.
+ *
+ * Owns two timers: the silence deadline, re-armed on every frame, and the
+ * heartbeat interval. Both are cleared by {@link stop}, which the socket's
+ * `close` handler must call — a timer left running after a reconnect would
+ * tear down the *next* socket for the previous one's silence.
+ */
+export declare class ServerLiveness {
+    private readonly timeoutMs;
+    private readonly heartbeatIntervalMs;
+    private readonly now;
+    private readonly onSilence;
+    private readonly onHeartbeat;
+    private lastFrameAt;
+    private lastPingAt;
+    private deadline;
+    private heartbeat;
+    private stopped;
+    constructor(options: LivenessOptions);
+    /**
+     * Arm the deadline. Called on `open`: the handshake completing is itself the
+     * first proof of life, and `ws` has its own timeout for a handshake that
+     * never completes.
+     */
+    start(): void;
+    /** Record a frame from the server. Any frame counts; a `ping` is also remembered as one. */
+    observe(frameType: unknown): void;
+    /** Release both timers. Idempotent; safe to call from `close` however the socket ended. */
+    stop(): void;
+    state(): LivenessState;
+    private arm;
+}
+/**
+ * Tear a socket down without the closing handshake.
+ *
+ * `close()` sends a close frame and then waits for the peer's — on a half-open
+ * connection that never comes, and `ws` only gives up on it after its own 30 s
+ * timer. `terminate()` destroys the underlying socket immediately, which is
+ * the right thing for a peer we have already decided is not there. The test
+ * doubles have no `terminate`, so fall back to `close`.
+ */
+export declare function terminateSocket(ws: LivenessSocket): void;
+/**
+ * Switch on TCP keepalive for the connection under a `ws` client.
+ *
+ * Reaches into `ws`'s private `_socket` — there is no public accessor — so
+ * everything is guarded: a build of `ws` that renames it, or a test double
+ * that has none, simply gets no keepalive rather than a crash on `open`.
+ * Returns whether the kernel-level probe was actually enabled.
+ */
+export declare function enableTcpKeepAlive(ws: unknown, delayMs?: number): boolean;
+/** Whole seconds, for log lines. */
+export declare function seconds(ms: number): number;

package/dist/liveness.js

@@ -0,0 +1,156 @@
+/**
+ * Client-side liveness for the event-stream socket.
+ *
+ * The server pings every 30 seconds and closes a socket that has not answered
+ * for 60. That contract only helps when the close actually arrives. A laptop
+ * that sleeps loses the server's FIN, the kernel keeps the TCP connection in
+ * ESTABLISHED, and `ws` — which reacts to `close` and `error` alone — sees a
+ * socket that is open, quiet, and never coming back. One paired agent sat on
+ * exactly that for three weeks: connected as far as the client could tell,
+ * unreachable as far as the server was concerned, and nothing on either side
+ * with a reason to say so.
+ *
+ * So the client keeps its own deadline. Every frame the server sends — pings
+ * included — is a proof of life; ninety seconds without one (three missed
+ * pings, comfortably past the server's own 60 s reaper) means the connection
+ * is dead whatever the kernel thinks, and the socket is torn down locally so
+ * the ordinary reconnect path runs. TCP keepalive is switched on as a second,
+ * kernel-level probe, and a periodic heartbeat line makes a stalled daemon
+ * visible in its log instead of indistinguishable from a healthy quiet one.
+ */
+/** Silence tolerated before the socket is declared dead: three missed pings. */
+export const PING_LIVENESS_MS = 90_000;
+/** Delay before the kernel starts sending TCP keepalive probes on an idle socket. */
+export const TCP_KEEPALIVE_DELAY_MS = 30_000;
+/** How often a connected harness writes its "still here" line. */
+export const HEARTBEAT_LOG_INTERVAL_MS = 300_000;
+/**
+ * Tracks the server's frames for one socket lifetime and fires when they stop.
+ *
+ * Owns two timers: the silence deadline, re-armed on every frame, and the
+ * heartbeat interval. Both are cleared by {@link stop}, which the socket's
+ * `close` handler must call — a timer left running after a reconnect would
+ * tear down the *next* socket for the previous one's silence.
+ */
+export class ServerLiveness {
+    timeoutMs;
+    heartbeatIntervalMs;
+    now;
+    onSilence;
+    onHeartbeat;
+    lastFrameAt;
+    lastPingAt;
+    deadline;
+    heartbeat;
+    stopped = false;
+    constructor(options) {
+        this.timeoutMs = options.timeoutMs ?? PING_LIVENESS_MS;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? HEARTBEAT_LOG_INTERVAL_MS;
+        this.now = options.now ?? Date.now;
+        this.onSilence = options.onSilence;
+        this.onHeartbeat = options.onHeartbeat;
+        this.lastFrameAt = this.now();
+    }
+    /**
+     * Arm the deadline. Called on `open`: the handshake completing is itself the
+     * first proof of life, and `ws` has its own timeout for a handshake that
+     * never completes.
+     */
+    start() {
+        if (this.stopped)
+            return;
+        this.lastFrameAt = this.now();
+        this.arm();
+        if (this.onHeartbeat && this.heartbeat === undefined) {
+            this.heartbeat = setInterval(() => this.onHeartbeat?.(this.state()), this.heartbeatIntervalMs);
+            this.heartbeat.unref?.();
+        }
+    }
+    /** Record a frame from the server. Any frame counts; a `ping` is also remembered as one. */
+    observe(frameType) {
+        if (this.stopped)
+            return;
+        this.lastFrameAt = this.now();
+        if (frameType === 'ping')
+            this.lastPingAt = this.lastFrameAt;
+        if (this.deadline !== undefined)
+            this.arm();
+    }
+    /** Release both timers. Idempotent; safe to call from `close` however the socket ended. */
+    stop() {
+        this.stopped = true;
+        if (this.deadline !== undefined)
+            clearTimeout(this.deadline);
+        if (this.heartbeat !== undefined)
+            clearInterval(this.heartbeat);
+        this.deadline = undefined;
+        this.heartbeat = undefined;
+    }
+    state() {
+        const now = this.now();
+        return {
+            sinceLastFrameMs: now - this.lastFrameAt,
+            sinceLastPingMs: this.lastPingAt === undefined ? undefined : now - this.lastPingAt,
+        };
+    }
+    arm() {
+        if (this.deadline !== undefined)
+            clearTimeout(this.deadline);
+        this.deadline = setTimeout(() => {
+            this.deadline = undefined;
+            if (this.stopped)
+                return;
+            // Stop before firing: the callback tears the socket down, and the close
+            // handler that follows calls stop() again — harmless, but the deadline
+            // must not be re-armed by a frame that races the teardown.
+            this.stop();
+            this.onSilence(this.now() - this.lastFrameAt);
+        }, this.timeoutMs);
+        this.deadline.unref?.();
+    }
+}
+/**
+ * Tear a socket down without the closing handshake.
+ *
+ * `close()` sends a close frame and then waits for the peer's — on a half-open
+ * connection that never comes, and `ws` only gives up on it after its own 30 s
+ * timer. `terminate()` destroys the underlying socket immediately, which is
+ * the right thing for a peer we have already decided is not there. The test
+ * doubles have no `terminate`, so fall back to `close`.
+ */
+export function terminateSocket(ws) {
+    try {
+        if (typeof ws.terminate === 'function')
+            ws.terminate();
+        else
+            ws.close();
+    }
+    catch {
+        /* already gone */
+    }
+}
+/**
+ * Switch on TCP keepalive for the connection under a `ws` client.
+ *
+ * Reaches into `ws`'s private `_socket` — there is no public accessor — so
+ * everything is guarded: a build of `ws` that renames it, or a test double
+ * that has none, simply gets no keepalive rather than a crash on `open`.
+ * Returns whether the kernel-level probe was actually enabled.
+ */
+export function enableTcpKeepAlive(ws, delayMs = TCP_KEEPALIVE_DELAY_MS) {
+    try {
+        const socket = ws
+            ._socket;
+        if (!socket || typeof socket.setKeepAlive !== 'function')
+            return false;
+        socket.setKeepAlive(true, delayMs);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whole seconds, for log lines. */
+export function seconds(ms) {
+    return Math.round(ms / 1000);
+}

package/dist/upgrade.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Best-effort "a newer build exists" notice for `agent run`.
+ *
+ * A daemon installed with `npm i -g` never upgrades itself, and nothing in the
+ * product can tell an operator which build their machine is on: the one that
+ * sat on a dead socket for three weeks was two minor versions behind the
+ * registry the whole time. The auth frame now reports the version server-side;
+ * this is the client-side half — one registry lookup at startup, printed as a
+ * single line when it finds something newer, and silent on every other
+ * outcome. It never delays the connection and cannot fail startup: the
+ * registry being slow, down, or answering nonsense is not the operator's
+ * problem and must not become one.
+ */
+export declare const NPM_LATEST_URL = "https://registry.npmjs.org/@prohost/cli/latest";
+/** Longest the registry gets. The socket does not wait on this. */
+export declare const UPGRADE_CHECK_TIMEOUT_MS = 3000;
+export interface UpgradeCheckOptions {
+    /** The running build. Defaults to {@link CLI_VERSION}; tests pin it. */
+    currentVersion?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    registryUrl?: string;
+}
+/**
+ * Compare two `MAJOR.MINOR.PATCH[-prerelease]` strings the way npm orders them
+ * for the cases this check meets: numeric identifiers compared as numbers,
+ * missing ones as zero, and a prerelease sorting *before* its release. Returns
+ * a negative number when `a` is older, positive when newer, `0` when equal.
+ * Not a full semver implementation — build metadata and prerelease ordering
+ * are not needed to answer "is the registry ahead of me".
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Ask the registry for the latest published version.
+ *
+ * Resolves to the version string when it is strictly newer than the running
+ * build, and `undefined` for everything else — up to date, ahead of the
+ * registry (a local build), a timeout, a non-2xx, a malformed body. It never
+ * rejects.
+ */
+export declare function newerVersionAvailable(options?: UpgradeCheckOptions): Promise<string | undefined>;
+/** The one line printed when a newer build exists. */
+export declare function upgradeNotice(latest: string, current?: string): string;
+/**
+ * Run the check without waiting for it: prints the notice if and when one is
+ * due, and otherwise does nothing. The returned promise is for tests; callers
+ * on the startup path drop it.
+ */
+export declare function announceUpgradeIfAvailable(write: (line: string) => void, options?: UpgradeCheckOptions): Promise<void>;

package/dist/upgrade.js

@@ -0,0 +1,99 @@
+/**
+ * Best-effort "a newer build exists" notice for `agent run`.
+ *
+ * A daemon installed with `npm i -g` never upgrades itself, and nothing in the
+ * product can tell an operator which build their machine is on: the one that
+ * sat on a dead socket for three weeks was two minor versions behind the
+ * registry the whole time. The auth frame now reports the version server-side;
+ * this is the client-side half — one registry lookup at startup, printed as a
+ * single line when it finds something newer, and silent on every other
+ * outcome. It never delays the connection and cannot fail startup: the
+ * registry being slow, down, or answering nonsense is not the operator's
+ * problem and must not become one.
+ */
+import { CLI_VERSION, USER_AGENT } from './version.js';
+export const NPM_LATEST_URL = 'https://registry.npmjs.org/@prohost/cli/latest';
+/** Longest the registry gets. The socket does not wait on this. */
+export const UPGRADE_CHECK_TIMEOUT_MS = 3_000;
+/**
+ * Compare two `MAJOR.MINOR.PATCH[-prerelease]` strings the way npm orders them
+ * for the cases this check meets: numeric identifiers compared as numbers,
+ * missing ones as zero, and a prerelease sorting *before* its release. Returns
+ * a negative number when `a` is older, positive when newer, `0` when equal.
+ * Not a full semver implementation — build metadata and prerelease ordering
+ * are not needed to answer "is the registry ahead of me".
+ */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const [core = '', prerelease] = v.trim().replace(/^v/, '').split('-', 2);
+        const parts = core.split('.').map((p) => {
+            const n = Number.parseInt(p, 10);
+            return Number.isFinite(n) ? n : 0;
+        });
+        return { parts, prerelease: prerelease !== undefined && prerelease !== '' };
+    };
+    const left = parse(a);
+    const right = parse(b);
+    for (let i = 0; i < Math.max(left.parts.length, right.parts.length); i += 1) {
+        const diff = (left.parts[i] ?? 0) - (right.parts[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    if (left.prerelease === right.prerelease)
+        return 0;
+    return left.prerelease ? -1 : 1;
+}
+/**
+ * Ask the registry for the latest published version.
+ *
+ * Resolves to the version string when it is strictly newer than the running
+ * build, and `undefined` for everything else — up to date, ahead of the
+ * registry (a local build), a timeout, a non-2xx, a malformed body. It never
+ * rejects.
+ */
+export async function newerVersionAvailable(options = {}) {
+    const current = options.currentVersion ?? CLI_VERSION;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? UPGRADE_CHECK_TIMEOUT_MS);
+    timer.unref?.();
+    try {
+        const response = await fetchImpl(options.registryUrl ?? NPM_LATEST_URL, {
+            method: 'GET',
+            headers: { Accept: 'application/json', 'User-Agent': USER_AGENT },
+            signal: controller.signal,
+        });
+        if (response.status < 200 || response.status >= 300)
+            return undefined;
+        const body = await response.json();
+        const latest = body && typeof body === 'object' ? body.version : undefined;
+        if (typeof latest !== 'string' || !/^\d+\.\d+\.\d+/.test(latest))
+            return undefined;
+        return compareVersions(latest, current) > 0 ? latest : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The one line printed when a newer build exists. */
+export function upgradeNotice(latest, current = CLI_VERSION) {
+    return `⬆ @prohost/cli ${latest} is available (running ${current}) — npm i -g @prohost/cli`;
+}
+/**
+ * Run the check without waiting for it: prints the notice if and when one is
+ * due, and otherwise does nothing. The returned promise is for tests; callers
+ * on the startup path drop it.
+ */
+export function announceUpgradeIfAvailable(write, options = {}) {
+    return newerVersionAvailable(options)
+        .then((latest) => {
+        if (latest)
+            write(upgradeNotice(latest, options.currentVersion ?? CLI_VERSION));
+    })
+        .catch(() => {
+        /* never surfaces — see the module comment */
+    });
+}

package/dist/version.d.ts

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export declare const CLI_VERSION = "0.4.1";
+export declare const CLI_VERSION = "0.5.0";
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
-export declare const USER_AGENT = "prohost-cli/0.4.1";
+export declare const USER_AGENT = "prohost-cli/0.5.0";

package/dist/version.js

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export const CLI_VERSION = '0.4.1';
+export const CLI_VERSION = '0.5.0';
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
 export const USER_AGENT = `prohost-cli/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prohost/cli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",