@the-seeker/server-agent 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @the-seeker/server-agent
+
+Node.js 20 이상에서 실행하는 읽기 전용 서버 모니터링 수집기입니다.
+수집기, 게이트웨이 WebSocket 클라이언트(`run`), systemd/launchd 설치 명령
+(`install`·`uninstall`·`status`)을 포함합니다.
+
+## 설치
+
+Ubuntu(systemd) 및 macOS(launchd) 공통 설치 스크립트:
+
+```bash
+TOKEN=sa_... ENDPOINT=wss://ingest.theseeker.io/agent/ws bash scripts/install.sh
+```
+
+수동 설치 명령은 Ubuntu와 macOS에서 다음과 같습니다. Linux에서는 두 단계 모두 root 권한이 필요하며,
+에이전트 프로세스 자체는 sudo 를 사용하지 않습니다(생성되는 `ExecStart=` 에도 없음).
+
+Ubuntu:
+
+```bash
+sudo npm i -g @the-seeker/server-agent@latest
+sudo theseeker-agent install --token "$TOKEN" --endpoint "$ENDPOINT" --user "$USER"
+```
+
+macOS:
+
+```bash
+npm i -g @the-seeker/server-agent@latest
+theseeker-agent install --token "$TOKEN" --endpoint "$ENDPOINT" --user "$USER"
+```
+
+`install` 옵션: `--token`(필수), `--endpoint`(기본 `wss://ingest.theseeker.io/agent/ws`),
+`--user`(기본 `$SUDO_USER` → `$USER`), `--pm2-home`(기본 `<user home>/.pm2`),
+`--add-groups`(systemd 유닛에 `SupplementaryGroups=adm systemd-journal` 추가).
+`--add-groups` 를 생략하면 `usermod -aG adm,systemd-journal <user>` 안내가 출력됩니다.
+
+설정 파일은 `0600`으로 기록되고 root 실행 시 서비스 사용자에게 `chown` 됩니다
+(디렉터리는 `0750`). Linux 에서 root 가 아니면 아무것도 쓰지 않고 수동 명령을 출력한 뒤
+종료 코드 `2`로 끝납니다. macOS 는 `~/Library/LaunchAgents/io.theseeker.agent.plist`를
+쓰고 `launchctl bootstrap gui/$(id -u)`(실패 시 `launchctl load -w`)로 적재하며,
+LaunchAgent 는 GUI 로그인 세션에 묶입니다(부팅 시 자동 실행 아님).
+
+`install`·`uninstall` 을 반복 실행해도 같은 유닛/plist 를 다시 쓸 뿐 중복이 생기지 않습니다.
+`THESEEKER_AGENT_SKIP_SERVICE_MANAGER=1` 은 QA 전용으로 `systemctl`/`launchctl` 호출만
+건너뜁니다(실제 로그인 세션에 적재하지 않고 파일 생성만 검증할 때 사용).
+
+소스 체크아웃에서 빌드하려면 이 패키지 디렉터리에서:
+
+```bash
+npm install --include=dev
+npm run build
+```
+
+## 실행
+
+현재 수집기 확인:
+
+```bash
+node --input-type=module -e 'import { collectHost } from "./dist/collectors/host.js"; console.log(await collectHost())'
+```
+
+`collectHost(previousSample?)`는 `{ host, collected_at, sample }`을 반환합니다.
+다음 호출에는 `sample`을 전달하며, 프레임에는 `host`와 `collected_at`만 넣습니다.
+`sample.measuredAt`은 monotonic milliseconds이며 네트워크 속도는 bytes/second입니다.
+
+`collectPm2(registry, { pm2Home?, signal? })`,
+`collectSystemd(watchedServices, registry, { platform?, signal? })`,
+`collectNginx(nginxEnabled, registry, signal?)`는 `capability`와 프레임용 목록을 반환합니다.
+PM2 목록은 `processes`, systemd는 `services`, 공통 로그 메타데이터는 `sources`입니다.
+`collectCapabilities({ host, pm2, systemd, nginx })`로 상태를 합칩니다.
+
+nginx 상대 로그 경로는 필요할 때만 `nginx -V`의 `--prefix`를 조회해 절대 경로로
+변환합니다(nginx 기본값 `/usr/local/nginx`). 요청별 변수가 포함된 로그 경로는
+정적인 파일로 확정할 수 없어 광고하지 않습니다.
+
+PM2 실행 위치는 `PM2_BIN`, 데이터 위치는 `pm2Home` 또는 `PM2_HOME`으로 설정합니다.
+PM2 환경·실행 인수·실행 경로는 반환하지 않습니다. 로그 경로와 journal unit은
+`SourceRegistry` 내부에 보관하고 `tail(sourceId, lines, signal?)`로만 읽습니다.
+`lines`는 1~500이며 프로토콜 요청은 100/200/500만 허용합니다.
+반환은 `{ source_id, lines, truncated, bytes }`, 실패는 `CollectionError.code`입니다.
+로그는 최대 256 KiB이며 경로를 벗어나는 symlink와 일반 파일이 아닌 대상은 거부합니다.
+
+capability: `available`=조회 성공, `unsupported`=OS 미지원 또는 nginx 비활성,
+`not_installed`=실행 파일 없음, `permission_denied`=권한 부족, `error`=기타 조회/파싱 실패.
+호스트 조회 실패는 호출자가 처리하고 host capability를 `error`로 지정합니다.
+
+## 상태 확인과 제거
+
+Ubuntu:
+
+```bash
+sudo theseeker-agent status --user "$USER"  # 서비스 상태 + 마지막 로그 20줄
+sudo theseeker-agent uninstall --user "$USER"
+```
+
+macOS:
+
+```bash
+theseeker-agent status --user "$USER"       # 서비스 상태 + 마지막 로그 20줄
+theseeker-agent uninstall --user "$USER"
+```
+
+패키지를 제거할 때는 `npm uninstall -g @the-seeker/server-agent`를 실행한다.
+
+`uninstall` 은 서비스를 정지·비활성화하고 유닛/plist 와 설정 파일을 제거하며
+로그 디렉터리는 남깁니다.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: readonly string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createAgentClient } from "./client.js";
+import { AGENT_VERSION, createLogger, loadConfig } from "./config.js";
+import { createInstallEnvironment, SKIP_SERVICE_MANAGER_ENV } from "./install/detect.js";
+import { INSTALL_USAGE, runInstall, runStatus, runUninstall } from "./install/index.js";
+const SERVICE_COMMANDS = ["install", "uninstall", "status"];
+const USAGE = [
+    "theseeker-agent <command>",
+    "",
+    "Commands:",
+    "  run          run the agent in the foreground",
+    "  install      install the systemd unit (linux) or LaunchAgent (macOS) and write the config",
+    "  uninstall    stop the service and remove the unit/plist and config (logs are kept)",
+    "  status       show the service state and the last log lines",
+    "",
+    INSTALL_USAGE,
+    "",
+    "Options:",
+    "  --version    print the agent version",
+    "  --help       print this message",
+    "",
+    "Environment:",
+    "  THESEEKER_AGENT_ENDPOINT   gateway websocket URL (overrides the config file)",
+    "  THESEEKER_AGENT_TOKEN      agent token (overrides the config file)",
+    `  ${SKIP_SERVICE_MANAGER_ENV}   install/uninstall without calling systemctl/launchctl (QA only)`,
+].join("\n");
+function write(line) {
+    process.stdout.write(`${line}\n`);
+}
+async function runForeground() {
+    const config = await loadConfig();
+    const log = createLogger(config.logLevel);
+    const client = createAgentClient({ config, log });
+    let closing = false;
+    const shutdown = () => {
+        if (closing)
+            return;
+        closing = true;
+        void client.stop().then(() => { process.exitCode = 0; });
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    log("info", "starting", { version: AGENT_VERSION });
+    client.start();
+    return 0;
+}
+export async function main(argv) {
+    const args = argv.filter((argument) => argument.length > 0);
+    const command = args[0];
+    if (args.includes("--version") || args.includes("-v")) {
+        write(AGENT_VERSION);
+        return 0;
+    }
+    if (!command || args.includes("--help") || args.includes("-h")) {
+        write(USAGE);
+        return command ? 0 : 1;
+    }
+    if (SERVICE_COMMANDS.some((name) => name === command)) {
+        const environment = createInstallEnvironment({ print: write });
+        const rest = args.slice(1);
+        try {
+            if (command === "install")
+                return await runInstall(rest, environment);
+            if (command === "uninstall")
+                return await runUninstall(rest, environment);
+            return await runStatus(rest, environment);
+        }
+        catch (error) {
+            write(error instanceof Error ? `error: ${error.message}` : `error: ${command} failed`);
+            return 1;
+        }
+    }
+    if (command !== "run") {
+        write(`unknown command: ${command}\n\n${USAGE}`);
+        return 1;
+    }
+    try {
+        return await runForeground();
+    }
+    catch (error) {
+        write(error instanceof Error ? `error: ${error.message}` : "error: agent failed to start");
+        return 1;
+    }
+}
+function invokedDirectly() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    void main(process.argv.slice(2)).then((code) => { if (code !== 0)
+        process.exitCode = code; });
+}

