@tsplc/agent 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@tsplc/agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "The tsPLC plant agent: deploys a program and its server to a controller on the plant network, and holds an engineering login for reads, writes and forces.",
+  "keywords": [
+    "plc",
+    "codesys",
+    "deployment"
+  ],
+  "homepage": "https://github.com/livingforjesus/tsplc#readme",
+  "bugs": "https://github.com/livingforjesus/tsplc/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/livingforjesus/tsplc.git",
+    "directory": "packages/agent"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./src/client.ts",
+      "bun": "./src/client.ts",
+      "default": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/*.test.ts"
+  ],
+  "engines": {
+    "bun": ">=1.4.3"
+  },
+  "dependencies": {
+    "@tsplc/build": "0.2.0",
+    "@tsplc/config": "0.2.0",
+    "zod": "4.3.6"
+  },
+  "bin": {
+    "tsplc-agent": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,361 @@
+import { execFile } from "node:child_process";
+import { timingSafeEqual } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import {
+  explicitDownload,
+  findControllerLogin,
+  gatewayImage,
+  loginCommandSchema,
+  openControllerLogin,
+  resolveConfig,
+  updateController,
+} from "@tsplc/build";
+import { z } from "zod";
+import { discoverControllers, networkInterfaces } from "./discovery";
+import {
+  type AgentEvent,
+  type AgentStatus,
+  type Credentials,
+  credentialsSchema,
+  deployOptionsSchema,
+  type Release,
+  releaseSchema,
+  type Target,
+  targetSchema,
+} from "./protocol";
+import { loadRelease, readUpload, saveRelease } from "./releases";
+import { createServerSupervisor } from "./server-process";
+
+const execute = promisify(execFile);
+
+/** Builder containers reach the gateway by name on this Docker network. */
+const network = "tsplc-agent";
+const gateway = { host: "tsplc-agent-gateway", port: 1217 };
+const loginContainer = "tsplc-agent-login";
+/** CODESYS reads the controller user from these for one operation; the agent never stores it. */
+const credentialNames = {
+  usernameEnv: "TSPLC_DEVICE_USERNAME",
+  passwordEnv: "TSPLC_DEVICE_PASSWORD",
+};
+
+class AgentError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly downloadRequired = false,
+  ) {
+    super(message);
+  }
+}
+
+const json = (body: unknown, status = 200) => Response.json(body, { status });
+
+const readJson = async <T>(path: string, schema: z.ZodType<T>) =>
+  existsSync(path) ? schema.parse(JSON.parse(await readFile(path, "utf8"))) : null;
+
+const docker = (...args: string[]) => execute("docker", args).then(({ stdout }) => stdout.trim());
+
+/** The gateway container stays up between operations, as a CODESYS gateway service would. */
+const ensureGateway = async () => {
+  if (!(await docker("network", "ls", "--quiet", "--filter", `name=^${network}$`)))
+    await docker("network", "create", network);
+  if (await docker("container", "ls", "--quiet", "--filter", `name=^${gateway.host}$`)) return;
+  await docker("rm", "--force", gateway.host);
+  await docker(
+    "run",
+    "--detach",
+    "--restart",
+    "unless-stopped",
+    "--platform",
+    "linux/amd64",
+    "--network",
+    network,
+    "--name",
+    gateway.host,
+    gatewayImage,
+  );
+};
+
+/** Hands the controller user to CODESYS through the environment for the duration of `run`. */
+const withCredentials = async <T>(credentials: Credentials, run: () => Promise<T>) => {
+  process.env[credentialNames.usernameEnv] = credentials.username;
+  process.env[credentialNames.passwordEnv] = credentials.password;
+  try {
+    return await run();
+  } finally {
+    delete process.env[credentialNames.usernameEnv];
+    delete process.env[credentialNames.passwordEnv];
+  }
+};
+
+/** Relays the newest controller job's progress log, which CODESYS appends to as it works. */
+const followProgress = (controller: string, emit: (event: AgentEvent) => void) => {
+  const jobs = join(controller, ".codesys/controller/jobs");
+  const since = Date.now();
+  let following = true;
+  const done = (async () => {
+    let log: string | undefined;
+    let offset = 0;
+    while (following) {
+      await delay(2000);
+      if (!log && existsSync(jobs)) {
+        for (const job of await readdir(jobs)) {
+          const path = join(jobs, job, ".codesys/controller/progress.log");
+          if (existsSync(path) && (await stat(path)).mtimeMs >= since) log = path;
+        }
+      }
+      if (!log) continue;
+      const text = await readFile(log, "utf8");
+      for (const line of text.slice(offset).split("\n").filter(Boolean))
+        emit({ kind: "progress", message: line.replace(/^\S+Z /, "") });
+      offset = text.length;
+    }
+  })();
+  return async () => {
+    following = false;
+    await done;
+  };
+};
+
+export interface AgentOptions {
+  /** Releases, the controller's download baseline and the selected target live here. */
+  state: string;
+  token: string;
+  /** The deployed server's health route; without it a server that stays up 5 s counts as started. */
+  serverHealthUrl?: string;
+  log: (message: string) => void;
+}
+
+/** The plant agent's routes. It runs one deployment or login operation at a time. */
+export const createAgent = async (options: AgentOptions) => {
+  const paths = {
+    releases: join(options.state, "releases"),
+    controller: join(options.state, "controller"),
+    release: join(options.state, "release.json"),
+    target: join(options.state, "target.json"),
+  };
+  await mkdir(options.state, { recursive: true });
+  const server = createServerSupervisor({ healthUrl: options.serverHealthUrl, log: options.log });
+  const deployed = await readJson(paths.release, releaseSchema);
+  if (deployed?.server) server.start(join(paths.releases, deployed.server));
+  let busy: string | undefined;
+
+  const requireTarget = async () => {
+    const target = await readJson(paths.target, targetSchema);
+    if (!target) throw new AgentError("Select the controller first: tsplc target", 409);
+    return target;
+  };
+
+  /** The release's build config, aimed at `target` through the agent's gateway. */
+  const controllerConfig = (release: Awaited<ReturnType<typeof saveRelease>>, target: Target) => ({
+    ...resolveConfig(
+      {
+        ...release.manifest.config,
+        online: { network, gateway, device: target, credentials: credentialNames },
+      },
+      join(release.directory, "manifest.json"),
+    ),
+    // The baseline outlives releases: an online change compares against the last download.
+    outDir: paths.controller,
+  });
+
+  const currentRelease = async () => {
+    const release = await readJson(paths.release, releaseSchema);
+    if (!release) throw new AgentError("Nothing has been deployed yet: tsplc deploy", 409);
+    return loadRelease(paths.releases, release.id);
+  };
+
+  /** Streams one exclusive operation's events, then its result, as newline-delimited JSON. */
+  const operation = (
+    name: string,
+    run: (emit: (event: AgentEvent) => void) => Promise<unknown>,
+  ) => {
+    if (busy) throw new AgentError(`The agent is busy with ${busy}`, 409);
+    busy = name;
+    const encoder = new TextEncoder();
+    // A client that disconnects doesn't stop the operation; it just stops hearing about it.
+    let listening = true;
+    return new Response(
+      new ReadableStream({
+        start: async (controller) => {
+          const write = (text: string) => {
+            if (listening) controller.enqueue(encoder.encode(text));
+          };
+          const emit = (event: AgentEvent) => write(`${JSON.stringify(event)}\n`);
+          // CODESYS can stay silent for minutes; blank lines keep proxies from closing the stream.
+          const heartbeat = setInterval(() => write("\n"), 15_000);
+          try {
+            emit({ kind: "done", result: await run(emit) });
+          } catch (error) {
+            options.log(`${name} failed: ${error instanceof Error ? error.stack : String(error)}`);
+            emit({
+              kind: "error",
+              message: error instanceof Error ? error.message : String(error),
+              downloadRequired:
+                (error instanceof AgentError && error.downloadRequired) ||
+                (error instanceof Error && error.message.includes(explicitDownload)),
+            });
+          } finally {
+            clearInterval(heartbeat);
+            busy = undefined;
+            if (listening) controller.close();
+          }
+        },
+        cancel: () => {
+          listening = false;
+        },
+      }),
+      { headers: { "Content-Type": "application/x-ndjson" } },
+    );
+  };
+
+  const deploy = async (form: FormData) => {
+    const settings = deployOptionsSchema.parse(JSON.parse(z.string().parse(form.get("options"))));
+    const upload = await readUpload(form);
+    const target = await requireTarget();
+    if (await findControllerLogin(loginContainer))
+      throw new AgentError("A login is open; log out before deploying: tsplc logout", 409);
+    return operation("a deployment", async (emit) => {
+      const release = await saveRelease(paths.releases, upload);
+      const config = controllerConfig(release, target);
+      if (
+        !settings.download &&
+        !existsSync(join(paths.controller, ".codesys/controller/current.json"))
+      )
+        throw new AgentError(
+          "The controller has no application downloaded by this agent; only a full download can deploy",
+          409,
+          true,
+        );
+      const previous = await readJson(paths.release, releaseSchema);
+      // Server paths are relative to the releases directory.
+      const serverPath = release.manifest.server && `${release.id}/${release.manifest.server}`;
+      if (serverPath) {
+        emit({ kind: "progress", message: "Starting the new server" });
+        await server.replace(join(paths.releases, serverPath));
+      }
+      const kind = settings.download ? "download" : "online-change";
+      emit({ kind: "progress", message: `Starting the ${kind}; CODESYS takes minutes to start` });
+      await ensureGateway();
+      const stopFollowing = followProgress(paths.controller, emit);
+      const receipt = await withCredentials(settings.credentials, () =>
+        updateController(config, kind, { initializeUser: settings.initializeUser }),
+      )
+        .catch(async (failure: unknown) => {
+          if (serverPath) {
+            emit({ kind: "progress", message: "Restoring the previous server" });
+            await (previous?.server
+              ? server.replace(join(paths.releases, previous.server))
+              : server.stop());
+          }
+          throw failure;
+        })
+        .finally(stopFollowing);
+      const deployedRelease: Release = {
+        id: release.id,
+        deployedAt: new Date().toISOString(),
+        operation: kind,
+        controllerIds: receipt.controllerIds,
+        // A release without a server leaves the previous one running.
+        server: serverPath ?? previous?.server,
+      };
+      await writeFile(paths.release, JSON.stringify(deployedRelease, null, 2));
+      return deployedRelease;
+    });
+  };
+
+  const openLogin = async (credentials: Credentials) => {
+    const release = await currentRelease();
+    const config = controllerConfig(release, await requireTarget());
+    return operation("a login", async (emit) => {
+      if (await findControllerLogin(loginContainer))
+        throw new AgentError("A login is already open", 409);
+      emit({ kind: "progress", message: "Logging in; CODESYS takes minutes to start" });
+      await ensureGateway();
+      const login = await withCredentials(credentials, () =>
+        openControllerLogin(config, loginContainer),
+      );
+      return login.send({ command: "state" });
+    });
+  };
+
+  const requireLogin = async () => {
+    const login = await findControllerLogin(loginContainer);
+    if (!login) throw new AgentError("No login is open: tsplc login", 409);
+    return login;
+  };
+
+  const status = async (): Promise<AgentStatus> => {
+    const login = await findControllerLogin(loginContainer);
+    // A login still opening has its container but doesn't answer yet.
+    const state = login && (await login.ready()) && (await login.send({ command: "state" }));
+    return {
+      target: await readJson(paths.target, targetSchema),
+      release: await readJson(paths.release, releaseSchema),
+      server: server.status() ?? null,
+      login: state && "state" in state ? state : null,
+    };
+  };
+
+  const route = async (request: Request): Promise<Response> => {
+    const { pathname } = new URL(request.url);
+    const key = `${request.method} ${pathname}`;
+    switch (key) {
+      case "GET /status":
+        return json(await status());
+      case "GET /interfaces":
+        return json(networkInterfaces());
+      case "POST /discover": {
+        const { name } = z.strictObject({ name: z.string() }).parse(await request.json());
+        const selected = networkInterfaces().find((network) => network.name === name);
+        if (!selected) throw new AgentError(`No IPv4 interface named ${name}`, 404);
+        return json(await discoverControllers(selected));
+      }
+      case "PUT /target": {
+        const target = targetSchema.parse(await request.json());
+        await writeFile(paths.target, JSON.stringify(target, null, 2));
+        return json(target);
+      }
+      case "GET /variables":
+        return json((await currentRelease()).manifest.variables);
+      case "POST /deploy":
+        return deploy(await request.formData());
+      case "POST /login":
+        return openLogin(credentialsSchema.parse(await request.json()));
+      case "POST /login/command":
+        return json(
+          await (await requireLogin()).send(loginCommandSchema.parse(await request.json())),
+        );
+      case "DELETE /login":
+        await (await requireLogin()).close();
+        return json({});
+      default:
+        return json({ error: `No route ${key}` }, 404);
+    }
+  };
+
+  const expected = Buffer.from(`Bearer ${options.token}`);
+  return {
+    fetch: async (request: Request) => {
+      const actual = Buffer.from(request.headers.get("authorization") ?? "");
+      if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+        return json({ error: "Unauthorized" }, 401);
+      try {
+        return await route(request);
+      } catch (error) {
+        if (error instanceof AgentError) return json({ error: error.message }, error.status);
+        if (error instanceof z.ZodError) return json({ error: z.prettifyError(error) }, 400);
+        options.log(
+          `${request.method} ${request.url} failed: ${error instanceof Error ? error.stack : String(error)}`,
+        );
+        return json({ error: error instanceof Error ? error.message : String(error) }, 500);
+      }
+    },
+    /** Stops the supervised server; a login container keeps running for the next agent. */
+    stop: () => server.stop(),
+  };
+};

