nomarmy 0.1.0-alpha.2 → 0.1.0-alpha.21

package/lib/dispatch-schema.mjs

@@ -15,10 +15,12 @@
 //     never in a file nomArmy writes or reads back.
 
 import { z } from "zod";
+import { typeError, isMissingField, isUnknownDiscriminator } from "./zod-issues.mjs";
+import { THINKING_LEVELS } from "./thinking.mjs";
 
 const requiredString = () =>
   z
-    .string({ required_error: "is required", invalid_type_error: "must be a string" })
+    .string({ error: typeError("a string") })
     .refine((value) => value.trim().length > 0, { message: "must not be empty" });
 
 // Exported (not just used internally) so bin/nomarmy.mjs's interactive
@@ -101,11 +103,11 @@ export function isNativeProviderType(type) {
 export const CUSTOM_ENDPOINT_PROVIDER_TYPES = Object.freeze(["bedrock", "azure-openai", "openai-compatible"]);
 
 const idSchema = z
-  .string({ required_error: "is required", invalid_type_error: "must be a string" })
+  .string({ error: typeError("a string") })
   .regex(ID_RE, "must be 1-64 characters of letters, numbers, dot, underscore or hyphen");
 
 const weightSchema = z
-  .number({ required_error: "is required", invalid_type_error: "must be a number" })
+  .number({ error: typeError("a number") })
   .positive("must be a positive number")
   .finite("must be a finite number");
 
@@ -113,13 +115,13 @@ const weightSchema = z
 // one entry at once -- a stand-in for real rate-limit-aware admission (see
 // README's dispatch-pool section for why that's out of scope for now).
 const maxConcurrentSchema = z
-  .number({ invalid_type_error: "must be a number" })
+  .number({ error: typeError("a number") })
   .int("must be a whole number")
   .positive("must be a positive number")
   .default(2);
 
 const authEnvSchema = z
-  .string({ required_error: "is required", invalid_type_error: "must be a string" })
+  .string({ error: typeError("a string") })
   .regex(
     AUTH_ENV_NAME_RE,
     "must be an environment variable NAME (uppercase letters, digits, underscores), never the credential itself",
@@ -127,7 +129,7 @@ const authEnvSchema = z
 
 const urlSchema = () =>
   z
-    .string({ required_error: "is required", invalid_type_error: "must be a string" })
+    .string({ error: typeError("a string") })
     .url("must be a valid URL");
 
 // Whether/how the entry's model uses a thinking/reasoning mode. `true`
@@ -143,7 +145,7 @@ const urlSchema = () =>
 // OpenClaw names as supported (see parseUnsupportedThinkingError) -- so a
 // level this schema accepts is never a guarantee the provider/model
 // combination honors it today, only what to keep asking for.
-const thinkingSchema = z.union([z.boolean(), z.enum(["low", "medium", "high"])]).default(true);
+const thinkingSchema = z.union([z.boolean(), z.enum(THINKING_LEVELS)]).default(true);
 
 // Optional override for the model's real context window, in tokens. Absent
 // (the common case), lib/dispatch-config.mjs looks this up from OpenClaw's
@@ -152,7 +154,7 @@ const thinkingSchema = z.union([z.boolean(), z.enum(["low", "medium", "high"])])
 // knows about yet (see lib/model-catalog.mjs), or an operator who wants to
 // be more conservative than the model's rated maximum.
 const contextWindowSchema = z
-  .number({ invalid_type_error: "must be a number" })
+  .number({ error: typeError("a number") })
   .int("must be a whole number")
   .positive("must be a positive number")
   .optional();
@@ -189,7 +191,7 @@ const llamaCppEntrySchema = z
 // `agents add` installs it before registering the key.
 const genericOpenclawEntrySchema = hostedProviderSchema("openclaw", { requireBaseUrl: false }).extend({
   openclaw_provider: z
-    .string({ required_error: "is required", invalid_type_error: "must be a string" })
+    .string({ error: typeError("a string") })
     .regex(OPENCLAW_PROVIDER_ID_RE, "must be an OpenClaw provider id (lowercase letters, digits, dot, underscore, hyphen)")
     .refine((id) => !PROVIDER_TYPES.includes(id) || NATIVE_PROVIDER_TYPES.includes(id), "names a nomArmy provider type with its own setup -- use that type instead"),
   plugin: z.string().regex(/^\S+$/, "must be one plugin install spec, e.g. clawhub:@openclaw/deepseek-provider").optional(),
@@ -205,7 +207,7 @@ export const providerEntrySchema = z.discriminatedUnion("provider", [
 export const poolsSchema = z.record(
   z.string().min(1, "pool name must not be empty"),
   z
-    .array(providerEntrySchema, { invalid_type_error: "must be an array of provider entries" })
+    .array(providerEntrySchema, { error: typeError("an array of provider entries") })
     .min(1, "must list at least one provider entry"),
 );
 
@@ -250,11 +252,11 @@ export function formatDispatchIssues(error) {
       lines.push(`${where}: unexpected field(s) ${keys}`);
       continue;
     }
-    if (issue.code === "invalid_union_discriminator") {
+    if (isUnknownDiscriminator(issue)) {
       lines.push(`${where}: must be one of ${PROVIDER_TYPES.join(", ")}`);
       continue;
     }
-    if (issue.code === "invalid_type" && issue.received === "undefined") {
+    if (isMissingField(issue)) {
       lines.push(`${where}: is required`);
       continue;
     }

package/lib/doctor.mjs

@@ -8,8 +8,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { executionMode } from "./execution.mjs";
+import { maxJobs, jobsThatFit, vmGibFor } from "./limits.mjs";
 
 const MIN_NODE_MAJOR = 18;
 const DEFAULT_LLAMA_HOST = "127.0.0.1";
@@ -144,12 +145,19 @@ export function checkGitLongPaths(facts) {
  * @param {{podmanFound: boolean}} facts
  * @returns {{ok: boolean, message: string, fix?: string}}
  */
+/** How to install Podman here. On Windows and macOS it runs in a small VM that needs creating once. */
+export function installPodmanHint(platform = process.platform) {
+  if (platform === "win32") return "Install Podman ('winget install RedHat.Podman'), then create its VM once: 'podman machine init --memory 8192' and 'podman machine start' (it uses WSL2)";
+  if (platform === "darwin") return "Install Podman ('brew install podman'), then create its VM once: 'podman machine init --memory 8192' and 'podman machine start'";
+  return "Install Podman with your distro's package manager (e.g. 'sudo apt install podman')";
+}
+
 export function checkPodmanPresent(facts) {
   if (facts.podmanFound) return { ok: true, message: "podman is available." };
   return {
     ok: false,
     message: "podman executable not found.",
-    fix: "Install Podman ('brew install podman' on macOS, or your distro's package manager on Linux) and ensure 'podman' is on your PATH.",
+    fix: `${installPodmanHint(facts.platform)}, and make sure 'podman' is on your PATH.`,
   };
 }
 
@@ -161,12 +169,62 @@ export function checkPodmanPresent(facts) {
  * @param {{podmanFound: boolean, podmanDaemonReachable: boolean, podmanDaemonError?: string|null}} facts
  * @returns {{ok: boolean, message: string, fix?: string}}
  */
+// Below this the Podman VM (macOS, Windows) can't hold a sandbox, a
+// verification run and an image build at once. Seen live at 2 GiB: every
+// sandbox command a worker ran came back "Aborted", reads included.
+export const MIN_PODMAN_VM_MB = 4096;
+const RECOMMENDED_PODMAN_VM_MB = 8192;
+
+/**
+ * Rootless Podman needs a range of subordinate IDs to run an image whose
+ * files belong to other users (nomArmy's does). Seen live after a VM
+ * restart: /etc/subuid and /etc/subgid emptied, one ID mapped, and every
+ * sandbox failed with "error during chown ... permission denied".
+ */
+export function checkPodmanIdMappings(facts) {
+  const ids = facts.podmanIdMappings;
+  if (!ids || !ids.rootless) return { ok: true, message: "Podman ID mappings: not applicable (rootful, or Podman not answering)." };
+  if (ids.uid >= 2 && ids.gid >= 2) return { ok: true, message: "Podman has its subordinate ID ranges." };
+  return {
+    ok: false,
+    message: "Rootless Podman has no subordinate ID ranges (/etc/subuid, /etc/subgid are empty), so no sandbox can start: containers fail with \"error during chown ... permission denied\".",
+    fix: "nomarmy sandbox --repair  (on Linux: add a range for your user to /etc/subuid and /etc/subgid, then run podman system migrate)",
+  };
+}
+
+/** The Podman VM's memory: only where Podman runs in a VM (macOS, Windows). */
+export function checkPodmanMachineMemory(facts) {
+  const mb = facts.podmanMachineMemoryMb;
+  if (!Number.isFinite(mb)) return { ok: true, message: "Podman VM memory: not applicable (Podman runs natively here, or no machine is running)." };
+  const gib = (mb / 1024).toFixed(mb % 1024 ? 1 : 0);
+  if (mb >= MIN_PODMAN_VM_MB) return { ok: true, message: `Podman VM has ${gib} GiB of memory.` };
+  return {
+    ok: false,
+    message: `The Podman VM has only ${gib} GiB of memory. Sandboxes, verification and image builds share it, and at this size worker commands get cut off ("Aborted").`,
+    fix: `nomarmy sandbox --memory ${RECOMMENDED_PODMAN_VM_MB / 1024}`,
+  };
+}
+
+/** Whether the Podman VM fits the api and subscription jobs the operator allowed at once. */
+export function checkPodmanVmFitsJobs(facts) {
+  const fit = jobsThatFit(facts.podmanMachineMemoryMb);
+  const limit = facts.maxJobs;
+  if (limit?.problem) return { ok: false, message: limit.problem, fix: "nomarmy config max-jobs <n>" };
+  if (fit === null || !limit) return { ok: true, message: "Jobs at once vs Podman VM: not applicable." };
+  if (limit.value <= fit) return { ok: true, message: `Up to ${limit.value} api and subscription jobs at once; the Podman VM fits about ${fit}.` };
+  return {
+    ok: false,
+    message: `Up to ${limit.value} api and subscription jobs may run at once, but the Podman VM (${(facts.podmanMachineMemoryMb / 1024).toFixed(0)} GiB) fits about ${fit} sandboxes; the rest get refused for memory or cut off.`,
+    fix: `nomarmy sandbox --memory ${vmGibFor(limit.value)}  (or lower the limit: nomarmy config max-jobs ${fit})`,
+  };
+}
+
 export function checkPodmanDaemon(facts) {
   if (!facts.podmanFound) {
     return {
       ok: false,
       message: "Podman check skipped: podman executable not found.",
-      fix: "Install Podman ('brew install podman' on macOS, or your distro's package manager on Linux), then re-run 'nomarmy doctor'.",
+      fix: `${installPodmanHint(facts.platform)}, then re-run 'nomarmy doctor'.`,
     };
   }
   if (facts.podmanDaemonReachable) {
@@ -197,11 +255,11 @@ export function checkEndpoint(facts) {
     };
   }
   if (execution === "remote") return checkRemoteEndpoint(endpoint);
-  if (execution === "local") return checkLocalEndpoint(endpoint);
+  if (execution === "local") return checkLocalEndpoint(endpoint, facts.platform);
   return {
     ok: false,
     message: `NOMARMY_EXECUTION '${execution}' is not recognized.`,
-    fix: "Set NOMARMY_EXECUTION to 'local', 'remote', 'hosted', or 'bedrock' (see config/common.env).",
+    fix: "Set NOMARMY_EXECUTION to 'local', 'remote', 'hosted', or 'bedrock' (nomarmy setup --choose, or ~/.config/nomarmy/common.env).",
   };
 }
 
@@ -215,13 +273,14 @@ function checkRemoteEndpoint(endpoint) {
   };
 }
 
-function checkLocalEndpoint(endpoint) {
+function checkLocalEndpoint(endpoint, platform = process.platform) {
   const { url, healthy, error } = endpoint;
   if (healthy) return { ok: true, message: `llama-server is healthy at ${url}.` };
   return {
     ok: false,
     message: `llama-server health check failed at ${url}${error ? `: ${error}` : "."}`,
-    fix: "Start the local worker with './scripts/start-inference.sh' (after 'source scripts/lib.sh && load_profile <profile>'), then re-run 'nomarmy doctor'.",
+    // Most people run jobs on API and subscription agents: say how to choose that, not only how to start a model.
+    fix: `No local model is running. If your jobs run on API keys or subscriptions, choose that with 'nomarmy setup --choose' (hosted). To run a model on this machine: ${platform === "win32" ? "see docs/install.md#windows (the local model needs WSL2 or a native llama.cpp build)" : "'nomarmy start <profile>'"}. Then re-run 'nomarmy doctor'.`,
   };
 }
 
@@ -231,7 +290,7 @@ function checkBedrockEndpoint(endpoint) {
     return {
       ok: false,
       message: "NOMARMY_BEDROCK_REGION is not set.",
-      fix: "Set NOMARMY_BEDROCK_REGION, e.g. export NOMARMY_BEDROCK_REGION=eu-west-2 (see config/profiles/bedrock.env).",
+      fix: "Set NOMARMY_BEDROCK_REGION, e.g. export NOMARMY_BEDROCK_REGION=eu-west-2 (or set it in ~/.config/nomarmy/common.env).",
     };
   }
   if (!regionValid) {
@@ -253,6 +312,27 @@ function checkBedrockEndpoint(endpoint) {
 
 // --- fact collection: every side effect the checks above need lives here ---
 
+/** Rootless mode and how many UID/GID ranges Podman maps, or null. */
+function probePodmanIdMappings(podmanPath, platform) {
+  try {
+    const result = spawnSync(podmanPath, ["info", "--format", "json"], { encoding: "utf8", timeout: 5000, shell: platform === "win32" && /\.(cmd|bat)$/i.test(podmanPath) });
+    const host = JSON.parse(result.stdout || "{}").host ?? {};
+    return { rootless: Boolean(host.security?.rootless), uid: host.idMappings?.uidmap?.length ?? 0, gid: host.idMappings?.gidmap?.length ?? 0 };
+  } catch { return null; }
+}
+
+/** The running Podman machine's memory in MiB, or null (Linux, or no machine). */
+function probePodmanMachineMemory(podmanPath, platform) {
+  if (!["darwin", "win32"].includes(platform)) return null;
+  try {
+    const result = spawnSync(podmanPath, ["machine", "inspect"], { encoding: "utf8", timeout: 5000, shell: platform === "win32" && /\.(cmd|bat)$/i.test(podmanPath) });
+    const machines = JSON.parse(result.stdout || "[]");
+    const running = machines.find((m) => m.State === "running") ?? machines[0];
+    const mb = Number(running?.Resources?.Memory);
+    return Number.isFinite(mb) && mb > 0 ? mb : null;
+  } catch { return null; }
+}
+
 /**
  * Probe whether podman actually answers, not just whether the CLI exists.
  * The output of `podman info` is not parsed here, only the exit code matters,
@@ -438,6 +518,9 @@ export async function collectFacts(env = process.env) {
     podmanFound: Boolean(podmanPath),
     podmanDaemonReachable: podmanDaemon.reachable,
     podmanDaemonError: podmanDaemon.error,
+    podmanMachineMemoryMb: podmanPath && podmanDaemon.reachable ? probePodmanMachineMemory(podmanPath, platform) : null,
+    maxJobs: maxJobs({ env }),
+    podmanIdMappings: podmanPath && podmanDaemon.reachable ? probePodmanIdMappings(podmanPath, platform) : null,
     execution,
     endpoint,
   };
@@ -455,6 +538,9 @@ export function evaluateChecks(facts) {
     { id: "git-longpaths", ...checkGitLongPaths(facts) },
     { id: "podman", ...checkPodmanPresent(facts) },
     { id: "podman-daemon", ...checkPodmanDaemon(facts) },
+    { id: "podman-vm-memory", ...checkPodmanMachineMemory(facts) },
+    { id: "podman-vm-jobs", ...checkPodmanVmFitsJobs(facts) },
+    { id: "podman-idmap", ...checkPodmanIdMappings(facts) },
     { id: "endpoint", ...checkEndpoint(facts) },
   ];
 }
@@ -467,7 +553,10 @@ export function evaluateChecks(facts) {
 export async function runDoctor(opts = {}) {
   const { json = false, exit = false, env = process.env } = opts;
   const facts = opts.facts ?? await collectFacts(env);
-  const checks = evaluateChecks(facts);
+  const { runtimeIssues } = await import("./health.mjs");
+  const runtime = opts.runtime ? await runtimeIssues(opts.runtime) : [];
+  const checks = [...evaluateChecks(facts), ...(opts.additionalChecks ?? []),
+    ...runtime.map((issue) => ({ id: issue.id, ok: false, message: `${issue.title}. ${issue.detail}`, fix: issue.fix }))];
   const allOk = checks.every((c) => c.ok);
   const result = { ok: allOk, checks };
 

package/lib/egress-proxy.mjs

@@ -0,0 +1,116 @@
+// Verification-only egress boundary. Built-ins only; safe to mount in the base image.
+import { createHash, timingSafeEqual } from 'node:crypto';
+import http from 'node:http';
+import net from 'node:net';
+import { lookup } from 'node:dns/promises';
+import { pathToFileURL } from 'node:url';
+
+export function target(value, defaultPort = 443) {
+  if (typeof value !== 'string' || value.length > 260) throw new Error('invalid target');
+  const match = /^([a-zA-Z0-9.-]+)(?::([0-9]{1,5}))?$/.exec(value);
+  if (!match) throw new Error('invalid target');
+  const host = match[1].toLowerCase(), port = Number(match[2] ?? defaultPort);
+  const labels = host.split('.');
+  if (net.isIP(host) || labels.length < 2 || labels.some(l => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(l)) ||
+      !/^[a-z]{2,63}$/.test(labels.at(-1)) ||
+      /(?:^|\.)(?:localhost|local|localdomain|internal|intranet|private|corp|lan|home|test|invalid|onion|arpa)$/.test(host) ||
+      port < 1 || port > 65535) throw new Error('invalid target');
+  return { host, port, authority: `${host}:${port}` };
+}
+
+// Conservative globally routable unicast only. Reject IPv6 transition/mapped
+// forms too: they can encode IPv4 private destinations or depend on a relay.
+export function publicAddress(address) {
+  if (net.isIP(address) === 4) {
+    const [a, b, c] = address.split('.').map(Number);
+    return !(a === 0 || a === 10 || a === 127 || a >= 224 || address === "168.63.129.16" ||
+      (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254) ||
+      (a === 172 && b >= 16 && b <= 31) || (a === 192 && (b === 168 || b === 0 || (b === 88 && c === 99))) ||
+      (a === 198 && (b === 18 || b === 19 || (b === 51 && c === 100))) ||
+      (a === 203 && b === 0 && c === 113));
+  }
+  if (net.isIP(address) !== 6) return false;
+  // 2000::/3, excluding special-purpose 2001::/23 and 2002::/16.
+  if (address.includes('.')) return false;
+  const halves = address.toLowerCase().split('::');
+  const left = halves[0] ? halves[0].split(':') : [];
+  const right = halves[1] ? halves[1].split(':') : [];
+  const parts = halves.length === 2 ? [...left, ...Array(8 - left.length - right.length).fill('0'), ...right] : left;
+  if (parseInt(parts[5], 16) === 0x5efe || parseInt(parts[4], 16) === 0x5efe) return false;
+  const first = parseInt(parts[0], 16), second = parseInt(parts[1] || '0', 16);
+  return first >= 0x2000 && first <= 0x3fff && first !== 0x2002 &&
+    !(first === 0x2001 && (second <= 0x1ff || second === 0xdb8)) &&
+    !(first === 0x3fff && second <= 0xfff);
+}
+
+export function createEgressProxy({ allow, token, resolve = host => lookup(host, { all: true }), log = () => {}, connect = opts => net.connect(opts), request = opts => http.request(opts) }) {
+  if (typeof token !== 'string' || !token) throw new Error('proxy token required');
+  const digest = value => createHash('sha256').update(value).digest();
+  const expected = digest('Basic ' + Buffer.from('nomarmy:' + token).toString('base64'));
+  const authenticated = req => timingSafeEqual(expected, digest(String(req.headers['proxy-authorization'] ?? '')));
+  const allowed = new Set(allow.map(v => target(v).authority));
+  async function authorize(value, port) {
+    let parsed;
+    try {
+      parsed = target(value, port);
+      if (!allowed.has(parsed.authority)) throw new Error('unlisted');
+      const addresses = await resolve(parsed.host);
+      if (!addresses.length || addresses.some(a => !publicAddress(a.address))) throw new Error('private address');
+      return { ...parsed, address: addresses[0].address };
+    } catch {
+      // Never echo malformed input (it may contain a URL password or payload).
+      log(`${parsed?.authority ?? 'invalid:0'} denied`);
+      throw new Error('denied');
+    }
+  }
+  const server = http.createServer(async (req, res) => {
+    if (!authenticated(req)) { res.writeHead(407, { 'Proxy-Authenticate': 'Basic realm="verification"' }); res.end(); return; }
+    let destination, url, checking = false;
+    try {
+      url = new URL(req.url);
+      if (url.protocol !== 'http:' || url.username || url.password || url.hash) throw new Error('invalid');
+      checking = true;
+      destination = await authorize(url.host, 80);
+    } catch { if (!checking) log("invalid:0 denied"); res.writeHead(403); res.end(); return; }
+    const headers = { ...req.headers, host: destination.authority };
+    for (const name of String(req.headers.connection ?? '').split(',').map(s => s.trim().toLowerCase())) delete headers[name];
+    for (const name of ['proxy-authorization', 'proxy-authenticate', 'connection', 'keep-alive', 'upgrade', 'te', 'trailer']) delete headers[name];
+    headers.host = destination.authority;
+    const upstream = request({ hostname: destination.address, port: destination.port, method: req.method, path: url.pathname + url.search, headers, agent: false });
+    upstream.on('socket', socket => socket.once('connect', () => log(`${destination.authority} connected`)));
+    upstream.on('response', reply => { res.writeHead(reply.statusCode, reply.headers); reply.pipe(res); });
+    upstream.on('error', () => { log(`${destination.authority} denied`); if (!res.headersSent) res.writeHead(502); res.end(); });
+    upstream.setTimeout(30_000, () => upstream.destroy());
+    req.on('aborted', () => upstream.destroy());
+    res.on('close', () => upstream.destroy());
+    req.pipe(upstream);
+  });
+  server.on('connect', async (req, client, head) => {
+    client.on('error', () => {});
+    if (!authenticated(req)) { client.end('HTTP/1.1 407 Proxy Authentication Required\r\nProxy-Authenticate: Basic realm="verification"\r\nConnection: close\r\n\r\n'); return; }
+    let destination;
+    try { destination = await authorize(req.url, 443); }
+    catch { client.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); return; }
+    if (client.destroyed) return;
+    const upstream = connect({ host: destination.address, port: destination.port });
+    upstream.setTimeout(30_000, () => upstream.destroy());
+    upstream.on('error', () => { log(`${destination.authority} denied`); client.destroy(); });
+    client.on('close', () => upstream.destroy());
+    upstream.on('close', () => client.destroy());
+    upstream.on('connect', () => {
+      log(`${destination.authority} connected`);
+      client.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+      if (head.length) upstream.write(head);
+      client.pipe(upstream); upstream.pipe(client);
+    });
+  });
+  server.on('clientError', (_error, socket) => socket.destroy());
+  server.on('upgrade', (_req, socket) => socket.destroy());
+  server.headersTimeout = 10_000;
+  server.requestTimeout = 30_000;
+  return server;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  createEgressProxy({ token: process.env.NOMARMY_EGRESS_TOKEN, allow: JSON.parse(process.env.NOMARMY_EGRESS_ALLOW), log: line => process.stdout.write(`${line}\n`) }).listen(3128, '0.0.0.0');
+}