package/dist/client.d.ts

@@ -0,0 +1,56 @@
+import type { HostCollection, NetworkSample } from "./collectors/host.js";
+import type { NginxCollection } from "./collectors/nginx.js";
+import type { Pm2Collection } from "./collectors/pm2.js";
+import { SourceRegistry } from "./collectors/sources.js";
+import type { SystemdCollection } from "./collectors/systemd.js";
+import type { AgentConfig, Logger } from "./config.js";
+import type { Host } from "./protocol.js";
+export declare const MIN_INTERVAL_SEC = 10;
+export declare const MAX_INTERVAL_SEC = 60;
+export declare const SAMPLE_INTERVAL_MS = 5000;
+export declare const BACKOFF_BASE_MS = 1000;
+export declare const BACKOFF_CAP_MS = 60000;
+export declare const HANDSHAKE_TIMEOUT_MS = 10000;
+export type AgentPlatform = "linux" | "darwin";
+export interface AgentCollectors {
+    readonly host: (previous?: NetworkSample) => Promise<HostCollection>;
+    readonly pm2: (registry: SourceRegistry, options: {
+        readonly pm2Home?: string;
+        readonly signal?: AbortSignal;
+    }) => Promise<Pm2Collection>;
+    readonly systemd: (watched: readonly string[], registry: SourceRegistry, options: {
+        readonly platform?: string;
+        readonly signal?: AbortSignal;
+    }) => Promise<SystemdCollection>;
+    readonly nginx: (enabled: boolean, registry: SourceRegistry, signal?: AbortSignal) => Promise<NginxCollection>;
+}
+export interface AgentClientOptions {
+    readonly config: AgentConfig;
+    readonly agentVersion?: string | undefined;
+    readonly log?: Logger | undefined;
+    readonly registry?: SourceRegistry | undefined;
+    readonly collectors?: Partial<AgentCollectors> | undefined;
+    readonly platform?: AgentPlatform | undefined;
+    readonly sampleIntervalMs?: number | undefined;
+    /** Test seam: maps the negotiated `interval_sec` to a timer period. Defaults to seconds. */
+    readonly intervalToMs?: ((intervalSec: number) => number) | undefined;
+    readonly random?: (() => number) | undefined;
+    readonly handshakeTimeoutMs?: number | undefined;
+}
+export interface AgentClient {
+    start(): void;
+    stop(): Promise<void>;
+    readonly connected: boolean;
+    readonly seq: number;
+    readonly intervalSec: number;
+    readonly heartbeatIntervalMs: number;
+}
+export declare class AgentPlatformError extends Error {
+    constructor(platform: string);
+}
+export declare function clampIntervalSec(intervalSec: number): number;
+/** AWS full jitter: `random(0, min(cap, base * 2^attempt))`. */
+export declare function backoffDelayMs(attempt: number, random?: () => number): number;
+/** Averages cpu/load/net across the samples taken since the previous heartbeat; mem/swap/disks keep the latest reading. */
+export declare function averageHosts(samples: readonly Host[]): Host;
+export declare function createAgentClient(options: AgentClientOptions): AgentClient;