package/src/cli.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { configureDocker, configureGateway } from "@tsplc/build";
+import { z } from "zod";
+import { createAgent } from "./agent.ts";
+
+const usage = `tsplc-agent setup|serve [--listen host:port] [--state directory] [--server-health url]
+
+setup   Builds the CODESYS builder and gateway images. Run it once, and after updating tsPLC.
+serve   Serves deployments and logins. --listen is required: use the machine's Tailscale
+        address, such as 100.101.102.103:4850. TSPLC_AGENT_TOKEN must hold a shared secret of
+        at least 32 characters, such as one from \`openssl rand -hex 32\`.`;
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    help: { type: "boolean", short: "h" },
+    listen: { type: "string" },
+    state: { type: "string" },
+    "server-health": { type: "string" },
+  },
+});
+const command = positionals[0];
+if (!command || values.help) {
+  console.log(usage);
+  process.exit(0);
+}
+if (positionals.length > 1) throw new Error("Specify one command.");
+if (command === "setup") {
+  await configureDocker();
+  await configureGateway();
+} else if (command === "serve") {
+  const [, hostname, port] = /^(.+):(\d+)$/.exec(values.listen ?? "") ?? [];
+  if (!hostname || !port) throw new Error("--listen host:port is required.");
+  const token = z
+    .string({ error: "Set TSPLC_AGENT_TOKEN" })
+    .min(32, "TSPLC_AGENT_TOKEN must be at least 32 characters")
+    .parse(process.env["TSPLC_AGENT_TOKEN"]);
+  const agent = await createAgent({
+    state: values.state ?? join(homedir(), ".tsplc-agent"),
+    token,
+    serverHealthUrl: values["server-health"],
+    log: (message) => console.log(`${new Date().toISOString()} ${message}`),
+  });
+  const server = Bun.serve({
+    hostname,
+    port: Number(port),
+    fetch: agent.fetch,
+    // Deployments stream for minutes and upload a server executable.
+    idleTimeout: 0,
+    maxRequestBodySize: 2 ** 30,
+  });
+  console.log(`tsPLC agent listening on ${server.url}`);
+  for (const signal of ["SIGINT", "SIGTERM"] as const)
+    process.on(signal, () => {
+      void agent.stop().then(() => process.exit(0));
+    });
+} else throw new Error(`Unknown command ${command}.`);

