@saadnvd1/agent-os 0.3.807 → 0.3.815

package/lib/reach/classify.ts

@@ -0,0 +1,283 @@
+/**
+ * Turns reachability facts into findings. Pure: no I/O, no clock of its own.
+ * Every title and fix line lives in CAUSES, which the guide quotes word for
+ * word (guide-sync.test.ts), so the guide can't drift from what's printed.
+ */
+
+import type {
+  ReachCause,
+  ReachFacts,
+  ReachFinding,
+  ReachReport,
+  ReachRoute,
+  ReachStatus,
+} from "./types";
+import { slug } from "@/scripts/lib/heading-slugs";
+import { guideUrl } from "@/lib/guides";
+
+export const REACH_GUIDE = "reachability";
+
+/** How long a cause AgentOS retries by itself stays "nothing to do". */
+export const SELF_HEAL_MS = 5 * 60_000;
+
+interface CauseText {
+  title: string;
+  fix: string;
+  /** Other fixes for the same cause, picked by what the facts say. */
+  alt?: Record<string, string>;
+}
+
+export const CAUSES: Record<ReachCause, CauseText> = {
+  "no-route": {
+    title: "No way in from other devices yet",
+    fix: "agent-os setup",
+  },
+  "service-down": {
+    title: "AgentOS isn't running",
+    fix: "agent-os start",
+    alt: { "no-service": "agent-os enable" },
+  },
+  "service-stuck": {
+    title: "AgentOS holds its port but isn't answering",
+    fix: "agent-os restart",
+  },
+  "port-taken": {
+    title: "Another program holds AgentOS's port",
+    fix: "Stop that program, or move AgentOS: AGENT_OS_PORT=3012 agent-os restart",
+  },
+  "lan-off": {
+    title: "Wi-Fi access is off",
+    fix: "agent-os setup --via lan",
+  },
+  firewall: {
+    title: "The firewall may block devices on your Wi-Fi",
+    fix: "Allow incoming connections for node in this computer's firewall settings",
+  },
+  "tailscale-missing": {
+    title: "Tailscale isn't installed",
+    fix: "Install it from tailscale.com/download, then run agent-os check",
+  },
+  "tailscale-logged-out": {
+    title: "Tailscale is logged out",
+    fix: "sudo tailscale up",
+  },
+  "connect-not-linked": {
+    title: "Connect isn't linked",
+    fix: "agent-os connect",
+  },
+  "connect-off": {
+    title: "Connect is turned off",
+    fix: "agent-os connect --on",
+  },
+  "connect-not-here": {
+    title: "Connect can't run in this server",
+    fix: "Start AgentOS without AGENTOS_CONNECT=0",
+    alt: {
+      lock: "Another AgentOS on this machine holds the tunnel: stop it, then agent-os restart",
+      "dev-build": "Connect only runs from a production build: agent-os start",
+      "wrong-port": "Connect follows AgentOS's own port: agent-os restart",
+      "auth-off":
+        "Connect never runs with pairing off: remove AGENTOS_AUTH=off",
+      other: "agent-os logs",
+    },
+  },
+  "connect-denied": {
+    title: "Connect refused this machine",
+    fix: "agent-os connect",
+  },
+  "connector-not-ready": {
+    title: "The connector isn't connected yet",
+    fix: "agent-os logs",
+  },
+  "relay-down": {
+    title: "The Connect service isn't answering",
+    fix: "agent-os logs",
+  },
+  "origin-down": {
+    title: "Connect reaches this machine but AgentOS doesn't answer",
+    fix: "agent-os restart",
+  },
+  "wrong-origin": {
+    title: "Another AgentOS answers this address",
+    fix: "Stop the other one, or run agent-os connect here",
+  },
+  dns: {
+    title: "The address doesn't resolve",
+    fix: "Wait a minute for it to publish, then agent-os check",
+    alt: {
+      all: "This computer can't look up names: check its network or DNS settings",
+    },
+  },
+  offline: {
+    title: "This computer is offline",
+    fix: "Connect it to the internet, then agent-os check",
+  },
+  certificate: {
+    title: "The certificate didn't check out",
+    fix: "Something on this network intercepts HTTPS: try another network",
+    alt: { clock: "Fix this computer's clock: it's more than 5 minutes off" },
+  },
+};
+
+export const guideAnchor = (cause: ReachCause) => slug(CAUSES[cause].title);
+
+/** The finding for a cause, with its fix picked from CAUSES. */
+export function finding(
+  cause: ReachCause,
+  status: ReachStatus,
+  opts: {
+    route?: ReachRoute;
+    alt?: string;
+    needs?: "you" | "nothing";
+    detail?: string;
+  } = {}
+): ReachFinding {
+  const text = CAUSES[cause];
+  const needs = opts.needs ?? "you";
+  const fix = (opts.alt && text.alt?.[opts.alt]) || text.fix;
+  return {
+    ...(opts.route && { route: opts.route }),
+    status,
+    cause,
+    needs,
+    title: opts.detail ? `${text.title} (${opts.detail})` : text.title,
+    fix: needs === "nothing" ? "" : fix,
+    guide: guideUrl({ file: REACH_GUIDE, anchor: guideAnchor(cause) }),
+  };
+}
+
+const ROUTE_TITLE: Record<ReachRoute, string> = {
+  connect: "Reachable through Connect",
+  tailscale: "Reachable on your Tailscale network",
+  lan: "Reachable on this Wi-Fi",
+};
+
+const ok = (route: ReachRoute, url: string): ReachFinding => ({
+  route,
+  status: "ok",
+  needs: "nothing",
+  title: ROUTE_TITLE[route],
+  fix: "",
+  url,
+});
+
+// A cause AgentOS keeps retrying: nothing to do for a while, then it's yours.
+function retrying(cause: ReachCause, facts: ReachFacts): ReachFinding {
+  const since = facts.connect.downSince ?? facts.now;
+  return facts.now - since < SELF_HEAL_MS
+    ? finding(cause, "warn", { route: "connect", needs: "nothing" })
+    : finding(cause, "fail", { route: "connect" });
+}
+
+function connectFinding(facts: ReachFacts): ReachFinding {
+  const c = facts.connect;
+  const url = c.hostname ? `https://${c.hostname}` : "";
+  if (c.state === "refused")
+    return finding("connect-not-here", "fail", {
+      route: "connect",
+      alt: c.notHere,
+    });
+  if (c.state === "denied")
+    return finding("connect-denied", "fail", { route: "connect" });
+  if (c.state === "off")
+    return finding("connect-off", "fail", { route: "connect" });
+  if (c.state !== "up")
+    return retrying(
+      c.stage === "service" ? "relay-down" : "connector-not-ready",
+      facts
+    );
+  const p = facts.probe;
+  if (!p || p.kind === "ok")
+    return url ? ok("connect", url) : retrying("connector-not-ready", facts);
+  switch (p.kind) {
+    case "wrong-origin":
+      return finding("wrong-origin", "fail", { route: "connect" });
+    case "edge":
+      if (p.tunnel) return retrying("connector-not-ready", facts);
+      if (p.status === 502 || p.status === 504)
+        return finding("origin-down", "fail", { route: "connect" });
+      return retrying("relay-down", facts);
+    case "dns":
+      // This computer can't look anything up: others may still get in.
+      return p.scope === "all"
+        ? finding("dns", "warn", { route: "connect", alt: "all" })
+        : retrying("dns", facts);
+    case "tls":
+      return p.skewed
+        ? finding("certificate", "fail", { route: "connect", alt: "clock" })
+        : finding("certificate", "warn", { route: "connect" });
+    case "offline":
+      return finding("offline", "fail", { route: "connect" });
+    case "timeout":
+      return retrying("relay-down", facts);
+  }
+}
+
+/** The routes this machine is set up for: each one gets a finding. */
+export function routesInUse(
+  facts: ReachFacts,
+  want: ReachRoute[] = []
+): ReachRoute[] {
+  const out: ReachRoute[] = [];
+  if (
+    (facts.connect.linked && facts.connect.enabled) ||
+    want.includes("connect")
+  )
+    out.push("connect");
+  if (facts.tailscale.state === "running" || want.includes("tailscale"))
+    out.push("tailscale");
+  if (facts.lan.on || want.includes("lan")) out.push("lan");
+  return out;
+}
+
+function routeFinding(route: ReachRoute, facts: ReachFacts): ReachFinding {
+  if (route === "connect")
+    return facts.connect.linked
+      ? connectFinding(facts)
+      : finding("connect-not-linked", "fail", { route });
+  if (route === "tailscale") {
+    const t = facts.tailscale;
+    if (t.state === "running" && t.url) return ok(route, t.url);
+    return t.state === "logged-out" || t.state === "running"
+      ? finding("tailscale-logged-out", "fail", { route })
+      : finding("tailscale-missing", "fail", { route });
+  }
+  if (!facts.lan.on) return finding("lan-off", "fail", { route });
+  // A firewall reading is a guess from inside: never more than a warning.
+  if (facts.firewall === "blocks")
+    return finding("firewall", "warn", { route });
+  const ip = facts.lan.addresses[0];
+  return ip
+    ? ok(route, `http://${ip}:${facts.port}`)
+    : finding("lan-off", "warn", { route });
+}
+
+/**
+ * The report: one finding per route in use. Ok when every route works, warn
+ * when at least one does (or one is only retrying), fail when none does.
+ */
+export function classifyReach(
+  facts: ReachFacts,
+  want: ReachRoute[] = []
+): ReachReport {
+  const checkedAt = new Date(facts.now).toISOString();
+  const routes = routesInUse(facts, want);
+  if (!routes.length) {
+    // Linked but switched off is a clearer story than "no route".
+    const only =
+      facts.connect.linked && !facts.connect.enabled
+        ? finding("connect-off", "fail", { route: "connect" })
+        : finding("no-route", "fail");
+    return { status: "fail", findings: [only], checkedAt };
+  }
+  const findings = routes.map((r) => routeFinding(r, facts));
+  const url = findings.find((f) => f.url)?.url;
+  const working = findings.some((f) => f.status === "ok");
+  const retryingOnly = findings.every((f) => f.status !== "fail");
+  const status: ReachStatus = findings.every((f) => f.status === "ok")
+    ? "ok"
+    : working || retryingOnly
+      ? "warn"
+      : "fail";
+  return { status, ...(url && { url }), findings, checkedAt };
+}