package/dist/client.js

@@ -0,0 +1,365 @@
+import { arch, cpus, hostname, platform as currentPlatform, release, uptime } from "node:os";
+import { WebSocket } from "ws";
+import { collectCapabilities } from "./collectors/capabilities.js";
+import { collectHost } from "./collectors/host.js";
+import { collectNginx } from "./collectors/nginx.js";
+import { collectPm2 } from "./collectors/pm2.js";
+import { SourceRegistry } from "./collectors/sources.js";
+import { collectSystemd } from "./collectors/systemd.js";
+import { AGENT_VERSION, createLogger } from "./config.js";
+import { createRequestHandlers, errorResponse } from "./handlers.js";
+import { HeartbeatFrameSchema, HelloFrameSchema, MAX_HEARTBEAT_BYTES, MAX_RESPONSE_BYTES, PROTOCOL_VERSION, ResponseFrameSchema, parseGatewayFrame, } from "./protocol.js";
+export const MIN_INTERVAL_SEC = 10;
+export const MAX_INTERVAL_SEC = 60;
+export const SAMPLE_INTERVAL_MS = 5000;
+export const BACKOFF_BASE_MS = 1000;
+export const BACKOFF_CAP_MS = 60000;
+export const HANDSHAKE_TIMEOUT_MS = 10000;
+const MAX_BUFFERED_SAMPLES = 64;
+const CLOSE_GRACE_MS = 2000;
+export class AgentPlatformError extends Error {
+    constructor(platform) {
+        super(`unsupported platform: ${platform}`);
+        this.name = "AgentPlatformError";
+    }
+}
+export function clampIntervalSec(intervalSec) {
+    if (!Number.isFinite(intervalSec))
+        return MIN_INTERVAL_SEC;
+    return Math.min(MAX_INTERVAL_SEC, Math.max(MIN_INTERVAL_SEC, Math.floor(intervalSec)));
+}
+/** AWS full jitter: `random(0, min(cap, base * 2^attempt))`. */
+export function backoffDelayMs(attempt, random = Math.random) {
+    const bound = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** Math.max(0, attempt));
+    return Math.floor(random() * bound);
+}
+function mean(values) {
+    if (!values.length)
+        return null;
+    return values.reduce((total, value) => total + value, 0) / values.length;
+}
+/** Averages cpu/load/net across the samples taken since the previous heartbeat; mem/swap/disks keep the latest reading. */
+export function averageHosts(samples) {
+    const latest = samples[samples.length - 1];
+    if (!latest)
+        throw new Error("averageHosts requires at least one sample");
+    const cpu = mean(samples.map((sample) => sample.cpu_pct).filter((value) => value !== null));
+    const loads = samples.map((sample) => sample.load).filter((value) => value !== null);
+    const axis = (index) => mean(loads.map((load) => load[index])) ?? 0;
+    return {
+        ...latest,
+        cpu_pct: cpu === null ? null : Math.max(0, Math.min(100, cpu)),
+        load: loads.length ? [axis(0), axis(1), axis(2)] : null,
+        net: {
+            rx_bps: mean(samples.map((sample) => sample.net.rx_bps).filter((value) => value !== null)),
+            tx_bps: mean(samples.map((sample) => sample.net.tx_bps).filter((value) => value !== null)),
+        },
+    };
+}
+function unavailableHost() {
+    return {
+        cpu_pct: null, cpu_count: cpus().length, load: null, mem: null, swap: null,
+        disks: [], net: { rx_bps: null, tx_bps: null }, uptime_sec: uptime(),
+    };
+}
+function resolvePlatform(platform) {
+    if (platform !== "linux" && platform !== "darwin")
+        throw new AgentPlatformError(platform);
+    return platform;
+}
+export function createAgentClient(options) {
+    const log = options.log ?? createLogger(options.config.logLevel);
+    const agentVersion = options.agentVersion ?? AGENT_VERSION;
+    const platform = resolvePlatform(options.platform ?? currentPlatform());
+    const registry = options.registry ?? new SourceRegistry(options.config.pm2Home);
+    const collectors = {
+        host: options.collectors?.host ?? collectHost,
+        pm2: options.collectors?.pm2 ?? collectPm2,
+        systemd: options.collectors?.systemd ?? collectSystemd,
+        nginx: options.collectors?.nginx ?? collectNginx,
+    };
+    const sampleIntervalMs = options.sampleIntervalMs ?? SAMPLE_INTERVAL_MS;
+    const intervalToMs = options.intervalToMs ?? ((intervalSec) => intervalSec * 1000);
+    const random = options.random ?? Math.random;
+    let intervalSec = MIN_INTERVAL_SEC;
+    let watchedServices = [];
+    let nginxEnabled = true;
+    let nginxSources = [];
+    let nginxCapability = "unsupported";
+    let nginxDirty = true;
+    let hostCapability = "error";
+    let previousSample;
+    let samples = [];
+    let sampling = false;
+    let beating = false;
+    let socket = null;
+    let seq = 0;
+    let attempt = 0;
+    let stopped = true;
+    let heartbeatTimer = null;
+    let sampleTimer = null;
+    let reconnectTimer = null;
+    const handlers = createRequestHandlers({
+        registry, log, platform,
+        state: () => ({ nginxEnabled, ...(options.config.pm2Home ? { pm2Home: options.config.pm2Home } : {}) }),
+        onNginxSources: (sources) => { nginxSources = [...sources]; nginxCapability = "available"; nginxDirty = false; },
+    });
+    function pm2Options() {
+        return options.config.pm2Home ? { pm2Home: options.config.pm2Home } : {};
+    }
+    async function sample() {
+        if (sampling)
+            return;
+        sampling = true;
+        try {
+            const collection = await collectors.host(previousSample);
+            previousSample = collection.sample;
+            samples.push(collection.host);
+            if (samples.length > MAX_BUFFERED_SAMPLES)
+                samples = samples.slice(-MAX_BUFFERED_SAMPLES);
+            hostCapability = "available";
+        }
+        catch {
+            hostCapability = "error";
+            log("warn", "host_sample_failed");
+        }
+        finally {
+            sampling = false;
+        }
+    }
+    async function refreshNginx() {
+        const collection = await collectors.nginx(nginxEnabled, registry);
+        nginxSources = collection.sources;
+        nginxCapability = collection.capability;
+        nginxDirty = false;
+    }
+    function isOpen(candidate) {
+        return candidate !== null && candidate === socket && candidate.readyState === WebSocket.OPEN;
+    }
+    function send(candidate, text) {
+        if (!isOpen(candidate))
+            return;
+        candidate.send(text);
+    }
+    async function sendHello(target) {
+        const [pm2, systemd] = await Promise.all([
+            collectors.pm2(registry, pm2Options()),
+            collectors.systemd(watchedServices, registry, {}),
+            sample(),
+        ]);
+        await refreshNginx();
+        const capabilities = collectCapabilities({ host: hostCapability, pm2, systemd, nginx: { capability: nginxCapability } });
+        const frame = HelloFrameSchema.parse({
+            type: "hello", protocol_version: PROTOCOL_VERSION, agent_version: agentVersion, hostname: hostname(),
+            os: { platform, release: release(), arch: arch() }, cpu_count: cpus().length,
+            boot_time: new Date(Date.now() - uptime() * 1000).toISOString(),
+            capabilities, sources: [...pm2.sources, ...systemd.sources, ...nginxSources],
+        });
+        send(target, JSON.stringify(frame));
+        log("info", "hello_sent", { sources: frame.sources.length });
+    }
+    function serializeHeartbeat(frame) {
+        const full = JSON.stringify(HeartbeatFrameSchema.parse(frame));
+        if (Buffer.byteLength(full) <= MAX_HEARTBEAT_BYTES)
+            return full;
+        const trimmed = JSON.stringify(HeartbeatFrameSchema.parse({
+            type: frame.type, seq: frame.seq, collected_at: frame.collected_at, host: frame.host,
+            processes: frame.processes, services: frame.services, capabilities: frame.capabilities,
+        }));
+        if (Buffer.byteLength(trimmed) <= MAX_HEARTBEAT_BYTES)
+            return trimmed;
+        return null;
+    }
+    async function sendHeartbeat(target) {
+        if (beating)
+            return;
+        beating = true;
+        try {
+            if (!samples.length)
+                await sample();
+            const [pm2, systemd] = await Promise.all([
+                collectors.pm2(registry, pm2Options()),
+                collectors.systemd(watchedServices, registry, {}),
+            ]);
+            if (nginxDirty)
+                await refreshNginx();
+            const host = samples.length ? averageHosts(samples) : unavailableHost();
+            samples = [];
+            const next = seq + 1;
+            const frame = {
+                type: "heartbeat", seq: next, collected_at: new Date().toISOString(), host,
+                processes: pm2.processes, services: systemd.services,
+                capabilities: collectCapabilities({ host: hostCapability, pm2, systemd, nginx: { capability: nginxCapability } }),
+                sources: [...pm2.sources, ...systemd.sources, ...nginxSources],
+            };
+            if (!isOpen(target)) {
+                log("debug", "heartbeat_dropped");
+                return;
+            }
+            const text = serializeHeartbeat(frame);
+            if (!text) {
+                log("warn", "heartbeat_too_large");
+                return;
+            }
+            send(target, text);
+            seq = next;
+            log("debug", "heartbeat_sent", { seq, processes: frame.processes.length, services: frame.services.length });
+        }
+        catch {
+            log("warn", "heartbeat_failed");
+        }
+        finally {
+            beating = false;
+        }
+    }
+    function stopTimers() {
+        if (heartbeatTimer)
+            clearInterval(heartbeatTimer);
+        if (sampleTimer)
+            clearInterval(sampleTimer);
+        heartbeatTimer = null;
+        sampleTimer = null;
+    }
+    function startHeartbeat(target) {
+        if (heartbeatTimer)
+            clearInterval(heartbeatTimer);
+        heartbeatTimer = setInterval(() => void sendHeartbeat(target), intervalToMs(intervalSec));
+    }
+    function applyConfiguration(frame, target) {
+        const previousInterval = intervalSec;
+        intervalSec = clampIntervalSec(frame.interval_sec);
+        watchedServices = [...frame.watched_services];
+        if (nginxEnabled !== frame.nginx_enabled) {
+            nginxEnabled = frame.nginx_enabled;
+            nginxDirty = true;
+        }
+        if (frame.type === "welcome" || previousInterval !== intervalSec)
+            startHeartbeat(target);
+    }
+    async function respond(frame, target) {
+        let response = null;
+        try {
+            response = await handlers.handle(frame);
+        }
+        catch {
+            response = errorResponse(frame.request_id, "internal", "internal");
+        }
+        if (!response)
+            return;
+        let text;
+        try {
+            text = JSON.stringify(ResponseFrameSchema.parse(response));
+        }
+        catch {
+            text = JSON.stringify(errorResponse(frame.request_id, "internal", "internal"));
+        }
+        if (Buffer.byteLength(text) > MAX_RESPONSE_BYTES) {
+            text = JSON.stringify(errorResponse(frame.request_id, "too_large", "too_large"));
+        }
+        send(target, text);
+    }
+    function onMessage(target, data, binary) {
+        if (binary) {
+            log("warn", "binary_frame_ignored");
+            return;
+        }
+        const buffer = Array.isArray(data) ? Buffer.concat(data) : Buffer.isBuffer(data) ? data : Buffer.from(data);
+        const parsed = parseGatewayFrame(buffer.toString("utf8"));
+        if (!parsed.ok) {
+            log("warn", "invalid_frame_ignored");
+            return;
+        }
+        switch (parsed.frame.type) {
+            case "welcome":
+                attempt = 0;
+                applyConfiguration(parsed.frame, target);
+                log("info", "welcome", { interval_sec: intervalSec, generation: parsed.frame.connection_generation });
+                return;
+            case "config":
+                applyConfiguration(parsed.frame, target);
+                log("info", "config_applied", { interval_sec: intervalSec, watched_services: watchedServices.length, nginx_enabled: nginxEnabled });
+                return;
+            case "request":
+                void respond(parsed.frame, target);
+                return;
+            default:
+                log("warn", "invalid_frame_ignored");
+        }
+    }
+    function scheduleReconnect(code) {
+        if (stopped)
+            return;
+        const delayMs = backoffDelayMs(attempt, random);
+        attempt++;
+        log("info", "reconnecting", { attempt, delay_ms: delayMs, code });
+        reconnectTimer = setTimeout(() => { reconnectTimer = null; connect(); }, delayMs);
+    }
+    function connect() {
+        if (stopped)
+            return;
+        const target = new WebSocket(options.config.endpoint, {
+            headers: { Authorization: `Bearer ${options.config.token}`, "X-Agent-Version": agentVersion },
+            perMessageDeflate: false,
+            handshakeTimeout: options.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_MS,
+        });
+        socket = target;
+        seq = 0;
+        samples = [];
+        target.on("open", () => {
+            log("info", "connected");
+            sampleTimer = setInterval(() => void sample(), sampleIntervalMs);
+            void sendHello(target).catch(() => {
+                log("warn", "hello_failed");
+                target.close(1011, "hello_failed");
+            });
+        });
+        target.on("message", (data, binary) => { if (socket === target)
+            onMessage(target, data, binary); });
+        target.on("error", () => log("warn", "socket_error"));
+        target.on("close", (code) => {
+            if (socket !== target)
+                return;
+            socket = null;
+            stopTimers();
+            log("info", "disconnected", { code });
+            scheduleReconnect(code);
+        });
+    }
+    return {
+        get connected() { return socket !== null && socket.readyState === WebSocket.OPEN; },
+        get seq() { return seq; },
+        get intervalSec() { return intervalSec; },
+        get heartbeatIntervalMs() { return intervalToMs(intervalSec); },
+        start() {
+            if (!stopped)
+                return;
+            stopped = false;
+            connect();
+        },
+        async stop() {
+            stopped = true;
+            stopTimers();
+            if (reconnectTimer) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = null;
+            }
+            const target = socket;
+            socket = null;
+            if (!target) {
+                log("info", "stopped");
+                return;
+            }
+            await new Promise((resolve) => {
+                const done = setTimeout(() => { target.terminate(); resolve(); }, CLOSE_GRACE_MS);
+                target.once("close", () => { clearTimeout(done); resolve(); });
+                if (target.readyState === WebSocket.OPEN || target.readyState === WebSocket.CONNECTING)
+                    target.close(1000, "shutdown");
+                else {
+                    clearTimeout(done);
+                    resolve();
+                }
+            });
+            log("info", "stopped");
+        },
+    };
+}

