camstack 1.2.212 → 1.2.214

package/dist/chunk-37A556YF.js

@@ -0,0 +1,822 @@
+#!/usr/bin/env node
+import {
+  findHubs
+} from "./chunk-JPGJK5DC.js";
+
+// src/mcp/tool-result.ts
+import { text as plainText, textError } from "@camstack/develop";
+var FAILURE_STATUSES = /* @__PURE__ */ new Set([
+  "no-session",
+  "refused",
+  "failed",
+  "fetch-failed",
+  "unreachable",
+  "invalid-address",
+  "unsupported",
+  "unavailable",
+  "not-exposed"
+]);
+function isFailureResult(value) {
+  if (value === null || typeof value !== "object") return false;
+  const status = Reflect.get(value, "status");
+  return typeof status === "string" && FAILURE_STATUSES.has(status);
+}
+function text(value) {
+  const ok = plainText(value);
+  if (!isFailureResult(value)) return ok;
+  const body = ok.content[0]?.text ?? "";
+  return textError(body);
+}
+
+// src/mcp/setup-tools.ts
+import { z as z4 } from "zod";
+
+// src/mcp/setup-hubs.ts
+import * as https from "https";
+import {
+  createHubAgent,
+  explainTlsFailure,
+  HubAddressError,
+  hubCaFileForServer,
+  loadSession,
+  normalizeHubAddress,
+  resolveHubTls
+} from "@camstack/develop";
+import { z as z3 } from "zod";
+
+// src/mcp/setup-install.ts
+import { z as z2 } from "zod";
+
+// src/mcp/setup-install-rules.ts
+import { z } from "zod";
+var HOST_KINDS = [
+  "docker-compose",
+  "docker",
+  "unraid",
+  "proxmox-lxc",
+  "macos-desktop"
+];
+var HostKindSchema = z.enum(HOST_KINDS);
+var ROLES = ["hub", "agent"];
+var RoleSchema = z.enum(ROLES);
+var ACCELERATORS = ["intel", "amd", "coral", "apple", "cpu"];
+var AcceleratorSchema = z.enum(ACCELERATORS);
+var InstallPathsSchema = z.object({
+  data: z.string().min(1),
+  recordings: z.string().min(1),
+  config: z.string().min(1).optional(),
+  backups: z.string().min(1).optional()
+});
+var InstallGuideInputSchema = z.object({
+  hostKind: HostKindSchema.optional(),
+  role: RoleSchema.optional(),
+  accelerator: AcceleratorSchema.optional(),
+  paths: InstallPathsSchema.optional(),
+  /** Agents only: the hub the agent should dial (host or IP). */
+  hubAddress: z.string().min(1).optional()
+});
+var RAW = "https://raw.githubusercontent.com/camstack";
+var TEMPLATE_URLS = {
+  compose: {
+    hub: `${RAW}/proxmox/main/compose/hub.yml`,
+    agent: `${RAW}/proxmox/main/compose/agent.yml`
+  },
+  proxmoxInstaller: `${RAW}/proxmox/main/install-camstack-proxmox.sh`,
+  unraid: {
+    hub: `${RAW}/unraid-templates/main/templates/camstack.xml`,
+    agent: `${RAW}/unraid-templates/main/templates/camstack-agent.xml`
+  },
+  latestRelease: "https://api.github.com/repos/camstack/server/releases/latest"
+};
+var IMAGE_REPOSITORY = "ghcr.io/camstack/camstack";
+var IMAGE_TAG_BY_ACCELERATOR = {
+  intel: "intel-latest",
+  amd: "amd-latest",
+  // No Coral- or CPU-specific image: Intel hosts and the Unraid templates track intel-latest.
+  coral: "intel-latest",
+  cpu: "intel-latest",
+  apple: "intel-latest"
+};
+var NO_BARE_LATEST = "There is no bare :latest tag: use intel-<version>/intel-latest or amd-<version>/amd-latest, and never mix them across vendors.";
+var MUST_NOT_OMIT = [
+  "--pids-limit=8192 (pids_limit: 8192): the default 2048 counts threads and silently stops media on a busy hub.",
+  "CAMSTACK_MEDIA_ROOT=/recordings: without it recordings land in /data and fill the cache drive.",
+  "/config mapped: it is a VOLUME, so an unmapped path mints an anonymous volume on every re-create.",
+  "--restart unless-stopped: the NVR must come back after a host reboot.",
+  "CAMSTACK_MOLECULER_USE_HOSTNAME=false: otherwise a multi-machine cluster never forms.",
+  "Coral USB: /dev/bus/usb AND the device-cgroup rule c 189:* rmw."
+];
+var COMPOSE_MARKERS_BY_ACCELERATOR = {
+  intel: ["devices", "dri", "accel"],
+  amd: ["devices", "dri"],
+  coral: ["devices", "usb"],
+  cpu: [],
+  apple: []
+};
+function firstRunHub(host) {
+  return [
+    `Open https://${host}:4443 (a self-signed certificate: accept the browser warning).`,
+    "Sign in as admin / changeme; CamStack asks for a new password at once. Change it now.",
+    `Then, where your MCP client runs: camstack login ${host}`
+  ];
+}
+
+// src/mcp/setup-compose.ts
+var MARKER_LINE = /^(\s*)# (.*#@([A-Za-z0-9_]+)\s*)$/;
+var VOLUME_HOST_PATHS = [
+  { container: "/data", key: "data" },
+  { container: "/recordings", key: "recordings" },
+  { container: "/config", key: "config" },
+  { container: "/backups", key: "backups" }
+];
+function swapImageTag(body, imageTag) {
+  const escaped = IMAGE_REPOSITORY.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return body.replace(new RegExp(`(${escaped}):[A-Za-z0-9._-]+`), `$1:${imageTag}`);
+}
+function enableMarkers(body, markers) {
+  return body.split("\n").map((line) => {
+    const match = MARKER_LINE.exec(line);
+    if (match === null) return line;
+    const tag = match[3];
+    return tag !== void 0 && markers.includes(tag) ? `${match[1] ?? ""}${match[2] ?? ""}` : line;
+  }).join("\n");
+}
+function setVolumeHosts(body, paths) {
+  const edits = [];
+  let out = body;
+  for (const { container, key } of VOLUME_HOST_PATHS) {
+    const wanted = paths?.[key];
+    const volume = new RegExp(`^(\\s*- )([^\\s:]+)(:${container}\\s*)$`, "m");
+    if (!volume.test(out)) {
+      if (wanted !== void 0) {
+        edits.push(
+          `${container}: no volume line found in the template; map ${wanted} to it yourself`
+        );
+      }
+      continue;
+    }
+    if (wanted === void 0) {
+      edits.push(
+        `${container}: left at the template's host path, change it if that is not where you want it`
+      );
+      continue;
+    }
+    out = out.replace(
+      volume,
+      (_m, pre, _host, post) => `${pre}${wanted}${post}`
+    );
+  }
+  return { body: out, edits };
+}
+function setHubAddress(body, hubAddress) {
+  const line = /^(\s*- CAMSTACK_HUB_ADDRESS=).*$/m;
+  if (!line.test(body)) return { body, edits: [] };
+  if (hubAddress === void 0) {
+    return {
+      body,
+      edits: [
+        "CAMSTACK_HUB_ADDRESS: export it before `docker compose up` (or edit the line) with the hub IP or hostname"
+      ]
+    };
+  }
+  return {
+    body: body.replace(line, (_m, pre) => `${pre}${hubAddress}`),
+    edits: []
+  };
+}
+function customizeCompose(source, c) {
+  const tagged = enableMarkers(swapImageTag(source, c.imageTag), c.markers);
+  const volumes = setVolumeHosts(tagged, c.paths);
+  const hub = setHubAddress(volumes.body, c.hubAddress);
+  return { body: hub.body, edits: [...volumes.edits, ...hub.edits] };
+}
+function unquote(value) {
+  const v = value.trim();
+  if (v.length >= 2 && (v.startsWith('"') || v.startsWith("'")) && v.endsWith(v[0] ?? "")) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+function stripComment(line) {
+  return line.replace(/\s+#.*$/, "");
+}
+function readService(body) {
+  const fields = {
+    scalars: /* @__PURE__ */ new Map(),
+    lists: /* @__PURE__ */ new Map(),
+    maps: /* @__PURE__ */ new Map()
+  };
+  let key = null;
+  let sub = null;
+  for (const raw of body.split("\n")) {
+    if (raw.trim() === "" || raw.trim().startsWith("#")) continue;
+    const line = stripComment(raw);
+    const indent = line.length - line.trimStart().length;
+    const text2 = line.trim();
+    if (indent === 4) {
+      sub = null;
+      const m = /^([A-Za-z_]+):\s*(.*)$/.exec(text2);
+      if (m === null) continue;
+      key = m[1] ?? null;
+      if (key !== null && (m[2] ?? "") !== "") fields.scalars.set(key, unquote(m[2] ?? ""));
+    } else if (indent === 6 && key !== null) {
+      if (text2.startsWith("- ")) {
+        const list = fields.lists.get(key) ?? [];
+        list.push(unquote(text2.slice(2)));
+        fields.lists.set(key, list);
+      } else {
+        const m = /^([A-Za-z_-]+):\s*(.*)$/.exec(text2);
+        if (m === null) continue;
+        sub = m[1] ?? null;
+        const map = fields.maps.get(key) ?? /* @__PURE__ */ new Map();
+        if ((m[2] ?? "") !== "" && sub !== null) map.set(sub, unquote(m[2] ?? ""));
+        fields.maps.set(key, map);
+      }
+    } else if (indent === 8 && key !== null && sub !== null) {
+      const m = /^([A-Za-z_-]+):\s*(.*)$/.exec(text2);
+      if (m === null) continue;
+      const map = fields.maps.get(`${key}.${sub}`) ?? /* @__PURE__ */ new Map();
+      map.set(m[1] ?? "", unquote(m[2] ?? ""));
+      fields.maps.set(`${key}.${sub}`, map);
+    }
+  }
+  return fields;
+}
+function shellQuote(value) {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function composeToDockerRun(body) {
+  const f = readService(body);
+  const image = f.scalars.get("image");
+  if (image === void 0) return null;
+  const args = ["docker run -d"];
+  const name = f.scalars.get("container_name");
+  if (name !== void 0) args.push(`--name ${shellQuote(name)}`);
+  const restart = f.scalars.get("restart");
+  if (restart !== void 0) args.push(`--restart ${shellQuote(restart)}`);
+  const network = f.scalars.get("network_mode");
+  if (network !== void 0) args.push(`--network ${shellQuote(network)}`);
+  const pids = f.scalars.get("pids_limit");
+  if (pids !== void 0) args.push(`--pids-limit=${pids}`);
+  for (const d of f.lists.get("devices") ?? []) args.push(`--device ${shellQuote(d)}`);
+  for (const r of f.lists.get("device_cgroup_rules") ?? []) {
+    args.push(`--device-cgroup-rule ${shellQuote(r)}`);
+  }
+  for (const g of f.lists.get("group_add") ?? []) args.push(`--group-add ${shellQuote(g)}`);
+  for (const v of f.lists.get("volumes") ?? []) args.push(`-v ${shellQuote(v)}`);
+  for (const e of f.lists.get("environment") ?? []) {
+    if (!e.includes("${")) args.push(`-e ${shellQuote(e)}`);
+  }
+  const driver = f.maps.get("logging")?.get("driver");
+  if (driver !== void 0) args.push(`--log-driver ${shellQuote(driver)}`);
+  for (const [k, v] of f.maps.get("logging.options") ?? []) {
+    args.push(`--log-opt ${shellQuote(`${k}=${v}`)}`);
+  }
+  args.push(shellQuote(image));
+  return args.join(" \\\n  ");
+}
+
+// src/mcp/setup-install.ts
+var FETCH_TIMEOUT_MS = 1e4;
+var CONTAINER_ROUTES = ["docker-compose", "docker"];
+var Q_HOST = {
+  id: "hostKind",
+  question: "Where will CamStack run?",
+  options: ["docker-compose", "docker", "unraid", "proxmox-lxc", "macos-desktop"]
+};
+var Q_ROLE = {
+  id: "role",
+  question: "Which role? Start with a hub; an agent only adds a second machine to an existing hub.",
+  options: ["hub", "agent"]
+};
+var Q_ACCEL = {
+  id: "accelerator",
+  question: "Which accelerator does this host have?",
+  options: ["intel", "amd", "coral", "cpu"]
+};
+var Q_PATHS = {
+  id: "paths",
+  question: "Host paths as {data, recordings} (optionally config, backups). Recordings is the one that grows: put it on a roomy disk.",
+  options: []
+};
+function missingQuestions(input) {
+  const out = [];
+  if (input.hostKind === void 0) out.push(Q_HOST);
+  if (input.role === void 0) out.push(Q_ROLE);
+  const desktop = input.hostKind === "macos-desktop";
+  if (!desktop && (input.accelerator === void 0 || input.accelerator === "apple")) {
+    out.push(Q_ACCEL);
+  }
+  if (input.hostKind !== void 0 && CONTAINER_ROUTES.includes(input.hostKind) && input.paths === void 0) {
+    out.push(Q_PATHS);
+  }
+  return out;
+}
+async function fetchText(url, fetchFn) {
+  try {
+    const res = await fetchFn(url, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+    if (!res.ok) {
+      return {
+        ok: false,
+        failure: {
+          status: "fetch-failed",
+          url,
+          error: `answered ${res.status}`
+        }
+      };
+    }
+    return { ok: true, body: await res.text() };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    return { ok: false, failure: { status: "fetch-failed", url, error } };
+  }
+}
+var ReleaseSchema = z2.object({
+  tag_name: z2.string(),
+  assets: z2.array(z2.object({ name: z2.string(), browser_download_url: z2.string() }))
+});
+var DMG = /^CamStack-[0-9][0-9A-Za-z.-]*-(arm64|x64)\.dmg$/;
+function acceleratorEdits(accelerator, role) {
+  const note = `Image tag ${IMAGE_TAG_BY_ACCELERATOR[accelerator]} for ${accelerator}. ${NO_BARE_LATEST}`;
+  return role === "agent" ? [note, "Do not run a hub and an agent on the same host."] : [note];
+}
+async function composeGuide(input, fetchFn, asDockerRun) {
+  const url = TEMPLATE_URLS.compose[input.role];
+  const fetched = await fetchText(url, fetchFn);
+  if (!fetched.ok) return fetched.failure;
+  const imageTag = IMAGE_TAG_BY_ACCELERATOR[input.accelerator];
+  const custom = customizeCompose(fetched.body, {
+    imageTag,
+    markers: COMPOSE_MARKERS_BY_ACCELERATOR[input.accelerator],
+    paths: input.paths,
+    hubAddress: input.hubAddress
+  });
+  const edits = [...custom.edits, ...acceleratorEdits(input.accelerator, input.role)];
+  const first = firstRun(input);
+  if (!asDockerRun) {
+    return ready(input, imageTag, {
+      steps: [
+        "Save docker-compose.yml (below) in an empty directory on the host.",
+        "docker compose up -d && docker compose logs -f camstack",
+        "The first boot seeds addons and pulls models: allow a few minutes.",
+        ...first
+      ],
+      files: [{ path: "docker-compose.yml", body: custom.body, source: url }],
+      edits
+    });
+  }
+  const run = composeToDockerRun(custom.body);
+  if (run === null) {
+    return {
+      status: "fetch-failed",
+      url,
+      error: "the official compose file has no image line; cannot derive docker run"
+    };
+  }
+  return ready(input, imageTag, {
+    steps: [
+      "Create the host directories named by the -v lines, then run the file below as a shell script.",
+      "docker logs -f camstack (the first boot seeds addons and pulls models).",
+      ...first
+    ],
+    files: [{ path: "run-camstack.sh", body: `#!/bin/sh
+${run}
+`, source: url }],
+    edits
+  });
+}
+async function unraidGuide(input, fetchFn) {
+  const url = TEMPLATE_URLS.unraid[input.role];
+  const fetched = await fetchText(url, fetchFn);
+  if (!fetched.ok) return fetched.failure;
+  const imageTag = IMAGE_TAG_BY_ACCELERATOR[input.accelerator];
+  const edits = [
+    `In the template form, set Repository to ${IMAGE_REPOSITORY}:${imageTag} (the template ships intel-latest). ${NO_BARE_LATEST}`,
+    "Recordings: point it at a roomy array share, not the cache; leave Media root as /recordings.",
+    "Keep ExtraParams as shipped: --device-cgroup-rule and --pids-limit=8192.",
+    ...unraidDeviceEdits(input.accelerator)
+  ];
+  const first = firstRun(input);
+  return ready(input, imageTag, {
+    steps: [
+      `Unraid: Docker > Add Container > Template, paste ${url}`,
+      "Review the paths and Repository (edits below), then Apply.",
+      ...first
+    ],
+    files: [{ path: urlName(url), body: fetched.body, source: url }],
+    edits
+  });
+}
+function unraidDeviceEdits(accelerator) {
+  if (accelerator === "intel" || accelerator === "amd") {
+    return ["Intel/AMD iGPU: enter /dev/dri in that field. Intel NPU: enter /dev/accel."];
+  }
+  if (accelerator === "coral") {
+    return ["Coral USB: enter /dev/bus/usb (the whole bus). Coral PCIe/M.2: /dev/apex_0 (and _1)."];
+  }
+  return [];
+}
+function urlName(url) {
+  return url.slice(url.lastIndexOf("/") + 1);
+}
+async function proxmoxGuide(input, fetchFn) {
+  const url = TEMPLATE_URLS.proxmoxInstaller;
+  const fetched = await fetchText(url, fetchFn);
+  if (!fetched.ok) return fetched.failure;
+  const imageTag = IMAGE_TAG_BY_ACCELERATOR[input.accelerator];
+  const vars = [`ROLE=${input.role}`];
+  vars.push(`IMAGE_TAG=${IMAGE_REPOSITORY}:${imageTag}`);
+  if (input.accelerator === "cpu") vars.push("PASS_ACCEL=none");
+  if (input.role === "agent") vars.push(`CAMSTACK_HUB_ADDRESS=${input.hubAddress ?? "<hub-ip>"}`);
+  if (input.paths !== void 0) vars.push(`RECORDINGS_HOST_PATH=${input.paths.recordings}`);
+  const header = fetched.body.split("\n").slice(1, 20).filter((l) => l.startsWith("#")).join("\n");
+  const first = firstRun(input);
+  return ready(input, imageTag, {
+    steps: [
+      "Run on the Proxmox HOST (needs `pct`), not inside a container. It asks nothing: everything is an environment variable (defaults: VMID 200 hub / 201 agent, 8 cores, 8 GB, 64 GB disk, bridge vmbr0).",
+      `${vars.join(" ")} bash -c "$(curl -fsSL ${url})"`,
+      "It builds an Ubuntu 24.04 LXC with Docker, passes through the accelerators the host has (PASS_ACCEL=none skips it) and starts CamStack.",
+      ...first
+    ],
+    files: [
+      {
+        path: "install-camstack-proxmox.sh (header)",
+        body: header,
+        source: url
+      }
+    ],
+    edits: [
+      `The script defaults to the amd image; IMAGE_TAG above sets ${imageTag}. ${NO_BARE_LATEST}`,
+      "A hub and an agent on one machine need two CTs (host networking collides otherwise)."
+    ]
+  });
+}
+async function macGuide(input, fetchFn) {
+  const url = TEMPLATE_URLS.latestRelease;
+  const fetched = await fetchText(url, fetchFn);
+  if (!fetched.ok) return fetched.failure;
+  let release;
+  try {
+    const parsed = ReleaseSchema.safeParse(JSON.parse(fetched.body));
+    if (!parsed.success) {
+      return {
+        status: "fetch-failed",
+        url,
+        error: "the release answer had no assets"
+      };
+    }
+    release = parsed.data;
+  } catch {
+    return {
+      status: "fetch-failed",
+      url,
+      error: "the release answer was not JSON"
+    };
+  }
+  const dmgs = release.assets.filter((a) => DMG.test(a.name));
+  const first = firstRun(input);
+  return ready(input, null, {
+    steps: [
+      `Download the disk image for your Mac from release ${release.tag_name}: ${dmgs.map((a) => `${a.name} (${a.browser_download_url})`).join(" or ")}. Apple silicon (M1 and later) takes arm64; Intel takes x64. The CamStackViewer files are a different app.`,
+      "Drag CamStack into Applications and open it.",
+      `The setup window asks what this Mac should be: choose ${input.role === "hub" ? "Hub (full server)" : "Agent (worker)"}, then Save and start.`,
+      ...first
+    ],
+    files: [],
+    edits: ["A Mac uses the app, not Docker: a container there cannot reach the Neural Engine."]
+  });
+}
+function firstRun(input) {
+  const host = input.hostKind === "macos-desktop" ? "localhost" : "<host>";
+  if (input.role === "hub") return firstRunHub(host);
+  return [
+    "The agent status dashboard answers on http://<agent-host>:4444.",
+    "Pair it from the hub: run setup_add_node (it lists agents found on the network), then in the admin UI Cluster > Nodes > Agents found on the network. Type the six digits shown on the other screen on BOTH sides."
+  ];
+}
+function ready(input, imageTag, body) {
+  return {
+    status: "ready",
+    hostKind: input.hostKind,
+    role: input.role,
+    imageTag,
+    steps: body.steps,
+    files: body.files,
+    edits: body.edits,
+    mustNotOmit: input.hostKind === "macos-desktop" ? [] : MUST_NOT_OMIT
+  };
+}
+async function installGuide(input, fetchFn) {
+  const questions = missingQuestions(input);
+  if (questions.length > 0) return { status: "need-answers", questions };
+  const { hostKind, role } = input;
+  if (hostKind === void 0 || role === void 0) {
+    return { status: "need-answers", questions: missingQuestions({}) };
+  }
+  const resolved = {
+    hostKind,
+    role,
+    accelerator: hostKind === "macos-desktop" ? "apple" : input.accelerator ?? "cpu",
+    paths: input.paths,
+    hubAddress: input.hubAddress
+  };
+  switch (hostKind) {
+    case "docker-compose":
+      return composeGuide(resolved, fetchFn, false);
+    case "docker":
+      return composeGuide(resolved, fetchFn, true);
+    case "unraid":
+      return unraidGuide(resolved, fetchFn);
+    case "proxmox-lxc":
+      return proxmoxGuide(resolved, fetchFn);
+    case "macos-desktop":
+      return macGuide(resolved, fetchFn);
+  }
+}
+
+// src/mcp/setup-hubs.ts
+var DEFAULT_DISCOVER_TIMEOUT_MS = 2500;
+var MAX_DISCOVER_TIMEOUT_MS = 15e3;
+var HEALTH_TIMEOUT_MS = 5e3;
+var LOGIN = (server) => `run \`camstack login ${server}\` in a terminal`;
+var httpsHealth = (url, tls) => new Promise((resolve) => {
+  const req = https.get(
+    `${url}/health`,
+    { agent: createHubAgent(tls), timeout: HEALTH_TIMEOUT_MS },
+    (res) => {
+      res.resume();
+      resolve({ ok: true, status: res.statusCode ?? 0 });
+    }
+  );
+  req.on("timeout", () => req.destroy(new Error("timed out")));
+  req.on("error", (err) => {
+    resolve({
+      ok: false,
+      error: err.message,
+      tlsHint: explainTlsFailure(url, err)
+    });
+  });
+});
+async function discoverHubsTool(timeoutMs, deps) {
+  const wait = Math.min(timeoutMs ?? DEFAULT_DISCOVER_TIMEOUT_MS, MAX_DISCOVER_TIMEOUT_MS);
+  const finder = deps.findHubs ?? ((ms) => findHubs({
+    mdnsTimeoutMs: ms,
+    ...deps.sessionDir !== void 0 ? { sessionDir: deps.sessionDir } : {},
+    ...deps.env !== void 0 ? { env: deps.env } : {}
+  }));
+  const found = await finder(wait);
+  const hubs = found.map((h) => ({
+    host: h.host,
+    port: h.port,
+    name: h.nodeId,
+    version: h.version,
+    sources: h.sources
+  }));
+  return {
+    status: "ok",
+    hubs,
+    next: hubs.length === 0 ? "no hub answered: install one with setup_install_guide, or pass its address to setup_connect" : "pass the host of the hub you want to setup_connect"
+  };
+}
+function pinnedTls(url, deps) {
+  const caFile = hubCaFileForServer(url, deps.sessionDir);
+  try {
+    return {
+      tls: resolveHubTls(url, deps.env ?? process.env, deps.sessionDir),
+      caFile
+    };
+  } catch {
+    return { tls: {}, caFile };
+  }
+}
+async function connectTool(server, deps) {
+  let url;
+  try {
+    url = normalizeHubAddress(server);
+  } catch (err) {
+    const message = err instanceof HubAddressError ? err.message : String(err);
+    return { status: "invalid-address", server, message };
+  }
+  const { tls, caFile } = pinnedTls(url, deps);
+  const outcome = await (deps.health ?? httpsHealth)(url, tls);
+  const caPinned = tls.ca !== void 0;
+  const session = loadSession(url, deps.sessionDir);
+  const sessionInfo = {
+    exists: session !== null,
+    username: session?.username ?? null
+  };
+  if (!outcome.ok) {
+    return {
+      status: "unreachable",
+      server: url,
+      message: outcome.error,
+      tls: { caPinned, caFile, hint: outcome.tlsHint },
+      session: sessionInfo,
+      next: outcome.tlsHint === null ? "check the host, that the hub is running, and that port 4443 is reachable" : `the hub answers but its certificate is not trusted: ${LOGIN(url)}; login pins the CA (never disable verification)`
+    };
+  }
+  return {
+    status: "reachable",
+    server: url,
+    health: { status: outcome.status },
+    tls: { caPinned, caFile, hint: null },
+    session: sessionInfo,
+    next: session === null ? LOGIN(url) : "a session exists: the ops tools can use it"
+  };
+}
+var DiscoveredAgentsSchema = z3.object({
+  agents: z3.array(
+    z3.object({
+      nodeId: z3.string(),
+      host: z3.string(),
+      port: z3.number(),
+      version: z3.string().nullable(),
+      name: z3.string().nullable(),
+      state: z3.enum(["unpaired", "pending", "paired"])
+    })
+  )
+});
+var PAIRING_STEPS = [
+  "Pairing is started from the HUB (D857): admin UI, Cluster > Nodes > Agents found on the network. Pick the agent, or add it by address (host and port 4444).",
+  "Both screens now show six digits. Type the digits shown on the OTHER screen, on BOTH sides: the hub operator types the code the agent shows, and the agent operator confirms on the agent.",
+  "The agent installs its certificate only after its own operator confirmed. Nothing here (and no tool of this MCP) confirms a pairing for you.",
+  "The agent then appears under Cluster > Nodes."
+];
+async function addNodeTool(input, ctx) {
+  const guide = await installGuide({ ...input, role: "agent" }, ctx.fetch);
+  const outcome = await ctx.hub();
+  if (!outcome.ok) {
+    return {
+      guide,
+      pairing: PAIRING_STEPS,
+      agentsOnNetwork: { status: "no-session", action: outcome.action }
+    };
+  }
+  try {
+    const raw = await outcome.connection.client.call("GET", "agentPairing.listDiscoveredAgents", {});
+    const parsed = DiscoveredAgentsSchema.safeParse(raw);
+    return {
+      guide,
+      pairing: PAIRING_STEPS,
+      agentsOnNetwork: parsed.success ? { status: "ok", agents: parsed.data.agents } : {
+        status: "unavailable",
+        error: "the hub answered in an unexpected shape"
+      }
+    };
+  } catch (err) {
+    return {
+      guide,
+      pairing: PAIRING_STEPS,
+      agentsOnNetwork: {
+        status: "unavailable",
+        error: err instanceof Error ? err.message : String(err)
+      }
+    };
+  }
+}
+
+// src/mcp/setup-tools.ts
+var SUPPORTED_HOST_KINDS = HOST_KINDS;
+var REGISTRY = "https://registry.npmjs.org";
+var REGISTRY_TIMEOUT_MS = 5e3;
+var RegistryLatestSchema = z4.object({ version: z4.string() });
+async function latestOnNpm(name, fetchFn) {
+  const url = `${REGISTRY}/${name.replace("/", "%2f")}/latest`;
+  try {
+    const res = await fetchFn(url, {
+      signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS)
+    });
+    if (!res.ok) return { latest: null, error: `registry answered ${res.status}` };
+    const parsed = RegistryLatestSchema.safeParse(await res.json());
+    if (!parsed.success) return { latest: null, error: "registry answer had no version" };
+    return { latest: parsed.data.version };
+  } catch (err) {
+    return {
+      latest: null,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function about(ctx) {
+  const [cli, server] = await Promise.all([
+    latestOnNpm("camstack", ctx.fetch),
+    latestOnNpm("@camstack/server", ctx.fetch)
+  ]);
+  return {
+    cli: { installed: ctx.cliVersion, ...cli },
+    server,
+    supportedHostKinds: SUPPORTED_HOST_KINDS
+  };
+}
+function registerSetupTools(server, ctx, deps = {}) {
+  server.tool(
+    "setup_about",
+    "Versions of the camstack CLI (installed and latest on npm), the latest @camstack/server on npm, and the host kinds CamStack supports. Needs no hub and no login.",
+    {},
+    async () => text(await about(ctx))
+  );
+  server.tool(
+    "setup_install_guide",
+    'Interview-style install guide. Call it with whatever you know; while an answer is missing it returns {status:"need-answers", questions} listing only what is still unknown. When complete it returns the steps and the OFFICIAL template files (fetched live) for that route: docker-compose, docker, unraid, proxmox-lxc or macos-desktop. Start with a hub.',
+    {
+      hostKind: HostKindSchema.optional(),
+      role: RoleSchema.optional(),
+      accelerator: AcceleratorSchema.optional(),
+      paths: InstallPathsSchema.optional(),
+      hubAddress: z4.string().min(1).optional().describe("Agents only: the hub to dial.")
+    },
+    async (input) => text(await installGuide(input, ctx.fetch))
+  );
+  server.tool(
+    "setup_discover_hubs",
+    "Find CamStack hubs on the local network (mDNS) plus the hubs this machine already knows, with host, port, name and version. Needs no login.",
+    { timeoutMs: z4.number().int().min(200).max(15e3).optional() },
+    async ({ timeoutMs }) => text(await discoverHubsTool(timeoutMs, deps))
+  );
+  server.tool(
+    "setup_connect",
+    "Check that a hub answers on https://<server>:4443/health, whether its CA is already pinned for TLS, and whether a `camstack login` session exists. Never takes a password: when there is no session it says to run `camstack login <server>` in a terminal.",
+    { server: z4.string().min(1) },
+    async ({ server: address }) => text(await connectTool(address, deps))
+  );
+  server.tool(
+    "setup_add_node",
+    "Guide to add an AGENT (a second machine) to a hub: the install route for that host, then the pairing flow where the operator types the six digits shown on the other screen on both sides. With a login session it also lists the agents found on the network. It never confirms a pairing.",
+    {
+      hostKind: HostKindSchema.optional(),
+      accelerator: AcceleratorSchema.optional(),
+      paths: InstallPathsSchema.optional(),
+      hubAddress: z4.string().min(1).optional()
+    },
+    async (input) => text(await addNodeTool(input, ctx))
+  );
+}
+
+// src/mcp/ops-update-cli.ts
+import { execFile } from "child_process";
+var CLI_PACKAGE = "camstack";
+var NPM_GLOBAL = /[\\/]lib[\\/]node_modules[\\/]camstack[\\/]|[\\/]npm[\\/]node_modules[\\/]camstack[\\/]/;
+var OTHER_MANAGER = /[\\/]\.bun[\\/]|[\\/]pnpm[\\/]|[\\/]\.yarn[\\/]|[\\/]yarn[\\/]|[\\/]\.volta[\\/]/;
+function detectCliInstall(entryPath) {
+  const manual = `Update it with the package manager it was installed with, for example \`npm install -g ${CLI_PACKAGE}@latest\` (no sudo: fix the npm prefix permissions instead).`;
+  if (/[\\/]_npx[\\/]/.test(entryPath)) {
+    return {
+      method: "npx",
+      command: null,
+      instructions: `The CLI runs through npx: there is nothing installed to update. Start it as \`npx ${CLI_PACKAGE}@latest mcp\` (or clear the npx cache), then restart the MCP in your client.`
+    };
+  }
+  if (OTHER_MANAGER.test(entryPath) || !NPM_GLOBAL.test(entryPath)) {
+    return { method: "unknown", command: null, instructions: manual };
+  }
+  return {
+    method: "npm-global",
+    command: ["npm", "install", "-g", `${CLI_PACKAGE}@latest`],
+    instructions: `npm install -g ${CLI_PACKAGE}@latest`
+  };
+}
+var runCommand = (file, args) => new Promise((resolve) => {
+  execFile(file, [...args], { timeout: 5 * 6e4 }, (err, stdout, stderr) => {
+    const out = `${stdout}${stderr}`.trim().slice(-600);
+    resolve({
+      ok: err === null,
+      output: err ? `${err.message} ${out}`.trim() : out
+    });
+  });
+});
+function parts(v) {
+  return v.split("-")[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
+}
+function isOlder(a, b) {
+  const x = parts(a);
+  const y = parts(b);
+  for (let i = 0; i < 3; i++) {
+    const d = (x[i] ?? 0) - (y[i] ?? 0);
+    if (d !== 0) return d < 0;
+  }
+  return false;
+}
+async function cliVerdict(installed, fetchFn, entryPath) {
+  const latest = await latestOnNpm(CLI_PACKAGE, fetchFn);
+  return {
+    installed,
+    latest: latest.latest,
+    updateAvailable: latest.latest === null ? null : isOlder(installed, latest.latest),
+    ...latest.error !== void 0 ? { error: latest.error } : {},
+    install: detectCliInstall(entryPath)
+  };
+}
+
+export {
+  text,
+  IMAGE_TAG_BY_ACCELERATOR,
+  NO_BARE_LATEST,
+  MUST_NOT_OMIT,
+  latestOnNpm,
+  registerSetupTools,
+  runCommand,
+  isOlder,
+  cliVerdict
+};