gpu_processes

Instructions

Implementation Reference

• server.js:173-241 (handler)

  async function gpuProcesses() — main handler for the gpu_processes tool. Calls rocm-smi --showpids --json, parses the JSON output, handles two possible shapes from different ROCm versions, extracts PID, process name, GPU count, VRAM bytes, SDMA bytes, and CU occupancy, and returns a list of running GPU compute processes.

  async function gpuProcesses() {
    const missing = requireRocmSmi();
    if (missing) return errorResult(missing);
  
    const r = await run(BIN.rocmSmi, ['--showpids', '--json']);
    // rocm-smi writes the JSON to stdout, and the "No JSON data to report"
    // warning to stderr. But some ROCm versions have been observed to swap
    // them, so try both streams before giving up.
    const data = parseRocmJson(r.stdout) || parseRocmJson(r.stderr);
  
    // Empty list = no KFD processes registered. Include raw stream snippets
    // in the note so the caller can tell "nothing is running" apart from
    // "rocm-smi returned an unexpected shape I couldn't parse".
    if (!data) {
      return textResult({
        timestamp: new Date().toISOString(),
        processes: [],
        note: 'No GPU compute processes currently running (or rocm-smi returned no parseable JSON).',
        diagnostic: {
          exit_code: r.code,
          stdout_snippet: (r.stdout || '').slice(0, 500),
          stderr_snippet: (r.stderr || '').slice(0, 500),
        },
      });
    }
  
    // rocm-smi --showpids --json emits one of two shapes depending on version:
    //   (a) {"system": {"PID19971": "python, 1, 1139888128, 0, unknown"}, ...}
    //   (b) {"system": {"19971": {"GPU use": "...", "VRAM": "...", ...}}, ...}
    // The CSV string in (a) is:
    //   "<process_name>, <gpu_count>, <vram_bytes>, <sdma_bytes>, <cu_occupancy>"
    const PID_KEY_RE = /^(?:PID)?(\d+)$/;
    const processes = [];
    for (const [k, v] of Object.entries(data)) {
      if (!v || typeof v !== 'object') continue;
      for (const [rawKey, info] of Object.entries(v)) {
        const m = rawKey.match(PID_KEY_RE);
        if (!m) continue;
        const pid = parseInt(m[1], 10);
        let entry;
        if (typeof info === 'string') {
          const parts = info.split(',').map((s) => s.trim());
          const [process_name, gpu_count, vram_bytes, sdma_bytes, cu_occupancy] = parts;
          entry = {
            pid,
            scope: k,
            process_name: process_name ?? null,
            gpu_count: gpu_count !== undefined ? parseInt(gpu_count, 10) : null,
            vram_bytes: vram_bytes !== undefined ? parseInt(vram_bytes, 10) : null,
            sdma_bytes: sdma_bytes !== undefined ? parseInt(sdma_bytes, 10) : null,
            cu_occupancy: cu_occupancy && cu_occupancy.toLowerCase() !== 'unknown'
              ? cu_occupancy
              : null,
          };
        } else if (info && typeof info === 'object') {
          entry = { pid, scope: k, ...info };
        } else {
          continue;
        }
        processes.push(entry);
      }
    }
  
    return textResult({
      timestamp: new Date().toISOString(),
      count: processes.length,
      processes,
    });
  }

• server.js:369-373 (registration)

  Tool registration entry in the TOOLS array: declares name 'gpu_processes', description, annotations (read-only), and empty inputSchema.

    name: 'gpu_processes',
    description: 'List compute processes using the GPU (KFD PIDs) with their VRAM usage and card index. Returns an empty list when no compute workloads are running.',
    annotations: { title: 'List GPU processes', readOnlyHint: true, destructiveHint: false, openWorldHint: false },
    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
  },

• server.js:398-398 (registration)

  Handler mapping in HANDLERS object: 'gpu_processes' -> gpuProcesses function, used by the JSON-RPC dispatch in handle().

  gpu_processes: gpuProcesses,