package/lib/reach/cli.ts

@@ -0,0 +1,38 @@
+/** Entry for agent-os check (lib/reach/check-cli.ts). Argv: port, then flags. */
+
+import { execFile } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { runCheckCli } from "./check-cli";
+
+const [port, ...args] = process.argv.slice(2);
+const p = Number(port) || 3011;
+
+const SERVICE_FILES = [
+  "Library/LaunchAgents/com.agent-os.plist",
+  ".config/systemd/user/agent-os.service",
+];
+
+runCheckCli(args, {
+  base: `http://127.0.0.1:${p}`,
+  fetch,
+  out: (line) => console.log(line),
+  holder: () =>
+    new Promise((resolve) =>
+      execFile(
+        "lsof",
+        ["-nP", `-iTCP:${p}`, "-sTCP:LISTEN", "-Fc"],
+        { timeout: 3000 },
+        (_err, stdout) =>
+          resolve(
+            String(stdout ?? "")
+              .split("\n")
+              .find((l) => l.startsWith("c"))
+              ?.slice(1) || null
+          )
+      )
+    ),
+  serviceInstalled: () =>
+    SERVICE_FILES.some((f) => fs.existsSync(path.join(os.homedir(), f))),
+}).then((code) => process.exit(code));

package/lib/reach/gatherFacts.ts

