@xuda.io/ai_module 1.1.5656 → 1.1.5658

package/xudex_runtime.mjs

@@ -0,0 +1,200 @@
+// Xudex runtime: the seam between what runs and where it runs.
+//
+// See docs/plans/xudex.md section 3.8. Every layer above this one (the engine, the
+// verify loop, preview, git, the run tracker) talks to a WORKSPACE and must never
+// know whether that workspace is a persistent VM, an ephemeral runner, a container
+// or a microVM. Section 3.2 says the Proxmox VM is a v1 choice made because we
+// already operate it, not the end state, and 3.9 puts a number on when it has to
+// change. This file is what makes that change one implementation instead of a
+// rewrite, so the rule is simple: nothing above here may reach past the workspace
+// handle to a VM id, an ssh command or a host path.
+//
+// Built BEFORE any substrate, deliberately. An interface written after a VM exists
+// is an interface shaped like a VM.
+//
+// ── The contracts ──────────────────────────────────────────────────────────────
+//
+// A SUBSTRATE is a way of getting compute:
+//   { kind, available(), acquire(req) -> workspace }
+//
+// A WORKSPACE is one project's working area, already prepared:
+//   {
+//     id, kind, project_id, dir,
+//     exec(argv, opts)        -> { exit_code, stdout, stderr, timed_out, ms }
+//     read_file(rel)          -> string
+//     write_file(rel, data)   -> true
+//     list_dir(rel)           -> [names]
+//     expose_port(port)       -> { url } | null
+//     release(opts)           -> true            // opts.destroy: keep nothing
+//   }
+//
+// exec NEVER throws on a non-zero exit: a failing build is data the verify loop
+// needs, not an exception. It throws only when the command could not be run at all.
+//
+// ── Why the factory ────────────────────────────────────────────────────────────
+// index.mjs already owns `run_process`, whose detached process-group kill is the
+// only thing that reliably stops a Codex run (Node's own spawn timeout kills the
+// shim and orphans the native binary). Duplicating that here would mean two copies
+// of a subtle fix, so the primitive is injected instead.
+
+import fs from 'fs';
+import path from 'node:path';
+
+if (!global._conf) {
+  global._conf = (await import(path.join(process.env.XUDA_HOME, 'common', 'load_conf.mjs'))).loadConf();
+}
+
+const xudex_conf = () => global._conf.xudex || {};
+
+// Wall clock for a single command. This is abuse layer 3 in the plan (9.3) as much
+// as it is a timeout: an ephemeral workspace that dies on schedule takes a miner
+// with it, so no caller is allowed to run without a deadline.
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+
+const run_timeout_ms = () => Number(xudex_conf().run_timeout_ms) || DEFAULT_TIMEOUT_MS;
+
+// ── Path safety ────────────────────────────────────────────────────────────────
+// Every relative path from above this layer is attacker-influenced: the agent
+// writes the file list, and the agent is driven by whatever the customer typed.
+// So a workspace path is resolved and then proven to still be inside the workspace,
+// which is the only check that survives `..`, an absolute path, and a symlink that
+// was created during the run.
+const safe_join = function (root, rel) {
+  const resolved = path.resolve(root, String(rel || ''));
+  const rooted = path.resolve(root) + path.sep;
+  if (resolved !== path.resolve(root) && !resolved.startsWith(rooted)) {
+    throw new Error(`path escapes the workspace: ${rel}`);
+  }
+  return resolved;
+};
+
+// ── The local substrate ────────────────────────────────────────────────────────
+// What UI-226 already does: a working copy on the region server's own filesystem,
+// with the engine running against it in place. It is expressed through the
+// interface so the seam has a real implementation from day one rather than a
+// comment, and so the existing Code tab has somewhere to land.
+//
+// It is NOT a xudex customer substrate and must never become one. Section 3.1 is
+// the reason: the verify loop installs arbitrary packages and runs arbitrary test
+// suites, and this substrate's filesystem belongs to a box that also runs CouchDB
+// and our cpi services. Hence the config gate below, off unless a box opts in.
+const local_substrate = function ({ run_process }) {
+  return {
+    kind: 'local',
+
+    available() {
+      return xudex_conf().allow_local_substrate === true;
+    },
+
+    async acquire({ project_id, dir, timeout_ms }) {
+      if (!dir) throw new Error('the local substrate needs an existing working copy dir');
+      await fs.promises.mkdir(dir, { recursive: true });
+      const deadline = Number(timeout_ms) || run_timeout_ms();
+
+      return {
+        id: `local:${project_id}`,
+        kind: 'local',
+        project_id,
+        dir,
+
+        async exec(argv, opts = {}) {
+          if (!Array.isArray(argv) || !argv.length) throw new Error('exec needs an argv array');
+          const started = Date.now();
+          const ret = await run_process(argv[0], argv.slice(1), opts.input || null, {
+            cwd: opts.cwd ? safe_join(dir, opts.cwd) : dir,
+            env: { ...process.env, ...(opts.env || {}) },
+            timeout: Number(opts.timeout_ms) || deadline,
+            killSignal: 'SIGKILL',
+            onStdout: opts.onStdout,
+            onStderr: opts.onStderr,
+          });
+          const ms = Date.now() - started;
+          return {
+            exit_code: ret.exit_code,
+            stdout: ret.stdout || '',
+            stderr: ret.stderr || '',
+            // run_process reports a kill by appending to stderr rather than by a
+            // flag, so the deadline is re-derived here instead of being guessed by
+            // every caller.
+            timed_out: ms >= (Number(opts.timeout_ms) || deadline),
+            ms,
+          };
+        },
+
+        async read_file(rel) {
+          return await fs.promises.readFile(safe_join(dir, rel), 'utf8');
+        },
+
+        async write_file(rel, data) {
+          const target = safe_join(dir, rel);
+          await fs.promises.mkdir(path.dirname(target), { recursive: true });
+          await fs.promises.writeFile(target, data);
+          return true;
+        },
+
+        async list_dir(rel = '.') {
+          return await fs.promises.readdir(safe_join(dir, rel));
+        },
+
+        // No port can be published from a region server to the outside world, and
+        // pretending otherwise would let the preview layer build on something that
+        // only works here. Callers must handle null.
+        async expose_port() {
+          return null;
+        },
+
+        // Nothing to hand back: the working copy is the record, exactly as UI-226
+        // designed it. `destroy` is honoured so the contract is uniform, but the
+        // caller has to mean it.
+        async release(opts = {}) {
+          if (opts.destroy === true) await fs.promises.rm(dir, { recursive: true, force: true });
+          return true;
+        },
+      };
+    },
+  };
+};
+
+// ── The registry ───────────────────────────────────────────────────────────────
+// Substrates register themselves here and callers ask for a workspace, not for a
+// machine. `preferred_kind` exists for CI, which wants an ephemeral workspace even
+// when the account owns a warm VM (plan 3.8: a long test suite must not block the
+// user's next message).
+export const create_runtime = function ({ run_process }) {
+  if (typeof run_process !== 'function') throw new Error('create_runtime needs run_process');
+
+  const substrates = new Map();
+  const register = (s) => { substrates.set(s.kind, s); return s; };
+
+  register(local_substrate({ run_process }));
+
+  return {
+    register,
+
+    list() {
+      return [...substrates.values()].map((s) => ({ kind: s.kind, available: s.available() }));
+    },
+
+    get(kind) {
+      return substrates.get(kind) || null;
+    },
+
+    // Resolve a workspace for a run. Order of preference: what the caller asked
+    // for, then the account's own machine, then anything available. Returning a
+    // clear error beats falling back silently onto a substrate the caller did not
+    // expect, because "it ran somewhere else" is the hardest class of bug to see.
+    async acquire(req = {}) {
+      const wanted = req.preferred_kind ? [req.preferred_kind] : [];
+      const order = [...wanted, 'vm', 'ephemeral', 'local'];
+      for (const kind of order) {
+        const s = substrates.get(kind);
+        if (s && s.available()) return await s.acquire(req);
+      }
+      throw new Error(
+        `no xudex runtime is available (asked for ${req.preferred_kind || 'any'}, have ${[...substrates.keys()].join(', ') || 'none'})`,
+      );
+    },
+  };
+};
+
+export const _internal = { safe_join, run_timeout_ms };

