@yeaft/webchat-agent 1.0.437 → 1.0.439

package/container-cli.js

@@ -1,11 +1,18 @@
 #!/usr/bin/env node
+import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import {
   createContainerAgent,
+  DEFAULT_AGENT_SLICE,
+  detectHostResources,
+  ensureAgentSlice,
   inspectContainerAgent,
+  isAgentSliceReady,
   logsContainerAgent,
   removeContainerAgent,
+  resolveDiskSize,
+  runDocker,
   startContainerAgent,
   stopContainerAgent,
   writeAgentSecretFile,
@@ -14,12 +21,25 @@ import {
 function help() {
   console.log(`
 Usage:
-  yeaft-agent container install --server <ws-url> --name <name> --secret <secret> [--image <image>]
+  yeaft-agent container install --server <ws-url> --name <name> --secret <secret> [--image <image>] [--cgroup-parent <slice>] [--no-slice] [--disk-size <size>]
+  yeaft-agent container setup-limits [--cpu-percent <pct>] [--memory-percent <pct>] [--pids <n>]
   yeaft-agent container start|stop|status|remove|logs --name <name>
 
 The container is an ordinary yeaft-agent. This command only manages its Docker lifecycle.
 The secret is passed as an argument, like 'yeaft-agent install', and persisted by this
 command to a private 0600 file before the container is created.
+
+Resource protection (default): install attaches the container to the shared
+'${DEFAULT_AGENT_SLICE}' cgroup slice, which caps the sum of all Yeaft Agent
+containers at 90% of host CPU and 70% of host memory. The slice is initialized
+automatically on first install (as root directly, otherwise via sudo; you are
+prompted for the sudo password once). Pass --no-slice to opt out of protection.
+
+--disk-size <size>: per-volume capacity quota for the data and workspace volumes, e.g.
+  20G or 80% of the Docker data-root filesystem. Requires Docker overlay2 on xfs with
+  project quotas; unsupported filesystems fail docker create. Applies to newly created
+  volumes only (Docker ignores size for existing volumes).
+
 Use --keep-volumes with remove to preserve its Yeaft data and workspace volumes.
 `);
 }
@@ -29,7 +49,7 @@ export function parseContainerArgs(args) {
   const positionals = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (arg === '--keep-volumes' || arg === '--follow') {
+    if (arg === '--keep-volumes' || arg === '--follow' || arg === '--no-slice') {
       options[arg.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = true;
       continue;
     }
@@ -44,6 +64,62 @@ export function parseContainerArgs(args) {
   return { action: positionals[0], options };
 }
 
+async function dockerDataRoot() {
+  const result = await runDocker(['info', '--format', '{{.DockerRootDir}}']);
+  if (!result.stdout) throw new Error('docker info did not report a data-root');
+  return result.stdout;
+}
+
+/**
+ * Initialize the shared agent slice during `container install` so users never
+ * have to run `setup-limits` by hand. Root can write the slice directly; a
+ * non-root user re-invokes this CLI via an interactive sudo so the password
+ * prompt happens inline. Non-interactive shells skip sudo and fail with
+ * guidance instead of hanging.
+ *
+ * @param {object} options { spawnImpl, interactive } overrides for tests
+ */
+export async function ensureAgentSliceAuto({
+  spawnImpl = spawn,
+  interactive = Boolean(process.stdin?.isTTY),
+} = {}) {
+  if (typeof process.getuid === 'function' && process.getuid() === 0) {
+    await ensureAgentSlice();
+    return;
+  }
+  if (!interactive) {
+    throw new Error(
+      `Agent slice '${DEFAULT_AGENT_SLICE}' is not initialized and this shell is not interactive; ` +
+      'run "sudo yeaft-agent container setup-limits" once, ' +
+      'or pass --no-slice to install without shared resource limits',
+    );
+  }
+  const code = await runSudoSetupLimits({ spawnImpl });
+  if (code !== 0) {
+    throw new Error(
+      `Failed to initialize Agent slice '${DEFAULT_AGENT_SLICE}' via sudo (exit ${code}); ` +
+      'run "sudo yeaft-agent container setup-limits" manually, ' +
+      'or pass --no-slice to install without shared resource limits',
+    );
+  }
+}
+
+function runSudoSetupLimits({ spawnImpl = spawn } = {}) {
+  return new Promise((resolvePromise, reject) => {
+    // `sudo env PATH=...` keeps user-installed runtimes (nvm etc.) reachable
+    // even when sudoers sets a secure_path. Re-invoking the current entry
+    // script avoids depending on the npm bin being in sudo's PATH.
+    const entry = process.argv[1] ? resolve(process.argv[1]) : null;
+    const args = ['env', `PATH=${process.env.PATH || ''}`];
+    if (entry) args.push(process.execPath, entry);
+    else args.push('yeaft-agent');
+    args.push('container', 'setup-limits');
+    const child = spawnImpl('sudo', args, { stdio: 'inherit' });
+    child.once('error', reject);
+    child.once('close', code => resolvePromise(code ?? 1));
+  });
+}
+
 export async function runContainerCli(args) {
   if (args.length === 0 || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') return help();
   const { action, options } = parseContainerArgs(args);
@@ -57,12 +133,44 @@ export async function runContainerCli(args) {
     if (!secret) throw new Error('--secret <secret> is required');
     const secretFile = join(homedir(), '.yeaft', 'container-agents', name, 'agent-secret');
     await writeAgentSecretFile(secretFile, secret);
+    let cgroupParent;
+    if (options.noSlice) {
+      cgroupParent = undefined;
+    } else if (options.cgroupParent) {
+      cgroupParent = String(options.cgroupParent).trim();
+    } else if (!(await isAgentSliceReady())) {
+      await ensureAgentSliceAuto();
+      cgroupParent = DEFAULT_AGENT_SLICE;
+    } else {
+      cgroupParent = DEFAULT_AGENT_SLICE;
+    }
+    let diskSizeBytes;
+    if (options.diskSize) {
+      const value = String(options.diskSize).trim();
+      diskSizeBytes = await resolveDiskSize(value, {
+        dockerRoot: value.includes('%') ? await dockerDataRoot() : undefined,
+      });
+    }
     result = await createContainerAgent({
       name,
       serverUrl: options.server,
       secretFile,
       image: options.image,
+      cgroupParent,
+      diskSizeBytes,
+    });
+  } else if (action === 'setup-limits') {
+    if (typeof process.getuid === 'function' && process.getuid() !== 0) {
+      throw new Error('setup-limits must run as root; use sudo');
+    }
+    const resources = await detectHostResources();
+    result = await ensureAgentSlice({
+      cpuPercent: Number(options.cpuPercent) || 90,
+      memoryPercent: Number(options.memoryPercent) || 70,
+      pidsLimit: Number(options.pids) || 4096,
+      resources,
     });
+    result.resources = resources;
   } else if (action === 'start') {
     result = await startContainerAgent(name);
   } else if (action === 'stop') {

package/container-manager.js

@@ -1,9 +1,13 @@
 import { spawn } from 'node:child_process';
-import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, statfs, writeFile } from 'node:fs/promises';
+import { cpus } from 'node:os';
 import { dirname, resolve } from 'node:path';
 
 export const DEFAULT_AGENT_IMAGE = 'ghcr.io/yeaft/yeaft-web-code-agent-agent:dev';
+export const DEFAULT_AGENT_SLICE = 'yeaft.slice';
+export const SLICE_READY_MARKER = 'yeaft-slice.ready';
 const NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$/;
+const CPU_PERIOD_US = 100_000;
 
 export class ContainerAgentError extends Error {
   constructor(code, message = code) {
@@ -64,6 +68,8 @@ export function buildCreateArgs({
   dataVolume,
   workspaceVolume,
   restart = 'unless-stopped',
+  cgroupParent,
+  diskSizeBytes,
 }) {
   const agentName = normalizeContainerAgentName(name);
   if (!String(serverUrl || '').match(/^wss?:\/\//)) {
@@ -73,14 +79,29 @@ export function buildCreateArgs({
   const containerName = containerNameForAgent(agentName);
   const safeImage = String(image || '').trim();
   if (!safeImage || safeImage.startsWith('-')) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_IMAGE');
-  return [
+  const args = [
     'create', '--name', containerName,
     '--label', 'io.yeaft.container-agent=true',
     '--label', `io.yeaft.agent-name=${agentName}`,
     '--restart', restart,
     '--init',
-    '--mount', `type=volume,src=${dataVolume || `${containerName}-data`},dst=/home/yeaft/.yeaft`,
-    '--mount', `type=volume,src=${workspaceVolume || `${containerName}-workspace`},dst=/workspace`,
+  ];
+  if (cgroupParent) {
+    const slice = String(cgroupParent).trim();
+    if (!slice) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_CGROUP_PARENT');
+    args.push('--cgroup-parent', slice);
+  }
+  let diskOpt = '';
+  if (diskSizeBytes) {
+    const size = Math.floor(Number(diskSizeBytes));
+    if (!Number.isFinite(size) || size <= 0) {
+      throw new ContainerAgentError('CONTAINER_AGENT_INVALID_DISK_SIZE');
+    }
+    diskOpt = `,volume-opt=size=${size}`;
+  }
+  args.push(
+    '--mount', `type=volume,src=${dataVolume || `${containerName}-data`},dst=/home/yeaft/.yeaft${diskOpt}`,
+    '--mount', `type=volume,src=${workspaceVolume || `${containerName}-workspace`},dst=/workspace${diskOpt}`,
     '--mount', `type=bind,src=${resolve(secretFile)},dst=/run/yeaft-host-secret,readonly`,
     '--env', `SERVER_URL=${serverUrl}`,
     '--env', `AGENT_NAME=${agentName}`,
@@ -88,7 +109,8 @@ export function buildCreateArgs({
     '--env', 'YEAFT_DIR=/home/yeaft/.yeaft',
     '--env', 'WORK_DIR=/workspace',
     safeImage,
-  ];
+  );
+  return args;
 }
 
 /**
@@ -182,3 +204,161 @@ export async function logsContainerAgent(name, { follow = false, ...runtime } =
   args.push(containerNameForAgent(name));
   return runDocker(args, { ...runtime, stdout: follow ? 'inherit' : 'pipe' });
 }
+
+function clampPercent(value, fallback) {
+  const n = Number(value);
+  const safe = Number.isFinite(n) ? n : fallback;
+  return Math.min(100, Math.max(1, safe));
+}
+
+/**
+ * Compute cgroup v2 slice limits from host resources. Pure function so the
+ * 90% CPU / 70% memory policy is directly testable.
+ *
+ * @param {object} policy cpuPercent (default 90), memoryPercent (default 70), pidsLimit (default 4096)
+ * @param {object} resources { cpuCores, memTotalBytes } from detectHostResources
+ * @returns {{cpuQuotaUs: number, cpuPeriodUs: number, memoryMaxBytes: number, pidsMax: number}}
+ */
+export function buildSliceLimits(
+  { cpuPercent = 90, memoryPercent = 70, pidsLimit = 4096 } = {},
+  { cpuCores = 0, memTotalBytes = 0 } = {},
+) {
+  const cores = Math.max(1, Math.floor(Number(cpuCores) || 0) || 1);
+  const cpuPct = clampPercent(cpuPercent, 90);
+  const memPct = clampPercent(memoryPercent, 70);
+  return {
+    cpuQuotaUs: Math.floor((cores * cpuPct / 100) * CPU_PERIOD_US),
+    cpuPeriodUs: CPU_PERIOD_US,
+    memoryMaxBytes: Math.floor((Number(memTotalBytes) || 0) * memPct / 100),
+    pidsMax: Math.max(64, Math.floor(Number(pidsLimit) || 0) || 4096),
+  };
+}
+
+/**
+ * Detect host resources: logical CPU count plus MemTotal from /proc/meminfo.
+ * MemTotal may be 0 on non-Linux or unreadable /proc; callers must treat a
+ * zero memory limit as "no memory constraint" rather than OOM-ing containers.
+ *
+ * @param {object} options { readFileImpl, cpuCount } overrides for tests
+ * @returns {Promise<{cpuCores: number, memTotalBytes: number}>}
+ */
+export async function detectHostResources({ readFileImpl = readFile, cpuCount = cpus().length } = {}) {
+  let memTotalBytes = 0;
+  try {
+    const meminfo = await readFileImpl('/proc/meminfo', 'utf8');
+    const match = String(meminfo || '').match(/^MemTotal:\s+(\d+)\s*kB/m);
+    if (match) memTotalBytes = Number(match[1]) * 1024;
+  } catch {
+    // Non-Linux or restricted /proc; memory limiting is skipped downstream.
+  }
+  return { cpuCores: Math.max(1, Math.floor(Number(cpuCount) || 0) || 1), memTotalBytes };
+}
+
+/**
+ * Create or refresh a cgroup v2 slice that all Yeaft Agent containers share.
+ * Requires root (writes under /sys/fs/cgroup). Writes a ready marker so
+ * `container install` can refuse to create unprotected containers by default.
+ *
+ * @param {object} options slice, cpuPercent, memoryPercent, pidsLimit,
+ *   resources (pre-detected), fsImpl { mkdir, readFile, writeFile } for tests
+ * @returns {Promise<{slice: string, limits: object, controllers: string[]}>}
+ */
+export async function ensureAgentSlice({
+  slice = DEFAULT_AGENT_SLICE,
+  cpuPercent = 90,
+  memoryPercent = 70,
+  pidsLimit = 4096,
+  resources,
+  fsImpl = { mkdir, readFile, writeFile },
+} = {}) {
+  const slicePath = `/sys/fs/cgroup/${String(slice).replace(/^\/+/, '')}`;
+  let controllers = [];
+  try {
+    const text = await fsImpl.readFile('/sys/fs/cgroup/cgroup.controllers', 'utf8');
+    controllers = String(text || '').trim().split(/\s+/).filter(Boolean);
+  } catch {
+    // Treat missing controller list as "no controllers writable".
+  }
+  const wanted = ['cpu', 'memory', 'pids'].filter(name => controllers.includes(name));
+  if (wanted.length === 0) {
+    throw new ContainerAgentError(
+      'CONTAINER_AGENT_CGROUP_UNAVAILABLE',
+      'cgroup v2 controllers (cpu/memory/pids) are unavailable; setup-limits requires a host running cgroup v2 and root access to /sys/fs/cgroup',
+    );
+  }
+  await fsImpl.mkdir(slicePath, { recursive: true, mode: 0o755 });
+  await fsImpl.writeFile(
+    `${slicePath}/cgroup.subtree_control`,
+    wanted.map(name => `+${name}`).join(' '),
+    'utf8',
+  );
+  const detected = resources || await detectHostResources({ readFileImpl: fsImpl.readFile });
+  const limits = buildSliceLimits({ cpuPercent, memoryPercent, pidsLimit }, detected);
+  if (wanted.includes('cpu') && limits.cpuQuotaUs > 0) {
+    await fsImpl.writeFile(`${slicePath}/cpu.max`, `${limits.cpuQuotaUs} ${limits.cpuPeriodUs}`, 'utf8');
+  }
+  if (wanted.includes('memory') && limits.memoryMaxBytes > 0) {
+    await fsImpl.writeFile(`${slicePath}/memory.max`, String(limits.memoryMaxBytes), 'utf8');
+    // No swap escape hatch: the 70% RAM hard cap is the whole memory budget.
+    await fsImpl.writeFile(`${slicePath}/memory.swap.max`, '0', 'utf8');
+  }
+  if (wanted.includes('pids') && limits.pidsMax > 0) {
+    await fsImpl.writeFile(`${slicePath}/pids.max`, String(limits.pidsMax), 'utf8');
+  }
+  const marker = {
+    slice,
+    cpuQuotaUs: limits.cpuQuotaUs,
+    cpuPeriodUs: limits.cpuPeriodUs,
+    memoryMaxBytes: limits.memoryMaxBytes,
+    pidsMax: limits.pidsMax,
+    updatedAt: new Date().toISOString(),
+  };
+  await fsImpl.writeFile(`${slicePath}/${SLICE_READY_MARKER}`, JSON.stringify(marker, null, 2), 'utf8');
+  return { slice, limits, controllers: wanted };
+}
+
+/**
+ * Whether `container setup-limits` has initialized the given slice.
+ *
+ * @param {object} options slice, readFileImpl for tests
+ * @returns {Promise<boolean>}
+ */
+export async function isAgentSliceReady({ slice = DEFAULT_AGENT_SLICE, readFileImpl = readFile } = {}) {
+  const slicePath = `/sys/fs/cgroup/${String(slice).replace(/^\/+/, '')}`;
+  try {
+    await readFileImpl(`${slicePath}/${SLICE_READY_MARKER}`, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const DISK_SIZE_RE = /^(\d+(?:\.\d+)?)\s*(%|[kmgt](?:i?b)?|b)?$/i;
+
+/**
+ * Resolve a disk size like "20G" or "80%" to bytes. Percentages are computed
+ * against the Docker data-root filesystem and require statfsImpl (node:fs
+ * statfs) plus the docker root path.
+ *
+ * @param {string|number} value
+ * @param {object} options { dockerRoot, statfsImpl } for percent resolution and tests
+ * @returns {Promise<number>}
+ */
+export async function resolveDiskSize(value, { dockerRoot, statfsImpl = statfs } = {}) {
+  const input = String(value ?? '').trim();
+  const match = input.match(DISK_SIZE_RE);
+  if (!match) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_DISK_SIZE', `Invalid disk size: ${input}`);
+  const amount = Number(match[1]);
+  const unit = (match[2] || 'b').toLowerCase();
+  if (unit === 'b') return Math.floor(amount);
+  if (unit === '%') {
+    if (!dockerRoot) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_DISK_SIZE', 'Percent disk size requires the Docker data-root');
+    const info = await statfsImpl(dockerRoot);
+    const totalBytes = Number(info.bsize) * Number(info.blocks);
+    return Math.floor(totalBytes * amount / 100);
+  }
+  const multipliers = { k: 1024, kb: 1024, kib: 1024, m: 1024 ** 2, mb: 1024 ** 2, mib: 1024 ** 2, g: 1024 ** 3, gb: 1024 ** 3, gib: 1024 ** 3, t: 1024 ** 4, tb: 1024 ** 4, tib: 1024 ** 4 };
+  const multiplier = multipliers[unit];
+  if (!multiplier) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_DISK_SIZE', `Invalid disk size: ${input}`);
+  return Math.floor(amount * multiplier);
+}

package/local-runtime/agent/container-manager.js

@@ -1,9 +1,13 @@
 import { spawn } from 'node:child_process';
-import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, statfs, writeFile } from 'node:fs/promises';
+import { cpus } from 'node:os';
 import { dirname, resolve } from 'node:path';
 
 export const DEFAULT_AGENT_IMAGE = 'ghcr.io/yeaft/yeaft-web-code-agent-agent:dev';
+export const DEFAULT_AGENT_SLICE = 'yeaft.slice';
+export const SLICE_READY_MARKER = 'yeaft-slice.ready';
 const NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$/;
+const CPU_PERIOD_US = 100_000;
 
 export class ContainerAgentError extends Error {
   constructor(code, message = code) {
@@ -64,6 +68,8 @@ export function buildCreateArgs({
   dataVolume,
   workspaceVolume,
   restart = 'unless-stopped',
+  cgroupParent,
+  diskSizeBytes,
 }) {
   const agentName = normalizeContainerAgentName(name);
   if (!String(serverUrl || '').match(/^wss?:\/\//)) {
@@ -73,14 +79,29 @@ export function buildCreateArgs({
   const containerName = containerNameForAgent(agentName);
   const safeImage = String(image || '').trim();
   if (!safeImage || safeImage.startsWith('-')) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_IMAGE');
-  return [
+  const args = [
     'create', '--name', containerName,
     '--label', 'io.yeaft.container-agent=true',
     '--label', `io.yeaft.agent-name=${agentName}`,
     '--restart', restart,
     '--init',
-    '--mount', `type=volume,src=${dataVolume || `${containerName}-data`},dst=/home/yeaft/.yeaft`,
-    '--mount', `type=volume,src=${workspaceVolume || `${containerName}-workspace`},dst=/workspace`,
+  ];
+  if (cgroupParent) {
+    const slice = String(cgroupParent).trim();
+    if (!slice) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_CGROUP_PARENT');
+    args.push('--cgroup-parent', slice);
+  }
+  let diskOpt = '';
+  if (diskSizeBytes) {
+    const size = Math.floor(Number(diskSizeBytes));
+    if (!Number.isFinite(size) || size <= 0) {
+      throw new ContainerAgentError('CONTAINER_AGENT_INVALID_DISK_SIZE');
+    }
+    diskOpt = `,volume-opt=size=${size}`;
+  }
+  args.push(
+    '--mount', `type=volume,src=${dataVolume || `${containerName}-data`},dst=/home/yeaft/.yeaft${diskOpt}`,
+    '--mount', `type=volume,src=${workspaceVolume || `${containerName}-workspace`},dst=/workspace${diskOpt}`,
     '--mount', `type=bind,src=${resolve(secretFile)},dst=/run/yeaft-host-secret,readonly`,
     '--env', `SERVER_URL=${serverUrl}`,
     '--env', `AGENT_NAME=${agentName}`,
@@ -88,7 +109,8 @@ export function buildCreateArgs({
     '--env', 'YEAFT_DIR=/home/yeaft/.yeaft',
     '--env', 'WORK_DIR=/workspace',
     safeImage,
-  ];
+  );
+  return args;
 }
 
 /**
@@ -182,3 +204,161 @@ export async function logsContainerAgent(name, { follow = false, ...runtime } =
   args.push(containerNameForAgent(name));
   return runDocker(args, { ...runtime, stdout: follow ? 'inherit' : 'pipe' });
 }
+
+function clampPercent(value, fallback) {
+  const n = Number(value);
+  const safe = Number.isFinite(n) ? n : fallback;
+  return Math.min(100, Math.max(1, safe));
+}
+
+/**
+ * Compute cgroup v2 slice limits from host resources. Pure function so the
+ * 90% CPU / 70% memory policy is directly testable.
+ *
+ * @param {object} policy cpuPercent (default 90), memoryPercent (default 70), pidsLimit (default 4096)
+ * @param {object} resources { cpuCores, memTotalBytes } from detectHostResources
+ * @returns {{cpuQuotaUs: number, cpuPeriodUs: number, memoryMaxBytes: number, pidsMax: number}}
+ */
+export function buildSliceLimits(
+  { cpuPercent = 90, memoryPercent = 70, pidsLimit = 4096 } = {},
+  { cpuCores = 0, memTotalBytes = 0 } = {},
+) {
+  const cores = Math.max(1, Math.floor(Number(cpuCores) || 0) || 1);
+  const cpuPct = clampPercent(cpuPercent, 90);
+  const memPct = clampPercent(memoryPercent, 70);
+  return {
+    cpuQuotaUs: Math.floor((cores * cpuPct / 100) * CPU_PERIOD_US),
+    cpuPeriodUs: CPU_PERIOD_US,
+    memoryMaxBytes: Math.floor((Number(memTotalBytes) || 0) * memPct / 100),
+    pidsMax: Math.max(64, Math.floor(Number(pidsLimit) || 0) || 4096),
+  };
+}
+
+/**
+ * Detect host resources: logical CPU count plus MemTotal from /proc/meminfo.
+ * MemTotal may be 0 on non-Linux or unreadable /proc; callers must treat a
+ * zero memory limit as "no memory constraint" rather than OOM-ing containers.
+ *
+ * @param {object} options { readFileImpl, cpuCount } overrides for tests
+ * @returns {Promise<{cpuCores: number, memTotalBytes: number}>}
+ */
+export async function detectHostResources({ readFileImpl = readFile, cpuCount = cpus().length } = {}) {
+  let memTotalBytes = 0;
+  try {
+    const meminfo = await readFileImpl('/proc/meminfo', 'utf8');
+    const match = String(meminfo || '').match(/^MemTotal:\s+(\d+)\s*kB/m);
+    if (match) memTotalBytes = Number(match[1]) * 1024;
+  } catch {
+    // Non-Linux or restricted /proc; memory limiting is skipped downstream.
+  }
+  return { cpuCores: Math.max(1, Math.floor(Number(cpuCount) || 0) || 1), memTotalBytes };
+}
+
+/**
+ * Create or refresh a cgroup v2 slice that all Yeaft Agent containers share.
+ * Requires root (writes under /sys/fs/cgroup). Writes a ready marker so
+ * `container install` can refuse to create unprotected containers by default.
+ *
+ * @param {object} options slice, cpuPercent, memoryPercent, pidsLimit,
+ *   resources (pre-detected), fsImpl { mkdir, readFile, writeFile } for tests
+ * @returns {Promise<{slice: string, limits: object, controllers: string[]}>}
+ */
+export async function ensureAgentSlice({
+  slice = DEFAULT_AGENT_SLICE,
+  cpuPercent = 90,
+  memoryPercent = 70,
+  pidsLimit = 4096,
+  resources,
+  fsImpl = { mkdir, readFile, writeFile },
+} = {}) {
+  const slicePath = `/sys/fs/cgroup/${String(slice).replace(/^\/+/, '')}`;
+  let controllers = [];
+  try {
+    const text = await fsImpl.readFile('/sys/fs/cgroup/cgroup.controllers', 'utf8');
+    controllers = String(text || '').trim().split(/\s+/).filter(Boolean);
+  } catch {
+    // Treat missing controller list as "no controllers writable".
+  }
+  const wanted = ['cpu', 'memory', 'pids'].filter(name => controllers.includes(name));
+  if (wanted.length === 0) {
+    throw new ContainerAgentError(
+      'CONTAINER_AGENT_CGROUP_UNAVAILABLE',
+      'cgroup v2 controllers (cpu/memory/pids) are unavailable; setup-limits requires a host running cgroup v2 and root access to /sys/fs/cgroup',
+    );
+  }
+  await fsImpl.mkdir(slicePath, { recursive: true, mode: 0o755 });
+  await fsImpl.writeFile(
+    `${slicePath}/cgroup.subtree_control`,
+    wanted.map(name => `+${name}`).join(' '),
+    'utf8',
+  );
+  const detected = resources || await detectHostResources({ readFileImpl: fsImpl.readFile });
+  const limits = buildSliceLimits({ cpuPercent, memoryPercent, pidsLimit }, detected);
+  if (wanted.includes('cpu') && limits.cpuQuotaUs > 0) {
+    await fsImpl.writeFile(`${slicePath}/cpu.max`, `${limits.cpuQuotaUs} ${limits.cpuPeriodUs}`, 'utf8');
+  }
+  if (wanted.includes('memory') && limits.memoryMaxBytes > 0) {
+    await fsImpl.writeFile(`${slicePath}/memory.max`, String(limits.memoryMaxBytes), 'utf8');
+    // No swap escape hatch: the 70% RAM hard cap is the whole memory budget.
+    await fsImpl.writeFile(`${slicePath}/memory.swap.max`, '0', 'utf8');
+  }
+  if (wanted.includes('pids') && limits.pidsMax > 0) {
+    await fsImpl.writeFile(`${slicePath}/pids.max`, String(limits.pidsMax), 'utf8');
+  }
+  const marker = {
+    slice,
+    cpuQuotaUs: limits.cpuQuotaUs,
+    cpuPeriodUs: limits.cpuPeriodUs,
+    memoryMaxBytes: limits.memoryMaxBytes,
+    pidsMax: limits.pidsMax,
+    updatedAt: new Date().toISOString(),
+  };
+  await fsImpl.writeFile(`${slicePath}/${SLICE_READY_MARKER}`, JSON.stringify(marker, null, 2), 'utf8');
+  return { slice, limits, controllers: wanted };
+}
+
+/**
+ * Whether `container setup-limits` has initialized the given slice.
+ *
+ * @param {object} options slice, readFileImpl for tests
+ * @returns {Promise<boolean>}
+ */
+export async function isAgentSliceReady({ slice = DEFAULT_AGENT_SLICE, readFileImpl = readFile } = {}) {
+  const slicePath = `/sys/fs/cgroup/${String(slice).replace(/^\/+/, '')}`;
+  try {
+    await readFileImpl(`${slicePath}/${SLICE_READY_MARKER}`, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const DISK_SIZE_RE = /^(\d+(?:\.\d+)?)\s*(%|[kmgt](?:i?b)?|b)?$/i;
+
+/**
+ * Resolve a disk size like "20G" or "80%" to bytes. Percentages are computed
+ * against the Docker data-root filesystem and require statfsImpl (node:fs
+ * statfs) plus the docker root path.
+ *
+ * @param {string|number} value
+ * @param {object} options { dockerRoot, statfsImpl } for percent resolution and tests
+ * @returns {Promise<number>}
+ */
+export async function resolveDiskSize(value, { dockerRoot, statfsImpl = statfs } = {}) {
+  const input = String(value ?? '').trim();
+  const match = input.match(DISK_SIZE_RE);
+  if (!match) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_DISK_SIZE', `Invalid disk size: ${input}`);
+  const amount = Number(match[1]);
+  const unit = (match[2] || 'b').toLowerCase();
+  if (unit === 'b') return Math.floor(amount);
+  if (unit === '%') {
+    if (!dockerRoot) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_DISK_SIZE', 'Percent disk size requires the Docker data-root');
+    const info = await statfsImpl(dockerRoot);
+    const totalBytes = Number(info.bsize) * Number(info.blocks);
+    return Math.floor(totalBytes * amount / 100);
+  }
+  const multipliers = { k: 1024, kb: 1024, kib: 1024, m: 1024 ** 2, mb: 1024 ** 2, mib: 1024 ** 2, g: 1024 ** 3, gb: 1024 ** 3, gib: 1024 ** 3, t: 1024 ** 4, tb: 1024 ** 4, tib: 1024 ** 4 };
+  const multiplier = multipliers[unit];
+  if (!multiplier) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_DISK_SIZE', `Invalid disk size: ${input}`);
+  return Math.floor(amount * multiplier);
+}

package/local-runtime/server/config.js

@@ -140,7 +140,11 @@ export const CONFIG = {
     enabled: process.env.SANDBOX_ENABLED === 'true',
     image: process.env.SANDBOX_AGENT_IMAGE || 'ghcr.io/yeaft/yeaft-web-code-agent-agent:dev',
     serverUrl: process.env.SANDBOX_SERVER_URL || '',
-    stateDir: process.env.SANDBOX_STATE_DIR || join(homedir(), '.yeaft', 'container-agents')
+    stateDir: process.env.SANDBOX_STATE_DIR || join(homedir(), '.yeaft', 'container-agents'),
+    // Shared cgroup slice (created by `yeaft-agent container setup-limits` on the
+    // Host) that caps the sum of all sandbox containers' CPU/memory usage. Empty
+    // means no cgroup-parent is passed and sandbox containers are unprotected.
+    cgroupParent: process.env.SANDBOX_CGROUP_PARENT || ''
   },
 
   // File upload settings