agenticros 0.0.1 → 0.1.1

package/runtime/packages/agenticros/src/describer.ts

@@ -0,0 +1,157 @@
+import type { AgenticROSConfig } from "@agenticros/core";
+
+/**
+ * Optional in-plugin image describer.
+ *
+ * Why this exists:
+ *
+ *   * The OpenClaw runtime filters image content blocks out of tool results
+ *     before passing them to text-only chat models (see
+ *     `provider-stream-EGXtbhbQ.js:309` — `model.input.includes("image") ?
+ *     blocks : blocks.filter(b => b.type !== "image")`).
+ *   * `agents.defaults.imageModel` configures the *explicit* `image` tool
+ *     the agent can call, but does **not** install an automatic
+ *     tool-result-to-caption hook. So when the primary model is text-only
+ *     (e.g. Ollama qwen2.5:7b for tool-calling on Jetson), it never sees
+ *     the camera frame and tends to hallucinate a generic description.
+ *
+ * The describer calls a vision-capable OpenAI-compatible endpoint
+ * directly from the plugin and the `ros2_camera_snapshot` tool then
+ * embeds the description text into its tool result. This bypasses
+ * OpenClaw's image filtering entirely.
+ *
+ * # Networking
+ *
+ * Inside NemoClaw the gateway runs with ``NODE_USE_ENV_PROXY=1`` and
+ * ``HTTP_PROXY=http://10.200.0.1:3128``. Node 22's built-in undici
+ * ``fetch`` reads those automatically and routes all outbound HTTP(S)
+ * through the OPA-managed proxy. We therefore use ``fetch`` and don't
+ * implement any of our own proxy logic — past attempts to manually build
+ * CONNECT tunnels or absolute-form URLs ended up double-proxied (the OPA
+ * proxy saw ``host:3128`` instead of the real upstream port) or hit
+ * "FORWARD denied" because Ollama on the host isn't reachable on its raw
+ * port from the docker bridge — only the auth proxy on
+ * ``host.openshell.internal:11435`` is. See the
+ * ``agenticros-describer.policy.yaml`` / ``local-inference`` preset for
+ * the corresponding policy.
+ *
+ * # Bearer token
+ *
+ * The auth proxy on port 11435 requires ``Authorization: Bearer <token>``
+ * (24-byte hex token written by nemoclaw to
+ * ``~/.nemoclaw/ollama-proxy-token`` on the host). Inside the sandbox the
+ * gateway does NOT receive this token in its environment by default. We
+ * accept it via the plugin config field ``describer.apiKey`` — set it in
+ * ``~/.openclaw/openclaw.json`` under ``plugins.entries.agenticros.config``.
+ */
+
+export interface DescribeImageOptions {
+  config: AgenticROSConfig;
+  /** Base64-encoded image (no data: prefix). */
+  base64: string;
+  /** MIME type, e.g. "image/jpeg" or "image/png". */
+  mimeType: string;
+  /** Optional override prompt; otherwise the one from config is used. */
+  prompt?: string;
+  /** Optional logger for diagnostics. */
+  logger?: { info(msg: string): void; warn(msg: string): void; error(msg: string): void };
+}
+
+export interface DescribeImageResult {
+  description: string;
+  model: string;
+  latencyMs: number;
+}
+
+/**
+ * Call the configured vision model with the image and return its text caption.
+ *
+ * Throws on network/HTTP failure so callers can decide whether to surface the
+ * error or silently fall back to "no description".
+ */
+export async function describeImage(opts: DescribeImageOptions): Promise<DescribeImageResult> {
+  const cfg = opts.config.describer;
+  if (!cfg.enabled) {
+    throw new Error("describer disabled in config");
+  }
+  const url = cfg.url;
+  const model = cfg.model;
+  const prompt = (opts.prompt ?? cfg.prompt).trim();
+  const maxTokens = cfg.maxTokens;
+  const timeoutMs = cfg.timeoutMs;
+  const apiKey = (cfg.apiKey ?? "").trim();
+
+  const dataUrl = `data:${opts.mimeType};base64,${opts.base64}`;
+
+  const body = JSON.stringify({
+    model,
+    stream: false,
+    max_tokens: maxTokens,
+    messages: [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: prompt },
+          { type: "image_url", image_url: { url: dataUrl } },
+        ],
+      },
+    ],
+  });
+
+  const start = Date.now();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": "AgenticROS-Describer/1.0",
+        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+      },
+      body,
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`describer HTTP ${res.status} from ${url}: ${text.slice(0, 300)}`);
+  }
+  let data: { choices?: Array<{ message?: { content?: string } }>; model?: string };
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new Error(`describer response was not JSON (HTTP ${res.status}): ${text.slice(0, 200)}`);
+  }
+  const content = data.choices?.[0]?.message?.content?.trim() ?? "";
+  if (!content) {
+    throw new Error(`describer returned empty content (HTTP ${res.status})`);
+  }
+  return {
+    description: content,
+    model: data.model ?? model,
+    latencyMs: Date.now() - start,
+  };
+}
+
+/**
+ * Convenience: try to describe; on failure, log and return null.
+ * The caller (ros2_camera_snapshot) uses this to keep the tool result
+ * usable even when the describer endpoint is misconfigured or down.
+ */
+export async function describeImageBestEffort(
+  opts: DescribeImageOptions,
+): Promise<DescribeImageResult | null> {
+  if (!opts.config.describer.enabled) return null;
+  try {
+    return await describeImage(opts);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    opts.logger?.warn(`ros2_camera_snapshot: describer failed: ${msg}`);
+    return null;
+  }
+}