package/xudex_tracker.mjs

@@ -0,0 +1,276 @@
+// Xudex run tracker: what a run cost, and whether it was a build at all.
+//
+// docs/plans/xudex.md 9.4. One component, three jobs, which is why it is built properly
+// rather than bolted on as monitoring:
+//
+//   1. ABUSE DETECTION. A machine that runs arbitrary customer code is the classic mining
+//      target, and neither the membership floor nor the L2 gate stops someone who paid and
+//      verified from then mining. This is the layer that notices.
+//   2. THE RUN METER. "50 runs a month" on the free tier is counted from these records.
+//   3. THE BENCHMARK. Section 13 needs wall clock and tokens per task to make any
+//      efficiency claim falsifiable, and those are the same numbers.
+//
+// ── Why the detection rule is shaped the way it is ─────────────────────────────────────
+// Not machine learning. The signatures are far apart and a rule you can read is a rule you
+// can defend to a customer you just suspended.
+//
+//   A BUILD:  CPU spiky rather than flat, bounded in time, network front-loaded into a
+//             dependency install and then quiet, and a compiler, test runner or dev server
+//             visible in the process tree the whole time.
+//   MINING:   sustained full CPU, flat, for the entire run, no build or test process, and
+//             either no network at all or a steady trickle to one destination.
+//
+// The rule deliberately looks for the ABSENCE OF LEGITIMATE WORK rather than the presence
+// of a miner. Miners rename their binaries, so matching process names against a list of
+// known miners catches only the lazy ones and fails silently forever after. "Full CPU for
+// minutes with nothing that could be producing it" is a property the attacker cannot
+// rename their way out of.
+//
+// ── A known evasion, measured rather than assumed ──────────────────────────────────────
+// CPU here is SYSTEM WIDE, from /proc/stat, so on a multi-core box a miner that uses only
+// some of the cores never reaches the threshold. Measured on dev 2026-08-14: a
+// single-threaded busy loop peaked at 85% and would not have tripped a 90% line. It is
+// much less of a gap than it first looks, because the xudex tiers are 1, 2 and 4 vCPU, so
+// there are not many cores to hide behind, and an attacker throttling to stay under the
+// line is an attacker earning proportionally less. It is a real gap all the same, so the
+// core count is recorded on every run: thresholds cannot be tuned per box size without it,
+// and tuning on real data is exactly what log-only mode is for.
+//
+// ── Log-only first, and this is not optional ───────────────────────────────────────────
+// `xudex.tracker.enforce` is false. The tracker records a verdict and logs it and does
+// nothing else, so thresholds are tuned against real builds before anything can act on
+// them. The first false positive under enforcement suspends a paying customer in the
+// middle of their work, and there is no good way to apologise for that.
+
+import path from 'node:path';
+
+if (!global._conf) {
+  global._conf = (await import(path.join(process.env.XUDA_HOME, 'common', 'load_conf.mjs'))).loadConf();
+}
+
+const tracker_conf = () => global._conf.xudex?.tracker || {};
+
+// One shell command per sample, because sampling a workspace costs an exec and a run is
+// sampled repeatedly. Every line is prefixed so the parser never has to guess what it is
+// looking at, and each metric fails independently: a box without /proc/net/dev still
+// yields CPU rather than the whole sample being lost.
+export const SAMPLE_COMMAND = [
+  `awk '/^cpu /{print "cpu " ($2+$3+$4+$5+$6+$7+$8) " " $5}' /proc/stat 2>/dev/null`,
+  `awk -F'[: ]+' '/:/ && $1!~/lo/ {rx+=$3; tx+=$11} END{print "net " rx+0 " " tx+0}' /proc/net/dev 2>/dev/null`,
+  `awk '/^MemTotal/{t=$2} /^MemAvailable/{a=$2} END{print "mem " (t-a) " " t}' /proc/meminfo 2>/dev/null`,
+  `echo "cores $(nproc 2>/dev/null || echo 1)"`,
+  `ps -eo comm= 2>/dev/null | sort -u | tr '\\n' ',' | sed 's/^/proc /'`,
+].join('; ');
+
+// Process names that mean real work is happening. Xudex v1 is Node and TypeScript only
+// (plan section 10), so this list is deliberately small: a wider list is a wider hole,
+// because every name on it is a name a miner can adopt.
+export const BUILD_PROCESSES = [
+  'node',
+  'npm',
+  'npx',
+  'pnpm',
+  'yarn',
+  'tsc',
+  'tsx',
+  'jest',
+  'vitest',
+  'vite',
+  'esbuild',
+  'webpack',
+  'rollup',
+  'next',
+  'eslint',
+  'prettier',
+  'git',
+  'codex',
+  'claude',
+];
+
+// Parse one sample. Returns nulls rather than throwing for anything the box did not give
+// us, because a partial sample is still worth having and a thrown error inside a sampler
+// would take down the run it is supposed to be watching.
+export const parse_sample = function (text) {
+  const out = { cpu_total: null, cpu_idle: null, cores: null, net_rx: null, net_tx: null, mem_used_kb: null, mem_total_kb: null, procs: [] };
+  for (const line of String(text || '').split('\n')) {
+    const parts = line.trim().split(/\s+/);
+    if (parts[0] === 'cpu' && parts.length >= 3) {
+      out.cpu_total = Number(parts[1]);
+      out.cpu_idle = Number(parts[2]);
+    } else if (parts[0] === 'cores' && parts.length >= 2) {
+      out.cores = Number(parts[1]) || null;
+    } else if (parts[0] === 'net' && parts.length >= 3) {
+      out.net_rx = Number(parts[1]);
+      out.net_tx = Number(parts[2]);
+    } else if (parts[0] === 'mem' && parts.length >= 3) {
+      out.mem_used_kb = Number(parts[1]);
+      out.mem_total_kb = Number(parts[2]);
+    } else if (parts[0] === 'proc') {
+      out.procs = line
+        .trim()
+        .slice(5)
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    }
+  }
+  return out;
+};
+
+// CPU percentage between two /proc/stat readings. Jiffies are cumulative, so a single
+// sample says nothing: the interesting number is always a delta.
+export const cpu_pct_between = function (prev, cur) {
+  if (!prev || !cur || prev.cpu_total == null || cur.cpu_total == null) return null;
+  const total = cur.cpu_total - prev.cpu_total;
+  const idle = cur.cpu_idle - prev.cpu_idle;
+  if (!(total > 0)) return null;
+  return Math.max(0, Math.min(100, ((total - idle) / total) * 100));
+};
+
+export const has_build_process = function (procs) {
+  if (!Array.isArray(procs) || !procs.length) return false;
+  return procs.some((p) => BUILD_PROCESSES.includes(String(p).toLowerCase()));
+};
+
+// The verdict. Pure, so it can be argued with in a test rather than in production.
+//
+// Two independent triggers, both requiring a duration or a volume rather than an instant:
+// a build absolutely does peg a CPU, and it absolutely does download a lot, so anything
+// that fires on a moment rather than on a pattern would flag half our own customers.
+export const evaluate_run = function (record, conf = tracker_conf()) {
+  const reasons = [];
+  const cpu_pct = Number(conf.cpu_sustained_pct ?? 90);
+  const cpu_seconds = Number(conf.cpu_sustained_seconds ?? 180);
+  const max_out_mb = Number(conf.max_outbound_mb ?? 2048);
+
+  const sustained = Number(record?.cpu?.sustained_high_seconds) || 0;
+  const build_seen = record?.build_seen === true;
+
+  // The core rule: full CPU for minutes with nothing in the tree that could be producing
+  // it. Either half alone is ordinary. A long compile is high CPU WITH a compiler; an
+  // idle machine has no build process and no CPU. Only the pair is strange.
+  if (sustained >= cpu_seconds && !build_seen) {
+    reasons.push(`cpu above ${cpu_pct}% for ${Math.round(sustained)}s with no build or test process running`);
+  }
+
+  const out_mb = (Number(record?.net?.out_bytes) || 0) / (1024 * 1024);
+  if (out_mb > max_out_mb) {
+    reasons.push(`sent ${Math.round(out_mb)} MB outbound, over the ${max_out_mb} MB ceiling`);
+  }
+
+  return {
+    verdict: reasons.length ? 'flag' : 'ok',
+    reasons,
+    // Whether anything is DONE about it is a separate question from whether it looked
+    // wrong, and it stays separate on purpose (see the log-only note at the top).
+    enforce: conf.enforce === true,
+  };
+};
+
+// A tracker for one run. `workspace` is the runtime interface's handle (xudex_runtime.mjs),
+// so this works identically on a VM, an ephemeral runner or a container, which is the
+// whole reason that seam exists.
+export const create_run_tracker = function ({ workspace, conf = tracker_conf(), now = () => Date.now() }) {
+  const samples = [];
+  let prev = null;
+  let first = null;
+  let last = null;
+  let started_ts = null;
+  let sustained_high_ms = 0;
+  let peak_cpu = 0;
+  let peak_mem_mb = 0;
+  let build_seen = false;
+  let last_sample_ts = null;
+  let cores = null;
+  const cpu_threshold = Number(conf.cpu_sustained_pct ?? 90);
+
+  return {
+    async start() {
+      started_ts = now();
+      try {
+        const r = await workspace.exec(['sh', '-c', SAMPLE_COMMAND], { timeout_ms: 15000 });
+        prev = parse_sample(r.stdout);
+        first = prev;
+        last_sample_ts = started_ts;
+      } catch (e) {
+        // Sampling is observation. It must never be the reason a customer's run fails.
+        console.warn(`[xudex] tracker start sample failed: ${e.message}`);
+      }
+      return true;
+    },
+
+    async sample() {
+      try {
+        const r = await workspace.exec(['sh', '-c', SAMPLE_COMMAND], { timeout_ms: 15000 });
+        const cur = parse_sample(r.stdout);
+        const ts = now();
+        const pct = cpu_pct_between(prev, cur);
+
+        if (pct != null) {
+          peak_cpu = Math.max(peak_cpu, pct);
+          // Credit the elapsed interval, not one tick, so the sustained figure means
+          // seconds of wall clock above the line rather than a count of samples.
+          if (pct >= cpu_threshold && last_sample_ts) sustained_high_ms += ts - last_sample_ts;
+          // A single sample below the line breaks the streak. Mining is flat by nature, so
+          // this costs an attacker real throughput to evade, while a spiky build resets it
+          // constantly, which is exactly the discrimination we want.
+          else sustained_high_ms = 0;
+          samples.push({ ts, cpu_pct: pct });
+        }
+        if (cur.mem_used_kb != null) peak_mem_mb = Math.max(peak_mem_mb, cur.mem_used_kb / 1024);
+        if (cur.cores != null) cores = cur.cores;
+        if (has_build_process(cur.procs)) build_seen = true;
+
+        prev = cur;
+        last = cur;
+        last_sample_ts = ts;
+      } catch (e) {
+        console.warn(`[xudex] tracker sample failed: ${e.message}`);
+      }
+      return true;
+    },
+
+    // Close the run and hand back the record. `usage` is the engine's own token count
+    // (normalize_codex_usage already produces this shape for codex), which is what makes
+    // this the same instrument the benchmark needs.
+    finish({ usage = {}, engine = null, model = null, meta = {} } = {}) {
+      const ended_ts = now();
+      const cpu_values = samples.map((s) => s.cpu_pct);
+      const mean = cpu_values.length ? cpu_values.reduce((a, b) => a + b, 0) / cpu_values.length : 0;
+
+      const record = {
+        docType: 'xudex_run',
+        ...meta,
+        engine,
+        model,
+        started_ts,
+        ended_ts,
+        wall_ms: started_ts ? ended_ts - started_ts : 0,
+        cpu: {
+          mean_pct: Math.round(mean * 10) / 10,
+          peak_pct: Math.round(peak_cpu * 10) / 10,
+          sustained_high_seconds: Math.round(sustained_high_ms / 1000),
+          samples: samples.length,
+          // Recorded so a threshold can later be reasoned about per box size. A system-wide
+          // percentage means something different on 1 vCPU than on 4, and without this the
+          // tuning pass would have no way to tell those runs apart.
+          cores: cores ?? first?.cores ?? null,
+        },
+        mem: { peak_mb: Math.round(peak_mem_mb) },
+        net: {
+          out_bytes: first && last && last.net_tx != null && first.net_tx != null ? Math.max(0, last.net_tx - first.net_tx) : 0,
+          in_bytes: first && last && last.net_rx != null && first.net_rx != null ? Math.max(0, last.net_rx - first.net_rx) : 0,
+        },
+        build_seen,
+        tokens: { input: Number(usage.input_tokens) || 0, output: Number(usage.output_tokens) || 0 },
+        ts: ended_ts,
+      };
+
+      const verdict = evaluate_run(record, conf);
+      record.verdict = verdict.verdict;
+      record.reasons = verdict.reasons;
+      record.enforced = verdict.verdict === 'flag' && verdict.enforce === true;
+      return record;
+    },
+  };
+};