package/src/client.ts

@@ -0,0 +1,119 @@
+import { type LoginCommand, loginResultSchema } from "@tsplc/build";
+import { z } from "zod";
+import {
+  type AgentEvent,
+  controllerSchema,
+  type Credentials,
+  type DeployOptions,
+  eventSchema,
+  networkInterfaceSchema,
+  type ReleaseManifest,
+  releaseSchema,
+  statusSchema,
+  type Target,
+  targetSchema,
+  variableSchema,
+} from "./protocol";
+
+/** A failed agent operation; `downloadRequired` means only a full download can deploy. */
+export class AgentOperationError extends Error {
+  constructor(
+    message: string,
+    readonly downloadRequired = false,
+  ) {
+    super(message);
+  }
+}
+
+/** A file to upload, at its path in the release. */
+export interface ReleaseFile {
+  path: string;
+  content: Blob;
+}
+
+/** Talks to a plant agent at `url`, such as its Tailscale name and port. */
+export const createAgentClient = (options: { url: string; token: string }) => {
+  const call = async (path: string, init: RequestInit = {}) => {
+    const response = await fetch(new URL(path, options.url), {
+      ...init,
+      headers: { ...init.headers, Authorization: `Bearer ${options.token}` },
+    }).catch((cause: unknown) => {
+      throw new Error(`Cannot reach the plant agent at ${options.url}`, { cause });
+    });
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw new AgentOperationError(
+        z.object({ error: z.string() }).safeParse(body).data?.error ??
+          `The agent answered ${response.status}`,
+      );
+    }
+    return response;
+  };
+  const get = async <T>(path: string, schema: z.ZodType<T>) =>
+    schema.parse(await (await call(path)).json());
+  const send = async <T>(method: string, path: string, body: unknown, schema: z.ZodType<T>) =>
+    schema.parse(
+      await (
+        await call(path, {
+          method,
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+        })
+      ).json(),
+    );
+
+  /** Reads a streamed operation, reporting progress, until its result or failure. */
+  const operation = async (response: Response, onProgress: (message: string) => void) => {
+    const reader = response.body?.pipeThrough(new TextDecoderStream()).getReader();
+    if (!reader) throw new Error("The agent returned no operation stream");
+    let buffered = "";
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) throw new Error("The agent closed the operation without a result");
+      buffered += value;
+      const lines = buffered.split("\n");
+      buffered = lines.pop() ?? "";
+      for (const line of lines.filter(Boolean)) {
+        const event: AgentEvent = eventSchema.parse(JSON.parse(line));
+        if (event.kind === "progress") onProgress(event.message);
+        else if (event.kind === "done") return event.result;
+        else throw new AgentOperationError(event.message, event.downloadRequired);
+      }
+    }
+  };
+
+  return {
+    status: () => get("/status", statusSchema),
+    interfaces: () => get("/interfaces", z.array(networkInterfaceSchema)),
+    discover: (name: string) => send("POST", "/discover", { name }, z.array(controllerSchema)),
+    setTarget: (target: Target) => send("PUT", "/target", target, targetSchema),
+    variables: () => get("/variables", z.array(variableSchema)),
+    deploy: async (
+      release: { manifest: ReleaseManifest; files: ReleaseFile[] },
+      settings: DeployOptions,
+      onProgress: (message: string) => void,
+    ) => {
+      const form = new FormData();
+      form.set("manifest", JSON.stringify(release.manifest));
+      form.set("options", JSON.stringify(settings));
+      for (const file of release.files) form.set(`files/${file.path}`, file.content, file.path);
+      return releaseSchema.parse(
+        await operation(await call("/deploy", { method: "POST", body: form }), onProgress),
+      );
+    },
+    login: async (credentials: Credentials, onProgress: (message: string) => void) =>
+      loginResultSchema.parse(
+        await operation(
+          await call("/login", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(credentials),
+          }),
+          onProgress,
+        ),
+      ),
+    command: (command: LoginCommand) => send("POST", "/login/command", command, loginResultSchema),
+    logout: () => send("DELETE", "/login", undefined, z.object({})),
+  };
+};
+export type AgentClient = ReturnType<typeof createAgentClient>;