package/runtime/packages/agenticros/src/image-binary-trim.ts

@@ -0,0 +1,16 @@
+/**
+ * Some CompressedImage decoders leave trailing bytes after the JPEG EOI (FFD9).
+ * OpenClaw's image sanitizer uses getImageMetadata(); extra bytes can make metadata fail
+ * and drop the tool image block. Trim to the last EOI marker when the buffer looks like JPEG.
+ */
+export function trimJpegToLastEoi(buf: Buffer): Buffer {
+  if (buf.length < 4 || buf[0] !== 0xff || buf[1] !== 0xd8) {
+    return buf;
+  }
+  for (let i = buf.length - 2; i >= 0; i--) {
+    if (buf[i] === 0xff && buf[i + 1] === 0xd9) {
+      return buf.subarray(0, i + 2);
+    }
+  }
+  return buf;
+}

package/runtime/packages/agenticros/src/index.ts

@@ -0,0 +1,85 @@
+import type { OpenClawPluginApi } from "./plugin-api.js";
+import { parseConfig, isCdrTypeSupported, agenticROSBannerLines } from "@agenticros/core";
+import { readAgenticROSConfigFromFile } from "./config-file.js";
+import { registerService } from "./service.js";
+import { registerTools } from "./tools/index.js";
+import { registerMemoryTools } from "./tools/ros2-memory.js";
+import { initMemory } from "./memory.js";
+import { loadSkills } from "./skill-loader.js";
+import { registerSafetyHook } from "./safety/validator.js";
+import { registerRobotContext } from "./context/robot-context.js";
+import { registerEstopCommand } from "./commands/estop.js";
+import { registerTransportCommand } from "./commands/transport.js";
+import { registerRoutes } from "./routes.js";
+
+/**
+ * AgenticROS — OpenClaw plugin for ROS2 robot control via natural language.
+ */
+export default {
+  id: "agenticros",
+  name: "AgenticROS",
+
+  register(api: OpenClawPluginApi): void {
+    for (const line of agenticROSBannerLines({ tagline: true })) {
+      api.logger.info(line);
+    }
+    api.logger.info("AgenticROS plugin loading...");
+    const imageSupported = isCdrTypeSupported("sensor_msgs/msg/CompressedImage");
+    api.logger.info(`AgenticROS: Zenoh CDR Image/CompressedImage supported=${imageSupported}`);
+
+    let config: ReturnType<typeof parseConfig>;
+    try {
+      config = readAgenticROSConfigFromFile();
+      api.logger.info("AgenticROS: using config from file (transport, namespace, etc.)");
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      api.logger.warn("AgenticROS: could not read config from file: " + msg + " — using gateway pluginConfig.");
+      config = parseConfig(api.pluginConfig ?? {});
+    }
+    const mode = config.transport?.mode ?? "local";
+    const zenohEndpoint = config.zenoh?.routerEndpoint ?? "";
+    api.logger.info(`AgenticROS: transport mode=${mode}${mode === "zenoh" && zenohEndpoint ? ` endpoint=${zenohEndpoint}` : ""}`);
+
+    // Register HTTP routes before any await so OpenClaw gateways that don't await register() still mount them (e.g. 2026.3.11 "async registration is ignored")
+    if (typeof api.registerHttpRoute === "function") {
+      registerRoutes(api, config);
+    }
+
+    // Register the rosbridge WebSocket connection as a managed service
+    registerService(api, config);
+
+    // Register core ROS2 tools (no Follow Me — that lives in agenticros-skill-followme)
+    registerTools(api, config);
+
+    // Initialize optional memory subsystem (async; off-by-default; same pattern as skills below).
+    void initMemory(config, api.logger)
+      .then((memory) => {
+        if (memory) registerMemoryTools(api, config);
+      })
+      .catch((e) => {
+        const msg = e instanceof Error ? e.message : String(e);
+        api.logger.error("AgenticROS: memory init failed: " + msg);
+      });
+
+    // Load optional skills from skillPackages and skillPaths (async; OpenClaw 2026.5+ requires sync register())
+    void loadSkills(api, config).catch((e) => {
+      const msg = e instanceof Error ? e.message : String(e);
+      api.logger.error("AgenticROS: skill load failed: " + msg);
+    });
+
+    // Register safety validation hook (before_tool_call)
+    registerSafetyHook(api, config);
+
+    // Register robot capability injection (before_agent_start)
+    registerRobotContext(api, config);
+
+    // Register direct commands (bypass AI)
+    registerEstopCommand(api, config);
+    registerTransportCommand(api, config);
+
+    api.logger.info("AgenticROS plugin loaded successfully");
+  },
+};
+
+export type { OpenClawPluginApi } from "./plugin-api.js";
+export type { SkillContext, RegisterSkill, DepthSampleResult, DepthSectorsResult } from "./skill-api.js";