package/dist/collectors/capabilities.d.ts

@@ -0,0 +1,13 @@
+import type { Capabilities, CapabilityState } from "../protocol.js";
+export declare function collectCapabilities(states: {
+    readonly host: CapabilityState;
+    readonly pm2: {
+        readonly capability: CapabilityState;
+    };
+    readonly systemd: {
+        readonly capability: CapabilityState;
+    };
+    readonly nginx: {
+        readonly capability: CapabilityState;
+    };
+}): Capabilities;

package/dist/collectors/capabilities.js

@@ -0,0 +1,3 @@
+export function collectCapabilities(states) {
+    return { host: states.host, pm2: states.pm2.capability, systemd: states.systemd.capability, nginx: states.nginx.capability };
+}

package/dist/collectors/command.d.ts

@@ -0,0 +1,13 @@
+import type { ExecFileOptions } from "node:child_process";
+import type { CapabilityState, ResponseError } from "../protocol.js";
+export declare function run(file: string, args: readonly string[], options?: Omit<ExecFileOptions, "shell">): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function locate(binary: string): Promise<string | null>;
+export declare class CollectionError extends Error {
+    readonly code: ResponseError["code"];
+    constructor(code: ResponseError["code"]);
+}
+export declare function responseError(error: unknown): CollectionError;
+export declare function capabilityError(error: unknown): CapabilityState;