@@ -0,0 +1,167 @@
+/**
+ * Collects what the classifier reads. Every tool's output is reduced to a
+ * label here: raw text can carry keys, tokens or account names, so it never
+ * reaches a finding.
+ */
+
+import { execFile } from "child_process";
+import fs from "fs";
+import { promisify } from "util";
+import { connectStatus, type ConnectStatus } from "@/lib/connect/serve";
+import { connectDir, readConnect } from "@/lib/connect/config";
+import { tailscaleStatus, type TailscaleState } from "@/lib/tailscale";
+import { lanAddresses } from "@/lib/security/net";
+import { lanEnabled } from "@/lib/security/network-settings";
+import { reachFrom } from "@/lib/security/reach";
+import { tailnetHttpsUrl } from "@/lib/security/tailnet-https";
+import { probeConnect } from "./probeConnect";
+import type { ConnectProbe, NotHere, ReachFacts } from "./types";
+
+type Exec = (file: string, args: string[]) => Promise<string>;
+
+export interface GatherDeps {
+  connect: () => ConnectStatus;
+  connectFiles: () => { enabled: boolean; controlHost?: string };
+  tailscale: () => Promise<TailscaleState>;
+  tailnetHttps: () => string | null;
+  lan: () => { on: boolean; addresses: string[] };
+  exec: Exec;
+  readFile: (p: string) => string | null;
+  probe: (hostname: string, controlHost: string) => Promise<ConnectProbe>;
+  platform: NodeJS.Platform;
+  nodePath: string;
+  port: number;
+  now: () => number;
+}
+
+const run = promisify(execFile);
+
+export const defaultGatherDeps = (): GatherDeps => ({
+  connect: connectStatus,
+  connectFiles: () => {
+    const r = readConnect(connectDir());
+    if (!r.ok) return { enabled: false };
+    let controlHost: string | undefined;
+    try {
+      controlHost = new URL(r.files.config.apiUrl).hostname;
+    } catch {}
+    return { enabled: r.enabled, controlHost };
+  },
+  tailscale: tailscaleStatus,
+  tailnetHttps: tailnetHttpsUrl,
+  lan: () => {
+    const on = lanEnabled();
+    return { on, addresses: on ? lanAddresses() : [] };
+  },
+  exec: async (file, args) =>
+    (await run(file, args, { timeout: 3000 })).stdout.toString(),
+  readFile: (p) => {
+    try {
+      return fs.readFileSync(p, "utf8");
+    } catch {
+      return null;
+    }
+  },
+  probe: (hostname, controlHost) => probeConnect(hostname, controlHost),
+  platform: process.platform,
+  nodePath: process.execPath,
+  port: Number(process.env.AGENTOS_PORT || 3011),
+  now: Date.now,
+});
+
+/** The server's own words for why Connect doesn't run here, as a label. */
+export function notHereLabel(reason = ""): NotHere {
+  if (reason === "AGENTOS_CONNECT=0") return "env-off";
+  if (reason === "not a production build") return "dev-build";
+  if (reason.startsWith("port ")) return "wrong-port";
+  if (reason.includes("AGENTOS_AUTH=off")) return "auth-off";
+  if (reason.includes("holds the tunnel")) return "lock";
+  return "other";
+}
+
+const SOCKETFILTERFW = "/usr/libexec/ApplicationFirewall/socketfilterfw";
+
+/**
+ * Whether the firewall would stop devices on the Wi-Fi reaching node, read
+ * without sudo. A guess from inside, so the classifier only ever warns.
+ */
+export async function readFirewall(
+  deps: Pick<GatherDeps, "exec" | "readFile" | "platform" | "nodePath" | "port">
+): Promise<ReachFacts["firewall"]> {
+  try {
+    if (deps.platform === "darwin") {
+      const all = await deps.exec(SOCKETFILTERFW, ["--getblockall"]);
+      if (
+        /block all/i.test(all) &&
+        /enabled/i.test(all) &&
+        !/disabled/i.test(all)
+      )
+        return "blocks";
+      const app = await deps.exec(SOCKETFILTERFW, [
+        "--getappblocked",
+        deps.nodePath,
+      ]);
+      return /\bblocked\b/i.test(app) && !/not blocked|permitted/i.test(app)
+        ? "blocks"
+        : "off";
+    }
+    if (deps.platform === "linux") {
+      const conf = deps.readFile("/etc/ufw/ufw.conf");
+      if (!conf) return "off";
+      if (!/^\s*ENABLED\s*=\s*yes\s*$/m.test(conf)) return "off";
+      // The rules file is often root-only: then it may block.
+      const rules = deps.readFile("/etc/ufw/user.rules");
+      return rules && new RegExp(`--dport ${deps.port}\\b`).test(rules)
+        ? "off"
+        : "blocks";
+    }
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export async function gatherFacts(
+  deps: GatherDeps = defaultGatherDeps()
+): Promise<ReachFacts> {
+  const c = deps.connect();
+  const files = deps.connectFiles();
+  const lan = deps.lan();
+  const [ts, firewall] = await Promise.all([
+    deps.tailscale(),
+    lan.on ? readFirewall(deps) : Promise.resolve("off" as const),
+  ]);
+  const tsUrl = reachFrom(ts, [], deps.port, null, deps.tailnetHttps()).find(
+    (r) => r.kind === "tailscale"
+  )?.url;
+  const linked = !!c.enrolled || !!c.hostname;
+  // Off while switched on: the service stopped it (as good as refused), or
+  // it hasn't started yet.
+  const state =
+    c.state === "off" && linked && files.enabled
+      ? c.reason
+        ? "denied"
+        : "connecting"
+      : c.state;
+  const probe =
+    state === "up" && c.hostname && files.controlHost
+      ? await deps.probe(c.hostname, files.controlHost)
+      : undefined;
+  return {
+    now: deps.now(),
+    port: deps.port,
+    lan,
+    firewall,
+    tailscale: { state: ts.state, ...(tsUrl && { url: tsUrl }) },
+    connect: {
+      state,
+      linked,
+      enabled: files.enabled,
+      ...(c.hostname && { hostname: c.hostname }),
+      ...(state === "refused" && { notHere: notHereLabel(c.reason) }),
+      ...(c.stage && { stage: c.stage }),
+      ...(c.downSince && { downSince: c.downSince }),
+    },
+    ...(probe && { probe }),
+  };
+}

package/lib/reach/index.ts

@@ -0,0 +1,4 @@
+export { checkReach } from "./checkReach";
+export { classifyReach, CAUSES, finding, guideAnchor } from "./classify";
+export { bootId, PROBE_PATH } from "./probeConnect";
+export type * from "./types";

package/lib/reach/probeConnect.ts

@@ -0,0 +1,122 @@
+/**
+ * Fetches this machine's own Connect address from here, to prove the whole
+ * path works: DNS, the certificate, the edge, the connector and this server.
+ * /api/reach/probe answers with this process's boot id, so an answer from a
+ * cache or another AgentOS can't pass for ours.
+ */
+
+import { randomBytes } from "crypto";
+import { lookup } from "dns/promises";
+import type { ConnectProbe } from "./types";
+
+const g = globalThis as unknown as { __agentosBoot?: string };
+/** Random per process; the route and the probe must see the same one. */
+export const bootId = () =>
+  (g.__agentosBoot ??= randomBytes(8).toString("hex"));
+
+export const PROBE_PATH = "/api/reach/probe";
+const PROBE_MS = 8_000;
+const SKEW_MS = 5 * 60_000;
+
+export interface ProbeDeps {
+  fetch: typeof fetch;
+  /** Whether a name resolves at all. */
+  resolves: (name: string) => Promise<boolean>;
+  now: () => number;
+}
+
+const defaultDeps: ProbeDeps = {
+  fetch: (...a) => fetch(...a),
+  resolves: (name) =>
+    lookup(name).then(
+      () => true,
+      () => false
+    ),
+  now: Date.now,
+};
+
+const DNS = new Set(["ENOTFOUND", "EAI_AGAIN", "EAI_NODATA", "EAI_NONAME"]);
+const OFFLINE = new Set([
+  "ENETUNREACH",
+  "ENETDOWN",
+  "EHOSTUNREACH",
+  "ECONNREFUSED",
+]);
+const TLS = /^(CERT_|ERR_TLS_|ERR_SSL_)|SELF_SIGNED|UNABLE_TO_(GET|VERIFY)/;
+// Both names come from Connect's own config; only a plain DNS name is fetched,
+// so nothing in them can add a port, a path or a userinfo part to the URL.
+const DNS_NAME =
+  /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,62}$/i;
+
+function errorCode(err: unknown): string {
+  const e = err as { name?: string; code?: string; cause?: { code?: string } };
+  if (e?.name === "TimeoutError" || e?.name === "AbortError") return "TIMEOUT";
+  return String(e?.cause?.code ?? e?.code ?? "");
+}
+
+// The clock is off when a server's Date header disagrees by minutes. Over
+// plain HTTP, so a broken certificate can't hide the answer.
+async function clockSkewed(
+  deps: ProbeDeps,
+  controlHost: string
+): Promise<boolean> {
+  if (!controlHost) return false;
+  try {
+    const res = await deps.fetch(`http://${controlHost}/`, {
+      method: "HEAD",
+      redirect: "manual",
+      signal: AbortSignal.timeout(PROBE_MS),
+    });
+    const date = Date.parse(res.headers.get("date") ?? "");
+    return Number.isFinite(date) && Math.abs(date - deps.now()) > SKEW_MS;
+  } catch {
+    return false;
+  }
+}
+
+export async function probeConnect(
+  hostname: string,
+  controlHost: string,
+  boot = bootId(),
+  deps: ProbeDeps = defaultDeps
+): Promise<ConnectProbe> {
+  if (!DNS_NAME.test(hostname)) return { kind: "dns", scope: "host" };
+  if (!DNS_NAME.test(controlHost)) controlHost = "";
+  let res: Response;
+  try {
+    res = await deps.fetch(`https://${hostname}${PROBE_PATH}`, {
+      redirect: "manual",
+      cache: "no-store",
+      signal: AbortSignal.timeout(PROBE_MS),
+    });
+  } catch (err) {
+    const code = errorCode(err);
+    if (code === "TIMEOUT") return { kind: "timeout" };
+    if (DNS.has(code))
+      return {
+        kind: "dns",
+        scope:
+          controlHost && !(await deps.resolves(controlHost)) ? "all" : "host",
+      };
+    if (TLS.test(code))
+      return {
+        kind: "tls",
+        skewed:
+          code === "CERT_NOT_YET_VALID" ||
+          (await clockSkewed(deps, controlHost)),
+      };
+    if (OFFLINE.has(code)) return { kind: "offline" };
+    return { kind: "timeout" };
+  }
+  if (res.status >= 500) {
+    const body = await res.text().catch(() => "");
+    // 530 with error 1033: the edge has no connector for this address.
+    const tunnel = res.status === 530 || /\b1033\b/.test(body);
+    return { kind: "edge", status: res.status, tunnel };
+  }
+  if (res.status !== 200) return { kind: "wrong-origin" };
+  const body = (await res.json().catch(() => null)) as {
+    boot?: unknown;
+  } | null;
+  return body?.boot === boot ? { kind: "ok" } : { kind: "wrong-origin" };
+}