package/runtime/packages/agenticros/src/landing-page.ts

@@ -0,0 +1,38 @@
+/**
+ * Returns the AgenticROS landing page HTML (links to Config and Teleop).
+ *
+ * `basePath` is the mount prefix where this plugin is served (e.g. `/plugins/agenticros`,
+ * `/agenticros`, or `/api/agenticros`). Hrefs are built absolutely from it so the
+ * buttons work whether the user opens the landing URL with or without a trailing slash.
+ */
+export function getLandingPageHtml(basePath = "/agenticros"): string {
+  const base = basePath.replace(/\/+$/, "");
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>AgenticROS</title>
+  <style>
+    * { box-sizing: border-box; }
+    body { font-family: system-ui, sans-serif; margin: 12px; background: #1a1a1a; color: #e0e0e0; }
+    h1 { font-size: 1.5rem; margin: 0 0 8px 0; }
+    p { margin: 0 0 20px 0; color: #aaa; font-size: 0.95rem; }
+    nav { display: flex; flex-wrap: wrap; gap: 12px; }
+    a { display: inline-block; padding: 12px 20px; border-radius: 8px; background: #333; color: #e0e0e0; text-decoration: none; border: 1px solid #555; }
+    a:hover { background: #444; color: #fff; }
+    a.back { background: transparent; border-color: #444; color: #aaa; font-size: 0.9rem; padding: 6px 12px; margin-bottom: 12px; }
+    a.back:hover { background: #2a2a2a; color: #e0e0e0; }
+  </style>
+</head>
+<body>
+  <a class="back" href="/">← Back to chat</a>
+  <h1>AgenticROS</h1>
+  <p>ROS2 + OpenClaw — natural language control of robots.</p>
+  <nav>
+    <a href="${base}/config">Config</a>
+    <a href="${base}/teleop/">Teleop</a>
+  </nav>
+</body>
+</html>`;
+}

package/runtime/packages/agenticros/src/memory.ts

@@ -0,0 +1,44 @@
+import type { AgenticROSConfig, MemoryProvider } from "@agenticros/core";
+import { createMemory } from "@agenticros/core";
+import type { PluginLogger } from "./plugin-api.js";
+
+let provider: MemoryProvider | null = null;
+let initStarted = false;
+let initError: string | null = null;
+
+/**
+ * Initialize the memory provider for the OpenClaw plugin.
+ *
+ * Called once during plugin registration. The provider is held as a module
+ * singleton and looked up by the memory tools.
+ */
+export async function initMemory(
+  config: AgenticROSConfig,
+  logger: PluginLogger,
+): Promise<MemoryProvider | null> {
+  if (initStarted) return provider;
+  initStarted = true;
+  if (!config.memory?.enabled) {
+    logger.info("AgenticROS: memory disabled (config.memory.enabled=false)");
+    return null;
+  }
+  try {
+    provider = await createMemory(config);
+    if (provider) {
+      logger.info(`AgenticROS: memory backend=${provider.backend} ready`);
+    }
+  } catch (err) {
+    initError = err instanceof Error ? err.message : String(err);
+    logger.error("AgenticROS: memory init failed: " + initError);
+    provider = null;
+  }
+  return provider;
+}
+
+export function getMemory(): MemoryProvider | null {
+  return provider;
+}
+
+export function getMemoryInitError(): string | null {
+  return initError;
+}

package/runtime/packages/agenticros/src/plugin-api.ts

@@ -0,0 +1,173 @@
+/**
+ * Type declarations matching the real OpenClaw plugin SDK.
+ *
+ * Only the subset used by the AgenticROS plugin is declared here.
+ * These types mirror openclaw/plugin-sdk so that the plugin compiles
+ * without importing the SDK at build time (it is provided at runtime).
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+
+// --- Logger ---
+
+export interface PluginLogger {
+  info(msg: string): void;
+  warn(msg: string): void;
+  error(msg: string): void;
+}
+
+// --- Tools ---
+
+export interface AgentTool {
+  name: string;
+  label: string;
+  description: string;
+  parameters: TSchema;
+  execute(
+    toolCallId: string,
+    params: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<ToolResult>;
+}
+
+export interface ToolResult {
+  content: ToolContent[];
+  details?: unknown;
+}
+
+export type ToolContent =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string };
+
+// --- Services ---
+
+export interface ServiceContext {
+  config: Record<string, unknown>;
+  stateDir: string;
+  logger: PluginLogger;
+}
+
+export interface PluginService {
+  id: string;
+  start(ctx: ServiceContext): Promise<void>;
+  stop?(ctx: ServiceContext): Promise<void>;
+}
+
+// --- Commands ---
+
+export interface CommandContext {
+  senderId?: string;
+  channel: string;
+  channelId?: string;
+  isAuthorizedSender: boolean;
+  args?: string;
+  commandBody: string;
+  config: Record<string, unknown>;
+  from?: string;
+  to?: string;
+  accountId?: string;
+  messageThreadId?: number;
+}
+
+export interface PluginCommand {
+  name: string;
+  description: string;
+  handler(ctx: CommandContext): Promise<CommandResult> | CommandResult;
+}
+
+export interface CommandResult {
+  text: string;
+}
+
+// --- Hooks ---
+
+export interface BeforeAgentStartEvent {
+  prompt: string;
+}
+
+export interface BeforeAgentStartResult {
+  prependContext?: string;
+}
+
+export interface BeforeAgentStartContext {
+  agentId?: string;
+  sessionKey?: string;
+  sessionId?: string;
+  workspaceDir?: string;
+  messageProvider?: string;
+}
+
+export type BeforeAgentStartHandler = (
+  event: BeforeAgentStartEvent,
+  ctx: BeforeAgentStartContext,
+) => Promise<BeforeAgentStartResult | void> | BeforeAgentStartResult | void;
+
+export interface BeforeToolCallEvent {
+  toolName: string;
+  params: Record<string, unknown>;
+}
+
+export interface BeforeToolCallResult {
+  block?: boolean;
+  blockReason?: string;
+}
+
+export interface BeforeToolCallContext {
+  agentId?: string;
+  sessionKey?: string;
+  toolName: string;
+}
+
+export type BeforeToolCallHandler = (
+  event: BeforeToolCallEvent,
+  ctx: BeforeToolCallContext,
+) => Promise<BeforeToolCallResult | void> | BeforeToolCallResult | void;
+
+// --- HTTP routes (Phase 3 teleop) ---
+
+/** Minimal request shape for plugin HTTP route handlers (gateway provides at runtime). */
+export interface HttpRouteRequest {
+  method: string;
+  url: string;
+  /** Read JSON body (e.g. for POST). May throw if body is invalid. */
+  readJsonBody?(): Promise<Record<string, unknown>>;
+}
+
+/** Minimal response shape for plugin HTTP route handlers (Node-style; gateway provides at runtime). */
+export interface HttpRouteResponse {
+  setHeader(name: string, value: string | number): void;
+  /** HTTP status code (e.g. res.statusCode = 200). */
+  statusCode: number;
+  end(body?: string | Buffer): void;
+}
+
+export type HttpRouteHandler = (
+  req: HttpRouteRequest,
+  res: HttpRouteResponse,
+) => void | Promise<void>;
+
+export interface HttpRouteOptions {
+  path: string;
+  method?: string;
+  handler: HttpRouteHandler;
+  /** When false, gateway should not require Bearer auth for this route (OpenClaw 2026.3.2+ may reject registration if missing). */
+  requireAuth?: boolean;
+  /** OpenClaw 2026.3.11+ requires explicit auth: "gateway" (use gateway token) or "plugin" (plugin-managed / no gateway auth). */
+  auth?: "gateway" | "plugin";
+}
+
+// --- Plugin API ---
+
+export interface OpenClawPluginApi {
+  pluginConfig?: Record<string, unknown>;
+  logger: PluginLogger;
+
+  registerTool(tool: AgentTool, opts?: { name?: string; names?: string[]; optional?: boolean }): void;
+  registerService(service: PluginService): void;
+  registerCommand(command: PluginCommand): void;
+  /** Register an HTTP route (e.g. for Phase 3 teleop). Optional; gateway may not provide it. */
+  registerHttpRoute?(options: HttpRouteOptions): void;
+
+  on(hookName: "before_agent_start", handler: BeforeAgentStartHandler): void;
+  on(hookName: "before_tool_call", handler: BeforeToolCallHandler): void;
+}

package/runtime/packages/agenticros/src/plugin-image-base64.ts

@@ -0,0 +1,69 @@
+/**
+ * Normalize base64 for OpenClaw tool image blocks.
+ * OpenClaw's sanitizeToolResultImages uses canonicalizeBase64(); strings must be
+ * strict base64 (no whitespace) with length multiple of 4, or the image is dropped
+ * and the UI/model may see broken data URLs.
+ *
+ * Logic aligned with openclaw/src/media/base64.ts canonicalizeBase64.
+ */
+
+function isBase64DataChar(code: number): boolean {
+  return (
+    (code >= 0x41 && code <= 0x5a) ||
+    (code >= 0x61 && code <= 0x7a) ||
+    (code >= 0x30 && code <= 0x39) ||
+    code === 0x2b ||
+    code === 0x2f
+  );
+}
+
+function canonicalizeBase64Strict(base64: string): string | undefined {
+  let cleaned = "";
+  let padding = 0;
+  let sawPadding = false;
+  for (let i = 0; i < base64.length; i += 1) {
+    const code = base64.charCodeAt(i);
+    if (code <= 0x20) {
+      continue;
+    }
+    if (code === 0x3d) {
+      padding += 1;
+      if (padding > 2) {
+        return undefined;
+      }
+      sawPadding = true;
+      cleaned += "=";
+      continue;
+    }
+    if (sawPadding || !isBase64DataChar(code)) {
+      return undefined;
+    }
+    cleaned += base64[i]!;
+  }
+  if (!cleaned || cleaned.length % 4 !== 0) {
+    return undefined;
+  }
+  return cleaned;
+}
+
+/**
+ * Strip optional data-URL prefix, remove whitespace, validate, then round-trip through Buffer
+ * so the payload is canonical base64 OpenClaw accepts.
+ */
+export function normalizePluginToolImageBase64(input: string): string | undefined {
+  let s = input.trim();
+  const dataUrl = /^data:[^;]+;base64,(.*)$/is.exec(s);
+  if (dataUrl) {
+    s = (dataUrl[1] ?? "").trim();
+  }
+  s = s.replace(/\s/g, "");
+  const canonical = canonicalizeBase64Strict(s);
+  if (!canonical) {
+    return undefined;
+  }
+  const buf = Buffer.from(canonical, "base64");
+  if (buf.length === 0) {
+    return undefined;
+  }
+  return buf.toString("base64");
+}

package/runtime/packages/agenticros/src/preflight.ts

@@ -0,0 +1,110 @@
+import { createConnection, type Socket } from "node:net";
+
+/**
+ * Result of a TCP-level reachability probe for a `ws://` / `wss://` endpoint.
+ *
+ * We only check that *something* accepts a TCP connection on the host:port — not
+ * that it speaks the WebSocket protocol. That is enough to distinguish "router
+ * is not running" (the common failure mode for AgenticROS users who forget to
+ * start zenohd) from "router is up but rejecting".
+ */
+export interface PreflightResult {
+  /** True if the TCP socket connected within the timeout. */
+  reachable: boolean;
+  /** Resolved host:port (for messages). Empty when parsing failed. */
+  host: string;
+  port: number;
+  /** Short human-readable reason when `reachable` is false. */
+  reason?: string;
+}
+
+/**
+ * TCP-level reachability probe for a WebSocket URL.
+ *
+ * Why TCP and not an actual WebSocket handshake?
+ *  - It's instant when the port is closed (the OS returns ECONNREFUSED, no
+ *    timeout wait).
+ *  - It doesn't depend on `ws://` library handshake quirks; we just need to
+ *    know whether zenohd / rosbridge is up.
+ *  - Calling `zenoh-ts` `Session.open()` against a closed port triggers its
+ *    own internal retry loop that spams `WebSocket disconnected from
+ *    remote-api-plugin: 1006` and `Restart connection (N/10)` — we want to
+ *    avoid invoking it at all when we already know the port is dead.
+ */
+export async function preflightWsEndpoint(
+  endpoint: string,
+  timeoutMs = 1500,
+): Promise<PreflightResult> {
+  const trimmed = (endpoint ?? "").trim();
+  if (!trimmed) {
+    return { reachable: false, host: "", port: 0, reason: "endpoint is empty" };
+  }
+
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return { reachable: false, host: "", port: 0, reason: `invalid URL "${trimmed}"` };
+  }
+
+  if (!/^wss?:$/i.test(url.protocol)) {
+    return {
+      reachable: false,
+      host: url.hostname,
+      port: 0,
+      reason: `expected ws:// or wss:// URL, got ${url.protocol}//`,
+    };
+  }
+
+  const host = url.hostname;
+  const defaultPort = url.protocol.toLowerCase() === "wss:" ? 443 : 80;
+  const port = url.port ? Number.parseInt(url.port, 10) : defaultPort;
+  if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+    return { reachable: false, host, port: 0, reason: `invalid port ${url.port}` };
+  }
+
+  return await new Promise<PreflightResult>((resolve) => {
+    let settled = false;
+    let socket: Socket | null = null;
+    const finish = (result: PreflightResult): void => {
+      if (settled) return;
+      settled = true;
+      if (socket) {
+        try {
+          socket.destroy();
+        } catch {
+          /* ignore */
+        }
+      }
+      resolve(result);
+    };
+
+    const timer = setTimeout(() => {
+      finish({ reachable: false, host, port, reason: `timeout after ${timeoutMs}ms` });
+    }, timeoutMs);
+    timer.unref?.();
+
+    try {
+      socket = createConnection({ host, port });
+    } catch (err) {
+      clearTimeout(timer);
+      finish({
+        reachable: false,
+        host,
+        port,
+        reason: err instanceof Error ? err.message : String(err),
+      });
+      return;
+    }
+    socket.once("connect", () => {
+      clearTimeout(timer);
+      finish({ reachable: true, host, port });
+    });
+    socket.once("error", (err: NodeJS.ErrnoException) => {
+      clearTimeout(timer);
+      const reason =
+        err && typeof err.code === "string" ? `${err.code} (${err.message})` : err?.message ?? "connection error";
+      finish({ reachable: false, host, port, reason });
+    });
+  });
+}