package/src/discovery.ts

@@ -0,0 +1,84 @@
+import { Resolver } from "node:dns/promises";
+import { createConnection } from "node:net";
+import { networkInterfaces as osInterfaces } from "node:os";
+import type { DiscoveredController, NetworkInterface } from "./protocol";
+
+/** CODESYS runtimes accept engineering connections on their TCP block driver port. */
+export const runtimePort = 11740;
+/** A /22 is 1022 hosts: a sweep at 128 probes a time takes a few seconds. */
+const largestPrefix = 22;
+const probeTimeoutMs = 500;
+const probesAtOnce = 128;
+
+/** The machine's IPv4 networks, which `discoverControllers` scans one at a time. */
+export const networkInterfaces = (): NetworkInterface[] =>
+  Object.entries(osInterfaces()).flatMap(([name, addresses]) =>
+    (addresses ?? [])
+      .filter((address) => address.family === "IPv4" && !address.internal)
+      .map((address) => ({
+        name,
+        address: address.address,
+        prefixLength: address.netmask
+          .split(".")
+          .reduce((bits, octet) => bits + Number(octet).toString(2).replaceAll("0", "").length, 0),
+      })),
+  );
+
+const toNumber = (address: string) =>
+  address.split(".").reduce((value, octet) => value * 256 + Number(octet), 0);
+const toAddress = (value: number) =>
+  [24, 16, 8, 0].map((shift) => Math.floor(value / 2 ** shift) % 256).join(".");
+
+/** Every host address on the interface's subnet, except the interface's own. */
+export const subnetHosts = ({ address, prefixLength }: NetworkInterface) => {
+  if (prefixLength < largestPrefix)
+    throw new Error(
+      `The /${prefixLength} network is too large to scan; the limit is /${largestPrefix}.`,
+    );
+  const size = 2 ** (32 - prefixLength);
+  const network = toNumber(address) - (toNumber(address) % size);
+  // /31 and /32 networks have no network or broadcast address to skip.
+  const hosts =
+    size <= 2
+      ? Array.from({ length: size }, (_, index) => network + index)
+      : Array.from({ length: size - 2 }, (_, index) => network + index + 1);
+  return hosts.map(toAddress).filter((host) => host !== address);
+};
+
+const accepts = (host: string, port: number) =>
+  new Promise<boolean>((resolve) => {
+    const socket = createConnection({ host, port });
+    // A silent host leaves the connection pending for the OS's own timeout, which is minutes.
+    const timer = setTimeout(() => finish(false), probeTimeoutMs);
+    const finish = (open: boolean) => {
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(open);
+    };
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+  });
+
+const resolver = new Resolver({ timeout: 1000, tries: 1 });
+const hostname = (address: string) =>
+  resolver.reverse(address).then(
+    (names) => names[0] ?? null,
+    // Plant networks rarely have reverse DNS; the address alone identifies the controller.
+    () => null,
+  );
+
+/** Finds the hosts on `network` that accept CODESYS runtime connections. */
+export const discoverControllers = async (
+  network: NetworkInterface,
+  port = runtimePort,
+): Promise<DiscoveredController[]> => {
+  const hosts = subnetHosts(network);
+  const found: DiscoveredController[] = [];
+  for (let start = 0; start < hosts.length; start += probesAtOnce) {
+    const batch = hosts.slice(start, start + probesAtOnce);
+    const open = await Promise.all(batch.map((host) => accepts(host, port)));
+    for (const [index, host] of batch.entries())
+      if (open[index]) found.push({ address: host, port, hostname: await hostname(host) });
+  }
+  return found;
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export { type AgentOptions, createAgent } from "./agent.ts";
+export * from "./protocol.ts";